rea-agents 4.0.1 → 5.0.0

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

@@ -2,6 +2,8 @@ import canonicalize from "canonicalize";
 import { sha256, } from "./managedMemberComparisonMatch.js";
 const methodDimensions = (left, right) => {
     const dimensions = [];
+    if (left.flags !== right.flags || left.impl_flags !== right.impl_flags)
+        dimensions.push("metadata");
     if (left.signature.raw_sha256 !== right.signature.raw_sha256)
         dimensions.push("signature");
     const leftBodyComplete = left.body.status === "present" && left.body.truncated_instructions === 0;
@@ -54,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) {
@@ -176,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) => {
@@ -229,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);
@@ -65,8 +65,10 @@ export const collectNativeSymbols = (observations) => {
     }
     return { symbols, accepted, unsupported };
 };
-const normalizeSymbol = (value) => value.replace(/^_+/u, "");
-const sameSymbolName = (left, right) => normalizeSymbol(left) === normalizeSymbol(right);
+const sameSymbolName = (expected, native) => expected ===
+    (native.source === "macho-export" && native.name.startsWith("_")
+        ? native.name.slice(1)
+        : native.name);
 const normalizeModule = (value) => basename(value)
     .toLowerCase()
     .replace(/^lib/u, "")
@@ -96,7 +98,7 @@ const candidateNames = (managed) => {
 };
 const matchPinvoke = (managed, symbols, supportedNativeEvidence) => {
     const names = candidateNames(managed);
-    const allCandidates = symbols.filter((symbol) => names.some((name) => sameSymbolName(name, symbol.name)));
+    const allCandidates = symbols.filter((symbol) => names.some((name) => sameSymbolName(name, symbol)));
     const [first, ...remaining] = allCandidates;
     if (first === undefined)
         return {

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/{nativeDataType.js → native/nativeDataType.js}

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { nativeMetadataRecoverySchema } from "./nativeMetadataRecovery.js";
 /** Select a database type by exact category path or a defined typed data address. */
 export const nativeDataTypeInputSchema = z
     .strictObject({
@@ -48,4 +49,5 @@ export const nativeDataTypeSchema = z.strictObject({
     total_fields: z.number().int().nonnegative(),
     truncated: z.boolean(),
     limitations: z.array(z.string()),
+    metadata_recovery: nativeMetadataRecoverySchema.optional(),
 });

package/dist/domain/native/nativeFunctionAnnotations.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { functionDossierSchema } from "../hopperValues.js";
+/** One explicit function's analyst-authored metadata changes. */
+export const nativeFunctionAnnotationsInputSchema = z
+    .strictObject({
+    procedure: z.string().min(1),
+    name: z.string().min(1).optional(),
+    comment: z
+        .string()
+        .optional()
+        .describe("Regular entry comment; empty text clears it"),
+    inline_comment: z
+        .string()
+        .optional()
+        .describe("Inline entry comment; empty text clears it"),
+})
+    .refine((value) => value.name !== undefined ||
+    value.comment !== undefined ||
+    value.inline_comment !== undefined, "Supply at least one annotation change");
+/** Readback and refreshed analysis after one atomic metadata edit. */
+export const nativeFunctionAnnotationsSchema = z
+    .strictObject({
+    annotations: z.strictObject({
+        address: z.string().min(1),
+        name: z.string().min(1),
+        comment: z.string().nullable(),
+        inline_comment: z.string().nullable(),
+    }),
+    dossier: functionDossierSchema,
+    effects: z.strictObject({
+        scope: z.literal("session-analysis-database"),
+        source_bytes_modified: z.literal(false),
+        persists_after_close: z.literal(false),
+    }),
+})
+    .superRefine((value, context) => {
+    if (value.annotations.address !== value.dossier.procedure.address ||
+        value.annotations.name !== value.dossier.procedure.name)
+        context.addIssue({
+            code: "custom",
+            message: "Annotation readback disagrees with refreshed function identity",
+        });
+});

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/native/nativeLoadImage.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { nativeMetadataRecoverySummarySchema } from "./nativeMetadataRecovery.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);
+const address = z.string().min(1);
+/** Measured provider image, without exporting the complete executable bytes. */
+export const nativeLoadImageObservationSchema = z.strictObject({
+    metadata_recovery: z.array(nativeMetadataRecoverySummarySchema).optional(),
+    executable_format: z.string().min(1),
+    language_id: z.string().min(1),
+    compiler_spec_id: z.string().min(1),
+    image_base: address,
+    default_address_space: z.string().min(1),
+    source_files: z.array(z.strictObject({
+        name: z.string(),
+        size: integer,
+        original_sha256: digest,
+        modified_sha256: digest,
+    })),
+    mappings: z.array(z.strictObject({
+        block: z.string(),
+        start: address,
+        end: address,
+        address_space: z.string().min(1),
+        initialized: z.boolean(),
+        loaded: z.boolean(),
+        overlay: z.boolean(),
+        length: integer.min(1),
+        source_file_index: integer.nullable(),
+        file_offset: integer.nullable(),
+        sha256: digest.nullable(),
+    })),
+    relocations: z.array(z.strictObject({
+        address,
+        segment: integer.max(0xffff).nullable(),
+        offset: integer.max(0xffff).nullable(),
+        status: z.string().min(1),
+        type: z.number().int(),
+        values: z.array(z
+            .number()
+            .int()
+            .min(Number.MIN_SAFE_INTEGER)
+            .max(Number.MAX_SAFE_INTEGER)),
+        original_bytes_hex: hexBytes.nullable(),
+        memory_bytes_hex: hexBytes.nullable(),
+    })),
+    entry_points: z.array(address),
+    entry_context: z.array(z.strictObject({
+        address,
+        registers: z.array(z.strictObject({
+            name: z.string().min(1),
+            value_hex: z
+                .string()
+                .regex(/^0x[a-f0-9]+$/u)
+                .nullable(),
+        })),
+    })),
+});
+/** Independent comparison, preserving both expectations and measured values. */
+export const nativeLoadImageCheckSchema = z.strictObject({
+    name: z.string().min(1),
+    matched: z.boolean(),
+    expected: jsonValueSchema,
+    observed: jsonValueSchema,
+    file_offset: integer.nullable(),
+    address: address.nullable(),
+});
+/** Read-only native image verification; verified applies only to declared coverage. */
+export const nativeLoadImageSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("unsupported"),
+        reason: z.string().min(1),
+        observations: nativeLoadImageObservationSchema,
+        limitations: z.array(z.string().min(1)),
+    }),
+    z.strictObject({
+        status: z.enum(["verified", "mismatch"]),
+        format: z.enum(["dos-mz", "dos-com"]),
+        target_sha256: digest,
+        load_segment: integer.max(0xffff),
+        header_bytes: integer,
+        module_bytes: integer,
+        overlay_bytes: integer,
+        entry: z.strictObject({
+            relative_segment: integer.max(0xffff),
+            offset: integer.max(0xffff),
+            linear_address: address,
+        }),
+        observations: nativeLoadImageObservationSchema,
+        checks: z.array(nativeLoadImageCheckSchema),
+        limitations: z.array(z.string().min(1)),
+    }),
+]);

package/dist/domain/native/nativeMetadataRecovery.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const address = z.string().regex(/^0x[0-9a-f]+$/u);
+const relatedType = z.strictObject({ address, type: z.string().nullable() });
+/** Runtime-format metadata recovered in an analysis image, with explicit inference boundaries. */
+export const nativeMetadataRecoverySchema = z.strictObject({
+    format: z.literal("dotnet-nativeaot"),
+    status: z.enum(["complete", "partial"]),
+    header_address: address,
+    format_major: z.number().int().nonnegative(),
+    format_minor: z.number().int().nonnegative(),
+    method_table_address: address,
+    name_origin: z.enum(["generated", "inferred"]),
+    original_name: z.null(),
+    base_size_bytes: z.number().int().nonnegative(),
+    related_type: relatedType.nullable(),
+    interfaces: z.array(relatedType),
+    virtual_slots: z.array(z.strictObject({
+        slot: z.number().int().nonnegative(),
+        slot_address: address,
+        target_address: address.nullable(),
+        procedure_name: z.string().nullable(),
+        basis: z.literal("method-table-pointer"),
+    })),
+    derived_memory: z.strictObject({
+        address,
+        size_bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        file_offset: z.null(),
+    }),
+    diagnostics: z.array(z.string()),
+    limitations: z.array(z.string()),
+});
+/** Discover a recovered runtime format and reusable type identities from the loaded image. */
+export const nativeMetadataRecoverySummarySchema = z.strictObject({
+    format: z.literal("dotnet-nativeaot"),
+    status: z.enum(["complete", "partial", "not_applicable"]),
+    reason: z.string().nullable(),
+    analysis_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    header_address: address.nullable(),
+    discovery: z.enum(["symbol", "signature-heuristic"]).nullable(),
+    format_major: z.number().int().nonnegative().nullable(),
+    format_minor: z.number().int().nonnegative().nullable(),
+    method_tables: z.number().int().nonnegative(),
+    types: z.array(relatedType),
+    derived_memory: nativeMetadataRecoverySchema.shape.derived_memory.nullable(),
+    coverage: z
+        .strictObject({
+        frozen_object_candidates: z.number().int().nonnegative(),
+        frozen_objects_annotated: z.number().int().nonnegative(),
+        basis: z.literal("rehydrated-pointer-candidates-and-committed-instance-types"),
+    })
+        .nullable(),
+    diagnostics: z.array(z.string()),
+    limitations: z.array(z.string()),
+});

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(),