@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/src/evidence/source-inventory.ts

@@ -0,0 +1,193 @@
+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 { 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 {
+  readonly projectRoot: string;
+  readonly guid: string;
+}
+
+export interface ProducerSemanticIdentityInput {
+  readonly producerRoot: string;
+  readonly sourcePath: string;
+  readonly sourceDigest: string;
+  readonly schemaVersion: string;
+  readonly importer: string;
+  readonly codec: string;
+  readonly settings: unknown;
+  readonly producer: string;
+  readonly profile: string;
+  readonly declaredGuids?: readonly string[];
+}
+
+export interface ProducerRelativeDdcIdentity {
+  readonly logicalPath: string;
+  readonly sourceDigest: string;
+  readonly key: string;
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+export function producerRelativeLogicalPath(producerRoot: string, sourcePath: string): string {
+  const root = resolve(producerRoot);
+  const source = resolve(sourcePath);
+  const path = relative(root, source);
+  if (
+    path.length === 0 ||
+    path === '..' ||
+    path.startsWith(`..${sep}`) ||
+    resolve(root, path) !== source
+  ) {
+    throw new Error('producer source must be inside the injected producer root');
+  }
+  return path.split(sep).join('/');
+}
+
+export function producerRelativeDdcKey(input: ProducerSemanticIdentityInput): string {
+  const logicalPath = producerRelativeLogicalPath(input.producerRoot, input.sourcePath);
+  const semantic = {
+    schemaVersion: input.schemaVersion,
+    logicalPath,
+    sourceDigest: input.sourceDigest,
+    importer: input.importer,
+    codec: input.codec,
+    settings: stableValue(input.settings),
+    producer: input.producer,
+    profile: input.profile,
+    declaredGuids: [...(input.declaredGuids ?? [])].sort(),
+  };
+  return createHash('sha256').update(JSON.stringify(semantic)).digest('hex');
+}
+
+export function producerRelativeDdcIdentity(
+  input: ProducerSemanticIdentityInput,
+): ProducerRelativeDdcIdentity {
+  return {
+    logicalPath: producerRelativeLogicalPath(input.producerRoot, input.sourcePath),
+    sourceDigest: input.sourceDigest,
+    key: producerRelativeDdcKey(input),
+  };
+}
+
+function fingerprint(meta: string, source: Uint8Array | undefined): string {
+  const hash = createHash('sha256').update(meta);
+  if (source !== undefined) hash.update(source);
+  return hash.digest('base64');
+}
+
+function sourceFromMeta(
+  metaPath: string,
+  meta: {
+    readonly source?: unknown;
+    readonly inputFingerprint?: unknown;
+    readonly importSettings?: unknown;
+    readonly subAssets?: readonly { readonly guid?: unknown }[];
+  },
+  guid: string,
+  raw: string,
+): SourceDeclarationEvidence | undefined {
+  if (
+    !meta.subAssets?.some(
+      (asset) => typeof asset.guid === 'string' && asset.guid.toLowerCase() === guid.toLowerCase(),
+    )
+  ) {
+    return undefined;
+  }
+  const source =
+    typeof meta.source === 'string' ? meta.source : basename(metaPath).replace(/\.meta\.json$/, '');
+  const sourcePath = resolve(dirname(metaPath), source);
+  const inputFingerprint =
+    typeof meta.inputFingerprint === 'string' ? meta.inputFingerprint : fingerprint(raw, undefined);
+  return { origin: 'sourceMeta', sourcePath, inputFingerprint };
+}
+
+async function collectDeclarationPaths(root: string): Promise<string[]> {
+  const paths: string[] = [];
+  async function visit(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SCANNER_BLACKLIST.has(entry.name)) await visit(path);
+        continue;
+      }
+      if (
+        entry.isFile() &&
+        (entry.name.endsWith('.meta.json') ||
+          entry.name.endsWith('.pack.json') ||
+          entry.name.endsWith('.pack.ts'))
+      ) {
+        paths.push(path);
+      }
+    }
+  }
+  await visit(root);
+  return paths;
+}
+
+/** Read `.meta.json` or `.pack.json` source declarations without runtime imports. */
+export async function readSourceInventory(
+  request: SourceInventoryRequest,
+): Promise<SourceDeclarationEvidence | undefined> {
+  const result = await scan([request.projectRoot]);
+  const paths = result.ok ? result.value : await collectDeclarationPaths(request.projectRoot);
+  const guid = request.guid.toLowerCase();
+  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 };
+      }
+      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 }[];
+    };
+    try {
+      parsed = JSON.parse(raw) as typeof parsed;
+    } catch {
+      continue;
+    }
+    if (path.endsWith('.pack.json')) {
+      if (
+        parsed.assets?.some(
+          (asset) =>
+            typeof asset.guid === 'string' &&
+            (asset.guid === request.guid || asset.guid.toLowerCase() === guid),
+        )
+      ) {
+        authored = { origin: 'authoredPack', sourcePath: path };
+      }
+      continue;
+    }
+    if (path.endsWith('.meta.json')) {
+      const source = sourceFromMeta(path, parsed, request.guid, raw);
+      if (source !== undefined) return source;
+    }
+  }
+  return authored;
+}

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,108 @@
+// @forgeax/engine-pack
+// Disk schema, GUID tools, and browser-safe asset contracts.
+// Node-only catalog/build APIs live under @forgeax/engine-pack/build.
+
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  createMaterialCookIdentity,
+  type MaterialCookArtifact,
+  type MaterialCookIdentity,
+  type MaterialCookIdentityExpectation,
+  type MaterialCookIdentityInput,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  type MaterialCookWasmProvenance,
+  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/material-cook.ts

@@ -0,0 +1,15 @@
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  createMaterialCookIdentity,
+  type MaterialCookArtifact,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  type MaterialCookWasmProvenance,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  serializeMaterialCookReceipt,
+  validateCookedMaterialRecord,
+} from './evidence/material-cook.js';

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,
+    },
+  };
+}