rea-agents 2.2.0 → 2.3.0

package/dist/cliSetup.js

@@ -1,4 +1,5 @@
 import { cancel, confirm, intro, isCancel, multiselect, outro, } from "@clack/prompts";
+import { projectDoctorReport } from "./application/DoctorProjection.js";
 import { SUPPORTED_CLIENT_DEFINITIONS } from "./application/SupportedClients.js";
 const clientDisplayNames = new Map(SUPPORTED_CLIENT_DEFINITIONS.map(({ name, displayName }) => [
     name,
@@ -10,7 +11,7 @@ const promptStreams = {
     withGuide: true,
 };
 const agentIntegrationCapabilityId = "agent_integration";
-/** Run the inline setup picker, exact preflight, and default-No consent. */
+/** Run the inline setup picker, exact preflight, and explicit consent. */
 export const confirmInteractiveSetup = async (actions, accessible) => {
     intro("REA setup", promptStreams);
     renderValueIntroduction();
@@ -31,7 +32,7 @@ export const confirmInteractiveSetup = async (actions, accessible) => {
         message: selectedActions.length === 1
             ? "Apply this change?"
             : `Apply these ${String(selectedActions.length)} changes?`,
-        initialValue: false,
+        initialValue: true,
         active: "Yes, apply",
         inactive: "No, cancel",
     });
@@ -77,10 +78,7 @@ export const conciseSetupResult = (result) => ({
     plannedActions: result.plannedActions,
     appliedActions: result.appliedActions,
     clients: result.clients,
-    doctor: {
-        healthy: result.doctor.healthy,
-        checks: result.doctor.checks.filter(({ ok }) => !ok),
-    },
+    doctor: projectDoctorReport(result.doctor, "summary"),
     ...(result.code === undefined ? {} : { code: result.code }),
     ...(result.remediation === undefined
         ? {}
@@ -90,9 +88,10 @@ const selectSetupActions = async (actions, accessible) => {
     const clientActions = actions.filter(({ kind }) => kind === "configure_client");
     const componentActions = actions.filter(({ kind }) => kind !== "configure_client");
     const capabilities = setupCapabilities(clientActions, componentActions);
+    const preselectedCapabilityIds = defaultCapabilityIds(capabilities);
     const selectedCapabilities = accessible
-        ? await selectCapabilitiesAccessibly(capabilities)
-        : await selectCapabilities(capabilities);
+        ? await selectCapabilitiesAccessibly(capabilities, preselectedCapabilityIds)
+        : await selectCapabilities(capabilities, preselectedCapabilityIds);
     if (selectedCapabilities === undefined)
         return undefined;
     const selectedCapabilityIds = new Set(selectedCapabilities);
@@ -102,24 +101,30 @@ const selectSetupActions = async (actions, accessible) => {
         .map(({ id }) => id);
     if (!selectedCapabilityIds.has(agentIntegrationCapabilityId))
         return selectedActionIds;
+    const bundledSkillId = bundledSkillAction === undefined ? undefined : bundledSkillAction.id;
     if (clientActions.length === 0)
         return [
-            ...(bundledSkillAction === undefined ? [] : [bundledSkillAction.id]),
+            ...(bundledSkillId === undefined ? [] : [bundledSkillId]),
             ...selectedActionIds,
         ];
+    const preselectedClientIds = clientActions.map(({ id }) => id);
     const selectedClients = accessible
-        ? await selectClientsAccessibly(clientActions)
-        : await selectClients(clientActions);
+        ? await selectClientsAccessibly(clientActions, preselectedClientIds)
+        : await selectClients(clientActions, preselectedClientIds);
     if (selectedClients === undefined)
         return undefined;
-    if (selectedClients.length === 0)
-        return selectedActionIds;
     return [
         ...selectedClients,
-        ...(bundledSkillAction === undefined ? [] : [bundledSkillAction.id]),
+        ...(bundledSkillId === undefined ? [] : [bundledSkillId]),
         ...selectedActionIds,
     ];
 };
+const defaultCapabilityIds = (capabilities) => {
+    const hasAgentIntegration = capabilities.some(({ id }) => id === agentIntegrationCapabilityId);
+    if (!hasAgentIntegration)
+        return [];
+    return [agentIntegrationCapabilityId];
+};
 const setupCapabilities = (clientActions, componentActions) => [
     ...(clientActions.length === 0 &&
         !componentActions.some(({ kind }) => kind === "install_skill")
@@ -141,7 +146,7 @@ const setupCapabilities = (clientActions, componentActions) => [
         hint: `${action.operation} · ${action.target}`,
     })),
 ];
-const selectCapabilities = async (capabilities) => {
+const selectCapabilities = async (capabilities, initialValues) => {
     const selection = await multiselect({
         ...promptStreams,
         message: "What should REA set up?",
@@ -150,19 +155,21 @@ const selectCapabilities = async (capabilities) => {
             label: capability.label,
             hint: capability.hint,
         })),
+        initialValues: [...initialValues],
         required: false,
         maxItems: Math.max(3, Math.min(capabilities.length, (process.stderr.rows ?? 24) - 8)),
         showInstructions: true,
     });
     return isCancel(selection) ? undefined : selection;
 };
-const selectCapabilitiesAccessibly = async (capabilities) => {
+const selectCapabilitiesAccessibly = async (capabilities, preselectedIds) => {
+    const preselected = new Set(preselectedIds);
     const selected = [];
     for (const capability of capabilities) {
         const included = await confirm({
             ...promptStreams,
             message: `Set up ${capability.label}? ${capability.hint}`,
-            initialValue: false,
+            initialValue: preselected.has(capability.id),
             vertical: true,
         });
         if (isCancel(included))
@@ -172,28 +179,30 @@ const selectCapabilitiesAccessibly = async (capabilities) => {
     }
     return selected;
 };
-const selectClients = async (actions) => {
+const selectClients = async (actions, initialValues) => {
     const selection = await multiselect({
         ...promptStreams,
         message: "Which agents should use REA?",
         options: actions.map((action) => ({
             value: action.id,
             label: `${action.label} (detected)`,
-            hint: `${action.operation} · ${action.target}`,
+            hint: `Configure the REA MCP server for ${action.label}`,
         })),
+        initialValues: [...initialValues],
         required: false,
         maxItems: Math.max(3, Math.min(actions.length, (process.stderr.rows ?? 24) - 8)),
         showInstructions: true,
     });
     return isCancel(selection) ? undefined : selection;
 };
-const selectClientsAccessibly = async (actions) => {
+const selectClientsAccessibly = async (actions, initialValues) => {
+    const preselected = new Set(initialValues);
     const selected = [];
     for (const action of actions) {
         const included = await confirm({
             ...promptStreams,
             message: `Configure ${action.label}? ${action.target}`,
-            initialValue: false,
+            initialValue: preselected.has(action.id),
             vertical: true,
         });
         if (isCancel(included))

package/dist/contracts/applicationToolContracts.js

@@ -1,5 +1,8 @@
-import { applicationVersionComparisonResultSchema, compareApplicationVersionsInputSchema, } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
-import { applicationFeatureTraceResultSchema, traceApplicationFeatureInputSchema, } from "../domain/javascriptFeatureTraceSchemas.js";
+import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationFeatureTraceResultSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticTraceResultSchema } from "../domain/javascriptSemanticTraceSchemas.js";
+import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
+import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "./applicationWorkflowInputContracts.js";
 import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
 import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
 import { reconstructionCoverageCommitInputSchema, reconstructionCoverageCommitOutputSchema, reconstructionCoverageQueryInputSchema, } from "../application/ReconstructionCoverageService.js";
@@ -7,9 +10,11 @@ import { reconstructionClosureResultSchema } from "../domain/reconstructionCover
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
+import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
+const semanticTraceOutputSchema = evidenceResultOf(javaScriptSemanticTraceResultSchema);
 const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
+const exportShapeComparisonOutputSchema = evidenceResultOf(javaScriptExportShapeComparisonResultSchema);
 const HASH = "0".repeat(64);
 const NODE_PREPARATION_EXAMPLE = jsonObjectSchema.parse({
     preparation_approved: true,
@@ -77,9 +82,9 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "trace_application_feature",
         ...toolContractMetadata("trace_application_feature"),
-        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph supplied as full Evidence or an Evidence ID returned earlier in this session. Explicit direction, depth, node, edge, and path bounds apply. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
         kind: "application",
-        inputSchema: traceApplicationFeatureInputSchema,
+        inputSchema: traceApplicationFeatureRequestSchema,
         outputSchema: traceOutputSchema,
         examples: [
             {
@@ -88,12 +93,33 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "trace_javascript_semantics",
+        ...toolContractMetadata("trace_javascript_semantics"),
+        description: "Trace bounded static JavaScript data-flow, direct call/return, and closure relations from authenticated analyze_javascript_application v2 Evidence. Queries declare direction and exact node, relation, depth, function, module, and page limits. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
+        kind: "application",
+        inputSchema: traceJavaScriptSemanticsRequestSchema,
+        outputSchema: semanticTraceOutputSchema,
+        examples: [
+            {
+                title: "Trace backward provenance from one semantic node",
+                input: {
+                    application_evidence_id: `ev_${HASH}`,
+                    query: {
+                        seed: { kind: "semantic-node", node_id: `jsrg_node_${HASH}` },
+                        direction: "backward-provenance",
+                        source_map_authority: { authority: "none" },
+                    },
+                },
+            },
+        ],
+    },
     {
         name: "compare_application_versions",
         ...toolContractMetadata("compare_application_versions"),
-        description: "Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
+        description: "Compare two authenticated JavaScript Application Graph versions supplied as full Evidence or Evidence IDs returned earlier in this session. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
         kind: "application",
-        inputSchema: compareApplicationVersionsInputSchema,
+        inputSchema: compareApplicationVersionsRequestSchema,
         outputSchema: comparisonOutputSchema,
         examples: [
             {
@@ -102,6 +128,20 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "compare_javascript_export_shapes",
+        ...toolContractMetadata("compare_javascript_export_shapes"),
+        description: "Compare bounded static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph, supplied as full Evidence or session Evidence IDs. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes and recommends controlled replay separately without executing JavaScript.",
+        kind: "application",
+        inputSchema: compareJavaScriptExportShapesRequestSchema,
+        outputSchema: exportShapeComparisonOutputSchema,
+        examples: [
+            {
+                title: "Compare one exact parser export without execution",
+                input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
+            },
+        ],
+    },
     {
         name: "run_controlled_replay",
         ...toolContractMetadata("run_controlled_replay"),
@@ -223,3 +263,10 @@ export const APPLICATION_TOOL_CONTRACTS = [
         ],
     },
 ];
+/** Resolve one named application contract without relying on array position. */
+export const applicationToolContract = (name) => {
+    const contract = APPLICATION_TOOL_CONTRACTS.find(({ name: candidate }) => candidate === name);
+    if (contract === undefined)
+        throw new Error(`Missing application tool contract: ${name}`);
+    return contract;
+};

package/dist/contracts/applicationWorkflowInputContracts.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { evidenceSchema } from "../domain/evidence.js";
+import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticQueryInputSchema } from "../domain/javascriptSemanticQuerySchemas.js";
+const evidenceIdSchema = z
+    .string()
+    .regex(/^ev_[a-f0-9]{64}$/u)
+    .describe("Evidence ID returned earlier in this session");
+const requireExactlyOne = (context, fields) => {
+    const [leftName, left, rightName, right] = fields;
+    if ((left === undefined) !== (right === undefined))
+        return;
+    context.addIssue({
+        code: "custom",
+        path: [left === undefined ? leftName : rightName],
+        message: `Supply exactly one of ${leftName} or ${rightName}`,
+    });
+};
+/** MCP/CLI trace request accepting full Evidence or a ledger reference. */
+export const traceApplicationFeatureRequestSchema = z
+    .strictObject({
+    application: evidenceSchema.optional(),
+    application_evidence_id: evidenceIdSchema.optional(),
+    native_observations: traceApplicationFeatureInputSchema.shape.native_observations,
+    native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    seed: traceApplicationFeatureInputSchema.shape.seed,
+    direction: traceApplicationFeatureInputSchema.shape.direction,
+    limits: traceApplicationFeatureInputSchema.shape.limits,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "application",
+        input.application,
+        "application_evidence_id",
+        input.application_evidence_id,
+    ]);
+});
+/** MCP/CLI semantic trace request accepting full Evidence or a ledger reference. */
+export const traceJavaScriptSemanticsRequestSchema = z
+    .strictObject({
+    application: evidenceSchema.optional(),
+    application_evidence_id: evidenceIdSchema.optional(),
+    query: javaScriptSemanticQueryInputSchema,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "application",
+        input.application,
+        "application_evidence_id",
+        input.application_evidence_id,
+    ]);
+});
+/** MCP/CLI comparison request accepting full Evidence or ledger references. */
+export const compareApplicationVersionsRequestSchema = z
+    .strictObject({
+    left: evidenceSchema.optional(),
+    left_evidence_id: evidenceIdSchema.optional(),
+    right: evidenceSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_native_observations: compareApplicationVersionsInputSchema.shape.left_native_observations,
+    left_native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    right_native_observations: compareApplicationVersionsInputSchema.shape.right_native_observations,
+    right_native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    limits: compareApplicationVersionsInputSchema.shape.limits,
+    unknown_registry_approved: compareApplicationVersionsInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "left",
+        input.left,
+        "left_evidence_id",
+        input.left_evidence_id,
+    ]);
+    requireExactlyOne(context, [
+        "right",
+        input.right,
+        "right_evidence_id",
+        input.right_evidence_id,
+    ]);
+});
+/** MCP/CLI export-shape request accepting full Evidence or ledger references. */
+export const compareJavaScriptExportShapesRequestSchema = z
+    .strictObject({
+    left: evidenceSchema.optional(),
+    left_evidence_id: evidenceIdSchema.optional(),
+    right: evidenceSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_module_path: compareJavaScriptExportShapesInputSchema.shape.left_module_path,
+    left_export_name: compareJavaScriptExportShapesInputSchema.shape.left_export_name,
+    right_module_path: compareJavaScriptExportShapesInputSchema.shape.right_module_path,
+    right_export_name: compareJavaScriptExportShapesInputSchema.shape.right_export_name,
+    limits: compareJavaScriptExportShapesInputSchema.shape.limits,
+    unknown_registry_approved: compareJavaScriptExportShapesInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "left",
+        input.left,
+        "left_evidence_id",
+        input.left_evidence_id,
+    ]);
+    requireExactlyOne(context, [
+        "right",
+        input.right,
+        "right_evidence_id",
+        input.right_evidence_id,
+    ]);
+});

package/dist/contracts/electronToolContracts.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
 import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/electronObservation.js";
-import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
+import { analyzeJavaScriptApplicationInputSchema, javaScriptApplicationAnalysisResultV1Schema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
 import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "../domain/javascriptApplicationGraphSchemas.js";
 import { applicationCoverageSchema } from "../domain/javascriptApplicationEvidenceSchemas.js";
 import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeReconciliationSchemas.js";
@@ -17,39 +17,60 @@ export const analyzeJavaScriptApplicationToolInputSchema = analyzeJavaScriptAppl
         .describe("summary returns bounded findings and paged graph resource URIs; full returns the complete graph only when explicitly required"),
 });
 /** Bounded default projection for agent-facing JavaScript application analysis. */
-export const javascriptApplicationAnalysisSummarySchema = javascriptApplicationAnalysisResultSchema.omit({ graph: true }).extend({
-    unknowns: z.array(z.string().min(1).max(4_096)).max(1_000),
-    graph: z.strictObject({
-        graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
-        node_count: z.number().int().min(0),
-        edge_count: z.number().int().min(0),
-        roots: z.strictObject({
-            items: z.array(z.string().regex(/^jag_node_[a-f0-9]{64}$/u)),
-            total: z.number().int().min(0),
-            truncated: z.boolean(),
-        }),
-        node_kinds: z.array(z.strictObject({
-            kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
-            count: z.number().int().min(1),
-        })),
-        top_findings: z.array(z.strictObject({
-            node_id: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
-            kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
-            label: z.string().nullable(),
-            authority: z.string(),
-            state: z.string(),
-            confidence: z.string(),
-            location: z.json(),
-        })),
-        coverage: applicationCoverageSchema,
-        limitations: z.array(z.string()),
-        pages: z.strictObject({
-            nodes: z.string().startsWith("rea://evidence/"),
-            edges: z.string().startsWith("rea://evidence/"),
-            page_limit: z.number().int().min(1).max(500),
-        }),
+const applicationGraphSummarySchema = z.strictObject({
+    graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+    node_count: z.number().int().min(0),
+    edge_count: z.number().int().min(0),
+    roots: z.strictObject({
+        items: z.array(z.string().regex(/^jag_node_[a-f0-9]{64}$/u)),
+        total: z.number().int().min(0),
+        truncated: z.boolean(),
+    }),
+    node_kinds: z.array(z.strictObject({
+        kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+        count: z.number().int().min(1),
+    })),
+    top_findings: z.array(z.strictObject({
+        node_id: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
+        kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+        label: z.string().nullable(),
+        authority: z.string(),
+        state: z.string(),
+        confidence: z.string(),
+        location: z.json(),
+    })),
+    coverage: applicationCoverageSchema,
+    limitations: z.array(z.string()),
+    pages: z.strictObject({
+        nodes: z.string().startsWith("rea://evidence/"),
+        edges: z.string().startsWith("rea://evidence/"),
+        page_limit: z.number().int().min(1).max(500),
     }),
 });
+const semanticGraphSummarySchema = z.strictObject({
+    graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
+    nodes: z.number().int().min(0),
+    relations: z.number().int().min(0),
+    unknown_frontiers: z.number().int().min(0),
+    fingerprints: z.number().int().min(0),
+    coverage: z.enum(["complete", "partial", "unknown", "unavailable"]),
+    query_tool: z.literal("trace_javascript_semantics"),
+});
+const summaryFields = {
+    unknowns: z.array(z.string().min(1).max(4_096)).max(1_000),
+    graph: applicationGraphSummarySchema,
+};
+/** Bounded default projection for agent-facing JavaScript application analysis. */
+export const javascriptApplicationAnalysisSummarySchema = z.discriminatedUnion("schema_version", [
+    javaScriptApplicationAnalysisResultV1Schema
+        .omit({ graph: true })
+        .extend(summaryFields),
+    javaScriptApplicationAnalysisResultV1Schema.omit({ graph: true }).extend({
+        schema_version: z.literal(2),
+        ...summaryFields,
+        semantic_graph: semanticGraphSummarySchema,
+    }),
+]);
 const applicationOutputSchema = evidenceResultOf(z.union([
     javascriptApplicationAnalysisSummarySchema,
     javascriptApplicationAnalysisResultSchema,

package/dist/contracts/javascriptApplicationWorkflowExamples.js

@@ -28,19 +28,42 @@ const reconciliationEvidence = createEvidence(undefined, {
     limitations: reconciliation.limitations,
     evidenceLinks: reconciliation.evidence_links,
 });
-/** Valid public trace request without proprietary artifacts. */
+const EXAMPLE_EVIDENCE_ID = `ev_${"0".repeat(64)}`;
+const SECOND_EXAMPLE_EVIDENCE_ID = `ev_${"1".repeat(64)}`;
+const TRACE_SEED = {
+    kind: "module",
+    value: "renderer.js",
+    match: "exact",
+    case_sensitive: false,
+};
+/** Natural trace request using the Evidence ID returned by its producer. */
 export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
-    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
-    seed: {
-        kind: "module",
-        value: "renderer.js",
-        match: "exact",
-        case_sensitive: false,
-    },
+    application_evidence_id: EXAMPLE_EVIDENCE_ID,
+    seed: TRACE_SEED,
     direction: "both",
 };
-/** Valid static/runtime graph pair demonstrating comparison authority. */
+/** Natural version comparison using two producer-returned Evidence IDs. */
 export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
+    left_evidence_id: EXAMPLE_EVIDENCE_ID,
+    right_evidence_id: SECOND_EXAMPLE_EVIDENCE_ID,
+};
+/** Exact static return-shape comparison using producer-returned Evidence IDs. */
+export const JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE = {
+    left_evidence_id: EXAMPLE_EVIDENCE_ID,
+    right_evidence_id: SECOND_EXAMPLE_EVIDENCE_ID,
+    left_module_path: "parser.mjs",
+    left_export_name: "default",
+    right_module_path: "parser.mjs",
+    right_export_name: "default",
+};
+/** Full-Evidence compatibility fixture used by pure domain and adapter tests. */
+export const JAVASCRIPT_FEATURE_TRACE_FULL_EVIDENCE_EXAMPLE = {
+    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    seed: TRACE_SEED,
+    direction: "both",
+};
+/** Full-Evidence compatibility comparison fixture. */
+export const JAVASCRIPT_VERSION_COMPARISON_FULL_EVIDENCE_EXAMPLE = {
     left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
     right: reconciliationEvidence,
 };

package/dist/contracts/processCaptureExample.js

@@ -55,6 +55,7 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
     ],
     shim_events: [],
     protocol_events: [],
+    replay_transitions: [],
     files_before: [],
     files_after: [],
     filesystem_effects: [],

package/dist/contracts/replayMachineExample.js

@@ -0,0 +1,37 @@
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+/** Minimal login callback accepted by the direct replay-machine contract. */
+export const REPLAY_MACHINE_RUN_EXAMPLE = jsonObjectSchema.parse({
+    machine: {
+        initial_state: "waiting",
+        states: [{ name: "waiting" }, { name: "complete", terminal: true }],
+        transitions: [
+            {
+                id: "accept_callback",
+                from: "waiting",
+                to: "complete",
+                trigger: { protocol: "http", method: "POST", path: "/callback" },
+                captures: [
+                    {
+                        variable: "token",
+                        value: { source: "request_json", path: ["token"] },
+                        sensitive: true,
+                    },
+                ],
+                actions: [{ type: "http_response", status: 204, body: "" }],
+                max_uses: 1,
+            },
+        ],
+        max_transitions: 1,
+    },
+    events: [
+        {
+            protocol: "http",
+            connection: "not_applicable",
+            at_ms: 0,
+            method: "POST",
+            path: "/callback",
+            headers: {},
+            body: '{"token":"opaque"}',
+        },
+    ],
+});

package/dist/contracts/toolContractExamples.js

@@ -2,6 +2,7 @@ import { UNKNOWN_CONTRACT_EXAMPLES } from "./unknownContractExamples.js";
 import { ARTIFACT_COMPARISON_EXAMPLE } from "./artifactComparisonExample.js";
 import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
 import { INVESTIGATION_EXAMPLES } from "./investigationExamples.js";
+import { REPLAY_MACHINE_RUN_EXAMPLE } from "./replayMachineExample.js";
 /** Canonical examples for contracts whose required inputs have no defaults. */
 export const TOOL_EXAMPLE_OVERRIDES = {
     ...UNKNOWN_CONTRACT_EXAMPLES,
@@ -35,6 +36,7 @@ export const TOOL_EXAMPLE_OVERRIDES = {
         executable: "/usr/bin/true",
         working_directory: "/tmp",
     },
+    run_replay_machine: REPLAY_MACHINE_RUN_EXAMPLE,
     compare_process_captures: {
         left_evidence_id: `ev_${"0".repeat(64)}`,
         right_evidence_id: `ev_${"1".repeat(64)}`,

package/dist/contracts/toolContracts.js

@@ -9,6 +9,8 @@ import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
 import { callPathInputSchema } from "../domain/callPath.js";
 import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
+import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
 import { enhancedInputSchemas } from "./enhancedInputs.js";
 import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sessionOutputSchemas, } from "./toolOutputSchemas.js";
 import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
@@ -164,6 +166,7 @@ export const importEvidenceBundleInputSchema = z.strictObject({
 export const processComparisonInputSchema = z.strictObject({
     left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
     right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    trace_spec: processTraceSpecificationSchema.optional(),
     max_capture_age_ms: z.number().int().nonnegative().optional(),
     unknown_registry_approved: z
         .literal(true)
@@ -190,7 +193,7 @@ export const SESSION_TOOL_CONTRACTS = [
     session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
     session("import_evidence_bundle", "Read a bounded local JSON bundle beneath an operator-approved root, validate every Evidence v2 ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
     session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Produces Process Capture v4; legacy v3 captures cannot be upgraded and must be recaptured with this tool. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),
-    session("compare_process_captures", "Compare two compatible Process Capture v4 observations across terminal, interaction, exit, settlement, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Process Capture v3 is unsupported and must be recaptured with capture_process_scenario. Missing or truncated observations are never treated as equivalent.", processComparisonInputSchema),
+    session("compare_process_captures", "Compare two compatible Process Capture v4 observations across terminal, interaction, lifecycle, process, filesystem, command-shim, HTTP, and WebSocket evidence. Optional trace_spec validates exact events against an explicit partial order or finite trace language; concurrency is never inferred from timestamps or broad sorting. Missing, journal-free, or truncated observations are never treated as equivalent.", processComparisonInputSchema),
     session("compare_artifacts", "Compare two bounded sets of inventory_artifact Evidence pages by logical occurrence path, content identity, metadata, and graph relations. Pages must share and satisfy their graph commitment; every delta cites both sets, and gaps yield truncated or unknown, never equivalence.", artifactComparisonInputSchema),
     session("compare_functions", "Compare two explicit bounded sets of analyze_function Evidence pages across identity, exact provider text, calls, references, strings, and address-normalized CFG topology. Missing or provider-incompatible facets remain truncated or unknown; every conclusion cites both Evidence sets.", functionComparisonInputSchema),
     session("compare_bundles", "Compare two canonical Evidence v2 bundles by exact record membership, explicit one-to-one observation pairs, and complete residual-unknown revision histories. Missing bundle members describe omission only, never behavioral equivalence; output is digest-anchored and deterministically paginated.", bundleComparisonInputSchema),
@@ -202,6 +205,7 @@ export const SESSION_TOOL_CONTRACTS = [
     session("record_unknown", "Create one deterministic residual unknown and immutable mutation evidence. Requires approved: true, validates all evidence and relationship references, and rejects duplicate stable identity.", recordUnknownInputSchema),
     session("update_unknown", "Append one immutable full-state revision and mutation evidence. Requires approved: true and exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.", updateUnknownInputSchema),
     session("verify_unknown_resolution", "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", verifyUnknownResolutionInputSchema),
+    session("run_replay_machine", "Evaluate ordered HTTP and WebSocket events directly against one validated finite replay machine without opening sockets or launching a target. Returns every decision, a capture-value-free transition journal, one redacted action table entry per used transition, captured aliases, final state, and exact configured and consumed limits.", replayMachineRunInputSchema),
 ];
 /** Complete ordered public inventory used by registration and verification. */
 export const TOOL_CONTRACTS = [

package/dist/contracts/toolEffects.js

@@ -93,7 +93,10 @@ export const TOOL_EFFECTS = {
     analyze_javascript_application: evidence,
     reconcile_javascript_runtime: evidence,
     trace_application_feature: evidence,
+    trace_javascript_semantics: evidence,
     compare_application_versions: evidence,
+    compare_javascript_export_shapes: evidence,
+    run_replay_machine: effects(),
     run_controlled_replay: effects({
         mutatesSession: true,
         writesFilesystem: true,