rea-agents 0.2.1 → 0.4.0

package/dist/domain/reconstructionUnknowns.js

@@ -0,0 +1,90 @@
+/** Select the latest revision of each residual unknown. */
+export const reconstructionUnknownHeads = (revisions) => {
+    const heads = new Map();
+    for (const item of revisions) {
+        const current = heads.get(item.unknown_id);
+        if (current === undefined || current.revision < item.revision)
+            heads.set(item.unknown_id, item);
+    }
+    return heads;
+};
+/** Find active unknowns that affect a comparison or one of its sources. */
+export const reconstructionClaimUnknowns = (heads, comparisonId, sourceIds) => {
+    const evidenceIds = new Set([comparisonId, ...sourceIds]);
+    const relevantIds = new Set([...heads.values()]
+        .filter((item) => item.status !== "resolved" &&
+        [
+            ...item.supporting_evidence_ids,
+            ...item.contradicting_evidence_ids,
+        ].some((id) => evidenceIds.has(id)))
+        .map(({ unknown_id: id }) => id));
+    const pending = [...relevantIds];
+    while (pending.length > 0) {
+        const currentId = pending.pop();
+        if (currentId === undefined)
+            continue;
+        const current = heads.get(currentId);
+        if (current === undefined)
+            continue;
+        for (const relationship of current.relationships) {
+            if (relationship.type === "related-to")
+                continue;
+            const dependency = heads.get(relationship.unknown_id);
+            if (dependency === undefined ||
+                dependency.status === "resolved" ||
+                relevantIds.has(dependency.unknown_id))
+                continue;
+            relevantIds.add(dependency.unknown_id);
+            pending.push(dependency.unknown_id);
+        }
+    }
+    return [...relevantIds]
+        .flatMap((id) => {
+        const unknown = heads.get(id);
+        return unknown === undefined ? [] : [unknown];
+    })
+        .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id, "en"));
+};
+/** Aggregate and bound deterministic probes for unresolved claims. */
+export const reconstructionProbes = (results, heads) => {
+    const output = new Map();
+    for (const result of results.filter(({ status }) => status === "unknown")) {
+        const unknowns = result.unknown_ids.flatMap((id) => {
+            const item = heads.get(id);
+            return item === undefined ? [] : [item];
+        });
+        const probes = unknowns.flatMap(({ recommended_probes: items }) => items);
+        const candidates = probes.length > 0 ? probes : [defaultProbe(result.kind)];
+        for (const probe of candidates) {
+            const key = `${probe.operation}\0${probe.rationale}`;
+            const current = output.get(key) ?? {
+                ...probe,
+                claim_ids: [],
+                unknown_ids: [],
+            };
+            current.claim_ids = uniqueSorted([...current.claim_ids, result.claim_id]);
+            current.unknown_ids = uniqueSorted([
+                ...current.unknown_ids,
+                ...result.unknown_ids,
+            ]);
+            output.set(key, current);
+        }
+    }
+    const sorted = [...output.values()].sort((left, right) => `${left.operation}\0${left.rationale}`.localeCompare(`${right.operation}\0${right.rationale}`, "en"));
+    return { items: sorted.slice(0, 2_000), truncated: sorted.length > 2_000 };
+};
+const defaultProbe = (kind) => kind === "behavioral"
+    ? {
+        operation: "capture_process_scenario",
+        rationale: "Repeat both scenarios under one controlled environment.",
+    }
+    : kind === "structural-function"
+        ? {
+            operation: "analyze_function",
+            rationale: "Capture complete function dossiers under equal limits.",
+        }
+        : {
+            operation: "inventory_artifact",
+            rationale: "Capture complete artifact inventories under equal limits.",
+        };
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));

package/dist/domain/reconstructionVerification.js

@@ -0,0 +1,285 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { artifactComparisonResultSchema } from "./artifactComparison.js";
+import { artifactInventoryResultSchema } from "./artifactGraph.js";
+import { parseEvidence } from "./evidence.js";
+import { parseEvidenceBundle } from "./evidenceBundle.js";
+import { functionComparisonResultSchema } from "./functionComparison.js";
+import { functionDossierSchema } from "./hopperValues.js";
+import { processCaptureComparisonSchema, processCaptureSchema, } from "./processCapture.js";
+import { reconstructionClaimResultSchema, reconstructionSpecificationSchema, reconstructionVerificationResultSchema, } from "./reconstructionVerificationSchemas.js";
+import { reconstructionClaimUnknowns, reconstructionProbes, reconstructionUnknownHeads, } from "./reconstructionUnknowns.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+export { reconstructionVerificationInputSchema, reconstructionVerificationResultSchema, } from "./reconstructionVerificationSchemas.js";
+const MAX_BUNDLE_RECORDS = 20_100;
+const MAX_UNKNOWN_REVISIONS = 10_000;
+const MAX_CANONICAL_BYTES = 32 * 1024 * 1024;
+const providers = {
+    behavioral: {
+        operation: "compare_process_captures",
+        predicate: "rea.process-comparison/v1",
+        id: "rea-process",
+        name: "REA deterministic process harness",
+    },
+    "structural-function": {
+        operation: "compare_functions",
+        predicate: "rea.function-comparison/v1",
+        id: "rea-function-comparison",
+        name: "REA function comparison",
+    },
+    "structural-artifact": {
+        operation: "compare_artifacts",
+        predicate: "rea.artifact-comparison/v1",
+        id: "rea-artifact-comparison",
+        name: "REA artifact comparison",
+    },
+};
+/** Verify only explicitly declared claims; no global equivalence is inferred. */
+export const verifyReconstruction = (specificationInput, bundleInput, offset, limit) => {
+    const specification = reconstructionSpecificationSchema.parse(specificationInput);
+    enforceInputSize(bundleInput);
+    const bundle = parseEvidenceBundle(bundleInput);
+    if (bundle.records.length > MAX_BUNDLE_RECORDS)
+        throw new TypeError("Reconstruction Evidence record limit exceeded");
+    if (bundle.unknowns.length > MAX_UNKNOWN_REVISIONS)
+        throw new TypeError("Reconstruction unknown revision limit exceeded");
+    const records = new Map(bundle.records.map((item) => [item.evidence_id, item]));
+    const heads = reconstructionUnknownHeads(bundle.unknowns);
+    const results = specification.claims
+        .map((claim) => evaluateClaim(claim, records, heads))
+        .sort((left, right) => left.claim_id.localeCompare(right.claim_id, "en"));
+    const page = results.slice(offset, offset + limit);
+    const failed = count(results, "fail");
+    const unresolved = count(results, "unknown");
+    const probes = reconstructionProbes(results, heads);
+    const evidenceLinks = uniqueSorted(results.flatMap(({ evidence_links: links }) => links));
+    if (evidenceLinks.length > 20_100)
+        throw new TypeError("Reconstruction Evidence closure exceeds limit");
+    const output = {
+        status: failed > 0 ? "fail" : unresolved > 0 ? "unknown" : "pass",
+        specification_sha256: digest({
+            ...specification,
+            claims: [...specification.claims].sort((left, right) => left.claim_id.localeCompare(right.claim_id, "en")),
+        }),
+        summary: {
+            total: results.length,
+            passed: count(results, "pass"),
+            failed,
+            unknown: unresolved,
+            behavioral: results.filter(({ kind }) => kind === "behavioral").length,
+            structural: results.filter(({ kind }) => kind !== "behavioral").length,
+        },
+        claims: {
+            items: page,
+            offset,
+            limit,
+            total: results.length,
+            next_offset: offset + page.length < results.length ? offset + page.length : null,
+        },
+        recommended_probes: probes.items,
+        evidence_links: evidenceLinks,
+        limitations: [
+            "Pass means every declared claim passed; it does not establish global implementation equivalence.",
+            ...(probes.truncated
+                ? ["Recommended probes were truncated at the 2,000-item limit."]
+                : []),
+        ],
+    };
+    return reconstructionVerificationResultSchema.parse(output);
+};
+const evaluateClaim = (claim, records, heads) => {
+    const comparison = records.get(claim.comparison_evidence_id);
+    if (comparison === undefined)
+        throw new TypeError(`Missing comparison Evidence ${claim.comparison_evidence_id}`);
+    validateComparisonIdentity(claim, comparison);
+    const sides = sourceSides(claim, comparison);
+    const allSourceIds = [...sides.left, ...sides.right];
+    if (new Set(allSourceIds).size !== allSourceIds.length)
+        throw new TypeError("Comparison source Evidence must be unique and two-sided");
+    if (!sameSet(comparison.evidence_links, allSourceIds))
+        throw new TypeError("Comparison Evidence closure disagrees with its parameters");
+    const sources = allSourceIds.map((id) => {
+        const source = records.get(id);
+        if (source === undefined)
+            throw new TypeError(`Missing source Evidence ${id}`);
+        return source;
+    });
+    validateSourceKinds(claim, sources);
+    const observed = observedStatus(claim, comparison);
+    const limitations = authorityLimitations(claim, sources, sides);
+    const relevantUnknowns = reconstructionClaimUnknowns(heads, comparison.evidence_id, allSourceIds);
+    const status = classify(observed, limitations, relevantUnknowns);
+    const displayedUnknowns = relevantUnknowns.slice(0, 100);
+    const hiddenUnknownCount = relevantUnknowns.length - displayedUnknowns.length;
+    return reconstructionClaimResultSchema.parse({
+        claim_id: claim.claim_id,
+        kind: claim.kind,
+        dimension: claim.dimension,
+        status,
+        observed_status: observed,
+        comparison_evidence_id: comparison.evidence_id,
+        left_evidence_ids: sides.left,
+        right_evidence_ids: sides.right,
+        evidence_links: uniqueSorted([comparison.evidence_id, ...allSourceIds]),
+        unknown_ids: displayedUnknowns.map(({ unknown_id: id }) => id),
+        limitations: uniqueSorted([
+            ...comparison.limitations,
+            ...limitations,
+            ...displayedUnknowns.map(({ question }) => `Residual unknown: ${question}`),
+            ...(hiddenUnknownCount > 0
+                ? [
+                    `${hiddenUnknownCount} additional active residual unknowns affect this claim but are omitted by the 100-item display limit.`,
+                ]
+                : []),
+        ]),
+    });
+};
+const validateSourceKinds = (claim, sources) => {
+    const expected = claim.kind === "behavioral"
+        ? ["capture_process_scenario", "rea.process-capture/v2"]
+        : claim.kind === "structural-function"
+            ? ["analyze_function", "rea.analysis/v2"]
+            : ["inventory_artifact", "rea.analysis/v2"];
+    if (sources.some((source) => source.operation !== expected[0] ||
+        source.predicate_type !== expected[1]))
+        throw new TypeError("Comparison source Evidence has an unexpected observation type");
+    for (const source of sources) {
+        if (claim.kind === "behavioral")
+            processCaptureSchema.parse(source.normalized_result);
+        else if (claim.kind === "structural-function")
+            functionDossierSchema.parse(source.normalized_result);
+        else
+            artifactInventoryResultSchema.parse(source.normalized_result);
+    }
+};
+const validateComparisonIdentity = (claim, evidence) => {
+    parseEvidence(evidence);
+    const expected = providers[claim.kind];
+    if (evidence.operation !== expected.operation ||
+        evidence.predicate_type !== expected.predicate ||
+        evidence.provider.id !== expected.id ||
+        evidence.provider.name !== expected.name ||
+        evidence.provider.version !== "1" ||
+        evidence.confidence !== "derived" ||
+        evidence.authority !== "analyst-inference" ||
+        evidence.subject !== null)
+        throw new TypeError("Comparison Evidence identity or authority disagrees");
+};
+const sourceSides = (claim, evidence) => {
+    const parameters = evidence.parameters;
+    if (claim.kind === "behavioral") {
+        const parsed = z
+            .object({
+            left_evidence_id: evidenceIdSchema,
+            right_evidence_id: evidenceIdSchema,
+        })
+            .passthrough()
+            .parse(parameters);
+        return {
+            left: [parsed.left_evidence_id],
+            right: [parsed.right_evidence_id],
+        };
+    }
+    const parsed = z
+        .object({
+        left_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+        right_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    })
+        .passthrough()
+        .parse(parameters);
+    return { left: parsed.left_evidence_ids, right: parsed.right_evidence_ids };
+};
+const observedStatus = (claim, evidence) => {
+    if (claim.kind === "behavioral") {
+        const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
+        validateProcessStatus(result);
+        return claim.dimension === "overall"
+            ? result.status
+            : result[claim.dimension];
+    }
+    if (claim.kind === "structural-function") {
+        const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+        if (claim.dimension === "overall")
+            return result.status;
+        const dimension = result.dimensions.find((item) => item.dimension === claim.dimension);
+        if (dimension === undefined)
+            throw new TypeError("Function comparison dimension missing");
+        if (dimension.evidence_links.some((id) => !evidence.evidence_links.includes(id)))
+            throw new TypeError("Function dimension cites Evidence outside comparison closure");
+        return dimension.status;
+    }
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    if (result.changes.offset !== 0 ||
+        result.changes.next_offset !== null ||
+        result.changes.items.length !== result.changes.total)
+        return "unknown";
+    if (result.changes.items.some((item) => item.evidence_links.some((id) => !evidence.evidence_links.includes(id))))
+        throw new TypeError("Artifact change cites Evidence outside comparison closure");
+    return result.status;
+};
+const validateProcessStatus = (result) => {
+    const dimensions = [
+        result.terminal,
+        result.exit,
+        result.filesystem,
+        result.protocol,
+        result.process,
+    ];
+    const expected = dimensions.includes("truncated")
+        ? "truncated"
+        : dimensions.some((status) => ["added", "removed", "changed"].includes(status))
+            ? "changed"
+            : dimensions.includes("unknown")
+                ? "unknown"
+                : "unchanged";
+    if (result.status !== expected)
+        throw new TypeError("Process comparison status contradicts its dimensions");
+};
+const authorityLimitations = (claim, sources, sides) => {
+    const requiredAuthority = claim.kind === "behavioral" ? "controlled-replay" : "shipped-artifact";
+    const limitations = [];
+    if (sources.some((source) => source.authority !== requiredAuthority ||
+        (claim.kind === "structural-function"
+            ? source.confidence === "inferred"
+            : source.confidence !== "observed")))
+        limitations.push(`Source Evidence lacks qualifying ${requiredAuthority} authority.`);
+    if (claim.kind !== "behavioral" &&
+        sources.some(({ subject }) => subject === null))
+        limitations.push("Structural source artifact identity is unavailable.");
+    if (claim.kind === "behavioral") {
+        const byId = new Map(sources.map((source) => [source.evidence_id, source]));
+        const left = byId.get(sides.left[0] ?? "");
+        const right = byId.get(sides.right[0] ?? "");
+        if (left?.environment === null ||
+            right?.environment === null ||
+            JSON.stringify(left?.environment) !== JSON.stringify(right?.environment))
+            limitations.push("Controlled replay environments are unavailable or incompatible.");
+    }
+    return limitations;
+};
+const classify = (observed, limitations, unknowns) => {
+    if (limitations.length > 0)
+        return "unknown";
+    if (["changed", "added", "removed"].includes(observed))
+        return "fail";
+    if (observed === "unknown" || observed === "truncated" || unknowns.length > 0)
+        return "unknown";
+    return "pass";
+};
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Specification canonicalization failed");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const enforceInputSize = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined ||
+        Buffer.byteLength(encoded, "utf8") > MAX_CANONICAL_BYTES)
+        throw new TypeError("Reconstruction Evidence bundle exceeds byte limit");
+};
+const count = (items, status) => items.filter((item) => item.status === status).length;
+const sameSet = (left, right) => left.length === right.length &&
+    uniqueSorted(left).every((id, index) => id === uniqueSorted(right)[index]);
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));

package/dist/domain/reconstructionVerificationSchemas.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { evidenceBundleSchema } from "./evidenceBundle.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const unknownIdSchema = z.string().regex(/^unk_[a-f0-9]{64}$/u);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const claimIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
+const titleSchema = z.string().trim().min(1).max(500);
+const verificationStatusSchema = z.enum(["pass", "fail", "unknown"]);
+const commonClaim = {
+    claim_id: claimIdSchema,
+    title: titleSchema,
+    comparison_evidence_id: evidenceIdSchema,
+};
+const behavioralClaimSchema = z.object({
+    ...commonClaim,
+    kind: z.literal("behavioral"),
+    dimension: z.enum([
+        "overall",
+        "terminal",
+        "exit",
+        "filesystem",
+        "protocol",
+        "process",
+    ]),
+});
+const functionClaimSchema = z.object({
+    ...commonClaim,
+    kind: z.literal("structural-function"),
+    dimension: z.enum([
+        "overall",
+        "identity",
+        "pseudocode",
+        "assembly",
+        "comments",
+        "calls",
+        "references",
+        "strings_names",
+        "cfg",
+    ]),
+});
+const artifactClaimSchema = z.object({
+    ...commonClaim,
+    kind: z.literal("structural-artifact"),
+    dimension: z.literal("overall"),
+});
+const reconstructionClaimSchema = z.discriminatedUnion("kind", [
+    behavioralClaimSchema,
+    functionClaimSchema,
+    artifactClaimSchema,
+]);
+/** Finite, typed behavioral and structural specification. */
+export const reconstructionSpecificationSchema = z
+    .object({
+    schema_version: z.literal(1),
+    name: z.string().trim().min(1).max(200),
+    claims: z.array(reconstructionClaimSchema).min(1).max(100),
+})
+    .superRefine((value, context) => {
+    const ids = value.claims.map(({ claim_id: id }) => id);
+    if (new Set(ids).size !== ids.length)
+        context.addIssue({ code: "custom", message: "Claim IDs must be unique" });
+    const selectors = value.claims.map(({ kind, comparison_evidence_id: id, dimension }) => `${kind}:${id}:${dimension}`);
+    if (new Set(selectors).size !== selectors.length)
+        context.addIssue({
+            code: "custom",
+            message: "Claim comparison selectors must be unique",
+        });
+});
+/** Bounded reconstruction-verification input. */
+export const reconstructionVerificationInputSchema = z.object({
+    specification: reconstructionSpecificationSchema,
+    evidence_bundle: evidenceBundleSchema,
+    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(),
+});
+export const reconstructionClaimResultSchema = z.object({
+    claim_id: claimIdSchema,
+    kind: z.enum(["behavioral", "structural-function", "structural-artifact"]),
+    dimension: z.string().min(1),
+    status: verificationStatusSchema,
+    observed_status: z.enum([
+        "unchanged",
+        "added",
+        "removed",
+        "changed",
+        "truncated",
+        "unknown",
+    ]),
+    comparison_evidence_id: evidenceIdSchema,
+    left_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    right_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    evidence_links: z.array(evidenceIdSchema).min(3).max(201),
+    unknown_ids: z.array(unknownIdSchema).max(100),
+    limitations: z.array(z.string()),
+});
+/** Evidence-cited result over every declared claim, independently paged. */
+export const reconstructionVerificationResultSchema = z.object({
+    status: verificationStatusSchema,
+    specification_sha256: digestSchema,
+    summary: z.object({
+        total: z.number().int().min(1).max(100),
+        passed: z.number().int().min(0),
+        failed: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+        behavioral: z.number().int().min(0),
+        structural: z.number().int().min(0),
+    }),
+    claims: z.object({
+        items: z.array(reconstructionClaimResultSchema).max(100),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(100),
+        total: z.number().int().min(1).max(100),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    recommended_probes: z
+        .array(z.object({
+        operation: z.string().min(1).max(200),
+        rationale: z.string().min(1).max(1_000),
+        claim_ids: z.array(claimIdSchema).min(1).max(100),
+        unknown_ids: z.array(unknownIdSchema).max(100),
+    }))
+        .max(2_000),
+    evidence_links: z.array(evidenceIdSchema).min(3).max(20_100),
+    limitations: z.array(z.string()),
+});