rea-agents 4.1.0 → 5.0.0

package/dist/domain/{sourceToBundleComparisonSchemas.js → javascript/sourceToBundleComparisonSchemas.js}

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { evidenceSchema } from "./evidence.js";
+import { evidenceSchema } from "../evidence.js";
 import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "./javascriptApplicationGraphSchemas.js";
-import { historicalSourceGraphSchema } from "./referenceSourceGraph.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { historicalSourceGraphSchema } from "../referenceSourceGraph.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const nodeIdSchema = prefixedDigestSchema("jag_node");
 const textSchema = z.string().min(1);

package/dist/domain/{sourceToBundleSignals.js → javascript/sourceToBundleSignals.js}

@@ -1,7 +1,7 @@
 import { posix } from "node:path";
-import { compareCodePoints } from "./canonicalOrdering.js";
+import { compareCodePoints } from "../canonicalOrdering.js";
 import { SOURCE_TO_BUNDLE_SIGNAL_WEIGHTS, } from "./sourceToBundleComparisonSchemas.js";
-import { isDigest } from "./digests.js";
+import { isDigest } from "../digests.js";
 const RELEVANT_NODE_KINDS = new Set([
     "javascript-asset",
     "javascript-module",

package/dist/domain/{managedApplicationGraph.js → managed/managedApplicationGraph.js}

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
-import { evidenceSchema, parseEvidence } from "./evidence.js";
-import { createJavaScriptApplicationGraph, javascriptApplicationGraphSchema, } from "./javascriptApplicationGraph.js";
+import { evidenceSchema, parseEvidence } from "../evidence.js";
+import { createJavaScriptApplicationGraph, javascriptApplicationGraphSchema, } from "../javascript/javascriptApplicationGraph.js";
 import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "./managedArtifact.js";
 import { assessManagedGraphOmissions, managedGraphEvidenceCoverage, managedGraphResultCoverage, } from "./managedApplicationGraphCoverage.js";
 import { addArtifactNode, addArtifactIdentityNodes, addBoundaryNodes, addMemberNodes, } from "./managedApplicationGraphNodes.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const textSchema = z.string().min(1);
 /** Authenticated managed Evidence records projected into the application graph. */

package/dist/domain/{managedApplicationGraphNodes.js → managed/managedApplicationGraphNodes.js}

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { createJavaScriptApplicationEdge, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+import { createJavaScriptApplicationEdge, createJavaScriptApplicationNode, } from "../javascript/javascriptApplicationGraph.js";
 import { managedSourceCoverage } from "./managedApplicationGraphCoverage.js";
 import {} from "./managedArtifact.js";
 import { moduleCoverageState } from "./managedApplicationGraphNodeCoverage.js";

package/dist/domain/{managedArtifact.js → managed/managedArtifact.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { digestSchema } from "./../domain/digests.js";
+import { digestSchema } from "../digests.js";
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
 const offsetSchema = z.number().int().min(0);
 /** A 16-byte CLI metadata GUID without RFC 4122 version/variant restrictions. */

package/dist/domain/{managedMemberComparison.js → managed/managedMemberComparison.js}

@@ -1,12 +1,12 @@
 import { z } from "zod";
-import { emptyArraySchema } from "./emptyArraySchema.js";
-import { evidenceSchema } from "./evidence.js";
+import { emptyArraySchema } from "../emptyArraySchema.js";
+import { evidenceSchema } from "../evidence.js";
 import { cliMetadataGuidSchema, } from "./managedArtifact.js";
 import { buildComparisonCoverage, buildComparisonMatching, buildComparisonSummary, comparisonLimitations, sideManifest, } from "./managedMemberComparisonCoverage.js";
 import { buildFieldItems, buildMethodItems, } from "./managedMemberComparisonItems.js";
 import { keyMembers, sha256 } from "./managedMemberComparisonMatch.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
 const boundedTextSchema = z.string().min(1);

package/dist/domain/{managedMemberComparisonCoverage.js → managed/managedMemberComparisonCoverage.js}

@@ -33,7 +33,7 @@ export const buildComparisonSummary = (items) => ({
 });
 export const buildComparisonMatching = (methodItems, fieldItems) => ({
     exact_il_signature: methodItems.filter(({ match }) => match.basis === "exact-il-signature").length,
-    exact_signature: methodItems.filter(({ match }) => match.basis === "exact-signature").length,
+    exact_signature: [...methodItems, ...fieldItems].filter(({ match }) => match.basis === "exact-signature").length,
     structural_method_shape: methodItems.filter(({ match }) => match.basis === "structural-method-shape").length,
     field_signature: fieldItems.filter(({ match }) => match.basis === "field-signature").length,
     ambiguous: methodItems.filter(({ match }) => match.status === "ambiguous").length +
@@ -44,6 +44,7 @@ export const comparisonLimitations = (left, right) => {
     const limitations = [
         "Metadata tokens are build-local coordinates; matched pairs are remaps, not persistent identities.",
         "Methods pair by exact CIL/signature, then declared type, name, and signature, then structural shape; names alone are never a matching basis.",
+        "Fields pair by exact signature, then declared type, name, and signature; an undecoded signature is compared only by its raw bytes, and an unmatched member with one stays unknown.",
     ];
     if (left.coverage.state !== "complete" || right.coverage.state !== "complete")
         limitations.push("At least one managed member observation is partial.");

package/dist/domain/{managedMemberComparisonItems.js → managed/managedMemberComparisonItems.js}

@@ -56,72 +56,131 @@ const unmatchedComparison = () => ({
     candidate_left_tokens: [],
     candidate_right_tokens: [],
 });
-const methodOnlyItem = (member, context) => {
+const methodOnlyItem = (member, context, undecoded) => {
     if (member.left !== undefined) {
-        const absenceObserved = context.rightComplete;
+        const limitations = absenceLimitations(member.left, {
+            oppositeComplete: context.rightComplete,
+            oppositeUndecodedNames: undecoded.right,
+            opposite: "right",
+            inventory: "method",
+        });
         return {
             item_id: `mmc_method_${sha256({ token: member.left.token, side: "left" })}`,
-            status: absenceObserved ? "removed" : "unknown",
+            status: limitations.length === 0 ? "removed" : "unknown",
             left: methodIdentity(member.left),
             right: null,
             match: unmatchedComparison(),
             dimensions: ["availability"],
             evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-            limitations: absenceObserved
-                ? []
-                : [
-                    "unknown-within-incomplete-metadata: The right method inventory is incomplete, so absence was not observed.",
-                ],
+            limitations,
         };
     }
-    const absenceObserved = context.leftComplete;
+    const limitations = absenceLimitations(member.right, {
+        oppositeComplete: context.leftComplete,
+        oppositeUndecodedNames: undecoded.left,
+        opposite: "left",
+        inventory: "method",
+    });
     return {
         item_id: `mmc_method_${sha256({ token: member.right.token, side: "right" })}`,
-        status: absenceObserved ? "added" : "unknown",
+        status: limitations.length === 0 ? "added" : "unknown",
         left: null,
         right: methodIdentity(member.right),
         match: unmatchedComparison(),
         dimensions: ["availability"],
         evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-        limitations: absenceObserved
-            ? []
-            : [
-                "unknown-within-incomplete-metadata: The left method inventory is incomplete, so absence was not observed.",
-            ],
+        limitations,
     };
 };
-const fieldOnlyItem = (member, context) => {
+/**
+ * Why a one-sided member's absence from the other inventory was not
+ * observed: that inventory is incomplete, the member's own signature was not
+ * decoded, so no shape round could seek a changed counterpart, or the other
+ * inventory has an unpaired (one-sided or ambiguous) same-named member whose
+ * signature was not decoded, which may be this member with a changed
+ * signature.
+ */
+const absenceLimitations = (member, opposite) => [
+    ...(opposite.oppositeComplete
+        ? []
+        : [
+            `unknown-within-incomplete-metadata: The ${opposite.opposite} ${opposite.inventory} inventory is incomplete, so absence was not observed.`,
+        ]),
+    ...(member.signature.parse_status === "decoded"
+        ? []
+        : [
+            `signature-not-decoded: The member's ${member.signature.parse_status} signature was compared only by exact declared type, name, and raw bytes, so a changed or renamed counterpart could not be sought.`,
+        ]),
+    ...(member.signature.parse_status === "decoded" &&
+        opposite.oppositeUndecodedNames.has(declaredName(member))
+        ? [
+            `counterpart-signature-not-decoded: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature was not decoded, so it may be this member with a changed signature.`,
+        ]
+        : []),
+];
+const declaredName = (member) => JSON.stringify([member.declaring_type, member.name]);
+/**
+ * Declared names of unpaired members whose signature was not decoded: one-sided
+ * members and candidates of ambiguous groups, which also remain unpaired.
+ */
+const undecodedOneSidedNames = (members) => {
+    const names = (side) => new Set(side
+        .filter(({ item }) => item.signature.parse_status !== "decoded")
+        .map(({ item }) => declaredName(item)));
+    return {
+        left: names([
+            ...members.leftOnly,
+            ...members.ambiguous.flatMap(({ left }) => left),
+        ]),
+        right: names([
+            ...members.rightOnly,
+            ...members.ambiguous.flatMap(({ right }) => right),
+        ]),
+    };
+};
+const fieldOnlyItem = (member, context, undecoded) => {
     if (member.left !== undefined) {
-        const absenceObserved = context.rightComplete;
+        const limitations = absenceLimitations(member.left, {
+            oppositeComplete: context.rightComplete,
+            oppositeUndecodedNames: undecoded.right,
+            opposite: "right",
+            inventory: "field",
+        });
         return {
             item_id: `mmc_field_${sha256({ token: member.left.token, side: "left" })}`,
-            status: absenceObserved ? "removed" : "unknown",
+            status: limitations.length === 0 ? "removed" : "unknown",
             left: fieldIdentity(member.left),
             right: null,
             match: unmatchedComparison(),
             evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-            limitations: absenceObserved
-                ? []
-                : [
-                    "unknown-within-incomplete-metadata: The right field inventory is incomplete, so absence was not observed.",
-                ],
+            limitations,
         };
     }
-    const absenceObserved = context.leftComplete;
+    const limitations = absenceLimitations(member.right, {
+        oppositeComplete: context.leftComplete,
+        oppositeUndecodedNames: undecoded.left,
+        opposite: "left",
+        inventory: "field",
+    });
     return {
         item_id: `mmc_field_${sha256({ token: member.right.token, side: "right" })}`,
-        status: absenceObserved ? "added" : "unknown",
+        status: limitations.length === 0 ? "added" : "unknown",
         left: null,
         right: fieldIdentity(member.right),
         match: unmatchedComparison(),
         evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-        limitations: absenceObserved
-            ? []
-            : [
-                "unknown-within-incomplete-metadata: The left field inventory is incomplete, so absence was not observed.",
-            ],
+        limitations,
     };
 };
+/**
+ * Name the identity key an ambiguous group shares. The exact-signature key
+ * already includes the declared type and name, so names cannot separate it.
+ */
+const ambiguityLimitation = (members, basis) => basis === "exact-signature"
+    ? `Multiple managed ${members} share the same declared type, name, and raw signature; REA did not guess a token remap.`
+    : members === "methods"
+        ? "Multiple managed methods share the same non-name identity key; REA did not guess a token remap."
+        : "Multiple managed fields share the same signature; REA did not guess a token remap from names.";
 export const buildMethodItems = (matches, context) => {
     const items = [];
     for (const pair of matches.pairs) {
@@ -178,15 +237,14 @@ export const buildMethodItems = (matches, context) => {
             },
             dimensions: ["availability"],
             evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-            limitations: [
-                "Multiple managed methods share the same non-name identity key; REA did not guess a token remap.",
-            ],
+            limitations: [ambiguityLimitation("methods", ambiguous.basis)],
         });
     }
+    const undecoded = undecodedOneSidedNames(matches);
     for (const item of matches.leftOnly)
-        items.push(methodOnlyItem({ left: item.item }, context));
+        items.push(methodOnlyItem({ left: item.item }, context, undecoded));
     for (const item of matches.rightOnly)
-        items.push(methodOnlyItem({ right: item.item }, context));
+        items.push(methodOnlyItem({ right: item.item }, context, undecoded));
     return items;
 };
 export const buildFieldItems = (matches, context) => {
@@ -231,13 +289,12 @@ export const buildFieldItems = (matches, context) => {
                 candidate_right_tokens: ambiguous.right.map(({ item }) => item.token),
             },
             evidence_links: [context.leftEvidenceId, context.rightEvidenceId],
-            limitations: [
-                "Multiple managed fields share the same signature; REA did not guess a token remap from names.",
-            ],
+            limitations: [ambiguityLimitation("fields", ambiguous.basis)],
         });
+    const undecoded = undecodedOneSidedNames(matches);
     for (const item of matches.leftOnly)
-        items.push(fieldOnlyItem({ left: item.item }, context));
+        items.push(fieldOnlyItem({ left: item.item }, context, undecoded));
     for (const item of matches.rightOnly)
-        items.push(fieldOnlyItem({ right: item.item }, context));
+        items.push(fieldOnlyItem({ right: item.item }, context, undecoded));
     return items;
 };

package/dist/domain/{managedMemberComparisonMatch.js → managed/managedMemberComparisonMatch.js}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
-import { parseEvidence } from "./evidence.js";
+import { parseEvidence } from "../evidence.js";
 import { managedMemberInspectionSchema, } from "./managedArtifact.js";
 export const sha256 = (value) => {
     const serialized = canonicalize(value);
@@ -19,14 +19,13 @@ const keyMethod = (item) => ({
             item.body.normalized_il_sha256,
         ])
         : null,
-    signatureKey: item.signature.parse_status === "decoded"
-        ? stableKey([
-            "method-signature",
-            item.declaring_type,
-            item.name,
-            item.signature.raw_sha256,
-        ])
-        : null,
+    // The raw blob is the exact signature; decoding only feeds shape keys.
+    signatureKey: stableKey([
+        "method-signature",
+        item.declaring_type,
+        item.name,
+        item.signature.raw_sha256,
+    ]),
     structuralKey: item.signature.parse_status === "decoded" && item.body.status === "present"
         ? stableKey([
             "method-structural",
@@ -61,7 +60,14 @@ const keyField = (item) => ({
     exactKey: item.signature.parse_status === "decoded"
         ? stableKey(["field-exact", item.signature.raw_sha256])
         : null,
-    signatureKey: null,
+    // Only an undecoded field reaches this round: a decoded field with the
+    // same raw signature already met its counterpart in the exact round.
+    signatureKey: stableKey([
+        "field-signature",
+        item.declaring_type,
+        item.name,
+        item.signature.raw_sha256,
+    ]),
     structuralKey: stableKey([
         "field-structural",
         item.signature.kind,
@@ -89,7 +95,12 @@ const matchFields = (left, right) => matchByKeys({
     left,
     right,
     exactBasis: "field-signature",
-    fallbackBases: [],
+    fallbackBases: [
+        {
+            basis: "exact-signature",
+            key: ({ signatureKey }) => signatureKey,
+        },
+    ],
 });
 const matchByKeys = ({ left, right, exactBasis, fallbackBases, }) => {
     const usedLeft = new Set();

package/dist/domain/{managedNativeVerification.js → managed/managedNativeVerification.js}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
-import { parseEvidence } from "./evidence.js";
+import { parseEvidence } from "../evidence.js";
 import { managedNativeBoundaryInspectionSchema, } from "./managedArtifact.js";
 import { managedNativeVerificationResultSchema, } from "./managedNativeVerificationSchemas.js";
 import { buildVerificationResult, collectNativeSymbols, verifyPinvoke, } from "./managedNativeVerificationMatch.js";

package/dist/domain/{managedNativeVerificationMatch.js → managed/managedNativeVerificationMatch.js}

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import canonicalize from "canonicalize";
-import { parseEvidence } from "./evidence.js";
-import { functionDossierSchema } from "./hopperValues.js";
-import { inspectMachoSchema } from "./nativeInspection.js";
+import { parseEvidence } from "../evidence.js";
+import { functionDossierSchema } from "../hopperValues.js";
+import { inspectMachoSchema } from "../native/nativeInspection.js";
 import { pinvokeVerificationSchema, } from "./managedNativeVerificationSchemas.js";
 const digest = (value) => {
     const serialized = canonicalize(value);

package/dist/domain/{managedNativeVerificationSchemas.js → managed/managedNativeVerificationSchemas.js}

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { emptyArraySchema } from "./emptyArraySchema.js";
-import { evidenceSchema } from "./evidence.js";
+import { emptyArraySchema } from "../emptyArraySchema.js";
+import { evidenceSchema } from "../evidence.js";
 import { cliMetadataGuidSchema } from "./managedArtifact.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
 const textSchema = z.string().min(1);
@@ -176,4 +176,5 @@ export const managedNativeVerificationResultSchema = z
             path: ["summary", "native_body_unresolved"],
             message: "Native body summary must match unresolved implementations",
         });
-});
+})
+    .describe("Counts must agree across the result: native accepted plus unsupported equals total; each P/Invoke summary count equals the number of items with that status; and native_body_unresolved equals native_implementations.unresolved. REA checks these cross-field invariants after constructing the result.");

package/dist/domain/{managedReconstruction.js → managed/managedReconstruction.js}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
-import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { evidenceSchema, parseEvidence } from "../evidence.js";
 import { cliMetadataGuidSchema, managedMemberInspectionSchema, } from "./managedArtifact.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
 const textSchema = z.string().min(1);

package/dist/domain/{nativeFunctionAnnotations.js → native/nativeFunctionAnnotations.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { functionDossierSchema } from "./hopperValues.js";
+import { functionDossierSchema } from "../hopperValues.js";
 /** One explicit function's analyst-authored metadata changes. */
 export const nativeFunctionAnnotationsInputSchema = z
     .strictObject({

package/dist/domain/{nativeInspection.js → native/nativeInspection.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 const hexAddress = z.string().regex(/^0x[a-fA-F0-9]+$/u);
 const coverage = (item) => z.object({
     items: z.array(item),

package/dist/domain/{nativeInvestigationGraph.js → native/nativeInvestigationGraph.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { nativeMetadataEvidenceSchema, nativeMetadataLocationSchema, } from "./objcSwiftMetadata.js";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 /** Entity kinds shared by decoded Interface Builder archives and native code. */
 export const nativeInvestigationNodeKindSchema = z.enum([
     "storyboard",
@@ -154,14 +154,23 @@ export const traceNativeInvestigationGraph = (graph, input) => {
     let reachedDepth = 0;
     let truncated = false;
     let reason = null;
+    const adjacency = new Map();
+    for (const edge of graph.edges) {
+        const nodeId = direction === "forward" ? edge.from : edge.to;
+        if (nodeId === null)
+            continue;
+        const entries = adjacency.get(nodeId);
+        if (entries === undefined)
+            adjacency.set(nodeId, [edge]);
+        else
+            entries.push(edge);
+    }
     while (queue.length > 0) {
         const current = queue.shift();
         if (current === undefined)
             break;
         reachedDepth = Math.max(reachedDepth, current.depth);
-        const adjacent = graph.edges.filter((edge) => direction === "forward"
-            ? edge.from === current.id
-            : edge.to === current.id);
+        const adjacent = adjacency.get(current.id) ?? [];
         for (const edge of adjacent) {
             if (selectedEdges.size + unresolved.size >= limits.max_edges) {
                 truncated = true;

package/dist/domain/{nativeLoadImage.js → native/nativeLoadImage.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { nativeMetadataRecoverySummarySchema } from "./nativeMetadataRecovery.js";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 const integer = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
 const digest = z.string().regex(/^[a-f0-9]{64}$/u);
 const hexBytes = z.string().regex(/^(?:[a-f0-9]{2})*$/u);

package/dist/domain/{nativeUiObservation.js → native/nativeUiObservation.js}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import { decodeCanonicalBase64 } from "./webScreenshot.js";
+import { decodeCanonicalBase64 } from "../webScreenshot.js";
 const scope = {
     pid: z.number().int().positive(),
     window_id: z.number().int().positive(),
@@ -51,10 +51,24 @@ export const nativeUiScenarioInputSchema = z.strictObject({
 const nativeUiScreenshotSchema = z
     .strictObject({
     mime_type: z.literal("image/png"),
-    base64: z.string().min(4),
-    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-    width: z.number().int().positive(),
-    height: z.number().int().positive(),
+    base64: z
+        .string()
+        .min(4)
+        .describe("Canonical base64 encoding of PNG bytes; the decoded bytes must have a PNG signature and IHDR chunk."),
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .describe("SHA-256 digest of the decoded PNG bytes."),
+    width: z
+        .number()
+        .int()
+        .positive()
+        .describe("Must equal the width encoded in the PNG IHDR chunk."),
+    height: z
+        .number()
+        .int()
+        .positive()
+        .describe("Must equal the height encoded in the PNG IHDR chunk."),
 })
     .superRefine((screenshot, context) => {
     const bytes = decodeCanonicalBase64(screenshot.base64);
@@ -101,7 +115,7 @@ export const nativeUiSnapshotSchema = z.strictObject({
         title: z.string().nullable(),
         value: z.string().nullable(),
         actions: z.array(z.string()),
-        children_count: z.number().int().nonnegative(),
+        children_count: z.number().int().nonnegative().nullable(),
     })),
     truncated: z.boolean(),
     screenshot: nativeUiScreenshotSchema.nullable(),

package/dist/domain/{objcSwiftMetadata.js → native/objcSwiftMetadata.js}

@@ -133,6 +133,22 @@ export const objcDispatchImplementationSchema = z.strictObject({
     selector: z.string().min(1),
     method_type: z.enum(["instance", "class"]),
     implementation_address: z.string().nullable(),
+    /** Category that adds this method, when it is not defined by the class itself. */
+    category: z.string().nullable().optional(),
+    location: nativeMetadataLocationSchema,
+    decode: nativeMetadataDecodeSchema,
+    evidence: z.array(nativeMetadataEvidenceSchema).min(1),
+});
+/** Objective-C category: methods, protocols and properties added to a class. */
+export const objcCategorySchema = z.strictObject({
+    name: z.string().min(1),
+    /** Extended class; external classes come from the category's bind symbol. */
+    class_name: z.string().min(1).nullable(),
+    class_source: z.enum(["local", "external", "unresolved"]),
+    instance_methods: z.array(z.string()),
+    class_methods: z.array(z.string()),
+    protocols: z.array(z.string()),
+    properties: z.array(objcPropertySchema),
     location: nativeMetadataLocationSchema,
     decode: nativeMetadataDecodeSchema,
     evidence: z.array(nativeMetadataEvidenceSchema).min(1),
@@ -240,6 +256,7 @@ export const dbSaveResultSchema = z.strictObject({
 export const objcSwiftMetadataSchema = z.strictObject({
     objc_classes: z.array(objcClassSchema).default([]),
     objc_protocols: z.array(objcProtocolSchema).default([]),
+    objc_categories: z.array(objcCategorySchema).default([]),
     swift_decls: z.array(swiftDeclSchema).default([]),
     objc_ivars: z.array(objcIvarSchema).default([]),
     objc_protocol_records: z.array(objcProtocolRecordSchema).default([]),

package/dist/domain/processCapture.js

@@ -165,13 +165,15 @@ const processCaptureShapeSchema = z.strictObject({
     }),
 });
 /** Exact serialized shape plus all process-capture semantic invariants. */
-export const processCaptureSchema = processCaptureShapeSchema.superRefine((capture, context) => {
+export const processCaptureSchema = processCaptureShapeSchema
+    .superRefine((capture, context) => {
     for (const issue of collectProcessCaptureIssues(capture))
         context.addIssue({
             code: "custom",
             path: issue.path.split("."),
             message: issue.message,
         });
-});
+})
+    .describe("The capture must preserve its canonical scenario, comparison, and normalization SHA-256 commitments; ordered capture timestamps and contiguous sequence numbers; before and final filesystem snapshots with truncation propagated; and exit-code consistency with deadline termination. When parsing older input without an event journal, REA supplies an empty journal; empty journals are valid. A non-empty journal must reference every captured observation exactly once with unique in-range references. These cross-field invariants are checked by REA after capture.");
 export { parseProcessCapture } from "./processCaptureParsing.js";
 export { compareProcessCaptures, comparisonStatusSchema, deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./processComparison.js";

package/dist/domain/processScenario.js

@@ -3,10 +3,18 @@ import canonicalize from "canonicalize";
 import { z } from "zod";
 const positiveBudget = z.number().int().safe().positive();
 const timedEventBase = { at_ms: z.number().int().safe().nonnegative() };
+const reservedRunIdEnvironmentName = "REA_PROCESS_RUN_ID";
 const environmentName = z
     .string()
-    .regex(/^[^=\0]+$/u, "Environment names cannot contain '=' or NUL");
-const reservedEnvironment = new Set(["REA_PROCESS_RUN_ID"]);
+    .min(1, "Environment names must not be empty")
+    .regex(/^(?!REA_PROCESS_RUN_ID(?![\s\S]))[^=\0]+$/u, {
+    error: (issue) => issue.input === reservedRunIdEnvironmentName
+        ? `${reservedRunIdEnvironmentName} is reserved by the process adapter`
+        : "Environment names cannot contain '=' or NUL",
+});
+const childProcessString = z
+    .string()
+    .regex(/^[^\0]*$/u, "Values passed to operating-system APIs cannot contain NUL");
 export const normalizationSchema = z.object({
     paths: z.boolean(),
     pids: z.boolean(),
@@ -61,11 +69,13 @@ export const processComparisonContract = (scenario) => ({
  */
 export const processScenarioSchema = z
     .object({
-    executable: z.string().min(1),
-    arguments: z.array(z.string()).default([]),
-    working_directory: z.string().default("."),
-    environment: z.record(environmentName, z.string()).default({}),
-    filesystem_observation_paths: z.array(z.string().min(1)).default([]),
+    executable: childProcessString.min(1),
+    arguments: z.array(childProcessString).default([]),
+    working_directory: childProcessString.default("."),
+    environment: z.record(environmentName, childProcessString).default({}),
+    filesystem_observation_paths: z
+        .array(childProcessString.min(1))
+        .default([]),
     terminal: z
         .object({
         columns: z.number().int().min(1).max(65_535).default(80),
@@ -147,16 +157,6 @@ export const processScenarioSchema = z
             });
         }
     }
-    const explicit = new Set(Object.keys(scenario.environment));
-    for (const name of explicit) {
-        if (reservedEnvironment.has(name)) {
-            context.addIssue({
-                code: "custom",
-                message: `${name} is reserved by the process adapter`,
-                path: ["environment", name],
-            });
-        }
-    }
     for (const event of scenario.events) {
         if (event.at_ms > scenario.timeout_ms) {
             context.addIssue({