@vgai/engine 0.2.0 → 0.3.0

package/src/data/data-asset.ts

@@ -0,0 +1,167 @@
+/**
+ * Data assets — W1 of `docs/DATA-TOOLS-DESIGN.md` (§2.3 consumption API).
+ *
+ * A data asset is designer-tunable game data: a JSON file in the project's
+ * `src/data/`, governed by a Zod schema (`*.schema.ts`, engineer-owned) whose
+ * emitted JSON Schema (`*.schema.json`, see {@link toDataJsonSchema}) gives
+ * VS Code validation via the data file's `"$schema"` first line. Data assets
+ * are immutable at runtime — definitions, not state (§2.1).
+ *
+ * The blessed consumption shape, scaffolded working-at-birth by the project
+ * template (`src/data/` there is the worked example — §6.2):
+ *
+ * ```ts
+ * import raw from './tuning.data.json';
+ * import { TuningSchema } from './tuning.schema';
+ * import { defineData } from '@engine/data/data-asset';
+ *
+ * export const tuning = defineData(TuningSchema, raw, 'src/data/tuning.data.json');
+ * // Vite HMR needs the literal dep path in THIS module (static analysis) —
+ * // this one line is the entire live-tuning wiring (['default'] not .default:
+ * // strict tsconfigs index-signature ModuleNamespace):
+ * import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']));
+ * ```
+ *
+ * Game code reads `tuning.get()` inside its update loop (never cache fields
+ * across frames) or `subscribe()`s; an edit to the `.data.json` — from
+ * VS Code, an agent, or the future editor Data tab (W2) — flows through Vite
+ * HMR into the running game with no remount. React worlds/tools get a
+ * `useData` hook with W3's tool-hooks package (deferred with it: the engine
+ * core stays React-free).
+ */
+
+import { z } from 'zod';
+
+/**
+ * A live handle to one data asset (§2.3). `get`/`subscribe` are the whole
+ * runtime surface; `hotSwap` exists only for the owning module's
+ * `import.meta.hot.accept` callback.
+ */
+export interface DataHandle<T> {
+  /** Current parsed values. Read every frame — HMR swaps them under you. */
+  get(): T;
+  /**
+   * Called with the new value after every successful hot swap (NOT with the
+   * initial value). Returns an unsubscribe function.
+   */
+  subscribe(fn: (value: T) => void): () => void;
+  /**
+   * HMR entry point — call from the owning module's
+   * `import.meta.hot.accept('<file>.data.json', (m) => handle.hotSwap(m?.default))`.
+   * Parses like load, but a FAILING edit keeps the last good value and
+   * `console.error`s instead of throwing: a typo mid-live-tune must not
+   * crash the running game. Fix the file and save again.
+   */
+  hotSwap(next: unknown): void;
+  /**
+   * The project-relative path this handle was defined with (`defineData`'s
+   * own `sourcePath` argument, populated automatically below) — OPTIONAL so
+   * any hand-rolled structural implementer stays valid. `getRef`
+   * (`./data-ref.ts`) reads this to catch a `getRef(wrongHandle, "stem#key")`
+   * mismatch with a teaching error instead of silently resolving against the
+   * wrong asset; without it, `getRef` just skips that one check.
+   */
+  readonly sourcePath?: string;
+}
+
+/**
+ * Define a data asset from its Zod schema, the statically imported JSON, and
+ * its project-relative path (used verbatim in error messages, so pass the
+ * real one). Parse-on-load: an invalid file fails loud at import time, naming
+ * the file, every bad path, and the fix (§2.3, §6.5 "errors teach").
+ *
+ * Schema fields should carry `.min/.max/.default/.describe` — the same
+ * annotations `GameComponent.static schema` uses — so the emitted JSON Schema
+ * documents the file and (W2+) the editor renders real widgets.
+ */
+export function defineData<S extends z.ZodType>(
+  schema: S,
+  initial: unknown,
+  sourcePath: string,
+): DataHandle<z.output<S>> {
+  let current = parseDataJson(schema, initial, sourcePath);
+  const subscribers = new Set<(value: z.output<S>) => void>();
+  return {
+    get: () => current,
+    sourcePath,
+    subscribe(fn) {
+      subscribers.add(fn);
+      return () => subscribers.delete(fn);
+    },
+    hotSwap(next) {
+      let parsed: z.output<S>;
+      try {
+        parsed = parseDataJson(schema, next, sourcePath);
+      } catch (err) {
+        // Keep the last good value alive — see the JSDoc on DataHandle.hotSwap.
+        // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game (mirrors overlay-report.ts's direct console use)
+        console.error(`[data] hot edit rejected, keeping previous values.\n${String(err)}`);
+        return;
+      }
+      current = parsed;
+      for (const fn of subscribers) fn(current);
+    },
+  };
+}
+
+/**
+ * Emit the JSON Schema interchange artifact for a data asset's Zod schema
+ * (§2.1: `*.schema.json` is EMITTED, never hand-written; D4: generated and
+ * committed by default so VS Code works with no dev server running).
+ *
+ * Wraps `z.toJSONSchema` with `io: 'input'` — the one non-obvious knob:
+ * defaulted fields must be OPTIONAL in the file schema (a data file may omit
+ * them), whereas the default output mode would mark every field `required`
+ * and make VS Code reject valid files. The template's root `emit-schemas.ts`
+ * is the blessed caller (`npm run emit-schemas`).
+ *
+ * The emitted root schema also explicitly ALLOWS the `"$schema"` string
+ * property, mirroring the parse-side strip below: without it, a TABLE
+ * asset's emitted schema (`z.record` → `additionalProperties: <rowSchema>`)
+ * makes VS Code flag the data file's own `"$schema"` line as an invalid row.
+ */
+export function toDataJsonSchema(schema: z.ZodType): Record<string, unknown> {
+  const emitted = z.toJSONSchema(schema, { io: 'input' }) as Record<string, unknown>;
+  if (emitted['type'] === 'object') {
+    const properties = (emitted['properties'] ?? {}) as Record<string, unknown>;
+    properties['$schema'] ??= { type: 'string' };
+    emitted['properties'] = properties;
+  }
+  return emitted;
+}
+
+/**
+ * Parse a raw `.data.json` payload: strips the `"$schema"` interchange line,
+ * validates through the Zod schema, throws the teaching error on failure.
+ * `defineData` uses this internally on load and hot swap; it is exported for
+ * emit/doctor-style scripts (the template's `emit-schemas.ts` validates every
+ * data file through it, so file validation and runtime validation can never
+ * disagree).
+ */
+export function parseDataJson<S extends z.ZodType>(
+  schema: S,
+  data: unknown,
+  sourcePath: string,
+): z.output<S> {
+  // Strip the data file's `"$schema"` interchange line before validating —
+  // singleton (z.object, strip-mode) schemas ignored it by luck, but a TABLE
+  // asset (z.record) would try to validate it as a row and fail.
+  const payload =
+    data !== null && typeof data === 'object' && !Array.isArray(data) && '$schema' in data
+      ? Object.fromEntries(Object.entries(data).filter(([key]) => key !== '$schema'))
+      : data;
+  const result = schema.safeParse(payload);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('\n');
+    throw new Error(
+      `Data asset "${sourcePath}" failed its schema:\n${issues}\n` +
+        `Fix the JSON to match the Zod schema (its emitted twin, ` +
+        `"${sourcePath.replace(/\.data\.json$/, '.schema.json')}", documents every field — ` +
+        `re-emit with \`npm run emit-schemas\` if the schema changed). ` +
+        `Worked example: the template's src/data/.`,
+    );
+  }
+  return result.data;
+}

package/src/data/data-check-core.ts

@@ -0,0 +1,242 @@
+/**
+ * Data-asset integrity core — the PURE half of W5 enforcement
+ * (docs/DATA-TOOLS-DESIGN.md §6.6 "dangling `file#key` ref" / §6.7 build-path
+ * validation). No filesystem, no vite, no zod: plain parsed-JSON in, findings
+ * out, so BOTH consumers — `vgai doctor`'s data checks
+ * (`packages/editor/src/doctor/data-checks.ts`) and the build-time plugin
+ * (`./vite-plugin-data.ts`) — share one definition of "what is a ref" and
+ * "what counts as dangling" and can never drift apart.
+ *
+ * What is a ref (§2.2): a cross-asset reference is a plain string
+ * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`
+ * (file `#` key `.` field-path). There is no branded-ref Zod helper shipped
+ * yet (W1 deferred it), so ref DETECTION is by convention, tuned against
+ * false positives: a string is treated as a ref IFF it matches
+ * {@link DATA_REF_PATTERN} AND its `file` prefix names a data asset that
+ * actually exists in the project (`src/data/<file>.data.json`). Strings that
+ * merely contain `#` — hex colors (`"#ff0000"`, no prefix), URLs with
+ * fragments (`/` and `:` never match), musical pitches (`"C#4"` only matches
+ * if a `C.data.json` exists) — never fire. The flip side is deliberate and
+ * honest: a ref whose file prefix names a NONEXISTENT asset is
+ * indistinguishable from an arbitrary string and is NOT flagged ("error if
+ * refs exist yet" — the check only bites once the target file exists).
+ *
+ * `dataRef` (`./data-ref.ts`) now exists, closing that flip side for anyone
+ * who adopts it: a `dataRef(target)` field's EMITTED schema carries
+ * `"x-vgai-ref": target` — a declared intent, independent of whether the
+ * target file currently exists. {@link collectDeclaredRefFields} /
+ * {@link findMissingRefTargets} below walk that (zod-free — plain emitted
+ * JSON Schema in, findings out, same purity contract as the rest of this
+ * module) to catch the §9.4 hole for DECLARED refs: renaming/deleting a
+ * target file used to silently un-check every ref into it; now a declared
+ * ref's target is checked by NAME, not by "does a string happen to look
+ * like one right now." Undeclared conventional-string refs keep the
+ * calibrated behavior above, unchanged.
+ */
+
+/**
+ * `file#key(.field)*` — prefix must look like an asset stem (letters,
+ * digits, `_`, `-`), key path is dot-separated segments of the same alphabet.
+ */
+export const DATA_REF_PATTERN = /^([A-Za-z0-9_-]+)#([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)$/;
+
+/** One ref-shaped string found while walking a data file's parsed JSON. */
+export interface DataRefOccurrence {
+  /** Asset stem of the data file the ref string was found IN (e.g. `"tuning"`). */
+  readonly inAsset: string;
+  /** JSON path of the string inside that file (e.g. `"rows.goblin.drops[2]"`). */
+  readonly atPath: string;
+  /** The full ref string, verbatim (e.g. `"enemies#goblin"`). */
+  readonly ref: string;
+  /** Parsed target asset stem (`"enemies"`). */
+  readonly targetAsset: string;
+  /** Parsed dot-separated key path into the target (`["goblin"]`). */
+  readonly targetKeyPath: readonly string[];
+}
+
+/** One dangling ref: the target FILE exists but the key path does not resolve in it. */
+export interface DanglingRefFinding extends DataRefOccurrence {
+  /** The first key-path segment that failed to resolve, for the teaching message. */
+  readonly missingSegment: string;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Walk one data file's parsed JSON and collect every ref-shaped string whose
+ * file prefix names an asset in `assetNames`. The top-level `"$schema"`
+ * interchange line is skipped (it is wiring, not data — same special-casing
+ * as `parseDataJson`'s strip).
+ */
+export function collectDataRefs(
+  inAsset: string,
+  json: unknown,
+  assetNames: ReadonlySet<string>,
+): DataRefOccurrence[] {
+  const out: DataRefOccurrence[] = [];
+  visitForRefs(json, '', true, (node, path) => {
+    const occurrence = asRefOccurrence(inAsset, node, path, assetNames);
+    if (occurrence) out.push(occurrence);
+  });
+  return out;
+}
+
+/** Depth-first walk over parsed JSON, calling `onString` for every string leaf with its JSON path. */
+function visitForRefs(
+  node: unknown,
+  path: string,
+  topLevel: boolean,
+  onString: (value: string, path: string) => void,
+): void {
+  if (typeof node === 'string') {
+    onString(node, path);
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => {
+      visitForRefs(item, `${path}[${i}]`, false, onString);
+    });
+    return;
+  }
+  if (isPlainObject(node)) {
+    for (const [key, value] of Object.entries(node)) {
+      if (topLevel && key === '$schema') continue;
+      visitForRefs(value, path ? `${path}.${key}` : key, false, onString);
+    }
+  }
+}
+
+/** The string is a ref iff it matches the pattern AND its file prefix names a real asset. */
+function asRefOccurrence(
+  inAsset: string,
+  value: string,
+  path: string,
+  assetNames: ReadonlySet<string>,
+): DataRefOccurrence | null {
+  const m = DATA_REF_PATTERN.exec(value);
+  if (!m || !assetNames.has(m[1] as string)) return null;
+  return {
+    inAsset,
+    atPath: path || '(root)',
+    ref: value,
+    targetAsset: m[1] as string,
+    targetKeyPath: (m[2] as string).split('.'),
+  };
+}
+
+/**
+ * Find every dangling `file#key(.field)*` ref across a project's data assets.
+ *
+ * @param files parsed `.data.json` payloads keyed by asset stem (the
+ *   filename minus `.data.json` — the same name the ref's prefix uses, §2.2).
+ *   Pass only files that parsed as JSON; unparseable files are already an
+ *   error in their own right and can't be resolved against anyway.
+ * @returns one finding per ref whose target FILE is in `files` but whose key
+ *   path does not fully resolve inside it (a table row that doesn't exist, a
+ *   singleton field path that walks off the object).
+ */
+export function findDanglingDataRefs(files: ReadonlyMap<string, unknown>): DanglingRefFinding[] {
+  const assetNames = new Set(files.keys());
+  const findings: DanglingRefFinding[] = [];
+  for (const [name, json] of files) {
+    for (const occurrence of collectDataRefs(name, json, assetNames)) {
+      const missing = firstUnresolvedSegment(files.get(occurrence.targetAsset), occurrence);
+      if (missing !== null) findings.push({ ...occurrence, missingSegment: missing });
+    }
+  }
+  return findings;
+}
+
+/** The first key-path segment that fails to resolve in the target payload, or `null` if the whole path resolves. */
+function firstUnresolvedSegment(target: unknown, ref: DataRefOccurrence): string | null {
+  let node: unknown = target;
+  for (const segment of ref.targetKeyPath) {
+    if (!isPlainObject(node) || !(segment in node)) return segment;
+    node = node[segment];
+  }
+  return null;
+}
+
+/** One `dataRef` field declared in an emitted JSON Schema. */
+export interface DeclaredRefField {
+  /** Dot-separated field path within the schema (e.g. `"drop"`, `"loot.dropTable"`). A table's row-schema fields are reported WITHOUT a row-key segment — the declaration applies to every row alike. */
+  readonly fieldPath: string;
+  /** The asset stem the field's `dataRef(...)` call named. */
+  readonly targetStem: string;
+}
+
+/** One declared ref whose target stem names no asset that currently exists. */
+export interface MissingRefTargetFinding {
+  readonly fieldPath: string;
+  readonly targetStem: string;
+}
+
+/** Loosely-typed view of an emitted JSON Schema node — walked structurally, never through Zod (this module stays zod-free). */
+interface JsonSchemaNode {
+  properties?: Record<string, unknown>;
+  additionalProperties?: unknown;
+  'x-vgai-ref'?: unknown;
+}
+
+function asSchemaNode(value: unknown): JsonSchemaNode | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as JsonSchemaNode)
+    : null;
+}
+
+/**
+ * Walk an emitted data-asset JSON Schema (`toDataJsonSchema`'s output, or the
+ * committed `.schema.json` twin — same shape either way) and collect every
+ * field stamped `"x-vgai-ref": <target>` by `dataRef` (`./data-ref.ts`).
+ * Handles both blessed shapes (spec §2.1): a singleton's `properties`, and a
+ * table's `additionalProperties` row schema — walked with the SAME field
+ * path (a table's declared ref applies uniformly to every row, there is no
+ * per-row schema variation). Nested `properties` inside a ref-declaring
+ * field are not walked further (a ref leaf has no children); nested groups
+ * elsewhere recurse via their own `properties`.
+ */
+export function collectDeclaredRefFields(schema: unknown): DeclaredRefField[] {
+  const out: DeclaredRefField[] = [];
+  walkForDeclaredRefs(schema, '', out);
+  return out;
+}
+
+function walkForDeclaredRefs(raw: unknown, path: string, out: DeclaredRefField[]): void {
+  const node = asSchemaNode(raw);
+  if (!node) return;
+
+  if (typeof node['x-vgai-ref'] === 'string') {
+    out.push({ fieldPath: path || '(root)', targetStem: node['x-vgai-ref'] });
+    return; // a ref leaf — nothing further to walk under it
+  }
+
+  if (isPlainObject(node.properties)) {
+    for (const [key, child] of Object.entries(node.properties)) {
+      if (key === '$schema') continue;
+      walkForDeclaredRefs(child, path ? `${path}.${key}` : key, out);
+    }
+  }
+  // A table's row schema (`z.record(rowSchema)` emits an object-valued
+  // `additionalProperties`) — same field-path grammar, no row-key segment.
+  if (isPlainObject(node.additionalProperties)) {
+    walkForDeclaredRefs(node.additionalProperties, path, out);
+  }
+}
+
+/**
+ * Every declared ref field whose target stem names no asset in
+ * `assetNames` — the §9.4 fix: a `dataRef('items')` field stays flagged if
+ * `items.data.json` is renamed or deleted, independent of whether any
+ * CURRENT value happens to look like an `items#...` string (the gap the
+ * conventional-string calibration above deliberately leaves open).
+ */
+export function findMissingRefTargets(
+  declared: readonly DeclaredRefField[],
+  assetNames: ReadonlySet<string>,
+): MissingRefTargetFinding[] {
+  return declared
+    .filter((d) => !assetNames.has(d.targetStem))
+    .map((d) => ({ fieldPath: d.fieldPath, targetStem: d.targetStem }));
+}

package/src/data/data-ref.ts

@@ -0,0 +1,145 @@
+/**
+ * `file#key` refs — the resolvable half (docs/DATA-TOOLS-DESIGN.md §2.2).
+ *
+ * Cross-asset references (`"enemies#goblin"`, `"tuning#economy.slotGrowth"`)
+ * have been DETECTED and VALIDATED since W5 (`data-check-core.ts`'s
+ * `DATA_REF_PATTERN` + `findDanglingDataRefs`, enforced by both `vgai doctor`
+ * and the build plugin) — but nothing could actually RESOLVE one at runtime,
+ * and nothing declared a field AS a ref in its schema (detection was by
+ * string-shape convention alone). This module closes both halves:
+ *
+ * - {@link dataRef} — a typed Zod schema for a ref FIELD. Stamps the emitted
+ *   JSON Schema with a precise `pattern` (the target stem is baked into the
+ *   regex, so VS Code validates the prefix for free) and a machine-readable
+ *   `"x-vgai-ref": target` marker (a Zod `.meta()` that survives
+ *   `toDataJsonSchema`, including inside a table's `additionalProperties` row
+ *   schema — no emitter changes needed). The editor's Data panel
+ *   (`json-schema-fields.ts`'s `'ref'` kind) reads that marker to render a
+ *   `stem#key` PICKER instead of free text.
+ * - {@link getRef} — lazy, read-time resolution. The caller names the target
+ *   HANDLE explicitly (`getRef(items, goblin.drop)`), so the resolved type is
+ *   the handle's own row type — no stem→handle registry, no load-order
+ *   problem, no cycle hazard (nothing walks a graph; two refs resolved when
+ *   you choose to resolve them isn't a cycle), and it's HMR-correct for free
+ *   (it reads `target.get()` at CALL time, same doctrine as every other data
+ *   read — "read every frame", never cache across frames).
+ *
+ * Deliberately NOT built (see docs/DATA-TOOLS-DESIGN.md §2.2 and the design
+ * note this module's history carries): eager resolution inside `defineData`
+ * (would change `get()`'s shipped output type and entangle HMR — an edit to
+ * `enemies.data.json` would have to re-notify every OTHER asset that
+ * references it), and a global `resolveRef(addressString)` (needs a runtime
+ * stem→handle registry that `src/data/assets.ts` — side-effect-free,
+ * config-load-time, schemas-only by its own module doc — must not become).
+ */
+
+import { z } from 'zod';
+import type { DataHandle } from './data-asset';
+import { DATA_REF_PATTERN } from './data-check-core';
+
+/** An asset-stem-tagged `file#key` string — `` `${Stem}#${string}` ``. */
+export type DataRef<Stem extends string = string> = `${Stem}#${string}`;
+
+/** Prefix/key-path grammar a ref must match, parameterized by target stem (mirrors `DATA_REF_PATTERN` in `data-check-core.ts`, minus the alternation — this one is anchored to ONE target). */
+function refPattern(target: string): RegExp {
+  return new RegExp(`^${target}#[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$`);
+}
+
+/**
+ * A Zod schema for a data-asset FIELD that references another asset by
+ * `"<target>#<key>(.<field>)*"`. Use it in a `.schema.ts`:
+ *
+ * ```ts
+ * export const EnemyRowSchema = z.object({
+ *   name: z.string(),
+ *   drop: dataRef('items'), // -> "items#potion"
+ * });
+ * ```
+ *
+ * The emitted JSON Schema (`toDataJsonSchema`) carries both a precise
+ * `pattern` (VS Code validates the target-stem prefix for free) and
+ * `"x-vgai-ref": target` (the editor's Data panel picker keys off this).
+ * Detection by `data-check-core.ts`'s conventional-string calibration still
+ * applies at the VALUE level (a `dataRef` field's actual string still has to
+ * look like `target#key` to resolve) — this only makes the field's INTENT
+ * declared in the schema, closing the §9.4 "renamed target file silently
+ * un-checks its refs" hole for anything that adopts it (see
+ * `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
+ */
+export function dataRef<Stem extends string>(target: Stem): z.ZodType<DataRef<Stem>> {
+  return z
+    .string()
+    .regex(refPattern(target), {
+      message:
+        `must be a "${target}#<key>" reference (docs/DATA-TOOLS-DESIGN.md §2.2) — ` +
+        `expected the target asset stem "${target}", e.g. "${target}#some-key".`,
+    })
+    .meta({ 'x-vgai-ref': target }) as z.ZodType<DataRef<Stem>>;
+}
+
+/** First failing key-path segment, or `null` if the whole path resolves — same walk `data-check-core.ts`'s `firstUnresolvedSegment` does over parsed JSON, here over a live handle's value. */
+function firstMissingSegment(root: unknown, keyPath: readonly string[]): string | null {
+  let node: unknown = root;
+  for (const segment of keyPath) {
+    if (node === null || typeof node !== 'object' || Array.isArray(node) || !(segment in node)) {
+      return segment;
+    }
+    node = (node as Record<string, unknown>)[segment];
+  }
+  return null;
+}
+
+/**
+ * Resolve a `"target#key(.field)*"` ref against the named target HANDLE,
+ * read live (`target.get()` at call time — HMR-correct, no caching across
+ * frames, same doctrine as any other data read).
+ *
+ * `ref`'s stem prefix should name `target`'s own asset — when `target` was
+ * built with a `sourcePath` (every `defineData` call populates it), a
+ * mismatch throws a teaching error instead of silently walking the wrong
+ * handle's data. Without a `sourcePath` (a hand-rolled `DataHandle`, or an
+ * older one built before this field existed) the mismatch check is skipped —
+ * resolution still proceeds against `target`, since the caller named it
+ * explicitly and that's the actual contract.
+ *
+ * Throws a teaching error naming the ref and the first key-path segment that
+ * doesn't resolve (a deleted row, a typo'd key) — never returns `undefined`
+ * silently, matching `parseDataJson`'s "errors teach" doctrine (§6.5).
+ */
+export function getRef<T>(target: DataHandle<Record<string, T>>, ref: string): T {
+  const m = DATA_REF_PATTERN.exec(ref);
+  if (!m) {
+    throw new Error(
+      `getRef: "${ref}" is not a "file#key" reference (docs/DATA-TOOLS-DESIGN.md §2.2) — ` +
+        'expected a string shaped like "some-file#some-key".',
+    );
+  }
+  const refStem = m[1] as string;
+  const keyPathStr = m[2] as string;
+  const targetStem = target.sourcePath
+    ?.split('\\')
+    .join('/')
+    .split('/')
+    .pop()
+    ?.replace(/\.data\.json$/, '');
+  if (targetStem !== undefined && targetStem !== refStem) {
+    throw new Error(
+      `getRef: ref "${ref}" names target asset "${refStem}", but the handle passed in is ` +
+        `"${targetStem}" (${target.sourcePath}). Pass the handle ` +
+        `"${refStem}#..." actually names — getRef(${refStem}, ...), not getRef(${targetStem}, ...).`,
+    );
+  }
+  const keyPath = keyPathStr.split('.');
+  const root = target.get();
+  const missing = firstMissingSegment(root, keyPath);
+  if (missing !== null) {
+    throw new Error(
+      `getRef: dangling ref "${ref}" — "${missing}" does not exist` +
+        (targetStem ? ` in ${targetStem}.data.json` : '') +
+        '. Fix the key or remove the ref (refs are "file#key" strings — docs/DATA-TOOLS-DESIGN.md §2.2).',
+    );
+  }
+  let node: unknown = root;
+  for (const segment of keyPath) node = (node as Record<string, unknown>)[segment];
+  return node as T;
+}