@forgeax/engine-pack 0.1.29 → 0.1.31

package/src/__tests__/runtime-publication.unit.test.ts

@@ -0,0 +1,36 @@
+import { expect, it } from 'vitest';
+import { createRuntimePackPublication } from '../runtime-publication.js';
+
+it('preserves declared source keys in derived publication rows and their digest', () => {
+  const input = {
+    pack: {
+      assets: [
+        { guid: 'WALL-GUID', kind: 'volume', payload: {} },
+        { guid: 'CONTROL-GUID', kind: 'mesh', payload: {} },
+      ],
+    },
+    scopeId: 'lab',
+    sourcePath: 'wall.pack.json',
+    sourceRevision: 'source-1',
+    packageUrl: '/wall.pack.json',
+  };
+  const before = createRuntimePackPublication(input);
+  const after = createRuntimePackPublication({
+    ...input,
+    sourceKeys: new Map([['wall-guid', 'wall/main']]),
+  });
+  expect(after.publication.outputs.map(({ guid, sourceKey }) => [guid, sourceKey])).toEqual([
+    ['wall-guid', 'wall/main'],
+    ['control-guid', 'control-guid'],
+  ]);
+  expect(after.pack.digest).toBe(before.pack.digest);
+  expect(after.pack.outputSetDigest).not.toBe(before.pack.outputSetDigest);
+  expect(after.publication.receipt.outputSetDigest).toBe(after.pack.outputSetDigest);
+  // Explicit producer output rows remain authoritative when provided.
+  const explicit = createRuntimePackPublication({
+    ...input,
+    sourceKeys: new Map([['wall-guid', 'ignored']]),
+    outputs: after.publication.outputs,
+  });
+  expect(explicit.publication.outputs).toEqual(after.publication.outputs);
+});

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

@@ -1,12 +1,46 @@
 // @perf-budget-skip: intentional ScriptablePack CLI integration gate.
 
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { err } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { runCliAsset } from '../cli-asset.js';
+import { loadScriptablePack } from '../scriptable-pack-node.js';
 
 describe('ScriptablePack CLI Meta inspection', () => {
+  it('executes TypeScript re-export closures using JavaScript specifiers and directory indexes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-ts-closure-'));
+    try {
+      await mkdir(join(root, 'nested'));
+      await writeFile(join(root, 'nested/index.ts'), 'export const count: number = 7;');
+      await writeFile(join(root, 'barrel.ts'), "export * from './nested';");
+      const source = join(root, 'shape.pack.ts');
+      await writeFile(
+        source,
+        `import { count } from './barrel.js';
+        export default { schemaVersion: '2.0.0',
+          packageId: new Uint8Array([1,159,250,151,139,57,122,210,132,204,39,50,104,89,26,180]),
+          build() { return { ok: true, value: { 'scene/main': { kind: 'scene', entities: [], mounts: [], count } } }; }
+        };`,
+      );
+      const loaded = await loadScriptablePack(source);
+      expect(loaded.ok).toBe(true);
+      if (!loaded.ok) throw loaded.error;
+      const built = await loaded.value.build({
+        packageId: loaded.value.packageId,
+        values: {},
+        readByGuid: async () => err('unused'),
+      });
+      expect(built).toMatchObject({
+        ok: true,
+        value: { 'scene/main': { kind: 'scene', count: 7 } },
+      });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it('loads the definition without invoking build', async () => {
     const root = await mkdtemp(join(tmpdir(), 'forgeax-scriptable-pack-'));
     try {

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/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/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": [

package/src/scriptable-pack-node.ts

@@ -684,7 +684,11 @@ export async function loadScriptablePack(
   options: LoadScriptablePackOptions = {},
 ): Promise<Result<Readonly<AnyScriptablePackDefinition>, PackAuthoringError>> {
   const timeoutMs = options.timeoutMs ?? 15_000;
-  const buildTimeoutMs = options.buildTimeoutMs ?? 5_000;
+  // Keep authored builds bounded, but give legitimate procedural packs the
+  // same cold-start budget already used for module initialization. The old
+  // five-second default rejected large production packs before they could
+  // publish a result.
+  const buildTimeoutMs = options.buildTimeoutMs ?? 15_000;
   const executor = options.executor ?? new WorkerScriptablePackExecutor();
   let disposeReason: 'complete' | 'timeout' | 'failure' | undefined;
   let timeout: ReturnType<typeof setTimeout> | undefined;

package/src/scriptable-pack-worker.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parentPort, workerData } from 'node:worker_threads';
@@ -66,15 +66,26 @@ const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs']
 function resolveRelativeImport(importer: string, specifier: string): string | undefined {
   if (!specifier.startsWith('.')) return undefined;
   const raw = resolve(dirname(importer), specifier);
+  const extension = extname(raw);
+  const stem = raw.slice(0, raw.length - extension.length);
+  // Authored NodeNext sources use runtime extensions even when their producer files are TypeScript.
+  const substitutions =
+    extension === '.js'
+      ? [`${stem}.ts`, `${stem}.tsx`]
+      : extension === '.mjs'
+        ? [`${stem}.mts`]
+        : extension === '.cjs'
+          ? [`${stem}.cts`]
+          : [];
   const candidates =
-    extname(raw).length > 0
-      ? [raw]
+    extension.length > 0
+      ? [...substitutions, raw]
       : [
           raw,
           ...SOURCE_EXTENSIONS.map((extension) => `${raw}${extension}`),
           resolve(raw, 'index.ts'),
         ];
-  return candidates.find((candidate) => existsSync(candidate));
+  return candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
 }
 
 function outputName(path: string): string {

package/src/scriptable-pack.ts

@@ -1,4 +1,5 @@
 import type { Asset, AssetGuid, Result } from '@forgeax/engine-types';
+import type { PackCookSource } from './pack-authoring.js';
 
 /**
  * Build-time Pack vocabulary shared by the source loader and output
@@ -82,7 +83,7 @@ export interface ScriptablePackSourceClosureEntry {
 
 /** AssetReader is intentionally a small, realm-neutral source boundary. */
 export interface AssetReader {
-  readByGuid<TAsset extends Asset = Asset>(
+  readByGuid<TAsset extends Asset | PackCookSource = Asset>(
     guid: AssetGuid,
   ): Promise<Result<TAsset, ScriptablePackReadError>>;
 }