rea-agents 3.0.0 → 3.2.0

package/dist/domain/conformancePackage.js

@@ -3,18 +3,10 @@ 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({
+import { err, ok } from "./result.js";
+const conformancePackageIdSchema = z.string().regex(/^cp_[a-f0-9]{64}$/u);
+const scenarioIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);
+const scenarioManifestSchema = z.strictObject({
     scenario_id: scenarioIdSchema,
     name: z.string().min(1),
     description: z.string().min(1),
@@ -25,8 +17,7 @@ export const scenarioManifestSchema = z.strictObject({
     /** 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({
+const replayPlanSchema = z.strictObject({
     scenario_id: scenarioIdSchema,
     /** Ordered steps to execute during replay. */
     steps: z
@@ -36,37 +27,30 @@ export const replayPlanSchema = z.strictObject({
         arguments: z.array(z.string()).default([]),
         timeout_ms: z.number().int().positive(),
     }))
-        .min(1)
-        .max(100),
+        .min(1),
     /** 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({
+const shimPlanSchema = z.strictObject({
     scenario_id: scenarioIdSchema,
     /** Shims to install, each intercepting a named effect. */
-    shims: z
-        .array(z.strictObject({
+    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({
+const expectedEvidenceSchema = z.strictObject({
     scenario_id: scenarioIdSchema,
     /** Expected evidence envelopes. */
-    envelopes: z.array(evidenceEnvelopeSchema).min(0).max(100),
+    envelopes: z.array(evidenceEnvelopeSchema),
     /** 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({
+const verifierContractSchema = z.strictObject({
     scenario_id: scenarioIdSchema,
     /** Dimensions to verify. */
     dimensions: z
@@ -75,95 +59,140 @@ export const verifierContractSchema = z.strictObject({
         required: z.boolean().default(true),
         comparison: z.enum(["exact", "semantic", "fuzzy"]),
     }))
-        .min(1)
-        .max(50),
+        .min(1),
     /** 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,
+const conformancePackageContentsSchema = z.strictObject({
     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. */
+    scenarios: z.array(scenarioManifestSchema).min(1),
+    /** Exactly one replay plan for each scenario. */
+    replay_plans: z.array(replayPlanSchema).min(1),
+    /** At most one optional shim plan for each scenario. */
     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),
+    /** Exactly one expected-evidence record for each scenario. */
+    expected_evidence: z.array(expectedEvidenceSchema).min(1),
+    /** Exactly one verifier contract for each scenario. */
+    verifier_contracts: z.array(verifierContractSchema).min(1),
 });
-/** Validate a conformance package and cross-check internal references. */
-export function validateConformancePackage(input) {
+const conformancePackageRecordSchema = conformancePackageContentsSchema.extend({
+    package_id: conformancePackageIdSchema,
+});
+const conformancePackageSchema = conformancePackageRecordSchema.brand();
+/** Parse unknown input once into a package whose aggregate invariants hold. */
+export function parseConformancePackage(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 err({
+            kind: "invalid_package",
+            message: parsed.error.issues[0]?.message ?? "Invalid package",
+        });
+    const relationError = parseScenarioRelations(parsed.data);
+    if (relationError !== undefined)
+        return err(relationError);
+    const expectedPackageId = computePackageId(packageContents(parsed.data));
+    if (parsed.data.package_id !== expectedPackageId)
+        return err({
+            kind: "package_id_mismatch",
+            actual: parsed.data.package_id,
+            expected: expectedPackageId,
+            message: "Package identifier does not match its canonical contents",
+        });
+    return ok(parsed.data);
+}
+/** Create a content-addressed package from source-owned typed fields. */
+export function createConformancePackage(input) {
+    const contents = conformancePackageContentsSchema.safeParse(input);
+    if (!contents.success)
+        throw new TypeError(`Invalid conformance package source: ${contents.error.issues[0]?.message ?? "unknown parse failure"}`);
+    const parsed = parseConformancePackage({
+        ...contents.data,
+        package_id: computePackageId(contents.data),
+    });
+    if (!parsed.ok)
+        throw new TypeError(`Invalid conformance package source: ${parsed.error.message}`);
+    return parsed.value;
+}
+const parseScenarioRelations = (pkg) => {
+    const scenarioIds = new Set();
+    for (const scenario of pkg.scenarios) {
+        if (scenarioIds.has(scenario.scenario_id))
             return {
-                ok: false,
-                error: { kind: "duplicate_scenario", scenario_id: s.scenario_id },
+                kind: "duplicate_scenario",
+                scenario_id: scenario.scenario_id,
+                message: `Duplicate scenario ${scenario.scenario_id}`,
             };
-        seen.add(s.scenario_id);
+        scenarioIds.add(scenario.scenario_id);
     }
-    // Check that replay plans reference existing scenarios
-    for (const rp of pkg.replay_plans) {
-        if (!seen.has(rp.scenario_id))
+    const sections = [
+        { name: "replay_plans", entries: pkg.replay_plans, required: true },
+        { name: "shim_plans", entries: pkg.shim_plans, required: false },
+        {
+            name: "expected_evidence",
+            entries: pkg.expected_evidence,
+            required: true,
+        },
+        {
+            name: "verifier_contracts",
+            entries: pkg.verifier_contracts,
+            required: true,
+        },
+    ];
+    for (const section of sections) {
+        const error = parseScenarioSection(scenarioIds, section);
+        if (error !== undefined)
+            return error;
+    }
+    return undefined;
+};
+const parseScenarioSection = (scenarioIds, section) => {
+    const referenced = new Set();
+    for (const entry of section.entries) {
+        if (!scenarioIds.has(entry.scenario_id))
             return {
-                ok: false,
-                error: {
-                    kind: "scenario_not_found",
-                    scenario_id: rp.scenario_id,
-                },
+                kind: "unknown_scenario_reference",
+                section: section.name,
+                scenario_id: entry.scenario_id,
+                message: `${section.name} references unknown scenario ${entry.scenario_id}`,
             };
-    }
-    // Check that expected evidence references existing scenarios
-    for (const ee of pkg.expected_evidence) {
-        if (!seen.has(ee.scenario_id))
+        if (referenced.has(entry.scenario_id))
             return {
-                ok: false,
-                error: {
-                    kind: "scenario_not_found",
-                    scenario_id: ee.scenario_id,
-                },
+                kind: "duplicate_scenario_reference",
+                section: section.name,
+                scenario_id: entry.scenario_id,
+                message: `${section.name} contains duplicate scenario ${entry.scenario_id}`,
             };
+        referenced.add(entry.scenario_id);
     }
-    // Check that verifier contracts reference existing scenarios
-    for (const vc of pkg.verifier_contracts) {
-        if (!seen.has(vc.scenario_id))
+    if (!section.required)
+        return undefined;
+    for (const scenarioId of scenarioIds) {
+        if (!referenced.has(scenarioId))
             return {
-                ok: false,
-                error: {
-                    kind: "scenario_not_found",
-                    scenario_id: vc.scenario_id,
-                },
+                kind: "missing_scenario_reference",
+                section: section.name,
+                scenario_id: scenarioId,
+                message: `${section.name} is missing scenario ${scenarioId}`,
             };
     }
-    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 undefined;
+};
+const packageContents = (pkg) => ({
+    name: pkg.name,
+    description: pkg.description,
+    created_at: pkg.created_at,
+    scenarios: pkg.scenarios,
+    replay_plans: pkg.replay_plans,
+    shim_plans: pkg.shim_plans,
+    expected_evidence: pkg.expected_evidence,
+    verifier_contracts: pkg.verifier_contracts,
+});
+const computePackageId = (contents) => {
+    const json = canonicalize(contents);
+    if (json === undefined)
+        throw new TypeError("Could not canonicalize parsed conformance 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

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { conformancePackageSchema, } from "./conformancePackage.js";
-import { trustGateResultSchema } from "./conformanceTrustGate.js";
+import { parseConformancePackage } 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),
@@ -11,7 +11,8 @@ export const scenarioReplayResultSchema = z.strictObject({
     error: z.string().nullable(),
 });
 /** Result of replaying an entire conformance package. */
-export const packageReplayResultSchema = z.strictObject({
+export const packageReplayResultSchema = z
+    .strictObject({
     package_id: z.string().min(1),
     total_scenarios: z.number().int().positive(),
     passed: z.number().int().nonnegative(),
@@ -25,9 +26,37 @@ export const packageReplayResultSchema = z.strictObject({
         .strictObject({
         scenario_id: z.string().min(1),
         dimension: z.string().min(1),
+        evidence_id: z.string().min(1),
         message: z.string(),
     })
         .nullable(),
+})
+    .superRefine((result, context) => {
+    const count = (status) => result.scenario_results.filter((item) => item.status === status).length;
+    const countMismatch = result.passed !== count("pass") ||
+        result.failed !== count("fail") ||
+        result.errored !== count("error") ||
+        result.skipped !== count("skipped");
+    const driftDetected = result.trust_gate_results.some(({ verdict }) => verdict === "fail");
+    if (result.total_scenarios !== result.scenario_results.length ||
+        countMismatch)
+        context.addIssue({
+            code: "custom",
+            message: "Scenario totals must summarize scenario results",
+            path: ["total_scenarios"],
+        });
+    if (result.drift_detected !== driftDetected)
+        context.addIssue({
+            code: "custom",
+            message: "Drift status must summarize trust-gate failures",
+            path: ["drift_detected"],
+        });
+    if (!driftDetected && result.first_drift !== null)
+        context.addIssue({
+            code: "custom",
+            message: "A drift witness requires a failed trust gate",
+            path: ["first_drift"],
+        });
 });
 /**
  * Default no-op scenario runner that skips all scenarios.
@@ -49,10 +78,10 @@ async function defaultRunner() {
  * 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 parsed = parseConformancePackage(packageInput);
+    if (!parsed.ok)
+        throw new TypeError(`invalid conformance package: ${parsed.error.message}`);
+    const pkg = parsed.value;
     const scenarioResults = [];
     let passed = 0;
     let failed = 0;
@@ -84,10 +113,11 @@ export async function replayConformancePackage(packageInput, actualEvidence, run
         ? {
             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 {
+    return packageReplayResultSchema.parse({
         package_id: pkg.package_id,
         total_scenarios: pkg.scenarios.length,
         passed,
@@ -98,7 +128,5 @@ export async function replayConformancePackage(packageInput, actualEvidence, run
         trust_gate_results: trustGateResults,
         drift_detected,
         first_drift,
-    };
+    });
 }
-/** Import trust gate evaluator for replay. */
-import { evaluatePackageTrustGates } from "./conformanceTrustGate.js";