@vgai/engine 0.5.5 → 0.5.7

package/dist/data/data-ref.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `file#key` refs — the resolvable half.
+ *
+ * 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 (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';
+/** An asset-stem-tagged `file#key` string — `` `${Stem}#${string}` ``. */
+export type DataRef<Stem extends string = string> = `${Stem}#${string}`;
+/**
+ * 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 declare function dataRef<Stem extends string>(target: Stem): z.ZodType<DataRef<Stem>>;
+/**
+ * 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 declare function getRef<T>(target: DataHandle<Record<string, T>>, ref: string): T;
+//# sourceMappingURL=data-ref.d.ts.map

package/dist/data/data-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-ref.d.ts","sourceRoot":"","sources":["../../src/data/data-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,0EAA0E;AAC1E,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC;AAOxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CASnF;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAoC/E"}

package/dist/data/data-ref.js

@@ -0,0 +1,130 @@
+/**
+ * `file#key` refs — the resolvable half.
+ *
+ * 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 (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 { DATA_REF_PATTERN } from './data-check-core';
+/** 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) {
+    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(target) {
+    return z
+        .string()
+        .regex(refPattern(target), {
+        message: `must be a "${target}#<key>" reference — ` +
+            `expected the target asset stem "${target}", e.g. "${target}#some-key".`,
+    })
+        .meta({ 'x-vgai-ref': target });
+}
+/** 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, keyPath) {
+    let node = root;
+    for (const segment of keyPath) {
+        if (node === null || typeof node !== 'object' || Array.isArray(node) || !(segment in node)) {
+            return segment;
+        }
+        node = node[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(target, ref) {
+    const m = DATA_REF_PATTERN.exec(ref);
+    if (!m) {
+        throw new Error(`getRef: "${ref}" is not a "file#key" reference — ` +
+            'expected a string shaped like "some-file#some-key".');
+    }
+    const refStem = m[1];
+    const keyPathStr = m[2];
+    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).');
+    }
+    let node = root;
+    for (const segment of keyPath)
+        node = node[segment];
+    return node;
+}

package/dist/data/vite-plugin-data.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `vgaiDataCheck` — build-path validation for data assets and project tools (the
+ * enforcement half of W5). A Vite plugin for the PROJECT's own `vite.config.ts`
+ * (the template wires it; the editor dev server boots Vite from the ENGINE's
+ * config and never runs this — its surface is covered by `vgai doctor` instead).
+ * Build-only (`apply: 'build'`): in dev, `defineData`'s parse-on-load already
+ * fails loud in the console.
+ *
+ * Three checks, all failing the build loud:
+ *
+ * 1. **Schema integrity** (`buildStart`): every registered asset's
+ *    `.data.json` is read fresh from disk and validated through
+ *    {@link parseDataJson} — the EXACT parse `defineData` runs at load (§9.1:
+ *    an emitted-JSON-Schema validator here could disagree with runtime; the
+ *    Zod schema itself never can). The schemas arrive EXECUTABLE because
+ *    `vite.config.ts` statically imports the project's data-asset registry
+ *    (`src/data/assets.ts` in the template) — Vite's config loader bundles
+ *    config-relative TS imports, which is what makes this the one build-side
+ *    place project Zod schemas can run.
+ * 2. **Ref integrity** (`buildStart`): every `file#key(.field)*` string in
+ *    every `src/data/*.data.json` (registered or not) must resolve — shared
+ *    definition with `vgai doctor` via {@link findDanglingDataRefs}, so the
+ *    two surfaces can never disagree about what "dangling" means. A second,
+ *    narrower ref check runs alongside it for REGISTERED assets only: any
+ *    field declared with `dataRef(target)` (`./data-ref.ts`) whose `target`
+ *    names no asset currently on disk fails loud too (§9.4's "renamed the
+ *    target file" hole, closed for declared refs — see
+ *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
+ * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
+ *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
+ *    standalone builds strip tools entirely; W4 made this true by
+ *    construction — nothing imports tools — and this check PINS it against
+ *    the day some game module imports a tool "just for a helper").
+ *
+ * Unregistered data files (a `.data.json` with no entry in the passed
+ * `assets` list) are a WARNING, not an error: they still get ref-integrity
+ * and runtime parse-on-load, but no build-time schema check — the warning
+ * names the registry file to fix.
+ */
+import type { Plugin } from 'vite';
+import type { z } from 'zod';
+/** One registered data asset: its executable Zod schema + the project-relative path of its `.data.json`. */
+export interface DataCheckAsset {
+    readonly schema: z.ZodType;
+    /** e.g. `'src/data/tuning.data.json'` — read fresh from disk at buildStart. */
+    readonly sourcePath: string;
+}
+export interface VgaiDataCheckOptions {
+    readonly assets: readonly DataCheckAsset[];
+    /** Project root the `sourcePath`s resolve against. Default: `process.cwd()` (vite build's cwd). */
+    readonly root?: string;
+}
+/**
+ * The fs half of checks 1 + 2, extracted from the plugin hook so it is
+ * directly unit-testable against a fixture folder (no rollup context needed).
+ */
+export declare function collectDataCheckProblems(options: VgaiDataCheckOptions): {
+    errors: string[];
+    warnings: string[];
+};
+/** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
+export declare function isToolModuleId(id: string): boolean;
+/**
+ * Build-path validation plugin — see the module doc. Wire it in the project's
+ * `vite.config.ts`, passing the data-asset registry:
+ *
+ * ```ts
+ * import { vgaiDataCheck } from '@vgai/engine/data/vite-plugin-data';
+ * import { dataAssets } from './src/data/assets';
+ * export default defineConfig({
+ *   plugins: [vgaiDataCheck({
+ *     root: __dirname,
+ *     assets: dataAssets.map((a) => ({ schema: a.schema, sourcePath: `src/data/${a.name}.data.json` })),
+ *   })],
+ * });
+ * ```
+ */
+export declare function vgaiDataCheck(options: VgaiDataCheckOptions): Plugin;
+//# sourceMappingURL=vite-plugin-data.d.ts.map

package/dist/data/vite-plugin-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin-data.d.ts","sourceRoot":"","sources":["../../src/data/vite-plugin-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAuGD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CA2DA;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAmCnE"}

package/dist/data/vite-plugin-data.js

@@ -0,0 +1,217 @@
+/**
+ * `vgaiDataCheck` — build-path validation for data assets and project tools (the
+ * enforcement half of W5). A Vite plugin for the PROJECT's own `vite.config.ts`
+ * (the template wires it; the editor dev server boots Vite from the ENGINE's
+ * config and never runs this — its surface is covered by `vgai doctor` instead).
+ * Build-only (`apply: 'build'`): in dev, `defineData`'s parse-on-load already
+ * fails loud in the console.
+ *
+ * Three checks, all failing the build loud:
+ *
+ * 1. **Schema integrity** (`buildStart`): every registered asset's
+ *    `.data.json` is read fresh from disk and validated through
+ *    {@link parseDataJson} — the EXACT parse `defineData` runs at load (§9.1:
+ *    an emitted-JSON-Schema validator here could disagree with runtime; the
+ *    Zod schema itself never can). The schemas arrive EXECUTABLE because
+ *    `vite.config.ts` statically imports the project's data-asset registry
+ *    (`src/data/assets.ts` in the template) — Vite's config loader bundles
+ *    config-relative TS imports, which is what makes this the one build-side
+ *    place project Zod schemas can run.
+ * 2. **Ref integrity** (`buildStart`): every `file#key(.field)*` string in
+ *    every `src/data/*.data.json` (registered or not) must resolve — shared
+ *    definition with `vgai doctor` via {@link findDanglingDataRefs}, so the
+ *    two surfaces can never disagree about what "dangling" means. A second,
+ *    narrower ref check runs alongside it for REGISTERED assets only: any
+ *    field declared with `dataRef(target)` (`./data-ref.ts`) whose `target`
+ *    names no asset currently on disk fails loud too (§9.4's "renamed the
+ *    target file" hole, closed for declared refs — see
+ *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
+ * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
+ *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
+ *    standalone builds strip tools entirely; W4 made this true by
+ *    construction — nothing imports tools — and this check PINS it against
+ *    the day some game module imports a tool "just for a helper").
+ *
+ * Unregistered data files (a `.data.json` with no entry in the passed
+ * `assets` list) are a WARNING, not an error: they still get ref-integrity
+ * and runtime parse-on-load, but no build-time schema check — the warning
+ * names the registry file to fix.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseDataJson, toDataJsonSchema } from './data-asset';
+import { collectDeclaredRefFields, findDanglingDataRefs, findMissingRefTargets, } from './data-check-core';
+/** Recursively collect `*.data.json` under `dir` (absent dir → empty — a project with no data assets builds fine). */
+function findDataFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...findDataFiles(full));
+        else if (entry.endsWith('.data.json'))
+            out.push(full);
+    }
+    return out;
+}
+/** `src/data/tuning.data.json` → `tuning` (normalizing either slash direction). */
+function assetStem(sourcePath) {
+    const rel = sourcePath.split('\\').join('/');
+    return (rel
+        .split('/')
+        .pop()
+        ?.replace(/\.data\.json$/, '') ?? rel);
+}
+function parseAllDataFiles(root, registered, errors, warnings) {
+    const parsedByStem = new Map();
+    const pathsByStem = new Map();
+    for (const abs of findDataFiles(join(root, 'src', 'data'))) {
+        const rel = relative(root, abs).split('\\').join('/');
+        const stem = assetStem(rel);
+        const paths = pathsByStem.get(stem);
+        if (paths)
+            paths.push(rel);
+        else
+            pathsByStem.set(stem, [rel]);
+        try {
+            parsedByStem.set(stem, JSON.parse(readFileSync(abs, 'utf-8')));
+        }
+        catch (err) {
+            errors.push(`"${rel}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (!registered.has(rel)) {
+            warnings.push(`"${rel}" is not registered in the data-asset registry (src/data/assets.ts), so it gets ` +
+                'no build-time schema check (runtime parse-on-load still applies). Register it there — ' +
+                'the template ships the worked example.');
+        }
+    }
+    const ambiguousStems = new Set();
+    for (const [stem, paths] of pathsByStem) {
+        if (paths.length < 2)
+            continue;
+        ambiguousStems.add(stem);
+        errors.push(`asset stem "${stem}" is claimed by ${paths.length} files (${paths.join(', ')}) — ` +
+            '"file#key" refs and the data-asset registry address a file 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.');
+        parsedByStem.delete(stem); // arbitrary otherwise — neither check below may resolve through it
+    }
+    return { parsedByStem, ambiguousStems };
+}
+/**
+ * The fs half of checks 1 + 2, extracted from the plugin hook so it is
+ * directly unit-testable against a fixture folder (no rollup context needed).
+ */
+export function collectDataCheckProblems(options) {
+    const root = options.root ?? process.cwd();
+    const errors = [];
+    const warnings = [];
+    const registered = new Set(options.assets.map((a) => a.sourcePath.split('\\').join('/')));
+    const { parsedByStem, ambiguousStems } = parseAllDataFiles(root, registered, errors, warnings);
+    // Check 1 — registered assets validate through the exact runtime parse.
+    for (const asset of options.assets) {
+        const rel = asset.sourcePath.split('\\').join('/');
+        if (!parsedByStem.has(assetStem(rel))) {
+            // An AMBIGUOUS stem already has its own duplicate-stem error above,
+            // which fully explains why there's no single payload to validate
+            // against — a second "not found on disk" here would just be
+            // confusing noise about a file that plainly IS on disk.
+            if (!ambiguousStems.has(assetStem(rel))) {
+                errors.push(`registered data asset "${rel}" was not found on disk — fix the path in the registry ` +
+                    '(src/data/assets.ts) or restore the file.');
+            }
+            continue;
+        }
+        try {
+            parseDataJson(asset.schema, parsedByStem.get(assetStem(rel)), rel);
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    // Check 2 — no dangling refs anywhere.
+    for (const dangling of findDanglingDataRefs(parsedByStem)) {
+        errors.push(`dangling data ref in "src/data/${dangling.inAsset}.data.json" at ${dangling.atPath}: ` +
+            `"${dangling.ref}" — "${dangling.missingSegment}" does not exist in ` +
+            `src/data/${dangling.targetAsset}.data.json. Fix the key or remove the ref ` +
+            '(refs are "file#key" strings).');
+    }
+    // Check 2b — every declared `dataRef(target)` field (registered assets
+    // only, same set check 1 already validates) must name a target that's
+    // actually on disk — the §9.4 fix: this fires even if NO current value
+    // happens to look like a ref, unlike check 2 above (see
+    // `data-check-core.ts`'s module doc).
+    const assetNames = new Set(parsedByStem.keys());
+    for (const asset of options.assets) {
+        const rel = asset.sourcePath.split('\\').join('/');
+        const declared = collectDeclaredRefFields(toDataJsonSchema(asset.schema));
+        for (const missing of findMissingRefTargets(declared, assetNames)) {
+            errors.push(`"${rel}" declares field "${missing.fieldPath}" 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 the schema.`);
+        }
+    }
+    return { errors, warnings };
+}
+/** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
+export function isToolModuleId(id) {
+    const normalized = id.split('\\').join('/');
+    return /\/src\/tools\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
+}
+/**
+ * Build-path validation plugin — see the module doc. Wire it in the project's
+ * `vite.config.ts`, passing the data-asset registry:
+ *
+ * ```ts
+ * import { vgaiDataCheck } from '@vgai/engine/data/vite-plugin-data';
+ * import { dataAssets } from './src/data/assets';
+ * export default defineConfig({
+ *   plugins: [vgaiDataCheck({
+ *     root: __dirname,
+ *     assets: dataAssets.map((a) => ({ schema: a.schema, sourcePath: `src/data/${a.name}.data.json` })),
+ *   })],
+ * });
+ * ```
+ */
+export function vgaiDataCheck(options) {
+    return {
+        name: 'vgai:data-check',
+        apply: 'build',
+        buildStart() {
+            const { errors, warnings } = collectDataCheckProblems(options);
+            for (const warning of warnings)
+                this.warn(warning);
+            if (errors.length > 0) {
+                // ONE error carrying every problem — fail loud with the full picture,
+                // not a fix-one-rebuild-see-the-next loop.
+                this.error(`data-asset validation failed (${errors.length} problem${errors.length === 1 ? '' : 's'}` +
+                    `):\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+            }
+        },
+        generateBundle(_outputOptions, bundle) {
+            const leaked = new Set();
+            for (const output of Object.values(bundle)) {
+                if (output.type !== 'chunk')
+                    continue;
+                for (const id of Object.keys(output.modules)) {
+                    if (isToolModuleId(id))
+                        leaked.add(id.split('\\').join('/'));
+                }
+            }
+            if (leaked.size > 0) {
+                this.error('project tool code reached the game build — tools are editor-only and must never ship ' +
+                    'to players. Remove every game-code import of these ' +
+                    `modules (tools may import game code, never the reverse):\n${[...leaked]
+                        .map((id) => `  - ${id}`)
+                        .join('\n')}`);
+            }
+        },
+    };
+}