rea-agents 2.5.0 → 3.1.0

package/dist/domain/bytecodeProvider.js

@@ -0,0 +1,177 @@
+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;
+}
+const STANDARD_LIBRARY_PATH_MARKERS = [
+    "/stdlib/",
+    "/site-packages/",
+    "java/",
+    "javax/",
+    "sun/",
+];
+const STANDARD_LIBRARY_SYMBOL_MARKERS = ["java.", "javax.", "sun.", "__"];
+const GENERATED_PATH_MARKERS = [
+    "/generated/",
+    "_generated",
+    "/build/",
+    "/target/",
+    "/dist-packages/",
+    "/__pycache__/",
+];
+const GENERATED_SYMBOL_MARKERS = ["Generated", "_generated"];
+const VENDORED_PATH_MARKERS = [
+    "/vendor/",
+    "/vendored/",
+    "/third_party/",
+    "/3rdparty/",
+    "/node_modules/",
+];
+const BUNDLED_PATH_MARKERS = ["/bundle/", "/bundled/", ".jar!", ".war!"];
+const includesAny = (value, markers) => markers.some((marker) => value.includes(marker));
+const startsWithAny = (value, markers) => markers.some((marker) => value.startsWith(marker));
+/** Classify bytecode symbol provenance. */
+export function classifyProvenance(path, symbolName) {
+    const lower = path.toLowerCase();
+    if (includesAny(lower, STANDARD_LIBRARY_PATH_MARKERS) ||
+        startsWithAny(symbolName, STANDARD_LIBRARY_SYMBOL_MARKERS))
+        return "standard_library";
+    if (includesAny(lower, GENERATED_PATH_MARKERS) ||
+        includesAny(symbolName, GENERATED_SYMBOL_MARKERS))
+        return "generated";
+    if (includesAny(lower, VENDORED_PATH_MARKERS))
+        return "vendored";
+    if (includesAny(lower, BUNDLED_PATH_MARKERS))
+        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/callPath.js

@@ -178,9 +178,10 @@ const parseSnapshots = (groups) => {
     return snapshots;
 };
 const assertCompatible = (snapshots) => {
-    const first = snapshots.values().next().value;
-    if (first === undefined)
+    const firstEntry = snapshots.values().next();
+    if (firstEntry.done)
         return;
+    const first = firstEntry.value;
     for (const snapshot of snapshots.values()) {
         if (snapshot.subject.digest.sha256 !== first.subject.digest.sha256 ||
             snapshot.subject.format !== first.subject.format ||

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 { evaluatePackageTrustGates, 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),
+        evidence_id: 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,
+            evidence_id: first_drift_gate.first_divergence.evidence_id,
+            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,
+    };
+}