rea-agents 2.5.0 → 3.0.0

package/dist/domain/conformancePackage.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { evidenceEnvelopeSchema } from "./evidence.js";
+import { evidenceBundleSchema } from "./evidenceBundle.js";
+/** Schema version for the conformance package format. */
+export const CONFORMANCE_PACKAGE_VERSION = 1;
+/** A stable, path-independent identifier for a conformance package. */
+export const conformancePackageIdSchema = z
+    .string()
+    .regex(/^cp_[a-f0-9]{64}$/u);
+/** Identifier for a single scenario within a package. */
+export const scenarioIdSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
+/** Deterministic manifest for a scenario fixture. */
+export const scenarioManifestSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    name: z.string().min(1),
+    description: z.string().min(1),
+    /** Source-owned fixture path relative to the repository root. */
+    fixture_path: z.string().min(1),
+    /** Expected exit code or null if unspecified. */
+    expected_exit_code: z.number().int().nullable(),
+    /** Expected output patterns that must appear in the capture. */
+    expected_patterns: z.array(z.string()).default([]),
+});
+/** Replay plan describing how a scenario is replayed deterministically. */
+export const replayPlanSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Ordered steps to execute during replay. */
+    steps: z
+        .array(z.strictObject({
+        step_id: z.string().min(1),
+        action: z.string().min(1),
+        arguments: z.array(z.string()).default([]),
+        timeout_ms: z.number().int().positive(),
+    }))
+        .min(1)
+        .max(100),
+    /** Environment variables to set (never inherit host paths). */
+    environment: z.record(z.string(), z.string()).default({}),
+});
+/** Shim plan for intercepting observable effects. */
+export const shimPlanSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Shims to install, each intercepting a named effect. */
+    shims: z
+        .array(z.strictObject({
+        shim_id: z.string().min(1),
+        kind: z.enum(["filesystem", "network", "process", "signal"]),
+        target: z.string().min(1),
+        policy: z.enum(["observe", "allow", "block", "emulate"]),
+    }))
+        .min(0)
+        .max(50),
+});
+/** Expected evidence for a scenario, checked against the captured run. */
+export const expectedEvidenceSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Expected evidence envelopes. */
+    envelopes: z.array(evidenceEnvelopeSchema).min(0).max(100),
+    /** Expected evidence bundle. */
+    bundle: evidenceBundleSchema.nullable(),
+    /** Required dimensions that must be present in the evidence. */
+    required_dimensions: z.array(z.string().min(1)).default([]),
+});
+/** Verifier contract describing how to validate conformance. */
+export const verifierContractSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Dimensions to verify. */
+    dimensions: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        required: z.boolean().default(true),
+        comparison: z.enum(["exact", "semantic", "fuzzy"]),
+    }))
+        .min(1)
+        .max(50),
+    /** Tolerance for timing differences in milliseconds. */
+    timing_tolerance_ms: z.number().int().nonnegative().default(0),
+});
+/** Top-level conformance package manifest. */
+export const conformancePackageSchema = z.strictObject({
+    schema_version: z.literal(CONFORMANCE_PACKAGE_VERSION),
+    package_id: conformancePackageIdSchema,
+    name: z.string().min(1),
+    description: z.string().min(1),
+    created_at: z.string().datetime(),
+    /** Scenario manifests. */
+    scenarios: z.array(scenarioManifestSchema).min(1).max(100),
+    /** Replay plans keyed by scenario_id. */
+    replay_plans: z.array(replayPlanSchema).min(1).max(100),
+    /** Shim plans keyed by scenario_id. */
+    shim_plans: z.array(shimPlanSchema).default([]),
+    /** Expected evidence for each scenario. */
+    expected_evidence: z.array(expectedEvidenceSchema).min(1).max(100),
+    /** Verifier contracts for each scenario. */
+    verifier_contracts: z.array(verifierContractSchema).min(1).max(100),
+});
+/** Validate a conformance package and cross-check internal references. */
+export function validateConformancePackage(input) {
+    const parsed = conformancePackageSchema.safeParse(input);
+    if (!parsed.success)
+        return {
+            ok: false,
+            error: {
+                kind: "invalid_package",
+                message: parsed.error.issues[0]?.message ?? "invalid package",
+            },
+        };
+    const pkg = parsed.data;
+    // Check for duplicate scenario IDs
+    const seen = new Set();
+    for (const s of pkg.scenarios) {
+        if (seen.has(s.scenario_id))
+            return {
+                ok: false,
+                error: { kind: "duplicate_scenario", scenario_id: s.scenario_id },
+            };
+        seen.add(s.scenario_id);
+    }
+    // Check that replay plans reference existing scenarios
+    for (const rp of pkg.replay_plans) {
+        if (!seen.has(rp.scenario_id))
+            return {
+                ok: false,
+                error: {
+                    kind: "scenario_not_found",
+                    scenario_id: rp.scenario_id,
+                },
+            };
+    }
+    // Check that expected evidence references existing scenarios
+    for (const ee of pkg.expected_evidence) {
+        if (!seen.has(ee.scenario_id))
+            return {
+                ok: false,
+                error: {
+                    kind: "scenario_not_found",
+                    scenario_id: ee.scenario_id,
+                },
+            };
+    }
+    // Check that verifier contracts reference existing scenarios
+    for (const vc of pkg.verifier_contracts) {
+        if (!seen.has(vc.scenario_id))
+            return {
+                ok: false,
+                error: {
+                    kind: "scenario_not_found",
+                    scenario_id: vc.scenario_id,
+                },
+            };
+    }
+    return { ok: true, value: pkg };
+}
+/** Compute a deterministic package ID from the canonical JSON. */
+export function computePackageId(pkg) {
+    const json = canonicalize(pkg);
+    if (!json)
+        throw new Error("failed to canonicalize package");
+    return `cp_${createHash("sha256").update(json).digest("hex")}`;
+}
+/** Create a conformance package with an auto-computed package_id. */
+export function createConformancePackage(pkg) {
+    const package_id = computePackageId(pkg);
+    return { package_id, ...pkg };
+}

package/dist/domain/conformanceReplay.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { conformancePackageSchema, } from "./conformancePackage.js";
+import { trustGateResultSchema } from "./conformanceTrustGate.js";
+/** Result of a single scenario replay. */
+export const scenarioReplayResultSchema = z.strictObject({
+    scenario_id: z.string().min(1),
+    status: z.enum(["pass", "fail", "error", "skipped"]),
+    exit_code: z.number().int().nullable(),
+    duration_ms: z.number().int().nonnegative(),
+    output: z.string().default(""),
+    error: z.string().nullable(),
+});
+/** Result of replaying an entire conformance package. */
+export const packageReplayResultSchema = z.strictObject({
+    package_id: z.string().min(1),
+    total_scenarios: z.number().int().positive(),
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    errored: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    scenario_results: z.array(scenarioReplayResultSchema),
+    trust_gate_results: z.array(trustGateResultSchema),
+    drift_detected: z.boolean(),
+    first_drift: z
+        .strictObject({
+        scenario_id: z.string().min(1),
+        dimension: z.string().min(1),
+        message: z.string(),
+    })
+        .nullable(),
+});
+/**
+ * Default no-op scenario runner that skips all scenarios.
+ * Real CI replays inject an actual runner.
+ */
+async function defaultRunner() {
+    return {
+        scenario_id: "unknown",
+        status: "skipped",
+        exit_code: null,
+        duration_ms: 0,
+        output: "",
+        error: "no runner provided",
+    };
+}
+/**
+ * Replay a conformance package from a clean checkout.
+ * Runs each scenario, evaluates trust gates, and detects drift
+ * between the captured run and the committed package.
+ */
+export async function replayConformancePackage(packageInput, actualEvidence, runner = defaultRunner, options = {}) {
+    const parsed = conformancePackageSchema.safeParse(packageInput);
+    if (!parsed.success)
+        throw new TypeError(`invalid conformance package: ${parsed.error.issues[0]?.message ?? "unknown"}`);
+    const pkg = parsed.data;
+    const scenarioResults = [];
+    let passed = 0;
+    let failed = 0;
+    let errored = 0;
+    let skipped = 0;
+    for (const scenario of pkg.scenarios) {
+        const result = await runner(scenario.scenario_id, scenario.fixture_path);
+        scenarioResults.push(result);
+        switch (result.status) {
+            case "pass":
+                passed++;
+                break;
+            case "fail":
+                failed++;
+                break;
+            case "error":
+                errored++;
+                break;
+            case "skipped":
+                skipped++;
+                break;
+        }
+    }
+    const trustGateResults = evaluatePackageTrustGates(pkg, actualEvidence, options);
+    const driftGates = trustGateResults.filter((r) => r.verdict === "fail");
+    const drift_detected = driftGates.length > 0;
+    const first_drift_gate = driftGates[0];
+    const first_drift = first_drift_gate?.first_divergence
+        ? {
+            scenario_id: first_drift_gate.scenario_id,
+            dimension: first_drift_gate.first_divergence.dimension,
+            message: first_drift_gate.first_divergence.message,
+        }
+        : null;
+    return {
+        package_id: pkg.package_id,
+        total_scenarios: pkg.scenarios.length,
+        passed,
+        failed,
+        errored,
+        skipped,
+        scenario_results: scenarioResults,
+        trust_gate_results: trustGateResults,
+        drift_detected,
+        first_drift,
+    };
+}
+/** Import trust gate evaluator for replay. */
+import { evaluatePackageTrustGates } from "./conformanceTrustGate.js";

package/dist/domain/conformanceTrustGate.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+/** Result of comparing a single dimension. */
+export const dimensionResultSchema = z.strictObject({
+    name: z.string().min(1),
+    status: z.enum(["match", "mismatch", "unknown", "truncated"]),
+    message: z.string().default(""),
+    evidence_ids: z.array(z.string()).default([]),
+});
+/** Result of evaluating a trust gate for one scenario. */
+export const trustGateResultSchema = z.strictObject({
+    scenario_id: z.string().min(1),
+    verdict: z.enum(["pass", "fail", "unknown"]),
+    dimension_results: z.array(dimensionResultSchema),
+    first_divergence: z
+        .strictObject({
+        dimension: z.string().min(1),
+        evidence_id: z.string().min(1),
+        message: z.string(),
+    })
+        .nullable(),
+});
+/** Dimension that is volatile due to timing or normalization. */
+const VOLATILE_DIMENSIONS = new Set([
+    "timing",
+    "timestamp",
+    "pid",
+    "ppid",
+    "duration_ms",
+    "created_at",
+    "updated_at",
+]);
+/** Dimension that carries semantic content. */
+const SEMANTIC_DIMENSIONS = new Set([
+    "exit_code",
+    "stdout",
+    "stderr",
+    "filesystem",
+    "process_tree",
+    "shim_events",
+    "protocol_events",
+    "event_journal",
+]);
+/** Check if a dimension name is volatile (timing/normalization noise). */
+export function isVolatileDimension(name) {
+    return VOLATILE_DIMENSIONS.has(name);
+}
+/** Check if a dimension name carries semantic content. */
+export function isSemanticDimension(name) {
+    return SEMANTIC_DIMENSIONS.has(name);
+}
+/**
+ * Compare two values for a dimension, classifying semantic diffs
+ * from timing/normalization noise.
+ *
+ * Volatile dimensions (timing, timestamps, PIDs) are always treated
+ * as matches because their values are expected to differ across
+ * runs and do not carry semantic meaning.
+ */
+export function compareDimension(dimensionName, expected, actual, options = {}) {
+    // Volatile dimensions: always match regardless of values
+    if (isVolatileDimension(dimensionName)) {
+        return {
+            name: dimensionName,
+            status: "match",
+            message: "volatile dimension ignored",
+            evidence_ids: [],
+        };
+    }
+    if (options.truncated) {
+        return {
+            name: dimensionName,
+            status: "truncated",
+            message: "evidence was truncated",
+            evidence_ids: [],
+        };
+    }
+    if (expected === undefined && actual === undefined) {
+        return {
+            name: dimensionName,
+            status: "unknown",
+            message: "both expected and actual are undefined",
+            evidence_ids: [],
+        };
+    }
+    if (expected === undefined || actual === undefined) {
+        return {
+            name: dimensionName,
+            status: "mismatch",
+            message: `expected ${expected === undefined ? "present" : "absent"}, actual ${actual === undefined ? "absent" : "present"}`,
+            evidence_ids: [],
+        };
+    }
+    // Semantic comparison for structured objects
+    if (typeof expected === "object" && typeof actual === "object") {
+        const expectedJson = JSON.stringify(sortKeys(expected));
+        const actualJson = JSON.stringify(sortKeys(actual));
+        if (expectedJson === actualJson) {
+            return {
+                name: dimensionName,
+                status: "match",
+                message: "",
+                evidence_ids: [],
+            };
+        }
+        return {
+            name: dimensionName,
+            status: "mismatch",
+            message: "semantic content differs",
+            evidence_ids: [],
+        };
+    }
+    // Primitive comparison
+    if (expected === actual) {
+        return {
+            name: dimensionName,
+            status: "match",
+            message: "",
+            evidence_ids: [],
+        };
+    }
+    return {
+        name: dimensionName,
+        status: "mismatch",
+        message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
+        evidence_ids: [],
+    };
+}
+/** Recursively sort object keys for deterministic comparison. */
+function sortKeys(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+/**
+ * Evaluate a trust gate for one scenario by comparing expected
+ * evidence against the actual captured run.
+ */
+export function evaluateTrustGate(contract, expectedEvidence, actualEvidence, options = {}) {
+    const dimensionResults = [];
+    let firstDivergence = null;
+    for (const dim of contract.dimensions) {
+        if (!dim.required)
+            continue;
+        const expectedValue = expectedEvidence[dim.name];
+        const actualValue = actualEvidence[dim.name];
+        const result = compareDimension(dim.name, expectedValue, actualValue, options);
+        dimensionResults.push(result);
+        if (result.status === "mismatch" && firstDivergence === null) {
+            firstDivergence = {
+                dimension: dim.name,
+                evidence_id: result.evidence_ids[0] ?? "unknown",
+                message: result.message,
+            };
+        }
+    }
+    const hasFail = dimensionResults.some((r) => r.status === "mismatch" || r.status === "truncated");
+    const hasUnknown = dimensionResults.some((r) => r.status === "unknown");
+    const verdict = hasFail
+        ? "fail"
+        : hasUnknown
+            ? "unknown"
+            : "pass";
+    return {
+        scenario_id: contract.scenario_id,
+        verdict,
+        dimension_results: dimensionResults,
+        first_divergence: firstDivergence,
+    };
+}
+/**
+ * Evaluate trust gates for all scenarios in a conformance package.
+ * Rejects runs that differ in required dimensions. Unknown/truncated
+ * evidence is never treated as equivalence.
+ */
+export function evaluatePackageTrustGates(pkg, actualEvidence, options = {}) {
+    const results = [];
+    for (const contract of pkg.verifier_contracts) {
+        const expected = pkg.expected_evidence.find((e) => e.scenario_id === contract.scenario_id);
+        if (!expected)
+            continue;
+        const expectedEvidence = expected.envelopes[0] ?? {};
+        const actual = actualEvidence[contract.scenario_id] ?? {};
+        const result = evaluateTrustGate(contract, expectedEvidence, actual, options);
+        results.push(result);
+    }
+    return results;
+}

package/dist/domain/customProtocolCapture.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Supported transport types for custom protocol capture. */
+export const transportTypeSchema = z.enum([
+    "tcp",
+    "udp",
+    "ipc",
+    "unix-socket",
+    "named-pipe",
+    "xpc",
+]);
+/** Direction of a protocol frame. */
+export const frameDirectionSchema = z.enum(["sent", "received", "intercepted"]);
+/** A captured protocol frame. */
+export const protocolFrameSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Transport type. */
+    transport: transportTypeSchema,
+    /** Direction of the frame. */
+    direction: frameDirectionSchema,
+    /** Source process identity. */
+    source_pid: z.number().int().nullable(),
+    /** Destination process identity. */
+    dest_pid: z.number().int().nullable(),
+    /** Endpoint address (IP:port, socket path, pipe name). */
+    source_endpoint: z.string().nullable(),
+    /** Destination endpoint. */
+    dest_endpoint: z.string().nullable(),
+    /** Raw frame data as base64. */
+    raw_data: z.string().nullable(),
+    /** Decoded/parsed frame content if known. */
+    decoded_content: jsonValueSchema.nullable(),
+    /** Frame size in bytes. */
+    size: z.number().int().nonnegative(),
+    /** Whether the frame was truncated. */
+    truncated: z.boolean().default(false),
+});
+/** Authentication flow stage. */
+export const authStageSchema = z.enum([
+    "init",
+    "challenge",
+    "response",
+    "token_exchange",
+    "renewal",
+    "revocation",
+    "failure",
+    "success",
+]);
+/** Token lifecycle event. */
+export const tokenLifecycleEventSchema = z.enum([
+    "issued",
+    "refreshed",
+    "expired",
+    "revoked",
+    "renewed",
+]);
+/** A captured authentication flow event. */
+export const authFlowEventSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Authentication stage. */
+    stage: authStageSchema,
+    /** Protocol used. */
+    protocol: z.string().min(1),
+    /** Token type if applicable. */
+    token_type: z.string().nullable(),
+    /** Token lifecycle event. */
+    token_lifecycle: tokenLifecycleEventSchema.nullable(),
+    /** Correlation ID linking challenge-response pairs. */
+    correlation_id: z.string().nullable(),
+    /** Whether credentials were detected and redacted. */
+    credentials_redacted: z.boolean().default(false),
+    /** Whether the authentication succeeded. */
+    succeeded: z.boolean().default(false),
+    /** Error message if authentication failed. */
+    error: z.string().nullable(),
+});
+/** A captured protocol session. */
+export const customProtocolCaptureSchema = z.strictObject({
+    /** Transport type for this session. */
+    transport: transportTypeSchema,
+    /** Captured frames in order. */
+    frames: z.array(protocolFrameSchema).min(0).max(100_000),
+    /** Authentication flow events. */
+    auth_events: z.array(authFlowEventSchema).default([]),
+    /** Whether any frame was truncated. */
+    has_truncated: z.boolean().default(false),
+    /** Whether credentials were detected. */
+    credentials_detected: z.boolean().default(false),
+});
+/** Correlate a frame with process identity. */
+export function correlateProcessIdentity(frame, pid) {
+    return frame.source_pid === pid || frame.dest_pid === pid;
+}
+/** Check if a frame contains credential-like content. */
+export function looksLikeCredentialFrame(frame) {
+    const patterns = [
+        "password",
+        "token",
+        "secret",
+        "api_key",
+        "apikey",
+        "authorization",
+        "credential",
+    ];
+    const content = JSON.stringify(frame.decoded_content ?? "").toLowerCase();
+    return patterns.some((p) => content.includes(p));
+}
+/** Filter frames by transport type. */
+export function framesByTransport(frames, transport) {
+    return frames.filter((f) => f.transport === transport);
+}
+/** Get all authentication flow events for a specific protocol. */
+export function authEventsByProtocol(events, protocol) {
+    return events.filter((e) => e.protocol === protocol);
+}
+/** Get successful authentication events. */
+export function successfulAuthEvents(events) {
+    return events.filter((e) => e.succeeded);
+}
+/** Get failed authentication events. */
+export function failedAuthEvents(events) {
+    return events.filter((e) => !e.succeeded);
+}
+/** Compute the duration of an authentication flow in milliseconds. */
+export function authFlowDuration(events) {
+    if (events.length === 0)
+        return null;
+    const first = events[0];
+    const last = events[events.length - 1];
+    return last.at_ms - first.at_ms;
+}