rea-agents 2.4.0 → 3.0.0

package/dist/domain/bytecodeProvider.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+/** Supported managed-runtime bytecode families. */
+export const bytecodeFamilySchema = z.enum(["jvm", "python"]);
+/** Classification of bytecode provenance. */
+export const bytecodeProvenanceSchema = z.enum([
+    "application",
+    "generated",
+    "vendored",
+    "bundled",
+    "standard_library",
+]);
+/** A bytecode symbol discovered through static analysis. */
+export const bytecodeSymbolSchema = z.strictObject({
+    /** Fully qualified name. */
+    name: z.string().min(1),
+    /** Raw bytecode location or offset. */
+    raw_location: z.string().min(1),
+    /** Normalized symbol type. */
+    kind: z.enum([
+        "class",
+        "interface",
+        "method",
+        "field",
+        "function",
+        "module",
+        "variable",
+    ]),
+    /** Bytecode version if known. */
+    bytecode_version: z.number().int().nullable(),
+    /** Provenance classification. */
+    provenance: bytecodeProvenanceSchema,
+    /** Whether the symbol is accessible (public). */
+    is_public: z.boolean().default(false),
+});
+/** A discovered bytecode artifact (class file, wheel, etc). */
+export const bytecodeArtifactSchema = z.strictObject({
+    /** Artifact path relative to the analysis root. */
+    path: z.string().min(1),
+    /** Bytecode family. */
+    family: bytecodeFamilySchema,
+    /** Artifact format. */
+    format: z.enum(["class", "jar", "war", "ear", "pyc", "pyo", "whl", "zipapp"]),
+    /** Size in bytes. */
+    size: z.number().int().nonnegative(),
+    /** SHA-256 digest. */
+    digest: z.string().regex(/^[a-f0-9]{64}$/u),
+    /** Discovered symbols. */
+    symbols: z.array(bytecodeSymbolSchema).default([]),
+    /** Whether this is a standard library artifact. */
+    is_standard_library: z.boolean().default(false),
+    /** Whether this is a generated artifact. */
+    is_generated: z.boolean().default(false),
+    /** Whether this is a vendored artifact. */
+    is_vendored: z.boolean().default(false),
+});
+/** Static bytecode analysis result. */
+export const bytecodeAnalysisSchema = z.strictObject({
+    /** Bytecode family. */
+    family: bytecodeFamilySchema,
+    /** All discovered artifacts. */
+    artifacts: z.array(bytecodeArtifactSchema).min(0).max(10_000),
+    /** Total symbols across all artifacts. */
+    total_symbols: z.number().int().nonnegative(),
+    /** Symbols classified as application code. */
+    application_symbols: z.number().int().nonnegative(),
+    /** Symbols classified as generated code. */
+    generated_symbols: z.number().int().nonnegative(),
+    /** Symbols classified as vendored code. */
+    vendored_symbols: z.number().int().nonnegative(),
+    /** Symbols classified as standard library. */
+    standard_library_symbols: z.number().int().nonnegative(),
+});
+/** Detect bytecode family from file extension. */
+export function detectBytecodeFamily(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".class") ||
+        lower.endsWith(".jar") ||
+        lower.endsWith(".war") ||
+        lower.endsWith(".ear")) {
+        return "jvm";
+    }
+    if (lower.endsWith(".pyc") ||
+        lower.endsWith(".pyo") ||
+        lower.endsWith(".whl") ||
+        lower.endsWith(".pyz") ||
+        lower.endsWith(".zipapp")) {
+        return "python";
+    }
+    return null;
+}
+/** Detect artifact format from file path. */
+export function detectArtifactFormat(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".class"))
+        return "class";
+    if (lower.endsWith(".jar"))
+        return "jar";
+    if (lower.endsWith(".war"))
+        return "war";
+    if (lower.endsWith(".ear"))
+        return "ear";
+    if (lower.endsWith(".pyc"))
+        return "pyc";
+    if (lower.endsWith(".pyo"))
+        return "pyo";
+    if (lower.endsWith(".whl"))
+        return "whl";
+    if (lower.endsWith(".pyz") || lower.endsWith(".zipapp"))
+        return "zipapp";
+    return null;
+}
+/** Classify bytecode symbol provenance. */
+export function classifyProvenance(path, symbolName) {
+    const lower = path.toLowerCase();
+    // Standard library paths
+    if (lower.includes("/stdlib/") ||
+        lower.includes("/site-packages/") ||
+        lower.includes("java/") ||
+        lower.includes("javax/") ||
+        lower.includes("sun/") ||
+        symbolName.startsWith("java.") ||
+        symbolName.startsWith("javax.") ||
+        symbolName.startsWith("sun.") ||
+        symbolName.startsWith("__")) {
+        return "standard_library";
+    }
+    // Generated code
+    if (lower.includes("/generated/") ||
+        lower.includes("_generated") ||
+        lower.includes("/build/") ||
+        lower.includes("/target/") ||
+        lower.includes("/dist-packages/") ||
+        lower.includes("/__pycache__/") ||
+        symbolName.includes("Generated") ||
+        symbolName.includes("_generated")) {
+        return "generated";
+    }
+    // Vendored code
+    if (lower.includes("/vendor/") ||
+        lower.includes("/vendored/") ||
+        lower.includes("/third_party/") ||
+        lower.includes("/3rdparty/") ||
+        lower.includes("/node_modules/") ||
+        lower.includes("/vendor/")) {
+        return "vendored";
+    }
+    // Bundled code
+    if (lower.includes("/bundle/") ||
+        lower.includes("/bundled/") ||
+        lower.includes(".jar!") ||
+        lower.includes(".war!")) {
+        return "bundled";
+    }
+    return "application";
+}
+/** Analyze a set of bytecode artifacts and produce a summary. */
+export function analyzeBytecodeArtifacts(artifacts, family) {
+    const applicationSymbols = artifacts
+        .flatMap((a) => a.symbols)
+        .filter((s) => s.provenance === "application").length;
+    const generatedSymbols = artifacts
+        .flatMap((a) => a.symbols)
+        .filter((s) => s.provenance === "generated").length;
+    const vendoredSymbols = artifacts
+        .flatMap((a) => a.symbols)
+        .filter((s) => s.provenance === "vendored").length;
+    const standardLibrarySymbols = artifacts
+        .flatMap((a) => a.symbols)
+        .filter((s) => s.provenance === "standard_library").length;
+    return {
+        family,
+        artifacts: artifacts.slice(0, 10_000),
+        total_symbols: artifacts.reduce((sum, a) => sum + a.symbols.length, 0),
+        application_symbols: applicationSymbols,
+        generated_symbols: generatedSymbols,
+        vendored_symbols: vendoredSymbols,
+        standard_library_symbols: standardLibrarySymbols,
+    };
+}

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;
+}