Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

15.7 KB
Raw Blame
import { artifactComparisonResultSchema } from "./artifactComparison.js";
import {
  ArtifactInventoryCarrierError,
  parseArtifactInventoryEvidence,
} from "./artifactInventoryEvidence.js";
import { uniqueSorted } from "./canonicalOrdering.js";
import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
import {
  assertComparisonFindingLinks,
  comparisonSourceEvidenceSides,
} from "./comparisonSourceEvidence.js";
import type { Evidence } from "./evidence.js";
import { hasComparisonEvidenceIdentity } from "./comparisonEvidenceIdentity.js";
import { readEvidenceBundle } from "./evidenceBundle.js";
import { AnalysisInputError } from "./analysisErrorCore.js";
import { EvidenceIntegrityError } from "./evidenceErrors.js";
import { analysisInputErrorFromIssues } from "./inputIssueProjection.js";
import { readEvidencePayload } from "./evidenceValidation.js";
import { functionComparisonResultSchema } from "./functionComparisonSchemas.js";
import { functionDossierSchema } from "./hopperValues.js";
import { assessFunctionCallCoverage } from "./functionCallCoverage.js";
import { processCaptureComparisonSchema } from "./process/processComparison.js";
import { processCaptureSchema } from "./process/processCapture.js";
import { digestCanonicalValue } from "./canonicalDigest.js";
import {
  reconstructionClaimResultSchema,
  reconstructionSpecificationSchema,
  reconstructionVerificationResultSchema,
  type ReconstructionClaim as Claim,
  type ReconstructionClaimResult as ClaimResult,
  type ReconstructionObservedStatus as ObservedStatus,
  type ReconstructionVerificationResult,
} from "./reconstructionVerificationSchemas.js";
import {
  reconstructionClaimUnknowns,
  reconstructionProbes,
  reconstructionUnknownHeads,
} from "./reconstructionUnknowns.js";
import type { ResidualUnknown } from "./residualUnknown.js";

const comparisonOperationsByClaimKind = {
  behavioral: "compare_process_captures",
  "structural-function": "compare_functions",
  "structural-artifact": "compare_artifacts",
} as const;

interface FunctionSourceFacts {
  readonly evidence_id: string;
  readonly callCoverageBlockers: readonly string[];
  readonly callCoverageDiagnostics: readonly string[];
}

/** Verify only explicitly declared claims; no global equivalence is inferred. */
export const verifyReconstruction = (
  specificationInput: unknown,
  bundleInput: unknown,
): ReconstructionVerificationResult => {
  const parsedSpecification =
    reconstructionSpecificationSchema.safeParse(specificationInput);
  if (!parsedSpecification.success)
    throw analysisInputErrorFromIssues(
      "verify_reconstruction",
      parsedSpecification.error.issues,
      specificationInput,
      { cause: parsedSpecification.error },
    );
  const specification = parsedSpecification.data;
  const bundleResult = readEvidenceBundle(bundleInput);
  if (!bundleResult.ok) throw bundleResult.error;
  const bundle = bundleResult.value;
  const records = new Map(
    bundle.records.map((item) => [item.evidence_id, item]),
  );
  const heads = reconstructionUnknownHeads(bundle.unknowns);
  const results = specification.claims
    .map((claim, index) => evaluateClaim(claim, index, records, heads))
    .sort((left, right) =>
      compareUnicodeCodePoints(left.claim_id, right.claim_id),
    );
  const failed = count(results, "fail");
  const unresolved = count(results, "unknown");
  const probes = reconstructionProbes(results, heads);
  const evidenceLinks = uniqueSorted(
    results.flatMap(({ evidence_links: links }) => links),
  );
  const output = {
    status: failed > 0 ? "fail" : unresolved > 0 ? "unknown" : "pass",
    specification_sha256: digestCanonicalValue(
      {
        ...specification,
        claims: [...specification.claims].sort((left, right) =>
          compareUnicodeCodePoints(left.claim_id, right.claim_id),
        ),
      },
      "Reconstruction specification",
    ),
    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: results,
    },
    recommended_probes: probes,
    evidence_links: evidenceLinks,
    limitations: [
      "Pass means every declared claim passed; it does not establish global implementation equivalence.",
    ],
  };
  return reconstructionVerificationResultSchema.parse(output);
};

const evaluateClaim = (
  claim: Claim,
  claimIndex: number,
  records: ReadonlyMap<string, Evidence>,
  heads: ReadonlyMap<string, ResidualUnknown>,
): ClaimResult => {
  const comparison = records.get(claim.comparison_evidence_id);
  if (comparison === undefined)
    throw missingSourceInputError(
      claimIndex,
      `Missing comparison Evidence ${claim.comparison_evidence_id}`,
    );
  validateComparisonIdentity(claim, comparison, claimIndex);
  const sides = comparisonSourceEvidenceSides(comparison);
  const allSourceIds = uniqueSorted([...sides.left, ...sides.right]);
  if (!sameSet(comparison.evidence_links, allSourceIds))
    throw new EvidenceIntegrityError(
      "Comparison Evidence closure disagrees with its parameters",
      {
        userMessage:
          "Comparison Evidence closure disagrees with its parameters",
      },
    );
  const sources = allSourceIds.map((id) => {
    const source = records.get(id);
    if (source === undefined)
      throw missingSourceInputError(
        claimIndex,
        `Missing source Evidence ${id}`,
      );
    return source;
  });
  const functionSourceFacts = readValidatedSourceFacts(claim, sources);
  const observation = comparisonObservation(claim, comparison);
  const observed = observation.status;
  const callCoverage = sourceCallCoverage(
    claim,
    functionSourceFacts,
    observation.hasIndependentFunctionChange === true,
  );
  const blockers = [
    ...authorityLimitations(claim, sources, sides),
    ...callCoverage.blockers,
  ];
  const relatedUnknowns = reconstructionClaimUnknowns(
    heads,
    comparison.evidence_id,
    allSourceIds,
    claim.dimension,
  );
  const relevantUnknowns = relatedUnknowns;
  const status = classify(observed, blockers, relevantUnknowns);
  const displayedUnknowns = relevantUnknowns;
  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,
      ...observation.limitations,
      ...blockers,
      ...callCoverage.diagnostics,
      ...displayedUnknowns.map(
        ({ question }) => `Residual unknown: ${question}`,
      ),
    ]),
  });
};

const readValidatedSourceFacts = (
  claim: Claim,
  sources: readonly Evidence[],
): readonly FunctionSourceFacts[] => {
  const isExpectedType = (source: Evidence): boolean => {
    if (claim.kind === "behavioral")
      return (
        source.operation === "capture_process_scenario" &&
        source.predicate_type === "rea.process-capture"
      );
    if (claim.kind === "structural-function")
      return (
        source.operation === "analyze_function" &&
        source.predicate_type === "rea.analysis"
      );
    return (
      (source.operation === "inventory_artifact" ||
        source.operation === "inspect_artifact") &&
      source.predicate_type === "rea.analysis"
    );
  };
  if (sources.some((source) => !isExpectedType(source)))
    throw new EvidenceIntegrityError(
      "Comparison source Evidence has an unexpected observation type",
      {
        userMessage:
          "Comparison source Evidence has an unexpected observation type",
      },
    );
  const functionSources: FunctionSourceFacts[] = [];
  for (const source of sources) {
    if (claim.kind === "behavioral") {
      const capture = readEvidencePayload(
        processCaptureSchema,
        source.normalized_result,
      );
      if (!capture.ok) throw capture.error;
    } else if (claim.kind === "structural-function") {
      const parsedDossier = readEvidencePayload(
        functionDossierSchema,
        source.normalized_result,
      );
      if (!parsedDossier.ok) throw parsedDossier.error;
      const dossier = parsedDossier.value;
      const callCoverage = assessFunctionCallCoverage(
        source.relationship_coverage,
        dossier,
      );
      functionSources.push({
        evidence_id: source.evidence_id,
        callCoverageBlockers: callCoverage.blockers,
        callCoverageDiagnostics: callCoverage.diagnostics,
      });
    } else {
      try {
        parseArtifactInventoryEvidence(source);
      } catch (cause: unknown) {
        if (cause instanceof EvidenceIntegrityError) throw cause;
        if (cause instanceof ArtifactInventoryCarrierError)
          throw new EvidenceIntegrityError(cause.message, {
            cause,
            userMessage: cause.message,
          });
        throw cause;
      }
    }
  }
  return functionSources;
};

const validateComparisonIdentity = (
  claim: Claim,
  evidence: Evidence,
  claimIndex: number,
): void => {
  const expectedOperation = comparisonOperationsByClaimKind[claim.kind];
  if (evidence.operation !== expectedOperation)
    throw missingSourceInputError(
      claimIndex,
      `Claim ${claim.claim_id} requires ${expectedOperation} Evidence; selected ${evidence.operation}`,
    );
  if (!hasComparisonEvidenceIdentity(evidence)) {
    const message = "Comparison Evidence identity or authority disagrees";
    throw new EvidenceIntegrityError(message, { userMessage: message });
  }
};

const comparisonObservation = (
  claim: Claim,
  evidence: Evidence,
): {
  readonly status: ObservedStatus;
  readonly limitations: readonly string[];
  readonly hasIndependentFunctionChange?: boolean;
} => {
  if (claim.kind === "behavioral") {
    const parsed = readEvidencePayload(
      processCaptureComparisonSchema,
      evidence.normalized_result,
    );
    if (!parsed.ok) throw parsed.error;
    const result = parsed.value;
    if (claim.dimension !== "overall")
      return { status: result[claim.dimension], limitations: [] };
    if (
      result.status === "unchanged" &&
      result.first_divergence.status === "unknown"
    )
      return {
        status: "unknown",
        limitations: [result.first_divergence.reason],
      };
    return {
      status: result.status,
      limitations: [],
    };
  }
  if (claim.kind === "structural-function") {
    const parsed = readEvidencePayload(
      functionComparisonResultSchema,
      evidence.normalized_result,
    );
    if (!parsed.ok) throw parsed.error;
    const result = parsed.value;
    assertComparisonFindingLinks(
      evidence,
      result.dimensions.flatMap(({ evidence_links }) => evidence_links),
    );
    if (claim.dimension === "overall")
      return {
        status: result.status,
        limitations: result.dimensions.flatMap(
          ({ limitations }) => limitations,
        ),
        // Historical overall changes can be caused only by incomplete call
        // sets. Ignore that aggregate change when independently checking the
        // source call-coverage limitations.
        hasIndependentFunctionChange:
          result.function_match.status === "mismatched" ||
          (result.function_match.status === "matched" &&
            result.dimensions.some(
              (dimension) =>
                dimension.dimension !== "calls" &&
                dimension.status === "changed",
            )),
      };
    const dimension = result.dimensions.find(
      (item) => item.dimension === claim.dimension,
    );
    if (dimension === undefined) {
      const message = "Function comparison dimension missing";
      throw new EvidenceIntegrityError(message, { userMessage: message });
    }
    return { status: dimension.status, limitations: dimension.limitations };
  }
  const parsed = readEvidencePayload(
    artifactComparisonResultSchema,
    evidence.normalized_result,
  );
  if (!parsed.ok) throw parsed.error;
  const result = parsed.value;
  assertComparisonFindingLinks(
    evidence,
    result.changes.flatMap(({ evidence_links }) => evidence_links),
  );
  return { status: result.status, limitations: [] };
};

const missingSourceInputError = (claimIndex: number, message: string) =>
  new AnalysisInputError("verify_reconstruction", { userMessage: message }, [
    {
      path: ["claims", claimIndex, "comparison_evidence_id"],
      reason: "invalid_value",
      message,
    },
  ]);

const authorityLimitations = (
  claim: Claim,
  sources: readonly Evidence[],
  sides: {
    readonly left: readonly string[];
    readonly right: readonly string[];
  },
): string[] => {
  const requiredAuthority =
    claim.kind === "behavioral" ? "controlled-replay" : "shipped-artifact";
  const limitations: string[] = [];
  if (sides.left.some((id) => sides.right.includes(id)))
    limitations.push(
      "A source observation appears on both comparison sides; independent original and reconstruction observations are unavailable.",
    );
  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 referenceEnvironment = sources[0]?.environment;
    if (
      referenceEnvironment === null ||
      referenceEnvironment === undefined ||
      sources.some(
        ({ environment }) =>
          environment === null ||
          JSON.stringify(environment) !== JSON.stringify(referenceEnvironment),
      )
    )
      limitations.push(
        "Controlled replay environments are unavailable or incompatible.",
      );
  }
  return limitations;
};

const sourceCallCoverage = (
  claim: Claim,
  functionSources: readonly FunctionSourceFacts[],
  hasIndependentFunctionChange: boolean,
): { blockers: string[]; diagnostics: string[] } => {
  if (
    claim.kind !== "structural-function" ||
    (claim.dimension !== "calls" &&
      !(claim.dimension === "overall" && !hasIndependentFunctionChange))
  )
    return { blockers: [], diagnostics: [] };
  return {
    blockers: functionSources.flatMap(({ evidence_id, callCoverageBlockers }) =>
      callCoverageBlockers.map((reason) => `Source ${evidence_id}: ${reason}`),
    ),
    diagnostics: functionSources.flatMap(
      ({ evidence_id, callCoverageDiagnostics }) =>
        callCoverageDiagnostics.map(
          (reason) => `Source ${evidence_id}: ${reason}`,
        ),
    ),
  };
};

const classify = (
  observed: ObservedStatus,
  limitations: readonly string[],
  unknowns: readonly ResidualUnknown[],
): ClaimResult["status"] => {
  if (limitations.length > 0) return "unknown";
  if (["changed", "added", "removed", "contradiction"].includes(observed))
    return "fail";
  if (observed === "unknown" || observed === "truncated" || unknowns.length > 0)
    return "unknown";
  return "pass";
};

const count = (
  items: readonly ClaimResult[],
  status: ClaimResult["status"],
): number => items.filter((item) => item.status === status).length;
const sameSet = (left: readonly string[], right: readonly string[]): boolean =>
  uniqueSorted(left).length === uniqueSorted(right).length &&
  uniqueSorted(left).every((id, index) => id === uniqueSorted(right)[index]);