rea-agents 1.6.0 → 2.0.0

package/dist/domain/errors.js

@@ -28,6 +28,7 @@ const ANALYSIS_ERROR_TAGS = [
     "NoBinaryOpenError",
     "BinaryTargetError",
     "PermissionRequiredError",
+    "ReplayPlanStaleError",
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
@@ -46,10 +47,12 @@ export class AnalysisProtocolError extends AnalysisError {
 /** Caller input failed provider-neutral application parsing. */
 export class AnalysisInputError extends AnalysisError {
     operation;
+    issues;
     _tag = "AnalysisInputError";
-    constructor(operation, options) {
+    constructor(operation, options, issues = []) {
         super(`Invalid analysis input for ${operation}`, options);
         this.operation = operation;
+        this.issues = issues;
     }
 }
 /** Provider output failed provider-neutral application parsing. */
@@ -96,24 +99,74 @@ export class AnalysisTimeoutError extends AnalysisError {
         this.timeoutMs = timeoutMs;
     }
 }
-/** No configured provider can satisfy a requested operation. */
+/** No configured provider can satisfy a requested operation or target binding. */
 export class ProviderSelectionError extends AnalysisError {
-    operation;
     _tag = "ProviderSelectionError";
-    constructor(operation) {
-        super(`No configured provider can execute ${operation}`);
+    operation;
+    reason;
+    requestedProviderId;
+    candidateIds;
+    rejections;
+    userMessage;
+    constructor(input) {
+        const legacy = typeof input === "string";
+        const options = legacy
+            ? {
+                operation: input,
+                reason: "provider_unavailable",
+                requestedProviderId: "auto",
+                candidateIds: [],
+            }
+            : input;
+        const operation = options.operation ?? "open_binary";
+        super(legacy
+            ? `No configured provider can execute ${operation}`
+            : providerSelectionDiagnostic(options));
         this.operation = operation;
+        this.reason = options.reason;
+        this.requestedProviderId = options.requestedProviderId;
+        this.candidateIds = [...options.candidateIds];
+        this.rejections = [...(options.rejections ?? [])].map((rejection) => ({
+            ...rejection,
+            diagnostics: structuredClone(rejection.diagnostics),
+        }));
+        this.userMessage = providerSelectionUserMessage(options);
     }
 }
+const providerSelectionDiagnostic = (options) => {
+    const candidates = options.candidateIds.length === 0
+        ? "none"
+        : options.candidateIds.join(", ");
+    return `Analysis provider selection failed (${options.reason}) for ${options.requestedProviderId}; candidates: ${candidates}`;
+};
+const providerSelectionUserMessage = (options) => {
+    switch (options.reason) {
+        case "ambiguous":
+            return "Multiple analysis providers support this target. Choose one with provider_id, --provider, or REA_ANALYSIS_PROVIDER.";
+        case "unknown_provider":
+            return `The requested analysis provider is unknown. Choose one of: ${options.candidateIds.join(", ") || "no configured providers"}.`;
+        case "provider_unavailable":
+            return "The selected analysis provider is unavailable. Review the reported local diagnostics or run `rea doctor`, then retry.";
+        case "target_unsupported":
+            return "The selected analysis provider does not support this target. Choose another provider or open a supported extracted binary.";
+        case "invalid_options":
+            return "The analysis provider selection or open options are invalid. Correct them and try again.";
+    }
+};
 /** A provider adapter failed outside its more precise typed variants. */
 export class ProviderAdapterError extends AnalysisError {
     providerId;
     operation;
     _tag = "ProviderAdapterError";
-    constructor(providerId, operation, options) {
+    diagnostics;
+    constructor(providerId, operation, options = {}) {
         super(`Provider ${providerId} adapter failed during ${operation}`, options);
         this.providerId = providerId;
         this.operation = operation;
+        this.diagnostics =
+            options.diagnostics === undefined
+                ? undefined
+                : structuredClone(options.diagnostics);
     }
 }
 /** A bounded passive browser observation failed at its CDP boundary. */
@@ -146,6 +199,20 @@ export class ArtifactOperationError extends AnalysisError {
 export class EvidenceIntegrityError extends AnalysisError {
     _tag = "EvidenceIntegrityError";
 }
+/** A session Evidence reference is missing or has the wrong semantic identity. */
+export class EvidenceReferenceError extends EvidenceIntegrityError {
+    evidenceId;
+    reason;
+    expected;
+    actual;
+    constructor(evidenceId, reason, expected, actual) {
+        super(`Evidence reference ${reason}: ${evidenceId}`);
+        this.evidenceId = evidenceId;
+        this.reason = reason;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
 /** A bounded evidence ledger cannot accept more records or serialized bytes. */
 export class EvidenceLimitError extends AnalysisError {
     limit;
@@ -279,6 +346,17 @@ export class PermissionRequiredError extends AnalysisError {
         this.restartRequired = restartRequired;
     }
 }
+/** Approved replay commitment no longer matches the immediately rebuilt plan. */
+export class ReplayPlanStaleError extends AnalysisError {
+    approvedDigest;
+    actualDigest;
+    _tag = "ReplayPlanStaleError";
+    constructor(approvedDigest, actualDigest) {
+        super("Controlled replay plan changed before execution");
+        this.approvedDigest = approvedDigest;
+        this.actualDigest = actualDigest;
+    }
+}
 /** Project expected failures into exhaustive, secret-safe caller fields. */
 export const projectAnalysisError = (error) => {
     assertKnownTag(error._tag);
@@ -300,8 +378,13 @@ export const projectAnalysisError = (error) => {
     };
 };
 const errorCode = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "plan_stale";
     if (error instanceof PermissionRequiredError)
         return "permission_required";
+    if (error instanceof ProviderSelectionError &&
+        error.reason === "provider_unavailable")
+        return "provider_unavailable";
     if (error instanceof BrowserObservationError) {
         if (error.reason === "payload_limit")
             return "truncated";
@@ -400,9 +483,35 @@ const errorCode = (error) => {
         case "UnknownRegistryError":
         case "PermissionRequiredError":
             throw new TypeError("Unhandled specialized analysis error");
+        case "ReplayPlanStaleError":
+            throw new TypeError("Unhandled specialized replay error");
     }
 };
 const errorDetails = (error) => {
+    if (error instanceof AnalysisInputError && error.issues.length > 0)
+        return {
+            operation: error.operation,
+            issues: error.issues.map((issue) => ({
+                path: [...issue.path],
+                reason: issue.reason,
+                ...(issue.expected === undefined ? {} : { expected: issue.expected }),
+                ...(issue.minimum === undefined ? {} : { minimum: issue.minimum }),
+                ...(issue.maximum === undefined ? {} : { maximum: issue.maximum }),
+            })),
+        };
+    if (error instanceof EvidenceReferenceError)
+        return {
+            evidence_id: error.evidenceId,
+            reason: error.reason,
+            expected: error.expected,
+            actual: error.actual,
+        };
+    if (error instanceof ReplayPlanStaleError)
+        return {
+            approved_plan_digest: error.approvedDigest,
+            actual_plan_digest: error.actualDigest,
+            application_code_admitted: false,
+        };
     if (error instanceof PermissionRequiredError)
         return {
             capability: error.requested.capability,
@@ -441,8 +550,27 @@ const errorDetails = (error) => {
         return { operation: error.operation, reason: error.reason };
     if (error instanceof AnalysisCapabilityUnavailableError)
         return { provider_id: error.providerId, operation: error.operation };
+    if (error instanceof ProviderSelectionError)
+        return {
+            operation: error.operation,
+            selection_reason: error.reason,
+            requested_provider_id: error.requestedProviderId,
+            candidate_ids: [...error.candidateIds],
+            rejections: error.rejections.map((rejection) => ({
+                provider_id: rejection.providerId,
+                code: rejection.code,
+                reason: rejection.reason,
+                diagnostics: rejection.diagnostics,
+            })),
+        };
     if (error instanceof ProviderAdapterError)
-        return { provider_id: error.providerId, operation: error.operation };
+        return {
+            provider_id: error.providerId,
+            operation: error.operation,
+            ...(error.diagnostics === undefined
+                ? {}
+                : { diagnostics: error.diagnostics }),
+        };
     if (error instanceof BrowserObservationError)
         return { operation: error.operation, reason: error.reason };
     if (error instanceof HopperRemoteError)
@@ -483,12 +611,17 @@ const missingScopeDetails = (scope) => ({
     ...(scope.mount === undefined ? {} : { mount: scope.mount }),
 });
 const RETRYABLE_CODES = new Set([
+    "invalid_request",
     "provider_timeout",
     "cancelled",
     "revision_conflict",
     "provider_unavailable",
 ]);
 const remediationAction = (error) => {
+    if (error instanceof AnalysisInputError)
+        return "Correct the listed arguments and retry.";
+    if (error instanceof ReplayPlanStaleError)
+        return "Review the rebuilt replay plan and explicitly approve its new digest.";
     if (error instanceof PermissionRequiredError)
         return error.elicitationSupported
             ? "Approve the exact missing scope, then retry the operation."
@@ -496,8 +629,13 @@ const remediationAction = (error) => {
     return userMessage(error);
 };
 const errorCategory = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "integrity_mismatch";
     if (error instanceof PermissionRequiredError)
         return "permission_required";
+    if (error instanceof ProviderSelectionError &&
+        error.reason === "provider_unavailable")
+        return "unavailable";
     if (error._tag === "ProcessCaptureError")
         return error.userCategory ?? "execution_failure";
     if (error instanceof BrowserObservationError) {
@@ -557,6 +695,8 @@ const STATIC_ERROR_CATEGORIES = {
     BinaryTargetError: "unavailable",
 };
 const userMessage = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "The controlled replay plan changed before execution. Refresh the current state and try again.";
     if (error instanceof PermissionRequiredError)
         return "This operation needs additional local permission. Review the requested scope and remediation.";
     if (error instanceof AnalysisInputError)
@@ -695,6 +835,7 @@ const KNOWN_ERROR_TAGS = {
     NoBinaryOpenError: true,
     BinaryTargetError: true,
     PermissionRequiredError: true,
+    ReplayPlanStaleError: true,
 };
 const assertKnownTag = (tag) => {
     if (KNOWN_ERROR_TAGS[tag] !== true)

package/dist/domain/evidence.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
+import { analysisProfileSchema, } from "./analysisProfile.js";
 import { jsonValueSchema } from "./jsonValue.js";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 /** Provider identity schema shared by evidence-bearing persistence formats. */
@@ -14,6 +15,7 @@ const subjectSchema = z.object({
     digest: z.object({ sha256: digestSchema }),
     format: z.enum([
         "hopper",
+        "analysis-database",
         "mach-o",
         "elf",
         "pe",
@@ -66,8 +68,8 @@ const executionEnvironmentSchema = z.object({
     architecture: z.string().min(1),
     isolation: z.enum(["none", "process", "container", "virtual-machine"]),
 });
-/** Strict, provider-neutral record for one successful public observation. */
-export const evidenceSchema = z.object({
+const evidenceBaseSchema = z
+    .object({
     schema_version: z.literal(2),
     evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
     subject: subjectSchema.nullable(),
@@ -83,7 +85,34 @@ export const evidenceSchema = z.object({
     limitations: z.array(z.string()),
     locations: z.array(evidenceLocationSchema),
     evidence_links: z.array(z.string().regex(/^ev_[a-f0-9]{64}$/u)),
+})
+    .strict();
+/** Object envelope used to specialize caller-visible Evidence result schemas. */
+export const evidenceEnvelopeSchema = evidenceBaseSchema.extend({
+    analysis_profile: analysisProfileSchema.optional(),
 });
+const validateAnalysisProfileProvider = (evidence, context) => {
+    const profile = evidence.analysis_profile;
+    if (profile !== undefined &&
+        (profile.provider.id !== evidence.provider.id ||
+            profile.provider.name !== evidence.provider.name ||
+            profile.provider.version !== evidence.provider.version))
+        context.addIssue({
+            code: "custom",
+            path: ["analysis_profile", "provider"],
+            message: "Analysis profile provider does not match Evidence provider",
+        });
+};
+/** Strict, provider-neutral record for one successful public observation. */
+export const evidenceSchema = evidenceEnvelopeSchema.superRefine(validateAnalysisProfileProvider);
+const profiledEvidenceSchema = evidenceBaseSchema
+    .extend({ analysis_profile: analysisProfileSchema })
+    .superRefine(validateAnalysisProfileProvider);
+/** JSON-exact union used where Evidence participates in larger schemas. */
+export const evidenceRecordSchema = z.union([
+    profiledEvidenceSchema,
+    evidenceBaseSchema,
+]);
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 /** Serialize JSON according to RFC 8785 JSON Canonicalization Scheme. */
 const canonicalJson = (value) => {
@@ -102,6 +131,9 @@ const semanticProjection = (evidence) => ({
             architecture: evidence.subject.architecture,
         },
     provider: evidence.provider,
+    ...(!("analysis_profile" in evidence)
+        ? {}
+        : { analysis_profile: evidence.analysis_profile }),
     predicate_type: evidence.predicate_type,
     operation: evidence.operation,
     parameters: evidence.parameters,
@@ -123,7 +155,7 @@ export const parseEvidence = (input) => {
         "schema_version" in input &&
         input.schema_version !== 2)
         throw new TypeError(`Unsupported evidence schema_version ${String(input.schema_version)}; Evidence v1 is not accepted. Produce Evidence v2.`);
-    const evidence = evidenceSchema.parse(input);
+    const evidence = evidenceRecordSchema.parse(input);
     const { evidence_id: evidenceId, ...withoutId } = evidence;
     if (computeEvidenceId(withoutId) !== evidenceId)
         throw new TypeError("Evidence semantic identifier does not match its record");
@@ -154,6 +186,9 @@ export const createEvidence = (target, provider, observation) => {
             name: provider.name,
             version: provider.version,
         },
+        ...(observation.analysisProfile === undefined
+            ? {}
+            : { analysis_profile: observation.analysisProfile }),
         predicate_type: observation.predicateType ?? "rea.analysis/v2",
         operation: observation.operation,
         parameters: observation.parameters,
@@ -171,9 +206,13 @@ export const createEvidence = (target, provider, observation) => {
         locations: [...(observation.locations ?? [])],
         evidence_links: [...(observation.evidenceLinks ?? [])],
     };
-    return evidenceSchema.parse({
+    const normalized = evidenceRecordSchema.parse({
         ...semantic,
-        evidence_id: `ev_${sha256(canonicalJson(semantic))}`,
+        evidence_id: `ev_${"0".repeat(64)}`,
         subject,
     });
+    return parseEvidence({
+        ...normalized,
+        evidence_id: computeEvidenceId(normalized),
+    });
 };

package/dist/domain/evidenceBundle.js

@@ -1,21 +1,23 @@
 import { z } from "zod";
 import canonicalize from "canonicalize";
-import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { evidenceEnvelopeSchema, evidenceRecordSchema, parseEvidence, providerSchema, } from "./evidence.js";
 import { residualUnknownSchema, } from "./residualUnknown.js";
-const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+const artifactManifestSchema = evidenceEnvelopeSchema.shape.subject
+    .unwrap()
+    .pick({
     digest: true,
     format: true,
     architecture: true,
 });
-const providerManifestSchema = evidenceSchema.shape.provider;
-const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
+const providerManifestSchema = providerSchema;
+const environmentManifestSchema = evidenceEnvelopeSchema.shape.environment.unwrap();
 const scenarioManifestSchema = z.object({
-    evidence_id: evidenceSchema.shape.evidence_id,
+    evidence_id: evidenceEnvelopeSchema.shape.evidence_id,
     operation: z.string().min(1),
     authority: z.literal("controlled-replay"),
 });
 const captureManifestSchema = z.object({
-    evidence_id: evidenceSchema.shape.evidence_id,
+    evidence_id: evidenceEnvelopeSchema.shape.evidence_id,
     predicate_type: z.string().min(1),
 });
 export const evidenceBundleSchema = z.object({
@@ -26,7 +28,7 @@ export const evidenceBundleSchema = z.object({
     scenarios: z.array(scenarioManifestSchema),
     captures: z.array(captureManifestSchema),
     unknowns: z.array(residualUnknownSchema),
-    records: z.array(evidenceSchema),
+    records: z.array(evidenceRecordSchema),
 });
 /** Project records into a deterministic bundle whose order has no semantics. */
 export const createEvidenceBundle = (records, unknowns = []) => {

package/dist/domain/functionComparison.js

@@ -1,6 +1,6 @@
 import { diffLines } from "diff";
 import { parseFunctionEvidence, } from "./functionDossierEvidence.js";
-import { commentProjection, combineCoverage, functionMatch, identityProjection, isAutoName, normalizeCfg, project, referenceProjection, sorted, stringAndNameProjection, } from "./functionComparisonNormalization.js";
+import { commentProjection, combineCoverage, functionMatch, identityProjection, isAutoName, normalizeCfg, project, referenceKindProjection, referenceProjection, sorted, stringAndNameProjection, } from "./functionComparisonNormalization.js";
 import { functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
 import { canonicalJson, dimensionResult, overallStatus, summarize, unresolvedDimension as buildUnresolvedDimension, } from "./functionComparisonResults.js";
 export { functionComparisonInputSchema, functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
@@ -141,10 +141,16 @@ const compareReferences = (left, right, links, providersDiffer) => {
             rightCount: rightProjection.length,
             textDelta: null,
             limitations: [
-                "Reference endpoints differ; exact reference kinds remain unavailable.",
+                "Reference endpoints differ independently of provider reference-kind metadata.",
             ],
         });
-    return unresolvedDimension("references", "unknown", links, leftProjection.length, rightProjection.length, ["Reference kinds are unavailable in the current dossier contract."]);
+    const leftKinds = referenceKindProjection(left);
+    const rightKinds = referenceKindProjection(right);
+    if (leftKinds !== null && rightKinds !== null)
+        return compareValues("references", leftKinds, rightKinds, links, true, true, providersDiffer);
+    return unresolvedDimension("references", "unknown", links, leftProjection.length, rightProjection.length, [
+        "At least one provider did not expose reference kinds, so equal endpoints do not prove equal edge semantics.",
+    ]);
 };
 const compareIdentity = (left, right, links, providersDiffer) => {
     if (isAutoName(left.procedure.name) || isAutoName(right.procedure.name))

package/dist/domain/functionComparisonNormalization.js

@@ -60,6 +60,43 @@ export const referenceProjection = (snapshot) => sorted([
         target: item.target_procedure?.name ?? null,
     })),
 ]);
+export const referenceKindProjection = (snapshot) => {
+    const edges = [
+        ...snapshot.collections.incoming_references.items.map((edge) => ({
+            direction: "in",
+            edge,
+        })),
+        ...snapshot.collections.outgoing_references.items.map((edge) => ({
+            direction: "out",
+            edge,
+        })),
+    ];
+    if (edges.some(({ edge }) => !edge.kind.available))
+        return null;
+    return sorted(edges.map(({ direction, edge }) => {
+        if (!edge.kind.available)
+            throw new TypeError("Reference-kind availability changed during projection");
+        return {
+            direction,
+            source: edge.source_procedure?.name ?? null,
+            target: edge.target_procedure?.name ?? null,
+            type: edge.kind.type,
+            flow: edge.kind.flow,
+            call: edge.kind.call,
+            jump: edge.kind.jump,
+            data: edge.kind.data,
+            read: edge.kind.read,
+            write: edge.kind.write,
+            indirect: edge.kind.indirect,
+            computed: edge.kind.computed,
+            conditional: edge.kind.conditional,
+            terminal: edge.kind.terminal,
+            primary: edge.kind.primary,
+            operand_index: edge.kind.operand_index,
+            external: edge.kind.external,
+        };
+    }));
+};
 export const commentProjection = (snapshot) => {
     const values = snapshot.collections.comments.items.map(({ address, kind, text }) => ({
         offset: relativeAddress(address, snapshot.procedure.address),

package/dist/domain/functionComparisonSchemas.js

@@ -1,9 +1,4 @@
 import { z } from "zod";
-import { evidenceSchema } from "./evidence.js";
-const evidenceInput = z.union([
-    evidenceSchema,
-    z.array(evidenceSchema).min(1).max(100),
-]);
 const comparisonStatusSchema = z.enum([
     "unchanged",
     "added",
@@ -25,9 +20,9 @@ const dimensionNameSchema = z.enum([
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 /** Strict bounded input for explicit function-to-function comparison. */
-export const functionComparisonInputSchema = z.object({
-    left: evidenceInput,
-    right: evidenceInput,
+export const functionComparisonInputSchema = z.strictObject({
+    left_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    right_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),

package/dist/domain/functionDossierEvidence.js

@@ -47,7 +47,10 @@ export const parseFunctionEvidence = (input) => {
         collections,
         instructionScan: first.dossier.instruction_scan,
         limitations: [
-            ...new Set(pages.flatMap(({ evidence }) => evidence.limitations)),
+            ...new Set(pages.flatMap(({ evidence, dossier }) => [
+                ...evidence.limitations,
+                ...dossier.limitations,
+            ])),
         ].sort((left, right) => left.localeCompare(right)),
     };
 };

package/dist/domain/hopperValues.js

@@ -1,8 +1,27 @@
 import { z } from "zod";
 import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
-/** Return the non-negative byte distance between hexadecimal addresses. */
-export const addressDistance = (start, end) => Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));
+/** Return a bounded byte distance between canonical addresses in one space. */
+export const addressDistance = (start, end) => {
+    const left = addressCoordinate(start);
+    const right = addressCoordinate(end);
+    if (left === null || right === null || left.space !== right.space)
+        return 0;
+    const distance = right.offset - left.offset;
+    if (distance <= 0n)
+        return 0;
+    return Number(distance > BigInt(Number.MAX_SAFE_INTEGER)
+        ? BigInt(Number.MAX_SAFE_INTEGER)
+        : distance);
+};
+const addressCoordinate = (value) => {
+    const separator = value.lastIndexOf(":0x");
+    const space = separator < 0 ? "default" : value.slice(0, separator);
+    const offset = separator < 0 ? value : value.slice(separator + 1);
+    if (!/^0x[0-9a-f]+$/u.test(offset))
+        return null;
+    return { space, offset: BigInt(offset) };
+};
 const procedureMapSchema = z.record(z.string(), z.string());
 const addressedNamesSchema = z.array(z.object({ address: z.string(), name: z.string() }));
 const addressedNameMapSchema = z.record(z.string(), z.string());
@@ -39,16 +58,28 @@ const addressedPageSchema = z
         });
     }
 });
-const unavailableSchema = z
+const unavailableAnalysisFactSchema = z
     .object({ available: z.literal(false), reason: z.string() })
     .strict();
-const procedureIdentitySchema = z
-    .object({ address: z.string(), name: z.string() })
+export const procedureClassificationSchema = z
+    .object({
+    external: z.boolean(),
+    thunk: z.boolean(),
+    thunk_target: z.string().nullable(),
+    provenance: z.string().min(1),
+})
+    .strict();
+export const procedureIdentitySchema = z
+    .object({
+    address: z.string(),
+    name: z.string(),
+    classification: procedureClassificationSchema.nullable().default(null),
+})
     .strict();
-const localVariableSchema = z
+export const localVariableSchema = z
     .object({
     description: z.string(),
-    provenance: z.literal("hopper-public-python-api"),
+    provenance: z.string().min(1),
 })
     .strict();
 const boundedSchema = (item) => z
@@ -83,13 +114,37 @@ const boundedSchema = (item) => z
         });
     }
 });
+const availableReferenceKindSchema = z
+    .object({
+    available: z.literal(true),
+    provenance: z.string().min(1),
+    type: z.string(),
+    flow: z.boolean(),
+    call: z.boolean(),
+    jump: z.boolean(),
+    data: z.boolean(),
+    read: z.boolean(),
+    write: z.boolean(),
+    indirect: z.boolean(),
+    computed: z.boolean(),
+    conditional: z.boolean(),
+    terminal: z.boolean(),
+    primary: z.boolean(),
+    operand_index: z.number().int(),
+    external: z.boolean(),
+})
+    .strict();
+export const referenceKindSchema = z.discriminatedUnion("available", [
+    unavailableAnalysisFactSchema,
+    availableReferenceKindSchema,
+]);
 const referenceEdgeSchema = z
     .object({
     source_address: z.string(),
     target_address: z.string(),
     source_procedure: procedureIdentitySchema.nullable(),
     target_procedure: procedureIdentitySchema.nullable(),
-    kind: unavailableSchema,
+    kind: referenceKindSchema,
 })
     .strict();
 export const functionDossierSchema = z
@@ -98,6 +153,7 @@ export const functionDossierSchema = z
         .object({
         address: z.string(),
         name: z.string(),
+        classification: procedureClassificationSchema.nullable().default(null),
         signature: z.string().nullable(),
         locals: z.array(localVariableSchema),
     })
@@ -170,9 +226,10 @@ export const functionDossierSchema = z
     instruction_scan: z
         .object({ scanned: z.number().int().min(0), truncated: z.boolean() })
         .strict(),
+    limitations: z.array(z.string()).default([]),
 })
     .strict();
-/** Strictly parse a complete Hopper function dossier at the provider boundary. */
+/** Strictly parse a complete provider-neutral function dossier. */
 export const parseFunctionDossier = (value) => {
     const parsed = functionDossierSchema.safeParse(value);
     return parsed.success