reverseport 0.0.0-stage → 1.2.0

package/dist/domain/process/processObservation.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../jsonValue.js";
+/** Project normalized PTY facts without source text used only for audit. */
+export const comparableTerminalFrame = (frame) => ({
+    sequence: frame.sequence,
+    at_ms: frame.at_ms,
+    data: frame.data,
+});
+/** Process-capture observation families shared by live drivers and trace assertions. */
+export const processObservationSourceSchema = z.enum([
+    "terminal_raw",
+    "terminal_rendered",
+    "interaction",
+    "lifecycle",
+    "process",
+    "filesystem",
+]);
+/** Stable raw-record location within one Process Capture observation journal. */
+export const processObservationLocationSchema = z.strictObject({
+    collection: z.enum([
+        "frames",
+        "rendered_frames",
+        "interaction_events",
+        "lifecycle",
+        "process_samples",
+        "filesystem_checkpoints",
+    ]),
+    index: z.number().int().nonnegative(),
+    capture_order: z.number().int().nonnegative(),
+});
+/** Remove only explicitly declared top-level volatile fields before matching. */
+export const comparableProcessObservationPayload = (value, ignoredFields = []) => {
+    if (ignoredFields.length === 0 ||
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([name]) => !ignoredFields.includes(name)));
+};
+/** Construct a validated observation from one live producer record. */
+export const createProcessObservation = (input) => ({
+    event_id: `obs.${input.location.collection}.${String(input.location.index)}`,
+    source: input.source,
+    source_sequence: input.source_sequence,
+    capture_order: input.location.capture_order,
+    captured_at_ms: input.captured_at_ms,
+    subject_id: input.subject_id,
+    location: input.location,
+    payload: jsonValueSchema.parse(input.payload),
+});
+const atMilliseconds = (value) => {
+    if (typeof value !== "object" || value === null)
+        return null;
+    if ("at_ms" in value && isSafeMillisecond(value.at_ms))
+        return value.at_ms;
+    if ("dispatched_at_ms" in value && isSafeMillisecond(value.dispatched_at_ms))
+        return value.dispatched_at_ms;
+    return null;
+};
+const isSafeMillisecond = (value) => typeof value === "number" && Number.isSafeInteger(value);
+/** Derive the stable capture-local identity for one normalized observation. */
+export const processObservationSubject = (source, value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    if (source === "process" && "pid" in value && typeof value.pid === "number")
+        return `process:${String(value.pid)}`;
+    if (source === "filesystem" &&
+        "name" in value &&
+        typeof value.name === "string")
+        return `checkpoint:${value.name}`;
+    return null;
+};
+const projectedRecord = (capture, location) => {
+    const projected = (() => {
+        switch (location.collection) {
+            case "frames": {
+                const frame = capture.frames[location.index];
+                return {
+                    source: "terminal_raw",
+                    value: frame === undefined ? undefined : comparableTerminalFrame(frame),
+                };
+            }
+            case "rendered_frames":
+                return {
+                    source: "terminal_rendered",
+                    value: capture.rendered_frames[location.index],
+                };
+            case "interaction_events":
+                return {
+                    source: "interaction",
+                    value: capture.interaction_events[location.index],
+                };
+            case "lifecycle":
+                return location.index === 0
+                    ? {
+                        source: "lifecycle",
+                        value: { event: "exit", ...capture.exit },
+                    }
+                    : location.index === 1
+                        ? {
+                            source: "lifecycle",
+                            value: { event: "settlement", ...capture.settlement },
+                        }
+                        : null;
+            case "process_samples":
+                return {
+                    source: "process",
+                    value: capture.process_samples[location.index],
+                };
+            case "filesystem_checkpoints":
+                return {
+                    source: "filesystem",
+                    value: capture.filesystem_checkpoints[location.index],
+                };
+        }
+    })();
+    if (projected === null || projected.value === undefined)
+        return null;
+    const payload = jsonValueSchema.parse(projected.value);
+    return {
+        source: projected.source,
+        captured_at_ms: atMilliseconds(payload),
+        subject_id: processObservationSubject(projected.source, payload),
+        payload,
+    };
+};
+/** Project one validated capture-journal reference into the shared observation shape. */
+export const projectProcessObservation = (capture, location) => {
+    const projected = projectedRecord(capture, location);
+    if (projected === null)
+        return null;
+    return createProcessObservation({
+        source: projected.source,
+        source_sequence: location.index,
+        captured_at_ms: projected.captured_at_ms,
+        subject_id: projected.subject_id,
+        location,
+        payload: projected.payload,
+    });
+};

package/dist/domain/process/processScenario.js

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const positiveBudget = z.number().int().safe().positive();
+/**
+ * Maximum xterm backing cells for one visible-plus-scrollback buffer. Each
+ * xterm BufferLine stores three Uint32 words per cell (12 MB at this cap),
+ * before row objects, serialization strings, and retained frame copies.
+ */
+export const PROCESS_TERMINAL_CELL_BUDGET = 1_000_000;
+const timedEventBase = { at_ms: z.number().int().safe().nonnegative() };
+const reservedRunIdEnvironmentName = "REA_PROCESS_RUN_ID";
+const ENVIRONMENT_NAME_CHARACTER = "[^=\\x00]";
+/**
+ * Nonempty environment names other than the reserved run identifier. The
+ * exclusion is spelled as a complement instead of a negative look-ahead,
+ * because RE2 and Rust schema validators reject look-around and would refuse
+ * every tool in the advertised catalog.
+ */
+const environmentNamePattern = (reserved) => {
+    // After the complete reserved name, at least one more character is needed.
+    let rest = `${ENVIRONMENT_NAME_CHARACTER}+`;
+    for (let index = reserved.length - 1; index >= 0; index -= 1) {
+        const character = reserved[index] ?? "";
+        // Diverge here, match the next reserved character, or (after a nonempty
+        // prefix) end the name early.
+        const choice = `[^=\\x00${character}]${ENVIRONMENT_NAME_CHARACTER}*|${character}${rest}`;
+        rest = index === 0 ? choice : `(?:${choice})?`;
+    }
+    return new RegExp(`^(?:${rest})$`, "u");
+};
+const environmentName = z
+    .string()
+    .min(1, "Environment names must not be empty")
+    .regex(environmentNamePattern(reservedRunIdEnvironmentName), {
+    error: (issue) => issue.input === reservedRunIdEnvironmentName
+        ? `${reservedRunIdEnvironmentName} is reserved by the process adapter`
+        : "Environment names cannot contain '=' or NUL",
+});
+const childProcessString = z
+    .string()
+    .regex(/^[^\x00]*$/u, "Values passed to operating-system APIs cannot contain NUL");
+const fitsProcessTerminalCellBudget = (columns, rows, scrollback) => rows + scrollback <= Math.floor(PROCESS_TERMINAL_CELL_BUDGET / columns);
+export const normalizationSchema = z.object({
+    paths: z.boolean(),
+    pids: z.boolean(),
+    ports: z.boolean(),
+    time_bucket_ms: positiveBudget,
+    patterns: z.array(z.object({
+        pattern: z.string(),
+        replacement: z.string(),
+    })),
+});
+/** Compute a canonical SHA-256 commitment independent of object key order. */
+export const digestProcessCommitment = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Process capture commitment is not canonical JSON");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+const committedScenarioEvents = (events, includeSensitiveInputLength) => events.map((event) => event.type === "input" && event.sensitive
+    ? {
+        ...event,
+        data: includeSensitiveInputLength
+            ? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
+            : "<redacted-input>",
+    }
+    : event);
+/** Build the caller-selected scenario projection committed by process-capture Evidence. */
+export const processScenarioCommitment = (scenario, executableSha256) => {
+    // A zero interval is today's immediate kill; leaving it out keeps the
+    // committed identity of every scenario that predates the field unchanged.
+    const { finalization_ms: finalizationMs, ...committed } = scenario;
+    return {
+        ...committed,
+        ...(finalizationMs > 0 ? { finalization_ms: finalizationMs } : {}),
+        events: committedScenarioEvents(scenario.events, true),
+        executable_sha256: executableSha256 ?? null,
+    };
+};
+/** Project observation settings shared by capture and reconstruction. */
+export const processComparisonContract = (scenario) => ({
+    working_directory: scenario.working_directory,
+    environment: scenario.environment,
+    ambient_environment: "unknown",
+    filesystem_observation_paths: scenario.filesystem_observation_paths,
+    terminal: scenario.terminal,
+    // Input bytes are intentionally absent from compatibility identity. Their
+    // redacted observations remain unknown, so equal commitments never imply
+    // that two secret values were the same.
+    events: committedScenarioEvents(scenario.events, false),
+    timeout_ms: scenario.timeout_ms,
+    idle_timeout_ms: scenario.idle_timeout_ms,
+    settle_ms: scenario.settle_ms,
+    ...(scenario.finalization_ms > 0
+        ? { finalization_ms: scenario.finalization_ms }
+        : {}),
+    limits: scenario.limits,
+    normalization: scenario.normalization,
+    ...(scenario.normalization.ports
+        ? { port_normalization_version: "contextual-endpoints-v2" }
+        : {}),
+    ...(scenario.normalization.patterns.length > 0
+        ? { pattern_normalization_version: "literal-replacements-v1" }
+        : {}),
+    rendered_line_format: "trailing-spaces-trimmed-v1",
+});
+/**
+ * Boundary schema for one bounded process experiment.
+ * Defaults are part of the evidence contract and must remain deterministic.
+ */
+export const processScenarioSchema = z
+    .strictObject({
+    executable: childProcessString.min(1),
+    arguments: z.array(childProcessString).default([]),
+    working_directory: childProcessString.default("."),
+    environment: z.record(environmentName, childProcessString).default({}),
+    filesystem_observation_paths: z
+        .array(childProcessString.min(1))
+        .default([]),
+    terminal: z
+        .strictObject({
+        columns: z.number().int().min(1).max(65_535).default(80),
+        rows: z.number().int().min(1).max(65_535).default(24),
+        scrollback: z.number().int().safe().nonnegative().default(1_000),
+    })
+        .describe("The visible terminal and scrollback together must use at most 1,000,000 xterm renderer cells: columns × (rows + scrollback). Resize events use the same scrollback and limit.")
+        .default({ columns: 80, rows: 24, scrollback: 1_000 }),
+    events: z
+        .array(z.discriminatedUnion("type", [
+        z.strictObject({
+            ...timedEventBase,
+            type: z.literal("input"),
+            data: z.string(),
+            sensitive: z.boolean().default(false),
+        }),
+        z.strictObject({
+            ...timedEventBase,
+            type: z.literal("resize"),
+            columns: z.number().int().min(1).max(65_535),
+            rows: z.number().int().min(1).max(65_535),
+        }),
+        z.strictObject({
+            ...timedEventBase,
+            type: z.literal("signal"),
+            signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),
+        }),
+    ]))
+        .default([]),
+    timeout_ms: positiveBudget.default(30_000),
+    idle_timeout_ms: positiveBudget.default(30_000),
+    settle_ms: z.number().int().safe().nonnegative().default(100),
+    finalization_ms: z
+        .number()
+        .int()
+        .safe()
+        .nonnegative()
+        .default(0)
+        .describe("Milliseconds a target may keep running after SIGTERM when timeout_ms or idle_timeout_ms fires, before SIGKILL; 0 sends SIGKILL immediately. Both signals reach the captured root only while its launch-time start identity still matches; cancellation ends the run at once."),
+    limits: z
+        .strictObject({
+        output_bytes: positiveBudget.default(1_000_000),
+        files: positiveBudget.default(10_000),
+        file_bytes: positiveBudget.default(10_000_000),
+        processes: positiveBudget.default(1_000),
+        filesystem_depth: z.number().int().safe().nonnegative().default(16),
+    })
+        .strict()
+        .default({
+        output_bytes: 1_000_000,
+        files: 10_000,
+        file_bytes: 10_000_000,
+        processes: 1_000,
+        filesystem_depth: 16,
+    }),
+    normalization: z
+        .strictObject({
+        paths: z.boolean().default(false),
+        pids: z.boolean().default(true),
+        ports: z.boolean().default(true),
+        time_bucket_ms: positiveBudget.default(10),
+        patterns: z
+            .array(z.strictObject({
+            pattern: z
+                .string()
+                .describe("Literal text to replace in captured output; not a regular expression."),
+            replacement: z.string(),
+        }))
+            .default([]),
+    })
+        .default({
+        paths: false,
+        pids: true,
+        ports: true,
+        time_bucket_ms: 10,
+        patterns: [],
+    }),
+})
+    .superRefine((scenario, context) => {
+    // Each budget is a safe integer, but their sum is not checked anywhere
+    // else. BigInt keeps the comparison exact beyond the representable range.
+    const lifecycleBudget = BigInt(scenario.timeout_ms) +
+        BigInt(scenario.finalization_ms) +
+        BigInt(scenario.settle_ms);
+    if (lifecycleBudget > BigInt(Number.MAX_SAFE_INTEGER))
+        context.addIssue({
+            code: "custom",
+            message: `timeout_ms + finalization_ms + settle_ms must stay at or below ${String(Number.MAX_SAFE_INTEGER)} ms, the largest total exactly representable as a JavaScript number`,
+            path: ["timeout_ms"],
+        });
+    if (!fitsProcessTerminalCellBudget(scenario.terminal.columns, scenario.terminal.rows, scenario.terminal.scrollback))
+        context.addIssue({
+            code: "custom",
+            path: ["terminal"],
+            message: `terminal columns × (rows + scrollback) must not exceed ${String(PROCESS_TERMINAL_CELL_BUDGET)} renderer cells`,
+        });
+    for (let index = 1; index < scenario.events.length; index += 1) {
+        const event = scenario.events[index];
+        const previous = scenario.events[index - 1];
+        if (eventsOutOfOrder(event, previous)) {
+            context.addIssue({
+                code: "custom",
+                message: "events must be ordered by at_ms",
+                path: ["events", index],
+            });
+        }
+    }
+    for (const [index, event] of scenario.events.entries()) {
+        if (event.type === "resize" &&
+            !fitsProcessTerminalCellBudget(event.columns, event.rows, scenario.terminal.scrollback))
+            context.addIssue({
+                code: "custom",
+                path: ["events", index],
+                message: `resize event at ${String(event.at_ms)} ms exceeds the ${String(PROCESS_TERMINAL_CELL_BUDGET)}-cell renderer budget with the selected scrollback`,
+            });
+        if (event.at_ms > scenario.timeout_ms) {
+            context.addIssue({
+                code: "custom",
+                message: "event occurs after the scenario timeout",
+                path: ["events"],
+            });
+        }
+    }
+});
+const eventsOutOfOrder = (event, previous) => event !== undefined && previous !== undefined && event.at_ms < previous.at_ms;
+/** Parse untrusted process scenario input and apply safe default budgets. */
+export const parseProcessScenario = (input) => processScenarioSchema.parse(input);

package/dist/domain/process/processTraceComparison.js

@@ -0,0 +1,34 @@
+import { evaluateProcessTraceSide, processTraceComparisonResultSchema, } from "./processTraceEvaluation.js";
+import { processTraceSpecificationSchema, } from "./processTraceSpecification.js";
+/** Compare two captures against an explicit finite trace language. */
+export const compareProcessTraces = (left, right, specificationInput) => {
+    const specification = processTraceSpecificationSchema.parse(specificationInput);
+    const leftEvaluation = evaluateProcessTraceSide(left, specification);
+    const rightEvaluation = evaluateProcessTraceSide(right, specification);
+    const diagnostic = leftEvaluation.diagnostic === null
+        ? rightEvaluation.diagnostic === null
+            ? null
+            : { side: "right", ...rightEvaluation.diagnostic }
+        : { side: "left", ...leftEvaluation.diagnostic };
+    const outcomesDiffer = leftEvaluation.result.status !== rightEvaluation.result.status ||
+        JSON.stringify(leftEvaluation.result.raw_trace.map(({ event_id }) => event_id)) !==
+            JSON.stringify(rightEvaluation.result.raw_trace.map(({ event_id }) => event_id));
+    return processTraceComparisonResultSchema.parse({
+        verdict: leftEvaluation.result.status === "unknown" ||
+            rightEvaluation.result.status === "unknown"
+            ? "unknown"
+            : leftEvaluation.result.status === "pass" &&
+                rightEvaluation.result.status === "pass"
+                ? "equivalent"
+                : outcomesDiffer
+                    ? "different"
+                    : "nonconforming",
+        left: leftEvaluation.result,
+        right: rightEvaluation.result,
+        diagnostic,
+    });
+};
+/** Whether trace conformance or raw declared order differs across captures. */
+export const processTraceOutcomesDiffer = (comparison) => comparison.left.status !== comparison.right.status ||
+    JSON.stringify(comparison.left.raw_trace.map(({ event_id }) => event_id)) !==
+        JSON.stringify(comparison.right.raw_trace.map(({ event_id }) => event_id));

package/dist/domain/process/processTraceDimensionProjection.js

@@ -0,0 +1,35 @@
+/** Map declared trace sources to process-comparison dimensions. */
+export const dimensionsForTraceSources = (sources) => {
+    const dimensions = new Set();
+    for (const source of sources) {
+        if (source.startsWith("terminal_"))
+            dimensions.add("terminal");
+        else if (source === "interaction")
+            dimensions.add("interaction");
+        else if (source === "lifecycle")
+            dimensions.add("exit");
+        else if (source === "filesystem")
+            dimensions.add("filesystem");
+        else if (source === "process")
+            dimensions.add("process");
+    }
+    return dimensions;
+};
+/** Whether a trace specification covers every observed source in a dimension. */
+export const traceCoversObservedDimension = (dimension, sources, left, right) => {
+    const any = (leftValues, rightValues) => leftValues.length > 0 || rightValues.length > 0;
+    switch (dimension) {
+        case "terminal":
+            return ((!any(left.frames, right.frames) || sources.has("terminal_raw")) &&
+                (!any(left.rendered_frames, right.rendered_frames) ||
+                    sources.has("terminal_rendered")));
+        case "interaction":
+            return sources.has("interaction");
+        case "exit":
+            return sources.has("lifecycle");
+        case "filesystem":
+            return false;
+        case "process":
+            return sources.has("process");
+    }
+};