rea-agents 2.4.0 → 2.5.0

package/dist/contracts/toolOutputSchemaGroups.js

@@ -2,9 +2,10 @@ import { z } from "zod";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
 import { residualUnknownSchema } from "../domain/residualUnknown.js";
-import { referenceKindSchema } from "../domain/hopperValues.js";
+import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
 import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
 import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
 import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
 import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
@@ -20,7 +21,7 @@ import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCor
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { addressList, analysisActivity, addressedEntry, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -43,6 +44,18 @@ export const officialOutputSchemas = {
     procedure_callees: resultOf(addressList),
     procedure_callers: resultOf(addressList),
     procedure_info: procedureInfoOutput,
+    read_function_instructions: resultOf(functionInstructionWindowSchema),
+    read_bytes: resultOf(z.object({
+        address: z.string(),
+        requested_bytes: z.number().int().min(1).max(4_096),
+        returned_bytes: z.number().int().min(0).max(4_096),
+        bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
+        complete: z.boolean(),
+    })),
+    address_to_file_offset: resultOf(z.object({
+        address: z.string(),
+        file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    })),
     procedure_references: resultOf(z.object({
         procedure: procedureIdentity,
         direction: z.enum(["incoming", "outgoing"]),
@@ -69,6 +82,55 @@ export const officialOutputSchemas = {
     unset_bookmark: resultOf(z.boolean()),
     xrefs: resultOf(addressList),
 };
+const literalTraceOutput = resultOf(z.object({
+    query: z.string(),
+    search_mode: z.literal("literal"),
+    operations_used: z.number().int().min(0),
+    operation_budget: z.number().int().min(1),
+    matches: z.array(z.object({
+        type: z.enum(["string", "procedure"]),
+        address: z.string(),
+        value: z.string(),
+    })),
+    references: z.array(z.object({
+        target_address: z.string(),
+        source_address: z.string(),
+        containing_procedure: containingProcedureResolution,
+    })),
+    truncated: z.boolean(),
+    residual_unknowns: z.array(z.string()),
+}));
+const callPathTraceOutput = resultOf(z.object({
+    start: z.string(),
+    goal: z.string().nullable(),
+    direction: z.enum(["forward", "backward"]),
+    goal_status: z.enum(["not_requested", "reached", "not_reached"]),
+    nodes: z.array(z.object({
+        address: z.string(),
+        depth: z.number().int().min(0),
+    })),
+    edges: z.array(z.object({
+        source_address: z.string(),
+        target_address: z.string(),
+        discovery_depth: z.number().int().min(1),
+    })),
+    traversal_path: z.array(z.string()),
+    failures: z.array(z.object({
+        address: z.string(),
+        error: analysisErrorProjectionSchema,
+    })),
+    frontier: z.array(z.string()),
+    limits: z.object({
+        max_depth: z.number().int().min(1),
+        max_nodes: z.number().int().min(1),
+        max_operations: z.number().int().min(1),
+        nodes_visited: z.number().int().min(1),
+        operations_used: z.number().int().min(0),
+    }),
+    truncated: z.boolean(),
+    residual_unknowns: z.array(z.string()),
+    limitations: z.array(z.string()),
+}));
 /** Exact structured-content schemas for composed analysis workflows. */
 export const enhancedOutputSchemas = {
     swift_classes: symbolDiscoveryOutput("classes"),
@@ -126,24 +188,9 @@ export const enhancedOutputSchemas = {
         string_count: z.number().int().min(0),
     })),
     analyze_function: functionDossierOutput,
-    trace_feature: resultOf(z.object({
-        query: z.string(),
-        search_mode: z.literal("literal"),
-        operations_used: z.number().int().min(0),
-        operation_budget: z.number().int().min(1),
-        matches: z.array(z.object({
-            type: z.enum(["string", "procedure"]),
-            address: z.string(),
-            value: z.string(),
-        })),
-        references: z.array(z.object({
-            target_address: z.string(),
-            source_address: z.string(),
-            containing_procedure: containingProcedureResolution,
-        })),
-        truncated: z.boolean(),
-        residual_unknowns: z.array(z.string()),
-    })),
+    trace_feature: literalTraceOutput,
+    find_code_for_string: literalTraceOutput,
+    trace_call_path: callPathTraceOutput,
 };
 /** Exact Evidence v2 schemas for provider-neutral native inspection. */
 export const nativeOutputSchemas = {
@@ -156,6 +203,7 @@ export const nativeOutputSchemas = {
 /** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
 export const artifactOutputSchemas = {
     inventory_artifact: resultOf(artifactInventoryResultSchema),
+    inspect_artifact: resultOf(artifactInspectionResultSchema),
     extract_artifact: resultOf(artifactExtractionResultSchema),
 };
 /** Exact Evidence v2 schema for execution-free managed static analysis. */
@@ -210,6 +258,7 @@ export const sessionOutputSchemas = {
                 reasons: z.array(z.string()),
                 remediation: z.string().nullable(),
             }),
+            analysis_activity: analysisActivity,
             recommended_actions: z.array(z.string()),
         }),
         z.object({
@@ -226,6 +275,7 @@ export const sessionOutputSchemas = {
                 next_cursor: z.number().int().min(0).nullable(),
                 has_more: z.boolean(),
             }),
+            client_features: clientFeatureAvailabilitySchema,
         }),
         z.union([
             sessionProvider.extend({

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -111,6 +111,22 @@ const analysisRun = z
     ]),
 })
     .nullable();
+export const analysisActivity = z.object({
+    status: z.enum(["not_observed", "idle", "busy", "timed_out_busy"]),
+    providers: z.array(z.object({
+        provider: providerIdentity,
+        active: z
+            .object({
+            request_id: z.number().int().min(1),
+            operation: z.string().min(1),
+            elapsed_ms: z.number().int().min(0),
+            timeout_ms: z.number().int().min(0),
+            caller_state: z.enum(["waiting", "timed_out", "cancelled"]),
+        })
+            .nullable(),
+        queued_requests: z.number().int().min(0),
+    })),
+});
 const providerRejectionCode = z.enum(PROVIDER_REJECTION_CODES);
 const providerDiagnostics = z.record(z.string(), z.json());
 const providerAvailability = z.discriminatedUnion("status", [
@@ -153,12 +169,26 @@ const providerTargetSupport = z.discriminatedUnion("status", [
         diagnostics: providerDiagnostics,
     }),
 ]);
+const clientFeatureNameSchema = z.enum([
+    "elicitation_form",
+    "elicitation_url",
+    "roots",
+    "sampling",
+]);
+/** Negotiated MCP client features that affect REA workflow availability. */
+export const clientFeatureAvailabilitySchema = z.object({
+    elicitation_form: z.boolean(),
+    elicitation_url: z.boolean(),
+    roots: z.boolean(),
+    sampling: z.boolean(),
+});
 export const toolAvailability = z.object({
     name: z.string(),
     surface: z.string(),
     available: z.boolean(),
     reason: z.enum([
         "available",
+        "client_capability_missing",
         "target_required",
         "provider_missing",
         "provider_unavailable",
@@ -167,6 +197,12 @@ export const toolAvailability = z.object({
         "policy_disabled",
     ]),
     remediation: z.string().nullable(),
+    client_requirements: z.object({
+        required: z.array(clientFeatureNameSchema),
+        optional: z.array(clientFeatureNameSchema),
+        missing_required: z.array(clientFeatureNameSchema),
+        missing_optional: z.array(clientFeatureNameSchema),
+    }),
     effects: z.strictObject({
         mutatesTarget: z.boolean(),
         mutatesSession: z.boolean(),
@@ -189,6 +225,7 @@ export const sessionProvider = z.object({
     providers: z.array(providerIdentity),
     capabilities: z.array(providerCapability),
     analysis_run: analysisRun,
+    analysis_activity: analysisActivity,
     analysis_provider_binding: z
         .object({
         provider: providerIdentity,

package/dist/domain/analysisErrorProjection.js

@@ -21,6 +21,8 @@ export const projectAnalysisError = (error) => {
     };
 };
 const errorCode = (error) => {
+    if (error.cleanupIncomplete)
+        return "cleanup_incomplete";
     if (error instanceof ReplayPlanStaleError)
         return "plan_stale";
     if (error instanceof PermissionRequiredError)
@@ -221,6 +223,12 @@ const providerErrorDetails = (error) => {
         return {
             provider_id: error.providerId,
             operation: error.operation,
+            ...(error.cleanupIncomplete
+                ? {
+                    cleanup: "incomplete",
+                    resources: [...error.cleanupResources],
+                }
+                : {}),
             ...(error.diagnostics === undefined
                 ? {}
                 : { diagnostics: error.diagnostics }),

package/dist/domain/artifactInspection.js

@@ -0,0 +1,347 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { artifactInventoryResultSchema, } from "./artifactGraph.js";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { jsonValueSchema } from "./jsonValue.js";
+const boundedTextSchema = z.string().min(1).max(4_096);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u);
+const inspectionLimitsSchema = z.strictObject({
+    max_observations: z.number().int().min(1).max(500).default(100),
+    max_relationships: z.number().int().min(1).max(500).default(100),
+    max_hypotheses: z.number().int().min(1).max(100).default(20),
+    max_unexplored_branches: z.number().int().min(1).max(100).default(20),
+    max_next_probes: z.number().int().min(1).max(50).default(20),
+    max_substeps: z.literal(1).default(1),
+});
+export const artifactInspectionLimitsSchema = inspectionLimitsSchema;
+const inspectionObservationSchema = z.strictObject({
+    observation_id: z.string().regex(/^aio_[a-f0-9]{64}$/u),
+    kind: z.enum(["root-manifest", "artifact", "occurrence", "integrity"]),
+    subject: boundedTextSchema,
+    value: jsonValueSchema,
+    evidence_id: evidenceIdSchema,
+});
+const inspectionRelationshipSchema = z.strictObject({
+    relationship_id: z.string().regex(/^air_[a-f0-9]{64}$/u),
+    relation: z.enum([
+        "contains",
+        "extracts",
+        "slice-of",
+        "embeds",
+        "loads",
+        "maps-source",
+        "derived-from",
+    ]),
+    source_artifact_id: artifactIdSchema,
+    target_artifact_id: artifactIdSchema,
+    occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),
+    logical_path: boundedTextSchema.nullable(),
+    evidence_id: evidenceIdSchema,
+});
+const inspectionHypothesisSchema = z.strictObject({
+    hypothesis_id: z.string().regex(/^aih_[a-f0-9]{64}$/u),
+    statement: boundedTextSchema,
+    confidence: z.enum(["medium", "low"]),
+    basis_evidence_ids: z.array(evidenceIdSchema).min(1).max(8),
+    limitation: boundedTextSchema,
+});
+const inspectionContradictionSchema = z.strictObject({
+    contradiction_id: z.string().regex(/^aic_[a-f0-9]{64}$/u),
+    statement: boundedTextSchema,
+    occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),
+    declared_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    observed_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    evidence_id: evidenceIdSchema,
+});
+const nextProbeSchema = z.strictObject({
+    operation: z.string().min(1).max(128),
+    rationale: boundedTextSchema,
+    authority: z.enum([
+        "artifact-bytes",
+        "managed-static-analysis",
+        "native-analysis-provider",
+        "ast-static-analysis",
+    ]),
+});
+const unexploredBranchSchema = z.strictObject({
+    branch_id: z.string().regex(/^aib_[a-f0-9]{64}$/u),
+    reason: z.enum([
+        "page-limit",
+        "format-specific-analysis-required",
+        "unknown-format",
+    ]),
+    detail: boundedTextSchema,
+    next_probe: nextProbeSchema.nullable(),
+    evidence_id: evidenceIdSchema,
+});
+/** Provider-neutral inspection result with its atomic source Evidence. */
+export const artifactInspectionResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    inspection_id: z.string().regex(/^ai_[a-f0-9]{64}$/u),
+    subject: z.strictObject({
+        manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+        root_artifact_id: artifactIdSchema,
+        root_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        root_format: z.string().min(1).max(128),
+    }),
+    substeps: z
+        .array(z.strictObject({
+        substep_id: z.string().regex(/^ais_[a-f0-9]{64}$/u),
+        operation: z.literal("inventory_artifact"),
+        status: z.literal("completed"),
+        evidence_id: evidenceIdSchema,
+        evidence: evidenceSchema,
+    }))
+        .min(1)
+        .max(1),
+    observations: z.array(inspectionObservationSchema).max(500),
+    derived_relationships: z.array(inspectionRelationshipSchema).max(500),
+    hypotheses: z.array(inspectionHypothesisSchema).max(100),
+    contradictions: z.array(inspectionContradictionSchema).max(100),
+    unexplored_branches: z.array(unexploredBranchSchema).max(100),
+    next_probes: z.array(nextProbeSchema).max(50),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-substeps", "partial", "truncated"]),
+        substeps_completed: z.literal(1),
+        observations_retained: z.number().int().min(0),
+        observations_omitted: z.number().int().min(0),
+        relationships_retained: z.number().int().min(0),
+        relationships_omitted: z.number().int().min(0),
+        hypotheses_retained: z.number().int().min(0),
+        hypotheses_omitted: z.number().int().min(0),
+        unexplored_branches_retained: z.number().int().min(0),
+        unexplored_branches_omitted: z.number().int().min(0),
+        next_probes_retained: z.number().int().min(0),
+        next_probes_omitted: z.number().int().min(0),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(1),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});
+/** Project one successful inventory Evidence record into an inspection report. */
+export const createArtifactInspection = (inventoryInput, limits) => {
+    const inventoryEvidence = parseInventoryEvidence(inventoryInput);
+    const inventory = artifactInventoryResultSchema.parse(inventoryEvidence.normalized_result);
+    const observations = allObservations(inventory, inventoryEvidence.evidence_id);
+    const relationships = allRelationships(inventory, inventoryEvidence.evidence_id);
+    const hypotheses = allHypotheses(inventory, inventoryEvidence.evidence_id);
+    const nextProbes = probesFor(inventory);
+    const branches = allUnexploredBranches(inventory, inventoryEvidence.evidence_id, nextProbes);
+    const retained = {
+        observations: observations.slice(0, limits.max_observations),
+        relationships: relationships.slice(0, limits.max_relationships),
+        hypotheses: hypotheses.slice(0, limits.max_hypotheses),
+        branches: branches.slice(0, limits.max_unexplored_branches),
+        probes: nextProbes.slice(0, limits.max_next_probes),
+    };
+    const omissions = {
+        observations: observations.length - retained.observations.length,
+        relationships: relationships.length - retained.relationships.length,
+        hypotheses: hypotheses.length - retained.hypotheses.length,
+        branches: branches.length - retained.branches.length,
+        probes: nextProbes.length - retained.probes.length,
+    };
+    const semantic = {
+        schema_version: 1,
+        subject: {
+            manifest_id: inventory.manifest.manifest_id,
+            root_artifact_id: inventory.manifest.root_artifact_id,
+            root_sha256: inventory.manifest.root_sha256,
+            root_format: inventory.manifest.root_format,
+        },
+        substeps: [
+            {
+                substep_id: `ais_${digestCanonical({
+                    operation: "inventory_artifact",
+                    evidence_id: inventoryEvidence.evidence_id,
+                })}`,
+                operation: "inventory_artifact",
+                status: "completed",
+                evidence_id: inventoryEvidence.evidence_id,
+                evidence: inventoryEvidence,
+            },
+        ],
+        observations: retained.observations,
+        derived_relationships: retained.relationships,
+        hypotheses: retained.hypotheses,
+        contradictions: contradictions(inventory, inventoryEvidence.evidence_id),
+        unexplored_branches: retained.branches,
+        next_probes: retained.probes,
+        coverage: {
+            status: inspectionCoverage(inventory, omissions),
+            substeps_completed: 1,
+            observations_retained: retained.observations.length,
+            observations_omitted: omissions.observations,
+            relationships_retained: retained.relationships.length,
+            relationships_omitted: omissions.relationships,
+            hypotheses_retained: retained.hypotheses.length,
+            hypotheses_omitted: omissions.hypotheses,
+            unexplored_branches_retained: retained.branches.length,
+            unexplored_branches_omitted: omissions.branches,
+            next_probes_retained: retained.probes.length,
+            next_probes_omitted: omissions.probes,
+        },
+        evidence_links: [inventoryEvidence.evidence_id],
+        limitations: uniqueSorted([
+            ...inventory.limitations,
+            "Inspection derives bounded static hypotheses and next probes; it does not execute the artifact or claim format-specific semantics.",
+        ]),
+    };
+    return artifactInspectionResultSchema.parse({
+        ...semantic,
+        inspection_id: `ai_${digestCanonical(semantic)}`,
+    });
+};
+const parseInventoryEvidence = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation !== "inventory_artifact")
+        throw new TypeError("Artifact inspection substep requires inventory_artifact Evidence");
+    return evidence;
+};
+const allObservations = (inventory, evidenceId) => [
+    observation("root-manifest", inventory.manifest.root_artifact_id, inventory.manifest, evidenceId),
+    ...inventory.nodes.items.map((node) => observation("artifact", node.artifact_id, node, evidenceId)),
+    ...inventory.occurrences.items.map((occurrence) => observation("occurrence", occurrence.occurrence_id, occurrence, evidenceId)),
+    ...inventory.integrity_contradictions.map((value) => observation("integrity", value.contradiction_id, value, evidenceId)),
+];
+const observation = (kind, subject, value, evidenceId) => {
+    const semantic = {
+        kind,
+        subject,
+        value: jsonValueSchema.parse(value),
+        evidence_id: evidenceId,
+    };
+    return { observation_id: `aio_${digestCanonical(semantic)}`, ...semantic };
+};
+const allRelationships = (inventory, evidenceId) => inventory.edges.items.map((edge) => {
+    const semantic = {
+        relation: edge.relation,
+        source_artifact_id: edge.parent_artifact_id,
+        target_artifact_id: edge.child_artifact_id,
+        occurrence_id: edge.occurrence_id,
+        logical_path: edge.logical_path,
+        evidence_id: evidenceId,
+    };
+    return {
+        relationship_id: `air_${digestCanonical(semantic)}`,
+        ...semantic,
+    };
+});
+const allHypotheses = (inventory, evidenceId) => {
+    const statements = inventory.manifest.root_format === "pe"
+        ? [
+            "The PE artifact may contain managed CLI metadata or native code; inventory bytes alone do not distinguish them.",
+        ]
+        : ["asar", "javascript-bundle"].includes(inventory.manifest.root_format)
+            ? [
+                "The artifact may contain a recoverable JavaScript application graph.",
+            ]
+            : [];
+    return statements.map((statement) => {
+        const semantic = {
+            statement,
+            confidence: "low",
+            basis_evidence_ids: [evidenceId],
+            limitation: "Format classification proposes a bounded follow-up; it is not semantic proof.",
+        };
+        return { hypothesis_id: `aih_${digestCanonical(semantic)}`, ...semantic };
+    });
+};
+const contradictions = (inventory, evidenceId) => inventory.integrity_contradictions.map((value) => {
+    const semantic = {
+        statement: `Declared integrity for ${value.logical_path} contradicts observed bytes.`,
+        occurrence_id: value.occurrence_id,
+        declared_sha256: value.declared_sha256,
+        observed_sha256: value.observed_sha256,
+        evidence_id: evidenceId,
+    };
+    return {
+        contradiction_id: `aic_${digestCanonical(semantic)}`,
+        ...semantic,
+    };
+});
+const probesFor = (inventory) => {
+    const format = inventory.manifest.root_format;
+    if (["asar", "javascript-bundle", "directory"].includes(format))
+        return [
+            {
+                operation: "analyze_javascript_application",
+                rationale: "Recover bounded JavaScript modules, source maps, Electron boundaries, and application relationships.",
+                authority: "ast-static-analysis",
+            },
+        ];
+    if (format === "pe")
+        return [
+            {
+                operation: "inspect_managed_artifact",
+                rationale: "Check execution-free CLI metadata before choosing a deep native provider.",
+                authority: "managed-static-analysis",
+            },
+            {
+                operation: "open_binary",
+                rationale: "Open as native code only when managed inspection reports a native or mixed boundary.",
+                authority: "native-analysis-provider",
+            },
+        ];
+    if (["mach-o", "mach-o-universal", "elf"].includes(format))
+        return [
+            {
+                operation: "open_binary",
+                rationale: "Bind one deep native provider before function-level analysis.",
+                authority: "native-analysis-provider",
+            },
+        ];
+    if (format === "plist")
+        return [
+            {
+                operation: "inspect_plist",
+                rationale: "Parse property-list values without executing the artifact.",
+                authority: "artifact-bytes",
+            },
+        ];
+    return [];
+};
+const allUnexploredBranches = (inventory, evidenceId, nextProbes) => {
+    const pages = [
+        ["nodes", inventory.nodes.next_offset],
+        ["occurrences", inventory.occurrences.next_offset],
+        ["relationships", inventory.edges.next_offset],
+    ];
+    const branches = pages.flatMap(([collection, nextOffset]) => nextOffset === null
+        ? []
+        : [
+            branch("page-limit", `${collection} continue at offset ${String(nextOffset)}.`, null, evidenceId),
+        ]);
+    branches.push(...nextProbes.map((probe) => branch("format-specific-analysis-required", `${probe.operation} was not run by provider-neutral artifact inspection.`, probe, evidenceId)));
+    if (inventory.manifest.root_format === "unknown")
+        branches.push(branch("unknown-format", "Artifact bytes did not match an admitted format classifier.", null, evidenceId));
+    return branches;
+};
+const branch = (reason, detail, nextProbe, evidenceId) => {
+    const semantic = {
+        reason,
+        detail,
+        next_probe: nextProbe,
+        evidence_id: evidenceId,
+    };
+    return { branch_id: `aib_${digestCanonical(semantic)}`, ...semantic };
+};
+const inspectionCoverage = (inventory, omissions) => {
+    if (Object.values(omissions).some((count) => count > 0))
+        return "truncated";
+    return [
+        inventory.nodes.next_offset,
+        inventory.occurrences.next_offset,
+        inventory.edges.next_offset,
+    ].some((offset) => offset !== null)
+        ? "partial"
+        : "complete-within-substeps";
+};
+const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Artifact inspection could not canonicalize");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);

package/dist/domain/browserCaptureComparison.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { browserScenarioDiffSchema, compareBrowserScenarios, compareBrowserScenariosInputSchema, } from "./browserScenarioDiff.js";
+import { compareWebCaptures, captureSnapshotSchema, webCaptureDiffSchema, } from "./webCaptureDiff.js";
+/** Top-level MCP shape for legacy page or step-indexed scenario comparison. */
+export const browserCaptureComparisonWireSchema = z
+    .strictObject({
+    before: captureSnapshotSchema
+        .optional()
+        .describe("Earlier passive web-page capture; pair with after."),
+    after: captureSnapshotSchema
+        .optional()
+        .describe("Later passive web-page capture; pair with before."),
+    before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario
+        .optional()
+        .describe("Earlier browser scenario capture; pair with after_scenario."),
+    after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario
+        .optional()
+        .describe("Later browser scenario capture; pair with before_scenario."),
+    normalization: compareBrowserScenariosInputSchema.shape.normalization.describe("Scenario-only exact-literal normalization policy."),
+    max_changes: z
+        .number()
+        .int()
+        .min(1)
+        .max(20_000)
+        .default(2_000)
+        .describe("Maximum normalized change records to retain."),
+})
+    .superRefine((input, context) => {
+    const hasPassive = input.before !== undefined || input.after !== undefined;
+    const hasScenario = input.before_scenario !== undefined || input.after_scenario !== undefined;
+    if (hasPassive === hasScenario)
+        context.addIssue({
+            code: "custom",
+            message: "Provide exactly one complete pair: before/after or before_scenario/after_scenario",
+        });
+    if (hasPassive && (input.before === undefined || input.after === undefined))
+        context.addIssue({
+            code: "custom",
+            message: "Passive comparison requires both before and after",
+        });
+    if (hasScenario &&
+        (input.before_scenario === undefined ||
+            input.after_scenario === undefined))
+        context.addIssue({
+            code: "custom",
+            message: "Browser scenario comparison requires both before_scenario and after_scenario",
+        });
+    if (hasPassive && input.normalization.rules.length > 0)
+        context.addIssue({
+            code: "custom",
+            path: ["normalization"],
+            message: "Literal normalization rules apply only to browser scenario captures",
+        });
+});
+/** Parsed legacy page snapshots or step-indexed browser scenarios. */
+export const browserCaptureComparisonInputSchema = browserCaptureComparisonWireSchema.transform((input) => {
+    if (input.before_scenario !== undefined &&
+        input.after_scenario !== undefined)
+        return {
+            before_scenario: input.before_scenario,
+            after_scenario: input.after_scenario,
+            normalization: input.normalization,
+            max_changes: input.max_changes,
+        };
+    if (input.before !== undefined && input.after !== undefined)
+        return {
+            before: input.before,
+            after: input.after,
+            max_changes: input.max_changes,
+        };
+    throw new TypeError("Capture comparison pair refinement failed");
+});
+/** Result from passive page or browser scenario comparison. */
+export const browserCaptureComparisonSchema = z.union([
+    browserScenarioDiffSchema,
+    webCaptureDiffSchema,
+]);
+/** Dispatch a parsed capture comparison to its pure domain comparator. */
+export const compareBrowserCaptures = (input) => isScenarioComparison(input)
+    ? compareBrowserScenarios(input)
+    : compareWebCaptures(input);
+const isScenarioComparison = (input) => "before_scenario" in input;