@forgeax/engine-assets-runtime 0.1.7 → 0.1.20

package/src/registry/instantiate.ts

@@ -78,16 +78,26 @@ function catalogEntriesForFence(registry: AssetRegistry): readonly CatalogEntry[
     if (record.sourcePath === undefined) continue;
     const candidate = { ...record, guid, sourcePath: record.sourcePath } as CatalogEntry;
     const current = byGuid.get(guid.toLowerCase());
-    if (
-      current === undefined ||
-      (current.publication === undefined && candidate.publication !== undefined)
-    ) {
+    if (current === undefined || candidate.publication !== undefined) {
+      // A persisted Scene fence is captured from the complete pack-index
+      // publication at save time. If the CatalogReplica is still carrying its
+      // previous tuple during the watcher handoff, keep the same pack-index
+      // authority here or the freshly reopened scene will reject its own
+      // mount with asset-generation-fence-mismatch.
       byGuid.set(guid.toLowerCase(), candidate);
     }
   }
   return [...byGuid.values()];
 }
 
+/** Derive a publication fence from the registry's unified live projections. */
+export function scenePublicationFenceFromRegistry(
+  registry: AssetRegistry,
+  outputGuid: string,
+): Result<ScenePublicationFence, ScenePublicationFenceError> {
+  return scenePublicationFenceFromCatalog(catalogEntriesForFence(registry), outputGuid);
+}
+
 /**
  * Post-spawn hook contract (D-1). A hook runs after instantiate spawns the
  * scene subtree; the shipped implementation is runtime's `postSpawnResolveJoints`

package/src/registry/validate-material.ts

@@ -10,6 +10,60 @@ import {
 } from '@forgeax/engine-types';
 import type { AssetRegistry } from '../asset-registry';
 
+export interface TexturePublicationStateSnapshot {
+  readonly guid: string;
+  readonly sourceKey: string;
+  readonly acceptedGeneration: number;
+  readonly acceptedDigest: string;
+  readonly candidateGeneration?: number;
+  readonly candidateFailure?: string;
+}
+
+export interface TexturePublicationState {
+  reject(candidate: {
+    readonly generation: number;
+    readonly reason: string;
+  }): TexturePublicationStateSnapshot;
+  accept(candidate: {
+    readonly generation: number;
+    readonly digest: string;
+  }): TexturePublicationStateSnapshot;
+}
+
+/** Candidate/accepted state that keeps the last known good publication honest. */
+export function createTexturePublicationState(input: {
+  readonly guid: string;
+  readonly sourceKey: string;
+  readonly generation: number;
+  readonly digest: string;
+}): TexturePublicationState {
+  let accepted = {
+    generation: input.generation,
+    digest: input.digest,
+  };
+  let candidate: { readonly generation: number; readonly reason: string } | undefined;
+  const snapshot = (): TexturePublicationStateSnapshot => ({
+    guid: input.guid,
+    sourceKey: input.sourceKey,
+    acceptedGeneration: accepted.generation,
+    acceptedDigest: accepted.digest,
+    ...(candidate === undefined
+      ? {}
+      : { candidateGeneration: candidate.generation, candidateFailure: candidate.reason }),
+  });
+  return {
+    reject(next) {
+      candidate = next;
+      return snapshot();
+    },
+    accept(next) {
+      accepted = next;
+      candidate = undefined;
+      return snapshot();
+    },
+  };
+}
+
 /**
  * Validate a MaterialAsset's passes[] against the ShaderRegistry's
  * paramSchema (union semantics: all declared params across all passes
@@ -112,6 +166,100 @@ export function validateMaterialPasses(
   return null;
 }
 
+type TransmissionParameter =
+  | 'transmission'
+  | 'ior'
+  | 'thickness'
+  | 'attenuationColor'
+  | 'attenuationDistance'
+  | 'transmissionTexture'
+  | 'thicknessTexture';
+
+function transmissionError(
+  material: string,
+  parameter: TransmissionParameter,
+  reason: 'non-finite' | 'range' | 'shape' | 'blend' | 'depth-write',
+  actual?: unknown,
+): MaterialError {
+  return createMaterialError('material-transmission-contract-invalid', {
+    code: 'material-transmission-contract-invalid',
+    material,
+    parameter,
+    reason,
+    ...(actual === undefined ? {} : { actual }),
+  });
+}
+
+function validateTransmissionNumber(
+  material: string,
+  values: Record<string, unknown>,
+  parameter: 'transmission' | 'ior' | 'thickness' | 'attenuationDistance',
+  minimum: number,
+  maximum?: number,
+): MaterialError | null {
+  const value = values[parameter];
+  if (value === undefined) return null;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return transmissionError(material, parameter, 'non-finite', value);
+  }
+  if (value < minimum || (maximum !== undefined && value > maximum)) {
+    return transmissionError(material, parameter, 'range', value);
+  }
+  return null;
+}
+
+export function validateMaterialTransmissionContract(asset: MaterialAsset): MaterialError | null {
+  const material = (asset.values?.materialName as string | undefined) ?? '<unnamed>';
+  const values = (asset.values ?? {}) as Record<string, unknown>;
+  const numericChecks: ReadonlyArray<
+    ['transmission' | 'ior' | 'thickness' | 'attenuationDistance', number, number | undefined]
+  > = [
+    ['transmission', 0, 1],
+    ['ior', 1, undefined],
+    ['thickness', 0, undefined],
+    ['attenuationDistance', Number.MIN_VALUE, undefined],
+  ];
+  for (const [parameter, minimum, maximum] of numericChecks) {
+    const error = validateTransmissionNumber(material, values, parameter, minimum, maximum);
+    if (error !== null) return error;
+  }
+  const attenuationColor = values.attenuationColor;
+  if (attenuationColor !== undefined) {
+    if (
+      !Array.isArray(attenuationColor) ||
+      attenuationColor.length !== 3 ||
+      attenuationColor.some(
+        (value) => typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1,
+      )
+    ) {
+      return transmissionError(material, 'attenuationColor', 'shape', attenuationColor);
+    }
+  }
+  for (const parameter of ['transmissionTexture', 'thicknessTexture'] as const) {
+    const value = values[parameter];
+    if (
+      value !== undefined &&
+      typeof value !== 'string' &&
+      !(typeof value === 'number' && Number.isInteger(value) && value >= 0) &&
+      (typeof value !== 'object' || value === null || Array.isArray(value))
+    ) {
+      return transmissionError(material, parameter, 'shape', value);
+    }
+  }
+  const transmission = values.transmission;
+  if (typeof transmission === 'number' && transmission > 0) {
+    for (const pass of asset.passes ?? []) {
+      if (pass.renderState?.blend !== undefined) {
+        return transmissionError(material, 'transmission', 'blend');
+      }
+      if (pass.renderState?.depthWriteEnabled === true) {
+        return transmissionError(material, 'transmission', 'depth-write');
+      }
+    }
+  }
+  return null;
+}
+
 export interface MaterialEffectiveRootIdentity {
   readonly guid: string;
   readonly layoutIdentity: string;