rea-agents 1.1.0 → 1.3.0

package/dist/application/CommandShimReplay.js

@@ -0,0 +1,136 @@
+import { createServer } from "node:http";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const RUNNER = `const command = process.argv[2];
+const response = await fetch(process.env.REA_SHIM_LEDGER_URL, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ command, arguments: process.argv.slice(3), working_directory: process.cwd() }),
+});
+if (!response.ok) process.exit(127);
+const route = await response.json();
+let elapsed = 0;
+for (const output of route.outputs) {
+  const wait = Math.max(0, output.at_ms - elapsed);
+  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  elapsed = output.at_ms;
+  (output.stream === "stdout" ? process.stdout : process.stderr).write(output.data);
+}
+if (route.termination.type === "signal") process.kill(process.pid, route.termination.signal);
+else process.exit(route.termination.code);
+`;
+const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * Start bounded executable replay wrappers and their private invocation ledger.
+ *
+ * Exact argument matching is deliberate: a fallback to the host executable
+ * would make an unmatched dependency call look authoritative. Unmatched and
+ * exhausted routes therefore fail visibly and remain part of the capture.
+ */
+export const startCommandShimReplay = async (scenario, temporaryRoot, started) => {
+    const binPath = join(temporaryRoot, "shims");
+    await mkdir(binPath);
+    const runnerPath = join(temporaryRoot, "shim-runner.mjs");
+    await writeFile(runnerPath, RUNNER, { mode: 0o600, flag: "wx" });
+    for (const shim of scenario.command_shims) {
+        const path = join(binPath, shim.name);
+        const wrapper = `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(runnerPath)} ${shellQuote(shim.name)} "$@"\n`;
+        await writeFile(path, wrapper, { mode: 0o700, flag: "wx" });
+        await chmod(path, 0o700);
+    }
+    const events = [];
+    let truncated = false;
+    const calls = new Map();
+    const server = createServer((request, response) => {
+        if (request.method !== "POST" || request.url !== "/invoke") {
+            response.writeHead(404).end();
+            return;
+        }
+        readInvocation(request)
+            .then((invocation) => {
+            const shim = scenario.command_shims.find(({ name }) => name === invocation.command);
+            const routeIndex = shim?.routes.findIndex(({ arguments: expected }) => JSON.stringify(expected) === JSON.stringify(invocation.arguments));
+            const key = `${invocation.command}:${String(routeIndex ?? -1)}`;
+            const used = calls.get(key) ?? 0;
+            const route = shim !== undefined && routeIndex !== undefined && routeIndex >= 0
+                ? shim.routes[routeIndex]
+                : undefined;
+            const outcome = route === undefined
+                ? "unmatched"
+                : used >= route.max_calls
+                    ? "exhausted"
+                    : "matched";
+            if (events.length >= scenario.limits.protocol_events)
+                truncated = true;
+            else
+                events.push({
+                    sequence: events.length,
+                    at_ms: Math.max(0, Date.now() - started),
+                    command: invocation.command,
+                    route_index: routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,
+                    arguments: invocation.arguments,
+                    working_directory: invocation.working_directory,
+                    outcome,
+                });
+            if (outcome !== "matched" || route === undefined) {
+                response.writeHead(409).end();
+                return;
+            }
+            calls.set(key, used + 1);
+            response
+                .writeHead(200, { "content-type": "application/json" })
+                .end(JSON.stringify(route));
+        })
+            .catch(() => response.writeHead(400).end());
+    });
+    await listen(server);
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server);
+        throw new Error("command shim ledger did not bind an IPv4 port");
+    }
+    return {
+        binPath,
+        url: `http://127.0.0.1:${String(address.port)}/invoke`,
+        events,
+        get truncated() {
+            return truncated;
+        },
+        close: () => closeServer(server),
+    };
+};
+const readInvocation = async (request) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 64 * 1024)
+            throw new Error("shim invocation exceeds limit");
+        chunks.push(buffer);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (typeof value !== "object" ||
+        value === null ||
+        !("command" in value) ||
+        typeof value.command !== "string" ||
+        !("arguments" in value) ||
+        !Array.isArray(value.arguments) ||
+        !value.arguments.every((item) => typeof item === "string") ||
+        !("working_directory" in value) ||
+        typeof value.working_directory !== "string")
+        throw new Error("invalid shim invocation");
+    return {
+        command: value.command,
+        arguments: value.arguments,
+        working_directory: value.working_directory,
+    };
+};
+const listen = (server) => new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(0, "127.0.0.1", () => {
+        server.off("error", rejectListen);
+        resolveListen();
+    });
+});
+const closeServer = (server) => new Promise((resolveClose, rejectClose) => server.close((cause) => cause === undefined ? resolveClose() : rejectClose(cause)));

package/dist/application/CrossVersionInventory.js

@@ -0,0 +1,98 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { createEvidence } from "../domain/evidence.js";
+import { AnalysisCancelledError, ArtifactOperationError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { paginateArtifactInventory, } from "./ArtifactInventory.js";
+import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
+export const AUTOMATIC_RUN_LIMITATION = "Automatic cross-version runs compare shipped artifact structure only; they do not execute either version.";
+/** Authorize and scan both inputs once under the same bounded traversal policy. */
+export const scanVersions = async (input, inputRoots, signal) => {
+    try {
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError("find_changed_behavior"));
+        const limits = artifactLimits(input.options);
+        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal);
+        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal);
+        return ok({ left, right });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            return err(new ArtifactOperationError("inventory_artifact", cause.reason, cause.details));
+        return err(new ArtifactOperationError("inventory_artifact", "io"));
+    }
+};
+/** Project complete snapshots into bounded, comparable Evidence page sets. */
+export const createInventoryEvidencePages = (input, snapshots) => {
+    const left = inventoryPages(input.left_path, snapshots.left, input.options);
+    const right = inventoryPages(input.right_path, snapshots.right, input.options);
+    if (left.length > 100 || right.length > 100)
+        return err(new ArtifactOperationError("inventory_artifact", "limit"));
+    return ok({ left, right });
+};
+/** Reduce a snapshot to the content commitments used by run identity. */
+export const targetFor = (snapshot) => ({
+    root_sha256: snapshot.manifest.root_sha256,
+    graph_sha256: snapshot.manifest.graph_sha256,
+    manifest_id: snapshot.manifest.manifest_id,
+    format: snapshot.manifest.root_format,
+});
+/** Preserve scan and execution limitations in stable order. */
+export const runLimitations = (snapshots) => [
+    ...new Set([
+        ...snapshots.left.limitations.map((item) => `Left: ${item}`),
+        ...snapshots.right.limitations.map((item) => `Right: ${item}`),
+        AUTOMATIC_RUN_LIMITATION,
+    ]),
+].sort((left, right) => left.localeCompare(right));
+const inventoryPages = (path, snapshot, options) => {
+    const count = Math.max(1, Math.ceil(snapshot.nodes.length / options.page_size), Math.ceil(snapshot.occurrences.length / options.page_size), Math.ceil(snapshot.edges.length / options.page_size));
+    return Array.from({ length: count }, (_, index) => inventoryPage(path, snapshot, options, index * options.page_size));
+};
+const inventoryPage = (path, snapshot, options, offset) => {
+    const result = paginateArtifactInventory(snapshot, {
+        nodeOffset: offset,
+        nodeLimit: options.page_size,
+        occurrenceOffset: offset,
+        occurrenceLimit: options.page_size,
+        edgeOffset: offset,
+        edgeLimit: options.page_size,
+    });
+    return createEvidence({
+        path,
+        sha256: snapshot.manifest.root_sha256,
+        format: snapshot.manifest.root_format,
+    }, ARTIFACT_GRAPH_PROVIDER, {
+        operation: "inventory_artifact",
+        parameters: {
+            node_offset: offset,
+            node_limit: options.page_size,
+            occurrence_offset: offset,
+            occurrence_limit: options.page_size,
+            edge_offset: offset,
+            edge_limit: options.page_size,
+            max_entries: options.max_entries,
+            max_total_bytes: options.max_total_bytes,
+            max_entry_bytes: options.max_entry_bytes,
+            max_compression_ratio: options.max_compression_ratio,
+            max_depth: options.max_depth,
+            max_path_bytes: options.max_path_bytes,
+        },
+        result: jsonValueSchema.parse(result),
+        rawResult: null,
+        limitations: result.limitations,
+        locations: result.occurrences.items.map(({ logical_path: logicalPath }) => ({
+            kind: "artifact-path",
+            path: logicalPath,
+        })),
+    });
+};
+const artifactLimits = (options) => ({
+    maxEntries: options.max_entries,
+    maxTotalBytes: options.max_total_bytes,
+    maxEntryBytes: options.max_entry_bytes,
+    maxCompressionRatio: options.max_compression_ratio,
+    maxDepth: options.max_depth,
+    maxPathBytes: options.max_path_bytes,
+});

package/dist/application/CrossVersionInvestigation.js

@@ -0,0 +1,295 @@
+import { compareArtifacts } from "../domain/artifactComparison.js";
+import { findChangedBehavior } from "../domain/changedBehavior.js";
+import { createEvidence } from "../domain/evidence.js";
+import { createEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { AnalysisInputError, EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
+import { createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, investigationRunSummarySchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { AUTOMATIC_RUN_LIMITATION, createInventoryEvidencePages, runLimitations, scanVersions, targetFor, } from "./CrossVersionInventory.js";
+import { readInvestigationWorkspace, writeInvestigationWorkspace, } from "./InvestigationWorkspaceStore.js";
+import { ARTIFACT_COMPARISON_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, } from "./InvestigationProviders.js";
+/** Run or resume a deterministic cross-version artifact investigation. */
+export const runCrossVersionInvestigation = async (input, policy, execution) => {
+    const parsed = crossVersionInvestigationInputSchema.safeParse(input);
+    if (!parsed.success)
+        return err(new AnalysisInputError("find_changed_behavior", {
+            cause: parsed.error,
+        }));
+    const initial = await readInvestigationWorkspace(parsed.data.workspace_path, policy);
+    if (!initial.ok)
+        return initial;
+    const preflight = validateWorkspaceRequest(initial.value, parsed.data);
+    if (!preflight.ok)
+        return preflight;
+    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal);
+    if (!snapshots.ok)
+        return snapshots;
+    return continueInvestigation({
+        input: parsed.data,
+        initial: initial.value,
+        snapshots: snapshots.value,
+        policy,
+        session: execution.session,
+    });
+};
+const continueInvestigation = async (context) => {
+    const left = targetFor(context.snapshots.left);
+    const right = targetFor(context.snapshots.right);
+    const identity = createInvestigationRunIdentity({
+        left,
+        right,
+        options: context.input.options,
+    });
+    const existing = context.initial?.runs.find(({ run_id: id }) => id === identity.runId);
+    if (context.initial !== null && existing?.status === "complete")
+        return completeOutcome(context.initial, existing, true, context.session);
+    const pages = createInventoryEvidencePages(context.input, context.snapshots);
+    if (!pages.ok)
+        return pages;
+    const inventoried = await ensureInventoryCheckpoint({
+        input: context.input,
+        current: context.initial,
+        existing,
+        pages: pages.value,
+        snapshots: context.snapshots,
+        policy: context.policy,
+    });
+    if (!inventoried.ok)
+        return inventoried;
+    const compared = await ensureComparisonCheckpoint(context.input, inventoried.value, context.policy);
+    if (!compared.ok)
+        return compared;
+    return finalizeInvestigation(context.input, compared.value, context.policy, context.session);
+};
+const ensureInventoryCheckpoint = async (input) => {
+    if (input.existing !== undefined) {
+        const consistent = validateInventoryCheckpoint(input.existing, input.pages);
+        if (!consistent.ok)
+            return consistent;
+        return input.current === null
+            ? err(new EvidenceIntegrityError("Investigation workspace is missing"))
+            : ok({ workspace: input.current, run: input.existing });
+    }
+    const left = targetFor(input.snapshots.left);
+    const right = targetFor(input.snapshots.right);
+    const identity = createInvestigationRunIdentity({
+        left,
+        right,
+        options: input.input.options,
+    });
+    const run = investigationRunSchema.parse({
+        schema_version: 1,
+        run_id: identity.runId,
+        request_sha256: identity.requestSha256,
+        left,
+        right,
+        options: input.input.options,
+        status: "running",
+        completed_stages: ["inventory_left", "inventory_right"],
+        left_inventory_evidence_ids: evidenceIds(input.pages.left),
+        right_inventory_evidence_ids: evidenceIds(input.pages.right),
+        comparison_evidence_id: null,
+        result_evidence_id: null,
+        limitations: runLimitations(input.snapshots),
+    });
+    const saved = await checkpoint({
+        path: input.input.workspace_path,
+        name: input.input.workspace_name,
+        current: input.current,
+        records: [...input.pages.left, ...input.pages.right],
+        run,
+        policy: input.policy,
+    });
+    return saved.ok ? ok({ workspace: saved.value, run }) : saved;
+};
+const ensureComparisonCheckpoint = async (input, state, policy) => {
+    if (state.run.comparison_evidence_id !== null)
+        return ok(state);
+    const inventory = inventoryEvidence(state.workspace, state.run);
+    if (!inventory.ok)
+        return inventory;
+    const evidence = createArtifactComparisonEvidence(inventory.value, input.options.change_limit);
+    const run = investigationRunSchema.parse({
+        ...state.run,
+        completed_stages: [
+            "inventory_left",
+            "inventory_right",
+            "compare_artifacts",
+        ],
+        comparison_evidence_id: evidence.evidence_id,
+    });
+    const saved = await checkpoint({
+        path: input.workspace_path,
+        name: input.workspace_name,
+        current: state.workspace,
+        records: [evidence],
+        run,
+        policy,
+    });
+    return saved.ok ? ok({ workspace: saved.value, run }) : saved;
+};
+const createArtifactComparisonEvidence = (inventory, limit) => {
+    const comparison = compareArtifacts(inventory.left, inventory.right, 0, limit);
+    const leftIds = evidenceIds(inventory.left);
+    const rightIds = evidenceIds(inventory.right);
+    return createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
+        predicateType: "rea.artifact-comparison/v1",
+        operation: "compare_artifacts",
+        parameters: {
+            left_evidence_ids: leftIds,
+            right_evidence_ids: rightIds,
+            offset: 0,
+            limit,
+        },
+        result: jsonValueSchema.parse(comparison),
+        confidence: "derived",
+        authority: "analyst-inference",
+        limitations: comparison.limitations,
+        evidenceLinks: [...leftIds, ...rightIds],
+    });
+};
+const finalizeInvestigation = async (input, state, policy, session) => {
+    const comparison = comparisonEvidenceFor(state.workspace, state.run);
+    if (!comparison.ok)
+        return comparison;
+    const evidence = createChangedBehaviorEvidence(state, comparison.value);
+    const run = investigationRunSchema.parse({
+        ...state.run,
+        status: "complete",
+        completed_stages: [
+            "inventory_left",
+            "inventory_right",
+            "compare_artifacts",
+            "find_changed_behavior",
+        ],
+        result_evidence_id: evidence.evidence_id,
+    });
+    const saved = await checkpoint({
+        path: input.workspace_path,
+        name: input.workspace_name,
+        current: state.workspace,
+        records: [evidence],
+        run,
+        policy,
+    });
+    return saved.ok ? completeOutcome(saved.value, run, false, session) : saved;
+};
+const createChangedBehaviorEvidence = (state, comparison) => {
+    const limit = Math.min(state.run.options.change_limit, 100);
+    const changed = findChangedBehavior([comparison], 0, limit);
+    const summary = investigationRunSummarySchema.parse({
+        schema_version: 1,
+        workspace_id: state.workspace.workspace_id,
+        run_id: state.run.run_id,
+        left_manifest_id: state.run.left.manifest_id,
+        right_manifest_id: state.run.right.manifest_id,
+        inventory_evidence_count: state.run.left_inventory_evidence_ids.length +
+            state.run.right_inventory_evidence_ids.length,
+        comparison_evidence_id: comparison.evidence_id,
+        limitations: state.run.limitations,
+    });
+    return createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
+        predicateType: "rea.changed-behavior/v1",
+        operation: "find_changed_behavior",
+        parameters: {
+            workspace_id: state.workspace.workspace_id,
+            run_id: state.run.run_id,
+            comparison_evidence_ids: [comparison.evidence_id],
+            offset: 0,
+            limit,
+        },
+        result: jsonValueSchema.parse({
+            ...changed,
+            investigation_run: summary,
+        }),
+        confidence: "derived",
+        authority: "analyst-inference",
+        limitations: [...changed.limitations, AUTOMATIC_RUN_LIMITATION],
+        evidenceLinks: changed.evidence_links,
+    });
+};
+const comparisonEvidenceFor = (workspace, run) => {
+    const evidence = workspace.bundle.records.find(({ evidence_id: id }) => id === run.comparison_evidence_id);
+    return evidence === undefined
+        ? err(new EvidenceIntegrityError("Investigation comparison checkpoint is missing Evidence"))
+        : ok(evidence);
+};
+const checkpoint = async (input) => {
+    const records = mergeEvidence(input.current?.bundle.records ?? [], input.records);
+    const bundle = createEvidenceBundle(records, input.current?.bundle.unknowns ?? []);
+    const runs = replaceRun(input.current?.runs ?? [], input.run);
+    const next = input.current === null
+        ? createInvestigationWorkspace(input.name, bundle, runs)
+        : reviseInvestigationWorkspace(input.current, bundle, runs);
+    const written = await writeInvestigationWorkspace(next, input.path, input.current?.revision ?? null, input.policy);
+    return written.ok ? ok(next) : written;
+};
+const completeOutcome = (workspace, run, reused, session) => {
+    if (run.result_evidence_id === null)
+        return err(new EvidenceIntegrityError("Completed investigation has no result"));
+    const evidence = workspace.bundle.records.find(({ evidence_id: id }) => id === run.result_evidence_id);
+    if (evidence === undefined)
+        return err(new EvidenceIntegrityError("Completed investigation result Evidence is missing"));
+    if (session !== undefined) {
+        const records = recordsForRun(workspace, run);
+        const imported = session.importEvidenceBundle(createEvidenceBundle(records));
+        if (!imported.ok)
+            return imported;
+    }
+    return ok({ evidence, workspace, reused });
+};
+const validateWorkspaceRequest = (workspace, input) => {
+    if (workspace !== null && workspace.name !== input.workspace_name)
+        return err(new InvestigationWorkspaceError("update", "name-conflict"));
+    if (input.expected_workspace_revision !== undefined &&
+        workspace?.revision !== input.expected_workspace_revision)
+        return err(new InvestigationWorkspaceError("update", "revision-conflict"));
+    return ok(null);
+};
+const validateInventoryCheckpoint = (run, pages) => JSON.stringify(run.left_inventory_evidence_ids) ===
+    JSON.stringify(evidenceIds(pages.left)) &&
+    JSON.stringify(run.right_inventory_evidence_ids) ===
+        JSON.stringify(evidenceIds(pages.right))
+    ? ok(null)
+    : err(new EvidenceIntegrityError("Investigation inventory checkpoint disagrees with current content"));
+const inventoryEvidence = (workspace, run) => {
+    if (workspace === null)
+        return err(new EvidenceIntegrityError("Investigation workspace is missing"));
+    const byId = new Map(workspace.bundle.records.map((record) => [record.evidence_id, record]));
+    const left = run.left_inventory_evidence_ids.flatMap((id) => {
+        const evidence = byId.get(id);
+        return evidence === undefined ? [] : [evidence];
+    });
+    const right = run.right_inventory_evidence_ids.flatMap((id) => {
+        const evidence = byId.get(id);
+        return evidence === undefined ? [] : [evidence];
+    });
+    return left.length === run.left_inventory_evidence_ids.length &&
+        right.length === run.right_inventory_evidence_ids.length
+        ? ok({ left, right })
+        : err(new EvidenceIntegrityError("Investigation inventory checkpoint is incomplete"));
+};
+const recordsForRun = (workspace, run) => {
+    const ids = new Set([
+        ...run.left_inventory_evidence_ids,
+        ...run.right_inventory_evidence_ids,
+        ...(run.comparison_evidence_id === null
+            ? []
+            : [run.comparison_evidence_id]),
+        ...(run.result_evidence_id === null ? [] : [run.result_evidence_id]),
+    ]);
+    return workspace.bundle.records.filter(({ evidence_id: id }) => ids.has(id));
+};
+const mergeEvidence = (current, additions) => {
+    const records = new Map(current.map((record) => [record.evidence_id, record]));
+    for (const record of additions)
+        if (!records.has(record.evidence_id))
+            records.set(record.evidence_id, record);
+    return [...records.values()];
+};
+const replaceRun = (runs, replacement) => [
+    ...runs.filter(({ run_id: id }) => id !== replacement.run_id),
+    replacement,
+];
+const evidenceIds = (records) => records.map(({ evidence_id: id }) => id);