@forgeax/engine-pack 0.1.28 → 0.1.30

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/evidence/material-cook.ts

@@ -2,12 +2,20 @@ import type {
   MaterialAsset,
   MaterialParameter,
   MaterialPass,
+  MaterialProgramAbi,
+  MaterialProgramAddress,
   MaterialTextureReference,
   MaterialTextureValue,
   MaterialValue,
   Result,
 } from '@forgeax/engine-types';
-import { deriveStandardLayerPlan, err, MATERIAL_TEXTURE_SLOTS, ok } from '@forgeax/engine-types';
+import {
+  deriveStandardLayerPlan,
+  err,
+  isMaterialProgramAbi,
+  MATERIAL_TEXTURE_SLOTS,
+  ok,
+} from '@forgeax/engine-types';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { bytesToHex } from '@noble/hashes/utils.js';
 
@@ -44,6 +52,12 @@ export interface MaterialCookProgram {
   readonly selections: readonly {
     readonly pass: string;
     readonly context: MaterialCookProgramContext;
+    /** Renderer submission address selected by this publication. */
+    readonly address?: MaterialProgramAddress;
+    /** Actual entry point paired with the selected address. */
+    readonly entry?: string;
+    /** Producer-reflected ABI facts for the selected artifact/entry. */
+    readonly abi?: MaterialProgramAbi;
   }[];
 }
 
@@ -483,6 +497,9 @@ export function validateCookedMaterialRecord(
   const programs: MaterialCookProgram[] = [];
   const programKeys = new Set<string>();
   const selections = new Set<string>();
+  const submissionSelections = new Map<string, Set<MaterialProgramAddress>>();
+  let modernPublication = false;
+  let legacySelectionField: string | undefined;
   const selectedPasses = new Set<string>();
   for (const [index, entry] of candidate.programs.entries()) {
     const field = `programs[${index}]`;
@@ -511,9 +528,11 @@ export function validateCookedMaterialRecord(
     if (!Array.isArray(program.selections) || program.selections.length === 0)
       return invalid(`${field}.selections`);
     const programSelections: MaterialCookProgram['selections'][number][] = [];
-    for (const [selectionIndex, selection] of program.selections.entries()) {
+    for (const [selectionIndex, rawSelection] of program.selections.entries()) {
       const selectionField = `${field}.selections[${selectionIndex}]`;
-      if (selection === null || typeof selection !== 'object' || !passNames.has(selection.pass))
+      if (rawSelection === null || typeof rawSelection !== 'object') return invalid(selectionField);
+      const selection = rawSelection as Record<string, unknown>;
+      if (typeof selection.pass !== 'string' || !passNames.has(selection.pass))
         return invalid(selectionField);
       const context = validateMaterialCookProgramContext(selection.context);
       if (!context.ok)
@@ -521,11 +540,55 @@ export function validateCookedMaterialRecord(
           `${selectionField}.${context.error.detail.field}`,
           context.error.detail.actual,
         );
-      const key = JSON.stringify([selection.pass, materialProgramContextKey(context.value)]);
+      const address = selection.address === undefined ? 'direct' : selection.address;
+      if (address !== 'direct' && address !== 'scene-index')
+        return invalid(`${selectionField}.address`, selection.address);
+      const hasAddressFacts =
+        selection.address !== undefined ||
+        selection.entry !== undefined ||
+        selection.abi !== undefined;
+      modernPublication ||= hasAddressFacts;
+      if (!hasAddressFacts) legacySelectionField ??= selectionField;
+      const rawEntry = selection.entry;
+      const entry = typeof rawEntry === 'string' ? rawEntry : undefined;
+      if (hasAddressFacts && selection.address === undefined)
+        return invalid(
+          `${selectionField}.address`,
+          'modern ABI selections require an explicit address',
+        );
+      if (hasAddressFacts && (entry === undefined || entry.length === 0))
+        return invalid(`${selectionField}.entry`, rawEntry);
+      if (hasAddressFacts && !isMaterialProgramAbi(selection.abi))
+        return invalid(`${selectionField}.abi`, selection.abi);
+      if (hasAddressFacts) {
+        const abi = selection.abi as MaterialProgramAbi;
+        const expectedEntry = address === 'direct' ? abi.directEntry : abi.sceneIndexEntry;
+        if (entry !== expectedEntry)
+          return invalid(`${selectionField}.entry`, 'entry does not match published ABI');
+        const submissionKey = JSON.stringify([
+          selection.pass,
+          materialProgramContextKey(context.value),
+        ]);
+        const addresses =
+          submissionSelections.get(submissionKey) ?? new Set<MaterialProgramAddress>();
+        addresses.add(address);
+        submissionSelections.set(submissionKey, addresses);
+      }
+      const key = JSON.stringify([
+        selection.pass,
+        materialProgramContextKey(context.value),
+        address,
+      ]);
       if (selections.has(key)) return invalid(selectionField, 'ambiguous Pass/context selection');
       selections.add(key);
       selectedPasses.add(selection.pass);
-      programSelections.push({ pass: selection.pass, context: context.value });
+      programSelections.push({
+        pass: selection.pass,
+        context: context.value,
+        ...(selection.address === undefined ? {} : { address }),
+        ...(entry === undefined ? {} : { entry }),
+        ...(selection.abi === undefined ? {} : { abi: selection.abi as MaterialProgramAbi }),
+      });
     }
     programs.push({
       specializationKey: program.specializationKey,
@@ -533,6 +596,17 @@ export function validateCookedMaterialRecord(
       selections: programSelections,
     });
   }
+  if (modernPublication && legacySelectionField !== undefined) {
+    return invalid(
+      legacySelectionField,
+      'modern material publications require address, entry, and ABI facts on every selection',
+    );
+  }
+  for (const [selectionKey, addresses] of submissionSelections) {
+    if (addresses.size !== 2) {
+      return invalid('programs.selections', `incomplete submission address pair: ${selectionKey}`);
+    }
+  }
   if ([...passNames].some((pass) => !selectedPasses.has(pass)))
     return invalid('programs.selections', 'unpublished Pass');
   const manifestDigest = createMaterialProgramSetDigest(programs, passes);

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/pack-authoring.ts

@@ -569,7 +569,9 @@ function validateParameterDefinitions(
 }
 
 export interface PackBuildReadContext {
-  readByGuid<TAsset extends Asset = Asset>(guid: AssetGuid): Promise<Result<TAsset, unknown>>;
+  readByGuid<TAsset extends Asset | PackCookSource = Asset>(
+    guid: AssetGuid,
+  ): Promise<Result<TAsset, unknown>>;
 }
 
 export interface PackBuildContextWithoutParameters extends PackBuildReadContext {
@@ -588,7 +590,14 @@ export type PackBuildContext<TParameters extends readonly PackParameterDefinitio
     ? PackBuildContextWithParameters<TParameters>
     : PackBuildContextWithoutParameters;
 
-export type PackOutputMap = Readonly<Record<string, Asset>>;
+/** Build-only custom source. The host derives identity and invokes the kind's NativeCooker. */
+export interface PackCookSource {
+  readonly kind: string;
+  readonly execution: 'cooked';
+  readonly source: unknown;
+}
+
+export type PackOutputMap = Readonly<Record<string, Asset | PackCookSource>>;
 export type PackBuildResult<TError = unknown> =
   | Result<PackOutputMap, TError>
   | Promise<Result<PackOutputMap, TError>>;

package/src/runtime-publication.ts

@@ -48,6 +48,8 @@ export interface RuntimePackPublicationInput {
   readonly digest?: string;
   readonly generation?: number;
   readonly outputs?: readonly AssetPublicationOutput[];
+  /** Author/producer keys by normalized GUID when deriving output rows. */
+  readonly sourceKeys?: ReadonlyMap<string, string>;
   readonly externalEvidence?: readonly AssetPublicationExternalEvidence[];
 }
 
@@ -88,10 +90,10 @@ function normalizedAssets(pack: RuntimePackInput): readonly RuntimePackAsset[] {
   });
 }
 
-function outputFor(asset: RuntimePackAsset): AssetPublicationOutput {
+function outputFor(asset: RuntimePackAsset, sourceKey?: string): AssetPublicationOutput {
   return {
     guid: asset.guid.toLowerCase(),
-    sourceKey: asset.guid.toLowerCase(),
+    sourceKey: sourceKey ?? asset.guid.toLowerCase(),
     kind: asset.kind,
     digest: digest({
       guid: asset.guid.toLowerCase(),
@@ -145,7 +147,9 @@ export function createRuntimePackPublication(
     ),
   };
   const valueDigest = input.digest ?? digest(semantic);
-  const outputs = input.outputs ?? assets.map(outputFor);
+  const outputs =
+    input.outputs ??
+    assets.map((asset) => outputFor(asset, input.sourceKeys?.get(asset.guid.toLowerCase())));
   const outputDigest = outputSetDigest(outputs);
   const generation =
     input.generation ?? publicationGeneration(input.sourceRevision, valueDigest, outputDigest);

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/material-cook.schema.json

@@ -273,6 +273,113 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "address": {
+                  "enum": ["direct", "scene-index"]
+                },
+                "entry": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "abi": {
+                  "type": "object",
+                  "required": [
+                    "directEntry",
+                    "sceneIndexEntry",
+                    "materialRow",
+                    "resourceSlots",
+                    "uvSets",
+                    "vertexInputs",
+                    "alphaMask",
+                    "reflection",
+                    "receiptIdentity",
+                    "generation"
+                  ],
+                  "properties": {
+                    "directEntry": { "type": "string", "minLength": 1 },
+                    "sceneIndexEntry": { "type": "string", "minLength": 1 },
+                    "materialRow": {
+                      "type": "object",
+                      "required": ["byteLength", "fields"],
+                      "properties": {
+                        "byteLength": { "type": "integer", "minimum": 16, "multipleOf": 16 },
+                        "fields": { "type": "array", "items": { "type": "string" } }
+                      },
+                      "additionalProperties": false
+                    },
+                    "resourceSlots": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": ["name", "parameter", "kind", "group", "binding"],
+                        "properties": {
+                          "name": { "type": "string", "minLength": 1 },
+                          "parameter": { "type": "string", "minLength": 1 },
+                          "kind": { "enum": ["sampler", "texture", "storage-buffer"] },
+                          "group": { "type": "integer", "minimum": 0 },
+                          "binding": { "type": "integer", "minimum": 0 }
+                        },
+                        "additionalProperties": false
+                      }
+                    },
+                    "uvSets": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": ["parameter", "set"],
+                        "properties": {
+                          "parameter": { "type": "string", "minLength": 1 },
+                          "set": { "type": "integer", "minimum": 0 }
+                        },
+                        "additionalProperties": false
+                      }
+                    },
+                    "vertexInputs": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": ["semantic", "location", "format"],
+                        "properties": {
+                          "semantic": { "type": "string", "minLength": 1 },
+                          "location": { "type": "integer", "minimum": 0 },
+                          "format": { "type": "string", "minLength": 1 }
+                        },
+                        "additionalProperties": false
+                      }
+                    },
+                    "alphaMask": {
+                      "type": "object",
+                      "required": ["cutoff", "source"],
+                      "properties": {
+                        "cutoff": { "type": "string" },
+                        "source": { "type": "string" }
+                      },
+                      "additionalProperties": false
+                    },
+                    "skinPaletteAddress": {
+                      "type": "object",
+                      "required": ["group", "binding", "stride"],
+                      "properties": {
+                        "group": { "type": "integer", "minimum": 0 },
+                        "binding": { "type": "integer", "minimum": 0 },
+                        "stride": { "type": "integer", "minimum": 1 }
+                      },
+                      "additionalProperties": false
+                    },
+                    "reflection": {
+                      "type": "object",
+                      "required": ["layoutIdentity", "resourceSlots", "vertexInputs"],
+                      "properties": {
+                        "layoutIdentity": { "type": "string", "minLength": 1 },
+                        "resourceSlots": { "type": "array" },
+                        "vertexInputs": { "type": "array" }
+                      },
+                      "additionalProperties": false
+                    },
+                    "receiptIdentity": { "type": "string", "minLength": 1 },
+                    "generation": { "type": "integer", "minimum": 1 }
+                  },
+                  "additionalProperties": false
+                },
                 "context": {
                   "type": "object",
                   "required": [