@forgeax/engine-pack 0.1.28 → 0.1.29

package/src/__tests__/scriptable-pack-diagnostic.integration.test.ts

@@ -0,0 +1,45 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expect, it } from 'vitest';
+import { loadScriptablePack } from '../scriptable-pack-node.js';
+
+it('keeps the source line and column for a malformed author module', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'pack-source-diagnostic-'));
+  const source = join(root, 'broken.pack.ts');
+  try {
+    await writeFile(source, 'export default {\n  build: () => { const = 1; }\n};\n');
+    const loaded = await loadScriptablePack(source);
+    expect(loaded.ok).toBe(false);
+    if (loaded.ok) return;
+    expect(JSON.stringify(loaded.error)).toContain(`${source}:2:`);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+it.each([
+  0, 17,
+])('propagates worker exit %i during a build instead of waiting for timeout', async (code) => {
+  const root = await mkdtemp(join(tmpdir(), 'pack-worker-exit-'));
+  const source = join(root, 'exit.pack.ts');
+  try {
+    await writeFile(
+      source,
+      `export default { schemaVersion: '2.0.0', packageId: new Uint8Array([121,171,30,178,252,222,65,195,145,119,233,61,213,193,142,245]), build() { process.exit(${code}); } };`,
+    );
+    const loaded = await loadScriptablePack(source, { buildTimeoutMs: 1000 });
+    expect(loaded.ok).toBe(true);
+    if (!loaded.ok) return;
+    await expect(
+      loaded.value.build({
+        packageId: loaded.value.packageId,
+        readByGuid: async () => {
+          throw new Error('unexpected read');
+        },
+      }),
+    ).rejects.toThrow(`worker exited with code ${code}`);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/inventory/binding.ts

@@ -15,11 +15,11 @@ export function projectAssetRefs(inventory: AuthorInventory): readonly AssetRef[
 /** Derive instance-relative scene refs from the same validated author rows. */
 export function projectSceneEntityRefs(inventory: AuthorInventory): readonly SceneEntityRef[] {
   return inventory.declarations.flatMap((row) =>
-    row.sceneBindings === undefined
+    row.sceneEntityKeys === undefined
       ? []
-      : row.sceneBindings.map((bindingKey) => ({
+      : row.sceneEntityKeys.map((address) => ({
           sceneSourceKey: row.sourceKey,
-          bindingKey,
+          address,
         })),
   );
 }

package/src/inventory/declaration.ts

@@ -6,7 +6,7 @@ export interface AuthorInventoryRow {
   readonly kind: string;
   readonly payload: Readonly<Record<string, unknown>>;
   readonly refs: readonly string[];
-  readonly sceneBindings?: readonly string[];
+  readonly sceneEntityKeys?: readonly string[];
 }
 
 export interface AuthorInventory {
@@ -102,54 +102,16 @@ export function validateAuthorInventory(value: unknown): Result<AuthorInventory,
         { guid, sourceKey },
       );
     }
-    if (row.kind === 'scene') {
-      const payload = row.payload;
-      const payloadRecord =
-        typeof payload === 'object' && payload !== null
-          ? (payload as Record<string, unknown>)
-          : undefined;
-      const entities =
-        payloadRecord !== undefined && Array.isArray(payloadRecord.entities)
-          ? payloadRecord.entities
-          : [];
-      const bindings = new Set<string>();
-      for (const entity of entities) {
-        const bindingKey =
-          typeof entity === 'object' && entity !== null && typeof entity.bindingKey === 'string'
-            ? entity.bindingKey
-            : undefined;
-        if (bindingKey !== undefined && bindingKey.length === 0) {
-          return failure(
-            'inventory-scene-binding-missing',
-            'each declared scene bindingKey is non-empty',
-            'remove the empty bindingKey or declare a stable key in the scene producer',
-            { sourceKey },
-          );
-        }
-        if (bindingKey === undefined) continue;
-        if (bindings.has(bindingKey)) {
-          return failure(
-            'inventory-scene-binding-duplicate',
-            'bindingKey values are unique within one scene',
-            'rename the duplicate bindingKey in the scene producer',
-            { sourceKey },
-          );
-        }
-        bindings.add(bindingKey);
-      }
-    }
     guids.add(normalizedGuid);
     sourceKeys.add(sourceKey);
-    const sceneBindings =
-      row.kind === 'scene' && typeof row.payload === 'object' && row.payload !== null
-        ? (row.payload as { readonly entities?: readonly unknown[] }).entities?.flatMap(
-            (entity) => {
-              if (typeof entity !== 'object' || entity === null) return [];
-              const key = (entity as { readonly bindingKey?: unknown }).bindingKey;
-              return typeof key === 'string' && key.length > 0 ? [key] : [];
-            },
-          )
-        : undefined;
+    const sceneEntityKeys = (() => {
+      if (row.kind !== 'scene' || typeof row.payload !== 'object' || row.payload === null)
+        return undefined;
+      const entities = (row.payload as { readonly entities?: unknown }).entities;
+      if (entities === null || typeof entities !== 'object' || Array.isArray(entities))
+        return undefined;
+      return Object.keys(entities);
+    })();
     declarations.push({
       guid,
       sourceKey,
@@ -161,7 +123,7 @@ export function validateAuthorInventory(value: unknown): Result<AuthorInventory,
       refs: Array.isArray(row.refs)
         ? row.refs.filter((ref): ref is string => typeof ref === 'string')
         : [],
-      ...(sceneBindings === undefined ? {} : { sceneBindings }),
+      ...(sceneEntityKeys === undefined ? {} : { sceneEntityKeys }),
     });
   }
   return ok({ declarations });

package/src/inventory/sync.ts

@@ -5,7 +5,8 @@ export type InventoryDigest = string;
 export function inventoryDigest(inventory: AuthorInventory): InventoryDigest {
   return inventory.declarations
     .map(
-      (row) => `${row.guid}\0${row.sourceKey}\0${row.kind}\0${row.sceneBindings?.join('\0') ?? ''}`,
+      (row) =>
+        `${row.guid}\0${row.sourceKey}\0${row.kind}\0${row.sceneEntityKeys?.join('\0') ?? ''}`,
     )
     .sort()
     .join('\n');
@@ -16,7 +17,7 @@ export function syncAuthorInventory(inventory: AuthorInventory): AuthorInventory
     declarations: inventory.declarations.map((row) => ({
       ...row,
       refs: [...row.refs],
-      ...(row.sceneBindings === undefined ? {} : { sceneBindings: [...row.sceneBindings] }),
+      ...(row.sceneEntityKeys === undefined ? {} : { sceneEntityKeys: [...row.sceneEntityKeys] }),
     })),
   };
 }

package/src/native-cooker-registry.ts

@@ -20,6 +20,7 @@ export interface NativeCookDraft<P = unknown> {
   readonly refs: readonly string[];
   readonly artifacts: Readonly<Record<string, NativeCookArtifact>>;
   readonly inputFingerprint: string;
+  readonly sourceDependencies?: readonly string[];
 }
 
 export interface NativeCooker<P = unknown, I = unknown> {

package/src/scanner.ts

@@ -254,27 +254,35 @@ function makePackError(
 }
 
 /**
- * For scene assets with `payload.mounts[]`, return the lowercased GUID
- * each `mount.source` integer resolves to via `asset.refs[]`. Returns an
- * empty iterable for non-scene assets, scene assets without mounts, or
- * mounts with malformed `source` (out-of-range integer / non-integer) —
- * those are caught by ajv schema validation upstream. The yielded GUIDs
- * feed scanner step-6's mount-asset cycle DFS (D-1, R10).
+ * For keyed scene assets, return the lowercased GUID each nested instance
+ * source resolves to via `asset.refs[]` (or directly carries). The yielded GUIDs feed
+ * scanner step-6's scene dependency cycle DFS.
  */
-function* extractMountSourceGuids(asset: {
+function* extractInstanceSourceGuids(asset: {
   kind?: unknown;
   payload?: unknown;
   refs: readonly string[];
 }): Generator<string> {
   if (asset.kind !== 'scene') return;
-  const payload = asset.payload as { mounts?: unknown } | undefined;
-  if (!payload || !Array.isArray(payload.mounts)) return;
-  for (const rawMount of payload.mounts) {
-    const mount = rawMount as { source?: unknown };
-    const idx = mount.source;
-    if (typeof idx !== 'number' || !Number.isInteger(idx)) continue;
-    if (idx < 0 || idx >= asset.refs.length) continue;
-    const resolved = asset.refs[idx];
+  const payload = asset.payload as { entities?: unknown } | undefined;
+  if (
+    !payload ||
+    payload.entities === null ||
+    typeof payload.entities !== 'object' ||
+    Array.isArray(payload.entities)
+  )
+    return;
+  for (const rawEntity of Object.values(payload.entities as Record<string, unknown>)) {
+    if (rawEntity === null || typeof rawEntity !== 'object' || Array.isArray(rawEntity)) continue;
+    const instance = (rawEntity as { instance?: unknown }).instance;
+    if (instance === null || typeof instance !== 'object' || Array.isArray(instance)) continue;
+    const source = (instance as { source?: unknown }).source;
+    const resolved =
+      typeof source === 'number' && Number.isInteger(source)
+        ? asset.refs[source]
+        : typeof source === 'string'
+          ? source
+          : undefined;
     if (typeof resolved !== 'string') continue;
     yield resolved.toLowerCase();
   }
@@ -450,7 +458,7 @@ async function scanValidated(
           guidToPath.set(normalizedGuid, packPath);
           packRefs.set(normalizedGuid, [
             ...asset.refs.map((ref) => ref.toLowerCase()),
-            ...extractMountSourceGuids(asset),
+            ...extractInstanceSourceGuids(asset),
           ]);
         }
       }
@@ -563,20 +571,12 @@ async function scanValidated(
       }
       guidToPath.set(normalizedGuid, packPath);
 
-      // feat-20260608-scene-nesting-ecs-fication M1 / w14 (D-1):
-      // mount-payload-extract — for scene assets, redundantly inject the
-      // mount.source -> resolved GUID edge into the cycle graph alongside
-      // asset.refs[]. By the .pack.json convention mount.source is an
-      // integer index into the same asset.refs[], so the resolved GUID is
-      // already present in `existingRefs`; this defensive pass guarantees
-      // that any author-supplied mounts[] references participate in the
-      // cycle DFS even if the schema-emitter forgot to mirror them into
-      // refs[]. The `kind: 'mount-asset'` tag on the resulting
-      // pack-cyclic-reference detail is set by the cycle producer below
-      // (R10).
+      // Keyed scene instances are explicit dependency edges. Keep the
+      // producer source in the cycle graph alongside ordinary asset refs so
+      // recursive SceneAsset declarations fail before publication.
       packRefs.set(normalizedGuid, [
         ...asset.refs.map((ref) => ref.toLowerCase()),
-        ...extractMountSourceGuids(asset),
+        ...extractInstanceSourceGuids(asset),
       ]);
     }
     capture?.declarations.set(packPath, {

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('; ')}`,
       );
     }