rea-agents 1.6.0 → 2.0.0

package/dist/domain/javascriptFeatureTraceSchemas.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { evidenceSchema, providerSchema } from "./evidence.js";
+import { javascriptApplicationGraphSchema } from "./javascriptApplicationGraph.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const edgeIdSchema = z.string().regex(/^jag_edge_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+/** Literal starting point for one bounded application trace. */
+const applicationFeatureSeedSchema = z.strictObject({
+    kind: z.enum([
+        "node-id",
+        "route",
+        "string",
+        "api",
+        "channel",
+        "module",
+        "native-export",
+    ]),
+    value: boundedTextSchema,
+    match: z.enum(["exact", "contains"]).nullable().default(null),
+    case_sensitive: z.boolean().default(false),
+});
+const featureTraceLimitsSchema = z.strictObject({
+    max_seed_matches: z.number().int().min(1).max(1_000).default(25),
+    max_depth: z.number().int().min(0).max(64).default(12),
+    max_nodes: z.number().int().min(1).max(50_000).default(2_000),
+    max_edges: z.number().int().min(1).max(100_000).default(4_000),
+    max_paths: z.number().int().min(1).max(1_000).default(100),
+});
+/** Evidence-backed application graph and explicit trace bounds. */
+export const traceApplicationFeatureInputSchema = z
+    .strictObject({
+    application: evidenceSchema,
+    native_observations: z.array(evidenceSchema).max(64).default([]),
+    seed: applicationFeatureSeedSchema,
+    direction: z.enum(["outgoing", "incoming", "both"]).default("both"),
+    limits: featureTraceLimitsSchema.default({
+        max_seed_matches: 25,
+        max_depth: 12,
+        max_nodes: 2_000,
+        max_edges: 4_000,
+        max_paths: 100,
+    }),
+})
+    .superRefine((input, context) => {
+    const ids = input.native_observations.map(({ evidence_id: id }) => id);
+    if (new Set(ids).size !== ids.length)
+        context.addIssue({
+            code: "custom",
+            path: ["native_observations"],
+            message: "Native observations must be unique",
+        });
+});
+const seedMatchSchema = z.strictObject({
+    node_id: nodeIdSchema,
+    kind: z.string().min(1).max(128),
+    basis: z.enum(["node-id", "label", "identity", "property"]),
+    field: z.string().min(1).max(256),
+});
+const tracePathSchema = z.strictObject({
+    path_id: z.string().regex(/^jatp_[a-f0-9]{64}$/u),
+    start_node_id: nodeIdSchema,
+    end_node_id: nodeIdSchema,
+    end_kind: z.string().min(1).max(128),
+    node_ids: z.array(nodeIdSchema).min(1).max(65),
+    edge_ids: z.array(edgeIdSchema).max(64),
+    authorities: z.array(z.string().min(1).max(128)).max(16),
+    contains_inference: z.boolean(),
+});
+const nativeHandoffSchema = z.strictObject({
+    native_node_id: nodeIdSchema,
+    artifact_sha256: digestSchema,
+    artifact_path: z.string().min(1).max(4_096).nullable(),
+    export_node_ids: z.array(nodeIdSchema).max(1_000),
+    requested_exports: z.array(boundedTextSchema).max(1_000),
+    status: z.enum(["evidence-linked", "requires-provider-analysis"]),
+    providers: z.array(providerSchema).max(64),
+    evidence_ids: z.array(evidenceIdSchema).max(64),
+    recommended_tools: z
+        .array(z.enum([
+        "open_binary",
+        "binary_overview",
+        "search_procedures",
+        "analyze_function",
+        "xrefs",
+    ]))
+        .max(5),
+});
+/** Evidence-preserving bounded subgraph and native-analysis frontiers. */
+export const applicationFeatureTraceResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    trace_id: z.string().regex(/^jatr_[a-f0-9]{64}$/u),
+    source_evidence_id: evidenceIdSchema,
+    source_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+    seed: applicationFeatureSeedSchema,
+    direction: z.enum(["outgoing", "incoming", "both"]),
+    seed_matches: z.array(seedMatchSchema).max(1_000),
+    graph: javascriptApplicationGraphSchema.nullable(),
+    paths: z.array(tracePathSchema).max(1_000),
+    native_handoffs: z.array(nativeHandoffSchema).max(10_000),
+    summary: z.strictObject({
+        matched_seeds: z.number().int().min(0),
+        traced_nodes: z.number().int().min(0),
+        traced_edges: z.number().int().min(0),
+        terminal_paths: z.number().int().min(0),
+        native_handoffs: z.number().int().min(0),
+        observed_facts: z.number().int().min(0),
+        inferred_facts: z.number().int().min(0),
+        unknown_facts: z.number().int().min(0),
+        unavailable_facts: z.number().int().min(0),
+    }),
+    coverage: z.strictObject({
+        status: z.enum([
+            "complete-within-source",
+            "partial",
+            "truncated",
+            "no-match",
+        ]),
+        source_graph_status: z.enum([
+            "complete",
+            "partial",
+            "unknown",
+            "unavailable",
+        ]),
+        scanned_nodes: z.number().int().min(0),
+        total_seed_matches: z.number().int().min(0),
+        omitted_seed_matches: z.number().int().min(0),
+        omitted_nodes: z.number().int().min(0),
+        omitted_edges: z.number().int().min(0),
+        omitted_paths: z.number().int().min(0),
+        frontier_node_ids: z.array(nodeIdSchema).max(50_000),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(65),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});

package/dist/domain/javascriptFeatureTraversal.js

@@ -0,0 +1,88 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Traverse a JAG without treating edge inference as observed reachability. */
+export const traverseApplicationFeature = (graph, seedNodeIds, direction, limits) => {
+    const nodeById = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    const adjacency = buildAdjacency(graph.edges, direction);
+    const visited = new Set(seedNodeIds);
+    const retainedEdges = new Map();
+    const omittedNodes = new Set();
+    const omittedEdges = new Set();
+    const frontier = new Set();
+    const depths = new Map(seedNodeIds.map((nodeId) => [nodeId, 0]));
+    const predecessors = new Map();
+    const queue = [...seedNodeIds];
+    for (let offset = 0; offset < queue.length; offset += 1) {
+        const current = queue[offset];
+        if (current === undefined)
+            continue;
+        const depth = depths.get(current) ?? 0;
+        for (const entry of adjacency.get(current) ?? []) {
+            if (depth >= limits.max_depth) {
+                recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
+                continue;
+            }
+            if (!visited.has(entry.nextNodeId) && visited.size >= limits.max_nodes) {
+                recordOmission(entry, current, omittedNodes, omittedEdges, frontier);
+                continue;
+            }
+            if (!retainedEdges.has(entry.edge.edge_id) &&
+                retainedEdges.size >= limits.max_edges) {
+                omittedEdges.add(entry.edge.edge_id);
+                frontier.add(current);
+                frontier.add(entry.nextNodeId);
+                continue;
+            }
+            retainedEdges.set(entry.edge.edge_id, entry.edge);
+            if (visited.has(entry.nextNodeId))
+                continue;
+            if (!nodeById.has(entry.nextNodeId))
+                continue;
+            visited.add(entry.nextNodeId);
+            depths.set(entry.nextNodeId, depth + 1);
+            predecessors.set(entry.nextNodeId, {
+                previousNodeId: current,
+                edgeId: entry.edge.edge_id,
+            });
+            queue.push(entry.nextNodeId);
+        }
+    }
+    return {
+        nodes: [...visited]
+            .map((nodeId) => nodeById.get(nodeId))
+            .filter((node) => node !== undefined)
+            .sort((left, right) => compareCodePoints(left.node_id, right.node_id)),
+        edges: [...retainedEdges.values()].sort((left, right) => compareCodePoints(left.edge_id, right.edge_id)),
+        depths,
+        predecessors,
+        frontierNodeIds: [...frontier].sort(compareCodePoints),
+        omittedNodeCount: omittedNodes.size,
+        omittedEdgeCount: omittedEdges.size,
+    };
+};
+const buildAdjacency = (edges, direction) => {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        if (direction !== "incoming")
+            addAdjacency(adjacency, edge.source_node_id, {
+                edge,
+                nextNodeId: edge.target_node_id,
+            });
+        if (direction !== "outgoing")
+            addAdjacency(adjacency, edge.target_node_id, {
+                edge,
+                nextNodeId: edge.source_node_id,
+            });
+    }
+    for (const entries of adjacency.values())
+        entries.sort((left, right) => compareCodePoints(`${left.edge.edge_id}\0${left.nextNodeId}`, `${right.edge.edge_id}\0${right.nextNodeId}`));
+    return adjacency;
+};
+const addAdjacency = (adjacency, nodeId, entry) => {
+    adjacency.set(nodeId, [...(adjacency.get(nodeId) ?? []), entry]);
+};
+const recordOmission = (entry, current, omittedNodes, omittedEdges, frontier) => {
+    omittedNodes.add(entry.nextNodeId);
+    omittedEdges.add(entry.edge.edge_id);
+    frontier.add(current);
+    frontier.add(entry.nextNodeId);
+};

package/dist/domain/javascriptNativeHandoff.js

@@ -0,0 +1,85 @@
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Build provider-neutral addon targets and link exact-subject native Evidence. */
+export const buildJavaScriptNativeHandoffs = (nodes, edges, nativeEvidence) => {
+    const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
+    return nodes
+        .filter(({ kind }) => kind === "native-addon")
+        .flatMap((node) => {
+        const digest = artifactDigest(node);
+        if (digest === null)
+            return [];
+        const linked = nativeEvidence.filter(({ subject }) => subject?.digest.sha256 === digest);
+        const exportNodes = nativeExportNodes(node, edges, nodeById);
+        return [
+            {
+                native_node_id: node.node_id,
+                artifact_sha256: digest,
+                artifact_path: artifactPath(node),
+                export_node_ids: exportNodes.map(({ node_id: id }) => id),
+                requested_exports: requestedExports(exportNodes),
+                status: linked.length === 0
+                    ? "requires-provider-analysis"
+                    : "evidence-linked",
+                providers: uniqueProviders(linked),
+                evidence_ids: linked
+                    .map(({ evidence_id: id }) => id)
+                    .sort(compareCodePoints),
+                recommended_tools: [
+                    "open_binary",
+                    "binary_overview",
+                    "search_procedures",
+                    "analyze_function",
+                    "xrefs",
+                ],
+            },
+        ];
+    })
+        .sort((left, right) => compareCodePoints(left.native_node_id, right.native_node_id));
+};
+const artifactDigest = (node) => {
+    if (node.identity.strategy === "content-digest")
+        return node.identity.sha256;
+    const observation = node.observations.find(({ evidence }) => evidence.artifact.available);
+    return observation?.evidence.artifact.available === true
+        ? observation.evidence.artifact.sha256
+        : null;
+};
+const artifactPath = (node) => {
+    for (const { evidence } of node.observations)
+        if (evidence.location.available &&
+            evidence.location.value.kind === "artifact-path")
+            return evidence.location.value.path;
+    return null;
+};
+const nativeExportNodes = (addon, edges, nodeById) => {
+    const ids = edges.flatMap((edge) => {
+        if (edge.source_node_id === addon.node_id &&
+            ["contains", "exposes"].includes(edge.relation))
+            return [edge.target_node_id];
+        if (edge.target_node_id === addon.node_id &&
+            ["imports", "loads"].includes(edge.relation))
+            return [edge.source_node_id];
+        return [];
+    });
+    return [...new Set(ids)]
+        .map((id) => nodeById.get(id))
+        .filter((node) => node?.kind === "native-export")
+        .sort((left, right) => compareCodePoints(left.node_id, right.node_id));
+};
+const requestedExports = (nodes) => {
+    const values = nodes.flatMap((node) => node.observations.flatMap((observation) => [
+        ...(observation.label === null ? [] : [observation.label]),
+        ...stringArray(observation.properties.requested_members),
+        ...stringArray(observation.properties.members),
+    ]));
+    return [...new Set(values)].sort(compareCodePoints).slice(0, 1_000);
+};
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === "string")
+    : [];
+const uniqueProviders = (evidence) => [
+    ...new Map(evidence.map(({ provider }) => [
+        `${provider.id}\0${provider.name}\0${provider.version ?? ""}`,
+        provider,
+    ])).values(),
+].sort((left, right) => compareCodePoints(`${left.id}\0${left.name}\0${left.version ?? ""}`, `${right.id}\0${right.name}\0${right.version ?? ""}`));

package/dist/domain/javascriptReplay.js

@@ -0,0 +1,361 @@
+import { z } from "zod";
+import { evidenceEnvelopeSchema } from "./evidence.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const absolutePathSchema = z.string().startsWith("/").max(4096);
+const aliasSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z0-9_./:@-]+$/u);
+const replayModuleSchema = z
+    .object({
+    alias: aliasSchema,
+    path: absolutePathSchema,
+    format: z.enum(["esm", "commonjs-factory"]),
+    role: z.enum(["module", "stub"]).default("module"),
+    dependencies: z
+        .record(z.string().min(1).max(256), aliasSchema)
+        .refine((value) => Object.keys(value).length <= 128, {
+        message: "Replay modules may declare at most 128 dependencies",
+    })
+        .default({}),
+})
+    .strict();
+const replaySideSchema = z
+    .object({
+    modules: z.array(replayModuleSchema).min(1).max(128),
+    entry_alias: aliasSchema,
+    entry_export: z.string().min(1).max(256).default("default"),
+})
+    .strict();
+const explicitCaseSchema = z
+    .object({
+    case_id: z.string().min(1).max(128),
+    arguments: z.array(z.json()).max(16),
+})
+    .strict();
+const generatorSchema = z
+    .object({
+    preset: z.enum([
+        "parser-boundaries",
+        "sanitizer-boundaries",
+        "clipboard-boundaries",
+    ]),
+    seed: z.number().int().min(0).max(0xffff_ffff),
+    count: z.number().int().min(1).max(64),
+})
+    .strict();
+const replayLimitsSchema = z
+    .object({
+    wall_time_ms: z.number().int().min(100).max(10_000).default(3_000),
+    memory_bytes: z
+        .number()
+        .int()
+        .min(16 * 1024 * 1024)
+        .max(512 * 1024 * 1024)
+        .default(128 * 1024 * 1024),
+    tasks: z.number().int().min(1).max(32).default(8),
+    cpu_quota_percent: z.number().int().min(1).max(100).default(50),
+    tmpfs_bytes: z
+        .number()
+        .int()
+        .min(1024 * 1024)
+        .max(64 * 1024 * 1024)
+        .default(16 * 1024 * 1024),
+    module_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(16 * 1024 * 1024)
+        .default(4 * 1024 * 1024),
+    input_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(1024 * 1024)
+        .default(256 * 1024),
+    protocol_bytes: z
+        .number()
+        .int()
+        .min(1024 * 1024)
+        .max(64 * 1024 * 1024)
+        .default(16 * 1024 * 1024),
+    output_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(4 * 1024 * 1024)
+        .default(512 * 1024),
+    stderr_bytes: z
+        .number()
+        .int()
+        .min(0)
+        .max(256 * 1024)
+        .default(32 * 1024),
+    result_depth: z.number().int().min(1).max(64).default(16),
+    result_nodes: z.number().int().min(1).max(100_000).default(10_000),
+})
+    .strict();
+const determinismSchema = z
+    .object({
+    clock_iso: z.iso.datetime().default("2000-01-01T00:00:00.000Z"),
+    random_seed: z.number().int().min(0).max(0xffff_ffff).default(0),
+    locale: z.literal("en-US").default("en-US"),
+    timezone: z.literal("UTC").default("UTC"),
+    platform: z.literal("linux").default("linux"),
+})
+    .strict();
+export const controlledReplayInputSchema = z
+    .object({
+    mode: z.enum(["plan", "execute"]),
+    left: replaySideSchema,
+    right: replaySideSchema.optional(),
+    cases: z.array(explicitCaseSchema).max(128).default([]),
+    generator: generatorSchema.optional(),
+    determinism: determinismSchema.default({
+        clock_iso: "2000-01-01T00:00:00.000Z",
+        random_seed: 0,
+        locale: "en-US",
+        timezone: "UTC",
+        platform: "linux",
+    }),
+    limits: replayLimitsSchema.default({
+        wall_time_ms: 3_000,
+        memory_bytes: 128 * 1024 * 1024,
+        tasks: 8,
+        cpu_quota_percent: 50,
+        tmpfs_bytes: 16 * 1024 * 1024,
+        module_bytes: 4 * 1024 * 1024,
+        input_bytes: 256 * 1024,
+        protocol_bytes: 16 * 1024 * 1024,
+        output_bytes: 512 * 1024,
+        stderr_bytes: 32 * 1024,
+        result_depth: 16,
+        result_nodes: 10_000,
+    }),
+    approved: z.boolean().default(false),
+    plan_digest: digestSchema.optional(),
+    reproducer_export: z
+        .object({
+        path: absolutePathSchema,
+        approved: z.boolean(),
+        include_sources: z.boolean().default(false),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.cases.length === 0 && value.generator === undefined)
+        context.addIssue({
+            code: "custom",
+            path: ["cases"],
+            message: "At least one explicit or generated case is required",
+        });
+    if (value.cases.length + (value.generator?.count ?? 0) > 128)
+        context.addIssue({
+            code: "custom",
+            path: ["generator", "count"],
+            message: "Explicit and generated replay cases must total at most 128",
+        });
+    if (value.mode === "execute" &&
+        (value.approved !== true || value.plan_digest === undefined))
+        context.addIssue({
+            code: "custom",
+            path: ["approved"],
+            message: "Execution requires literal approval and a plan digest",
+        });
+});
+const moduleCommitmentSchema = z
+    .object({
+    alias: aliasSchema,
+    canonical_path: z.string().min(1),
+    format: z.enum(["esm", "commonjs-factory"]),
+    role: z.enum(["module", "stub"]),
+    byte_count: z.number().int().min(0),
+    sha256: digestSchema,
+    dependencies: z.record(z.string(), aliasSchema),
+})
+    .strict();
+const runtimeIdentitySchema = z
+    .object({
+    path: z.string().min(1),
+    version: z.string().min(1),
+    sha256: digestSchema,
+})
+    .strict();
+const runtimeFileIdentitySchema = z
+    .object({
+    source_path: z.string().min(1),
+    destination_path: z.string().min(1),
+    sha256: digestSchema,
+})
+    .strict();
+const replayPlanSchema = z
+    .object({
+    schema_version: z.literal(1),
+    plan_digest: digestSchema,
+    policy_version: z.literal("linux-bwrap-systemd-v1"),
+    policy_sha256: digestSchema,
+    network: z.literal("none"),
+    filesystem: z
+        .object({
+        host_writes: z.literal(false),
+        private_tmpfs_bytes: z.number().int(),
+    })
+        .strict(),
+    runtime: z
+        .object({
+        executable: runtimeIdentitySchema,
+        worker: runtimeIdentitySchema,
+        read_only_files: z.array(runtimeFileIdentitySchema).min(1),
+    })
+        .strict(),
+    sandbox: z
+        .object({
+        bubblewrap: runtimeIdentitySchema,
+        systemd_run: runtimeIdentitySchema,
+        systemctl: runtimeIdentitySchema,
+        shell: runtimeIdentitySchema,
+        seccomp_sha256: digestSchema,
+    })
+        .strict(),
+    left: z
+        .object({
+        modules: z.array(moduleCommitmentSchema),
+        entry_alias: aliasSchema,
+        entry_export: z.string(),
+    })
+        .strict(),
+    right: z
+        .object({
+        modules: z.array(moduleCommitmentSchema),
+        entry_alias: aliasSchema,
+        entry_export: z.string(),
+    })
+        .strict()
+        .optional(),
+    cases: z.array(z
+        .object({
+        case_id: z.string(),
+        arguments: z.array(z.json()),
+        sha256: digestSchema,
+    })
+        .strict()),
+    determinism: determinismSchema,
+    limits: replayLimitsSchema,
+    effects: z.array(z.string()),
+    reproducer_export: z
+        .object({
+        path: z.string().min(1),
+        include_sources: z.boolean(),
+        authority: z.literal("evidence_write"),
+    })
+        .strict()
+        .nullable(),
+})
+    .strict();
+const replayOutcomeSchema = z
+    .object({
+    case_id: z.string(),
+    outcome: z.enum([
+        "return",
+        "exception",
+        "serialization_error",
+        "denied",
+        "timeout",
+        "oom",
+        "crash",
+        "cancelled",
+        "protocol_error",
+    ]),
+    value: z.json().optional(),
+    exception: z
+        .object({
+        name: z.string(),
+        message: z.string(),
+        stack: z.string().nullable(),
+    })
+        .strict()
+        .optional(),
+    input_sha256: digestSchema,
+    output_sha256: digestSchema.nullable(),
+    truncated: z.boolean(),
+})
+    .strict();
+export const replayExecutionResultSchema = z
+    .object({
+    schema_version: z.literal(1),
+    plan_digest: digestSchema,
+    outcomes: z.array(replayOutcomeSchema),
+    comparison: z
+        .array(z
+        .object({
+        case_id: z.string(),
+        status: z.enum(["equal", "changed", "unknown"]),
+        left_index: z.number().int(),
+        right_index: z.number().int(),
+    })
+        .strict())
+        .optional(),
+    stderr: z.string(),
+    termination: z.enum([
+        "completed",
+        "timeout",
+        "oom",
+        "crash",
+        "cancelled",
+        "protocol_error",
+    ]),
+    cleanup: z
+        .object({
+        state: z.enum(["complete", "incomplete"]),
+        residual_resources: z.array(z.string()),
+    })
+        .strict(),
+    limitations: z.array(z.string()),
+    reproducer: z
+        .discriminatedUnion("state", [
+        z
+            .object({
+            state: z.literal("written"),
+            path: z.string(),
+            sha256: digestSchema,
+        })
+            .strict(),
+        z
+            .object({
+            state: z.literal("failed"),
+            path: z.string(),
+            error: z.string(),
+        })
+            .strict(),
+    ])
+        .nullable(),
+})
+    .strict();
+export const replayEvidenceSchema = evidenceEnvelopeSchema
+    .omit({ normalized_result: true })
+    .extend({ normalized_result: replayExecutionResultSchema });
+export const controlledReplayOutputSchema = z
+    .object({
+    phase: z.enum(["plan", "execute"]),
+    plan: replayPlanSchema.nullable(),
+    source_evidence: z.array(replayEvidenceSchema),
+    evidence: replayEvidenceSchema.nullable(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if ((value.phase === "plan" &&
+        (value.plan === null ||
+            value.evidence !== null ||
+            value.source_evidence.length !== 0)) ||
+        (value.phase === "execute" &&
+            (value.plan !== null ||
+                value.evidence === null ||
+                value.source_evidence.length === 0)))
+        context.addIssue({
+            code: "custom",
+            message: "Replay output phase does not match its payload",
+        });
+});