@forgeax/engine-pack 0.1.27 → 0.1.29

package/src/schema-compiled.ts

@@ -75,108 +75,69 @@ export function buildSceneAssetValidator(
     componentsProperties[name] = sub;
   }
 
-  // MountOverride schema (feat-20260608-scene-nesting-ecs-fication M1 / w11;
-  // feat-20260713-mount-override-component-add-and-shared-ref-round M1 / w3;
-  // requirements §S-10 / AC-03): validates each entry in mounts[].overrides[].
-  // `field` is optional — it is a component-granular add-or-patch discriminant
-  // (present -> patch one field with `value`; absent -> add/upsert the whole
-  // `comp` with `value` as its per-field map). `localId` / `comp` / `value`
-  // stay required; `additionalProperties: false` rejects any `op`-tag
-  // discriminant so downstream consumers never branch on it. Field-level type
-  // validation (matching the schema vocab) is enforced at runtime via
-  // setSceneOverride (D-9 / EcsErrorCode 'scene-override-type-mismatch').
-  const mountOverrideSchema = {
+  const componentsSchema = {
     type: 'object',
     additionalProperties: false,
-    required: ['localId', 'comp', 'value'],
-    properties: {
-      localId: { type: 'integer', minimum: 0 },
-      comp: { type: 'string', minLength: 1 },
-      field: { type: 'string', minLength: 1 },
-      value: {},
-    },
+    properties: componentsProperties,
   };
-
-  // SceneInstanceMount schema (feat-20260608-scene-nesting-ecs-fication
-  // M1 / w11; requirements §S-10): validates each mounts[] entry. parent /
-  // components / overrides are optional; cross-mount window collision and
-  // mount.source / mount.memberCount agreement with referenced child
-  // SceneAsset are checked at the build-time scanner (D-1, w14), not here.
-  const mountSchema = {
+  const instanceSchema = {
     type: 'object',
     additionalProperties: false,
-    required: ['localId', 'source', 'memberFirst', 'memberCount'],
+    required: ['source'],
     properties: {
-      localId: { type: 'integer', minimum: 0 },
-      source: { type: 'integer', minimum: 0 },
-      memberFirst: { type: 'integer', minimum: 0 },
-      memberCount: { type: 'integer', minimum: 0 },
-      parent: { type: 'integer', minimum: 0 },
-      components: {
-        type: 'object',
-        additionalProperties: false,
-        properties: componentsProperties,
+      // Authored scenes use a GUID string. Pack output may carry a refs[]
+      // index, which is resolved by the Scene decoder before instantiation.
+      source: {
+        oneOf: [
+          { type: 'string', minLength: 1 },
+          { type: 'integer', minimum: 0 },
+        ],
       },
       overrides: {
         type: 'array',
-        items: mountOverrideSchema,
-      },
-      publicationFence: {
-        type: 'object',
-        additionalProperties: false,
-        required: [
-          'schemaVersion',
-          'sourcePath',
-          'sourceRevision',
-          'publicationGeneration',
-          'outputDigest',
-          'outputSetDigest',
-          'receiptIdentity',
-        ],
-        properties: {
-          schemaVersion: { type: 'string', const: 'scene-publication-fence/1' },
-          sourcePath: { type: 'string', minLength: 1 },
-          sourceRevision: { type: 'string', minLength: 1 },
-          publicationGeneration: { type: 'integer', minimum: 1 },
-          outputDigest: { type: 'string', minLength: 1 },
-          outputSetDigest: { type: 'string', minLength: 1 },
-          receiptIdentity: { type: 'string', minLength: 1 },
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['target', 'components'],
+          properties: {
+            target: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+            components: componentsSchema,
+          },
         },
       },
     },
   };
-
+  const entitySchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['components'],
+    properties: {
+      components: componentsSchema,
+      instance: instanceSchema,
+    },
+  };
   const sceneSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['kind', 'entities'],
     properties: {
       kind: { type: 'string', const: 'scene' },
-      sourceKey: { type: 'string', minLength: 1 },
-      entities: {
+      // Skin assets are explicit scene dependencies so async catalog loading
+      // can finish the joint-wiring path before the Scene is instantiated.
+      // Authored producers use GUID strings; Pack output may use refs[] indices.
+      skinGuids: {
         type: 'array',
         items: {
-          type: 'object',
-          additionalProperties: false,
-          required: ['localId', 'components'],
-          properties: {
-            localId: { type: 'integer', minimum: 0 },
-            bindingKey: { type: 'string', minLength: 1 },
-            components: {
-              type: 'object',
-              additionalProperties: false,
-              properties: componentsProperties,
-            },
-          },
+          oneOf: [
+            { type: 'string', minLength: 1 },
+            { type: 'integer', minimum: 0 },
+          ],
         },
       },
-      // Optional top-level mounts[] (feat-20260608-scene-nesting-ecs-fication
-      // M1 / w11). Missing mounts is semantically equivalent to mounts: []
-      // (plan-strategy §6.3 back-compat); ajv default produces the empty
-      // array on absent input.
-      mounts: {
-        type: 'array',
-        items: mountSchema,
+      entities: {
+        type: 'object',
+        propertyNames: { type: 'string', minLength: 1 },
+        additionalProperties: entitySchema,
       },
     },
   };

package/src/scriptable-pack-node.ts

@@ -266,9 +266,17 @@ class WorkerScriptablePackExecutor
         }
       };
       worker.on('message', onMessage);
-      worker.once('error', rejectLoad);
+      const fail = (error: Error): void => {
+        rejectLoad(error);
+        const active = this.build;
+        this.build = undefined;
+        active?.reject(error);
+        void this.dispose('failure');
+      };
+      worker.once('error', fail);
       worker.once('exit', (code) => {
-        if (code !== 0) rejectLoad(new Error(`ScriptablePack worker exited with code ${code}`));
+        if (this.disposal !== undefined) return;
+        fail(new Error(`ScriptablePack worker exited with code ${code}`));
       });
     });
   }
@@ -393,7 +401,7 @@ class ReusableWorkerScriptablePackExecutor
       void this.dispose('failure');
     });
     this.worker.on('exit', (code) => {
-      if (code === 0 || this.disposal !== undefined) return;
+      if (this.disposal !== undefined) return;
       this.failed = true;
       this.rejectActive(new Error(`ScriptablePack worker exited with code ${code}`));
       void this.dispose('failure');

package/src/scriptable-pack-worker.ts

@@ -215,7 +215,14 @@ function compileModuleClosure(entryPath: string, outputRoot: string, loadId?: nu
     if (errors.length > 0) {
       throw new Error(
         `ScriptablePack TypeScript transpile failed for ${path}: ${errors
-          .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+          .map((diagnostic) => {
+            const position = diagnostic.file?.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+            const location =
+              position === undefined
+                ? path
+                : `${path}:${position.line + 1}:${position.character + 1}`;
+            return `${location}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`;
+          })
           .join('; ')}`,
       );
     }

package/src/__tests__/scanner-mount-cycle.test.ts

@@ -1,232 +0,0 @@
-// scanner-mount-cycle.test - scanner step-6 mount-asset cycle coverage
-// (feat-20260608-scene-nesting-ecs-fication M1 / w13).
-//
-// Coverage (AC-12; plan-strategy D-1):
-//   (a) acyclic mount chain A -> B -> C: scanner returns Ok (no cycle).
-//   (b) two-asset cycle A -> B -> A: scanner returns
-//       Err(PackError{ code: 'pack-cyclic-reference', detail.kind: 'mount-asset',
-//       detail.cycle: GUID[] }) with the GUIDs in cycle order (first === last).
-//   (c) three-asset cycle A -> B -> C -> A: same, longer cycle.
-//   (d) self-mount A -> A: same, single-element cycle.
-//
-// The fixtures are hand-authored scene .pack.json files in a tmpdir;
-// each scene asset uses `payload.mounts[].source` as an integer index into
-// the parent scene's `refs[]` (D-1 + research Finding 11). The mount window
-// (memberFirst / memberCount) is set conservatively so the scanner step-6
-// cycle pass triggers before any mount-window collision check.
-//
-// TDD red signal: until w14 wires `payload.mounts[].source` -> `refsByGuid`
-// edge into scanner step-6, the scanner does NOT see the mount edge in the
-// DFS and the cycle assertions miss. With w14 the cycle producer surfaces
-// `pack-cyclic-reference + detail.kind: 'mount-asset'` (w8 landed the
-// detail.kind tagging at the producer).
-
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { scan } from '../scanner.js';
-
-const GUID_A = 'aa000000-0000-4000-8000-000000000aaa';
-const GUID_B = 'bb000000-0000-4000-8000-000000000bbb';
-const GUID_C = 'cc000000-0000-4000-8000-000000000ccc';
-
-interface MountSpec {
-  readonly localId: number;
-  readonly source: number;
-  readonly memberFirst: number;
-  readonly memberCount: number;
-}
-
-interface SceneAssetSpec {
-  readonly guid: string;
-  /** GUIDs the scene asset's `payload.mounts[].source` integers index into. */
-  readonly refs: readonly string[];
-  readonly mounts: readonly MountSpec[];
-}
-
-function sceneAssetPack(spec: SceneAssetSpec): unknown {
-  return {
-    schemaVersion: '1.0.0',
-    kind: 'internal-text-package',
-    assets: [
-      {
-        guid: spec.guid,
-        kind: 'scene',
-        refs: [...spec.refs],
-        payload: {
-          kind: 'scene',
-          entities: [{ localId: 0, components: {} }],
-          mounts: spec.mounts.map((m) => ({
-            localId: m.localId,
-            source: m.source,
-            memberFirst: m.memberFirst,
-            memberCount: m.memberCount,
-          })),
-        },
-      },
-    ],
-  };
-}
-
-interface CycleErrorShape {
-  readonly code: string;
-  readonly detail: {
-    readonly code?: string;
-    readonly kind?: string;
-    readonly cycle?: readonly string[];
-  };
-}
-
-describe('scanner step-6 mount-asset cycle detection (AC-12; D-1)', () => {
-  let dir: string;
-
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'pack-mount-cycle-'));
-  });
-
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('(a) accepts an acyclic mount chain A -> B -> C', async () => {
-    // A mounts B (source=0 in A.refs) -> B mounts C (source=0 in B.refs) ->
-    // C mounts nothing.
-    await writeFile(
-      join(dir, 'a.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_A,
-          refs: [GUID_B],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    await writeFile(
-      join(dir, 'b.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_B,
-          refs: [GUID_C],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    await writeFile(
-      join(dir, 'c.pack.json'),
-      JSON.stringify(sceneAssetPack({ guid: GUID_C, refs: [], mounts: [] })),
-      'utf-8',
-    );
-
-    const result = await scan([dir]);
-    expect(result.ok).toBe(true);
-  });
-
-  it('(b) rejects a two-asset cycle A -> B -> A with kind: mount-asset', async () => {
-    await writeFile(
-      join(dir, 'a.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_A,
-          refs: [GUID_B],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    await writeFile(
-      join(dir, 'b.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_B,
-          refs: [GUID_A],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-
-    const result = await scan([dir]);
-    expect(result.ok).toBe(false);
-    if (result.ok) return;
-    const err = result.error as unknown as CycleErrorShape;
-    expect(err.code).toBe('pack-cyclic-reference');
-    expect(err.detail.kind).toBe('mount-asset');
-    const cycle = err.detail.cycle ?? [];
-    expect(cycle.length).toBeGreaterThanOrEqual(2);
-    expect(cycle[0]).toBe(cycle[cycle.length - 1]);
-    // Both GUIDs participate in the cycle (case-insensitive compare; scanner
-    // lowercases before storing).
-    const lower = cycle.map((g) => g.toLowerCase());
-    expect(lower).toContain(GUID_A.toLowerCase());
-    expect(lower).toContain(GUID_B.toLowerCase());
-  });
-
-  it('(c) rejects a three-asset cycle A -> B -> C -> A with kind: mount-asset', async () => {
-    await writeFile(
-      join(dir, 'a.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_A,
-          refs: [GUID_B],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    await writeFile(
-      join(dir, 'b.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_B,
-          refs: [GUID_C],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    await writeFile(
-      join(dir, 'c.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_C,
-          refs: [GUID_A],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-
-    const result = await scan([dir]);
-    expect(result.ok).toBe(false);
-    if (result.ok) return;
-    const err = result.error as unknown as CycleErrorShape;
-    expect(err.code).toBe('pack-cyclic-reference');
-    expect(err.detail.kind).toBe('mount-asset');
-    const cycle = err.detail.cycle ?? [];
-    expect(cycle.length).toBeGreaterThanOrEqual(3);
-    expect(cycle[0]).toBe(cycle[cycle.length - 1]);
-  });
-
-  it('(d) rejects a self-mount A -> A', async () => {
-    await writeFile(
-      join(dir, 'a.pack.json'),
-      JSON.stringify(
-        sceneAssetPack({
-          guid: GUID_A,
-          refs: [GUID_A],
-          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
-        }),
-      ),
-      'utf-8',
-    );
-    const result = await scan([dir]);
-    expect(result.ok).toBe(false);
-    if (result.ok) return;
-    const err = result.error as unknown as CycleErrorShape;
-    expect(err.code).toBe('pack-cyclic-reference');
-    expect(err.detail.kind).toBe('mount-asset');
-  });
-});