@forgeax/engine-pack 0.1.21 → 0.1.23

package/src/evidence/source-inventory.ts

@@ -2,9 +2,8 @@ import { createHash } from 'node:crypto';
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import type { SourceDeclarationEvidence } from '@forgeax/engine-types';
+import { parseParameterizedPackJson, projectDirectPackJson } from '../parameterized-pack.js';
 import { SCANNER_BLACKLIST, scan } from '../scanner.js';
-import { projectScriptablePackMeta } from '../scriptable-pack.js';
-import { loadScriptablePack } from '../scriptable-pack-node.js';
 
 /** Project root and GUID used to locate an authoritative source declaration. */
 export interface SourceInventoryRequest {
@@ -150,34 +149,43 @@ export async function readSourceInventory(
   let authored: SourceDeclarationEvidence | undefined;
   for (const path of paths) {
     if (path.endsWith('.pack.ts')) {
-      const loaded = await loadScriptablePack(path, { metadataOnly: true });
-      if (!loaded.ok) continue;
-      const meta = projectScriptablePackMeta(loaded.value, path);
-      if (meta.subAssets.some((asset) => asset.guid.toLowerCase() === guid)) {
-        return { origin: 'sourceMeta', sourcePath: path };
-      }
+      // Parameterized source identity is a build result, not a declaration
+      // table. The source index therefore records the source only after the
+      // producer publishes its materialized Pack output.
       continue;
     }
     const raw = await readFile(path, 'utf8').catch(() => undefined);
     if (raw === undefined) continue;
-    let parsed: {
-      readonly assets?: readonly { readonly guid?: unknown }[];
-      readonly source?: unknown;
-      readonly inputFingerprint?: unknown;
-      readonly importSettings?: unknown;
-      readonly subAssets?: readonly { readonly guid?: unknown }[];
-    };
+    let parsed: Record<string, unknown>;
     try {
-      parsed = JSON.parse(raw) as typeof parsed;
+      const value: unknown = JSON.parse(raw);
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) continue;
+      parsed = value as Record<string, unknown>;
     } catch {
       continue;
     }
     if (path.endsWith('.pack.json')) {
-      if (
-        parsed.assets?.some(
+      if (parsed.schemaVersion === '3.0.0') {
+        const direct = parseParameterizedPackJson(parsed);
+        if (direct.ok && direct.value.format === 'direct') {
+          const projected = projectDirectPackJson(direct.value);
+          if (
+            projected.ok &&
+            projected.value.assets.some((asset) => asset.guid.toLowerCase() === guid)
+          ) {
+            authored = { origin: 'authoredPack', sourcePath: path };
+          }
+        }
+      } else if (
+        Array.isArray(parsed.assets) &&
+        parsed.assets.some(
           (asset) =>
-            typeof asset.guid === 'string' &&
-            (asset.guid === request.guid || asset.guid.toLowerCase() === guid),
+            asset !== null &&
+            typeof asset === 'object' &&
+            !Array.isArray(asset) &&
+            typeof (asset as { readonly guid?: unknown }).guid === 'string' &&
+            ((asset as { readonly guid: string }).guid === request.guid ||
+              (asset as { readonly guid: string }).guid.toLowerCase() === guid),
         )
       ) {
         authored = { origin: 'authoredPack', sourcePath: path };
@@ -185,7 +193,12 @@ export async function readSourceInventory(
       continue;
     }
     if (path.endsWith('.meta.json')) {
-      const source = sourceFromMeta(path, parsed, request.guid, raw);
+      const source = sourceFromMeta(
+        path,
+        parsed as Parameters<typeof sourceFromMeta>[1],
+        request.guid,
+        raw,
+      );
       if (source !== undefined) return source;
     }
   }

package/src/guid.ts

@@ -1,3 +1,4 @@
+import { sha1 } from '@noble/hashes/legacy.js';
 import { uuidv7obj } from 'uuidv7';
 import { PackError } from './errors.js';
 
@@ -8,6 +9,9 @@ import { PackError } from './errors.js';
  */
 export type AssetGuid = Uint8Array & { readonly __guidBrand: 'AssetGuid' };
 
+/** Pack-level identity. It is intentionally not assignable to AssetGuid. */
+export type PackageId = Uint8Array & { readonly __packageIdBrand: 'PackageId' };
+
 /** Minimal Result alias for this module (structurally compatible with ScanResult). */
 export type GuidResult<T, E> =
   | { readonly ok: true; readonly value: T }
@@ -27,6 +31,13 @@ function bytesToDashForm(bytes: Uint8Array): string {
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+/** Stable author-owned output identity. Paths and payloads are not identity inputs. */
+export const PACK_SOURCE_KEY_RE = /^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*$/;
+
+export function isValidPackSourceKey(value: unknown): value is string {
+  return typeof value === 'string' && PACK_SOURCE_KEY_RE.test(value);
+}
+
 export function isValidAssetGuidString(value: unknown): value is string {
   return typeof value === 'string' && UUID_RE.test(value);
 }
@@ -40,6 +51,54 @@ function dashFormToBytes(dashForm: string): Uint8Array {
   return bytes;
 }
 
+function randomUuidBytes(): Uint8Array {
+  const uuid = uuidv7obj();
+  const bytes = new Uint8Array(16);
+  bytes.set(uuid.bytes);
+  return bytes;
+}
+
+function packageId(value: Uint8Array): PackageId {
+  return value as PackageId;
+}
+
+/** Utilities for the pack-level UUID identity. */
+export const PackageId = {
+  parse(dashForm: string): GuidResult<PackageId, PackError> {
+    const parsed = AssetGuid.parse(dashForm);
+    return parsed.ok ? { ok: true, value: packageId(parsed.value) } : parsed;
+  },
+  format(value: PackageId): string {
+    return bytesToDashForm(value);
+  },
+  random(): PackageId {
+    return packageId(randomUuidBytes());
+  },
+} as const;
+
+function derivedGuid(namespace: PackageId, sourceKey: string): AssetGuid {
+  if (!(namespace instanceof Uint8Array) || namespace.byteLength !== 16) {
+    throw new TypeError('AssetGuid.derive requires a 16-byte PackageId');
+  }
+  if (!isValidPackSourceKey(sourceKey)) {
+    const error = new TypeError(
+      `AssetGuid.derive received invalid sourceKey ${JSON.stringify(sourceKey)}`,
+    ) as TypeError & { readonly code?: string };
+    Object.defineProperty(error, 'code', { value: 'pack-source-key-invalid' });
+    throw error;
+  }
+  const name = new TextEncoder().encode(sourceKey);
+  const input = new Uint8Array(namespace.byteLength + name.byteLength);
+  input.set(namespace, 0);
+  input.set(name, namespace.byteLength);
+  const digest = sha1(input);
+  const result = digest.slice(0, 16);
+  // RFC 4122 §4.1.1 / §4.1.3: UUID version 5, RFC variant.
+  result[6] = ((result[6] ?? 0) & 0x0f) | 0x50;
+  result[8] = ((result[8] ?? 0) & 0x3f) | 0x80;
+  return brand(result);
+}
+
 /**
  * Utilities for the AssetGuid branded 16-byte UUID type.
  * Declare the type via `import type { AssetGuid } from '@forgeax/engine-pack/guid'`
@@ -91,9 +150,11 @@ export const AssetGuid = {
    * Works in both Node.js and browser environments.
    */
   random(): AssetGuid {
-    const uuid = uuidv7obj();
-    const bytes = new Uint8Array(16);
-    bytes.set(uuid.bytes);
-    return brand(bytes);
+    return brand(randomUuidBytes());
+  },
+
+  /** Derive the stable UUIDv5 projection for one Pack subject and sourceKey. */
+  derive(namespace: PackageId, sourceKey: string): AssetGuid {
+    return derivedGuid(namespace, sourceKey);
   },
 } as const;

package/src/index.ts

@@ -22,6 +22,13 @@ export {
   validateMaterialCookReceipt,
 } from './evidence/material-cook.js';
 export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';
+export {
+  AssetGuid,
+  isValidAssetGuidString,
+  isValidPackSourceKey,
+  PACK_SOURCE_KEY_RE,
+  PackageId,
+} from './guid.js';
 export {
   decodeMeshBinHeader,
   MESH_BIN_DIGEST_BYTES,
@@ -33,24 +40,18 @@ export {
   type MeshBinHeaderV4,
   writeMeshBinHeader,
 } from './mesh-bin-contract.js';
+export * from './parameterized-pack.js';
 export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 export {
   type AssetReader,
   isScriptablePackAssetKind,
-  projectScriptablePackMeta,
+  projectScriptablePackSceneComponents,
   SCRIPTABLE_PACK_ASSET_KINDS,
-  type ScriptablePackAssetDeclaration,
-  type ScriptablePackAssetDeclarations,
-  type ScriptablePackAssetFor,
   type ScriptablePackAssetKind,
-  type ScriptablePackDefinition,
-  type ScriptablePackError,
-  type ScriptablePackExternalAssets,
-  type ScriptablePackMetaJson,
-  type ScriptablePackOutputs,
-  type ScriptablePackPublicationEnvelope,
   type ScriptablePackReadError,
-  validateScriptablePackDefinition,
+  type ScriptablePackSceneComponent,
+  type ScriptablePackSceneComponentInput,
+  type ScriptablePackSourceClosureEntry,
 } from './scriptable-pack.js';
 export { calculateTopologyDiff, diffTopology } from './topology.js';
 

package/src/inventory/binding.ts

@@ -0,0 +1,25 @@
+import type { AssetRef, SceneEntityRef } from '@forgeax/engine-types';
+import type { AuthorInventory } from './declaration.js';
+
+export function projectAssetRefs(inventory: AuthorInventory): readonly AssetRef[] {
+  return inventory.declarations.map(
+    (row) =>
+      ({
+        guid: row.guid,
+        sourceKey: row.sourceKey,
+        kind: row.kind,
+      }) as 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.sceneBindings.map((bindingKey) => ({
+          sceneSourceKey: row.sourceKey,
+          bindingKey,
+        })),
+  );
+}

package/src/inventory/declaration.ts

@@ -0,0 +1,168 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export interface AuthorInventoryRow {
+  readonly guid: string;
+  readonly sourceKey: string;
+  readonly kind: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly refs: readonly string[];
+  readonly sceneBindings?: readonly string[];
+}
+
+export interface AuthorInventory {
+  readonly declarations: readonly AuthorInventoryRow[];
+}
+
+export type InventoryErrorCode =
+  | 'inventory-source-key-missing'
+  | 'inventory-source-key-duplicate'
+  | 'inventory-guid-duplicate'
+  | 'inventory-scene-binding-missing'
+  | 'inventory-scene-binding-duplicate';
+
+export type InventoryError = {
+  readonly code: InventoryErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly guid?: string;
+    readonly sourceKey?: string;
+  };
+};
+
+function failure(
+  code: InventoryErrorCode,
+  expected: string,
+  hint: string,
+  detail: InventoryError['detail'],
+): Result<never, InventoryError> {
+  return err({ code, expected, hint, detail });
+}
+
+export function validateAuthorInventory(value: unknown): Result<AuthorInventory, InventoryError> {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !Array.isArray((value as { readonly declarations?: unknown }).declarations)
+  ) {
+    return failure(
+      'inventory-source-key-missing',
+      'an author inventory with declaration rows',
+      'declare each author asset in the source inventory',
+      {},
+    );
+  }
+
+  const guids = new Set<string>();
+  const sourceKeys = new Set<string>();
+  const declarations: AuthorInventoryRow[] = [];
+  const rows = (value as { readonly declarations: readonly unknown[] }).declarations;
+  for (const raw of rows) {
+    if (typeof raw !== 'object' || raw === null) {
+      return failure(
+        'inventory-source-key-missing',
+        'each declaration has a non-empty sourceKey',
+        'add sourceKey to the author declaration before projection',
+        {},
+      );
+    }
+    const row = raw as Record<string, unknown>;
+    const guid = typeof row.guid === 'string' ? row.guid : undefined;
+    const sourceKey = typeof row.sourceKey === 'string' ? row.sourceKey : undefined;
+    if (
+      guid === undefined ||
+      sourceKey === undefined ||
+      sourceKey.trim().length === 0 ||
+      sourceKey !== sourceKey.trim()
+    ) {
+      return failure(
+        'inventory-source-key-missing',
+        'each declaration has a non-empty sourceKey',
+        'add sourceKey to the author declaration before projection',
+        {
+          ...(guid === undefined ? {} : { guid }),
+          ...(sourceKey === undefined ? {} : { sourceKey }),
+        },
+      );
+    }
+    const normalizedGuid = guid.toLowerCase();
+    if (guids.has(normalizedGuid)) {
+      return failure(
+        'inventory-guid-duplicate',
+        'every GUID identifies exactly one author declaration',
+        'remove or rename the duplicate GUID before publishing the inventory',
+        { guid, sourceKey },
+      );
+    }
+    if (sourceKeys.has(sourceKey)) {
+      return failure(
+        'inventory-source-key-duplicate',
+        'every sourceKey identifies exactly one author declaration',
+        'rename the duplicate semantic sourceKey before publishing the inventory',
+        { 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;
+    declarations.push({
+      guid,
+      sourceKey,
+      kind: typeof row.kind === 'string' ? row.kind : 'unknown',
+      payload:
+        typeof row.payload === 'object' && row.payload !== null
+          ? (row.payload as Readonly<Record<string, unknown>>)
+          : {},
+      refs: Array.isArray(row.refs)
+        ? row.refs.filter((ref): ref is string => typeof ref === 'string')
+        : [],
+      ...(sceneBindings === undefined ? {} : { sceneBindings }),
+    });
+  }
+  return ok({ declarations });
+}

package/src/inventory/index.ts

@@ -0,0 +1,18 @@
+export { validateProducerContract, validateProducerOutputs } from '../producer-contract.js';
+export {
+  type InventoryDeclaration,
+  type MetaInventoryDocument,
+  type MetaInventorySubAsset,
+  type PackInventoryAsset,
+  type PackInventoryDocument,
+  SCANNER_BLACKLIST,
+  type ScanInventory,
+  type ScanOptions,
+  type ScanResult,
+  type ScanSourceDeclaration,
+  type ScriptablePackInventoryDeclaration,
+  type ScriptablePackScanOptions,
+  STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS,
+  scan,
+  scanInventory,
+} from '../scanner.js';

package/src/inventory/sync.ts

@@ -0,0 +1,22 @@
+import type { AuthorInventory } from './declaration.js';
+
+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') ?? ''}`,
+    )
+    .sort()
+    .join('\n');
+}
+
+export function syncAuthorInventory(inventory: AuthorInventory): AuthorInventory {
+  return {
+    declarations: inventory.declarations.map((row) => ({
+      ...row,
+      refs: [...row.refs],
+      ...(row.sceneBindings === undefined ? {} : { sceneBindings: [...row.sceneBindings] }),
+    })),
+  };
+}

package/src/package-finalizer.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import type { AssetCodec, AssetRelation, CookReceipt } from '@forgeax/engine-types';
+import type { AssetCodec, CookReceipt } from '@forgeax/engine-types';
 
 export interface PackageArtifactBody {
   readonly mediaType: string;
@@ -24,25 +24,6 @@ export interface PackageProduct {
   readonly sourceKey?: string;
 }
 
-/** Minimal authored Pack v1/v2 shape consumed by the file transport seam. */
-export interface AuthoredPackAssetInput {
-  readonly guid: string;
-  readonly kind: string;
-  readonly name?: string;
-  readonly execution?: 'direct' | 'cooked';
-  readonly sourceKey?: string;
-  readonly sourceIndex?: number;
-  readonly relations?: readonly AssetRelation[];
-  readonly payload: Record<string, unknown>;
-  readonly refs?: readonly string[];
-  readonly artifacts?: Readonly<Record<string, unknown>>;
-}
-
-export interface AuthoredPackInput {
-  readonly schemaVersion?: string;
-  readonly assets?: readonly AuthoredPackAssetInput[];
-}
-
 export interface PackageDocumentArtifact {
   readonly path: string;
   readonly mediaType: string;
@@ -66,28 +47,6 @@ export interface PackageDocument {
   readonly assets: readonly PackageDocumentAsset[];
 }
 
-/** Upgrade the legacy authored Pack envelope at the Pack schema boundary. */
-export function upgradeLegacyAuthoredPack(pack: AuthoredPackInput): AuthoredPackInput {
-  if (pack.schemaVersion !== '1.0.0' || pack.assets === undefined) return pack;
-  return {
-    ...pack,
-    schemaVersion: '2.0.0',
-    assets: pack.assets.map((asset) => {
-      const fontRefs =
-        asset.kind === 'font'
-          ? [asset.payload.atlasGuid, asset.payload.samplerGuid].filter(
-              (guid): guid is string => typeof guid === 'string',
-            )
-          : [];
-      return {
-        ...asset,
-        refs: asset.refs ?? fontRefs,
-        artifacts: asset.artifacts ?? {},
-      };
-    }),
-  };
-}
-
 export interface PackageFinalizePolicy {
   readonly base: string;
   readonly packagePath: string;
@@ -364,6 +323,7 @@ export async function finalizePackageTransportSource(
     packageUrl: finalized.value.packageUrl,
     artifacts: transportArtifacts(product.assets, policy.artifactPath),
     digest: finalized.value.digest,
+    receipts: finalized.value.receipts,
     sourceRevision,
     semantic: JSON.stringify(sorted(finalized.value.pack)),
   };