Skip to content

armgit / rea

Public Imported from GitHub
0

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

14.9 KB
Raw Blame
import type {
  ReconstructionClosureResult,
  ReconstructionCoverageData,
  ReconstructionVerifierContract,
  ParsedReconstructionCoverage,
} from "./reconstructionCoverage.js";
import {
  packageProofHasComparableEvidence,
  verifierHasComparableEvidence,
} from "./reconstructionCoverageEvidence.js";
import {
  compareOffsetDateTimeInstants,
  offsetDateTimeInstantFromEpochMilliseconds,
  type OffsetDateTimeInstant,
} from "./offsetDateTime.js";
import {
  latestVerifierObservationsByVerifier,
  sameVerifierAssessment,
  type VerifierObservation,
} from "./reconstructionCoverageVerifierResults.js";

export const recommendedReconstructionProbes = (
  reasons: readonly ClosureReason[],
): readonly { operation: string; subject_id: string; rationale: string }[] =>
  reasons.map((reason) => ({
    operation: probeOperation(reason.code),
    subject_id: reason.subject_id,
    rationale: reason.detail,
  }));

const probeOperation = (code: ClosureReason["code"]): string => {
  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";
};

type Boundary = ReconstructionCoverageData["boundaries"][number];
type ClosureReason = ReconstructionClosureResult["reasons"][number];
export interface ReconstructionEvaluationContext extends ParsedReconstructionCoverage {
  readonly boundary: Boundary;
  readonly nowEpochMs: number;
  readonly nowInstant: OffsetDateTimeInstant;
  readonly reasons: ClosureReason[];
  readonly evidenceIds: Set<string>;
}

export const evaluateReconstructionSurfaces = (
  context: ReconstructionEvaluationContext,
): void => {
  for (const surfaceId of context.boundary.required_surface_ids) {
    const surface = context.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 (!context.surfaces.has(dependencyId))
        addReason(
          context,
          "dependency-surface-missing",
          surfaceId,
          `Declared dependency surface is absent: ${dependencyId}`,
        );
    evaluateOwner(context, surfaceId);
  }
};

const evaluateOwner = (
  context: ReconstructionEvaluationContext,
  surfaceId: string,
): void => {
  const owners = context.ownersBySurface.get(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: ReadonlyArray<
    readonly [boolean, ClosureReason["code"], string]
  > = [
    [
      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: ReconstructionEvaluationContext,
): void => {
  const indexes = createVerifierIndexes(context);
  for (const claimId of context.boundary.required_claim_ids) {
    const claim = context.claims.get(claimId);
    if (claim === undefined) {
      addReason(
        context,
        "claim-missing",
        claimId,
        "Required finite claim is absent.",
      );
      continue;
    }
    const contracts = indexes.contractsByClaim.get(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, indexes);
  }
};

interface VerifierIndexes {
  readonly contractsByClaim: ReadonlyMap<
    string,
    readonly ReconstructionVerifierContract[]
  >;
  readonly latestResultsByVerifier: ReadonlyMap<
    string,
    readonly VerifierObservation[]
  >;
  readonly artifactDigests: ReadonlySet<string>;
  readonly ownerDigests: ReadonlySet<string>;
  readonly surfaces: ReadonlyMap<
    string,
    ReconstructionCoverageData["surfaces"][number]
  >;
  readonly artifacts: ReadonlyMap<
    string,
    ReconstructionCoverageData["artifacts"][number]
  >;
  readonly ownersBySurface: ReadonlyMap<
    string,
    readonly ReconstructionCoverageData["owners"][number][]
  >;
}

const createVerifierIndexes = (
  context: ReconstructionEvaluationContext,
): VerifierIndexes => {
  const { coverage } = context;
  const contractsByClaim = new Map<string, ReconstructionVerifierContract[]>();
  for (const contract of coverage.verifier_contracts)
    for (const claimId of new Set(contract.claim_ids)) {
      const contracts = contractsByClaim.get(claimId) ?? [];
      contracts.push(contract);
      contractsByClaim.set(claimId, contracts);
    }

  return {
    contractsByClaim,
    latestResultsByVerifier: latestVerifierObservationsByVerifier(
      coverage.verifier_results,
    ),
    artifactDigests: new Set(
      coverage.artifacts.map(({ artifact_sha256: value }) => value),
    ),
    ownerDigests: new Set(
      coverage.owners.flatMap(({ ownership }) =>
        ownership.disposition === "implemented" ? [ownership.owner_sha256] : [],
      ),
    ),
    surfaces: context.surfaces,
    artifacts: context.artifacts,
    ownersBySurface: context.ownersBySurface,
  };
};

const evaluateVerifierResult = (
  context: ReconstructionEvaluationContext,
  claim: ReconstructionCoverageData["claims"][number],
  contract: ReconstructionVerifierContract,
  indexes: VerifierIndexes,
): void => {
  const latestResults = indexes.latestResultsByVerifier.get(
    contract.verifier_id,
  );
  if (latestResults === undefined) {
    addReason(
      context,
      "verifier-result-missing",
      claim.claim_id,
      "Verifier has no recorded result.",
    );
    return;
  }
  addEvidence(
    context,
    latestResults.flatMap(({ result }) => result.evidence_ids),
  );
  const latest = latestResults[0];
  if (latest === undefined) return;
  if (
    !latestResults.every((candidate) =>
      sameVerifierAssessment(latest.result, candidate.result),
    )
  ) {
    addReason(
      context,
      "verifier-result-ambiguous",
      claim.claim_id,
      "Latest verifier observations have conflicting assessment content.",
    );
    return;
  }
  const comparable = latestResults.find(({ result }) =>
    verifierHasComparableEvidence(result, contract, context.evidenceById),
  );
  if (comparable === undefined) {
    addReason(
      context,
      "verifier-result-incompatible",
      claim.claim_id,
      `Latest verifier observation has no cited Evidence with comparable ${contract.authority} authority and confidence.`,
    );
    return;
  }
  const { result } = comparable;
  if (!verifierResultMatchesContract(claim, contract, result, indexes)) {
    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 cutoffEpochMs = context.nowEpochMs - contract.max_age_ms;
  if (
    compareOffsetDateTimeInstants(comparable.instant, context.nowInstant) > 0 ||
    (cutoffEpochMs >= -Number.MAX_SAFE_INTEGER &&
      compareOffsetDateTimeInstants(
        comparable.instant,
        offsetDateTimeInstantFromEpochMilliseconds(cutoffEpochMs),
      ) < 0)
  ) {
    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 verifierResultMatchesContract = (
  claim: ReconstructionCoverageData["claims"][number],
  contract: ReconstructionVerifierContract,
  result: ReconstructionCoverageData["verifier_results"][number],
  indexes: VerifierIndexes,
): boolean => {
  const expectedArtifactDigests = claim.surface_ids.flatMap((surfaceId) => {
    const surface = indexes.surfaces.get(surfaceId);
    const artifact =
      surface === undefined
        ? undefined
        : indexes.artifacts.get(surface.artifact_id);
    return artifact === undefined ? [] : [artifact.artifact_sha256];
  });
  const expectedOwnerDigests = claim.surface_ids.flatMap((surfaceId) =>
    (indexes.ownersBySurface.get(surfaceId) ?? []).flatMap(({ ownership }) =>
      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) =>
      indexes.artifactDigests.has(item),
    ) &&
    expectedArtifactDigests.every((item) =>
      result.artifact_sha256s.includes(item),
    ) &&
    result.owner_sha256s.every((item) => indexes.ownerDigests.has(item)) &&
    expectedOwnerDigests.every((item) => result.owner_sha256s.includes(item)) &&
    result.repeats >= contract.minimum_repeats &&
    claim.required_authority === contract.authority
  );
};

export const evaluateReconstructionCoverageRisks = (
  context: ReconstructionEvaluationContext,
): void => {
  for (const unknownId of context.coverage.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.coverage.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: ReconstructionEvaluationContext,
): void => {
  const requiredArtifactDigests = context.boundary.required_surface_ids.flatMap(
    (surfaceId) => {
      const surface = context.surfaces.get(surfaceId);
      const artifact =
        surface === undefined
          ? undefined
          : context.artifacts.get(surface.artifact_id);
      return artifact === undefined ? [] : [artifact.artifact_sha256];
    },
  );
  for (const kind of context.boundary.required_package_proof_kinds) {
    const proofs = context.coverage.package_proofs.filter(
      (proof) => proof.kind === kind,
    );
    const applicable = (
      proof: ReconstructionCoverageData["package_proofs"][number],
    ): boolean =>
      requiredArtifactDigests.every((digest) =>
        proof.artifact_sha256s.includes(digest),
      ) && packageProofHasComparableEvidence(proof, context.evidenceById);
    const passing = proofs.find(
      (proof) => proof.status === "pass" && applicable(proof),
    );
    if (passing !== undefined) {
      addEvidence(context, passing.evidence_ids);
      continue;
    }
    const failing = proofs.find(
      (proof) => proof.status === "fail" && applicable(proof),
    );
    if (failing !== undefined) {
      addEvidence(context, failing.evidence_ids);
      addReason(
        context,
        "package-proof-failed",
        kind,
        "Required package or integration proof failed.",
      );
    } else if (proofs.length > 0) {
      addEvidence(
        context,
        proofs.flatMap(({ evidence_ids }) => evidence_ids),
      );
      addReason(
        context,
        "package-proof-unknown",
        kind,
        "Required package or integration proof has no qualifying passing Evidence.",
      );
    } else
      addReason(
        context,
        "package-proof-missing",
        kind,
        "Required package or integration proof is missing.",
      );
  }
};

const addReason = (
  context: ReconstructionEvaluationContext,
  code: ClosureReason["code"],
  subjectId: string,
  detail: string,
): void => {
  context.reasons.push({ code, subject_id: subjectId, detail });
};

const addEvidence = (
  context: ReconstructionEvaluationContext,
  evidenceIds: readonly string[],
): void => {
  for (const evidenceId of evidenceIds) context.evidenceIds.add(evidenceId);
};