chore: merge main into codex/openapi-partial-evidence

src/application/apiContract/ApiContractService.test.ts

@@ -5,6 +5,8 @@ import { expect, it, vi } from "vitest";
 import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
 import { apiContractSchema } from "../../domain/apiContract/apiContract.js";
 import { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js";
+import { parseEvidence } from "../../domain/evidence.js";
+import { projectAnalysisView } from "../../domain/analysisView/analysisView.js";
 import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
 import { inspectApiContractEvidence } from "./ApiContractService.js";
 import * as readOwner from "./ApiContractRead.js";
@@ -317,3 +319,89 @@ it("cancels a cooperative document traversal after the actual verified file read
     await resources.close();
   }
 });
+
+it.each(["between-paths", "after-projection"] as const)(
+  "preserves authenticated OpenAPI facts on cancellation %s",
+  async (stage) => {
+    const bytes = JSON.stringify({
+      openapi: "3.1.2",
+      info: { title: "Cancellation", version: "1" },
+      paths: { "/first": { get: {} }, "/second": { post: {} } },
+    });
+    const { path } = await inputFile(bytes);
+    const resources = new ArtifactResourceScope();
+    const controller = new AbortController();
+    const realParse = parser.parseApiContractSteps;
+    try {
+      const baseline = await inspectApiContractEvidence({ path }, resources);
+      if (!baseline.ok) throw baseline.error;
+      const complete = apiContractSchema.parse(
+        baseline.value.normalized_result,
+      );
+      const scheduled = vi
+        .spyOn(parser, "parseApiContractSteps")
+        .mockImplementationOnce(function* (...args) {
+          const steps = realParse(...args);
+          if (stage === "between-paths") {
+            expect(steps.next().done).toBe(false);
+            expect(steps.next().done).toBe(false);
+            setImmediate(() => controller.abort(stage));
+            return yield* steps;
+          }
+          const result = yield* steps;
+          setImmediate(() => controller.abort(stage));
+          return result;
+        });
+      try {
+        const result = await inspectApiContractEvidence({ path }, resources, {
+          signal: controller.signal,
+        });
+        if (result.ok) throw new Error("Expected cancellation");
+        expect(result.error._tag).toBe("AnalysisCancelledError");
+        expect(result.error.cause).toBe(stage);
+        const evidence = parseEvidence(result.error.partialObservation);
+        const retained = apiContractSchema.parse(evidence.normalized_result);
+        expect(evidence.subject).toEqual(baseline.value.subject);
+        expect(evidence.parameters).toEqual(baseline.value.parameters);
+        expect(retained.artifact).toEqual(complete.artifact);
+        expect(retained.contract_id).toBe(complete.contract_id);
+        if (stage === "between-paths") {
+          expect(retained.operations).toEqual(complete.operations.slice(0, 1));
+          expect(retained.source_coverage.status).toBe("partial");
+          expect(evidence.evidence_id).not.toBe(baseline.value.evidence_id);
+          const page = projectAnalysisView(
+            {
+              evidenceId: evidence.evidence_id,
+              operation: evidence.operation,
+              predicateType: evidence.predicate_type,
+              normalizedResult: evidence.normalized_result,
+              limitations: evidence.limitations,
+            },
+            {
+              kind: "api-contract",
+              collection: "operations",
+              offset: 0,
+              limit: 1,
+            },
+          );
+          expect(page).toMatchObject({
+            ok: true,
+            value: {
+              parent_evidence_id: evidence.evidence_id,
+              items: [{ path: "/first", state: "declared" }],
+              coverage: { exhausted: true },
+              source_coverage: { status: "partial" },
+            },
+          });
+        } else {
+          expect(retained).toEqual(complete);
+          expect(evidence.evidence_id).toBe(baseline.value.evidence_id);
+        }
+      } finally {
+        scheduled.mockRestore();
+      }
+    } finally {
+      await resources.close();
+    }
+  },
+);

src/application/apiContract/ApiContractService.ts

@@ -11,6 +11,8 @@ import { err, ok, type Result } from "../../domain/result.js";
 import {
   API_CONTRACT_OPERATION as operation,
   API_CONTRACT_PROVIDER,
+  apiContractSchema,
+  type ApiContract,
   type ApiContractArtifact,
 } from "../../domain/apiContract/apiContract.js";
 import {
@@ -70,8 +72,32 @@ function* documentSteps(document: unknown, artifact: ApiContractArtifact) {
   return yield* parseApiContractSteps(document, artifact);
 }
 
+type OpenApiInput = Extract<
+  InspectApiContractInput,
+  { format: "openapi-json" }
+>;
+
+const documentEvidence = (input: OpenApiInput, result: ApiContract): Evidence =>
+  createEvidence(
+    { path: input.path, format: "file", sha256: result.artifact.sha256 },
+    API_CONTRACT_PROVIDER,
+    {
+      operation,
+      predicateType: "rea.api-contract-inventory",
+      parameters: {
+        path: input.path,
+        format: input.format,
+        max_file_bytes: input.max_file_bytes,
+      },
+      result,
+      confidence: "observed",
+      limitations: result.limitations,
+      locations: [{ kind: "artifact-path", path: input.path }],
+    },
+  );
+
 const importDocument = async (
-  input: Extract<InspectApiContractInput, { format: "openapi-json" }>,
+  input: OpenApiInput,
   bytes: Buffer,
   sha256: string,
   signal?: AbortSignal,
@@ -86,26 +112,16 @@ const importDocument = async (
     }),
     signal,
   );
-  if (!parsed.ok) return parsed;
-  const result = parsed.value;
+  if (!parsed.ok) {
+    const partial = apiContractSchema.safeParse(
+      parsed.error.partialObservation,
+    );
+    if (partial.success)
+      parsed.error.partialObservation = documentEvidence(input, partial.data);
+    return parsed;
+  }
   return completeProviderEvidence(
-    createEvidence(
-      { path: input.path, format: "file", sha256 },
-      API_CONTRACT_PROVIDER,
-      {
-        operation,
-        predicateType: "rea.api-contract-inventory",
-        parameters: {
-          path: input.path,
-          format: input.format,
-          max_file_bytes: input.max_file_bytes,
-        },
-        result,
-        confidence: "observed",
-        limitations: result.limitations,
-        locations: [{ kind: "artifact-path", path: input.path }],
-      },
-    ),
+    documentEvidence(input, parsed.value),
     signal,
   );
 };

src/domain/analysisErrorBase.ts

@@ -1,6 +1,7 @@
 import type { PartialTaskMeasurement } from "./desktop/taskDifficulty.js";
 import type { AppleIpsPartialObservation } from "./native/appleIps.js";
 import type { PlaywrightTrace } from "./playwrightTrace/playwrightTrace.js";
+import type { ApiContract } from "./apiContract/apiContract.js";
 import type { GraphqlContract } from "./apiContract/graphqlContract.js";
 import type { SavedAnalysisSnapshotPartialObservation } from "./savedAnalysisSnapshot.js";
 import type { AnalysisSettingLimit } from "./analysisSettings.js";
@@ -498,6 +499,7 @@ export type AnalysisPartialObservation =
     }
   | { readonly kind: "unretained-evidence"; readonly evidence: Evidence }
   | { readonly kind: "retained-evidence"; readonly evidence_id: string }
+  | ApiContract
   | GraphqlContract
   | PlaywrightTrace
   | SavedAnalysisSnapshotPartialObservation

src/domain/analysisErrorPresentation.ts

@@ -73,8 +73,7 @@ export const analysisErrorRemediationAction = (
   error = resolvedAnalysisError(error);
   const continuing =
     callerLifetime === "continuing"
-      ? (error.continuingCallerGuidance?.remediationAction ??
-        hopperContinuingRecovery(error)?.remediationAction)
+      ? error.continuingCallerGuidance?.remediationAction
       : undefined;
   if (continuing !== undefined) return continuing;
   if (
@@ -163,13 +162,11 @@ export const analysisErrorRemediationAction = (
   if (error instanceof HopperTimeoutError)
     return error.operation === undefined
       ? HOPPER_STARTUP_TIMEOUT_REMEDIATION
-      : RERUN_HOPPER_INVOCATION;
+      : error.providerState === "busy"
+        ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
+        : "Check binary_session for Hopper health, then retry the operation.";
   if (error instanceof HopperProcessError)
-    return error.failureCode !== undefined && error.userMessage !== undefined
-      ? error.userMessage
-      : error.stage === "launch"
-        ? "Review the captured launcher diagnostics and Hopper setup, then retry opening the target."
-        : RERUN_HOPPER_INVOCATION;
+    return hopperProcessRemediation(error);
   if (error instanceof HopperStartError)
     return error.ownerRunId === undefined
       ? "Check the Hopper launcher and target details, then retry opening the target."
@@ -430,19 +427,10 @@ const analysisErrorUserMessageParts = (
 ): { readonly outcome: string; readonly continuing?: string } => {
   error = resolvedAnalysisError(error);
   const outcome = outcomeUserMessage(error);
-  const continuing =
-    error.continuingCallerGuidance?.userMessage ??
-    hopperContinuingRecovery(error)?.userMessage;
+  const continuing = error.continuingCallerGuidance?.userMessage;
   return continuing === undefined ? { outcome } : { outcome, continuing };
 };
 
-/** Whether a child diagnostic needs a distinct continuing guidance snapshot. */
-export const hasAnalysisContinuingCallerGuidance = (
-  error: AnalysisError,
-): boolean =>
-  error.continuingCallerGuidance !== undefined ||
-  hopperContinuingRecovery(error) !== undefined;
-
 /**
  * Re-attribute one failure's message and another's remediation to a composed
  * error, keeping the form each caller lifetime receives.
@@ -562,8 +550,8 @@ const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
       return "REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying.";
     const request = error.operation;
     return error.providerState === "busy"
-      ? `Hopper timed out during ${request} while the provider remained busy.`
-      : `Hopper timed out during ${request} before it started.`;
+      ? `Hopper timed out during ${request} while the provider remained busy. Check binary_session.analysis_activity, wait for the active request to finish, then retry.`
+      : `Hopper timed out during ${request} before it started. Check binary_session for provider health, then retry.`;
   }
   if (error instanceof HopperProcessError) return hopperProcessMessage(error);
   if (error instanceof HopperStartError)
@@ -579,38 +567,16 @@ const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
 const RESTART_OWNED_PROVIDER =
   "Restart the owned provider by calling close_binary, then open the target again and retry.";
 const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary preserves retained Evidence and Unknown history on this connection; export_evidence_bundle before ending the REA process if you need to resume later.`;
-const RERUN_HOPPER_INVOCATION =
-  "Review the reported Hopper state and resolve any incomplete cleanup before rerunning the command.";
 
-const hopperContinuingRecovery = (
-  error: AnalysisError,
-): AnalysisContinuingCallerGuidance | undefined => {
-  if (error instanceof HopperTimeoutError && error.operation !== undefined) {
-    const action =
-      error.providerState === "busy"
-        ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
-        : "Check binary_session for Hopper health, then retry the operation.";
-    return { userMessage: action, remediationAction: action };
-  }
-  if (!(error instanceof HopperProcessError)) return undefined;
-  if (
-    error.providerState === "exited" &&
-    (error.stage === "launch" || error.failureCode !== undefined)
-  )
-    return undefined;
-  const action =
-    error.providerState === "unreachable"
-      ? RESTART_UNREACHABLE_HOPPER
-      : providerRetryAction(error.providerState) === "restart_provider"
-        ? RESTART_OWNED_PROVIDER
-        : "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
-  return {
-    userMessage: action,
-    ...(error.stage === "launch" ||
-    (error.failureCode !== undefined && error.userMessage !== undefined)
-      ? {}
-      : { remediationAction: action }),
-  };
+const hopperProcessRemediation = (error: HopperProcessError): string => {
+  if (error.failureCode !== undefined && error.userMessage !== undefined)
+    return error.userMessage;
+  if (error.stage === "launch")
+    return "Review the captured launcher diagnostics and Hopper setup, then retry opening the target.";
+  if (error.providerState === "unreachable") return RESTART_UNREACHABLE_HOPPER;
+  if (providerRetryAction(error.providerState) === "restart_provider")
+    return RESTART_OWNED_PROVIDER;
+  return "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
 };
 
 const hopperProcessMessage = (error: HopperProcessError): string => {
@@ -630,11 +596,15 @@ const hopperProcessMessage = (error: HopperProcessError): string => {
           ? "no exit code was observed"
           : `signal ${signal}`
         : `exit code ${String(error.exitCode)}`;
-    return `Hopper exited during ${where} (${exit}).${startup}${request}`;
+    const recovery =
+      error.failureCode === undefined && stage !== "launch"
+        ? ` ${RESTART_OWNED_PROVIDER}`
+        : "";
+    return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
   }
   if (error.providerState === "unreachable")
-    return `Hopper became unreachable during ${where}; its process exit was not observed.${startup}${request}`;
-  return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup}${request}`;
+    return `Hopper became unreachable during ${where}; its process exit was not observed. ${RESTART_UNREACHABLE_HOPPER}${startup}${request}`;
+  return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup} Read binary_session.provider_operation_health for this request before retrying or restarting.${request}`;
 };
 
 const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {

src/domain/analysisErrorProjection.test.ts

@@ -1569,91 +1569,11 @@ describe("analysis error projection: caller lifetime", () => {
       applies_at: "next_invocation",
       environment: "REA_HOPPER_STARTUP_TIMEOUT_MS",
     });
-  });
-});
-
-describe("analysis error projection: Hopper caller lifetime", () => {
-  it.each([
-    [
-      new HopperProcessError(7, { operation: "search_strings", requestId: 4 }),
-      "close_binary",
-      "exit code 7",
-    ],
-    [
-      new HopperProcessError(null, {
-        operation: "search_strings",
-        providerState: "unreachable",
-      }),
-      "export_evidence_bundle",
-      "process exit was not observed",
-    ],
-    [
-      new HopperProcessError(null, { operation: "search_strings" }),
-      "binary_session.provider_operation_health",
-      "could not determine",
-    ],
-    [
-      new HopperTimeoutError(30_000, "search_strings", 42, "busy"),
-      "binary_session.analysis_activity",
-      "remained busy",
-    ],
-    [
-      new HopperTimeoutError(30_000, "search_strings", 42, "not_started"),
-      "binary_session",
-      "before it started",
-    ],
-  ] as const)(
-    "keeps Hopper outcome facts and scopes request recovery to the caller",
-    (error, continuingTool, outcome) => {
-      const continuing = projectAnalysisError(error);
-      const invocation = projectAnalysisError(error, "invocation");
-      expect(continuing.message).toContain(continuingTool);
-      expect(continuing.remediation.action).toContain(continuingTool);
-      expect(invocation.message).toContain(outcome);
-      expect(invocation.message).not.toContain(continuingTool);
-      expect(invocation.remediation.action).toContain("rerunning the command");
-      expect(invocation.remediation.action).not.toContain(continuingTool);
-      expect(invocation.details).toEqual(continuing.details);
-      expect(invocation.code).toBe(continuing.code);
-      expect(invocation.category).toBe(continuing.category);
-      expect(invocation.retryable).toBe(continuing.retryable);
-      expect(analysisErrorProjectionSchema.parse(invocation)).toEqual(
-        invocation,
-      );
-    },
-  );
-
-  it("keeps Hopper recovery scoped through composed cleanup and its history", () => {
-    const primary = new HopperProcessError(null, {
-      operation: "search_strings",
-      providerState: "unreachable",
-    });
-    const cleanup = new ProviderCleanupError("hopper", ["hopper-bridge"], {});
-    const composed = analysisErrorWithCleanupFailure(
-      primary,
-      cleanup,
-    ).bindCleanupDependencies([cleanup]);
-    const invocationPrimary = projectAnalysisError(primary, "invocation");
-    const continuingPrimary = projectAnalysisError(primary);
-    const invocation = projectAnalysisError(composed, "invocation");
-    const continuing = projectAnalysisError(composed);
-    expect(invocation.message).toBe(invocationPrimary.message);
-    expect(continuing.message).toBe(continuingPrimary.message);
-    expect(invocation.details).toMatchObject({
-      resources: ["hopper-bridge"],
-      diagnostics: { primary_error: invocationPrimary },
-    });
-    expect(continuing.details).toMatchObject({
-      diagnostics: { primary_error: continuingPrimary },
-    });
-
-    cleanup.resolveCleanup();
-    expect(
-      projectAnalysisError(composed, "invocation").details?.cleanup_history,
-    ).toMatchObject({ primary_error: invocationPrimary });
-    expect(
-      projectAnalysisError(composed).details?.cleanup_history,
-    ).toMatchObject({ primary_error: continuingPrimary });
+    // A busy request is not a startup: it carries no lifetime-specific text.
+    const busy = new HopperTimeoutError(30_000, "trace_feature", 42, "busy");
+    expect(projectAnalysisError(busy, "invocation").remediation).toEqual(
+      projectAnalysisError(busy).remediation,
+    );
   });
 });
 

src/domain/analysisErrorProjection.ts

@@ -13,7 +13,6 @@ import {
   analysisErrorRemediationAction,
   analysisErrorUserMessage,
   assertKnownAnalysisErrorTag,
-  hasAnalysisContinuingCallerGuidance,
 } from "./analysisErrorPresentation.js";
 import {
   AnalysisAccessDeniedError,
@@ -319,7 +318,7 @@ const projectionDependsOnCallerLifetime = (
     )
       if (
         node.limit !== undefined ||
-        hasAnalysisContinuingCallerGuidance(node) ||
+        node.continuingCallerGuidance !== undefined ||
         node.invocationDiagnostics !== undefined ||
         node.workflowUnknownPublication !== undefined
       )

src/domain/analysisView/apiContractView.ts

@@ -185,7 +185,7 @@ export const projectApiContractView = (
     unknowns:
       context.source_coverage.status === "partial"
         ? [
-            "Unresolved or malformed declarations limit this inventory; query path-item-references and diagnostics for exact source pointers.",
+            "This inventory is partial. Inspect limitations for coverage and query path-item-references and diagnostics for any retained source pointers.",
           ]
         : [],
   };

src/domain/apiContract/parseApiContract.test.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { expect, it } from "vitest";
 import { apiContractSchema, type ApiContractArtifact } from "./apiContract.js";
 import { parseApiContractSteps } from "./parseApiContract.js";
+import { AnalysisCancelledError } from "../analysisErrorCore.js";
 
 const artifact: ApiContractArtifact = {
   path: "/contract.json",
@@ -305,9 +306,39 @@ it("handles 3.2 QUERY and case-sensitive additional methods, diagnosing invalid
 
 it("bounds expanded identities and source pointers before building a giant row", () => {
   const result = parse(
-    document({ [`/${"a".repeat(1_100_000)}`]: { get: {} } }),
+    document({
+      "/retained": { get: {} },
+      [`/${"a".repeat(1_100_000)}`]: { get: {} },
+    }),
   );
   expect(result.ok).toBe(false);
-  if (!result.ok)
-    expect(result.error._tag).toBe("AnalysisResourceConstraintError");
+  if (result.ok) throw new Error("Expected a retained-facts refusal");
+  expect(result.error._tag).toBe("AnalysisResourceConstraintError");
+  const partial = apiContractSchema.parse(result.error.partialObservation);
+  expect(partial.operations.map((row) => row.path)).toEqual(["/retained"]);
+  expect(partial.source_coverage.status).toBe("partial");
+});
+
+it("retains an interpreted path when cancellation interrupts traversal", () => {
+  const input = document({
+    "/first": { get: { operationId: "first" } },
+    "/second": { get: { operationId: "second" } },
+  });
+  const steps = parseApiContractSteps(input, artifact);
+  for (let checkpoint = 0; checkpoint < 3; checkpoint++)
+    expect(steps.next().done).toBe(false);
+  const cancellation = new AnalysisCancelledError("inspect_api_contract");
+  const stopped = steps.throw(cancellation);
+  if (!stopped.done || stopped.value.ok)
+    throw new Error("Expected cancellation");
+  expect(stopped.value.error).toBe(cancellation);
+  const partial = apiContractSchema.parse(cancellation.partialObservation);
+  const complete = report(input);
+  expect(partial.operations).toEqual(complete.operations.slice(0, 1));
+  expect(partial.summary.operation_slots).toBe(1);
+  expect(partial.source_coverage).toMatchObject({
+    status: "partial",
+    path_entries_examined: 1,
+  });
+  expect(complete.source_coverage.status).toBe("complete-within-scope");
 });

src/domain/apiContract/parseApiContract.ts

@@ -1,4 +1,5 @@
 import {
+  AnalysisCancelledError,
   AnalysisInputError,
   AnalysisResourceConstraintError,
   AnalysisUnsupportedTargetError,
@@ -316,14 +317,17 @@ function* pathItem(
   return ok(undefined);
 }
 
-const completedInventory = (
+interface ContractReportContext {
+  readonly openapi: string;
+  readonly info: ApiContract["info"];
+  readonly pathsState: ApiContract["source_coverage"]["paths_state"];
+  examined: number;
+}
+
+const contractReport = (
   inventory: ContractInventory,
-  context: {
-    openapi: string;
-    info: ApiContract["info"];
-    pathsState: ApiContract["source_coverage"]["paths_state"];
-    examined: number;
-  },
+  context: ContractReportContext,
+  incomplete = false,
 ): ApiContract => {
   const artifact = inventory.artifact;
   let declared = 0;
@@ -348,7 +352,9 @@ const completedInventory = (
     source_coverage: {
       scope: "inline-path-operations",
       status:
-        inventory.references.length > 0 || inventory.diagnostics.length > 0
+        incomplete ||
+        inventory.references.length > 0 ||
+        inventory.diagnostics.length > 0
           ? "partial"
           : "complete-within-scope",
       paths_state: context.pathsState,
@@ -358,6 +364,11 @@ const completedInventory = (
       duplicate_json_members: "last-value-wins",
     },
     limitations: [
+      ...(incomplete
+        ? [
+            "Traversal stopped before the inventory was complete. Counts describe the retained rows.",
+          ]
+        : []),
       "Operations are document declarations, not evidence of runtime implementation, reachability or authorization.",
       "Only inline operations under paths are inventoried; callbacks, webhooks, components, servers, parameters, schemas, request/response contracts and security are not analyzed.",
       "No reference is resolved, including local fragments. A Path Item reference makes its effective operations unknown; adjacent inline slots are preserved without merging referenced definitions.",
@@ -368,6 +379,32 @@ const completedInventory = (
   };
 };
 
+function* collectPaths(
+  sourcePaths: Record<string, unknown>,
+  inventory: ContractInventory,
+  context: ContractReportContext,
+  modern: boolean,
+): Generator<void, Result<void, AnalysisError>> {
+  for (const path in sourcePaths) {
+    if (!Object.hasOwn(sourcePaths, path) || path.startsWith("x-")) continue;
+    yield;
+    context.examined++;
+    // Reserve expanded pointer/path strings before escaping or building a row.
+    const admitted = inventory.reserve(512 + path.length * 16);
+    if (!admitted.ok) return admitted;
+    const pointer = `/paths/${pointerPart(path)}`;
+    const read = path.startsWith("/")
+      ? yield* pathItem(sourcePaths[path], { inventory, path, pointer, modern })
+      : inventory.diagnostic(
+          "invalid-path-key",
+          pointer,
+          "A Paths entry must start with /; it was not interpreted as an endpoint.",
+        );
+    if (!read.ok) return read;
+  }
+  return ok(undefined);
+}
+
 /** Enumerate declarations only; never resolve references, servers, callbacks or runtime expressions. */
 export function* parseApiContractSteps(
   value: unknown,
@@ -417,36 +454,32 @@ export function* parseApiContractSteps(
     );
     if (!diagnosed.ok) return diagnosed;
   }
-  let examined = 0;
-  const sourcePaths = paths ?? {};
-  for (const path in sourcePaths) {
-    if (!Object.hasOwn(sourcePaths, path) || path.startsWith("x-")) continue;
-    yield;
-    examined++;
-    // Reserve expanded pointer/path strings before escaping or building a row.
-    const admitted = inventory.reserve(512 + path.length * 16);
-    if (!admitted.ok) return admitted;
-    const pointer = `/paths/${pointerPart(path)}`;
-    const read = path.startsWith("/")
-      ? yield* pathItem(sourcePaths[path], {
-          inventory,
-          path,
-          pointer,
-          modern: version[1] === "2",
-        })
-      : inventory.diagnostic(
-          "invalid-path-key",
-          pointer,
-          "A Paths entry must start with /; it was not interpreted as an endpoint.",
-        );
-    if (!read.ok) return read;
+  const context: ContractReportContext = {
+    openapi: root.openapi,
+    info: info.value,
+    pathsState,
+    examined: 0,
+  };
+  const interrupted = (error: AnalysisError) => {
+    const retainedRows =
+      inventory.operations.length +
+      inventory.references.length +
+      inventory.diagnostics.length;
+    if (retainedRows > 0)
+      error.retainPartialObservation(contractReport(inventory, context, true));
+    return err(error);
+  };
+  try {
+    const read = yield* collectPaths(
+      paths ?? {},
+      inventory,
+      context,
+      version[1] === "2",
+    );
+    if (!read.ok) return interrupted(read.error);
+  } catch (cause: unknown) {
+    if (cause instanceof AnalysisCancelledError) return interrupted(cause);
+    throw cause;
   }
-  return ok(
-    completedInventory(inventory, {
-      openapi: root.openapi,
-      info: info.value,
-      pathsState,
-      examined,
-    }),
-  );
+  return ok(contractReport(inventory, context));
 }