@forgeax/engine-pack 0.1.21 → 0.1.24

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

@@ -7,6 +7,8 @@ export {
   collectMaterialCookRefs,
   createMaterialArtifactDigest,
   createMaterialCookIdentity,
+  isStandardMaterialRecord,
+  isStandardRootModule,
   type MaterialCookArtifact,
   type MaterialCookIdentity,
   type MaterialCookIdentityExpectation,
@@ -15,6 +17,7 @@ export {
   type MaterialCookRecordError,
   type MaterialCookRefs,
   type MaterialCookWasmProvenance,
+  materialLayerPlanIdentity,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,
@@ -22,6 +25,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 +43,18 @@ export {
   type MeshBinHeaderV4,
   writeMeshBinHeader,
 } from './mesh-bin-contract.js';
+export * from './pack-authoring.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/material-cook.ts

@@ -8,6 +8,7 @@ export {
   type MaterialCookRecordError,
   type MaterialCookRefs,
   type MaterialCookWasmProvenance,
+  materialLayerPlanIdentity,
   projectCookedMaterialRecord,
   serializeCookedMaterialRecord,
   serializeMaterialCookReceipt,