refactor: make analysis states unrepresentable

Author: morluto

docs/verification/managed-conformance-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "manifest_id": "ecm_aba877529714e59795e8a7b51c5513b17081bd701cea1ffee31422a1d95dfa31",
+  "manifest_id": "ecm_1fde266c466ffd6dde6f171e702f2929fc19ab8afb9958d3ae11a518133740da",
   "verifier": {
     "id": "rea-managed-conformance",
     "version": "1"
@@ -14,7 +14,7 @@
   "skill_digests": [
     {
       "skill_id": "reverse-engineer-anything",
-      "sha256": "43fccde70ab600dfc86785a37b414865cb8c0f2cb479eb4ed6c2a90998e0f6a6"
+      "sha256": "44a7bc2732a693757d8c54a99362422111573fdb73bd61c562421c7787a87b1a"
     }
   ],
   "claims": [

scripts/verify-managed-conformance.mjs

@@ -344,11 +344,11 @@ try {
   assert.equal(reconstructionImport.value.confidence, "inferred");
   const runtimePlan = await planManagedRuntimeCorrelationEvidence(
     {
-      policy: {
-        enabled: true,
+      policy: () => ({
+        status: "enabled",
         roots: [workspace],
         executablePath: runtimeExecutable,
-      },
+      }),
       authority: runtimeAuthority.value,
     },
     {

src/application/ApplicationWorkflowEvidenceResolver.ts

@@ -12,6 +12,7 @@ import {
   type TraceApplicationFeatureRequest,
   type TraceJavaScriptSemanticsRequest,
 } from "../contracts/applicationWorkflowInputContracts.js";
+import type { Evidence } from "../domain/evidence.js";
 import { AnalysisInputError, type AnalysisError } from "../domain/errors.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
@@ -69,11 +70,7 @@ export const resolveTraceApplicationFeatureRequestValidated = (
   input: TraceApplicationFeatureRequest,
   lookup?: EvidenceLookup,
 ): Result<TraceInput, AnalysisError> => {
-  const application = graphEvidence(
-    input.application,
-    input.application_evidence_id,
-    lookup,
-  );
+  const application = graphEvidence(input, lookup);
   if (!application.ok) return application;
   const native = resolveEvidenceReferences(
     lookup,
@@ -109,11 +106,7 @@ export const resolveTraceJavaScriptSemanticsRequestValidated = (
   input: TraceJavaScriptSemanticsRequest,
   lookup?: EvidenceLookup,
 ): Result<SemanticTraceInput, AnalysisError> => {
-  const application = graphEvidence(
-    input.application,
-    input.application_evidence_id,
-    lookup,
-  );
+  const application = graphEvidence(input, lookup);
   if (!application.ok) return application;
   const raw = { application: application.value, query: input.query };
   const parsed = traceJavaScriptSemanticsInputSchema.safeParse(raw);
@@ -138,9 +131,19 @@ export const resolveCompareApplicationVersionsRequestValidated = (
   input: CompareApplicationVersionsRequest,
   lookup?: EvidenceLookup,
 ): Result<ComparisonInput, AnalysisError> => {
-  const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+  const left = graphEvidence(
+    "left" in input
+      ? { application: input.left }
+      : { application_evidence_id: input.left_evidence_id },
+    lookup,
+  );
   if (!left.ok) return left;
-  const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+  const right = graphEvidence(
+    "right" in input
+      ? { application: input.right }
+      : { application_evidence_id: input.right_evidence_id },
+    lookup,
+  );
   if (!right.ok) return right;
   const leftNative = resolveEvidenceReferences(
     lookup,
@@ -190,11 +193,7 @@ export const resolveCompareSourceToBundleRequestValidated = (
   input: CompareSourceToBundleRequest,
   lookup?: EvidenceLookup,
 ): Result<SourceToBundleInput, AnalysisError> => {
-  const application = graphEvidence(
-    input.application,
-    input.application_evidence_id,
-    lookup,
-  );
+  const application = graphEvidence(input, lookup);
   if (!application.ok) return application;
   const raw = {
     reference: input.reference,
@@ -226,9 +225,19 @@ export const resolveCompareJavaScriptExportShapesRequestValidated = (
   input: CompareJavaScriptExportShapesRequest,
   lookup?: EvidenceLookup,
 ): Result<ExportShapeComparisonInput, AnalysisError> => {
-  const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+  const left = graphEvidence(
+    "left" in input
+      ? { application: input.left }
+      : { application_evidence_id: input.left_evidence_id },
+    lookup,
+  );
   if (!left.ok) return left;
-  const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+  const right = graphEvidence(
+    "right" in input
+      ? { application: input.right }
+      : { application_evidence_id: input.right_evidence_id },
+    lookup,
+  );
   if (!right.ok) return right;
   const raw = {
     left: left.value,
@@ -249,19 +258,15 @@ export const resolveCompareJavaScriptExportShapesRequestValidated = (
 };
 
 const graphEvidence = (
-  evidence:
-    | TraceApplicationFeatureRequest["application"]
-    | TraceJavaScriptSemanticsRequest["application"]
-    | CompareApplicationVersionsRequest["left"]
-    | CompareJavaScriptExportShapesRequest["left"]
-    | CompareSourceToBundleRequest["application"],
-  evidenceId: string | undefined,
+  source:
+    | { readonly application: Evidence }
+    | { readonly application_evidence_id: string },
   lookup: EvidenceLookup | undefined,
 ) => {
-  if (evidence !== undefined) return ok(evidence);
+  if ("application" in source) return ok(source.application);
   const resolved = resolveEvidenceReferences(
     lookup,
-    evidenceId === undefined ? [] : [evidenceId],
+    [source.application_evidence_id],
     APPLICATION_GRAPH_IDENTITIES,
   );
   return resolved.ok ? ok(resolved.value[0]) : resolved;

src/application/ArtifactInventory/policy.ts

@@ -0,0 +1,41 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import type {
+  ArtifactIntegrityPolicy,
+  ArtifactNativeMountPolicy,
+} from "./types.js";
+
+/** Parsed caller intent for integrity mismatch handling. */
+export type ArtifactIntegrityIntent =
+  | { readonly mode: "fail" }
+  | {
+      readonly mode: "record-and-continue";
+      readonly maxMismatches: number;
+    };
+
+/** Resolve caller approval and operator policy before native reader selection. */
+export const resolveNativeMountPolicy = (
+  approved: boolean,
+  enabled: boolean,
+): ArtifactNativeMountPolicy => {
+  if (!approved) return { status: "disabled" };
+  if (!enabled)
+    throw new ArtifactReaderFailure(
+      "unavailable",
+      "Native DMG mounting is disabled by operator policy",
+    );
+  return { status: "approved" };
+};
+
+/** Resolve parsed caller intent and operator policy before artifact scanning. */
+export const resolveArtifactIntegrityPolicy = (
+  intent: ArtifactIntegrityIntent,
+  enabled: boolean,
+): ArtifactIntegrityPolicy => {
+  if (intent.mode === "fail") return intent;
+  if (!enabled)
+    throw new ArtifactReaderFailure(
+      "policy",
+      "Integrity continuation requires explicit approval and operator policy",
+    );
+  return intent;
+};

src/application/ArtifactInventory/reader.ts

@@ -1,8 +1,5 @@
 import { AsarArtifactReader } from "../../artifacts/AsarArtifactReader.js";
-import {
-  ArtifactReaderFailure,
-  type ArtifactReader,
-} from "../../artifacts/ArtifactReader.js";
+import type { ArtifactReader } from "../../artifacts/ArtifactReader.js";
 import { DirectoryArtifactReader } from "../../artifacts/DirectoryArtifactReader.js";
 import { MachOSliceArtifactReader } from "../../artifacts/MachOSliceArtifactReader.js";
 import { NativeDmgArtifactReader } from "../../artifacts/NativeDmgArtifactReader.js";
@@ -32,12 +29,7 @@ export const createReader = async (
         ? new MachOSliceArtifactReader(path)
         : undefined;
     case "dmg":
-      if (!nativeMount.nativeMountApproved) return undefined;
-      if (!nativeMount.nativeMountEnabled)
-        throw new ArtifactReaderFailure(
-          "unavailable",
-          "Native DMG mounting is disabled by operator policy",
-        );
+      if (nativeMount.status === "disabled") return undefined;
       return NativeDmgArtifactReader.create(path, signal);
     default:
       return undefined;

src/application/ArtifactInventory/scanCanonical.ts

@@ -44,14 +44,6 @@ export const scanCanonicalArtifactInventory = async (
   options: ArtifactInventoryOptions = {},
 ): Promise<ArtifactInventorySnapshot> => {
   const integrity = options.integrity ?? STRICT_INTEGRITY_POLICY;
-  if (
-    integrity.mode === "record-and-continue" &&
-    (!integrity.approved || !integrity.enabled)
-  )
-    throw new ArtifactReaderFailure(
-      "policy",
-      "Integrity continuation requires explicit approval and operator policy",
-    );
   const metadata = await lstat(path);
   const rootFormat = await classifyRoot(path, metadata.isDirectory());
   const rootDigest = metadata.isDirectory()

src/application/ArtifactInventory/scanReader.ts

@@ -166,19 +166,19 @@ const digestArtifactEntry = async (
   context.totalBytes += digest.bytes;
   const mismatched =
     entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
-  if (mismatched && context.integrity.mode === "fail")
-    throw new ArtifactReaderFailure(
-      "integrity",
-      `Artifact integrity metadata disagrees with content: ${logicalPath}`,
-      undefined,
-      {
-        logicalPath,
-        declaredSha256: entry.declaredSha256,
-        calculatedSha256: digest.sha256,
-        unpacked: entry.unpacked,
-      },
-    );
   if (mismatched && entry.declaredSha256 !== null) {
+    if (context.integrity.mode === "fail")
+      throw new ArtifactReaderFailure(
+        "integrity",
+        `Artifact integrity metadata disagrees with content: ${logicalPath}`,
+        undefined,
+        {
+          logicalPath,
+          declaredSha256: entry.declaredSha256,
+          calculatedSha256: digest.sha256,
+          unpacked: entry.unpacked,
+        },
+      );
     if (context.pendingContradictions.length >= context.integrity.maxMismatches)
       throw new ArtifactReaderFailure(
         "limit",

src/application/ArtifactInventory/types.ts

@@ -13,30 +13,25 @@ export interface InventoryPageInput {
   readonly edgeLimit: number;
 }
 
-/** Per-request authority combined with operator-owned native mount policy. */
-export interface ArtifactNativeMountPolicy {
-  readonly nativeMountApproved: boolean;
-  readonly nativeMountEnabled: boolean;
-}
+/** Resolved native mount authority admitted to the artifact reader. */
+export type ArtifactNativeMountPolicy =
+  | { readonly status: "disabled" }
+  | { readonly status: "approved" };
 
 export const NATIVE_MOUNT_DISABLED: ArtifactNativeMountPolicy = {
-  nativeMountApproved: false,
-  nativeMountEnabled: false,
+  status: "disabled",
 };
 
-/** Explicit caller approval bounded by operator-owned integrity policy. */
-export interface ArtifactIntegrityPolicy {
-  readonly mode: "fail" | "record-and-continue";
-  readonly approved: boolean;
-  readonly enabled: boolean;
-  readonly maxMismatches: number;
-}
+/** Resolved integrity behavior admitted to the artifact scanner. */
+export type ArtifactIntegrityPolicy =
+  | { readonly mode: "fail" }
+  | {
+      readonly mode: "record-and-continue";
+      readonly maxMismatches: number;
+    };
 
 export const STRICT_INTEGRITY_POLICY: ArtifactIntegrityPolicy = {
   mode: "fail",
-  approved: false,
-  enabled: false,
-  maxMismatches: 1,
 };
 
 /** Options shared by artifact inventory scans. */

src/application/BinarySession.ts

@@ -74,9 +74,9 @@ export class BinarySession
   #transition: Promise<void> = Promise.resolve();
   readonly #calls = new Set<Promise<unknown>>();
   readonly #providerRouter: SessionProviderRouter;
-  readonly #runtimeAvailability = new Map<
+  readonly #runtimeUnavailability = new Map<
     string,
-    { readonly available: boolean; readonly reason: string | null }
+    { readonly reason: string }
   >();
   readonly #availabilityListeners = new Set<() => void | Promise<void>>();
 
@@ -272,7 +272,7 @@ export class BinarySession
       target: this.#active?.target,
       route: this.#currentRoute(),
       router: this.#providerRouter,
-      runtimeAvailability: this.#runtimeAvailability,
+      runtimeUnavailability: this.#runtimeUnavailability,
       runId: this.#active?.runId,
       runtimeLineageSnapshots:
         this.#active?.client.runtimeLineageSnapshots?.() ?? [],
@@ -344,12 +344,12 @@ export class BinarySession
     result: Result<AnalysisExecution, AnalysisError>,
   ): void {
     if (result.ok) {
-      if (this.#setRuntimeAvailability(operation, true, null))
+      if (this.#markRuntimeAvailable(operation))
         this.#emitAvailabilityChanged();
       return;
     }
     if (result.error._tag === "AnalysisCapabilityUnavailableError") {
-      if (this.#setRuntimeAvailability(operation, false, result.error.message))
+      if (this.#markRuntimeUnavailable(operation, result.error.message))
         this.#emitAvailabilityChanged();
       return;
     }
@@ -367,32 +367,28 @@ export class BinarySession
       for (const descriptor of capabilities?.values() ?? [])
         if (providerId !== undefined && descriptor.provider.id === providerId)
           changed =
-            this.#setRuntimeAvailability(
+            this.#markRuntimeUnavailable(
               descriptor.operation,
-              false,
               "Provider became unavailable during this session.",
             ) || changed;
       if (changed) this.#emitAvailabilityChanged();
     }
   }
 
-  #setRuntimeAvailability(
-    operation: string,
-    available: boolean,
-    reason: string | null,
-  ): boolean {
-    const current = this.#runtimeAvailability.get(operation);
-    if (current?.available === available && current.reason === reason)
-      return false;
-    if (available && current === undefined) return false;
-    if (available) this.#runtimeAvailability.delete(operation);
-    else this.#runtimeAvailability.set(operation, { available, reason });
+  #markRuntimeAvailable(operation: string): boolean {
+    return this.#runtimeUnavailability.delete(operation);
+  }
+
+  #markRuntimeUnavailable(operation: string, reason: string): boolean {
+    const current = this.#runtimeUnavailability.get(operation);
+    if (current?.reason === reason) return false;
+    this.#runtimeUnavailability.set(operation, { reason });
     return true;
   }
 
   #clearRuntimeAvailability(): void {
-    if (this.#runtimeAvailability.size === 0) return;
-    this.#runtimeAvailability.clear();
+    if (this.#runtimeUnavailability.size === 0) return;
+    this.#runtimeUnavailability.clear();
     this.#emitAvailabilityChanged();
   }