@forgeax/engine-pack 0.1.28 → 0.1.30

package/README.md

@@ -37,11 +37,22 @@ export default definePack({
   build: ({ packageId: subjectId }) =>
     ok({
       'mesh/main': { kind: 'mesh', materialSlots: [] },
+      'scene/hero': {
+        kind: 'scene',
+        entities: { body: { components: {} } },
+      },
       'scene/main': {
         kind: 'scene',
-        entities: [],
-        mounts: [],
-        mesh: AssetGuid.format(AssetGuid.derive(subjectId, 'mesh/main')),
+        entities: {
+          root: { components: {} },
+          hero: {
+            components: {},
+            instance: {
+              source: AssetGuid.format(AssetGuid.derive(subjectId, 'scene/hero')),
+              overrides: [{ target: ['body'], components: {} }],
+            },
+          },
+        },
       },
     }),
 });
@@ -201,9 +212,10 @@ Pack owns the offline half of the GUID evidence chain: `source inventory -> cata
 
 The catalog is a locator, not proof. `lookup/verify --guid --project --catalog --json` joins the source meta or authored pack, the catalog row, the receipt, and the package descriptors. Both commands emit one JSON record on stdout or one structured `{code, expected, hint, detail}` record on stderr; there is no runtime or WebSocket dependency.
 
-## VFX Pack v2 migration
+## VFX Program v3 in Pack v2
 
-VFX source v2 is cooked in one atomic producer step. The executable contract is
+VFX source v3 is cooked in one atomic producer step and stored in the ordinary
+Pack v2 envelope. The executable contract is
 `scripts/asset-cook-contract.mjs`; a package-local scripts path is not valid.
 The cook publishes the Pack payload and
 `particle-effect/program.json` with the same source fingerprint. Runtime loads
@@ -266,6 +278,22 @@ vectors, colors, and asset-GUID constraints. The isolated Pack worker passes
 only serializable authoring data to the build and never exposes filesystem or
 runtime state.
 
+Custom build-only content uses `PackCookSource` in the same output map:
+
+```ts
+{ 'volume/main': { kind: 'game-volume', execution: 'cooked', source: { size: values.size } } }
+```
+
+Register the matching `NativeCooker` in the build host. The host supplies the
+derived GUID, source key/path and source data; the cooker returns matching-kind
+metadata, references and artifact bytes. Missing cookers, rewritten GUIDs and
+invalid products fail before publication. Custom sources can coexist with
+ordinary Assets and inherit normal Pack parameters and instance identities.
+They cannot override the closed ordinary Asset kinds. Authoring `readByGuid`
+can explicitly request a `PackCookSource` from the current build generation;
+that is source data, not a decoded runtime asset. Runtime custom kinds still
+need their normal Registry loader/decoder. No cooker enters the player.
+
 `forgeax asset inspect --subject <source.pack.ts> --root <project> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(context)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
 
 The default worker executes the complete relative TypeScript module closure on the supported Node floor, including Node 22 hosts that do not load `.ts` files directly. It transpiles that closure into a disposable ESM directory, resolves bare imports through the source project's nearest `node_modules`, and removes the directory when the worker is disposed. Bulk producers use the internal `createScriptablePackModuleExecutorPool()` with two recyclable workers; a pooled lease is released after metadata projection or one build, so a generation never retains one live Worker-backed definition per source.

package/dist/build.mjs

@@ -1,4 +1,4 @@
-import { ok, err, catalogOperationsFor, authoringCapabilityForAssetKind, MATERIAL_TEXTURE_SLOTS, projectCookProductEvidence, projectAssetEvidence, validateSourceOverrideMap, PACK_ERROR_HINTS, catalogEntryDigest, deriveStandardLayerPlan, AssetError, ImportError } from '@forgeax/engine-types';
+import { ok, err, catalogOperationsFor, authoringCapabilityForAssetKind, MATERIAL_TEXTURE_SLOTS, isMaterialProgramAbi, projectCookProductEvidence, projectAssetEvidence, validateSourceOverrideMap, PACK_ERROR_HINTS, catalogEntryDigest, deriveStandardLayerPlan, AssetError, ImportError } from '@forgeax/engine-types';
 import { dirname, resolve, isAbsolute, relative, join, basename, sep, extname } from 'path';
 import { sha1 } from '@noble/hashes/legacy.js';
 import { uuidv7obj } from 'uuidv7';
@@ -9061,9 +9061,17 @@ var WorkerScriptablePackExecutor = class {
         }
       };
       worker.on("message", onMessage);
-      worker.once("error", rejectLoad);
+      const fail = (error) => {
+        rejectLoad(error);
+        const active = this.build;
+        this.build = void 0;
+        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 !== void 0) return;
+        fail(new Error(`ScriptablePack worker exited with code ${code}`));
       });
     });
   }
@@ -9141,7 +9149,7 @@ function scriptablePackLoadFailure(sourcePath, reason, phase, diagnostic, timeou
 }
 async function loadScriptablePack(sourcePath, options = {}) {
   const timeoutMs = options.timeoutMs ?? 15e3;
-  const buildTimeoutMs = options.buildTimeoutMs ?? 5e3;
+  const buildTimeoutMs = options.buildTimeoutMs ?? 15e3;
   const executor = options.executor ?? new WorkerScriptablePackExecutor();
   let disposeReason;
   let timeout;
@@ -9298,16 +9306,17 @@ function makePackError(code, detail) {
     detail
   });
 }
-function* extractMountSourceGuids(asset) {
+function* extractInstanceSourceGuids(asset) {
   if (asset.kind !== "scene") return;
   const payload = asset.payload;
-  if (!payload || !Array.isArray(payload.mounts)) return;
-  for (const rawMount of payload.mounts) {
-    const mount = rawMount;
-    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];
+  if (!payload || payload.entities === null || typeof payload.entities !== "object" || Array.isArray(payload.entities))
+    return;
+  for (const rawEntity of Object.values(payload.entities)) {
+    if (rawEntity === null || typeof rawEntity !== "object" || Array.isArray(rawEntity)) continue;
+    const instance = rawEntity.instance;
+    if (instance === null || typeof instance !== "object" || Array.isArray(instance)) continue;
+    const source = instance.source;
+    const resolved = typeof source === "number" && Number.isInteger(source) ? asset.refs[source] : typeof source === "string" ? source : void 0;
     if (typeof resolved !== "string") continue;
     yield resolved.toLowerCase();
   }
@@ -9425,7 +9434,7 @@ async function scanValidated(roots, opts = {}, capture) {
           guidToPath.set(normalizedGuid, packPath);
           packRefs.set(normalizedGuid, [
             ...asset.refs.map((ref) => ref.toLowerCase()),
-            ...extractMountSourceGuids(asset)
+            ...extractInstanceSourceGuids(asset)
           ]);
         }
       }
@@ -9529,7 +9538,7 @@ async function scanValidated(roots, opts = {}, capture) {
       guidToPath.set(normalizedGuid, packPath);
       packRefs.set(normalizedGuid, [
         ...asset.refs.map((ref) => ref.toLowerCase()),
-        ...extractMountSourceGuids(asset)
+        ...extractInstanceSourceGuids(asset)
       ]);
     }
     capture?.declarations.set(packPath, {
@@ -10538,6 +10547,9 @@ function validateCookedMaterialRecord(value) {
   const programs = [];
   const programKeys = /* @__PURE__ */ new Set();
   const selections = /* @__PURE__ */ new Set();
+  const submissionSelections = /* @__PURE__ */ new Map();
+  let modernPublication = false;
+  let legacySelectionField;
   const selectedPasses = /* @__PURE__ */ new Set();
   for (const [index, entry] of candidate.programs.entries()) {
     const field = `programs[${index}]`;
@@ -10555,9 +10567,11 @@ function validateCookedMaterialRecord(value) {
     if (!Array.isArray(program.selections) || program.selections.length === 0)
       return invalid(`${field}.selections`);
     const programSelections = [];
-    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;
+      if (typeof selection.pass !== "string" || !passNames.has(selection.pass))
         return invalid(selectionField);
       const context = validateMaterialCookProgramContext(selection.context);
       if (!context.ok)
@@ -10565,11 +10579,51 @@ function validateCookedMaterialRecord(value) {
           `${selectionField}.${context.error.detail.field}`,
           context.error.detail.actual
         );
-      const key = JSON.stringify([selection.pass, materialProgramContextKey(context.value)]);
+      const address = selection.address === void 0 ? "direct" : selection.address;
+      if (address !== "direct" && address !== "scene-index")
+        return invalid(`${selectionField}.address`, selection.address);
+      const hasAddressFacts = selection.address !== void 0 || selection.entry !== void 0 || selection.abi !== void 0;
+      modernPublication ||= hasAddressFacts;
+      if (!hasAddressFacts) legacySelectionField ??= selectionField;
+      const rawEntry = selection.entry;
+      const entry2 = typeof rawEntry === "string" ? rawEntry : void 0;
+      if (hasAddressFacts && selection.address === void 0)
+        return invalid(
+          `${selectionField}.address`,
+          "modern ABI selections require an explicit address"
+        );
+      if (hasAddressFacts && (entry2 === void 0 || entry2.length === 0))
+        return invalid(`${selectionField}.entry`, rawEntry);
+      if (hasAddressFacts && !isMaterialProgramAbi(selection.abi))
+        return invalid(`${selectionField}.abi`, selection.abi);
+      if (hasAddressFacts) {
+        const abi = selection.abi;
+        const expectedEntry = address === "direct" ? abi.directEntry : abi.sceneIndexEntry;
+        if (entry2 !== 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) ?? /* @__PURE__ */ new Set();
+        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 === void 0 ? {} : { address },
+        ...entry2 === void 0 ? {} : { entry: entry2 },
+        ...selection.abi === void 0 ? {} : { abi: selection.abi }
+      });
     }
     programs.push({
       specializationKey: program.specializationKey,
@@ -10577,6 +10631,17 @@ function validateCookedMaterialRecord(value) {
       selections: programSelections
     });
   }
+  if (modernPublication && legacySelectionField !== void 0) {
+    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);
@@ -10714,9 +10779,9 @@ function projectAssetRefs(inventory) {
 }
 function projectSceneEntityRefs(inventory) {
   return inventory.declarations.flatMap(
-    (row) => row.sceneBindings === void 0 ? [] : row.sceneBindings.map((bindingKey) => ({
+    (row) => row.sceneEntityKeys === void 0 ? [] : row.sceneEntityKeys.map((address) => ({
       sceneSourceKey: row.sourceKey,
-      bindingKey
+      address
     }))
   );
 }
@@ -10776,49 +10841,23 @@ function validateAuthorInventory(value) {
         { guid, sourceKey: sourceKey2 }
       );
     }
-    if (row.kind === "scene") {
-      const payload = row.payload;
-      const payloadRecord = typeof payload === "object" && payload !== null ? payload : void 0;
-      const entities = payloadRecord !== void 0 && Array.isArray(payloadRecord.entities) ? payloadRecord.entities : [];
-      const bindings = /* @__PURE__ */ new Set();
-      for (const entity of entities) {
-        const bindingKey = typeof entity === "object" && entity !== null && typeof entity.bindingKey === "string" ? entity.bindingKey : void 0;
-        if (bindingKey !== void 0 && bindingKey.length === 0) {
-          return failure2(
-            "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: sourceKey2 }
-          );
-        }
-        if (bindingKey === void 0) continue;
-        if (bindings.has(bindingKey)) {
-          return failure2(
-            "inventory-scene-binding-duplicate",
-            "bindingKey values are unique within one scene",
-            "rename the duplicate bindingKey in the scene producer",
-            { sourceKey: sourceKey2 }
-          );
-        }
-        bindings.add(bindingKey);
-      }
-    }
     guids.add(normalizedGuid);
     sourceKeys.add(sourceKey2);
-    const sceneBindings = row.kind === "scene" && typeof row.payload === "object" && row.payload !== null ? row.payload.entities?.flatMap(
-      (entity) => {
-        if (typeof entity !== "object" || entity === null) return [];
-        const key = entity.bindingKey;
-        return typeof key === "string" && key.length > 0 ? [key] : [];
-      }
-    ) : void 0;
+    const sceneEntityKeys = (() => {
+      if (row.kind !== "scene" || typeof row.payload !== "object" || row.payload === null)
+        return void 0;
+      const entities = row.payload.entities;
+      if (entities === null || typeof entities !== "object" || Array.isArray(entities))
+        return void 0;
+      return Object.keys(entities);
+    })();
     declarations.push({
       guid,
       sourceKey: sourceKey2,
       kind: typeof row.kind === "string" ? row.kind : "unknown",
       payload: typeof row.payload === "object" && row.payload !== null ? row.payload : {},
       refs: Array.isArray(row.refs) ? row.refs.filter((ref) => typeof ref === "string") : [],
-      ...sceneBindings === void 0 ? {} : { sceneBindings }
+      ...sceneEntityKeys === void 0 ? {} : { sceneEntityKeys }
     });
   }
   return ok({ declarations });
@@ -10827,7 +10866,7 @@ function validateAuthorInventory(value) {
 // src/inventory/sync.ts
 function inventoryDigest(inventory) {
   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");
 }
 function syncAuthorInventory(inventory) {
@@ -10835,7 +10874,7 @@ function syncAuthorInventory(inventory) {
     declarations: inventory.declarations.map((row) => ({
       ...row,
       refs: [...row.refs],
-      ...row.sceneBindings === void 0 ? {} : { sceneBindings: [...row.sceneBindings] }
+      ...row.sceneEntityKeys === void 0 ? {} : { sceneEntityKeys: [...row.sceneEntityKeys] }
     }))
   };
 }
@@ -12784,10 +12823,10 @@ function normalizedAssets(pack) {
     };
   });
 }
-function outputFor(asset) {
+function outputFor(asset, sourceKey2) {
   return {
     guid: asset.guid.toLowerCase(),
-    sourceKey: asset.guid.toLowerCase(),
+    sourceKey: sourceKey2 ?? asset.guid.toLowerCase(),
     kind: asset.kind,
     digest: digest2({
       guid: asset.guid.toLowerCase(),
@@ -12826,7 +12865,7 @@ function createRuntimePackPublication(input) {
     )
   };
   const valueDigest = input.digest ?? digest2(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);
   const externalEvidence = input.externalEvidence ?? [];