rea-agents 6.4.0 → 6.5.0

package/dist/domain/evidenceBundle.js

@@ -4,23 +4,28 @@ import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { evidenceSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
 import { residualUnknownSchema, } from "./residualUnknown.js";
 import { freezeJsonSnapshot } from "./immutableJson.js";
-const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+const [detectedSubjectSchema, rawSubjectSchema] = evidenceSchema.shape.subject.unwrap().options;
+const manifestFields = {
     digest: true,
     format: true,
     architecture: true,
-});
+};
+const artifactManifestSchema = z.discriminatedUnion("format", [
+    detectedSubjectSchema.pick(manifestFields),
+    rawSubjectSchema.pick(manifestFields),
+]);
 const providerManifestSchema = providerSchema;
 const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
-const scenarioManifestSchema = z.object({
+const scenarioManifestSchema = z.strictObject({
     evidence_id: evidenceSchema.shape.evidence_id,
     operation: z.string().min(1),
     authority: z.literal("controlled-replay"),
 });
-const captureManifestSchema = z.object({
+const captureManifestSchema = z.strictObject({
     evidence_id: evidenceSchema.shape.evidence_id,
     predicate_type: z.string().min(1),
 });
-export const evidenceBundleSchema = z.object({
+export const evidenceBundleSchema = z.strictObject({
     artifacts: z.array(artifactManifestSchema),
     providers: z.array(providerManifestSchema),
     environments: z.array(environmentManifestSchema),
@@ -30,6 +35,13 @@ export const evidenceBundleSchema = z.object({
     records: z.array(evidenceSchema),
 });
 const immutableBundles = new WeakMap();
+/** Caller input has valid shape but is not in authenticated canonical form. */
+export class NonCanonicalEvidenceBundleError extends TypeError {
+    constructor() {
+        super("Evidence bundle manifests are not canonical");
+        this.name = "NonCanonicalEvidenceBundleError";
+    }
+}
 /** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
 export const createImmutableEvidenceBundle = (records, unknowns = []) => {
     const checkedRecords = records.map(immutableEvidence);
@@ -49,11 +61,11 @@ export const createEvidenceBundle = (records, unknowns = []) => {
         artifacts: uniqueSorted(sortedRecords.flatMap(({ subject }) => subject === null
             ? []
             : [
-                {
+                artifactManifestSchema.parse({
                     digest: subject.digest,
                     format: subject.format,
                     architecture: subject.architecture,
-                },
+                }),
             ])),
         providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
         environments: uniqueSorted(sortedRecords.flatMap(({ environment }) => environment === null ? [] : [environment])),
@@ -138,17 +150,22 @@ const referencedEvidenceIds = (unknown) => [
     ...unknown.mutation_evidence_ids,
     ...(unknown.resolution?.evidence_ids ?? []),
 ];
-/**
- * Name the bundle constraint that failed and how to recover. A single
- * Evidence record, such as one command result, is not a bundle.
- */
 export const describeEvidenceBundleFailure = (input, cause) => {
-    const record = evidenceSchema.safeParse(input);
-    if (record.success)
-        return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
-    return cause instanceof z.ZodError
-        ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
-        : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`;
+    try {
+        const record = parseEvidence(input);
+        return {
+            kind: "single-record",
+            message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
+        };
+    }
+    catch {
+        return {
+            kind: "invalid-bundle",
+            message: cause instanceof z.ZodError
+                ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
+                : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`,
+        };
+    }
 };
 /** Locate the first schema issue, or keep a thrown constraint message. */
 export const describeValidationFailure = (cause) => {
@@ -162,19 +179,36 @@ export const describeValidationFailure = (cause) => {
 };
 /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
 export const parseEvidenceBundle = (input) => {
+    return parseBundle(input, false);
+};
+/** Authenticate and seal file-owned payloads once for downstream zero-copy reuse. */
+export const parseImmutableEvidenceBundle = (input) => {
+    return parseBundle(input, true);
+};
+const parseBundle = (input, seal) => {
     if (typeof input === "object" && input !== null) {
         const owned = immutableBundles.get(input);
         if (owned !== undefined)
             return owned;
     }
-    const parsed = evidenceBundleSchema.parse(input);
+    return authenticateBundle(evidenceBundleSchema.parse(input), seal);
+};
+/** Authenticate evidence and bundle invariants after the bundle shape is parsed. */
+export const authenticateParsedEvidenceBundle = (parsed) => authenticateBundle(parsed, false);
+const authenticateBundle = (parsed, seal) => {
     const recordIds = parsed.records.map(({ evidence_id: id }) => id);
     if (new Set(recordIds).size !== recordIds.length)
         throw new TypeError("Evidence bundle contains duplicate record IDs");
     validateUnknownGraph(parsed.unknowns, parsed.records);
     const canonical = createEvidenceBundle(parsed.records.map((record, index) => {
         try {
-            return parseEvidence(record);
+            if (!seal)
+                return parseEvidence(record);
+            // Schema parsing gave this boundary exclusive ownership. Register only
+            // validated payloads before authenticating the complete record envelope.
+            record.normalized_result = freezeJsonSnapshot(record.normalized_result);
+            record.raw_result = freezeJsonSnapshot(record.raw_result);
+            return immutableEvidence(record);
         }
         catch (cause) {
             if (cause instanceof z.ZodError)
@@ -186,7 +220,11 @@ export const parseEvidenceBundle = (input) => {
         }
     }), parsed.unknowns);
     if (JSON.stringify(parsed) !== JSON.stringify(canonical))
-        throw new TypeError("Evidence bundle manifests are not canonical");
+        throw new NonCanonicalEvidenceBundleError();
+    if (seal) {
+        freezeJsonSnapshot(canonical);
+        immutableBundles.set(canonical, canonical);
+    }
     return canonical;
 };
 const validateUnknownGraph = (unknowns, records) => {

package/dist/domain/evidenceErrors.js

@@ -30,12 +30,17 @@ export class EvidenceFileError extends AnalysisError {
     operation;
     reason;
     _tag = "EvidenceFileError";
+    userMessage;
     /** Caller-selected path that failed, resolved against the working directory. */
     path;
+    /** Present only when a write committed before cleanup failed. */
+    published;
     constructor(operation, reason, options) {
         super(`Evidence bundle ${operation} failed: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
         this.path = options?.path;
+        this.published = options?.published;
+        this.userMessage = options?.userMessage;
     }
 }

package/dist/domain/evm/evmInterface.js

@@ -1,12 +1,11 @@
 import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { solidityMetadataSchema } from "./solidityMetadata.js";
 const byteOffset = z.number().int().nonnegative();
 const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
 /** Select the carrier representation explicitly; no RPC or deployed-contract lookup is implied. */
 export const inspectEvmInterfaceInputSchema = z.strictObject({
-    path: z
-        .string()
-        .min(1)
-        .describe("Absolute path to caller-selected local bytecode carrier"),
+    path: localPathStringSchema.describe("Absolute path to caller-selected local bytecode carrier"),
     encoding: z
         .enum(["raw", "hex"])
         .describe("Raw bytes or UTF-8 hex with optional 0x prefix and outer ASCII whitespace"),
@@ -28,6 +27,7 @@ export const evmInterfaceSchema = z
         kind: z.literal("unknown"),
         deployment_authenticity: z.literal("unknown"),
         hardfork: z.literal("unknown"),
+        metadata: solidityMetadataSchema.nullable().default(null),
     }),
     evidence_kind: z.literal("inferred"),
     functions: z.array(z.strictObject({
@@ -53,6 +53,20 @@ export const evmInterfaceSchema = z
             path: ["bytecode"],
             message: "Selected byte count does not match the bytecode hex representation.",
         });
+    const metadata = value.bytecode.metadata;
+    if (metadata !== null &&
+        metadata.status !== "unavailable" &&
+        (metadata.bytecode_offset === null ||
+            metadata.cbor_bytes === null ||
+            metadata.bytecode_offset + metadata.cbor_bytes + 2 !==
+                value.bytecode.bytes ||
+            metadata.cbor_bytes !==
+                Number.parseInt(value.bytecode.hex.slice(-4), 16)))
+        context.addIssue({
+            code: "custom",
+            path: ["bytecode", "metadata"],
+            message: "Metadata range must match the terminal length suffix in selected bytecode.",
+        });
     for (const [index, fn] of value.functions.entries())
         if (fn.bytecode_offset >= value.bytecode.bytes)
             context.addIssue({

package/dist/domain/evm/solidityMetadata.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/** Scalar view of CBOR; uninterpreted containers remain in original bytecode. */
+export const solidityMetadataScalarSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("text"), value: z.string().max(65535) }),
+    z.strictObject({
+        kind: z.literal("integer"),
+        value: z
+            .string()
+            .max(21)
+            .regex(/^-?(?:0|[1-9][0-9]*)$/),
+    }),
+    z.strictObject({
+        kind: z.literal("bytes"),
+        value: z
+            .string()
+            .max(131070)
+            .regex(/^(?:[a-f0-9]{2})*$/),
+    }),
+    z.strictObject({ kind: z.literal("boolean"), value: z.boolean() }),
+    z.strictObject({ kind: z.literal("null") }),
+    z.strictObject({
+        kind: z.literal("uninterpreted"),
+        container: z.enum(["array", "map"]),
+    }),
+]);
+/** A trailer candidate, not authentication of Solidity origin or deployment. */
+export const solidityMetadataSchema = z
+    .strictObject({
+    profile: z.literal("terminal-cbor-scalars-v1"),
+    status: z.enum(["unavailable", "decoded", "partial", "not-decoded"]),
+    bytecode_offset: z.number().int().nonnegative().nullable(),
+    cbor_bytes: z.number().int().positive().max(65535).nullable(),
+    entries: z
+        .array(z.strictObject({
+        key: solidityMetadataScalarSchema,
+        value: solidityMetadataScalarSchema,
+    }))
+        .max(32767),
+    compiler_version: z
+        .strictObject({
+        representation: z.enum(["release-bytes", "prerelease-text"]),
+        value: z.string().min(1).max(65535),
+    })
+        .nullable(),
+    diagnostic: z.string().max(512).nullable(),
+})
+    .superRefine((value, context) => {
+    const unavailable = value.status === "unavailable";
+    if (unavailable
+        ? value.bytecode_offset !== null || value.cbor_bytes !== null
+        : value.bytecode_offset === null || value.cbor_bytes === null)
+        context.addIssue({
+            code: "custom",
+            message: "Only unavailable metadata omits the candidate range.",
+        });
+    const unexamined = unavailable || value.status === "not-decoded";
+    if (unexamined &&
+        (value.entries.length !== 0 || value.compiler_version !== null))
+        context.addIssue({
+            code: "custom",
+            message: "Unavailable interpretation cannot report decoded entries or compiler identity.",
+        });
+    const uninterpreted = value.entries.some(({ key, value: entryValue }) => key.kind === "uninterpreted" || entryValue.kind === "uninterpreted");
+    if ((value.status === "decoded" && uninterpreted) ||
+        (value.status === "partial" && !uninterpreted))
+        context.addIssue({
+            code: "custom",
+            message: "Scalar coverage must preserve uninterpreted containers.",
+        });
+});

package/dist/domain/explicitSensitiveFailure.js

@@ -1,4 +1,4 @@
-import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, AnalysisCancelledError, AnalysisTimeoutError, } from "./analysisErrorCore.js";
 import { redactExplicitText } from "./explicitSensitiveValues.js";
 import { ProviderAdapterError } from "./providerAdapterError.js";
 import { ProviderCleanupError } from "./providerCleanupError.js";
@@ -51,12 +51,45 @@ export const redactExplicitFailure = (error, values) => {
             return diagnostics(value);
         return value;
     };
+    const context = {
+        cause: error,
+        ...(error.diagnostics === undefined
+            ? {}
+            : { diagnostics: diagnostics(error.diagnostics) }),
+        ...(error.capturedOutput === undefined
+            ? {}
+            : {
+                capturedOutput: {
+                    ...error.capturedOutput,
+                    stdout: text(error.capturedOutput.stdout),
+                    stderr: text(error.capturedOutput.stderr),
+                },
+            }),
+        ...(error.cleanup === undefined
+            ? {}
+            : {
+                cleanup: {
+                    reason: text(error.cleanup.reason),
+                    resources: error.cleanup.resources.map(text),
+                },
+            }),
+    };
+    if (error instanceof AnalysisCancelledError)
+        return new AnalysisCancelledError(error.operation, {
+            ...context,
+            partialObservation: error.partialObservation,
+        });
+    if (error instanceof AnalysisTimeoutError)
+        return new AnalysisTimeoutError(error.operation, error.timeoutMs, {
+            ...context,
+            partialObservation: error.partialObservation,
+        });
     if (error instanceof AnalysisAccessDeniedError)
-        return new AnalysisAccessDeniedError(error.operation, text(error.path), error.systemCode, { cause: error });
+        return new AnalysisAccessDeniedError(error.operation, text(error.path), error.systemCode, context);
     if (error instanceof AnalysisArtifactChangedError)
-        return new AnalysisArtifactChangedError(error.operation, text(error.path), text(error.reason), { cause: error });
+        return new AnalysisArtifactChangedError(error.operation, text(error.path), text(error.reason), context);
     if (error instanceof AnalysisInputError)
-        return new AnalysisInputError(error.operation, { cause: error }, error.issues.map((issue) => ({
+        return new AnalysisInputError(error.operation, context, error.issues.map((issue) => ({
             ...issue,
             // Unknown-argument paths contain literal field names, including names
             // beginning with '/'; they are not producer JSON-pointer coordinates.
@@ -69,40 +102,25 @@ export const redactExplicitFailure = (error, values) => {
                 : { expected: visit(issue.expected) }),
         })));
     if (error instanceof AnalysisOutputError)
-        return new AnalysisOutputError(error.operation, text(error.reason), {
-            cause: error,
-        });
+        return new AnalysisOutputError(error.operation, text(error.reason), context);
     if (error instanceof AnalysisCapabilityUnavailableError)
         return new AnalysisCapabilityUnavailableError(error.providerId, error.operation, text(error.reason), {
-            cause: error,
+            ...context,
             ...(error.userMessage === undefined
                 ? {}
                 : { userMessage: text(error.userMessage) }),
+            ...(error.retryable ? { retryable: true } : {}),
         });
     if (error instanceof AnalysisResourceConstraintError)
         return new AnalysisResourceConstraintError(error.operation, error.resource, text(error.reason), error.reportedLimits === null ? null : diagnostics(error.reportedLimits), {
-            cause: error,
+            ...context,
             ...(error.remediationAction === undefined
                 ? {}
                 : { remediationAction: text(error.remediationAction) }),
-            ...(error.capturedOutput === undefined
-                ? {}
-                : {
-                    capturedOutput: {
-                        stdout: text(error.capturedOutput.stdout),
-                        stderr: text(error.capturedOutput.stderr),
-                        truncated: error.capturedOutput.truncated,
-                    },
-                }),
         });
     if (error instanceof ProviderCleanupError)
         return new ProviderCleanupError(error.providerId, error.cleanupResources.map(text), diagnostics(error.diagnostics ?? {}), { operation: error.operation, cause: error });
     if (error instanceof ProviderAdapterError)
-        return new ProviderAdapterError(error.providerId, error.operation, {
-            cause: error,
-            ...(error.diagnostics === undefined
-                ? {}
-                : { diagnostics: diagnostics(error.diagnostics) }),
-        });
+        return new ProviderAdapterError(error.providerId, error.operation, context);
     return error;
 };

package/dist/domain/firmware/firmwareAnalysis.js

@@ -75,6 +75,32 @@ const chunk = z.strictObject({
     handler: z.string().nullable(),
     encrypted: z.boolean().nullable(),
     root_file_range: range.nullable(),
+    /** The producer reported extraction problems for this chunk. */
+    extraction_failed: z.boolean(),
+});
+/** One unextracted region or failing task/stage, with a supported continuation
+ * using already configured capabilities when one exists. */
+export const extractionGap = z.strictObject({
+    kind: z.enum([
+        "missing-extractor-dependency",
+        "unknown-chunk-handler",
+        "encrypted-chunk",
+        "depth-limited",
+        "extractor-failure",
+        "unpublished-entry",
+    ]),
+    /** Logical task path from the producer report; `$output/…` for unpublished entries. */
+    input_path: z.string(),
+    relative_path: z.string().nullable(),
+    handler: z.string().nullable(),
+    /** Reported chunk or multi-file stage identity; it does not imply a byte range. */
+    provider_id: z.string().nullable(),
+    range: range.nullable(),
+    root_file_range: range.nullable(),
+    /** Extractor executables named by the producer; empty when it named none. */
+    dependencies: z.array(z.string()),
+    /** Lookup key in the result's extraction_continuations table. */
+    continuation_id: z.string(),
 });
 /** Portable results retain reported boundaries, unknowns and extraction lineage. */
 export const firmwareResultSchemas = {
@@ -123,6 +149,9 @@ export const firmwareResultSchemas = {
         })),
         depth_limited_paths: z.array(z.string()),
         diagnostics: z.array(jsonValueSchema),
+        extraction_gaps: z.array(extractionGap),
+        /** Each distinct recovery instruction is serialized once, shared by gap ID. */
+        extraction_continuations: z.array(z.strictObject({ id: z.string(), instruction: z.string() })),
         published_bytes: bytes,
     }),
 };

package/dist/domain/flutter/flutterBuildAnalysis.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { digestSchema } from "../digests.js";
+/**
+ * Caller intent for Flutter build identification. This family is pure
+ * parsing: it reads an APK's `lib/<abi>/libapp.so` and `libflutter.so`
+ * directly and runs no engine, tool, or device.
+ */
+export const flutterInputSchemas = {
+    identify_flutter_build: z.strictObject({
+        path: localPathStringSchema.describe("Local APK file to inspect"),
+    }),
+    inspect_dart_aot: z.strictObject({
+        path: localPathStringSchema.describe("Local APK file carrying a Flutter AOT payload"),
+        abi: z
+            .string()
+            .min(2)
+            .max(16)
+            .regex(/^[a-z0-9_\x2d]+$/u, "ABI name as it appears under lib/, e.g. arm64-v8a")
+            .optional()
+            .describe("ABI to inspect; defaults to arm64-v8a, x86_64, x86, armeabi-v7a, then remaining ABIs alphabetically"),
+    }),
+};
+/** Retained delivery is selected independently of the provider's ABI request. */
+export const dartAotInspectionInputSchema = flutterInputSchemas.inspect_dart_aot.extend({
+    detail: z.enum(["complete", "summary"]).optional(),
+});
+/** Validate operation and input together so their types remain correlated. */
+export const flutterRequestSchema = z.discriminatedUnion("operation", [
+    z.strictObject({
+        operation: z.literal("identify_flutter_build"),
+        input: flutterInputSchemas.identify_flutter_build,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_dart_aot"),
+        input: flutterInputSchemas.inspect_dart_aot,
+    }),
+]);
+/** One hardware ABI's Flutter payload inside the APK. */
+export const flutterResultSchemas = {
+    identify_flutter_build: z.strictObject({
+        target: z.strictObject({
+            path: localPathStringSchema,
+            bytes: z.number().int().nonnegative(),
+            sha256: digestSchema,
+        }),
+        flutter_detected: z.boolean(),
+        abis: z.array(z.strictObject({
+            abi: z.string().min(1),
+            libapp: z.strictObject({
+                present: z.boolean(),
+                bytes: z.number().int().nonnegative().nullable(),
+                sha256: digestSchema.nullable(),
+                /** Supported ELF header with table extents inside the library; table contents are not validated. */
+                elf_header_valid: z.boolean().nullable(),
+                /** Number of Dart snapshot sections found (vm + isolate). */
+                snapshot_hash_sources: z.number().int().nonnegative(),
+                /** Distinct hashes found; more than one means the sections disagree. */
+                snapshot_hash_candidates: z.array(z.string().regex(/^[0-9a-f]{32}$/u)),
+                /** The single hash when every snapshot section agrees. */
+                snapshot_hash: z
+                    .string()
+                    .regex(/^[0-9a-f]{32}$/u)
+                    .nullable(),
+            }),
+            libflutter: z.strictObject({
+                present: z.boolean(),
+                bytes: z.number().int().nonnegative().nullable(),
+                sha256: digestSchema.nullable(),
+                build_id: z
+                    .string()
+                    .regex(/^[0-9a-f]{8,128}$/u)
+                    .nullable()
+                    .describe("The single GNU build ID when ELF note coverage is complete and unambiguous"),
+                build_id_candidates: z
+                    .array(z.string().regex(/^[0-9a-f]{8,128}$/u))
+                    .max(64)
+                    .describe("Distinct GNU build IDs observed in ELF-owned note ranges; conflicting IDs remain explicit"),
+                dart_version: z
+                    .string()
+                    .nullable()
+                    .describe("Labeled 'Dart VM version' string, when a build carries one"),
+                toolchain_lines: z.array(z.string().min(1)),
+                /** Dart labels omitted by grammar or single-version projection bounds. */
+                dart_version_capped: z.boolean(),
+                /** Toolchain labels omitted by grammar or projection bounds. */
+                toolchain_capped: z.boolean(),
+            }),
+        })),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    inspect_dart_aot: z.strictObject({
+        target: z.strictObject({
+            path: localPathStringSchema,
+            bytes: z.number().int().nonnegative(),
+            sha256: digestSchema,
+        }),
+        abi: z.string().min(1),
+        libapp: z.strictObject({
+            coverage: z
+                .enum(["complete", "partial"])
+                .describe("Coverage of ELF symbols, independent data headers, AOT kind, extents and agreeing hashes"),
+            bytes: z.number().int().nonnegative(),
+            sha256: digestSchema,
+            snapshot_hash: z
+                .string()
+                .regex(/^[0-9a-f]{32}$/u)
+                .nullable(),
+            /** Distinct hashes found; more than one means the sections disagree. */
+            snapshot_hash_candidates: z.array(z.string().regex(/^[0-9a-f]{32}$/u)),
+            /** Distinct exported data headers with a valid hash at the header's fixed offset. */
+            snapshot_hash_sources: z.number().int().nonnegative(),
+            /** Snapshot symbols read from the dynamic symbol table. */
+            sections: z.array(z.strictObject({
+                name: z.string().min(1),
+                offset: z.number().int().nonnegative(),
+                size: z.number().int().nonnegative(),
+                magic_valid: z.boolean(),
+                kind: z.number().int().nonnegative().nullable(),
+                /** Raw declared snapshot length, excluding the four magic bytes. */
+                header_length: z.number().int().nonnegative().nullable(),
+            })),
+        }),
+        string_pool: z.strictObject({
+            coverage: z
+                .enum(["complete", "partial"])
+                .describe("Coverage of the bounded printable-run projection; independent of snapshot header validity"),
+            /** Distinct package: source URIs, sorted, bounded. */
+            package_uris: z.array(z.string().min(1)),
+            package_uri_count_at_least: z.number().int().nonnegative(),
+            /** Distinct dart: SDK URIs, sorted, bounded. */
+            dart_uris: z.array(z.string().min(1)),
+            dart_uri_count_at_least: z.number().int().nonnegative(),
+            /** Identifier-like tokens, bounded; includes incidental matches. */
+            class_like_tokens: z.array(z.string().min(1)),
+            class_like_token_count_at_least: z.number().int().nonnegative(),
+            printable_run_count: z.number().int().nonnegative(),
+        }),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+};

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));
+};
+/** Explain why two resolved call sets cannot establish call-set equality. */
+export const functionCallCoverageLimitations = (coverage, dossier) => {
+    return uniqueSorted([
+        ...relationshipCoverageLimitations(coverage),
+        ...(coverage?.status === "complete" ? [] : (coverage?.diagnostics ?? [])),
+        ...(dossier.unresolved_calls ?? []).map(({ address, reason }) => `Unresolved call at ${address}: ${reason}`),
+    ]);
+};