rea-agents 1.1.0 → 1.2.0

package/dist/domain/processCapture.js

@@ -1,265 +1,105 @@
-import { resolve } from "node:path";
 import { z } from "zod";
-const positiveBudget = z.number().int().positive();
-const timedEventBase = { at_ms: z.number().int().nonnegative() };
-const environmentName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
-const reservedEnvironment = new Set([
-    "HOME",
-    "TERM",
-    "REA_PROCESS_RUN_ID",
-    "REA_REPLAY_HTTP_URL",
-    "REA_REPLAY_WEBSOCKET_URL",
-]);
-const normalizationSchema = z.object({
-    paths: z.boolean(),
-    pids: z.boolean(),
-    ports: z.boolean(),
-    time_bucket_ms: positiveBudget.max(60_000),
-    patterns: z.array(z.object({
-        pattern: z.string().max(500),
-        replacement: z.string().max(100),
-    })),
+import { LEGACY_PROCESS_CAPTURE_MESSAGE, normalizationSchema, } from "./processScenario.js";
+export * from "./processScenario.js";
+const fileStateSchema = z.object({
+    path: z.string(),
+    type: z.enum(["file", "directory", "symlink", "other"]),
+    mode: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    symlink_target: z.string().nullable(),
 });
-/** Exact boundary schema for bounded dynamic process scenarios. */
-export const processScenarioSchema = z
-    .object({
-    approved: z
-        .literal(true)
-        .describe("Explicit per-call acknowledgement that this operation launches the target"),
-    unknown_registry_approved: z
-        .literal(true)
-        .optional()
-        .describe("Explicit approval to record capture residuals durably"),
-    executable: z.string().startsWith("/"),
-    arguments: z.array(z.string()).max(256).default([]),
-    working_directory: z.string().startsWith("/"),
-    environment: z.record(environmentName, z.string()).default({}),
-    inherit_environment: z.array(environmentName).max(64).default([]),
-    secret_aliases: z.array(environmentName).max(64).default([]),
-    network_access: z.literal("host").default("host"),
-    filesystem_roots: z.array(z.string().startsWith("/")).max(16).default([]),
-    events: z
-        .array(z.discriminatedUnion("type", [
-        z.object({
-            ...timedEventBase,
-            type: z.literal("input"),
-            data: z.string(),
-        }),
-        z.object({
-            ...timedEventBase,
-            type: z.literal("resize"),
-            columns: z.number().int().min(1).max(1_000),
-            rows: z.number().int().min(1).max(1_000),
-        }),
-        z.object({
-            ...timedEventBase,
-            type: z.literal("signal"),
-            signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),
-        }),
-    ]))
-        .max(1_000)
-        .default([]),
-    timeout_ms: positiveBudget.max(300_000).default(30_000),
-    idle_timeout_ms: positiveBudget.max(300_000).default(30_000),
-    settle_ms: z.number().int().nonnegative().max(10_000).default(100),
-    limits: z
-        .object({
-        output_bytes: positiveBudget.max(10_000_000).default(1_000_000),
-        frames: positiveBudget.max(100_000).default(10_000),
-        files: positiveBudget.max(100_000).default(10_000),
-        file_bytes: positiveBudget.max(100_000_000).default(10_000_000),
-        processes: positiveBudget.max(10_000).default(1_000),
-        protocol_events: positiveBudget.max(100_000).default(10_000),
-        protocol_body_bytes: positiveBudget.max(10_000_000).default(1_000_000),
-        connections: positiveBudget.max(1_000).default(100),
-        filesystem_depth: z.number().int().min(1).max(64).default(16),
-    })
-        .default({
-        output_bytes: 1_000_000,
-        frames: 10_000,
-        files: 10_000,
-        file_bytes: 10_000_000,
-        processes: 1_000,
-        protocol_events: 10_000,
-        protocol_body_bytes: 1_000_000,
-        connections: 100,
-        filesystem_depth: 16,
-    }),
-    normalization: z
-        .object({
-        paths: z.boolean().default(true),
-        pids: z.boolean().default(true),
-        ports: z.boolean().default(true),
-        time_bucket_ms: positiveBudget.max(60_000).default(10),
-        patterns: z
-            .array(z.object({
-            pattern: z.string().max(500),
-            replacement: z.string().max(100),
-        }))
-            .max(32)
-            .default([]),
-    })
-        .default({
-        paths: true,
-        pids: true,
-        ports: true,
-        time_bucket_ms: 10,
-        patterns: [],
-    }),
-    replay: z
-        .object({
-        http: z
-            .array(z.object({
-            method: z.string().max(16),
-            path: z.string().startsWith("/"),
-            status: z.number().int().min(100).max(599),
-            body: z.string().max(1_000_000),
-            request_headers: z.record(z.string(), z.string()).default({}),
-            request_body: z.string().max(1_000_000).optional(),
-            response_headers: z.record(z.string(), z.string()).default({}),
-            delay_ms: z.number().int().nonnegative().max(30_000).default(0),
-            disconnect: z.boolean().default(false),
-            max_calls: z.number().int().min(1).max(100).default(1),
-        }))
-            .max(100)
-            .default([]),
-        websocket_messages: z
-            .array(z.string().max(1_000_000))
-            .max(100)
-            .default([]),
-        websocket_connections: z
-            .array(z.object({
-            messages: z
-                .array(z.object({
-                data: z.string().max(1_000_000),
-                delay_ms: z
-                    .number()
-                    .int()
-                    .nonnegative()
-                    .max(30_000)
-                    .default(0),
-            }))
-                .max(100),
-            disconnect_after: z.boolean().default(false),
-        }))
-            .max(100)
-            .default([]),
-    })
-        .default({
-        http: [],
-        websocket_messages: [],
-        websocket_connections: [],
-    }),
-})
-    .strict()
-    .superRefine((scenario, context) => {
-    for (let index = 1; index < scenario.events.length; index += 1) {
-        if (scenario.events[index].at_ms < scenario.events[index - 1].at_ms) {
-            context.addIssue({
-                code: "custom",
-                message: "events must be ordered by at_ms",
-                path: ["events", index],
-            });
-        }
-    }
-    const secrets = new Set(scenario.secret_aliases);
-    for (const alias of secrets) {
-        if (!(alias in scenario.environment)) {
-            context.addIssue({
-                code: "custom",
-                message: "secret alias has no environment value",
-                path: ["secret_aliases"],
-            });
-        }
-    }
-    const explicit = new Set(Object.keys(scenario.environment));
-    for (const name of [...explicit, ...scenario.inherit_environment]) {
-        if (reservedEnvironment.has(name)) {
-            context.addIssue({
-                code: "custom",
-                message: `${name} is reserved by the process adapter`,
-                path: ["environment", name],
-            });
-        }
-    }
-    for (const name of scenario.inherit_environment) {
-        if (explicit.has(name)) {
-            context.addIssue({
-                code: "custom",
-                message: "an environment name cannot be explicit and inherited",
-                path: ["inherit_environment"],
-            });
-        }
-    }
-    for (const event of scenario.events) {
-        if (event.at_ms > scenario.timeout_ms) {
-            context.addIssue({
-                code: "custom",
-                message: "event occurs after the scenario timeout",
-                path: ["events"],
-            });
-        }
-    }
+const fileEffectSchema = z.object({
+    path: z.string(),
+    status: z.enum(["created", "modified", "deleted", "unchanged"]),
+    before: fileStateSchema.nullable(),
+    after: fileStateSchema.nullable(),
 });
-/** Parse untrusted process scenario input and apply safe default budgets. */
-export const parseProcessScenario = (input) => processScenarioSchema.parse(input);
-const isWithin = (candidate, root) => resolve(candidate) === resolve(root) ||
-    resolve(candidate).startsWith(`${resolve(root)}${resolve(root).endsWith("/") ? "" : "/"}`);
-/** Evaluate scenario authority before any process or filesystem side effect occurs. */
-export const authorizeProcessScenario = (scenario, policy) => {
-    if (!policy.enabled)
-        return { allowed: false, reason: "process capture is disabled" };
-    if (scenario.network_access === "host" && !policy.allowExternalNetwork)
-        return {
-            allowed: false,
-            reason: "host network access is not approved by operator policy",
-        };
-    if (!policy.executableRoots.some((root) => isWithin(scenario.executable, root))) {
-        return { allowed: false, reason: "executable is outside approved roots" };
-    }
-    if (!policy.workingRoots.some((root) => isWithin(scenario.working_directory, root))) {
-        return {
-            allowed: false,
-            reason: "working directory is outside approved roots",
-        };
-    }
-    const requestedNames = [
-        ...Object.keys(scenario.environment),
-        ...scenario.inherit_environment,
-    ];
-    if (requestedNames.some((name) => !policy.allowedEnvironment.includes(name))) {
-        return {
-            allowed: false,
-            reason: "scenario requests an environment variable not allowed by policy",
-        };
-    }
-    if (scenario.filesystem_roots.some((path) => !policy.workingRoots.some((root) => isWithin(path, root)))) {
-        return {
-            allowed: false,
-            reason: "filesystem root is outside approved roots",
-        };
-    }
-    return { allowed: true };
-};
 /** Exact serialized shape of a bounded process capture. */
 export const processCaptureSchema = z.object({
-    schema_version: z.literal(2),
+    schema_version: z.literal(4, {
+        error: LEGACY_PROCESS_CAPTURE_MESSAGE,
+    }),
+    manifest: z.object({
+        rea_version: z.string().min(1),
+        provider_version: z.string().min(1),
+        platform: z.string().min(1),
+        architecture: z.string().min(1),
+        pty_backend: z.literal("node-pty"),
+        started_at: z.iso.datetime(),
+        completed_at: z.iso.datetime(),
+        scenario: z.record(z.string(), z.unknown()),
+        comparison_contract: z.record(z.string(), z.unknown()),
+        shim_plan: z.array(z.unknown()),
+        replay_plan: z.record(z.string(), z.unknown()),
+        full_scenario_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        comparison_contract_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        normalization_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        shim_plan_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        replay_plan_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
     normalization: normalizationSchema,
     frames: z.array(z.object({
         sequence: z.number().int().nonnegative(),
         at_ms: z.number().int().nonnegative(),
         data: z.string(),
     })),
+    rendered_frames: z.array(z.object({
+        sequence: z.number().int().nonnegative(),
+        at_ms: z.number().int().nonnegative(),
+        columns: z.number().int().positive(),
+        rows: z.number().int().positive(),
+        cursor_x: z.number().int().nonnegative(),
+        cursor_y: z.number().int().nonnegative(),
+        active_buffer: z.enum(["normal", "alternate"]),
+        lines: z.array(z.string()),
+        serialized_state: z.string(),
+    })),
+    interaction_events: z.array(z.object({
+        sequence: z.number().int().nonnegative(),
+        scheduled_at_ms: z.number().int().nonnegative(),
+        dispatched_at_ms: z.number().int().nonnegative(),
+        type: z.enum(["input", "resize", "signal"]),
+        data: z.string(),
+        outcome: z.enum(["dispatched", "target_exited", "failed"]),
+    })),
     exit: z.object({
         code: z.number().int().nullable(),
         signal: z.number().int().nullable(),
         reason: z.enum(["exited", "timeout", "idle_timeout"]),
     }),
+    settlement: z.object({
+        state: z.enum(["quiesced", "alive_at_deadline", "unverifiable"]),
+        elapsed_ms: z.number().int().nonnegative(),
+        cleanup_outcome: z.enum(["not_required", "cleaned", "failed"]),
+    }),
     process_samples: z.array(z.object({
         at_ms: z.number().int().nonnegative(),
         pid: z.number().int().positive(),
         parent_pid: z.number().int().nonnegative(),
         command: z.string(),
+        process_group_id: z.number().int().positive().nullable(),
+        session_id: z.number().int().nonnegative().nullable(),
+    })),
+    filesystem_checkpoints: z.array(z.object({
+        name: z.string(),
+        at_ms: z.number().int().nonnegative(),
+        files: z.array(fileStateSchema),
+        effects: z.array(fileEffectSchema),
+        truncated: z.boolean(),
+    })),
+    shim_events: z.array(z.object({
+        sequence: z.number().int().nonnegative(),
+        at_ms: z.number().int().nonnegative(),
+        command: z.string(),
+        route_index: z.number().int().nonnegative().nullable(),
+        arguments: z.array(z.string()),
+        working_directory: z.string(),
+        outcome: z.enum(["matched", "unmatched", "exhausted"]),
     })),
     protocol_events: z.array(z.object({
         sequence: z.number().int().nonnegative(),
@@ -276,58 +116,9 @@ export const processCaptureSchema = z.object({
             "disconnected",
         ]),
     })),
-    files_before: z.array(z.object({
-        path: z.string(),
-        type: z.enum(["file", "directory", "symlink", "other"]),
-        mode: z.number().int().nonnegative(),
-        size: z.number().int().nonnegative(),
-        sha256: z
-            .string()
-            .regex(/^[a-f0-9]{64}$/u)
-            .nullable(),
-        symlink_target: z.string().nullable(),
-    })),
-    files_after: z.array(z.object({
-        path: z.string(),
-        type: z.enum(["file", "directory", "symlink", "other"]),
-        mode: z.number().int().nonnegative(),
-        size: z.number().int().nonnegative(),
-        sha256: z
-            .string()
-            .regex(/^[a-f0-9]{64}$/u)
-            .nullable(),
-        symlink_target: z.string().nullable(),
-    })),
-    filesystem_effects: z.array(z.object({
-        path: z.string(),
-        status: z.enum(["created", "modified", "deleted", "unchanged"]),
-        before: z
-            .object({
-            path: z.string(),
-            type: z.enum(["file", "directory", "symlink", "other"]),
-            mode: z.number().int().nonnegative(),
-            size: z.number().int().nonnegative(),
-            sha256: z
-                .string()
-                .regex(/^[a-f0-9]{64}$/u)
-                .nullable(),
-            symlink_target: z.string().nullable(),
-        })
-            .nullable(),
-        after: z
-            .object({
-            path: z.string(),
-            type: z.enum(["file", "directory", "symlink", "other"]),
-            mode: z.number().int().nonnegative(),
-            size: z.number().int().nonnegative(),
-            sha256: z
-                .string()
-                .regex(/^[a-f0-9]{64}$/u)
-                .nullable(),
-            symlink_target: z.string().nullable(),
-        })
-            .nullable(),
-    })),
+    files_before: z.array(fileStateSchema),
+    files_after: z.array(fileStateSchema),
+    filesystem_effects: z.array(fileEffectSchema),
     truncated: z.boolean(),
     limitations: z.array(z.string()),
     residual_unknowns: z.array(z.object({
@@ -347,4 +138,19 @@ export const processCaptureSchema = z.object({
         temporary_root: z.literal("removed"),
     }),
 });
+export { validateProcessCapture } from "./processCaptureValidation.js";
+import { validateProcessCapture } from "./processCaptureValidation.js";
+/** Parse unknown input as v4 and reject invalid commitments or semantics. */
+export const parseProcessCapture = (input) => {
+    if (typeof input === "object" &&
+        input !== null &&
+        "schema_version" in input &&
+        input.schema_version === 3)
+        throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
+    const capture = processCaptureSchema.parse(input);
+    const issues = validateProcessCapture(capture);
+    if (issues.length > 0)
+        throw new TypeError(`Invalid Process Capture v4: ${issues.map(({ path, message }) => `${path}: ${message}`).join("; ")}`);
+    return capture;
+};
 export { compareProcessCaptures, comparisonStatusSchema, processCaptureComparisonSchema, } from "./processComparison.js";

package/dist/domain/processCaptureValidation.js

@@ -0,0 +1,124 @@
+import { digestProcessCommitment } from "./processScenario.js";
+const orderedTimestamps = (values) => values.every((value, index) => index === 0 || value.at_ms >= values[index - 1].at_ms);
+const validateCommitments = (capture, require) => {
+    const { manifest } = capture;
+    require(manifest.scenario.executable_sha256 ===
+        manifest.executable_sha256, "manifest.executable_sha256", "executable commitment does not match the scenario projection");
+    for (const [field, value] of [
+        ["full_scenario_sha256", manifest.scenario],
+        ["comparison_contract_sha256", manifest.comparison_contract],
+        ["normalization_sha256", capture.normalization],
+        ["shim_plan_sha256", manifest.shim_plan],
+        ["replay_plan_sha256", manifest.replay_plan],
+    ])
+        require(manifest[field] ===
+            digestProcessCommitment(value), `manifest.${field}`, "commitment does not match its canonical value");
+    require(Date.parse(manifest.started_at) <=
+        Date.parse(manifest.completed_at), "manifest.completed_at", "completion precedes start");
+};
+const validateOrdering = (capture, require) => {
+    for (const [name, values] of [
+        ["frames", capture.frames],
+        ["rendered_frames", capture.rendered_frames],
+        ["interaction_events", capture.interaction_events],
+        ["shim_events", capture.shim_events],
+        ["protocol_events", capture.protocol_events],
+    ])
+        require(values.every(({ sequence }, index) => sequence === index), name, "sequence values must be contiguous from zero");
+    for (const [name, values] of [
+        ["frames", capture.frames],
+        ["rendered_frames", capture.rendered_frames],
+        ["process_samples", capture.process_samples],
+        ["filesystem_checkpoints", capture.filesystem_checkpoints],
+        ["shim_events", capture.shim_events],
+        ["protocol_events", capture.protocol_events],
+    ])
+        require(orderedTimestamps(values), name, "timestamps must be ordered");
+};
+const validateLifecycle = (capture, require) => {
+    const checkpointNames = capture.filesystem_checkpoints.map(({ name }) => name);
+    require(new Set(checkpointNames).size ===
+        checkpointNames.length, "filesystem_checkpoints", "checkpoint names must be unique");
+    require(checkpointNames[0] ===
+        "before", "filesystem_checkpoints", "first checkpoint must be before");
+    require(checkpointNames.at(-1) ===
+        "after_settlement", "filesystem_checkpoints", "last checkpoint must be after_settlement");
+    require(!capture.filesystem_checkpoints.some(({ truncated }) => truncated) ||
+        capture.truncated, "truncated", "checkpoint truncation must propagate to the capture");
+    require(capture.exit.reason === "exited" ||
+        capture.exit.code ===
+            null, "exit", "deadline termination cannot declare a normal exit code");
+    require(capture.settlement.state !== "quiesced" ||
+        capture.settlement.cleanup_outcome ===
+            "not_required", "settlement.cleanup_outcome", "quiesced settlement cannot require cleanup");
+    require(capture.settlement.state === "quiesced" ||
+        capture.settlement.cleanup_outcome !==
+            "not_required", "settlement.cleanup_outcome", "non-quiesced settlement must report cleanup");
+};
+const shimPlans = (capture) => capture.manifest.shim_plan.flatMap((shim) => typeof shim === "object" &&
+    shim !== null &&
+    "name" in shim &&
+    "routes" in shim &&
+    typeof shim.name === "string" &&
+    Array.isArray(shim.routes)
+    ? shim.routes.map((route, routeIndex) => ({
+        command: shim.name,
+        route,
+        routeIndex,
+    }))
+    : []);
+const validateShimEvents = (capture, require) => {
+    const plans = shimPlans(capture);
+    for (const event of capture.shim_events) {
+        const declared = plans.some(({ command, routeIndex }) => command === event.command && routeIndex === event.route_index);
+        require(event.outcome === "unmatched"
+            ? event.route_index === null
+            : declared, "shim_events", "shim event has no declared route");
+    }
+    for (const plan of plans) {
+        const maximum = typeof plan.route === "object" &&
+            plan.route !== null &&
+            "max_calls" in plan.route &&
+            typeof plan.route.max_calls === "number"
+            ? plan.route.max_calls
+            : 0;
+        const matches = capture.shim_events.filter((event) => event.command === plan.command &&
+            event.route_index === plan.routeIndex &&
+            event.outcome === "matched").length;
+        require(matches <=
+            maximum, "shim_events", "matched shim events exceed the declared route max_calls");
+    }
+};
+const validateReplayEvents = (capture, require) => {
+    const { replay_plan: replayPlan } = capture.manifest;
+    const routes = "http" in replayPlan && Array.isArray(replayPlan.http)
+        ? replayPlan.http
+        : [];
+    for (const event of capture.protocol_events) {
+        if (event.protocol !== "http" ||
+            event.direction !== "request" ||
+            event.outcome !== "matched")
+            continue;
+        const declared = routes.some((route) => typeof route === "object" &&
+            route !== null &&
+            "method" in route &&
+            route.method === event.method &&
+            "path" in route &&
+            route.path === event.path);
+        require(declared, "protocol_events", "matched HTTP event has no declared replay route");
+    }
+};
+/** Recompute v4 commitments and cross-field invariants without side effects. */
+export const validateProcessCapture = (capture) => {
+    const issues = [];
+    const require = (condition, path, message) => {
+        if (!condition)
+            issues.push({ path, message });
+    };
+    validateCommitments(capture, require);
+    validateOrdering(capture, require);
+    validateLifecycle(capture, require);
+    validateShimEvents(capture, require);
+    validateReplayEvents(capture, require);
+    return issues;
+};