rea-agents 2.0.0 → 2.1.0

package/dist/application/RealHopperAssertions.js

@@ -61,6 +61,81 @@ export const requireFunctionDossier = (input, expectedAddress) => {
     validateInstructionScan(value.instruction_scan);
     return value;
 };
+/** Reject a structurally valid dossier that omits fixture-proven semantics. */
+export const requireFunctionDossierOracle = (input, oracle) => {
+    const value = requireFunctionDossier(input, oracle.procedure_address);
+    if (oracle.callee_address !== undefined) {
+        const callees = z
+            .array(identitySchema)
+            .parse(collectionSchema.parse(value.callees).items);
+        if (!callees.some(({ address }) => address === oracle.callee_address))
+            throw new TypeError("analyze_function omitted the expected fixture callee");
+        const references = z
+            .array(z.object({
+            source_address: addressSchema,
+            target_address: addressSchema,
+        }))
+            .parse(collectionSchema.parse(value.outgoing_references).items);
+        if (!references.some(({ target_address }) => target_address === oracle.callee_address))
+            throw new TypeError("analyze_function omitted the expected fixture reference");
+    }
+    if (oracle.caller_address !== undefined) {
+        const callers = z
+            .array(identitySchema)
+            .parse(collectionSchema.parse(value.callers).items);
+        if (!callers.some(({ address }) => address === oracle.caller_address))
+            throw new TypeError("analyze_function omitted the expected fixture caller");
+    }
+    if (oracle.referenced_string !== undefined)
+        requireReferencedValue(value, "referenced_strings", oracle.referenced_string, (candidate) => candidate);
+    if (oracle.referenced_name !== undefined)
+        requireReferencedValue(value, "referenced_names", oracle.referenced_name, (candidate) => candidate.replace(/^_+/u, ""));
+    if (oracle.comment !== undefined) {
+        const comments = z
+            .array(z.object({
+            address: addressSchema,
+            kind: z.enum(["comment", "inline"]),
+            text: z.string(),
+        }))
+            .parse(collectionSchema.parse(value.comments).items);
+        if (!comments.some(({ address, kind, text }) => address === oracle.procedure_address &&
+            kind === "comment" &&
+            text === oracle.comment))
+            throw new TypeError("analyze_function omitted the verifier comment");
+    }
+    if (oracle.require_assembly === true &&
+        collectionSchema.parse(value.assembly).items.length === 0)
+        throw new TypeError("analyze_function omitted fixture assembly");
+    if (oracle.require_cfg_successor) {
+        const blocks = z
+            .array(z.object({ successors: z.array(addressSchema) }))
+            .parse(collectionSchema.parse(value.basic_blocks).items);
+        if (!blocks.some(({ successors }) => successors.length > 0))
+            throw new TypeError("analyze_function omitted a real CFG successor");
+    }
+    return value;
+};
+const referencedValueSchema = z.object({
+    address: addressSchema,
+    value: z.string(),
+    source_address: addressSchema,
+});
+const referenceEdgeSchema = z.object({
+    source_address: addressSchema,
+    target_address: addressSchema,
+});
+const requireReferencedValue = (dossier, field, expected, normalize) => {
+    const values = z
+        .array(referencedValueSchema)
+        .parse(collectionSchema.parse(dossier[field]).items);
+    const references = z
+        .array(referenceEdgeSchema)
+        .parse(collectionSchema.parse(dossier.outgoing_references).items);
+    const found = values.some(({ address, value, source_address: sourceAddress }) => normalize(value) === expected &&
+        references.some(({ source_address, target_address }) => source_address === sourceAddress && target_address === address));
+    if (!found)
+        throw new TypeError(`analyze_function omitted the expected fixture ${field === "referenced_strings" ? "string" : "name"}`);
+};
 /** Require every relationship to be an actual hexadecimal address. */
 export const requireAddressArray = (input, operation) => {
     const parsed = z.array(addressSchema).parse(input);
@@ -69,6 +144,7 @@ export const requireAddressArray = (input, operation) => {
     return parsed;
 };
 const COLLECTION_FIELDS = [
+    "assembly",
     "comments",
     "callers",
     "callees",

package/dist/application/ReconstructionCoverageService.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisInputError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { evaluateReconstructionClosure, reconstructionCoverageWorkspaceSchema, } from "../domain/reconstructionCoverage.js";
+import { err, ok } from "../domain/result.js";
+import { readReconstructionCoverageWorkspace, writeReconstructionCoverageWorkspace, } from "./ReconstructionCoverageWorkspaceStore.js";
+const COMMIT_OPERATION = "commit_reconstruction_coverage";
+const QUERY_OPERATION = "query_reconstruction_coverage";
+const isAborted = (signal) => signal?.aborted === true;
+export const reconstructionCoverageCommitInputSchema = z.strictObject({
+    approved: z.literal(true),
+    workspace_path: z.string().min(1).max(4_096),
+    expected_revision: z.number().int().min(1).nullable(),
+    workspace: reconstructionCoverageWorkspaceSchema,
+});
+export const reconstructionCoverageQueryInputSchema = z.strictObject({
+    workspace_path: z.string().min(1).max(4_096),
+    boundary_id: z.string().min(1).max(200),
+});
+export const reconstructionCoverageCommitOutputSchema = z.strictObject({
+    workspace_path: z.string(),
+    bytes: z.number().int().min(0),
+    workspace_id: z.string().regex(/^rcw_[a-f0-9]{64}$/u),
+    revision: z.number().int().min(1),
+    revision_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    evidence_records: z.number().int().min(0),
+});
+/** Commit one caller-approved canonical reconstruction coverage CAS revision. */
+export const commitReconstructionCoverage = async (rawInput, policy, options = {}) => {
+    const parsed = reconstructionCoverageCommitInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(COMMIT_OPERATION, { cause: parsed.error }));
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(COMMIT_OPERATION));
+    const written = await writeReconstructionCoverageWorkspace(parsed.data.workspace, parsed.data.workspace_path, parsed.data.expected_revision, policy);
+    if (!written.ok)
+        return written;
+    return ok(jsonValueSchema.parse({
+        workspace_path: written.value.path,
+        bytes: written.value.bytes,
+        workspace_id: parsed.data.workspace.workspace_id,
+        revision: parsed.data.workspace.revision,
+        revision_sha256: parsed.data.workspace.revision_sha256,
+        evidence_records: parsed.data.workspace.evidence_bundle.records.length,
+    }));
+};
+/** Read one coverage revision and evaluate a named fail-closed boundary. */
+export const queryReconstructionCoverage = async (rawInput, policy, nowEpochMs, options = {}) => {
+    const parsed = reconstructionCoverageQueryInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(QUERY_OPERATION, { cause: parsed.error }));
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(QUERY_OPERATION));
+    const loaded = await readReconstructionCoverageWorkspace(parsed.data.workspace_path, policy);
+    if (!loaded.ok)
+        return loaded;
+    if (loaded.value === null)
+        return err(new AnalysisInputError(QUERY_OPERATION, {
+            cause: new TypeError("Reconstruction coverage workspace does not exist"),
+        }));
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(QUERY_OPERATION));
+    try {
+        return ok(jsonValueSchema.parse(evaluateReconstructionClosure(loaded.value, parsed.data.boundary_id, nowEpochMs)));
+    }
+    catch (cause) {
+        return err(new AnalysisInputError(QUERY_OPERATION, { cause }));
+    }
+};

package/dist/application/ReconstructionCoverageWorkspaceStore.js

@@ -0,0 +1,31 @@
+import { InvestigationWorkspaceError } from "../domain/errors.js";
+import { parseReconstructionCoverageWorkspace, serializeReconstructionCoverageWorkspace, } from "../domain/reconstructionCoverage.js";
+import { err, ok } from "../domain/result.js";
+import { readRevisionedWorkspace, writeRevisionedWorkspace, } from "./InvestigationWorkspaceStore.js";
+const codec = {
+    parse: parseReconstructionCoverageWorkspace,
+    serialize: serializeReconstructionCoverageWorkspace,
+    validateNext: (current, next, expectedRevision) => {
+        if ((current?.revision ?? null) !== expectedRevision)
+            return err(new InvestigationWorkspaceError("update", "revision-conflict"));
+        if (current === null)
+            return next.revision === 1 && next.previous_revision_sha256 === null
+                ? ok(null)
+                : err(new InvestigationWorkspaceError("update", "revision-conflict"));
+        if (current.name !== next.name ||
+            current.workspace_id !== next.workspace_id)
+            return err(new InvestigationWorkspaceError("update", "name-conflict"));
+        return next.revision === current.revision + 1 &&
+            next.previous_revision_sha256 === current.revision_sha256
+            ? ok(null)
+            : err(new InvestigationWorkspaceError("update", "revision-conflict"));
+    },
+};
+/** Read a validated reconstruction coverage workspace revision. */
+export const readReconstructionCoverageWorkspace = (path, policy) => readRevisionedWorkspace(path, policy, codec);
+/** Atomically append one reconstruction coverage workspace CAS revision. */
+export const writeReconstructionCoverageWorkspace = (workspace, path, expectedRevision, policy) => writeRevisionedWorkspace(path, policy, {
+    document: workspace,
+    expectedRevision,
+    codec,
+});

package/dist/application/RuntimeExecutableDiagnostics.js

@@ -0,0 +1,172 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+const TOOL_NAMES = ["node", "npm", "npx"];
+const MAX_CANDIDATES_PER_TOOL = 16;
+const MAX_OUTPUT_BYTES = 65_536;
+const MAX_DIAGNOSTIC_BYTES = 4_096;
+const PROBE_CONCURRENCY = 4;
+/** Inventory and bounded-probe Node toolchain candidates under one exact PATH. */
+export const inspectRuntimeExecutables = async (options) => {
+    const pathEntries = unique(options.path.split(delimiter).filter(Boolean));
+    const candidates = [
+        {
+            tool: "node",
+            path: options.launcherNode,
+            pathIndex: null,
+            selection: "rea-launcher",
+        },
+    ];
+    for (const tool of TOOL_NAMES) {
+        const discovered = await discoverToolCandidates(tool, pathEntries, options.platform, options.pathExtensions);
+        for (const [index, candidate] of discovered.entries())
+            candidates.push({
+                tool,
+                path: candidate.path,
+                pathIndex: candidate.pathIndex,
+                selection: index === 0 ? "path-primary" : "path-shadowed",
+            });
+    }
+    const seen = new Set();
+    const uniqueCandidates = [];
+    for (const candidate of candidates) {
+        const key = `${candidate.tool}\0${candidate.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        uniqueCandidates.push(candidate);
+    }
+    const diagnostics = await mapConcurrentBounded(uniqueCandidates, PROBE_CONCURRENCY, (candidate) => probeCandidate(candidate, options.timeoutMs ?? 5_000, options.path));
+    return {
+        launcher_node: await canonicalPath(options.launcherNode),
+        candidates: diagnostics,
+    };
+};
+const discoverToolCandidates = async (tool, pathEntries, platform, configuredExtensions) => {
+    const extensions = platform === "win32"
+        ? (configuredExtensions ?? [".COM", ".EXE", ".BAT", ".CMD"])
+        : [""];
+    const candidates = [];
+    for (const [pathIndex, directory] of pathEntries.entries()) {
+        for (const extension of extensions) {
+            const path = join(directory, `${tool}${extension}`);
+            if (await isExecutable(path, platform)) {
+                candidates.push({ path, pathIndex });
+                break;
+            }
+        }
+        if (candidates.length >= MAX_CANDIDATES_PER_TOOL)
+            break;
+    }
+    return candidates;
+};
+const probeCandidate = async (candidate, timeoutMs, effectivePath) => {
+    const canonical = await canonicalPath(candidate.path);
+    const result = await executeVersion(candidate.path, timeoutMs, effectivePath);
+    return {
+        tool: candidate.tool,
+        lexical_path: candidate.path,
+        canonical_path: canonical,
+        path_index: candidate.pathIndex,
+        selection: candidate.selection,
+        version: result.ok ? result.version : null,
+        healthy: result.ok,
+        failure: result.ok ? null : result.failure,
+    };
+};
+const executeVersion = (path, timeoutMs, effectivePath) => new Promise((resolve) => {
+    const child = execFile(path, ["--version"], {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: MAX_OUTPUT_BYTES,
+        windowsHide: true,
+        env: environmentWithPath(effectivePath),
+    }, (cause, stdout, stderr) => {
+        if (cause === null) {
+            const version = firstNonemptyLine(stdout) ?? firstNonemptyLine(stderr);
+            if (version !== undefined)
+                resolve({ ok: true, version });
+            else
+                resolve({
+                    ok: false,
+                    failure: failure("runtime_invalid_version_output", child, stderr),
+                });
+            return;
+        }
+        resolve({
+            ok: false,
+            failure: classifyProbeFailure(cause, child, stderr),
+        });
+    });
+});
+const classifyProbeFailure = (cause, child, stderr) => {
+    const dependency = missingDynamicLibrary(stderr);
+    if (dependency !== null)
+        return failure("runtime_dynamic_library_missing", child, stderr, dependency);
+    if ("killed" in cause && cause.killed === true)
+        return failure("runtime_timeout", child, stderr);
+    if (child.signalCode !== null)
+        return failure("runtime_signal", child, stderr);
+    if ("code" in cause && typeof cause.code === "string")
+        return failure("runtime_spawn_failed", child, stderr);
+    return failure("runtime_nonzero_exit", child, stderr);
+};
+const failure = (code, child, stderr, dependency = null) => ({
+    code,
+    exit_code: child.exitCode,
+    signal: child.signalCode,
+    dependency,
+    stderr: bounded(stderr.trim()),
+});
+const missingDynamicLibrary = (stderr) => /(?:dyld(?:\[[^\]]+\])?: )?Library not loaded:\s*([^\r\n]+)/u
+    .exec(stderr)?.[1]
+    ?.trim() ?? null;
+const isExecutable = async (path, platform) => {
+    try {
+        await access(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const canonicalPath = async (path) => {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return path;
+    }
+};
+const firstNonemptyLine = (value) => value
+    .split(/\r?\n/u)
+    .find((line) => line.trim().length > 0)
+    ?.trim();
+const bounded = (value) => value.length <= MAX_DIAGNOSTIC_BYTES
+    ? value
+    : value.slice(-MAX_DIAGNOSTIC_BYTES);
+const unique = (values) => [...new Set(values)];
+const environmentWithPath = (path) => {
+    const environment = {};
+    for (const [name, value] of Object.entries(process.env))
+        if (name.toUpperCase() !== "PATH")
+            environment[name] = value;
+    environment.PATH = path;
+    return environment;
+};
+const mapConcurrentBounded = async (inputs, concurrency, operation) => {
+    const outputs = [];
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(concurrency, inputs.length) }, async () => {
+        while (nextIndex < inputs.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const input = inputs[index];
+            if (input !== undefined)
+                outputs[index] = await operation(input);
+        }
+    });
+    await Promise.all(workers);
+    return outputs;
+};