@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/debug/build-debug-inspector-snapshot.ts

@@ -0,0 +1,686 @@
+// @internal — Debug projector.
+//
+// Composes already-shipped DocumentRuntime reads into one typed
+// `DebugInspectorSnapshot`. Consumed in two places:
+//
+//   1. The harness dev drawer — `HarnessDebugPanel` retargets off its
+//      current per-snapshot props onto a single `DebugInspectorSnapshot`
+//      read here.
+//   2. The Phase 2 `services/debug/` Railway service — the hidden
+//      `/session/[id]` page exposes `window.__debug.captureDebugSnapshot(query)`
+//      that calls this function on the mounted editor's runtime; agents
+//      fetch the same JSON through the HTTPS API.
+//
+// Priority ordering (user intent 2026-04-20):
+//   1. Scope debugging — drives `ScopeDebugEntry[]` with the three-way
+//      source discrimination (`marker-backed` | `overlay-only` | `detached`).
+//   2. OOXML audit — surfaced via `health.warnings` + `health.compatibility`
+//      and through the Phase 2 service's scenarios.
+//   3. Rendering — secondary; `layout` is minimal in Phase 0.
+//
+// Perf note: read-only. No DOM measurement. No PM state inspection. Every
+// read is an already-shipped runtime method. See CLAUDE.md perf invariants
+// 1, 4, 7.
+//
+// F-7 / api-channel scope: every runtime read below goes through `safeCall`
+// (see bottom of file) which invokes the method directly on the runtime
+// object. `api`-channel emissions come from the `wrapRefForTelemetry` Proxy
+// applied at `src/ui/WordReviewEditor.tsx` around the `useImperativeHandle`
+// ref — NOT from the runtime itself. So building a DebugInspectorSnapshot
+// never emits `api` events. This is architectural, not a bug: the debug
+// service's own internal reads must not pollute the trace that records
+// agent-origin method calls. See
+// `services/debug/docs/substrate-code-review-2026-04-20.md` §F-7.
+
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { DocumentRuntime } from "../document-runtime.ts";
+import { collectScopeLocations } from "../workflow/scope-resolver.ts";
+import { projectWorkflowDebugEntry } from "../workflow/projector.ts";
+import type {
+  EditorWarning,
+  ScopeQueryResult,
+  WorkflowOverlay,
+  WorkflowScope,
+} from "../../api/public-types.ts";
+import type {
+  DebugInspectorHealthSection,
+  DebugInspectorLayoutSection,
+  DebugInspectorQuery,
+  DebugInspectorReviewSection,
+  DebugInspectorSelectionSection,
+  DebugInspectorSessionSection,
+  DebugInspectorSnapshot,
+  DebugInspectorWorkflowSection,
+  RuntimeTelemetryEvent,
+  ScopeDebugEntry,
+  ScopeDebugSource,
+  ScopeMarkerState,
+} from "./types.ts";
+import type { TelemetryBus } from "./telemetry-bus.ts";
+import { buildFormattingDebugEntry } from "../formatting/projector.ts";
+import { buildLayoutDebugEntry } from "../layout/projector.ts";
+import { createGeometryFacet } from "../geometry/geometry-facet.ts";
+import { buildGeometryDebugEntry } from "../geometry/projector.ts";
+
+/**
+ * Optional `TelemetryBus` accessor — when passed, the projector pulls the
+ * recent event tail and the current channel state into the snapshot. When
+ * absent the snapshot omits `events` / `channels` (Phase 0 callers).
+ */
+export interface BuildDebugInspectorSnapshotOptions {
+  readonly bus?: TelemetryBus;
+}
+
+export function buildDebugInspectorSnapshot(
+  runtime: DocumentRuntime,
+  query?: DebugInspectorQuery,
+  options?: BuildDebugInspectorSnapshotOptions,
+): DebugInspectorSnapshot {
+  const partialFallbacks: string[] = [];
+
+  const session = projectSession(runtime, partialFallbacks);
+
+  const warnings = safeCall(runtime, (r) => r.getWarnings(), [], partialFallbacks, "warnings");
+  const compatibility = safeCall(
+    runtime,
+    (r) => r.getCompatibilityReport(),
+    null,
+    partialFallbacks,
+    "compatibility",
+  );
+  const guard = safeCall(
+    runtime,
+    (r) => r.getInteractionGuardSnapshot(),
+    null,
+    partialFallbacks,
+    "interaction-guard",
+  );
+  const fatalError = extractFatalError(runtime, partialFallbacks);
+  const protection = safeCall(
+    runtime,
+    (r) => r.getProtectionSnapshot(),
+    null,
+    partialFallbacks,
+    "protection",
+  );
+
+  const health: DebugInspectorHealthSection = {
+    compatibility: compatibility ?? emptyCompatibilityReport(),
+    warnings,
+    blockedReasons: guard?.blockedReasons ?? [],
+    fatalError,
+    readOnly:
+      protection?.enforcementActive === true && protection?.editType === "readOnly",
+  };
+
+  const context = safeCall(
+    runtime,
+    (r) => r.getRuntimeContextAnalytics(),
+    null,
+    partialFallbacks,
+    "context-analytics",
+  );
+
+  const selection = projectSelection(runtime, partialFallbacks);
+
+  const overlay = safeCall(
+    runtime,
+    (r) => r.getWorkflowOverlay(),
+    null,
+    partialFallbacks,
+    "workflow-overlay",
+  );
+  const scopeResults = safeCall(
+    runtime,
+    (r) => r.queryScopes(),
+    [] as ScopeQueryResult[],
+    partialFallbacks,
+    "query-scopes",
+  );
+  const markerBacked = safeCall(
+    runtime,
+    (r) => r.getMarkerBackedScopeIds(),
+    new Set<string>(),
+    partialFallbacks,
+    "marker-backed-ids",
+  );
+  const document = safeGetDocument(runtime, partialFallbacks);
+  const markerLocations = document
+    ? collectScopeLocations(document)
+    : new Map<string, { startPos?: number; endPos?: number }>();
+
+  const scopes = projectScopes({
+    runtime,
+    scopeResults,
+    overlay,
+    markerBackedScopeIds: markerBacked,
+    markerLocations,
+    warnings,
+    scopeFilter: query?.scopeFilter,
+    partialFallbacks,
+  });
+
+  const scopeChannelOn = options?.bus?.getChannels?.().scope ?? false;
+  const warningChannelOn = options?.bus?.getChannels?.().warning ?? false;
+  const includeDebugEntry = scopeChannelOn || warningChannelOn;
+  const workflow = projectWorkflow(
+    overlay,
+    scopes,
+    includeDebugEntry ? runtime : null,
+    partialFallbacks,
+  );
+  const review = projectReview(runtime, partialFallbacks);
+  const layout = projectLayout(runtime, partialFallbacks);
+
+  const events: readonly RuntimeTelemetryEvent[] | undefined =
+    query?.includeEvents && options?.bus
+      ? options.bus.tailAll(query.maxEvents ?? 64)
+      : query?.includeEvents
+        ? []
+        : undefined;
+
+  // Phase C1 — formatting projector gate.
+  // Channel-gated + document-dependent. Zero cost when off.
+  const formatting =
+    options?.bus?.isEnabled("formatting") && document
+      ? buildFormattingDebugEntry({ doc: document })
+      : undefined;
+
+  // Refactor/04 Slice 3 — layout projector gate. Channel-gated; reads
+  // existing facet state only (no pagination triggered). Zero cost when
+  // off.
+  const layoutDebug = options?.bus?.isEnabled("layout")
+    ? buildLayoutDebugEntry({
+        facet: runtime.getLayoutFacet(),
+        // Task 5 — surface the compat-input ledger when the document
+        // envelope is available. When the debug path runs against a
+        // runtime with no canonical fallback, `document` is undefined
+        // and the projector omits `compatInputs`.
+        ...(document?.subParts?.settings
+          ? { settings: document.subParts.settings }
+          : {}),
+      })
+    : undefined;
+
+  // Refactor/05 Slice 6 closure gap — `DebugInspectorSnapshot.geometry?`
+  // was declared in v35 but `build-debug-inspector-snapshot.ts` never
+  // called `buildGeometryDebugEntry`, so the declared field was always
+  // `undefined` even with the `layout` channel on. Wiring it here closes
+  // that closure gap. The mounted shell owns the long-lived geometry
+  // facet via its render kernel; this debug-path instance is a
+  // lightweight facet constructed on demand from the runtime's layout
+  // facet (no kernel → Slice-1-proxy path), which is sufficient for the
+  // projector to read frame-independent fields (`pageCount`, viewport
+  // scaffolding, and the sample-block id projection). Channel-gated so
+  // cold path cost stays zero. When `refactor/05` follow-up exposes
+  // `runtime.getGeometryFacet()`, swap to that handle and drop the
+  // on-demand factory call.
+  const geometry = options?.bus?.isEnabled("layout")
+    ? buildGeometryDebugEntry({
+        facet: createGeometryFacet({ layoutFacet: runtime.getLayoutFacet() }),
+        pageCount: runtime.getLayoutFacet().getPageCount(),
+      })
+    : undefined;
+
+  const snapshot: DebugInspectorSnapshot = {
+    schemaVersion: 1,
+    generatedAtUtc: new Date().toISOString(),
+    session,
+    health,
+    context,
+    selection,
+    workflow,
+    scopes,
+    review,
+    layout,
+    ...(events !== undefined ? { events } : {}),
+    ...(query?.includeTextProjection ? { textProjection: null } : {}),
+    ...(partialFallbacks.length > 0 ? { partialFallbacks } : {}),
+    ...(options?.bus ? { channels: options.bus.getChannels() } : {}),
+    ...(formatting !== undefined ? { formatting } : {}),
+    ...(layoutDebug !== undefined ? { layoutDebug } : {}),
+    ...(geometry !== undefined ? { geometry } : {}),
+  };
+
+  return snapshot;
+}
+
+/* -------------------------------------------------------------------------- */
+
+function projectSession(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): DebugInspectorSessionSection {
+  const render = safeCall(
+    runtime,
+    (r) => r.getRenderSnapshot(),
+    null,
+    fallbacks,
+    "render-snapshot-session",
+  ) as {
+    documentId?: string;
+    sessionId?: string;
+    isDirty?: boolean;
+    documentMode?: string;
+    activeStory?: DebugInspectorSessionSection["activeStory"];
+  } | null;
+  const viewState = safeCall(
+    runtime,
+    (r) => r.getViewState(),
+    null,
+    fallbacks,
+    "view-state",
+  ) as {
+    workspaceMode?: "canvas" | "page";
+    viewMode?: string;
+    measurementFidelity?: string | null;
+  } | null;
+  const pageLayout = safeCall(
+    runtime,
+    (r) => r.getPageLayoutSnapshot(),
+    null,
+    fallbacks,
+    "page-layout",
+  ) as { currentPage?: number } | null;
+  const exportBlocked =
+    (safeCall(
+      runtime,
+      (r) => r.getCompatibilityReport(),
+      null,
+      fallbacks,
+      "compat-for-session",
+    ) as { blockExport?: boolean } | null)?.blockExport === true;
+
+  return {
+    documentId: render?.documentId ?? "",
+    sessionId: render?.sessionId ?? "",
+    dirty: render?.isDirty ?? false,
+    exportBlocked: exportBlocked ?? false,
+    activeStory: render?.activeStory ?? { kind: "main" },
+    workspaceMode: viewState?.workspaceMode ?? "canvas",
+    viewMode: viewState?.viewMode ?? "editing",
+    documentMode: render?.documentMode ?? "editing",
+    measurementFidelity: viewState?.measurementFidelity ?? null,
+    currentPage: pageLayout?.currentPage ?? null,
+  };
+}
+
+function projectSelection(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): DebugInspectorSelectionSection {
+  const render = safeCall(runtime, (r) => r.getRenderSnapshot(), null, fallbacks, "render-snapshot");
+  const anchor =
+    (render as { selection?: { activeRange?: unknown } } | null)?.selection?.activeRange ??
+    null;
+  const location = anchor
+    ? safeCall(
+        runtime,
+        (r) => r.getLocationForAnchor(anchor as never),
+        null,
+        fallbacks,
+        "location-for-anchor",
+      )
+    : safeCall(
+        runtime,
+        (r) => r.getCurrentLocation(),
+        null,
+        fallbacks,
+        "current-location",
+      );
+  return { anchor: anchor as never, location };
+}
+
+interface ProjectScopesInput {
+  runtime: DocumentRuntime;
+  scopeResults: ScopeQueryResult[];
+  overlay: WorkflowOverlay | null;
+  markerBackedScopeIds: ReadonlySet<string>;
+  markerLocations: Map<string, { startPos?: number; endPos?: number }>;
+  warnings: readonly EditorWarning[];
+  scopeFilter: DebugInspectorQuery["scopeFilter"];
+  partialFallbacks: string[];
+}
+
+function projectScopes(input: ProjectScopesInput): ScopeDebugEntry[] {
+  const {
+    runtime,
+    scopeResults,
+    overlay,
+    markerBackedScopeIds,
+    markerLocations,
+    warnings,
+    scopeFilter,
+    partialFallbacks,
+  } = input;
+
+  const overlayById = new Map<string, WorkflowScope>();
+  for (const scope of overlay?.scopes ?? []) {
+    overlayById.set(scope.scopeId, scope);
+  }
+  const warningByScope = new Map<string, EditorWarning>();
+  for (const warning of warnings) {
+    const scopeId = (warning as { scopeId?: string }).scopeId;
+    if (scopeId && !warningByScope.has(scopeId)) {
+      warningByScope.set(scopeId, warning);
+    }
+  }
+
+  const entries: ScopeDebugEntry[] = [];
+  const seen = new Set<string>();
+
+  const allIds = new Set<string>([
+    ...scopeResults.map((r) => r.scope.scopeId),
+    ...(overlay?.scopes.map((s) => s.scopeId) ?? []),
+  ]);
+
+  for (const scopeId of allIds) {
+    if (seen.has(scopeId)) continue;
+    seen.add(scopeId);
+
+    const queryResult = scopeResults.find((r) => r.scope.scopeId === scopeId) ?? null;
+    const overlayScope = overlayById.get(scopeId) ?? null;
+    const marker = markerLocations.get(scopeId);
+    const markerState: ScopeMarkerState = deriveMarkerState(marker);
+    const liveScope = safeCall(
+      runtime,
+      (r) => r.getScope(scopeId),
+      null,
+      partialFallbacks,
+      `get-scope:${scopeId}`,
+    );
+
+    const liveAnchor =
+      liveScope?.anchor ??
+      overlayScope?.anchor ??
+      ({ kind: "detached", lastKnownRange: { from: 0, to: 0 }, reason: "deleted" } as const);
+    const isLiveDetached =
+      liveAnchor !== null &&
+      typeof liveAnchor === "object" &&
+      (liveAnchor as { kind?: string }).kind === "detached";
+
+    let source: ScopeDebugSource;
+    if (isLiveDetached) {
+      source = "detached";
+    } else if (markerBackedScopeIds.has(scopeId) && markerState === "complete") {
+      source = "marker-backed";
+    } else if (markerBackedScopeIds.has(scopeId)) {
+      source = "detached";
+    } else {
+      source = "overlay-only";
+    }
+
+    const detachedReason = isLiveDetached
+      ? ((liveAnchor as { reason?: ScopeDebugEntry["detachedReason"] }).reason ?? "deleted")
+      : source === "detached"
+        ? "invalidatedByStructureChange"
+        : undefined;
+
+    const trusted = source === "marker-backed" || source === "overlay-only";
+
+    const location = safeCall(
+      runtime,
+      (r) => r.getLocationForAnchor(liveAnchor as never, overlayScope?.storyTarget),
+      null,
+      partialFallbacks,
+      `location-for-scope:${scopeId}`,
+    );
+
+    const warning = warningByScope.get(scopeId) ?? null;
+
+    const entry: ScopeDebugEntry = {
+      scopeId,
+      label: overlayScope?.label ?? queryResult?.scope.label,
+      mode: (liveScope?.mode ?? overlayScope?.mode ?? "comment") as ScopeDebugEntry["mode"],
+      visibility: (overlayScope?.visibility ?? "visible") as ScopeDebugEntry["visibility"],
+      storyTarget: overlayScope?.storyTarget ?? { kind: "main" },
+      source,
+      liveAnchor: liveAnchor as ScopeDebugEntry["liveAnchor"],
+      storedOverlayAnchor: overlayScope?.anchor ?? null,
+      trusted,
+      markerState,
+      ...(detachedReason ? { detachedReason } : {}),
+      ...(warning ? { warningId: warning.warningId } : {}),
+      ...(isLiveDetached
+        ? {
+            lastKnownRange: (liveAnchor as { lastKnownRange?: { from: number; to: number } })
+              .lastKnownRange,
+          }
+        : {}),
+      location,
+      ...(overlayScope?.metadata && overlayScope.metadata.length > 0
+        ? {
+            // F-15: iterate every metadata entry; previously we dropped entries
+            // past index 0, which broke scopes with multiple metadata refs.
+            metadataLookups: overlayScope.metadata.map((m) => ({
+              ...(m?.key ? { metadataId: m.key } : {}),
+              ...(m?.storageRef ? { storageRef: String(m.storageRef) } : {}),
+              ...(m?.metadataVersion !== undefined
+                ? { metadataVersion: m.metadataVersion }
+                : {}),
+            })),
+          }
+        : {}),
+    };
+
+    if (matchesScopeFilter(entry, scopeFilter)) {
+      entries.push(entry);
+    }
+  }
+
+  // F-8: sort by doc-order (first-marker start position) when the scope is
+  // marker-backed in the document. Overlay-only / detached scopes lack a
+  // live position; push them to the end and keep them deterministically
+  // ordered by scopeId. This matches the plan's "top-to-bottom traversal"
+  // assumption in doc-debug-stack.md §diagnostic isolation.
+  const positionOf = (scopeId: string): number | undefined =>
+    markerLocations.get(scopeId)?.startPos;
+  entries.sort((a, b) => {
+    const aPos = positionOf(a.scopeId);
+    const bPos = positionOf(b.scopeId);
+    if (aPos !== undefined && bPos !== undefined) return aPos - bPos;
+    if (aPos !== undefined) return -1;
+    if (bPos !== undefined) return 1;
+    return a.scopeId.localeCompare(b.scopeId);
+  });
+  return entries;
+}
+
+function projectWorkflow(
+  overlay: WorkflowOverlay | null,
+  scopes: readonly ScopeDebugEntry[],
+  runtimeForDebugEntry: DocumentRuntime | null,
+  fallbacks: string[],
+): DebugInspectorWorkflowSection {
+  let markerBackedCount = 0;
+  let overlayOnlyCount = 0;
+  let detachedCount = 0;
+  for (const s of scopes) {
+    if (s.source === "marker-backed") markerBackedCount += 1;
+    else if (s.source === "overlay-only") overlayOnlyCount += 1;
+    else detachedCount += 1;
+  }
+
+  const base: DebugInspectorWorkflowSection = {
+    overlay,
+    activeWorkItemId: overlay?.activeWorkItemId ?? null,
+    metadataPersistenceMode: overlay?.metadataPersistence ?? null,
+    candidateCount: overlay?.candidates?.length ?? 0,
+    scopeCount: scopes.length,
+    markerBackedCount,
+    overlayOnlyCount,
+    detachedCount,
+  };
+
+  if (!runtimeForDebugEntry) return base;
+
+  const metadataSnapshot = safeCall(
+    runtimeForDebugEntry,
+    (r) => r.getWorkflowMetadataSnapshot(),
+    null,
+    fallbacks,
+    "workflow-metadata-snapshot",
+  );
+  const markupSnapshot = safeCall(
+    runtimeForDebugEntry,
+    (r) => r.getWorkflowMarkupSnapshot(),
+    null,
+    fallbacks,
+    "workflow-markup-snapshot",
+  );
+  const guard = safeCall(
+    runtimeForDebugEntry,
+    (r) => r.getInteractionGuardSnapshot(),
+    null,
+    fallbacks,
+    "interaction-guard-snapshot",
+  );
+
+  const debugEntry = projectWorkflowDebugEntry({
+    overlay,
+    metadataDefinitions: metadataSnapshot?.definitions ?? [],
+    metadataEntries: metadataSnapshot?.entries ?? [],
+    protectedRangeCount: markupSnapshot?.protectedRanges.length ?? 0,
+    scopeCounts: {
+      markerBacked: markerBackedCount,
+      overlayOnly: overlayOnlyCount,
+      detached: detachedCount,
+    },
+    guard,
+  });
+
+  return { ...base, debugEntry };
+}
+
+function projectReview(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): DebugInspectorReviewSection {
+  const render = safeCall(runtime, (r) => r.getRenderSnapshot(), null, fallbacks, "render-for-review");
+  const comments =
+    (render as { comments?: { openCommentIds?: string[]; detachedCommentIds?: string[] } } | null)
+      ?.comments ?? null;
+  const tracked =
+    (render as {
+      trackedChanges?: { pendingChangeIds?: string[]; detachedChangeIds?: string[] };
+    } | null)?.trackedChanges ?? null;
+  return {
+    unresolvedCommentCount: comments?.openCommentIds?.length ?? 0,
+    pendingRevisionCount: tracked?.pendingChangeIds?.length ?? 0,
+    detachedCommentCount: comments?.detachedCommentIds?.length ?? 0,
+    detachedRevisionCount: tracked?.detachedChangeIds?.length ?? 0,
+  };
+}
+
+function projectLayout(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): DebugInspectorLayoutSection {
+  const pageLayout = safeCall(
+    runtime,
+    (r) => r.getPageLayoutSnapshot(),
+    null,
+    fallbacks,
+    "page-layout-summary",
+  );
+  const sections = safeCall(runtime, (r) => r.getSections(), [], fallbacks, "sections");
+  const stories = safeCall(
+    runtime,
+    (r) => r.getDocumentTextStream(),
+    [],
+    fallbacks,
+    "document-text-stream",
+  );
+  return {
+    pageCount: (pageLayout as { pages?: unknown[] } | null)?.pages?.length ?? null,
+    sectionCount: sections.length,
+    storyCount: stories.length,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+
+function deriveMarkerState(
+  marker: { startPos?: number; endPos?: number } | undefined,
+): ScopeMarkerState {
+  if (!marker) return "missing";
+  const hasStart = marker.startPos !== undefined;
+  const hasEnd = marker.endPos !== undefined;
+  if (hasStart && hasEnd) return "complete";
+  if (hasStart) return "start-only";
+  if (hasEnd) return "end-only";
+  return "missing";
+}
+
+function matchesScopeFilter(
+  entry: ScopeDebugEntry,
+  filter: DebugInspectorQuery["scopeFilter"],
+): boolean {
+  if (!filter) return true;
+  if (filter.scopeIds && !filter.scopeIds.includes(entry.scopeId)) return false;
+  if (filter.modes && !filter.modes.includes(entry.mode)) return false;
+  if (filter.source) {
+    const allowed = Array.isArray(filter.source) ? filter.source : [filter.source];
+    if (!allowed.includes(entry.source)) return false;
+  }
+  if (filter.onlyDetached && entry.source !== "detached") return false;
+  return true;
+}
+
+function safeCall<T>(
+  runtime: DocumentRuntime,
+  fn: (r: DocumentRuntime) => T,
+  fallback: T,
+  fallbacks: string[],
+  tag: string,
+): T {
+  try {
+    return fn(runtime);
+  } catch (err) {
+    fallbacks.push(`${tag}:${(err as Error).message ?? "error"}`);
+    return fallback;
+  }
+}
+
+function safeGetDocument(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): CanonicalDocumentEnvelope | null {
+  return safeCall(
+    runtime,
+    (r) => r.getCanonicalDocument(),
+    null,
+    fallbacks,
+    "canonical-document",
+  );
+}
+
+function extractFatalError(
+  runtime: DocumentRuntime,
+  fallbacks: string[],
+): { code: string; message: string } | null {
+  const state = safeCall(
+    runtime,
+    (r) => r.getViewState() as { fatalError?: { code: string; message: string } | null },
+    null,
+    fallbacks,
+    "fatal-error",
+  );
+  return state?.fatalError ?? null;
+}
+
+// F-14: the previous implementation returned an ad-hoc shape silenced with
+// `as never`. The real CompatibilityReport interface (see
+// `src/api/public-types.ts`) requires reportVersion, generatedAt,
+// blockExport, featureEntries, warnings, errors — all declared here so a
+// downstream destructure doesn't throw on missing fields.
+function emptyCompatibilityReport(): DebugInspectorHealthSection["compatibility"] {
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt: new Date().toISOString(),
+    blockExport: false,
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+  };
+}