rea-agents 6.0.0 → 6.2.0

package/dist/domain/hopperValues.js

@@ -39,6 +39,34 @@ const segmentSchema = z.object({
 const unavailableAnalysisFactSchema = z
     .object({ available: z.literal(false), reason: z.string() })
     .strict();
+/** Typed string evidence shared by inventories and referenced function literals. */
+export const analysisStringSchema = z.object({
+    address: z.string(),
+    value: z.string(),
+    provider_value: z
+        .string()
+        .exactOptional()
+        .describe("Original provider display text, which may shorten the typed object."),
+    decoding: unavailableAnalysisFactSchema
+        .exactOptional()
+        .describe("When present, value retains native display text because typed bytes could not be decoded."),
+    string: z
+        .object({
+        encoding: z.string().min(1),
+        encoding_status: z
+            .enum(["observed", "inferred"])
+            .exactOptional()
+            .describe("Whether the provider declares the encoding or REA infers it from the typed bytes and native display. This does not establish the original source's intended encoding."),
+        termination: z.enum(["missing", "present_or_not_required"]),
+        byte_length: z.number().int().min(0),
+    })
+        .exactOptional(),
+});
+/** An analyzed bookmark retains a missing provider label as null. */
+export const analysisBookmarkSchema = z.strictObject({
+    address: z.string(),
+    name: z.string().nullable(),
+});
 /** Complete observed function-body ranges; every range endpoint is inclusive. */
 export const functionBodySchema = z.discriminatedUnion("available", [
     unavailableAnalysisFactSchema,
@@ -163,6 +191,13 @@ export const localVariableSchema = z
     .object({
     description: z.string(),
     provenance: z.string().min(1),
+    name: z.string().nullable().exactOptional(),
+    stack_displacement: z
+        .string()
+        .regex(/^-?\d+$/u)
+        .nullable()
+        .exactOptional()
+        .describe("Observed signed stack byte displacement, encoded as decimal to preserve precision."),
 })
     .strict();
 /** Provider-neutral complete raw-instruction list for one analyzed function. */
@@ -197,13 +232,26 @@ export const referenceKindSchema = z.discriminatedUnion("available", [
     unavailableAnalysisFactSchema,
     availableReferenceKindSchema,
 ]);
-const referenceEdgeSchema = z
+/** Reported call sites without resolved targets; unreported dispatch stays unknown. */
+export const unresolvedCallSchema = z.strictObject({
+    address: z.string(),
+    reason: z.string(),
+});
+/** Observed endpoints with complete or partial reference classification evidence. */
+export const referenceEdgeSchema = z
     .object({
     source_address: z.string(),
     target_address: z.string(),
     source_procedure: procedureIdentitySchema.nullable(),
     target_procedure: procedureIdentitySchema.nullable(),
     kind: referenceKindSchema,
+    call: z
+        .strictObject({
+        classification: z.enum(["none", "unknown", "direct", "objective_c"]),
+        provider_type: z.number().int(),
+        provenance: z.string().min(1),
+    })
+        .exactOptional(),
 })
     .strict();
 export const functionDossierSchema = z
@@ -225,13 +273,8 @@ export const functionDossierSchema = z
     callees: z.array(procedureIdentitySchema),
     incoming_references: z.array(referenceEdgeSchema),
     outgoing_references: z.array(referenceEdgeSchema),
-    referenced_strings: z.array(z
-        .object({
-        address: z.string(),
-        value: z.string(),
-        source_address: z.string(),
-    })
-        .strict()),
+    unresolved_calls: z.array(unresolvedCallSchema).exactOptional(),
+    referenced_strings: z.array(analysisStringSchema.extend({ source_address: z.string() })),
     referenced_names: z.array(z
         .object({
         address: z.string(),

package/dist/domain/immutableJson.js

@@ -0,0 +1,114 @@
+const immutableSnapshots = new WeakSet();
+/** Recognize an owned JSON snapshot sealed by this module, or an immutable scalar. */
+export const isImmutableJsonSnapshot = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value)) ||
+    (typeof value === "object" && immutableSnapshots.has(value));
+/** Seal an already parsed, owned JSON snapshot for immutable zero-copy reuse. */
+export const freezeJsonSnapshot = (value) => {
+    const pending = [{ value, exiting: false }];
+    // These sets exist only during traversal, while the owned root already
+    // retains every child. Strong sets avoid per-node ephemeron GC work.
+    const visited = new Set();
+    const ancestors = new Set();
+    const objects = [];
+    while (pending.length > 0) {
+        const entry = pending.pop();
+        if (entry === undefined)
+            break;
+        const item = entry.value;
+        if (entry.exiting && typeof item === "object" && item !== null) {
+            ancestors.delete(item);
+            visited.add(item);
+            objects.push(item);
+            continue;
+        }
+        if (isImmutableJsonSnapshot(item))
+            continue;
+        if (typeof item !== "object" || item === null)
+            throw new TypeError("Immutable JSON snapshots require JSON values");
+        if (ancestors.has(item))
+            throw new TypeError("Immutable JSON snapshots cannot contain circular references");
+        if (visited.has(item))
+            continue;
+        ancestors.add(item);
+        pending.push({ value: item, exiting: true });
+        pushSnapshotChildren(item, pending);
+    }
+    // Register only after every value is checked and every object is frozen.
+    // An arbitrary Object.freeze call cannot forge this snapshot identity.
+    for (const item of objects)
+        Object.freeze(item);
+    // Register the requested root, rather than retaining weak entries for every
+    // nested object. Sealing an Evidence or bundle skips previously sealed roots.
+    if (typeof value === "object" && value !== null)
+        immutableSnapshots.add(value);
+    return value;
+};
+/**
+ * Seal exclusively owned JSON in bounded steps, authenticating only completion.
+ * Abandonment or failure can leave the provisional input partly frozen.
+ */
+export function* freezeOwnedJsonSnapshotSteps(value) {
+    const pending = [{ value, exiting: false }];
+    const visited = new Set();
+    const ancestors = new Set();
+    let examined = 0;
+    try {
+        while (pending.length > 0) {
+            if (examined++ === 4096) {
+                examined = 0;
+                yield;
+            }
+            const entry = pending.pop();
+            if (entry === undefined)
+                break;
+            const item = entry.value;
+            if (entry.exiting && typeof item === "object" && item !== null) {
+                ancestors.delete(item);
+                visited.add(item);
+                continue;
+            }
+            if (isImmutableJsonSnapshot(item))
+                continue;
+            if (typeof item !== "object" || item === null)
+                throw new TypeError("Immutable JSON snapshots require JSON values");
+            if (ancestors.has(item))
+                throw new TypeError("Immutable JSON snapshots cannot contain circular references");
+            if (visited.has(item))
+                continue;
+            ancestors.add(item);
+            pending.push({ value: item, exiting: true });
+            pushSnapshotChildren(item, pending);
+            // Lock every inspected edge before the scheduler can release control.
+            Object.freeze(item);
+        }
+        if (typeof value === "object" && value !== null)
+            immutableSnapshots.add(value);
+        return value;
+    }
+    finally {
+        pending.length = 0;
+        visited.clear();
+        ancestors.clear();
+    }
+}
+const pushSnapshotChildren = (item, pending) => {
+    const prototype = Object.getPrototypeOf(item);
+    if (!Array.isArray(item) &&
+        prototype !== Object.prototype &&
+        prototype !== null)
+        throw new TypeError("Immutable JSON snapshots require ordinary objects");
+    if (Array.isArray(item))
+        for (let index = 0; index < item.length; index += 1)
+            if (!Object.hasOwn(item, index))
+                throw new TypeError("Immutable JSON snapshots cannot contain sparse arrays");
+    for (const key of Object.getOwnPropertyNames(item)) {
+        const descriptor = Object.getOwnPropertyDescriptor(item, key);
+        if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
+            throw new TypeError("Immutable JSON snapshots cannot contain accessors");
+        const child = descriptor.value;
+        pending.push({ value: child, exiting: false });
+    }
+};

package/dist/domain/inputIssueProjection.js

@@ -1,3 +1,6 @@
+import { AnalysisInputError, } from "./analysisErrorCore.js";
+/** Build the standard application input error while retaining schema causes and extra semantic issues. */
+export const analysisInputErrorFromIssues = (operation, issues, input, options = {}) => new AnalysisInputError(operation, options.cause === undefined ? undefined : { cause: options.cause }, [...projectInputIssues(issues, input), ...(options.additionalIssues ?? [])]);
 /** Project Zod failures to secret-safe caller correction metadata. */
 export const projectInputIssues = (issues, input) => issues.flatMap((issue) => projectIssue(issue, input));
 const projectIssue = (issue, input) => {

package/dist/domain/javascript/electronActiveObservation.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { isAbsoluteLocalPath } from "../localPath.js";
-const pathInputSchema = z.string().trim().min(1).refine(isAbsoluteLocalPath, {
+import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
+const pathInputSchema = localPathStringSchema.refine(isAbsoluteLocalPath, {
     message: "Electron executable, application, and root paths must be absolute local filesystem paths (for example /Applications/Electron.app/Contents/MacOS/Electron)",
 });
 const absolutePathSchema = z
@@ -60,60 +60,17 @@ export const electronActiveObservationInputSchema = z.strictObject({
     application_root: pathInputSchema
         .optional()
         .describe("Absolute local filesystem root for application-relative paths; omit to derive it from the application path. Relative paths are rejected."),
-    args: z.array(z.string()).default([]),
-    actions: z.array(actionSchema).default([]),
-});
-const ipcEventSchema = z.strictObject({
-    sequence: z.number().int().min(1),
-    correlation_id: z.string().nullable().default(null),
-    kind: z.enum([
-        "main-handler-invocation",
-        "main-event-invocation",
-        "utility-process-fork",
-        "utility-process-message",
-        "ipc-main-to-renderer",
-        "ipc-utility-to-main",
-        "ipc-renderer-send",
-        "ipc-renderer-invoke",
-        "ipc-renderer-post-message",
-    ]),
-    event: z.string().nullable().optional(),
-    phase: z
-        .enum(["attempted", "completed", "blocked", "failed", "observed"])
-        .nullable()
-        .optional(),
-    channel: z.string().nullable(),
-    direction: z
-        .enum([
-        "renderer-to-main",
-        "main-to-renderer",
-        "main-to-utility",
-        "utility-to-main",
-    ])
-        .nullable()
-        .optional(),
-    sender: z.string().nullable().optional(),
-    receiver: z.string().nullable().optional(),
-    frame: z.string().nullable().default(null),
-    target: z.string().nullable().optional(),
-    argument_shapes: z.array(z.string()),
-    result_shape: z.string().nullable(),
-    process_type: z.string().nullable(),
-    source: z.string().default("electron-active-hook"),
-    capture_method: z
-        .enum(["api-wrapper", "event-emitter", "process-hook"])
-        .default("api-wrapper"),
-    artifact_path: z.string().nullable().default(null),
-    artifact_sha256: z
+    args: z
+        .array(z
         .string()
-        .regex(/^[a-f0-9]{64}$/u)
-        .nullable()
-        .default(null),
-    error: z.boolean(),
+        .regex(/^[^\u0000]*$/u, "Electron arguments must not contain NUL"))
+        .default([]),
+    actions: z.array(actionSchema).default([]),
 });
-const timelineEventSchema = z.strictObject({
+/** Canonical active Electron event shared by the hook boundary and public timeline. */
+export const electronActiveTimelineEventSchema = z.strictObject({
     sequence: z.number().int().min(1),
-    correlation_id: z.string().nullable().default(null),
+    correlation_id: z.string().nullable(),
     kind: z.enum([
         "main-handler-invocation",
         "main-event-invocation",
@@ -166,6 +123,19 @@ const timelineEventSchema = z.strictObject({
         .nullable(),
     error: z.boolean(),
 });
+const ipcEventSchema = electronActiveTimelineEventSchema.extend({
+    kind: z.enum([
+        "main-handler-invocation",
+        "main-event-invocation",
+        "utility-process-fork",
+        "utility-process-message",
+        "ipc-main-to-renderer",
+        "ipc-utility-to-main",
+        "ipc-renderer-send",
+        "ipc-renderer-invoke",
+        "ipc-renderer-post-message",
+    ]),
+});
 const processMetricSchema = z.strictObject({
     pid: z.number().int().min(1),
     type: z.string().min(1),
@@ -235,19 +205,32 @@ export const electronActiveObservationResultSchema = z.strictObject({
     ipc: z.strictObject({
         events: z.array(ipcEventSchema),
         observed: z.number().int().min(0),
+        dropped: z.number().int().min(0),
     }),
-    timeline: z
-        .strictObject({
-        events: z.array(timelineEventSchema),
+    timeline: z.strictObject({
+        events: z.array(electronActiveTimelineEventSchema),
         observed: z.number().int().min(0),
-    })
-        .default({ events: [], observed: 0 }),
-    coverage: coverageSchema.default({
-        status: "partial_attach",
-        observed_event_families: [],
-        unavailable_event_families: [],
-        observed_roles: [],
-        pre_capture_activity: "unavailable",
+        dropped: z.number().int().min(0),
+    }),
+    retention: z.strictObject({
+        budget_bytes: z.number().int().min(0),
+        estimated_retained_bytes: z.number().int().min(0),
+        event_serialized_byte_upper_bound: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        dropped: z.number().int().min(0),
+        dropped_event_families: z.array(z.strictObject({
+            family: z.string().min(1),
+            count: z.number().int().min(1),
+        })),
+        dropped_event_roles: z.array(z.strictObject({
+            role: z.string().min(1),
+            count: z.number().int().min(1),
+        })),
+        observed_ipc: z.number().int().min(0),
+        dropped_ipc: z.number().int().min(0),
+        observed_runtime: z.number().int().min(0),
+        dropped_runtime: z.number().int().min(0),
     }),
+    coverage: coverageSchema,
     limitations: z.array(z.string()),
 });

package/dist/domain/javascript/electronObservation.js

@@ -80,9 +80,20 @@ export const electronPageInspectionSchema = z.object({
             script_key: prefixedDigestSchema("electron_script"),
             frame_id: z.string().nullable().default(null),
             file_path: z.string(),
-            cdp_hash: z.string(),
-            length: z.number().int().min(0),
-            is_module: z.boolean(),
+            cdp_hash: z
+                .string()
+                .nullable()
+                .describe("Producer-reported script hash; null when unavailable."),
+            length: z
+                .number()
+                .int()
+                .min(0)
+                .nullable()
+                .describe("Producer-reported script length; null when unavailable."),
+            is_module: z
+                .boolean()
+                .nullable()
+                .describe("Producer-reported module classification; null when unavailable."),
             language: z.string().nullable(),
             source: electronSourceSchema,
         })),

package/dist/domain/javascript/electronStaticAnalysisBrowser.js

@@ -54,10 +54,16 @@ const collectWindowOptions = (source, options) => {
 const collectWebPreferences = (source, object) => {
     const preferences = [];
     let unknown = 0;
-    let preload = {
-        preload_path: null,
-        preload_resolution_context: null,
-    };
+    const effectivePreload = objectProperty(object, "preload");
+    const preloadPath = effectivePreload.status === "explicit"
+        ? staticPath(effectivePreload.property.value)
+        : undefined;
+    const preload = effectivePreload.status === "explicit" && preloadPath !== undefined
+        ? {
+            preload_path: preloadPath,
+            preload_resolution_context: staticPathResolutionContext(effectivePreload.property.value),
+        }
+        : { preload_path: null, preload_resolution_context: null };
     for (const property of object.properties) {
         if (t.isSpreadElement(property)) {
             unknown += 1;
@@ -85,11 +91,6 @@ const collectWebPreferences = (source, object) => {
             continue;
         }
         const path = name === "preload" ? staticPath(property.value) : undefined;
-        if (path !== undefined)
-            preload = {
-                preload_path: path,
-                preload_resolution_context: staticPathResolutionContext(property.value),
-            };
         const value = path === undefined
             ? electronStaticValue(source, property.value)
             : { status: "literal", value: path, expression: null };

package/dist/domain/javascript/electronStaticAnalysisIpc.js

@@ -1,7 +1,8 @@
 import * as t from "@babel/types";
 import { boundedExpression, electronStaticValue, handlerKind, } from "./electronStaticAnalysisValues.js";
 import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
-import { argumentNode, calleeName, range, semanticStaticPropertyName, } from "./javascriptStaticAnalysisHelpers.js";
+import { argumentNode, calleeName, range, } from "./javascriptStaticAnalysisHelpers.js";
+import { semanticStaticPropertyName } from "./javascriptAstValues.js";
 /** Inspect Electron IPC operations and validation candidates. */
 export const inspectElectronIpcNode = (node, context) => {
     if (t.isCallExpression(node)) {

package/dist/domain/javascript/electronStaticAnalysisNative.js

@@ -2,7 +2,8 @@ import * as t from "@babel/types";
 import { compareCodePoints } from "../canonicalOrdering.js";
 import { stripQueryAndFragment } from "../artifactPathSyntax.js";
 import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
-import { argumentNode, calleeName, propertyName, range, semanticStaticPropertyName, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+import { argumentNode, calleeName, range, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+import { propertyName, semanticStaticPropertyName, } from "./javascriptAstValues.js";
 /** Inspect JavaScript-side imports and re-exports of native .node addons. */
 export const inspectElectronNativeNode = (node, context) => {
     if (t.isImportDeclaration(node))

package/dist/domain/javascript/electronStaticAnalysisValues.js

@@ -1,6 +1,6 @@
 import * as t from "@babel/types";
 import { compareCodePoints } from "../canonicalOrdering.js";
-import { semanticStaticPropertyName } from "./javascriptAstValues.js";
+import { readExactJavaScriptLiteral, semanticStaticPropertyName, } from "./javascriptAstValues.js";
 import { sourceSlice } from "./javascriptStaticAnalysisHelpers.js";
 /** Preserve one literal value or the exact inert expression. */
 export const electronStaticValue = (source, node) => {
@@ -101,17 +101,11 @@ const collectMembersAt = (object, prefix, depth, state) => {
     }
 };
 const literalValue = (node) => {
-    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isBooleanLiteral(node))
-        return { found: true, value: node.value };
-    if (t.isNullLiteral(node))
-        return { found: true, value: null };
-    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
-        return {
-            found: true,
-            value: node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? "",
-        };
+    if (node === null || node === undefined)
+        return { found: false };
+    const literal = readExactJavaScriptLiteral(node);
+    if (literal.found)
+        return literal;
     if (t.isUnaryExpression(node, { operator: "-" }) &&
         t.isNumericLiteral(node.argument))
         return { found: true, value: -node.argument.value };

package/dist/domain/javascript/javascriptApplicationAnalysis.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
-import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
-import { javaScriptSemanticGraphSchema } from "./javascriptSemanticGraph.js";
+import { javascriptApplicationGraphSchema, isValidatedImmutableJavaScriptApplicationGraph, } from "./javascriptApplicationGraph.js";
+import { javaScriptSemanticGraphSchema, isValidatedImmutableJavaScriptSemanticGraph, } from "./javascriptSemanticGraph.js";
 import { digestSchema } from "../digests.js";
 import { prefixedDigestSchema } from "../digests.js";
+import { localPathStringSchema } from "../localPath.js";
 const countSchema = z.number().int().min(0);
 /** Public target-free request for static JavaScript application analysis. */
 export const analyzeJavaScriptApplicationInputSchema = z.strictObject({
-    input_path: z.string().min(1),
+    input_path: localPathStringSchema,
     format: z.enum(["auto", "asar", "directory"]).default("auto"),
 });
 /** Compact counts for the high-level Electron architecture/security surface. */
@@ -45,9 +46,7 @@ const reconstructionStatisticsSchema = z.strictObject({
     parse_failures: countSchema,
     truncated_scopes: countSchema,
 });
-/** JavaScript application analysis with an authenticated semantic companion. */
-export const javascriptApplicationAnalysisResultSchema = z
-    .strictObject({
+const applicationAnalysisResultShape = z.strictObject({
     input_path: z.string().min(1),
     format: z.enum(["asar", "directory"]),
     root_artifact_sha256: digestSchema,
@@ -58,8 +57,8 @@ export const javascriptApplicationAnalysisResultSchema = z
     statistics: reconstructionStatisticsSchema,
     limitations: z.array(z.string().min(1)),
     semantic_graph: javaScriptSemanticGraphSchema,
-})
-    .superRefine((result, context) => {
+});
+function* checkApplicationBindingsSteps(result, context) {
     if (result.semantic_graph.application_graph_id !== result.graph.graph_id)
         context.addIssue({
             code: "custom",
@@ -72,19 +71,68 @@ export const javascriptApplicationAnalysisResultSchema = z
             path: ["semantic_graph", "root_artifact_sha256"],
             message: "Semantic graph must commit the containing root artifact",
         });
-    const applicationNodeIds = new Set(result.graph.nodes.map(({ node_id }) => node_id));
-    for (const [nodeIndex, node] of result.semantic_graph.nodes.entries())
-        for (const [identifierIndex, identifier,] of node.application_node_ids.entries())
-            if (!applicationNodeIds.has(identifier))
-                context.addIssue({
-                    code: "custom",
-                    path: [
-                        "semantic_graph",
-                        "nodes",
-                        nodeIndex,
-                        "application_node_ids",
-                        identifierIndex,
-                    ],
-                    message: "Semantic node references an absent application node",
-                });
+    const applicationNodeIds = new Set();
+    let examined = 0;
+    try {
+        for (const node of result.graph.nodes) {
+            applicationNodeIds.add(node.node_id);
+            if (++examined === 4096) {
+                examined = 0;
+                yield;
+            }
+        }
+        for (const [nodeIndex, node] of result.semantic_graph.nodes.entries()) {
+            if (++examined === 4096) {
+                examined = 0;
+                yield;
+            }
+            for (const [identifierIndex, identifier,] of node.application_node_ids.entries()) {
+                if (!applicationNodeIds.has(identifier))
+                    context.addIssue({
+                        code: "custom",
+                        path: [
+                            "semantic_graph",
+                            "nodes",
+                            nodeIndex,
+                            "application_node_ids",
+                            identifierIndex,
+                        ],
+                        message: "Semantic node references an absent application node",
+                    });
+                if (++examined === 4096) {
+                    examined = 0;
+                    yield;
+                }
+            }
+        }
+    }
+    finally {
+        applicationNodeIds.clear();
+    }
+}
+/** JavaScript application analysis with an authenticated semantic companion. */
+export const javascriptApplicationAnalysisResultSchema = applicationAnalysisResultShape.superRefine((result, context) => {
+    const steps = checkApplicationBindingsSteps(result, context);
+    while (!steps.next().done) {
+        // Public/imported results still receive complete synchronous validation.
+    }
+});
+const ownedAnalysisResultShape = applicationAnalysisResultShape.extend({
+    graph: z.custom(isValidatedImmutableJavaScriptApplicationGraph),
+    semantic_graph: z.custom(isValidatedImmutableJavaScriptSemanticGraph),
 });
+/** Reuse exact owned graphs while validating metadata and cross-graph bindings. */
+export function* parseOwnedJavaScriptApplicationAnalysisSteps(input) {
+    const prepared = ownedAnalysisResultShape.safeParse(input);
+    if (!prepared.success)
+        return javascriptApplicationAnalysisResultSchema.parse(input);
+    const issues = [];
+    yield* checkApplicationBindingsSteps(prepared.data, {
+        addIssue: (issue) => {
+            issues.push(issue);
+        },
+    });
+    if (issues.length > 0)
+        throw new z.ZodError(issues);
+    return prepared.data;
+}

package/dist/domain/javascript/javascriptApplicationEvidenceSchemas.js

@@ -347,6 +347,8 @@ export const applicationNodeIdentitySchema = z.discriminatedUnion("strategy", [
         source_map_sha256: digestSchema,
         // The exact `sources` entry; `""` is a legal relative reference.
         original_source: z.string(),
+        // Exact leaf-local root; null means omitted or explicitly null.
+        source_root: z.string().nullable(),
         source_sha256: digestSchema.nullable(),
     }),
     z.strictObject({