rea-agents 6.4.0 → 6.7.0

package/dist/domain/functionCallCoverage.js

@@ -0,0 +1,60 @@
+import { relationshipCoverageLimitations, } from "./relationshipCoverage.js";
+import { uniqueSorted } from "./canonicalOrdering.js";
+const callerCoveragePrefix = "Callers: ";
+const calleeCoveragePrefix = "Callees: ";
+/** Combine caller and callee read outcomes without losing either explanation. */
+export const combineFunctionRelationshipCoverage = (callers, callees) => {
+    const reads = [
+        { direction: "callers", coverage: callers },
+        { direction: "callees", coverage: callees },
+    ];
+    const diagnostics = uniqueSorted(reads.flatMap(({ coverage }) => coverage?.diagnostics ?? []));
+    const details = diagnostics.length > 0 ? { diagnostics } : {};
+    const callersLimited = callers?.status !== "complete";
+    const calleesLimited = callees?.status !== "complete";
+    const limited_directions = callersLimited
+        ? calleesLimited
+            ? ["callers", "callees"]
+            : ["callers"]
+        : ["callees"];
+    const reasons = reads.flatMap(({ direction, coverage }) => {
+        const label = direction === "callers" ? callerCoveragePrefix : calleeCoveragePrefix;
+        return relationshipCoverageLimitations(coverage).map((reason) => `${label}${reason}`);
+    });
+    if (reads.some(({ coverage }) => coverage === undefined || coverage.status === "unknown"))
+        return {
+            status: "unknown",
+            reason: uniqueSorted(reasons).join(" "),
+            limited_directions,
+            ...details,
+        };
+    if (reasons.length > 0)
+        return {
+            status: "partial",
+            limitations: uniqueSorted(reasons),
+            limited_directions,
+            ...details,
+        };
+    return { status: "complete", ...details };
+};
+/**
+ * Forward searches depend on callee coverage. Preserve the historical
+ * unknown-reason encoding when reading observations without explicit directions.
+ */
+export const isCallerOnlyIncompleteCoverage = (coverage) => {
+    if (coverage.status === "complete")
+        return false;
+    if (coverage.limited_directions !== undefined)
+        return !coverage.limited_directions.some((direction) => direction === "callees");
+    return (coverage.status === "unknown" &&
+        coverage.reason.startsWith(callerCoveragePrefix) &&
+        !coverage.reason.includes(calleeCoveragePrefix));
+};
+/** Keep observed-set blockers separate from descriptive provider caveats. */
+export const assessFunctionCallCoverage = (coverage, dossier) => ({
+    blockers: uniqueSorted([
+        ...relationshipCoverageLimitations(coverage),
+        ...(dossier.unresolved_calls ?? []).map(({ address, reason }) => `Unresolved call at ${address}: ${reason}`),
+    ]),
+    diagnostics: uniqueSorted(coverage?.diagnostics ?? []),
+});

package/dist/domain/functionComparisonDimensions.js

@@ -1,6 +1,6 @@
 import { canonicalJson } from "./comparisonSemantics.js";
 import { diffLines } from "diff";
-import { commentProjection, identityProjection, isAutoName, normalizeCfg, referenceKindProjection, referenceProjection, sorted, stringAndNameProjection, } from "./functionComparisonNormalization.js";
+import { commentProjection, identityProjection, isAutoName, normalizeCfg, referenceKindProjection, referenceProjection, sorted, stringAndNameProjection, swiftLiteralSitesConflict, } from "./functionComparisonNormalization.js";
 import { dimensionResult, unresolvedDimension, } from "./functionComparisonResults.js";
 export const compareDimensions = (left, right, context) => {
     return [
@@ -12,14 +12,66 @@ export const compareDimensions = (left, right, context) => {
         compareReferences(left, right, context),
         compareStringsAndNames(left, right, context),
         compareCfg(left, right, context),
-    ];
+    ].map((result) => {
+        const limitations = [
+            ...facetLimitations(left, result.dimension).map((reason) => `Left: ${reason}`),
+            ...facetLimitations(right, result.dimension).map((reason) => `Right: ${reason}`),
+        ];
+        return limitations.length === 0
+            ? result
+            : unresolvedDimension({
+                dimension: result.dimension,
+                links: context.links,
+                leftCount: null,
+                rightCount: null,
+                limitations: [...result.limitations, ...limitations],
+            });
+    });
+};
+/** An empty undeclared facet is not evidence of observed absence. */
+const facetLimitations = (snapshot, dimension) => {
+    const { dossier } = snapshot;
+    const fields = {
+        identity: [],
+        pseudocode: [["pseudocode", dossier.pseudocode.length]],
+        assembly: [["assembly", dossier.assembly.length]],
+        comments: [["comments", dossier.comments.length]],
+        calls: [
+            ["callers", dossier.callers.length],
+            ["callees", dossier.callees.length],
+        ],
+        references: [
+            [
+                "references",
+                dossier.incoming_references.length + dossier.outgoing_references.length,
+            ],
+        ],
+        strings_names: [
+            [
+                "strings_names",
+                dossier.referenced_strings.length + dossier.referenced_names.length,
+            ],
+        ],
+        cfg: [["cfg", dossier.basic_blocks.length]],
+    };
+    return fields[dimension].flatMap(([field, count]) => {
+        const availability = dossier.facet_availability?.[field];
+        if (availability?.available === false)
+            return [`${field}: ${availability.reason}`];
+        return availability === undefined && count === 0
+            ? [`${field}: Provider did not declare coverage for this empty facet.`]
+            : [];
+    });
 };
 const compareText = (dimension, left, right, context) => {
-    const limitations = dimension === "assembly"
-        ? [
-            "Assembly is opaque provider text; relocation normalization is unavailable.",
-        ]
-        : [];
+    const limitations = [
+        "Exact provider text is compared without address or generated-name normalization; layout-only differences do not establish a behavior change.",
+        ...(dimension === "assembly"
+            ? [
+                "Assembly is opaque provider text; relocation normalization is unavailable.",
+            ]
+            : []),
+    ];
     if (context.providersDiffer)
         return unresolvedDimension({
             dimension,
@@ -42,6 +94,7 @@ const compareText = (dimension, left, right, context) => {
             leftCount: [...left].length,
             rightCount: [...right].length,
             limitations: [
+                ...limitations,
                 "Bounded line diff exceeded its time or edit-distance limit.",
             ],
         });
@@ -78,8 +131,11 @@ const compareComments = (left, right, context) => {
     return compareValues("comments", leftValues, rightValues, context);
 };
 const compareStringsAndNames = (left, right, context) => {
-    const leftValues = stringAndNameProjection(left);
-    const rightValues = stringAndNameProjection(right);
+    const complete = swiftLiteralCoverage(left) === swiftLiteralCoverage(right) &&
+        swiftLiteralCoverage(left) !== "partial";
+    // Facts both dossiers record decide a change before Swift literal coverage can.
+    const leftValues = stringAndNameProjection(left, complete);
+    const rightValues = stringAndNameProjection(right, complete);
     if (leftValues === null || rightValues === null)
         return unresolvedDimension({
             dimension: "strings_names",
@@ -90,11 +146,39 @@ const compareStringsAndNames = (left, right, context) => {
                 "Reference source locations could not be normalized to function offsets.",
             ],
         });
-    return compareValues("strings_names", leftValues, rightValues, context);
+    const compared = compareValues("strings_names", leftValues, rightValues, context);
+    if (complete || compared.status === "changed")
+        return compared;
+    // A retained literal differs only when the opposite dossier establishes its absence.
+    if (swiftLiteralSitesConflict(left, right)) {
+        const leftAll = stringAndNameProjection(left);
+        const rightAll = stringAndNameProjection(right);
+        if (leftAll !== null && rightAll !== null)
+            return compareValues("strings_names", leftAll, rightAll, context);
+    }
+    return unresolvedDimension({
+        dimension: "strings_names",
+        links: context.links,
+        leftCount: null,
+        rightCount: null,
+        limitations: [
+            "Swift String literal coverage differs or is partial; referenced strings and names match, and complete coverage does not establish a differing literal.",
+        ],
+    });
 };
+const swiftLiteralCoverage = (snapshot) => (snapshot.dossier.swift_string_literal_omissions ?? []).length > 0
+    ? "partial"
+    : snapshot.dossier.swift_string_literals === undefined
+        ? "absent"
+        : "complete";
+const hasUnnamedEndpoint = (snapshot) => [
+    ...snapshot.dossier.incoming_references,
+    ...snapshot.dossier.outgoing_references,
+].some((edge) => edge.source_procedure === null || edge.target_procedure === null);
 const compareReferences = (left, right, context) => {
-    const leftProjection = referenceProjection(left);
-    const rightProjection = referenceProjection(right);
+    const sameArtifact = left.subject.digest.sha256 === right.subject.digest.sha256;
+    const leftProjection = referenceProjection(left, sameArtifact);
+    const rightProjection = referenceProjection(right, sameArtifact);
     if (leftProjection.length === 0 && rightProjection.length === 0)
         return compareValues("references", leftProjection, rightProjection, context);
     if (canonicalJson(leftProjection, "Function comparison") !==
@@ -112,9 +196,26 @@ const compareReferences = (left, right, context) => {
                 "Reference endpoints differ independently of provider reference-kind metadata.",
             ],
         });
-    const leftKinds = referenceKindProjection(left);
-    const rightKinds = referenceKindProjection(right);
-    if (leftKinds !== null && rightKinds !== null)
+    const leftKinds = referenceKindProjection(left, sameArtifact);
+    const rightKinds = referenceKindProjection(right, sameArtifact);
+    const kindsKnown = leftKinds !== null && rightKinds !== null;
+    // Differing known edge kinds are a change whatever the endpoint identity.
+    if (kindsKnown &&
+        canonicalJson(leftKinds, "Function comparison") !==
+            canonicalJson(rightKinds, "Function comparison"))
+        return compareValues("references", leftKinds, rightKinds, context);
+    // Equal projections with unknown endpoints do not establish equal targets.
+    if (!sameArtifact && (hasUnnamedEndpoint(left) || hasUnnamedEndpoint(right)))
+        return unresolvedDimension({
+            dimension: "references",
+            links: context.links,
+            leftCount: leftProjection.length,
+            rightCount: rightProjection.length,
+            limitations: [
+                "Unnamed reference endpoints have no stable identity across different artifacts, so equal named endpoints do not establish equal references.",
+            ],
+        });
+    if (kindsKnown)
         return compareValues("references", leftKinds, rightKinds, context);
     return unresolvedDimension({
         dimension: "references",
@@ -143,6 +244,22 @@ const compareIdentity = (left, right, context) => {
 const compareCalls = (left, right, context) => {
     const leftValues = callProjection(left);
     const rightValues = callProjection(right);
+    const coverageLimitations = [
+        ...left.callCoverageBlockers.map((reason) => `Left: ${reason}`),
+        ...right.callCoverageBlockers.map((reason) => `Right: ${reason}`),
+    ];
+    const coverageDiagnostics = [
+        ...left.callCoverageDiagnostics.map((reason) => `Left: ${reason}`),
+        ...right.callCoverageDiagnostics.map((reason) => `Right: ${reason}`),
+    ];
+    if (coverageLimitations.length > 0)
+        return unresolvedDimension({
+            dimension: "calls",
+            links: context.links,
+            leftCount: leftValues.length,
+            rightCount: rightValues.length,
+            limitations: [...coverageLimitations, ...coverageDiagnostics],
+        });
     if ([...leftValues, ...rightValues].some(({ name }) => isAutoName(name)))
         return unresolvedDimension({
             dimension: "calls",
@@ -151,9 +268,10 @@ const compareCalls = (left, right, context) => {
             rightCount: rightValues.length,
             limitations: [
                 "Address-derived callee or caller names cannot be matched safely.",
+                ...coverageDiagnostics,
             ],
         });
-    return compareValues("calls", sorted(leftValues), sorted(rightValues), context);
+    return compareValues("calls", sorted(leftValues), sorted(rightValues), context, coverageDiagnostics);
 };
 const callProjection = (snapshot) => [
     ...snapshot.dossier.callers.map(({ name }) => ({
@@ -182,7 +300,7 @@ const compareCfg = (left, right, context) => {
         });
     return compareValues("cfg", leftGraph, rightGraph, context);
 };
-const compareValues = (dimension, left, right, context) => {
+const compareValues = (dimension, left, right, context, limitations = []) => {
     const leftJson = canonicalJson(left, "Function comparison");
     const rightJson = canonicalJson(right, "Function comparison");
     return dimensionResult({
@@ -194,6 +312,6 @@ const compareValues = (dimension, left, right, context) => {
         leftCount: Array.isArray(left) ? left.length : null,
         rightCount: Array.isArray(right) ? right.length : null,
         textDelta: null,
-        limitations: [],
+        limitations,
     });
 };

package/dist/domain/functionComparisonNormalization.js

@@ -8,21 +8,21 @@ export const identityProjection = (snapshot) => ({
         .sort(),
 });
 export const functionMatch = (left, right) => {
-    if (!isAutoName(left.dossier.procedure.name) &&
-        left.dossier.procedure.name === right.dossier.procedure.name)
+    const leftName = left.dossier.procedure.name;
+    const rightName = right.dossier.procedure.name;
+    const stableNames = !isAutoName(leftName) && !isAutoName(rightName);
+    if (stableNames && leftName === rightName)
         return {
             status: "matched",
             method: "symbol",
-            left_name: left.dossier.procedure.name,
-            right_name: right.dossier.procedure.name,
+            left_name: leftName,
+            right_name: rightName,
         };
     return {
-        status: left.dossier.procedure.name === right.dossier.procedure.name
-            ? "ambiguous"
-            : "mismatched",
+        status: stableNames ? "mismatched" : "ambiguous",
         method: "explicit",
-        left_name: left.dossier.procedure.name,
-        right_name: right.dossier.procedure.name,
+        left_name: leftName,
+        right_name: rightName,
     };
 };
 export const normalizeCfg = (blocks) => {
@@ -57,19 +57,27 @@ export const normalizeCfg = (blocks) => {
     }
     return graph;
 };
-export const referenceProjection = (snapshot) => sorted([
+/**
+ * A named endpoint survives relocation. An unnamed endpoint is identified
+ * only by its address, which names one location only within one artifact;
+ * across artifacts it stays unknown (null).
+ */
+const referenceEndpoint = (procedure, address, sameArtifact) => procedure !== null ? procedure.name : sameArtifact ? { address } : null;
+export const referenceProjection = (snapshot, sameArtifact) => sorted([
     ...snapshot.dossier.incoming_references.map((item) => ({
         direction: "in",
-        source: item.source_procedure?.name ?? null,
-        target: item.target_procedure?.name ?? null,
+        item,
     })),
     ...snapshot.dossier.outgoing_references.map((item) => ({
         direction: "out",
-        source: item.source_procedure?.name ?? null,
-        target: item.target_procedure?.name ?? null,
+        item,
     })),
-]);
-export const referenceKindProjection = (snapshot) => {
+].map(({ direction, item }) => ({
+    direction,
+    source: referenceEndpoint(item.source_procedure, item.source_address, sameArtifact),
+    target: referenceEndpoint(item.target_procedure, item.target_address, sameArtifact),
+})));
+export const referenceKindProjection = (snapshot, sameArtifact) => {
     const edges = [
         ...snapshot.dossier.incoming_references.map((edge) => ({
             direction: "in",
@@ -87,8 +95,8 @@ export const referenceKindProjection = (snapshot) => {
             throw new TypeError("Reference-kind availability changed during projection");
         return {
             direction,
-            source: edge.source_procedure?.name ?? null,
-            target: edge.target_procedure?.name ?? null,
+            source: referenceEndpoint(edge.source_procedure, edge.source_address, sameArtifact),
+            target: referenceEndpoint(edge.target_procedure, edge.target_address, sameArtifact),
             type: edge.kind.type,
             flow: edge.kind.flow,
             call: edge.kind.call,
@@ -114,7 +122,7 @@ export const commentProjection = (snapshot) => {
     }));
     return values.some(({ offset }) => offset === null) ? null : sorted(values);
 };
-export const stringAndNameProjection = (snapshot) => {
+export const stringAndNameProjection = (snapshot, includeSwiftLiterals = true) => {
     const values = [
         ...snapshot.dossier.referenced_strings.map(({ source_address: sourceAddress, value }) => ({
             kind: "string",
@@ -126,11 +134,67 @@ export const stringAndNameProjection = (snapshot) => {
             source_offset: relativeAddress(sourceAddress, snapshot.dossier.procedure.address),
             value,
         })),
+        ...(includeSwiftLiterals
+            ? (snapshot.dossier.swift_string_literals ?? [])
+            : []).map(({ source_address: sourceAddress, value, representation, registers, }) => ({
+            kind: "swift_string",
+            source_offset: relativeAddress(sourceAddress, snapshot.dossier.procedure.address),
+            value,
+            representation,
+            registers,
+        })),
     ];
     return values.some(({ source_offset: offset }) => offset === null)
         ? null
         : sorted(values);
 };
+/**
+ * A retained literal proves presence, not that every path through its site was examined.
+ * A differing retained fact proves a change only when the opposite dossier is complete
+ * and therefore establishes its absence.
+ */
+export const swiftLiteralSitesConflict = (left, right) => {
+    const leftSites = swiftLiteralSites(left);
+    const rightSites = swiftLiteralSites(right);
+    for (const site of new Set([
+        ...leftSites.values.keys(),
+        ...rightSites.values.keys(),
+    ])) {
+        const leftValues = leftSites.values.get(site) ?? (leftSites.complete ? [] : undefined);
+        const rightValues = rightSites.values.get(site) ?? (rightSites.complete ? [] : undefined);
+        if (leftValues === undefined || rightValues === undefined)
+            continue;
+        const leftFacts = new Set(leftValues);
+        const rightFacts = new Set(rightValues);
+        if ((rightSites.complete &&
+            leftValues.some((value) => !rightFacts.has(value))) ||
+            (leftSites.complete && rightValues.some((value) => !leftFacts.has(value))))
+            return true;
+    }
+    return false;
+};
+const swiftLiteralSites = (snapshot) => {
+    const base = snapshot.dossier.procedure.address;
+    const omissions = snapshot.dossier.swift_string_literal_omissions ?? [];
+    const site = (sourceAddress, registers) => {
+        const offset = relativeAddress(sourceAddress, base);
+        return offset === null ? null : canonicalJson([offset, registers]);
+    };
+    // Keep the same literal facts the full strings_names projection compares.
+    const values = new Map();
+    for (const literal of snapshot.dossier.swift_string_literals ?? []) {
+        const key = site(literal.source_address, literal.registers);
+        if (key === null)
+            continue;
+        values.set(key, [
+            ...(values.get(key) ?? []),
+            canonicalJson([literal.value, literal.representation]),
+        ].sort(compareUnicodeCodePoints));
+    }
+    const complete = snapshot.dossier.swift_string_literals !== undefined &&
+        omissions.length === 0;
+    return { values, complete };
+};
 export const sorted = (values) => values
     .map((value) => ({
     value,

package/dist/domain/functionComparisonResults.js

@@ -37,14 +37,15 @@ export const unresolvedDimension = (input) => ({
     limitations: [...input.limitations],
 });
 export const overallStatus = (dimensions, match) => {
-    if (match === "ambiguous" ||
-        dimensions.some(({ status }) => status === "unknown"))
-        return "unknown";
     if (match === "mismatched")
         return "changed";
-    return dimensions.some(({ status }) => status === "changed")
-        ? "changed"
-        : "unchanged";
+    if (match === "ambiguous")
+        return "unknown";
+    if (dimensions.some(({ status }) => status === "changed"))
+        return "changed";
+    if (dimensions.some(({ status }) => status === "unknown"))
+        return "unknown";
+    return "unchanged";
 };
 export const summarize = (dimensions) => ({
     unchanged: dimensions.filter(({ status }) => status === "unchanged").length,

package/dist/domain/functionComparisonSchemas.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import { overallStatus } from "./functionComparisonResults.js";
 import { evidenceSchema } from "./evidence.js";
 import { digestSchema } from "./../domain/digests.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
 const comparisonStatusSchema = z.enum(["unchanged", "changed", "unknown"]);
-const dimensionNameSchema = z.enum([
+export const functionComparisonDimensionNameSchema = z.enum([
     "identity",
     "pseudocode",
     "assembly",
@@ -25,7 +26,7 @@ const textDeltaSchema = z.object({
     hunks: z.number().int().min(0),
 });
 const functionDimensionContextShape = {
-    dimension: dimensionNameSchema,
+    dimension: functionComparisonDimensionNameSchema,
     left_count: z.number().int().min(0).nullable(),
     right_count: z.number().int().min(0).nullable(),
     evidence_links: z.array(evidenceIdSchema).min(2),
@@ -72,7 +73,8 @@ const functionMatchSchema = z.union([
     }),
 ]);
 /** Deterministic dimension-classified function comparison Evidence payload. */
-export const functionComparisonResultSchema = z.object({
+export const functionComparisonResultSchema = z
+    .object({
     status: comparisonStatusSchema,
     function_match: functionMatchSchema,
     left_subject_sha256: digestSchema,
@@ -85,4 +87,13 @@ export const functionComparisonResultSchema = z.object({
     dimensions: z.array(functionDimensionSchema).length(8),
     changes: z.array(functionDimensionSchema),
     limitations: z.array(z.string()),
+})
+    .superRefine((result, context) => {
+    if (result.status !==
+        overallStatus(result.dimensions, result.function_match.status))
+        context.addIssue({
+            code: "custom",
+            path: ["status"],
+            message: "Function comparison status contradicts its dimensions or function match.",
+        });
 });

package/dist/domain/functionDossierEvidence.js

@@ -1,6 +1,7 @@
 import { parseEvidence } from "./evidence.js";
 import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { functionDossierSchema } from "./hopperValues.js";
+import { assessFunctionCallCoverage } from "./functionCallCoverage.js";
 /** Parse one complete analyze_function Evidence record for comparison workflows. */
 export const parseFunctionEvidence = (input) => {
     const evidence = parseEvidence(input);
@@ -9,6 +10,7 @@ export const parseFunctionEvidence = (input) => {
     if (evidence.subject === null)
         throw new TypeError("Function comparison requires artifact-bound Evidence");
     const dossier = functionDossierSchema.parse(evidence.normalized_result);
+    const callCoverage = assessFunctionCallCoverage(evidence.relationship_coverage, dossier);
     return {
         evidence,
         subject: evidence.subject,
@@ -16,5 +18,7 @@ export const parseFunctionEvidence = (input) => {
         limitations: [
             ...new Set([...evidence.limitations, ...dossier.limitations]),
         ].sort((left, right) => compareUnicodeCodePoints(left, right)),
+        callCoverageBlockers: callCoverage.blockers,
+        callCoverageDiagnostics: callCoverage.diagnostics,
     };
 };

package/dist/domain/go/goBinary.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { digestSchema } from "../digests.js";
+import { localPathStringSchema } from "../localPath.js";
+import { CANONICAL_BASE64_PATTERN } from "../stringPatterns.js";
+const sourceRangeSchema = z.strictObject({
+    offset: z.number().int().nonnegative(),
+    bytes: z.number().int().nonnegative(),
+});
+const moduleIdentitySchema = z.strictObject({
+    path: z.string(),
+    version: z.string(),
+    sum: z.string().nullable(),
+});
+/** Module identities retain development versions, local replacements and missing sums verbatim. */
+export const goModuleSchema = moduleIdentitySchema.extend({
+    replacement: moduleIdentitySchema.nullable(),
+});
+/** Parsed records alongside unrecognized text lines and exact non-UTF-8 line bytes. */
+export const goModuleMetadataSchema = z.strictObject({
+    path: z.string().nullable(),
+    main: goModuleSchema.nullable(),
+    dependencies: z.array(goModuleSchema),
+    settings: z.array(z.strictObject({ key: z.string(), value: z.string() })),
+    unparsed_lines: z.array(z.string()),
+    unparsed_line_bytes_base64: z.array(z.string().regex(CANONICAL_BASE64_PATTERN)),
+    complete: z.boolean(),
+});
+/** One exact local artifact, independent of any active disassembler target. */
+export const inspectGoBinaryInputSchema = z.strictObject({
+    path: localPathStringSchema.describe("Absolute filesystem path to the selected executable or library"),
+});
+/** Compiler-written build information and its original file-backed source ranges. */
+export const goBuildInfoSchema = z.strictObject({
+    header_offset: z.number().int().nonnegative(),
+    encoding: z.enum(["inline", "pointer"]),
+    go_version: z.string().nullable(),
+    go_version_bytes_base64: z.string().regex(CANONICAL_BASE64_PATTERN),
+    module_text: z.string().nullable(),
+    module_bytes_base64: z.string().regex(CANONICAL_BASE64_PATTERN),
+    version_location: sourceRangeSchema,
+    module_location: sourceRangeSchema,
+    module: goModuleMetadataSchema,
+});
+/** Complete bounded build-metadata observation; absence does not identify a binary as non-Go. */
+export const goBinarySchema = z
+    .strictObject({
+    artifact: z.strictObject({
+        path: localPathStringSchema,
+        sha256: digestSchema,
+        bytes: z.number().int().nonnegative(),
+    }),
+    format: z.enum(["elf", "pe", "macho"]),
+    architecture: z.string(),
+    bits: z.union([z.literal(32), z.literal(64)]),
+    byte_order: z.enum(["little", "big"]),
+    build_info: goBuildInfoSchema.nullable(),
+    limitations: z.array(z.string()),
+})
+    .superRefine((report, context) => {
+    const info = report.build_info;
+    if (info === null)
+        return;
+    if (info.header_offset > report.artifact.bytes - 32)
+        context.addIssue({
+            code: "custom",
+            path: ["build_info", "header_offset"],
+            message: "Build-info header is outside the selected artifact.",
+        });
+    for (const field of ["version_location", "module_location"]) {
+        const range = info[field];
+        if (range.offset > report.artifact.bytes ||
+            range.bytes > report.artifact.bytes - range.offset)
+            context.addIssue({
+                code: "custom",
+                path: ["build_info", field],
+                message: "Build-info source range is outside the selected artifact.",
+            });
+    }
+    for (const [field, range, description] of [
+        ["go_version_bytes_base64", info.version_location, "compiler"],
+        ["module_bytes_base64", info.module_location, "module"],
+    ]) {
+        const encoded = info[field];
+        const padding = encoded.endsWith("==")
+            ? 2
+            : encoded.endsWith("=")
+                ? 1
+                : 0;
+        if ((encoded.length / 4) * 3 - padding !== range.bytes)
+            context.addIssue({
+                code: "custom",
+                path: ["build_info", field],
+                message: `Encoded ${description} bytes do not match their reported source length.`,
+            });
+    }
+});