@forgeax/engine-pack 0.1.2

package/src/guid.ts

@@ -0,0 +1,99 @@
+import { uuidv7obj } from 'uuidv7';
+import { PackError } from './errors.js';
+
+/**
+ * 16-byte UUID branded ABI. Prevents assignment from plain Uint8Array or string.
+ * Brand field mirrors the declaration in @forgeax/engine-types for cross-package
+ * structural compatibility (both use __guidBrand: 'AssetGuid').
+ */
+export type AssetGuid = Uint8Array & { readonly __guidBrand: 'AssetGuid' };
+
+/** Minimal Result alias for this module (structurally compatible with ScanResult). */
+export type GuidResult<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+function brand(bytes: Uint8Array): AssetGuid {
+  return bytes as AssetGuid;
+}
+
+const HEX_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'));
+
+function bytesToDashForm(bytes: Uint8Array): string {
+  const h = HEX_BYTE;
+  // biome-ignore lint/style/noNonNullAssertion: length guaranteed 16
+  return `${h[bytes[0]!]}${h[bytes[1]!]}${h[bytes[2]!]}${h[bytes[3]!]}-${h[bytes[4]!]}${h[bytes[5]!]}-${h[bytes[6]!]}${h[bytes[7]!]}-${h[bytes[8]!]}${h[bytes[9]!]}-${h[bytes[10]!]}${h[bytes[11]!]}${h[bytes[12]!]}${h[bytes[13]!]}${h[bytes[14]!]}${h[bytes[15]!]}`;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isValidAssetGuidString(value: unknown): value is string {
+  return typeof value === 'string' && UUID_RE.test(value);
+}
+
+function dashFormToBytes(dashForm: string): Uint8Array {
+  const hex = dashForm.replace(/-/g, '');
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Utilities for the AssetGuid branded 16-byte UUID type.
+ * Declare the type via `import type { AssetGuid } from '@forgeax/engine-pack/guid'`
+ * or `import type { AssetGuid } from '@forgeax/engine-types'`.
+ */
+export const AssetGuid = {
+  /**
+   * Parse a 36-char RFC 4122 dash-form UUID string into an AssetGuid.
+   * Returns Ok(AssetGuid) on success or Err(PackError) with code 'pack-guid-malformed' on failure.
+   * Never throws for expected failures (requirements §4.2 / §14 / charter proposition 4).
+   */
+  parse(dashForm: string): GuidResult<AssetGuid, PackError> {
+    if (!isValidAssetGuidString(dashForm)) {
+      return {
+        ok: false,
+        error: new PackError({
+          code: 'pack-guid-malformed',
+          expected: '36-char RFC 4122 dash-form UUID',
+          hint: 'use AssetGuid.random() or a UUIDv7 generator; all GUID fields must be 36-char RFC 4122 dash-form',
+          detail: {
+            raw: dashForm,
+            reason: 'expected 36-char RFC 4122 dash-form UUID',
+          },
+        }),
+      };
+    }
+    return { ok: true, value: brand(dashFormToBytes(dashForm)) };
+  },
+
+  /**
+   * Format an AssetGuid as a 36-char RFC 4122 lowercase dash-form string.
+   */
+  format(guid: AssetGuid): string {
+    return bytesToDashForm(guid);
+  },
+
+  /**
+   * Test byte-by-byte equality between two AssetGuids.
+   */
+  equals(a: AssetGuid, b: AssetGuid): boolean {
+    for (let i = 0; i < 16; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  },
+
+  /**
+   * Mint a new time-ordered UUIDv7 as an 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);
+  },
+} as const;

package/src/index.ts

@@ -0,0 +1,104 @@
+// @forgeax/engine-pack
+// Disk schema, GUID tools, scanner, fail-fast error chain, and CLI bin.
+// Entry subpaths: . / schema / guid / errors / bridge / scanner
+
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  type MaterialCookArtifact,
+  type MaterialCookIdentityExpectation,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  serializeMaterialCookReceipt,
+  validateCookedMaterialRecord,
+  validateMaterialCookReceipt,
+} from './evidence/material-cook.js';
+export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';
+export {
+  decodeMeshBinHeader,
+  MESH_BIN_DIGEST_BYTES,
+  MESH_BIN_HEADER_V4_BYTES,
+  MESH_BIN_PROJECTION_VERSION,
+  MESH_BIN_VERSION,
+  type MeshBinContractError,
+  type MeshBinHeaderResult,
+  type MeshBinHeaderV4,
+  writeMeshBinHeader,
+} from './mesh-bin-contract.js';
+export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
+export {
+  type AssetReader,
+  isScriptablePackAssetKind,
+  projectScriptablePackMeta,
+  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,
+} from './scriptable-pack.js';
+export { calculateTopologyDiff, diffTopology } from './topology.js';
+
+import { err, ok, type PackV2, type PackV2Error, type Result } from '@forgeax/engine-types';
+
+export type { ArtifactPathContext } from './artifact-path.js';
+export { validateArtifactPath } from './artifact-path.js';
+
+import { validatePackV2 } from './schema-compiled.js';
+
+export type {
+  AnimationClip,
+  AnimationGraph,
+  Asset,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  MaterialAsset,
+  MeshAsset,
+  PackV2,
+  PackV2Error,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+export {
+  type MaterialArtifactWriteInput,
+  type MaterialArtifactWriteResult,
+  writeMaterialArtifact,
+} from './material/artifact-writer.js';
+export {
+  projectRuntimePack,
+  type RuntimeAssetProjectionInput,
+  type RuntimePackProjectionInput,
+} from './runtime-projection.js';
+export { validateMeta, validatePack, validatePackV2 } from './schema-compiled.js';
+
+export function parsePackV2(value: unknown): Result<PackV2, PackV2Error> {
+  if (!validatePackV2(value)) {
+    return err({
+      code: 'pack-v2-envelope-invalid',
+      expected: 'a Pack v2 envelope with unique asset GUIDs and valid descriptors',
+      hint: 'validate the pack against packages/pack/schema/pack.schema.json and re-cook it',
+      detail: { observed: 'invalid pack', expected: 'schemaVersion 2.0.0' },
+    });
+  }
+
+  return ok(value);
+}

package/src/material/artifact-writer.ts

@@ -0,0 +1,26 @@
+import { createMaterialArtifactDigest } from '../evidence/material-cook.js';
+
+export interface MaterialArtifactWriteInput {
+  readonly key: string;
+  readonly bytes: Uint8Array;
+  readonly mediaType?: string;
+}
+
+export interface MaterialArtifactWriteResult {
+  readonly key: string;
+  readonly bytes: Uint8Array;
+  readonly mediaType: string;
+  readonly digest: string;
+}
+
+/** Pack owns the immutable cooked material artifact tuple. */
+export function writeMaterialArtifact(
+  input: MaterialArtifactWriteInput,
+): MaterialArtifactWriteResult {
+  return {
+    key: input.key,
+    bytes: input.bytes.slice(),
+    mediaType: input.mediaType ?? 'application/octet-stream',
+    digest: createMaterialArtifactDigest(input.bytes),
+  };
+}

package/src/mesh-bin-contract.ts

@@ -0,0 +1,150 @@
+/** Canonical mesh binary wire facts shared by build-time and runtime owners. */
+
+export const MESH_BIN_VERSION = 4 as const;
+export const MESH_BIN_PROJECTION_VERSION = 1 as const;
+export const MESH_BIN_HEADER_V4_BYTES = 80;
+export const MESH_BIN_DIGEST_BYTES = 32;
+
+export interface MeshBinHeaderV4 {
+  readonly version: 4;
+  readonly projectionVersion: 1;
+  readonly mask: number;
+  readonly digest: string;
+  readonly stride: number;
+  readonly vertexCount: number;
+  readonly vertexBytes: number;
+  readonly indexCount: number;
+  readonly indexWidth: 0 | 2 | 4;
+  readonly indexBytes: number;
+  readonly jsonBytes: number;
+}
+
+export interface MeshBinContractError {
+  readonly code:
+    | 'mesh-bin-header-truncated'
+    | 'mesh-bin-version-unsupported'
+    | 'mesh-bin-header-invalid';
+  readonly subject: 'mesh-bin';
+  readonly sourceKey: string;
+  readonly expected: string;
+  readonly actual: string;
+  readonly recovery: string;
+}
+
+export type MeshBinHeaderResult =
+  | { readonly ok: true; readonly value: MeshBinHeaderV4 }
+  | { readonly ok: false; readonly error: MeshBinContractError };
+
+function failure(
+  code: MeshBinContractError['code'],
+  sourceKey: string,
+  expected: string,
+  actual: string,
+): MeshBinHeaderResult {
+  return {
+    ok: false,
+    error: {
+      code,
+      subject: 'mesh-bin',
+      sourceKey,
+      expected,
+      actual,
+      recovery: 're-cook the source with its Meta sidecar through the build-time importer',
+    },
+  };
+}
+
+function digestBytes(digest: string): Uint8Array {
+  const bytes = new Uint8Array(MESH_BIN_DIGEST_BYTES);
+  bytes.set(new TextEncoder().encode(digest).subarray(0, MESH_BIN_DIGEST_BYTES));
+  return bytes;
+}
+
+function readDigest(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes).replace(/\0+$/u, '');
+}
+
+export function writeMeshBinHeader(header: MeshBinHeaderV4, out: Uint8Array): void {
+  if (out.byteLength < MESH_BIN_HEADER_V4_BYTES) {
+    throw new RangeError('mesh-bin v4 header output is truncated');
+  }
+  const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  view.setUint32(0, header.version, true);
+  view.setUint32(4, header.projectionVersion, true);
+  view.setUint32(8, header.mask, true);
+  view.setUint32(12, header.stride, true);
+  view.setUint32(16, header.vertexCount, true);
+  view.setUint32(20, header.vertexBytes, true);
+  view.setUint32(24, header.indexCount, true);
+  view.setUint32(28, header.indexWidth, true);
+  view.setUint32(32, header.indexBytes, true);
+  view.setUint32(36, header.jsonBytes, true);
+  out.set(digestBytes(header.digest), 48);
+}
+
+export function decodeMeshBinHeader(
+  bytes: Uint8Array,
+  sourceKey = '<unknown mesh source>',
+): MeshBinHeaderResult {
+  if (bytes.byteLength < MESH_BIN_HEADER_V4_BYTES) {
+    return failure(
+      'mesh-bin-header-truncated',
+      sourceKey,
+      `mesh-bin v4 header (${MESH_BIN_HEADER_V4_BYTES} bytes)`,
+      `${bytes.byteLength} bytes`,
+    );
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = view.getUint32(0, true);
+  if (version !== MESH_BIN_VERSION) {
+    return failure('mesh-bin-version-unsupported', sourceKey, 'mesh-bin v4', `version ${version}`);
+  }
+  const projectionVersion = view.getUint32(4, true);
+  const mask = view.getUint32(8, true);
+  const stride = view.getUint32(12, true);
+  const vertexCount = view.getUint32(16, true);
+  const vertexBytes = view.getUint32(20, true);
+  const indexCount = view.getUint32(24, true);
+  const indexWidth = view.getUint32(28, true);
+  const indexBytes = view.getUint32(32, true);
+  const jsonBytes = view.getUint32(36, true);
+  const digest = readDigest(bytes.subarray(48, 48 + MESH_BIN_DIGEST_BYTES));
+  if (
+    projectionVersion !== MESH_BIN_PROJECTION_VERSION ||
+    mask === 0 ||
+    stride === 0 ||
+    !Number.isSafeInteger(vertexCount) ||
+    !Number.isSafeInteger(vertexBytes) ||
+    !Number.isSafeInteger(indexCount) ||
+    !Number.isSafeInteger(indexBytes) ||
+    !Number.isSafeInteger(jsonBytes) ||
+    (indexCount === 0 && indexWidth !== 0) ||
+    (indexCount > 0 && indexWidth !== 2 && indexWidth !== 4) ||
+    indexBytes !== indexCount * indexWidth ||
+    vertexBytes !== vertexCount * stride ||
+    digest.length === 0
+  ) {
+    return failure(
+      'mesh-bin-header-invalid',
+      sourceKey,
+      'safe v4 projection, stride, cardinality, and payload byte lengths',
+      `projection=${projectionVersion}; mask=${mask}; stride=${stride}; vertexBytes=${vertexBytes}; indexBytes=${indexBytes}; digest=${digest}`,
+    );
+  }
+  return {
+    ok: true,
+    value: {
+      version: 4,
+      projectionVersion: 1,
+      mask,
+      digest,
+      stride,
+      vertexCount,
+      vertexBytes,
+      indexCount,
+      indexWidth: indexWidth as 0 | 2 | 4,
+      indexBytes,
+      jsonBytes,
+    },
+  };
+}

package/src/native-cooker-registry.ts

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto';
+import type {
+  ArtifactDescriptor,
+  AssetCodec,
+  AssetStageError,
+  CookProduct,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface NativeCookArtifact {
+  readonly mediaType: string;
+  readonly assetCodec?: AssetCodec;
+  readonly bytes: Uint8Array;
+}
+
+export interface NativeCookDraft<P = unknown> {
+  readonly guid: string;
+  readonly payload: P;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, NativeCookArtifact>>;
+  readonly inputFingerprint: string;
+}
+
+export interface NativeCooker<P = unknown, I = unknown> {
+  readonly key: string;
+  readonly discover?: (input: unknown) => I | Promise<I>;
+  cook(input: I): NativeCookDraft<P> | Promise<NativeCookDraft<P>>;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (value instanceof Uint8Array) return Buffer.from(value).toString('base64');
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nested]) => [key, canonicalize(nested)]),
+  );
+}
+
+function digestDraft<P>(draft: NativeCookDraft<P>): string {
+  const bytes = JSON.stringify(
+    canonicalize({
+      guid: draft.guid,
+      payload: draft.payload,
+      refs: draft.refs,
+      artifacts: draft.artifacts,
+    }),
+  );
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+type NativeCookErrorDetail = Extract<
+  AssetStageError['detail'],
+  { readonly guid: string; readonly producer: string }
+>;
+
+function failure(key: string, detail: NativeCookErrorDetail): Result<never, AssetStageError> {
+  return err({
+    stage: 'native-cook',
+    code: 'native-cook-failed',
+    expected: 'a registered native cooker to produce a complete draft',
+    hint: 'register the cooker or repair its draft, then rerun recovery',
+    detail,
+    recovery: { action: `rerun native cooker ${key}`, retryable: true },
+  });
+}
+
+/** Injectable build-time table for native authored Pack producers. */
+export class NativeCookerRegistry {
+  private readonly cookers = new Map<string, NativeCooker>();
+
+  register(cooker: NativeCooker): void {
+    if (typeof cooker.key !== 'string' || cooker.key.length === 0) {
+      throw new TypeError('NativeCookerRegistry.register: key must be a non-empty string');
+    }
+    if (typeof cooker.cook !== 'function') {
+      throw new TypeError(`NativeCookerRegistry.register: cooker ${cooker.key} must expose cook`);
+    }
+    this.cookers.set(cooker.key, cooker);
+  }
+
+  get(key: string): NativeCooker | undefined {
+    return this.cookers.get(key);
+  }
+
+  registeredCookers(): readonly string[] {
+    return [...this.cookers.keys()];
+  }
+
+  async runDraft<P = unknown, I = unknown>(
+    key: string,
+    input: I,
+  ): Promise<Result<NativeCookDraft<P>, AssetStageError>> {
+    const cooker = this.cookers.get(key) as NativeCooker<P, I> | undefined;
+    if (cooker === undefined) {
+      return failure(key, { guid: 'unknown', producer: key });
+    }
+    let draft: NativeCookDraft<P>;
+    try {
+      const typedInput = cooker.discover === undefined ? input : await cooker.discover(input);
+      draft = await cooker.cook(typedInput);
+    } catch (error) {
+      return failure(key, { guid: 'unknown', producer: String(error) });
+    }
+    if (
+      draft.guid.length === 0 ||
+      draft.inputFingerprint.length === 0 ||
+      !Array.isArray(draft.refs) ||
+      typeof draft.payload !== 'object' ||
+      draft.payload === null ||
+      typeof draft.artifacts !== 'object' ||
+      draft.artifacts === null ||
+      Object.entries(draft.artifacts).some(
+        ([, artifact]) =>
+          artifact === null ||
+          typeof artifact !== 'object' ||
+          typeof artifact.mediaType !== 'string' ||
+          artifact.mediaType.length === 0 ||
+          !(artifact.bytes instanceof Uint8Array),
+      )
+    ) {
+      return failure(key, { guid: draft.guid || 'unknown', producer: key });
+    }
+    return ok(draft);
+  }
+
+  async run<P = unknown, I = unknown>(
+    key: string,
+    input: I,
+  ): Promise<Result<CookProduct<P>, AssetStageError>> {
+    const draftResult = await this.runDraft<P, I>(key, input);
+    if (!draftResult.ok) return draftResult;
+    const draft = draftResult.value;
+    const digest = digestDraft(draft);
+    const artifacts: Record<string, ArtifactDescriptor> = {};
+    for (const [path, artifact] of Object.entries(draft.artifacts)) {
+      artifacts[path] = {
+        path,
+        mediaType: artifact.mediaType,
+        ...(artifact.assetCodec === undefined ? {} : { assetCodec: artifact.assetCodec }),
+        byteLength: artifact.bytes.byteLength,
+      };
+    }
+    const receipt = {
+      guid: draft.guid,
+      origin: 'authoredPack' as const,
+      status: 'succeeded' as const,
+      inputFingerprint: draft.inputFingerprint,
+      outputDigest: digest,
+    };
+    const product: CookProduct<P> = {
+      guid: draft.guid,
+      payload: draft.payload,
+      refs: draft.refs,
+      artifacts,
+      digest,
+      receipt,
+    };
+    return ok(product);
+  }
+}

package/src/native-cooker.ts

@@ -0,0 +1,2 @@
+/** Node/build-time native cooker registry. The browser-safe pack root excludes this seam. */
+export * from './native-cooker-registry.js';