@vgai/editor 0.2.0

package/src/doctor/data-checks.ts

@@ -0,0 +1,285 @@
+/**
+ * `vgai doctor` — data-asset checks (docs/DATA-TOOLS-DESIGN.md §6.6, the
+ * enforcement half of W5). PURE data-in/data-out, exactly like its sibling
+ * `report.ts`: the fs/schema-executing scraping lives in
+ * `packages/editor/scripts/doctor-data-scan.ts` (spawned under `tsx`, which
+ * is what lets it dynamic-import the project's `.schema.ts` modules), and
+ * hands this module plain {@link ScannedDataProject} data — so the check
+ * RULES are unit-testable without a filesystem or a project.
+ *
+ * The checks, severities fixed by the spec (§6.6):
+ *
+ *   - **data file fails schema** → ERROR (flips the doctor exit code). Also
+ *     covers a `.data.json` that isn't valid JSON at all.
+ *   - **dangling `file#key` ref** → ERROR. Shared definition with the
+ *     build-path plugin via the engine's `findDanglingDataRefs` (a ref only
+ *     "exists" once its file prefix names a real data asset — see
+ *     `data-check-core.ts`'s calibration note).
+ *   - **declared `dataRef(target)` field's target file missing**
+ *     (`'data-ref-missing-file'`) → ERROR — the §9.4 fix. Unlike the
+ *     conventional-string check above, this fires purely from the SCHEMA's
+ *     declared intent (`"x-vgai-ref": target` on the emitted field), so
+ *     renaming/deleting the target file no longer silently un-checks the
+ *     ref — see `collectDeclaredRefFields`/`findMissingRefTargets` in
+ *     `data-check-core.ts`.
+ *   - **`.data.json` without a schema** → WARN. Two shapes: no governing
+ *     `.schema.ts` at all, or a `.schema.ts` whose emitted `.schema.json`
+ *     was never generated (D4 default is generated-and-committed).
+ *   - **zero data assets in a non-trivial project** → INFO nudge (the
+ *     doctrine's "deleting the pattern is a choice" — §6.2).
+ *
+ * Anti-shim doctrine (same as report.ts): a schema that could not be
+ * EXECUTED (import failed, ambiguous exports) is a WARN naming the reason —
+ * never silently counted as validated, never fabricated into an error the
+ * data file didn't earn.
+ *
+ * NOTE the engine import below is RELATIVE, not `@engine/*`: this module is
+ * imported by `scripts/run-doctor.ts`, which runs under plain `tsx` where no
+ * tsconfig-path alias exists (same constraint documented at run-doctor's own
+ * imports).
+ */
+
+import {
+  collectDeclaredRefFields,
+  findDanglingDataRefs,
+  findMissingRefTargets,
+} from '../../../engine/src/data/data-check-core';
+
+export type DataFindingSeverity = 'error' | 'warn' | 'info';
+
+export type DataCheckId =
+  | 'data-schema' // §6.6 check 1: data file fails schema (error)
+  | 'data-dangling-ref' // §6.6 check 2: dangling file#key ref (error)
+  | 'data-missing-schema' // §6.6 check 3: .data.json without schema (warn)
+  | 'data-duplicate-stem' // duplicate asset stem across files (error)
+  | 'data-ref-missing-file' // §9.4 fix: a declared dataRef(target)'s target file doesn't exist (error)
+  | 'data-none'; // §6.6 check 4: zero data assets, non-trivial project (info)
+
+export interface DataDoctorFinding {
+  readonly severity: DataFindingSeverity;
+  readonly check: DataCheckId;
+  /** Project-relative path of the offending file, or `null` for project-level findings. */
+  readonly file: string | null;
+  readonly message: string;
+}
+
+/** Outcome of executing an asset's `.schema.ts` against its `.data.json` — scraped by doctor-data-scan.ts. */
+export type ScannedSchemaValidation =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'invalid'; readonly message: string }
+  /** The schema module could not be executed/identified — reason says why (import error, ambiguous exports). */
+  | { readonly kind: 'unavailable'; readonly reason: string };
+
+export interface ScannedDataAsset {
+  /** Asset stem — filename minus `.data.json` (the name refs address it by, §2.2). */
+  readonly name: string;
+  /** Project-relative path of the `.data.json`. */
+  readonly dataPath: string;
+  /** Parsed JSON payload, or `undefined` when `jsonError` is set. */
+  readonly json?: unknown;
+  /** JSON.parse failure message, or `null` if the file parsed. */
+  readonly jsonError: string | null;
+  /** Project-relative path of the sibling `.schema.ts`, or `null` if none exists. */
+  readonly schemaTsPath: string | null;
+  /** Project-relative path of the sibling EMITTED `.schema.json`, or `null` if none exists. */
+  readonly schemaJsonPath: string | null;
+  /** Validation outcome — `null` iff there is no `.schema.ts` to validate against. */
+  readonly validation: ScannedSchemaValidation | null;
+  /**
+   * The emitted JSON Schema (`toDataJsonSchema` output, or the committed
+   * `.schema.json` twin when the module couldn't be executed) — present
+   * whenever EITHER is available, independent of `validation`'s outcome.
+   * Used only to find declared `dataRef(target)` fields (§9.4 fix); `null`/
+   * absent degrades to "no declared refs found here", never an error.
+   */
+  readonly emittedSchema?: Record<string, unknown>;
+}
+
+export interface ScannedDataProject {
+  readonly assets: readonly ScannedDataAsset[];
+  /** Count of `.ts`/`.tsx` files under the project's `src/` — the non-triviality signal. */
+  readonly sourceFileCount: number;
+}
+
+/**
+ * "Non-trivial project" calibration for the §6.6 info nudge: the template
+ * scaffolds ~17 source files INCLUDING the data trio, so a project that
+ * deleted the pattern still gets nudged, while a three-file experiment does
+ * not. Deliberately a soft signal — it gates an INFO, nothing stronger.
+ */
+export const NON_TRIVIAL_SOURCE_FILE_COUNT = 10;
+
+/**
+ * Every `.data.json`'s asset "name" is its STEM (filename minus the
+ * extension, §2.2) — the same identity `file#key` refs address a file by.
+ * `src/data/` is walked recursively (`scanProjectDataAssets`), so two files
+ * in different subdirectories can share a stem (e.g. `src/data/enemies` and
+ * `src/data/legacy/enemies`) — an unresolvable identity collision that the
+ * downstream stem-keyed `Map` (ref resolution, below) would otherwise
+ * silently paper over with last-wins, while `.find()`-based error attribution
+ * elsewhere would report the FIRST one — two different silent tie-breaks
+ * disagreeing with each other. This must be a hard error naming every
+ * colliding path, not a silent collision.
+ */
+function findDuplicateStems(assets: readonly ScannedDataAsset[]): Map<string, ScannedDataAsset[]> {
+  const byStem = new Map<string, ScannedDataAsset[]>();
+  for (const asset of assets) {
+    const group = byStem.get(asset.name);
+    if (group) group.push(asset);
+    else byStem.set(asset.name, [asset]);
+  }
+  for (const [stem, group] of [...byStem]) {
+    if (group.length < 2) byStem.delete(stem);
+  }
+  return byStem;
+}
+
+/** Assemble the §6.6 findings from a scanned project. Deterministic: per-asset checks in scan order, then refs, then the project-level nudge. */
+export function assembleDataFindings(scanned: ScannedDataProject): DataDoctorFinding[] {
+  const findings: DataDoctorFinding[] = [];
+
+  for (const asset of scanned.assets) {
+    findings.push(...perAssetFindings(asset));
+  }
+
+  const duplicateStems = findDuplicateStems(scanned.assets);
+  for (const [stem, group] of duplicateStems) {
+    const paths = group.map((a) => a.dataPath).join(', ');
+    for (const asset of group) {
+      findings.push({
+        severity: 'error',
+        check: 'data-duplicate-stem',
+        file: asset.dataPath,
+        message:
+          `asset stem "${stem}" is claimed by ${group.length} files (${paths}) — "file#key" refs ` +
+          'address a data asset by its stem alone (§2.2), so this is an unresolvable identity ' +
+          'collision. Rename one; asset stems must be unique across the whole project, not just ' +
+          'per directory.',
+      });
+    }
+  }
+
+  // Dangling refs — resolved across every file that parsed (an unparseable
+  // file is already an error above and cannot be resolved against). A
+  // duplicate-stem asset is excluded here too: it already has its own hard
+  // error above, and resolving refs against "whichever file happened to
+  // scan last" would be an arbitrary, possibly-wrong answer.
+  const parsed = new Map<string, unknown>();
+  for (const asset of scanned.assets) {
+    if (asset.jsonError === null && !duplicateStems.has(asset.name)) {
+      parsed.set(asset.name, asset.json);
+    }
+  }
+  for (const dangling of findDanglingDataRefs(parsed)) {
+    const inAsset = scanned.assets.find((a) => a.name === dangling.inAsset);
+    const target = scanned.assets.find((a) => a.name === dangling.targetAsset);
+    findings.push({
+      severity: 'error',
+      check: 'data-dangling-ref',
+      file: inAsset?.dataPath ?? null,
+      message:
+        `dangling ref at ${dangling.atPath}: "${dangling.ref}" — ` +
+        `"${dangling.missingSegment}" does not exist in ${target?.dataPath ?? `${dangling.targetAsset}.data.json`}. ` +
+        'Fix the key or remove the ref (refs are "file#key" strings — docs/DATA-TOOLS-DESIGN.md §2.2).',
+    });
+  }
+
+  // §9.4 fix: a DECLARED `dataRef(target)` field (schema carries
+  // `"x-vgai-ref": target`) whose target file doesn't exist, checked by
+  // NAME regardless of whether any current value looks like a ref — unlike
+  // the dangling-ref check above, this fires even on an asset with no data
+  // yet, and survives a target file being renamed/deleted (the exact §9.4
+  // hole conventional-string detection couldn't close). A file that exists
+  // (even a duplicate-stem one, already flagged above) is never re-flagged
+  // here — the check is purely "does the name resolve to SOME file."
+  const allAssetNames = new Set(scanned.assets.map((a) => a.name));
+  for (const asset of scanned.assets) {
+    if (!asset.emittedSchema) continue;
+    const declared = collectDeclaredRefFields(asset.emittedSchema);
+    for (const missing of findMissingRefTargets(declared, allAssetNames)) {
+      findings.push({
+        severity: 'error',
+        check: 'data-ref-missing-file',
+        file: asset.dataPath,
+        message:
+          `field "${missing.fieldPath}" is declared as dataRef('${missing.targetStem}'), but no ` +
+          `"src/data/${missing.targetStem}.data.json" exists. Restore/rename the target file, or ` +
+          `update the dataRef('${missing.targetStem}') call in ` +
+          `${asset.schemaTsPath ?? 'the schema'} (docs/DATA-TOOLS-DESIGN.md §9.4).`,
+      });
+    }
+  }
+
+  if (scanned.assets.length === 0 && scanned.sourceFileCount >= NON_TRIVIAL_SOURCE_FILE_COUNT) {
+    findings.push({
+      severity: 'info',
+      check: 'data-none',
+      file: null,
+      message:
+        `no data assets found (src/data/*.data.json) in a project with ${scanned.sourceFileCount} ` +
+        'source files. If a designer should be able to change it, it belongs in a data asset — ' +
+        'a JSON file in src/data/ with a Zod schema (docs/DATA-TOOLS-DESIGN.md §0; the template ' +
+        'ships the worked example). Deleting the pattern is a choice — this is a nudge, not a failure.',
+    });
+  }
+
+  return findings;
+}
+
+/** Checks 1 + 3 for one asset — factored out to keep {@link assembleDataFindings} within the lint complexity budget. */
+function perAssetFindings(asset: ScannedDataAsset): DataDoctorFinding[] {
+  const findings: DataDoctorFinding[] = [];
+
+  if (asset.jsonError !== null) {
+    findings.push({
+      severity: 'error',
+      check: 'data-schema',
+      file: asset.dataPath,
+      message: `not valid JSON: ${asset.jsonError}. Fix the syntax — every consumer of this file (defineData parse-on-load, the editor Data tab, VS Code) is wedged until it parses.`,
+    });
+  } else if (asset.validation?.kind === 'invalid') {
+    // parseDataJson's own teaching error text, verbatim — it already names
+    // the file, every bad path, and the fix (§6.5 "errors teach").
+    findings.push({
+      severity: 'error',
+      check: 'data-schema',
+      file: asset.dataPath,
+      message: asset.validation.message,
+    });
+  } else if (asset.validation?.kind === 'unavailable') {
+    findings.push({
+      severity: 'warn',
+      check: 'data-schema',
+      file: asset.dataPath,
+      message:
+        `could not validate against ${asset.schemaTsPath ?? 'its schema'}: ${asset.validation.reason} ` +
+        '— not counted as a pass (never fabricated). `npm run emit-schemas` in the project is the ' +
+        "same check with the project's own module resolution.",
+    });
+  }
+
+  if (asset.schemaTsPath === null) {
+    findings.push({
+      severity: 'warn',
+      check: 'data-missing-schema',
+      file: asset.dataPath,
+      message:
+        'no governing schema: expected a sibling ' +
+        `${asset.dataPath.replace(/\.data\.json$/, '.schema.ts')} (Zod, engineer-owned). ` +
+        "Every data asset is a trio — copy the template's src/data/ worked example " +
+        '(docs/DATA-TOOLS-DESIGN.md §2.1).',
+    });
+  } else if (asset.schemaJsonPath === null) {
+    findings.push({
+      severity: 'warn',
+      check: 'data-missing-schema',
+      file: asset.dataPath,
+      message:
+        `the emitted ${asset.dataPath.replace(/\.data\.json$/, '.schema.json')} is missing — run ` +
+        '`npm run emit-schemas` and commit it (D4: without it VS Code cannot validate this file ' +
+        'and the editor Data tab cannot render typed widgets).',
+    });
+  }
+
+  return findings;
+}

package/src/doctor/report.ts

@@ -0,0 +1,386 @@
+/**
+ * `vgai doctor <folder>` — per-world verdict assembly (D-A4,
+ * docs/WAVE6-DOCTOR-DESIGN.md Slice A; extended by D-H2,
+ * docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md Slice B). PURE
+ * data-in/data-out: this module never touches a browser, a filesystem, or a
+ * child process — the browser phase (`packages/editor/scripts/run-doctor.ts`,
+ * NOT in the unit gate per the Slice-A NOTs) does all the scraping (spawn the
+ * real dev server, drive the real editor page, read the `__vgaiIngest*`/
+ * `__vgaiModule`/`__vgaiMountFailureReports()`/`__vgaiSiblingMounts()` window
+ * signals D-A3/D-H1 add/expose) and hands its findings to
+ * {@link assembleDoctorReport} as plain data, so the verdict RULES
+ * themselves — the actual "what counts as proof" logic F19 exists to get
+ * right — are unit-testable without ever booting Chromium.
+ *
+ * Doctrine (binding, docs/WAVE6-DOCTOR-DESIGN.md doctrine header): anti-shim
+ * — never fabricate a PASS. Every declared world gets EXACTLY one verdict:
+ *
+ *   - **MOUNTED** — real evidence cleared the bar for this world's route
+ *     (see {@link DoctorIngestEvidence}/{@link DoctorModuleEvidence}/
+ *     {@link DoctorReactIngestEvidence} — the last added wave 10 Slice B,
+ *     docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md D-L3), OR a composite
+ *     sibling was present in the live sibling-mount list (see
+ *     {@link DoctorSiblingEvidence} — a deliberately WEAKER, presence-only
+ *     bar, checked last, never conflated with the ingest-capture bar above).
+ *   - **FAILED** — a `__vgaiMountFailureReports()` entry named this world;
+ *     its message is carried verbatim. Checked FIRST, ahead of any evidence
+ *     map — a throwing mount attempt can leave stale/partial evidence behind
+ *     (defensive; today's runner never populates both for the same world).
+ *   - **UNVERIFIABLE** — neither of the above: no proof, but no named
+ *     failure either. This is the "never silently omitted, never upgraded
+ *     to MOUNTED" floor AC-A6 requires, not an error state of this module.
+ */
+
+import type { DataDoctorFinding } from './data-checks';
+
+/** One declared world from the manifest — enough identity to label a verdict row. */
+export interface DoctorDeclaredWorld {
+  readonly worldId: string;
+  /** `ResolvedWorldEntry.kind` (e.g. `'threejs'`/`'pixijs'`/`'react'`). */
+  readonly kind: string;
+  /** `ResolvedAdapter['identity']` (e.g. `'ingest-three'`/`'module'`/`'default-three'`). */
+  readonly identity: string;
+}
+
+/**
+ * Scraped evidence for an ingest-capture world (`ingest-three`/`ingest-pixi`
+ * — the two identities whose healthy `__vgaiIngest`/`__vgaiIngest2D` payload
+ * carries `reflected`/`drawCount`). `null` fields mean "the runner found no
+ * such signal at all" (e.g. the world never mounted this session) — distinct
+ * from a present-but-failing value (e.g. `reflectedCount: 0`), which still
+ * means SOME payload was observed, just not enough to prove MOUNTED.
+ */
+export interface DoctorIngestEvidence {
+  readonly reflectedCount: number | null;
+  /** Whether `drawCount()` was sampled twice across an interval and strictly climbed. `null` = no `drawCount` function was found to sample. */
+  readonly drawCountClimbed: boolean | null;
+  /** `typeof setPaused === 'function'` on the payload. */
+  readonly playControlLive: boolean;
+  /** True only for a genuinely tier-disabled floor (embed-only: no loop exists to gate) — never a fake no-op standing in for a real capability. */
+  readonly playControlTierDisabled: boolean;
+  readonly achievedTier: string | null;
+  readonly declaredTier: string | null;
+}
+
+/** Scraped evidence for a `{ module }`-route world (`__vgaiModule`) — D-A4: presence + achieved/declared tier is the whole bar (no reflected/drawCount concept for a custom adapter). */
+export interface DoctorModuleEvidence {
+  readonly achievedTier: string;
+  readonly declaredTier: string | null;
+  readonly tierShortfall: boolean;
+}
+
+/** One `__vgaiMountFailureReports()` entry, trimmed to what the verdict needs. */
+export interface DoctorMountFailure {
+  readonly worldId: string;
+  readonly message: string;
+}
+
+/**
+ * Scraped evidence for a react-ingest world's LIVE DOM-authoring surface
+ * (`__vgaiIngestReact.domEvidence()` + `setPausedPresent`, wave 10 Slice B,
+ * docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md D-L1/D-L2). The MOUNTED
+ * bar for this class is {@link clearsReactIngestMountedBar} — ALL four legs,
+ * never partial credit (anti-shim, AC-L2/AC-L3).
+ */
+export interface DoctorReactIngestEvidence {
+  readonly elementCount: number;
+  readonly hierarchyNodeCount: number;
+  readonly reactRootPresent: boolean;
+  readonly setPausedPresent: boolean;
+  readonly achievedTier: string | null;
+}
+
+/**
+ * Scraped evidence for a COMPOSITE SIBLING world (`window.__vgaiSiblingMounts()`,
+ * D-H1, docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md Slice B) — deliberately
+ * a DISTINCT class from {@link DoctorIngestEvidence}/{@link DoctorModuleEvidence}
+ * (D-H2): the bar for this evidence is PRESENCE in the live sibling-mount list,
+ * not a capture/draw proof. Never conflate this with `clearsIngestMountedBar`'s
+ * ingest-capture bar — a sibling's evidence class name says, on its face, that
+ * this is the weaker of the two.
+ */
+export interface DoctorSiblingEvidence {
+  /** `typeof sibling.setPaused === 'function'` — absent for a bare `default-react` sibling (no loop to gate). */
+  readonly setPausedPresent: boolean;
+  /** `!!sibling.authoring` — present whenever the sibling mounted with a store (every production caller). */
+  readonly authoringPresent: boolean;
+  /** `sibling.authoring?.capabilities.persist === true` — false/absent authoring never reads as persistable. */
+  readonly authoringPersist: boolean;
+}
+
+/**
+ * Every raw datum the browser-phase runner scraped off the live page —
+ * data-in for {@link assembleDoctorReport}. Maps/sets are keyed by worldId so
+ * a world with no entry anywhere here means "no signal was ever observed for
+ * it" (the UNVERIFIABLE floor, never fabricated as MOUNTED).
+ */
+export interface DoctorRawSignals {
+  readonly ingestEvidence: ReadonlyMap<string, DoctorIngestEvidence>;
+  readonly moduleEvidence: ReadonlyMap<string, DoctorModuleEvidence>;
+  /** worldIds observed via `__vgaiIngestReact` — presence-only (D-N8: no authoring/capture surface in v1), deliberately NOT treated as proof of a working mount (see UNVERIFIABLE branch below). */
+  readonly reactIngestPresence: ReadonlySet<string>;
+  /**
+   * Per-worldId composite-sibling evidence (D-H2) — a presence-based bar,
+   * checked AFTER ingest/module evidence and react presence, BEFORE the
+   * terminal UNVERIFIABLE branch (see {@link assembleDoctorReport}).
+   * OPTIONAL (unlike the other maps above) so every pre-D-H2 `DoctorRawSignals`
+   * literal (existing tests, any other caller) keeps compiling/running
+   * byte-stable — an absent map reads exactly like an empty one.
+   */
+  readonly siblingEvidence?: ReadonlyMap<string, DoctorSiblingEvidence>;
+  /**
+   * Per-worldId react-ingest DOM evidence (D-L2, wave 10 Slice B,
+   * docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md) — checked in
+   * {@link assembleDoctorReport} after ingest/module evidence, before the
+   * legacy `reactIngestPresence`-only branch and the sibling branch (which
+   * stays LAST). OPTIONAL (unlike `reactIngestPresence`) so every
+   * pre-Slice-B `DoctorRawSignals` literal keeps compiling/running
+   * byte-stable — an absent map reads exactly like an empty one (the same
+   * wave-9B lesson `siblingEvidence` above already applies).
+   */
+  readonly reactIngestEvidence?: ReadonlyMap<string, DoctorReactIngestEvidence>;
+  readonly mountFailures: readonly DoctorMountFailure[];
+}
+
+interface DoctorVerdictBase extends DoctorDeclaredWorld {}
+
+export interface DoctorMountedVerdict extends DoctorVerdictBase {
+  readonly verdict: 'MOUNTED';
+  readonly evidence:
+    | DoctorIngestEvidence
+    | DoctorModuleEvidence
+    | DoctorSiblingEvidence
+    | DoctorReactIngestEvidence;
+}
+
+export interface DoctorFailedVerdict extends DoctorVerdictBase {
+  readonly verdict: 'FAILED';
+  readonly message: string;
+}
+
+export interface DoctorUnverifiableVerdict extends DoctorVerdictBase {
+  readonly verdict: 'UNVERIFIABLE';
+  readonly reason: string;
+}
+
+export type DoctorVerdict = DoctorMountedVerdict | DoctorFailedVerdict | DoctorUnverifiableVerdict;
+
+/** True iff an ingest-capture evidence bundle proves a real, live, editable mount (D-A4's MOUNTED bar for ingest worlds). */
+function clearsIngestMountedBar(ev: DoctorIngestEvidence): boolean {
+  const reflectedOk = ev.reflectedCount !== null && ev.reflectedCount > 0;
+  const drawOk = ev.drawCountClimbed === true;
+  const playOk = ev.playControlLive || ev.playControlTierDisabled;
+  return reflectedOk && drawOk && playOk;
+}
+
+/** Named, honest reason an ingest world's evidence fell short of the MOUNTED bar — never silently downgraded without saying why. */
+function ingestShortfallReason(worldId: string, ev: DoctorIngestEvidence): string {
+  return (
+    `world "${worldId}" produced an ingest-capture signal but did not clear the MOUNTED bar ` +
+    `(reflectedCount=${ev.reflectedCount ?? 'null'}, drawCountClimbed=${ev.drawCountClimbed ?? 'null'}, ` +
+    `playControlLive=${ev.playControlLive}, playControlTierDisabled=${ev.playControlTierDisabled}) — ` +
+    'never upgraded to MOUNTED without all three (docs/WAVE6-DOCTOR-DESIGN.md D-A4).'
+  );
+}
+
+/** True iff react-ingest DOM evidence proves a real, live, editable mount (D-L3's MOUNTED bar for react-ingest worlds) — ALL four legs, never partial credit. */
+function clearsReactIngestMountedBar(ev: DoctorReactIngestEvidence): boolean {
+  return (
+    ev.elementCount > 0 && ev.hierarchyNodeCount > 0 && ev.reactRootPresent && ev.setPausedPresent
+  );
+}
+
+/** Named, honest reason a react-ingest world's DOM evidence fell short of the MOUNTED bar — names exactly which leg(s), never silently downgraded without saying why. */
+function reactIngestShortfallReason(worldId: string, ev: DoctorReactIngestEvidence): string {
+  const failedLegs: string[] = [];
+  if (!(ev.elementCount > 0)) failedLegs.push(`elementCount=${ev.elementCount}`);
+  if (!(ev.hierarchyNodeCount > 0)) failedLegs.push(`hierarchyNodeCount=${ev.hierarchyNodeCount}`);
+  if (!ev.reactRootPresent) failedLegs.push('reactRootPresent=false');
+  if (!ev.setPausedPresent) failedLegs.push('setPausedPresent=false');
+  return (
+    `world "${worldId}" produced react-ingest DOM evidence but did not clear the MOUNTED bar ` +
+    `(${failedLegs.join(', ')}) — never upgraded to MOUNTED without all four legs ` +
+    '(docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md D-L3).'
+  );
+}
+
+/** Verdict for a world with ingest-capture evidence — factored out of {@link assembleDoctorReport} to keep its own cognitive complexity within the repo's lint budget. */
+function verdictForIngestEvidence(
+  world: DoctorDeclaredWorld,
+  ev: DoctorIngestEvidence,
+): DoctorVerdict {
+  const { worldId, kind, identity } = world;
+  return clearsIngestMountedBar(ev)
+    ? { worldId, kind, identity, verdict: 'MOUNTED', evidence: ev }
+    : {
+        worldId,
+        kind,
+        identity,
+        verdict: 'UNVERIFIABLE',
+        reason: ingestShortfallReason(worldId, ev),
+      };
+}
+
+/** Verdict for a world with react-ingest DOM evidence (D-L3) — same factoring reason as {@link verdictForIngestEvidence} above. */
+function verdictForReactIngestEvidence(
+  world: DoctorDeclaredWorld,
+  ev: DoctorReactIngestEvidence,
+): DoctorVerdict {
+  const { worldId, kind, identity } = world;
+  return clearsReactIngestMountedBar(ev)
+    ? { worldId, kind, identity, verdict: 'MOUNTED', evidence: ev }
+    : {
+        worldId,
+        kind,
+        identity,
+        verdict: 'UNVERIFIABLE',
+        reason: reactIngestShortfallReason(worldId, ev),
+      };
+}
+
+/**
+ * Assemble exactly one verdict per declared world (AC-A4). Iterates
+ * `declaredWorlds` (never the signal maps) so a world with zero matching
+ * signals still gets its own UNVERIFIABLE row rather than being dropped.
+ */
+export function assembleDoctorReport(
+  declaredWorlds: readonly DoctorDeclaredWorld[],
+  raw: DoctorRawSignals,
+): readonly DoctorVerdict[] {
+  const failureByWorld = new Map(raw.mountFailures.map((f) => [f.worldId, f.message]));
+
+  return declaredWorlds.map((world): DoctorVerdict => {
+    const { worldId, kind, identity } = world;
+
+    // FAILED is checked first — a named failure is the strongest, most
+    // actionable signal doctor can report, and takes precedence over any
+    // (possibly stale/partial) evidence left behind by the same attempt.
+    const failureMessage = failureByWorld.get(worldId);
+    if (failureMessage !== undefined) {
+      return { worldId, kind, identity, verdict: 'FAILED', message: failureMessage };
+    }
+
+    const ingestEv = raw.ingestEvidence.get(worldId);
+    if (ingestEv) return verdictForIngestEvidence(world, ingestEv);
+
+    const moduleEv = raw.moduleEvidence.get(worldId);
+    if (moduleEv) {
+      return { worldId, kind, identity, verdict: 'MOUNTED', evidence: moduleEv };
+    }
+
+    // D-L3 (wave 10 Slice B, docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md):
+    // checked in the SAME position the presence-only D-N8 branch used to
+    // occupy — after ingest/module evidence, before the sibling branch
+    // (which stays LAST) — so a world whose ingest evidence already fell
+    // short above is NEVER reconsidered here, and below-bar react evidence
+    // is NEVER reconsidered by the sibling branch below (AC-L5, anti-shim
+    // ordering pin: mirrors the ingest-evidence early-return above).
+    const reactEv = raw.reactIngestEvidence?.get(worldId);
+    if (reactEv) return verdictForReactIngestEvidence(world, reactEv);
+
+    if (raw.reactIngestPresence.has(worldId)) {
+      return {
+        worldId,
+        kind,
+        identity,
+        verdict: 'UNVERIFIABLE',
+        reason:
+          `world "${worldId}" mounted an ingest-react session (__vgaiIngestReact present), but no ` +
+          '`domEvidence()` accessor was found on its payload (an older build predating wave 10 ' +
+          'Slice B, docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md D-L1) — presence alone is not ' +
+          'proof of a working mount, so this is reported honestly rather than upgraded to MOUNTED.',
+      };
+    }
+
+    // D-H2 (docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md Slice B): checked
+    // LAST among the "some evidence exists" branches, after ingest/module
+    // evidence and react presence — so a world whose ingest evidence exists
+    // but fell short of `clearsIngestMountedBar` above is NEVER reconsidered
+    // here (AC-H4, anti-shim: sibling evidence never upgrades a below-the-bar
+    // ingest world). The bar itself is presence-in-the-live-list — parallel
+    // to the module-route bar above — and the evidence class name
+    // ({@link DoctorSiblingEvidence}) makes that weaker basis explicit; never
+    // conflate it with `clearsIngestMountedBar`'s capture/draw proof.
+    const siblingEv = raw.siblingEvidence?.get(worldId);
+    if (siblingEv) {
+      return { worldId, kind, identity, verdict: 'MOUNTED', evidence: siblingEv };
+    }
+
+    return {
+      worldId,
+      kind,
+      identity,
+      verdict: 'UNVERIFIABLE',
+      reason:
+        `no headless health signal was observed for world "${worldId}" (kind "${kind}", identity ` +
+        `"${identity}"), and no mount-failure entry named it either — either this identity has no ` +
+        'headless signal wired in doctor this slice, or the mount never ran at all.',
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// The full `--json` envelope (D-A5) — also pure; the CLI/runner only supply
+// the already-computed static summary + verdict list.
+// ---------------------------------------------------------------------------
+
+/** Static (Phase 1) result summary, as far as the JSON report cares (AC-A1). */
+export interface DoctorStaticSummary {
+  readonly ok: boolean;
+  /** Human-readable issues (manifest errors / missing declared files) — empty when `ok`. */
+  readonly issues: readonly string[];
+}
+
+/**
+ * Bump if this JSON shape ever changes incompatibly — consumers should gate
+ * on it. Bumped 1 -> 2 (D-H4, docs/WAVE9-SIBLING-PERSISTENCE-DOCTOR-DESIGN.md
+ * Slice B): a `MOUNTED` verdict's `evidence` union gained the
+ * {@link DoctorSiblingEvidence} variant. Bumped 2 -> 3 (D-L4, wave 10 Slice B,
+ * docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md): the `evidence` union
+ * gained the {@link DoctorReactIngestEvidence} variant (a react-ingest world
+ * can now MOUNT on real DOM evidence, not just be UNVERIFIABLE). Bumped
+ * 3 -> 4 (docs/DATA-TOOLS-DESIGN.md §6.6, W5 enforcement): the envelope
+ * gained the optional top-level `data` section (data-asset findings), and an
+ * ERROR-severity data finding now flips the exit code (see
+ * {@link doctorExitCode}).
+ */
+export const DOCTOR_VERSION = 4 as const;
+
+export interface DoctorJsonReport {
+  readonly doctorVersion: typeof DOCTOR_VERSION;
+  readonly static: DoctorStaticSummary;
+  readonly worlds: readonly DoctorVerdict[];
+  /** Data-asset check findings (docs/DATA-TOOLS-DESIGN.md §6.6) — present iff the caller ran the data scan (run-doctor.ts always does; older/other callers may not). */
+  readonly data?: { readonly findings: readonly DataDoctorFinding[] };
+}
+
+/** Build the stable `--json` envelope (D-A5: "stable shape, top-level `doctorVersion`, static-phase result included"; the version literal itself is {@link DOCTOR_VERSION}, currently `4`). The `data` section is included only when findings were actually scanned — never fabricated as an empty pass. */
+export function buildDoctorJsonReport(
+  staticSummary: DoctorStaticSummary,
+  worldVerdicts: readonly DoctorVerdict[],
+  dataFindings?: readonly DataDoctorFinding[],
+): DoctorJsonReport {
+  const base: DoctorJsonReport = {
+    doctorVersion: DOCTOR_VERSION,
+    static: staticSummary,
+    worlds: worldVerdicts,
+  };
+  return dataFindings ? { ...base, data: { findings: dataFindings } } : base;
+}
+
+/**
+ * D-A5: "Exit 0 iff static passed AND no world is FAILED. Exit 1 otherwise.
+ * UNVERIFIABLE does not flip the exit code." Extended by W5 enforcement
+ * (docs/DATA-TOOLS-DESIGN.md §6.6): an ERROR-severity data-asset finding
+ * (schema failure, dangling ref) also exits 1 — warn/info findings never do,
+ * mirroring how UNVERIFIABLE worlds never do.
+ */
+export function doctorExitCode(
+  staticSummary: DoctorStaticSummary,
+  worldVerdicts: readonly DoctorVerdict[],
+  dataFindings?: readonly DataDoctorFinding[],
+): 0 | 1 {
+  if (!staticSummary.ok) return 1;
+  if (dataFindings?.some((f) => f.severity === 'error')) return 1;
+  return worldVerdicts.some((v) => v.verdict === 'FAILED') ? 1 : 0;
+}