rea-agents 2.0.0 → 2.2.0

package/dist/domain/reconstructionCoverageEvaluation.js

@@ -0,0 +1,212 @@
+export const recommendedReconstructionProbes = (reasons) => reasons.slice(0, 100).map((reason) => ({
+    operation: probeOperation(reason.code),
+    subject_id: reason.subject_id,
+    rationale: reason.detail,
+}));
+const probeOperation = (code) => {
+    if (code.startsWith("owner-") || code.startsWith("authority-routing"))
+        return "reconcile_reconstruction_owner";
+    if (code.startsWith("verifier-"))
+        return "run_reconstruction_verifier";
+    if (code.startsWith("package-proof"))
+        return "verify_reconstruction_package";
+    if (code === "active-contradiction")
+        return "resolve_contradiction";
+    if (code === "active-unknown")
+        return "probe_residual_unknown";
+    return "update_authoritative_inventory";
+};
+export const evaluateReconstructionSurfaces = (context) => {
+    const surfaces = indexUnique(context.workspace.surfaces, "surface_id");
+    for (const surfaceId of context.boundary.required_surface_ids) {
+        const surface = surfaces.get(surfaceId);
+        if (surface === undefined) {
+            addReason(context, "surface-missing", surfaceId, "Required surface is absent from the authoritative inventory.");
+            continue;
+        }
+        addEvidence(context, surface.evidence_ids);
+        for (const dependencyId of surface.dependency_surface_ids)
+            if (!surfaces.has(dependencyId))
+                addReason(context, "dependency-surface-missing", surfaceId, `Declared dependency surface is absent: ${dependencyId}`);
+        evaluateOwner(context, surfaceId);
+    }
+};
+const evaluateOwner = (context, surfaceId) => {
+    const owners = context.workspace.owners.filter(({ surface_id: id }) => id === surfaceId);
+    if (owners.length === 0) {
+        addReason(context, "owner-missing", surfaceId, "Required surface has no reconstructed owner or explicit disposition.");
+        return;
+    }
+    if (owners.length > 1) {
+        addReason(context, "owner-duplicate", surfaceId, "Required surface has conflicting ownership declarations.");
+        return;
+    }
+    const owner = owners[0]?.ownership;
+    if (owner === undefined)
+        return;
+    if (owner.disposition !== "implemented") {
+        if (!context.boundary.allowed_dispositions.includes(owner.disposition))
+            addReason(context, "disposition-not-allowed", surfaceId, `${owner.disposition} is not allowed by this completion boundary.`);
+        return;
+    }
+    const ownerChecks = [
+        [
+            owner.path_state === "missing",
+            "owner-path-missing",
+            "Declared owner path is missing.",
+        ],
+        [
+            owner.path_state === "unknown",
+            "owner-path-unknown",
+            "Declared owner path has not been checked.",
+        ],
+        [
+            owner.package_state === "missing",
+            "owner-undistributed",
+            "Declared owner is absent from the distributable.",
+        ],
+        [
+            owner.package_state === "unknown",
+            "owner-distribution-unknown",
+            "Owner distribution state is unknown.",
+        ],
+        [
+            owner.authority_route === "detected",
+            "authority-routing-detected",
+            "Reconstructed owner routes into the authority.",
+        ],
+        [
+            owner.authority_route === "unknown",
+            "authority-routing-unknown",
+            "Authority independence has not been established.",
+        ],
+    ];
+    for (const [matches, code, detail] of ownerChecks)
+        if (matches)
+            addReason(context, code, surfaceId, detail);
+};
+export const evaluateReconstructionClaims = (context) => {
+    const claims = indexUnique(context.workspace.claims, "claim_id");
+    for (const claimId of context.boundary.required_claim_ids) {
+        const claim = claims.get(claimId);
+        if (claim === undefined) {
+            addReason(context, "claim-missing", claimId, "Required finite claim is absent.");
+            continue;
+        }
+        const contracts = context.workspace.verifier_contracts.filter(({ claim_ids: ids }) => ids.includes(claimId));
+        if (contracts.length === 0) {
+            addReason(context, "verifier-missing", claimId, "No verifier contract covers this claim.");
+            continue;
+        }
+        if (contracts.length > 1) {
+            addReason(context, "verifier-duplicate", claimId, "Multiple verifier contracts claim primary coverage.");
+            continue;
+        }
+        const contract = contracts[0];
+        if (contract !== undefined)
+            evaluateVerifierResult(context, claim, contract);
+    }
+};
+const evaluateVerifierResult = (context, claim, contract) => {
+    const results = context.workspace.verifier_results
+        .filter(({ verifier_id: id }) => id === contract.verifier_id)
+        .sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at));
+    const result = results[0];
+    if (result === undefined) {
+        addReason(context, "verifier-result-missing", claim.claim_id, "Verifier has no recorded result.");
+        return;
+    }
+    addEvidence(context, result.evidence_ids);
+    if (!verifierResultIsCompatible(context, claim, contract, result)) {
+        addReason(context, "verifier-result-incompatible", claim.claim_id, "Latest verifier result does not match current artifacts, owners, dimensions, authority, normalization, repeats, or contract.");
+        return;
+    }
+    const observedAt = Date.parse(result.observed_at);
+    if (observedAt > context.nowEpochMs ||
+        context.nowEpochMs - observedAt > contract.max_age_ms) {
+        addReason(context, "verifier-result-stale", claim.claim_id, "Latest compatible verifier result is stale.");
+        return;
+    }
+    if (result.status === "fail")
+        addReason(context, "verifier-failed", claim.claim_id, "Latest compatible verifier result failed.");
+    else if (result.status !== "pass")
+        addReason(context, "verifier-unknown", claim.claim_id, `Latest compatible verifier result is ${result.status}.`);
+};
+const verifierResultIsCompatible = (context, claim, contract, result) => {
+    const artifactDigests = new Set(context.workspace.artifacts.map(({ artifact_sha256: value }) => value));
+    const ownerDigests = new Set(context.workspace.owners.flatMap(({ ownership }) => ownership.disposition === "implemented" ? [ownership.owner_sha256] : []));
+    const surfaces = new Map(context.workspace.surfaces.map((surface) => [surface.surface_id, surface]));
+    const artifacts = new Map(context.workspace.artifacts.map((artifact) => [
+        artifact.artifact_id,
+        artifact,
+    ]));
+    const expectedArtifactDigests = claim.surface_ids.flatMap((surfaceId) => {
+        const surface = surfaces.get(surfaceId);
+        const artifact = surface === undefined ? undefined : artifacts.get(surface.artifact_id);
+        return artifact === undefined ? [] : [artifact.artifact_sha256];
+    });
+    const expectedOwnerDigests = context.workspace.owners.flatMap(({ surface_id: surfaceId, ownership }) => claim.surface_ids.includes(surfaceId) &&
+        ownership.disposition === "implemented"
+        ? [ownership.owner_sha256]
+        : []);
+    return (result.contract_sha256 === contract.contract_sha256 &&
+        result.normalization_sha256 === contract.normalization_sha256 &&
+        result.covered_claim_ids.includes(claim.claim_id) &&
+        result.covered_claim_ids.every((item) => contract.claim_ids.includes(item)) &&
+        claim.required_dimensions.every((item) => contract.dimensions.includes(item)) &&
+        claim.required_dimensions.every((item) => result.covered_dimensions.includes(item)) &&
+        result.covered_dimensions.every((item) => contract.dimensions.includes(item)) &&
+        result.artifact_sha256s.every((item) => artifactDigests.has(item)) &&
+        expectedArtifactDigests.every((item) => result.artifact_sha256s.includes(item)) &&
+        result.owner_sha256s.every((item) => ownerDigests.has(item)) &&
+        expectedOwnerDigests.every((item) => result.owner_sha256s.includes(item)) &&
+        result.repeats >= contract.minimum_repeats &&
+        claim.required_authority === contract.authority);
+};
+export const evaluateReconstructionWorkspaceRisks = (context) => {
+    for (const unknownId of context.workspace.residual_unknown_ids)
+        if (!context.boundary.allowed_unknown_ids.includes(unknownId))
+            addReason(context, "active-unknown", unknownId, "Active residual unknown is not permitted by the completion boundary.");
+    for (const contradiction of context.workspace.contradictions)
+        if (contradiction.status === "active" &&
+            (contradiction.surface_ids.some((id) => context.boundary.required_surface_ids.includes(id)) ||
+                contradiction.claim_ids.some((id) => context.boundary.required_claim_ids.includes(id)))) {
+            addEvidence(context, contradiction.evidence_ids);
+            addReason(context, "active-contradiction", contradiction.contradiction_id, "Active contradiction affects the completion boundary.");
+        }
+};
+export const evaluateReconstructionPackageProofs = (context) => {
+    const surfaces = new Map(context.workspace.surfaces.map((surface) => [surface.surface_id, surface]));
+    const artifacts = new Map(context.workspace.artifacts.map((artifact) => [
+        artifact.artifact_id,
+        artifact,
+    ]));
+    const requiredArtifactDigests = context.boundary.required_surface_ids.flatMap((surfaceId) => {
+        const surface = surfaces.get(surfaceId);
+        const artifact = surface === undefined ? undefined : artifacts.get(surface.artifact_id);
+        return artifact === undefined ? [] : [artifact.artifact_sha256];
+    });
+    for (const kind of context.boundary.required_package_proof_kinds) {
+        const proofs = context.workspace.package_proofs.filter((proof) => proof.kind === kind);
+        const passing = proofs.find(({ artifact_sha256s: digests, status }) => status === "pass" &&
+            requiredArtifactDigests.every((digest) => digests.includes(digest)));
+        if (passing !== undefined) {
+            addEvidence(context, passing.evidence_ids);
+            continue;
+        }
+        if (proofs.some(({ status }) => status === "fail"))
+            addReason(context, "package-proof-failed", kind, "Required package or integration proof failed.");
+        else if (proofs.length > 0)
+            addReason(context, "package-proof-unknown", kind, "Required package or integration proof is not passing.");
+        else
+            addReason(context, "package-proof-missing", kind, "Required package or integration proof is missing.");
+    }
+};
+const indexUnique = (items, key) => new Map(items.map((item) => [item[key], item]));
+const addReason = (context, code, subjectId, detail) => {
+    context.reasons.push({ code, subject_id: subjectId, detail });
+};
+const addEvidence = (context, evidenceIds) => {
+    for (const evidenceId of evidenceIds)
+        context.evidenceIds.add(evidenceId);
+};

package/dist/domain/reconstructionVerificationSchemas.js

@@ -70,6 +70,14 @@ export const reconstructionSpecificationSchema = z
 /** Bounded reconstruction-verification input. */
 export const reconstructionVerificationInputSchema = z.strictObject({
     specification: reconstructionSpecificationSchema,
+    coverage: z
+        .strictObject({
+        workspace_id: z.string().regex(/^rcw_[a-f0-9]{64}$/u),
+        revision: z.number().int().min(1),
+        revision_sha256: digestSchema,
+        boundary_id: z.string().min(1).max(200),
+    })
+        .optional(),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),

package/dist/domain/replayMachine.js

@@ -0,0 +1,316 @@
+import { MultiDirectedGraph } from "graphology";
+import { singleSource } from "graphology-shortest-path";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const replayIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u);
+const replayPathSchema = z
+    .array(z.union([z.string().max(256), z.number().int().nonnegative()]))
+    .max(32);
+const sensitiveHeaderNames = new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+]);
+const replayHeaderMatchersSchema = z
+    .record(z.string().min(1).max(256), z.string().max(8_192))
+    .superRefine((headers, context) => {
+    const names = Object.keys(headers).map((name) => name.toLowerCase());
+    if (new Set(names).size !== names.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay header matchers must be unique ignoring case",
+            input: headers,
+        });
+    if (names.some((name) => sensitiveHeaderNames.has(name)))
+        context.addIssue({
+            code: "custom",
+            message: "replay header matchers cannot persist authorization or cookie values; capture and guard through a secret alias instead",
+            input: headers,
+        });
+})
+    .transform((headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+    name.toLowerCase(),
+    value,
+])));
+const replayValueSourceSchema = z.discriminatedUnion("source", [
+    z.strictObject({
+        source: z.literal("request_header"),
+        name: z
+            .string()
+            .min(1)
+            .transform((name) => name.toLowerCase()),
+    }),
+    z.strictObject({ source: z.literal("request_json"), path: replayPathSchema }),
+    z.strictObject({
+        source: z.literal("websocket_json"),
+        path: replayPathSchema,
+    }),
+    z.strictObject({ source: z.literal("action_json"), path: replayPathSchema }),
+]);
+const replayTriggerSchema = z.discriminatedUnion("protocol", [
+    z.strictObject({
+        protocol: z.literal("http"),
+        method: z
+            .string()
+            .min(1)
+            .max(16)
+            .transform((method) => method.toUpperCase()),
+        path: z.string().startsWith("/"),
+        headers: replayHeaderMatchersSchema.default({}),
+        body: z.string().max(1_000_000).nullable().default(null),
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_connect"),
+        path: z.string().startsWith("/"),
+        headers: replayHeaderMatchersSchema.default({}),
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_message"),
+        path: z.string().startsWith("/"),
+        body: z.string().max(1_000_000).nullable().default(null),
+    }),
+]);
+const replayActionSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("http_response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.record(z.string(), z.string()).default({}),
+        body: z.string().max(1_000_000),
+    }),
+    z.strictObject({
+        type: z.literal("websocket_send"),
+        data: z.string().max(1_000_000),
+    }),
+    z.strictObject({ type: z.literal("disconnect") }),
+    z.strictObject({
+        type: z.literal("delay"),
+        duration_ms: z.number().int().nonnegative().max(30_000),
+    }),
+]);
+const replayTransitionSchema = z.strictObject({
+    id: replayIdentifierSchema,
+    from: replayIdentifierSchema,
+    to: replayIdentifierSchema,
+    priority: z.number().int().min(0).max(1_000).default(100),
+    trigger: replayTriggerSchema,
+    guards: z
+        .array(z.strictObject({
+        variable: replayIdentifierSchema,
+        value: replayValueSourceSchema,
+    }))
+        .max(32)
+        .default([]),
+    captures: z
+        .array(z.strictObject({
+        variable: replayIdentifierSchema,
+        value: replayValueSourceSchema,
+        sensitive: z.boolean().default(false),
+    }))
+        .max(32)
+        .default([]),
+    actions: z.array(replayActionSchema).min(1).max(32),
+    max_uses: z.number().int().min(1).max(10_000),
+});
+const transitionSignature = (transition) => {
+    const signature = canonicalize({
+        from: transition.from,
+        priority: transition.priority,
+        trigger: transition.trigger,
+    });
+    if (signature === undefined)
+        throw new TypeError("Replay transition signature is not canonical JSON");
+    return signature;
+};
+const replayMachineBaseSchema = z.strictObject({
+    initial_state: replayIdentifierSchema,
+    states: z
+        .array(z.strictObject({
+        name: replayIdentifierSchema,
+        terminal: z.boolean().default(false),
+        max_visits: z.number().int().min(1).max(100_000).default(100_000),
+    }))
+        .min(1)
+        .max(256),
+    transitions: z.array(replayTransitionSchema).min(1).max(2_000),
+    max_transitions: z.number().int().min(1).max(100_000),
+    limits: z
+        .strictObject({
+        connections: z.number().int().min(1).max(1_000).default(100),
+        messages: z.number().int().min(1).max(100_000).default(10_000),
+        bytes: z.number().int().min(1).max(10_000_000).default(1_000_000),
+        duration_ms: z.number().int().min(1).max(300_000).default(30_000),
+    })
+        .default({
+        connections: 100,
+        messages: 10_000,
+        bytes: 1_000_000,
+        duration_ms: 30_000,
+    }),
+});
+const validateReplayIdentities = (machine, context) => {
+    const names = machine.states.map(({ name }) => name);
+    const nameSet = new Set(names);
+    if (nameSet.size !== names.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine state names must be unique",
+            path: ["states"],
+            input: machine,
+        });
+    if (!nameSet.has(machine.initial_state))
+        context.addIssue({
+            code: "custom",
+            message: "replay machine initial state is not declared",
+            path: ["initial_state"],
+            input: machine,
+        });
+    const transitionIds = machine.transitions.map(({ id }) => id);
+    if (new Set(transitionIds).size !== transitionIds.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine transition IDs must be unique",
+            path: ["transitions"],
+            input: machine,
+        });
+    const signatures = machine.transitions.map(transitionSignature);
+    if (new Set(signatures).size !== signatures.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine transitions with the same state, trigger, and priority are ambiguous",
+            path: ["transitions"],
+            input: machine,
+        });
+    return nameSet;
+};
+const validateReplayVariables = (machine, context) => {
+    const capturedVariables = new Map();
+    for (const [transitionIndex, transition] of machine.transitions.entries()) {
+        for (const capture of transition.captures) {
+            const sensitivity = capturedVariables.get(capture.variable);
+            if (sensitivity !== undefined && sensitivity !== capture.sensitive)
+                context.addIssue({
+                    code: "custom",
+                    message: "a replay variable cannot change secret classification between captures",
+                    path: ["transitions", transitionIndex, "captures"],
+                    input: machine,
+                });
+            capturedVariables.set(capture.variable, capture.sensitive);
+        }
+    }
+    const availableByState = new Map([
+        [machine.initial_state, new Set()],
+    ]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const transition of machine.transitions) {
+            const available = availableByState.get(transition.from);
+            if (available === undefined ||
+                transition.guards.some(({ variable }) => !available.has(variable)))
+                continue;
+            const nextAvailable = new Set(available);
+            for (const { variable } of transition.captures)
+                nextAvailable.add(variable);
+            const existing = availableByState.get(transition.to);
+            if (existing === undefined) {
+                availableByState.set(transition.to, nextAvailable);
+                changed = true;
+                continue;
+            }
+            for (const variable of nextAvailable)
+                if (!existing.has(variable)) {
+                    existing.add(variable);
+                    changed = true;
+                }
+        }
+    }
+    for (const [transitionIndex, transition] of machine.transitions.entries())
+        for (const [guardIndex, guard] of transition.guards.entries())
+            if (!availableByState.get(transition.from)?.has(guard.variable))
+                context.addIssue({
+                    code: "custom",
+                    message: "replay guard variable is not captured on an executable path before use",
+                    path: ["transitions", transitionIndex, "guards", guardIndex],
+                    input: machine,
+                });
+};
+const validateReplayActions = (machine, context) => {
+    for (const [index, transition] of machine.transitions.entries()) {
+        const httpResponses = transition.actions.filter(({ type }) => type === "http_response").length;
+        const websocketSends = transition.actions.some(({ type }) => type === "websocket_send");
+        const invalid = transition.trigger.protocol === "http"
+            ? httpResponses !== 1 || websocketSends
+            : httpResponses !== 0;
+        if (invalid)
+            context.addIssue({
+                code: "custom",
+                message: "replay actions must match the transition protocol and HTTP transitions require exactly one response",
+                path: ["transitions", index, "actions"],
+                input: machine,
+            });
+    }
+};
+const validateReplayGraph = (machine, names, context) => {
+    const graph = new MultiDirectedGraph();
+    for (const name of names)
+        graph.addNode(name);
+    for (const [index, transition] of machine.transitions.entries()) {
+        if (!names.has(transition.from) || !names.has(transition.to)) {
+            context.addIssue({
+                code: "custom",
+                message: "replay machine transition references an unknown state",
+                path: ["transitions", index],
+                input: machine,
+            });
+            continue;
+        }
+        graph.addDirectedEdgeWithKey(`${transition.id}:${String(index)}`, transition.from, transition.to);
+    }
+    if (!graph.hasNode(machine.initial_state))
+        return;
+    if (!machine.states.some(({ terminal }) => terminal))
+        context.addIssue({
+            code: "custom",
+            message: "replay machine must declare at least one terminal state",
+            path: ["states"],
+            input: machine,
+        });
+    const reachable = new Set(Object.keys(singleSource(graph, machine.initial_state)));
+    reachable.add(machine.initial_state);
+    for (const [index, state] of machine.states.entries()) {
+        if (!reachable.has(state.name))
+            context.addIssue({
+                code: "custom",
+                message: "replay machine state is unreachable from the initial state",
+                path: ["states", index],
+                input: machine,
+            });
+        if (state.terminal && graph.outDegree(state.name) > 0)
+            context.addIssue({
+                code: "custom",
+                message: "terminal replay machine state cannot have outgoing transitions",
+                path: ["states", index],
+                input: machine,
+            });
+        if (!state.terminal && graph.outDegree(state.name) === 0)
+            context.addIssue({
+                code: "custom",
+                message: "non-terminal replay machine state has no outgoing transition",
+                path: ["states", index],
+                input: machine,
+            });
+    }
+};
+/** Portable finite replay machine with no executable callbacks. */
+export const replayMachineSchema = z
+    .object(replayMachineBaseSchema.shape)
+    .strict()
+    .superRefine((machine, context) => {
+    const names = validateReplayIdentities(machine, context);
+    validateReplayVariables(machine, context);
+    validateReplayActions(machine, context);
+    validateReplayGraph(machine, names, context);
+});