rea-agents 6.4.0 → 6.7.0

package/dist/ida/IdaOperationRunner.js

@@ -1,9 +1,12 @@
 import { z } from "zod";
-import { analysisSearchInput } from "../contracts/analysisSearchContract.js";
+import { nativeDecompileSchema, nativeDisassemblySchema, nativeCalleesSchema, nativeXrefsSchema, nativeLiteralSearchPattern, } from "./IdaNativeProtocol.js";
+import { analysisSearchPredicate, analysisSearchQuerySchema, } from "../domain/analysisSearch.js";
 import { AnalysisInputError, AnalysisCancelledError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
 import { functionDossierSchema, functionInstructionWindowSchema, } from "../domain/hopperValues.js";
-import { IDA_LIMITATIONS } from "./IdaProviderCapabilities.js";
-import { disassemblySchema, idaAddressSchema, idaFunctionSchema, legacyCalleesSchema, legacyPageSchema, legacyStringSchema, legacyXrefsSchema, modernCalleesSchema, modernDecompileSchema, modernDisassemblySchema, modernLookupSchema, modernPageSchema, modernStringsSchema, modernXrefsSchema, nextOffset, } from "./IdaProtocolValues.js";
+import { combineFunctionRelationshipCoverage } from "../domain/functionCallCoverage.js";
+import { readCallGraphCallees, unavailableCallGraph } from "./IdaCallGraph.js";
+import { IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION, } from "./IdaProviderCapabilities.js";
+import { disassemblySchema, idaAddressSchema, idaFunctionSchema, idaStringsPageSchema, legacyCalleesSchema, legacyPageSchema, legacyStringSchema, legacyXrefsSchema, modernCalleesSchema, modernDecompileSchema, modernDisassemblySchema, modernLookupSchema, modernLookupBatchSchema, modernPageSchema, modernXrefsSchema, nextOffset, surveySegmentsSchema, } from "./IdaProtocolValues.js";
 const unknownBody = {
     available: false,
     reason: "IDA MCP does not report complete function body ranges.",
@@ -14,29 +17,37 @@ const identity = (fn) => ({
     classification: null,
     body: unknownBody,
 });
+/** The only lookup answers upstream reports for a name or address that is not a function. */
+const MISSING_PROCEDURE_ANSWERS = new Set([
+    "Not found",
+    "Not a function",
+]);
 const lines = (asm) => asm.lines.map(({ address, instruction }) => `${address}: ${instruction}`);
 /** Translate explicit analyst questions into a closed set of read-only upstream requests. */
 export class IdaOperationRunner {
     connection;
     protocol;
     database;
-    signal;
+    options;
     raw = [];
     locations = [];
     limitations = [];
-    constructor(connection, protocol, database, signal) {
+    relationshipCoverage;
+    /** The upstream cap flag of the last `xrefs_to` read, when the producer reported one. */
+    referencesTruncated;
+    constructor(connection, protocol, database, options = {}) {
         this.connection = connection;
         this.protocol = protocol;
         this.database = database;
-        this.signal = signal;
+        this.options = options;
     }
     async call(tool, args) {
-        if (this.signal?.aborted)
+        if (this.options.signal?.aborted)
             throw new AnalysisCancelledError(tool);
         const scoped = this.database === undefined ? args : { ...args, database: this.database };
         const result = await this.connection.call(tool, scoped);
         this.raw.push({ tool, arguments: scoped, result });
-        if (this.signal?.aborted)
+        if (this.options.signal?.aborted)
             throw new AnalysisCancelledError(tool);
         return result;
     }
@@ -59,12 +70,19 @@ export class IdaOperationRunner {
         }
         return result;
     }
-    async resolve(query) {
-        if (this.protocol === "modern") {
+    /**
+     * Resolves a procedure. When `requestedBy` names the caller's operation, an
+     * upstream "not found" or "not a function" answer is reported as invalid
+     * input; every other failed lookup stays a producer fault. `run()` passes
+     * `requestedBy` only for caller-supplied selectors. Provider-derived
+     * selectors, such as the addresses composed workflows revisit, and the
+     * callee resolution inside `relationships()` pass none, because those
+     * addresses were reported by IDA itself.
+     */
+    async resolve(query, requestedBy) {
+        if (this.protocol !== "legacy") {
             const item = modernLookupSchema.parse(await this.call("lookup_funcs", { queries: [query] }))[0];
-            if (item?.fn == null || item.error !== null)
-                throw new AnalysisProtocolError(`IDA function lookup failed for ${query}: ${item?.error ?? "missing function"}`);
-            return item.fn;
+            return this.lookupFunction(query, item, requestedBy);
         }
         const address = idaAddressSchema.safeParse(/^0x/iu.test(query) ? query : undefined);
         const found = idaFunctionSchema.parse(await this.call(address.success ? "get_function_by_address" : "get_function_by_name", address.success ? { address: address.data } : { name: query }));
@@ -75,25 +93,103 @@ export class IdaOperationRunner {
             throw new AnalysisProtocolError("IDA function identity changed during lookup.");
         return entry;
     }
-    async strings() {
+    /** Parse one lookup row: a function, an expected "missing" answer, or a producer failure. */
+    lookupOutcome(query, item) {
+        if (item?.query !== query)
+            throw new AnalysisProtocolError(`IDA function lookup answered for a different query than ${JSON.stringify(query)}.`);
+        if (item.fn === null &&
+            item.error !== null &&
+            MISSING_PROCEDURE_ANSWERS.has(item.error))
+            return { missing: item.error };
+        if (item.fn === null || item.error !== null)
+            throw new AnalysisProtocolError(`IDA function lookup failed for ${query}: ${item.error ?? "missing function"}`);
+        return { fn: item.fn };
+    }
+    lookupFunction(query, item, requestedBy) {
+        const outcome = this.lookupOutcome(query, item);
+        if ("fn" in outcome)
+            return outcome.fn;
+        if (requestedBy === undefined)
+            throw new AnalysisProtocolError(`IDA function lookup failed for ${query}: ${outcome.missing}`);
+        throw new AnalysisInputError(requestedBy, {
+            cause: new AnalysisProtocolError(`IDA function lookup failed for ${query}: ${outcome.missing}`),
+        }, [
+            {
+                path: [],
+                reason: "invalid_value",
+                message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${outcome.missing}.`,
+            },
+        ]);
+    }
+    /** The containing function of an address, or why none contains it. */
+    async containingProcedure(address) {
+        const item = modernLookupSchema.parse(await this.call("lookup_funcs", { queries: [address] }))[0];
+        const outcome = this.lookupOutcome(address, item);
+        if ("fn" in outcome)
+            return {
+                query_address: address,
+                found: true,
+                procedure: identity(outcome.fn),
+            };
+        return {
+            query_address: address,
+            found: false,
+            procedure: null,
+            reason: (await this.addressInSegment(address))
+                ? "not_in_procedure"
+                : "outside_segments",
+        };
+    }
+    /** Segment membership from the database-scoped minimal survey; a missing fact is a failure. */
+    async addressInSegment(address) {
+        if (this.options.surveyAvailable === false)
+            throw new AnalysisProtocolError("The upstream server does not advertise survey_binary, so segment membership cannot be established.");
+        const { segments } = surveySegmentsSchema.parse(await this.call("survey_binary", { detail_level: "minimal" }));
+        const value = BigInt(address);
+        return segments.some(({ start, end }) => start <= value && value < end);
+    }
+    /** True only for modern callee reads on targets not proven x86-only; x86 reads never reach the graph code. */
+    readsCallGraph(direction) {
+        return (this.protocol === "modern" &&
+            direction === "callees" &&
+            this.options.x86Only === false);
+    }
+    /** Add processor-neutral function callees on targets where upstream `callees` is unsound. */
+    async addCallGraphCallees(fn, result) {
+        const graph = this.options.callGraphAvailable === false
+            ? unavailableCallGraph("the upstream server does not advertise it")
+            : await readCallGraphCallees((tool, args) => this.call(tool, args), fn.address);
+        this.limitations.push(...graph.limitations);
+        for (const callee of graph.callees)
+            if (!result.has(callee.address))
+                result.set(callee.address, identity({ ...callee, size: "unknown" }));
+        return graph.coverage;
+    }
+    async strings(nativePattern) {
+        if (this.protocol === "native")
+            this.limitations.push(IDA_NATIVE_STRING_LIMITATION);
         const result = [];
         let offset = 0;
         while (offset !== null) {
             const current = offset;
             if (this.protocol === "legacy") {
-                const page = legacyPageSchema.parse(await this.call("list_strings", { offset, count: 100 }));
-                result.push(...page.data.map((item) => {
+                const page = legacyPageSchema.parse(await this.call("list_strings", { offset, count: 0 }));
+                for (const item of page.data) {
                     const s = legacyStringSchema.parse(item);
-                    return { address: s.address, value: s.string };
-                }));
+                    result.push({ address: s.address, value: s.string });
+                }
                 offset = page.next_offset;
             }
             else {
-                const page = modernStringsSchema.parse(await this.call("find_regex", {
-                    pattern: "(?s).*",
+                const page = idaStringsPageSchema.parse(await this.call("find_regex", {
+                    pattern: this.protocol === "native"
+                        ? (nativePattern ?? "[\\s\\S]*")
+                        : "(?s).*",
                     offset,
                     limit: 100,
                 }));
+                if (page.error !== undefined && page.error !== null)
+                    throw new AnalysisProtocolError(`${this.protocol === "native" ? "Native IDA" : "IDA"} string search failed: ${page.error}`);
                 result.push(...page.matches.map((s) => ({ address: s.addr, value: s.string })));
                 offset = nextOffset(page.cursor, current);
             }
@@ -111,7 +207,9 @@ export class IdaOperationRunner {
         let result;
         let offset = 0;
         while (offset !== null) {
-            const page = modernDisassemblySchema.parse(await this.call("disasm", {
+            const page = (this.protocol === "native"
+                ? nativeDisassemblySchema
+                : modernDisassemblySchema).parse(await this.call("disasm", {
                 addr: fn.address,
                 offset,
                 max_instructions: 100,
@@ -139,6 +237,15 @@ export class IdaOperationRunner {
                 .string()
                 .nullable()
                 .parse(await this.call("decompile_function", { address: fn.address }));
+        if (this.protocol === "native") {
+            const page = nativeDecompileSchema.parse(await this.call("decompile", { addr: fn.address }));
+            if (page.addr !== fn.address)
+                throw new AnalysisProtocolError("Native IDA pseudocode identifies a different function than the resolved entry.");
+            if (!page.ok || page.error !== undefined || page.pseudocode === undefined)
+                throw new AnalysisProtocolError(`Native IDA decompilation failed: ${page.error ?? "missing pseudocode"}`);
+            this.limitations.push("Native pseudocode is rendered GUI text; the upstream viewer traversal is bounded and does not establish complete source recovery.");
+            return page.pseudocode;
+        }
         const result = [];
         let offset = 0;
         while (offset !== null) {
@@ -157,9 +264,11 @@ export class IdaOperationRunner {
     async xrefs(address) {
         if (this.protocol === "legacy")
             return legacyXrefsSchema.parse(await this.call("get_xrefs_to", { address }));
-        const page = modernXrefsSchema.parse(await this.call("xrefs_to", { addrs: [address], limit: 1000 }))[0];
+        const page = (this.protocol === "native" ? nativeXrefsSchema : modernXrefsSchema).parse(await this.call("xrefs_to", { addrs: [address], limit: 1000 }))[0];
         if (page?.xrefs == null || page.error !== undefined)
             throw new AnalysisProtocolError(`IDA xrefs failed: ${page?.error ?? "missing references"}`);
+        if (page.more !== undefined)
+            this.referencesTruncated = page.more;
         if (page.more === true)
             this.limitations.push("Upstream xrefs_to capped results at 1000 references; additional references remain unknown.");
         return page.xrefs.map((xref) => ({
@@ -171,6 +280,20 @@ export class IdaOperationRunner {
     async relationships(fn, direction) {
         const queries = [];
         const result = new Map();
+        let coverage = {
+            status: "unknown",
+            reason: "The legacy relationship response does not report coverage.",
+        };
+        if (this.readsCallGraph(direction)) {
+            coverage = await this.addCallGraphCallees(fn, result);
+            return {
+                items: [...result.values()],
+                coverage,
+                availability: coverage.status === "unknown"
+                    ? { available: false, reason: coverage.reason }
+                    : { available: true },
+            };
+        }
         if (this.protocol === "legacy") {
             const value = await this.call(direction === "callers" ? "get_callers" : "get_callees", { function_address: fn.address });
             const items = direction === "callers"
@@ -184,15 +307,34 @@ export class IdaOperationRunner {
             }
         }
         else if (direction === "callers") {
-            this.limitations.push("Modern upstream xrefs classify references as code or data, without proving call edges. Direct callers are unavailable in this profile.");
-            return [];
+            this.limitations.push("Upstream xrefs classify references as code or data, without proving call edges. Direct callers are unavailable in this profile.");
+            return {
+                items: [],
+                availability: {
+                    available: false,
+                    reason: "Upstream xrefs do not establish direct caller relationships.",
+                },
+                coverage: {
+                    status: "unknown",
+                    reason: "Upstream xrefs do not establish direct caller relationships.",
+                },
+            };
         }
         else {
-            const page = modernCalleesSchema.parse(await this.call("callees", { addrs: [fn.address], limit: 500 }))[0];
+            const page = (this.protocol === "native" ? nativeCalleesSchema : modernCalleesSchema).parse(await this.call("callees", { addrs: [fn.address], limit: 500 }))[0];
             if (page?.callees == null || page.error !== undefined)
                 throw new AnalysisProtocolError(`IDA callees failed: ${page?.error ?? "missing callees"}`);
             if (page.more === true)
                 this.limitations.push("Upstream callees capped results at 500; additional callees remain unknown.");
+            coverage =
+                page.more === true
+                    ? {
+                        status: "partial",
+                        limitations: [
+                            "Upstream callees capped results at 500; additional callees remain unknown.",
+                        ],
+                    }
+                    : { status: "complete" };
             for (const item of page.callees) {
                 if ("type" in item && item.type === "external")
                     result.set(item.addr, identity({ address: item.addr, name: item.name, size: "unknown" }));
@@ -200,36 +342,72 @@ export class IdaOperationRunner {
                     queries.push(item.addr);
             }
         }
-        for (const query of new Set(queries)) {
-            const resolved = identity(await this.resolve(query));
-            result.set(resolved.address, resolved);
+        const querySet = new Set(queries);
+        if (this.protocol === "native" && querySet.size > 0) {
+            const rows = modernLookupBatchSchema.parse(await this.call("lookup_funcs", { queries: [...querySet] }));
+            const byQuery = new Map(rows.map((row) => [row.query, row]));
+            if (rows.length !== querySet.size ||
+                byQuery.size !== rows.length ||
+                rows.some((row) => !querySet.has(row.query)))
+                throw new AnalysisProtocolError("Native IDA returned an inconsistent callee lookup batch.");
+            for (const query of querySet) {
+                const resolved = identity(this.lookupFunction(query, byQuery.get(query)));
+                result.set(resolved.address, resolved);
+            }
+        }
+        else {
+            for (const query of querySet) {
+                const resolved = identity(await this.resolve(query));
+                result.set(resolved.address, resolved);
+            }
         }
-        return [...result.values()];
+        return {
+            items: [...result.values()],
+            coverage,
+            availability: { available: true },
+        };
     }
     async run(operation, parameters) {
+        const query = operation === "search_procedures" || operation === "search_strings"
+            ? analysisSearchQuerySchema.parse(parameters)
+            : undefined;
+        const matches = query === undefined ? undefined : analysisSearchPredicate(query);
         if (operation === "list_procedures" || operation === "search_procedures") {
             const items = (await this.functions()).map((fn) => ({
                 address: fn.address,
                 value: fn.name,
             }));
-            return operation === "list_procedures"
+            return matches === undefined
                 ? items
-                : this.search(items, parameters);
+                : items.filter(({ value }) => matches(value));
         }
         if (operation === "list_strings" || operation === "search_strings") {
-            const items = await this.strings();
-            return operation === "search_strings"
-                ? this.search(items, parameters)
+            const nativePattern = this.protocol === "native" && query?.mode === "literal"
+                ? nativeLiteralSearchPattern(query.pattern, query.case_sensitive)
+                : undefined;
+            const items = await this.strings(nativePattern);
+            return matches !== undefined
+                ? items.filter(({ value }) => matches(value))
                 : parameters.address === undefined
                     ? items
                     : items.filter(({ address }) => address === idaAddressSchema.parse(parameters.address));
         }
+        if (operation === "list_documents") {
+            if (this.options.admittedDocument === undefined)
+                throw new AnalysisProtocolError("The admitted IDA program is unknown.");
+            return [this.options.admittedDocument];
+        }
+        if (operation === "resolve_containing_procedure") {
+            const queried = idaAddressSchema.parse(parameters.address);
+            this.locations.push({ kind: "address", address: queried });
+            return this.containingProcedure(queried);
+        }
         if (operation === "xrefs") {
             const inspectedAddress = idaAddressSchema.parse(parameters.address);
             this.locations.push({ kind: "address", address: inspectedAddress });
             return (await this.xrefs(inspectedAddress)).map(({ address }) => address);
         }
-        const fn = await this.resolve(z.string().min(1).parse(parameters.procedure));
+        const fn = await this.resolve(z.string().min(1).parse(parameters.procedure), this.options.selectorOrigin === "provider" ? undefined : operation);
         this.locations.push({ kind: "address", address: fn.address });
         switch (operation) {
             case "procedure_address":
@@ -239,11 +417,13 @@ export class IdaOperationRunner {
             case "procedure_assembly":
                 return lines(await this.assembly(fn)).join("\n");
             case "procedure_callers":
-                if (this.protocol === "modern")
+            case "procedure_callees": {
+                if (operation === "procedure_callers" && this.protocol !== "legacy")
                     throw new AnalysisProtocolError("This IDA MCP profile cannot distinguish direct callers from other code references.");
-                return (await this.relationships(fn, "callers")).map(({ address }) => address);
-            case "procedure_callees":
-                return (await this.relationships(fn, "callees")).map(({ address }) => address);
+                const relationships = await this.relationships(fn, operation === "procedure_callers" ? "callers" : "callees");
+                this.relationshipCoverage = relationships.coverage;
+                return relationships.items.map(({ address }) => address);
+            }
             case "read_function_instructions":
                 return functionInstructionWindowSchema.parse({
                     procedure: identity(fn),
@@ -254,31 +434,12 @@ export class IdaOperationRunner {
                 return this.dossier(fn);
         }
     }
-    search(items, input) {
-        const query = z.object(analysisSearchInput).parse(input);
-        let matches;
-        if (query.mode === "regex") {
-            try {
-                const regex = new RegExp(query.pattern, query.case_sensitive ? "u" : "iu");
-                matches = (value) => regex.test(value);
-            }
-            catch (cause) {
-                throw new AnalysisInputError("search", { cause });
-            }
-        }
-        else {
-            const needle = query.case_sensitive
-                ? query.pattern
-                : query.pattern.toLowerCase();
-            matches = (value) => (query.case_sensitive ? value : value.toLowerCase()).includes(needle);
-        }
-        return items.filter(({ value }) => matches(value));
-    }
     async dossier(fn) {
         const asm = await this.assembly(fn);
         const pseudocode = await this.pseudocode(fn);
         const callers = await this.relationships(fn, "callers");
         const callees = await this.relationships(fn, "callees");
+        this.relationshipCoverage = combineFunctionRelationshipCoverage(callers.coverage, callees.coverage);
         const signature = asm.return_type == null || asm.arguments == null
             ? null
             : `${asm.return_type} ${fn.name}(${asm.arguments.map((arg) => `${arg.type} ${arg.name}`).join(", ")})`;
@@ -287,8 +448,8 @@ export class IdaOperationRunner {
             pseudocode: pseudocode ?? "",
             assembly: lines(asm),
             comments: [],
-            callers,
-            callees,
+            callers: callers.items,
+            callees: callees.items,
             incoming_references: [],
             outgoing_references: [],
             referenced_strings: [],
@@ -296,6 +457,30 @@ export class IdaOperationRunner {
             basic_blocks: [],
             native_api: null,
             native_value_flow: null,
+            facet_availability: {
+                pseudocode: pseudocode === null
+                    ? { available: false, reason: "IDA did not supply pseudocode." }
+                    : { available: true },
+                assembly: { available: true },
+                comments: {
+                    available: false,
+                    reason: "IDA adapter does not expose typed comments.",
+                },
+                callers: callers.availability,
+                callees: callees.availability,
+                references: {
+                    available: false,
+                    reason: "IDA adapter does not expose typed reference edges.",
+                },
+                strings_names: {
+                    available: false,
+                    reason: "IDA adapter does not expose function-referenced strings and names.",
+                },
+                cfg: {
+                    available: false,
+                    reason: "IDA adapter does not expose basic blocks.",
+                },
+            },
             limitations: [
                 ...IDA_LIMITATIONS,
                 ...this.limitations,

package/dist/ida/IdaProtocolValues.js

@@ -30,6 +30,13 @@ export const legacyMetadataSchema = z
     base: idaAddressSchema,
 })
     .passthrough();
+/** A worker that is still busy right after opening reports this transient shape instead of its identity. */
+export const busyHealthSchema = z
+    .object({
+    status: z.literal("busy"),
+    busy_tool: z.string().optional(),
+})
+    .passthrough();
 export const modernHealthSchema = z
     .object({
     status: z.literal("ok"),
@@ -62,13 +69,13 @@ export const modernPageSchema = z
     next_offset: z.number().int().nonnegative().nullable(),
 }))
     .length(1);
-export const modernLookupSchema = z
-    .array(z.object({
+const modernLookupRowSchema = z.object({
     query: z.string(),
     fn: idaFunctionSchema.nullable(),
     error: z.string().nullable(),
-}))
-    .length(1);
+});
+export const modernLookupBatchSchema = z.array(modernLookupRowSchema);
+export const modernLookupSchema = modernLookupBatchSchema.length(1);
 const instructionSchema = z.union([
     z.object({
         address: idaAddressSchema,
@@ -109,9 +116,10 @@ export const legacyStringSchema = z.object({
     string: z.string(),
     length: z.number().int().nonnegative(),
 });
-export const modernStringsSchema = z.object({
+export const idaStringsPageSchema = z.object({
     matches: z.array(z.object({ addr: idaAddressSchema, string: z.string() })),
     cursor: cursorSchema,
+    error: z.string().nullish(),
 });
 export const legacyXrefsSchema = z.array(z.object({
     address: idaAddressSchema,
@@ -144,6 +152,25 @@ export const modernCalleesSchema = z
     more: z.boolean().optional(),
 }))
     .length(1);
+/** Depth-one `callgraph` reply: one row per root, with function-only call edges. */
+export const modernCallGraphSchema = z
+    .array(z
+    .object({
+    root: z.string(),
+    error: z.string().optional(),
+    nodes: z.array(z.object({ addr: idaAddressSchema, name: z.string().nullable() })),
+    edges: z.array(z.object({
+        from: idaAddressSchema,
+        to: idaAddressSchema,
+        type: z.string(),
+    })),
+    truncated: z.boolean().optional(),
+    limit_reason: z.string().nullable().optional(),
+    max_edges_per_func: z.number().int().positive().optional(),
+    per_func_capped: z.boolean().optional(),
+})
+    .passthrough())
+    .length(1);
 export const legacyCalleesSchema = z.array(z.object({ address: idaAddressSchema, name: z.string() }).passthrough());
 /** Parsed database lifecycle observations retain explicit ownership information. */
 export const openDatabaseSchema = z
@@ -154,6 +181,13 @@ export const openDatabaseSchema = z
         .passthrough(),
 })
     .passthrough();
+/** Only an explicit completed rejection preserves legacy no-worker cleanup. */
+export const rejectedOpenDatabaseSchema = z
+    .object({
+    error: z.string().min(1),
+    success: z.never().optional(),
+})
+    .passthrough();
 export const databaseListSchema = z
     .object({
     sessions: z.array(z
@@ -176,3 +210,52 @@ export const closeDatabaseSchema = z
     backend: z.enum(["worker", "gui"]),
 })
     .passthrough();
+/** Supervisor response when the requested worker was already reaped. */
+export const absentDatabaseCloseSchema = (sessionId) => z
+    .object({ error: z.literal(`Session not found: ${sessionId}`) })
+    .passthrough();
+// Piped, so a malformed coordinate is a schema issue and never reaches BigInt.
+const hexCoordinate = z
+    .string()
+    .regex(/^0x[0-9a-f]+$/iu)
+    .pipe(z.transform((value) => BigInt(value)));
+/**
+ * The minimal `survey_binary` reply, reduced to validated segment intervals
+ * (exclusive ends). Any malformed, reversed or inconsistent fact rejects the
+ * whole reply, because a membership answer needs every segment.
+ */
+export const surveySegmentsSchema = z
+    .object({
+    statistics: z
+        .object({ total_segments: z.number().int().nonnegative().optional() })
+        .passthrough()
+        .optional(),
+    segments: z
+        .array(z
+        .object({
+        start: hexCoordinate,
+        end: hexCoordinate,
+        size: hexCoordinate.optional(),
+    })
+        .passthrough())
+        .min(1),
+})
+    .passthrough()
+    .superRefine(({ statistics, segments }, context) => {
+    if (statistics?.total_segments !== undefined &&
+        statistics.total_segments !== segments.length)
+        context.addIssue({
+            code: "custom",
+            message: "survey segment count disagrees with its statistics",
+        });
+    for (const { start, end, size } of segments) {
+        // A malformed row has already reported its own issue; refinements still run.
+        if (typeof start !== "bigint" || typeof end !== "bigint")
+            continue;
+        if (start >= end || (size !== undefined && size !== end - start))
+            context.addIssue({
+                code: "custom",
+                message: "survey segment bounds are reversed or inconsistent",
+            });
+    }
+});