@call-me-sensei/toonlab 0.4.21 → 0.4.22

package/src/rockgen/rockDocument.js

@@ -19,12 +19,13 @@ import {
   resolveRockgenPreset,
 } from './rockgenPresets.js';
 import { compileDocument } from './sdf/fieldCompiler.js';
+import { resolveC7Projection } from './surface/c7GeologySurface.js';
 
 /** Document type tag stamped on saved rockgen project JSON. */
 export const ROCKGEN_PROJECT_DOCUMENT_TYPE = 'toonlab/rockgen-project';
 
 /** Current schema version for rockgen project documents. */
-export const ROCKGEN_PROJECT_SCHEMA_VERSION = 6;
+export const ROCKGEN_PROJECT_SCHEMA_VERSION = 7;
 
 /** Sparse source-mesh edits are packed into the portable document so normal
  * sculpting remains below the hosted creation-document limit. Runtime state
@@ -72,6 +73,26 @@ function lodTrianglesOption(value, targetTriangles, lodRatios) {
 
 function surfacePackageOption(value) {
   if (!value || typeof value !== 'object') return null;
+  const c8SurfaceVersion = Number(value.version);
+  if (value.schema === 'toonlab/c8-first12-geology-surface'
+    && (c8SurfaceVersion === 1 || c8SurfaceVersion === 2)) {
+    const assetId = String(value.assetId ?? '').trim();
+    const geometrySha256 = String(value.geometrySha256 ?? '').toLowerCase();
+    const profileId = String(value.profileId ?? '').trim();
+    const mapResolution = Math.round(Number(value.mapResolution));
+    if (!assetId || !profileId || !/^[a-f0-9]{64}$/u.test(geometrySha256)
+      || !Number.isInteger(mapResolution) || mapResolution < 1024 || mapResolution > 4096) return null;
+    return {
+      ...structuredClone(value),
+      assetId,
+      geometrySha256,
+      mapResolution,
+      profileId,
+      schema: 'toonlab/c8-first12-geology-surface',
+      seed: Math.round(Number(value.seed) || 0) >>> 0,
+      version: c8SurfaceVersion,
+    };
+  }
   if (value.schema !== 'toonlab/c7-geology-surface' || Number(value.version) !== 1) return null;
   const geology = String(value.geology ?? '').trim();
   if (!geology) return null;
@@ -85,6 +106,146 @@ function surfacePackageOption(value) {
   };
 }
 
+const SHA256_CONTENT_HASH = /^sha256:[0-9a-f]{64}$/u;
+
+function contentHashOption(value) {
+  return SHA256_CONTENT_HASH.test(value ?? '') ? value : null;
+}
+
+function customMeshArtifactOption(value, role) {
+  if (!value || typeof value !== 'object' || value.role !== role) return null;
+  if (value.mimeType !== 'model/gltf-binary' || value.unit !== 'metre'
+    || Number(value.metreUnitScale) !== 1 || value.coordinateSystem !== 'right-handed-y-up') return null;
+  const dimensionsMetres = vector3Option(value.dimensionsMetres, [0, 0, 0]);
+  const min = vector3Option(value.boundsMetres?.min, [0, 0, 0]);
+  const max = vector3Option(value.boundsMetres?.max, [0, 0, 0]);
+  const contentHash = contentHashOption(value.contentHash);
+  const topologyHash = contentHashOption(value.topologyHash);
+  const uri = String(value.uri ?? '').trim();
+  const id = String(value.id ?? '').trim();
+  const byteLength = positiveInteger(value.byteLength, 0);
+  const geometryAudit = {
+    meshVertexCounts: Array.isArray(value.geometryAudit?.meshVertexCounts)
+      ? value.geometryAudit.meshVertexCounts.map((entry) => positiveInteger(entry, 0))
+      : [],
+    topologyHash: contentHashOption(value.geometryAudit?.topologyHash),
+    triangleCount: positiveInteger(value.geometryAudit?.triangleCount, 0),
+    vertexCount: positiveInteger(value.geometryAudit?.vertexCount, 0),
+  };
+  if (!contentHash || !topologyHash || !uri.toLowerCase().endsWith('.glb')
+    || !id || byteLength < 20
+    || dimensionsMetres.some((entry) => entry <= 0)
+    || !min.every((entry, axis) => entry < max[axis])
+    || !dimensionsMetres.every((entry, axis) => (
+      Math.abs(entry - (max[axis] - min[axis])) <= Math.max(1e-6, entry * 1e-5)
+    ))
+    || geometryAudit.topologyHash !== topologyHash
+    || geometryAudit.vertexCount < 4 || geometryAudit.triangleCount < 4
+    || geometryAudit.meshVertexCounts.length === 0
+    || geometryAudit.meshVertexCounts.some((entry) => entry <= 0)) return null;
+  return {
+    boundsMetres: { max, min },
+    byteLength,
+    contentHash,
+    coordinateSystem: 'right-handed-y-up',
+    dimensionsMetres,
+    geometryAudit: { ...geometryAudit, topologyHash },
+    id,
+    metreUnitScale: 1,
+    mimeType: 'model/gltf-binary',
+    role,
+    sourceRevision: positiveInteger(value.sourceRevision, 1),
+    topologyHash,
+    unit: 'metre',
+    uri,
+  };
+}
+
+function identityLandmarksOption(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const id = String(entry?.id ?? '').trim();
+    if (!id) return [];
+    return [{
+      id,
+      positionMetres: vector3Option(entry.positionMetres, [0, 0, 0]),
+      role: String(entry.role ?? 'identity').trim(),
+    }];
+  });
+}
+
+function semanticRegionsOption(value, landmarkIds) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const id = String(entry?.id ?? '').trim();
+    const attribute = String(entry?.selector?.attribute ?? '').trim();
+    const selectorValue = Math.round(Number(entry?.selector?.value));
+    if (!id || !/^_[A-Z0-9_]+$/u.test(attribute) || !Number.isInteger(selectorValue) || selectorValue < 0) return [];
+    return [{
+      id,
+      label: String(entry.label ?? id),
+      landmarkIds: Array.isArray(entry.landmarkIds)
+        ? entry.landmarkIds.map(String).filter((landmarkId) => landmarkIds.has(landmarkId))
+        : [],
+      role: String(entry.role ?? 'primary-mass'),
+      selector: { attribute, kind: 'gltf-attribute', value: selectorValue },
+    }];
+  });
+}
+
+function customMeshSourceOption(value, identityLandmarks) {
+  if (!value || value.schema !== 'toonlab/c8-custom-mesh-source' || Number(value.version) !== 1) return null;
+  if (value.authority !== 'toonlab-editable-control-plus-retained-high') return null;
+  const control = customMeshArtifactOption(value.control, 'editable-control');
+  const highDetail = customMeshArtifactOption(value.highDetail, 'retained-high-detail');
+  if (!control || !highDetail || !control.id || !highDetail.id || control.id === highDetail.id
+    || control.contentHash === highDetail.contentHash
+    || control.geometryAudit.meshVertexCounts.some((entry) => entry <= 0)
+    || highDetail.geometryAudit.meshVertexCounts.some((entry) => entry <= 0)
+    || control.geometryAudit.meshVertexCounts.reduce((sum, entry) => sum + entry, 0) !== control.geometryAudit.vertexCount
+    || highDetail.geometryAudit.meshVertexCounts.reduce((sum, entry) => sum + entry, 0) !== highDetail.geometryAudit.vertexCount
+    || highDetail.geometryAudit.vertexCount <= control.geometryAudit.vertexCount
+    || highDetail.geometryAudit.triangleCount <= control.geometryAudit.triangleCount
+    || control.byteLength < 20 || highDetail.byteLength < 20) return null;
+  const landmarkIds = new Set(identityLandmarks.map((landmark) => landmark.id));
+  if (landmarkIds.size < 3 || landmarkIds.size !== identityLandmarks.length) return null;
+  const semanticRegions = semanticRegionsOption(value.semanticRegions, landmarkIds);
+  const maximumDisplacementMetres = Number(value.editEnvelope?.maximumDisplacementMetres);
+  const maximumVariationStrength = Number(value.editEnvelope?.maximumVariationStrength);
+  const semanticRegionIds = new Set(semanticRegions.map((region) => region.id));
+  const semanticSelectors = new Set(semanticRegions.map((region) => `${region.selector.attribute}:${region.selector.value}`));
+  const supportToleranceMetres = Math.max(...control.dimensionsMetres) * 1e-5;
+  const highCorrespondenceToleranceMetres = Math.max(...control.dimensionsMetres) * 0.05;
+  if (semanticRegions.length < 3 || semanticRegionIds.size !== semanticRegions.length
+    || semanticSelectors.size !== semanticRegions.length
+    || !semanticRegions.some((region) => region.role === 'base-support')
+    || Math.abs(control.boundsMetres.min[1]) > Math.max(1e-6, supportToleranceMetres)
+    || ['min', 'max'].some((key) => control.boundsMetres[key].some((entry, axis) => (
+      Math.abs(entry - highDetail.boundsMetres[key][axis]) > highCorrespondenceToleranceMetres
+    )))
+    || !Number.isFinite(maximumDisplacementMetres)
+    || maximumDisplacementMetres <= 0 || !Number.isFinite(maximumVariationStrength)
+    || maximumVariationStrength <= 0 || maximumVariationStrength > 1) return null;
+  return {
+    authority: 'toonlab-editable-control-plus-retained-high',
+    control,
+    editEnvelope: {
+      maximumDisplacementMetres,
+      maximumVariationStrength,
+      mode: 'bounded-source-space',
+    },
+    highDetail,
+    schema: 'toonlab/c8-custom-mesh-source',
+    semanticRegions,
+    version: 1,
+  };
+}
+
+export function isRockSourceMeshReference(reference) {
+  return reference?.sourceMode === 'mesh-template'
+    || Boolean(reference?.sourceMode === 'c8-custom-mesh' && reference.customMeshSource);
+}
+
 function bytesToBase64(bytes) {
   let binary = '';
   const chunkSize = 0x8000;
@@ -101,9 +262,13 @@ function base64ToBytes(value) {
   return bytes;
 }
 
-function unpackMeshEdits(value) {
-  if (!value || typeof value !== 'object' || value.encoding !== ROCKGEN_MESH_EDIT_ENCODING) return [];
-  if (typeof value.data !== 'string' || value.data.length === 0) return [];
+function unpackMeshEdits(value, { strict = false } = {}) {
+  if (value === null || value === undefined) return [];
+  if (typeof value !== 'object' || value.encoding !== ROCKGEN_MESH_EDIT_ENCODING
+    || typeof value.data !== 'string' || value.data.length === 0) {
+    if (strict) throw new Error('C8 packed mesh edits require the exact supported encoding and non-empty data.');
+    return [];
+  }
   try {
     const bytes = base64ToBytes(value.data);
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -120,30 +285,73 @@ function unpackMeshEdits(value) {
       offset += 4;
       return result;
     };
-    const operationCount = Math.min(readUint32(), ROCKGEN_MAX_MESH_EDIT_OPERATIONS);
+    const operationCount = readUint32();
+    if (operationCount > ROCKGEN_MAX_MESH_EDIT_OPERATIONS) throw new Error('operation count exceeds the portable limit');
+    if (value.operationCount !== undefined && Number(value.operationCount) !== operationCount) {
+      throw new Error('operation count metadata does not match the packed stream');
+    }
     const edits = [];
-    let remaining = ROCKGEN_MAX_MESH_EDIT_DELTAS;
-    for (let operationIndex = 0; operationIndex < operationCount && remaining > 0; operationIndex += 1) {
+    let totalDeltaCount = 0;
+    for (let operationIndex = 0; operationIndex < operationCount; operationIndex += 1) {
       const meshIndex = readUint32();
       const storedDeltaCount = readUint32();
-      const keptDeltaCount = Math.min(storedDeltaCount, remaining);
+      if (storedDeltaCount === 0 || totalDeltaCount + storedDeltaCount > ROCKGEN_MAX_MESH_EDIT_DELTAS) {
+        throw new Error('delta count is empty or exceeds the portable limit');
+      }
       const deltas = [];
       for (let deltaIndex = 0; deltaIndex < storedDeltaCount; deltaIndex += 1) {
         const delta = [readUint32(), readFloat32(), readFloat32(), readFloat32()];
-        if (deltaIndex < keptDeltaCount) deltas.push(delta);
+        if (!delta.slice(1).every(Number.isFinite)) throw new Error('packed delta contains a non-finite value');
+        deltas.push(delta);
       }
-      if (deltas.length > 0) edits.push({ deltas, meshIndex });
-      remaining -= deltas.length;
+      edits.push({ deltas, meshIndex });
+      totalDeltaCount += deltas.length;
+    }
+    if (value.deltaCount !== undefined && Number(value.deltaCount) !== totalDeltaCount) {
+      throw new Error('delta count metadata does not match the packed stream');
+    }
+    if (offset !== view.byteLength) {
+      throw new Error('packed mesh-edit stream contains trailing bytes');
     }
     return edits;
-  } catch {
+  } catch (error) {
+    if (strict) throw new Error(`Invalid C8 packed mesh edits: ${error.message}`);
     return [];
   }
 }
 
-function meshEditsOption(value, packedValue = null) {
-  const source = Array.isArray(value) ? value : unpackMeshEdits(packedValue);
+function meshEditsOption(value, packedValue = null, { strict = false } = {}) {
+  if (strict && Array.isArray(value) && packedValue) {
+    throw new Error('C8 mesh edits must use either the unpacked or packed representation, never both.');
+  }
+  const source = Array.isArray(value) ? value : unpackMeshEdits(packedValue, { strict });
   if (!Array.isArray(source)) return [];
+  if (strict) {
+    if (source.length > ROCKGEN_MAX_MESH_EDIT_OPERATIONS) {
+      throw new Error('C8 sparse sculpt history exceeds the portable operation limit.');
+    }
+    let deltaCount = 0;
+    return source.map((entry) => {
+      if (!entry || typeof entry !== 'object' || !Array.isArray(entry.deltas) || entry.deltas.length === 0
+        || !Number.isInteger(entry.meshIndex) || entry.meshIndex < 0) {
+        throw new Error('C8 mesh edits require a non-negative integer mesh index and non-empty delta array.');
+      }
+      const deltas = entry.deltas.map((delta) => {
+        if (!Array.isArray(delta) || delta.length !== 4
+          || !Number.isInteger(delta[0]) || delta[0] < 0
+          || !delta.slice(1).every(Number.isFinite)
+          || (delta[1] === 0 && delta[2] === 0 && delta[3] === 0)) {
+          throw new Error('C8 mesh edits require exact [vertexIndex, x, y, z] finite non-zero deltas.');
+        }
+        deltaCount += 1;
+        if (deltaCount > ROCKGEN_MAX_MESH_EDIT_DELTAS) {
+          throw new Error('C8 sparse sculpt history exceeds the portable delta limit.');
+        }
+        return [delta[0], Number(delta[1]), Number(delta[2]), Number(delta[3])];
+      });
+      return { deltas, meshIndex: entry.meshIndex };
+    });
+  }
   let remaining = ROCKGEN_MAX_MESH_EDIT_DELTAS;
   return source.slice(-ROCKGEN_MAX_MESH_EDIT_OPERATIONS).flatMap((entry) => {
     if (remaining <= 0) return [];
@@ -167,6 +375,249 @@ function meshEditsOption(value, packedValue = null) {
   });
 }
 
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJsonValue).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJsonValue(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function fnv1a64(value) {
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= BigInt(value.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+/** Deterministic browser-safe identity for the complete saved C8 control/high/semantic authority. */
+export function createC8ReferenceAuthoritySourceId(reference) {
+  if (reference?.sourceMode !== 'c8-custom-mesh' || !reference.customMeshSource) return null;
+  return `c8-authority-v1:fnv1a64:${fnv1a64(stableJsonValue(reference.customMeshSource))}`;
+}
+
+/** Deterministic browser-safe identity for the exact live C8 control geometry. */
+export function createC8ReferenceGeometrySourceId(reference) {
+  if (reference?.sourceMode !== 'c8-custom-mesh' || !reference.customMeshSource?.control) return null;
+  const payload = {
+    authoritySourceId: createC8ReferenceAuthoritySourceId(reference),
+    controlContentHash: reference.customMeshSource.control.contentHash,
+    controlTopologyHash: reference.customMeshSource.control.topologyHash,
+    meshEdits: reference.meshEdits ?? [],
+    variation: Number(reference.variation) || 0,
+    variationSeed: Math.round(Number(reference.variationSeed) || 0) >>> 0,
+  };
+  return `c8-geometry-v2:fnv1a64:${fnv1a64(stableJsonValue(payload))}`;
+}
+
+/** Surface derivative identity, separate from geometry and explicit about the C7 recipe. */
+export function createC8ReferenceSurfaceSourceId(reference) {
+  if (reference?.sourceMode !== 'c8-custom-mesh') return null;
+  const payload = {
+    authoritySourceId: createC8ReferenceAuthoritySourceId(reference),
+    geometrySourceId: reference.geometrySourceId ?? createC8ReferenceGeometrySourceId(reference),
+    geology: String(reference.geology ?? ''),
+    surfaceMode: reference.surfaceMode === 'generated' ? 'generated' : 'source',
+    surfacePackage: reference.surfacePackage ?? null,
+    topFinish: reference.topFinish ?? 'source',
+  };
+  return `c8-surface-v1:fnv1a64:${fnv1a64(stableJsonValue(payload))}`;
+}
+
+function c8SurfaceReprojectionOption(value, {
+  authoritySourceId,
+  controlContentHash,
+  geometrySourceId,
+  geology,
+  meshEditCount,
+  sourceId,
+  sourceRevision,
+  surfacePackage,
+  surfaceSourceId,
+}) {
+  if (value === null || value === undefined) return null;
+  if (!value || typeof value !== 'object'
+    || value.schema !== 'toonlab/c8-surface-reprojection'
+    || Number(value.version) !== 1
+    || value.method !== 'deterministic-metre-triplanar-map-reprojection'
+    || value.trueHighToLowBake !== false) {
+    throw new Error('C8 surface reprojection metadata must use the deterministic metre-triplanar schema and can never claim a true high-to-low bake.');
+  }
+  if (Number(value.sourceRevision) !== sourceRevision) {
+    throw new Error('C8 surface reprojection metadata is stale for the saved source revision.');
+  }
+  if (value.controlContentHash && value.controlContentHash !== controlContentHash) {
+    throw new Error('C8 surface reprojection metadata is stale for the admitted control GLB.');
+  }
+  if (value.geometrySourceId && value.geometrySourceId !== geometrySourceId) {
+    throw new Error('C8 surface reprojection metadata is stale for the saved geometry content ID.');
+  }
+  if (value.authoritySourceId && value.authoritySourceId !== authoritySourceId) {
+    throw new Error('C8 surface reprojection metadata is stale for the complete control/high authority.');
+  }
+  if (value.surfaceSourceId && value.surfaceSourceId !== surfaceSourceId) {
+    throw new Error('C8 surface reprojection metadata is stale for the saved surface recipe.');
+  }
+  const dimensionsMetres = vector3Option(value.dimensionsMetres ?? value.projection?.dimensionsMetres, [0, 0, 0]);
+  if (dimensionsMetres.some((entry) => entry <= 0)) throw new Error('C8 surface reprojection requires positive metre dimensions.');
+  const projection = value.projection;
+  const scaleMetres = Number(projection?.scaleMetres);
+  const axisScale = vector3Option(projection?.axisScale, [0, 0, 0]);
+  if (projection?.mode !== 'world-metre-triplanar-isotropic'
+    || !Number.isFinite(scaleMetres) || scaleMetres <= 0
+    || axisScale.some((entry) => Math.abs(entry - scaleMetres) > 1e-9)) {
+    throw new Error('C8 surface reprojection must remain metre-isotropic on all three axes.');
+  }
+  const expectedProjection = resolveC7Projection({ dimensionsMetres, geology });
+  if (stableJsonValue(projection) !== stableJsonValue(expectedProjection)) {
+    throw new Error('C8 surface reprojection projection must be deterministically derived from its saved metre dimensions and geology.');
+  }
+  const mapResolution = Math.round(Number(value.mapResolution));
+  if (!Number.isInteger(mapResolution) || mapResolution < 32 || mapResolution > 2048) {
+    throw new Error('C8 surface reprojection resolution must be between 32 and 2048.');
+  }
+  const resolvedGeology = String(value.geology ?? '').trim();
+  if (!resolvedGeology || resolvedGeology !== geology) throw new Error('C8 surface reprojection geology does not match its saved surface package.');
+  const resolvedSeed = Math.round(Number(value.seed) || 0) >>> 0;
+  if (!surfacePackage || surfacePackage.geology !== resolvedGeology
+    || surfacePackage.mapResolution !== mapResolution || surfacePackage.seed !== resolvedSeed) {
+    throw new Error('C8 surface reprojection must exactly match the saved C7 geology surface package.');
+  }
+  const record = {
+    authoritySourceId,
+    controlContentHash,
+    dimensionsMetres,
+    editOperationCount: meshEditCount,
+    geology: resolvedGeology,
+    geometrySourceId,
+    mapResolution,
+    method: 'deterministic-metre-triplanar-map-reprojection',
+    projection: structuredClone(expectedProjection),
+    schema: 'toonlab/c8-surface-reprojection',
+    seed: resolvedSeed,
+    sourceContentId: geometrySourceId,
+    sourceId,
+    sourceRevision,
+    surfaceSourceId,
+    trueHighToLowBake: false,
+    version: 1,
+  };
+  return { ...record, reprojectionContentId: `c8-reprojection-v1:fnv1a64:${fnv1a64(stableJsonValue(record))}` };
+}
+
+function portableDerivedArtifactState(value, {
+  authoritySourceId,
+  customMeshSource,
+  geometrySourceId,
+  sourceRevision,
+  surfaceReprojection,
+  surfaceSourceId,
+}) {
+  const source = value && typeof value === 'object' ? value : {};
+  const result = {};
+  for (const role of ['collision', 'geometricResidual', 'lods', 'pbrBake', 'runtimePackage']) {
+    const entry = source[role] && typeof source[role] === 'object' ? source[role] : {};
+    const status = entry.status === 'current' ? 'current' : 'stale';
+    if (status === 'current') {
+      const boundGeometryId = entry.geometrySourceId ?? entry.sourceGeometryContentId ?? entry.sourceContentId;
+      if (boundGeometryId !== geometrySourceId || !contentHashOption(entry.contentHash)
+        || entry.authoritySourceId !== authoritySourceId
+        || Number(entry.sourceRevision) !== sourceRevision) {
+        throw new Error(`Current C8 ${role} metadata must carry a content hash bound to the exact geometry source ID.`);
+      }
+      if (['pbrBake', 'runtimePackage'].includes(role) && entry.surfaceSourceId !== surfaceSourceId) {
+        throw new Error(`Current C8 ${role} metadata must be bound to the exact surface recipe ID.`);
+      }
+      if (role === 'pbrBake' && (entry.method !== 'blender-high-to-low-bake'
+        || entry.trueHighToLowBake !== true
+        || entry.highDetailContentHash !== customMeshSource.highDetail.contentHash)) {
+        throw new Error('A current C8 PBR bake must be an explicit Blender high-to-low bake bound to the retained high-detail GLB.');
+      }
+      if (role === 'geometricResidual' && (entry.method !== 'blender-signed-high-to-lod-residual'
+        || entry.highDetailContentHash !== customMeshSource.highDetail.contentHash)) {
+        throw new Error('A current C8 geometric residual must be an explicit Blender signed high-to-LOD residual bound to the retained high-detail GLB.');
+      }
+    }
+    result[role] = {
+      authoritySourceId,
+      contentHash: contentHashOption(entry.contentHash),
+      geometrySourceId,
+      reason: String(entry.reason ?? (status === 'current' ? 'verified-derived-artifact' : 'geometry-source-not-baked')),
+      sourceRevision,
+      status,
+      ...(['pbrBake', 'runtimePackage'].includes(role) ? { surfaceSourceId } : {}),
+      ...(role === 'pbrBake' && status === 'current' ? {
+        highDetailContentHash: customMeshSource.highDetail.contentHash,
+        method: 'blender-high-to-low-bake',
+        trueHighToLowBake: true,
+      } : {}),
+      ...(role === 'geometricResidual' && status === 'current' ? {
+        highDetailContentHash: customMeshSource.highDetail.contentHash,
+        method: 'blender-signed-high-to-lod-residual',
+      } : {}),
+    };
+  }
+  result.surfaceReprojection = surfaceReprojection
+    ? {
+        authoritySourceId,
+        contentHash: surfaceReprojection.reprojectionContentId,
+        geometrySourceId,
+        method: surfaceReprojection.method,
+        sourceRevision,
+        status: 'current',
+        surfaceSourceId,
+        trueHighToLowBake: false,
+      }
+    : {
+        authoritySourceId,
+        contentHash: null,
+        geometrySourceId,
+        reason: 'geometry-source-not-reprojected',
+        sourceRevision,
+        status: 'stale',
+        surfaceSourceId,
+        trueHighToLowBake: false,
+      };
+  return result;
+}
+
+function validateC8MeshEditSequence(meshEdits, customMeshSource) {
+  const maximumDisplacementMetres = customMeshSource.editEnvelope.maximumDisplacementMetres;
+  const meshVertexCounts = customMeshSource.control.geometryAudit.meshVertexCounts;
+  const accumulated = new Map();
+  let deltaCount = 0;
+  for (const edit of meshEdits) {
+    const meshVertexCount = meshVertexCounts[edit.meshIndex];
+    if (!Number.isInteger(meshVertexCount)) {
+      throw new Error(`C8 sparse sculpt references missing control mesh ${edit.meshIndex}.`);
+    }
+    const operationVertices = new Set();
+    for (const [vertexIndex, x, y, z] of edit.deltas) {
+      if (vertexIndex >= meshVertexCount) {
+        throw new Error(`C8 sparse sculpt references missing vertex ${vertexIndex} on control mesh ${edit.meshIndex}.`);
+      }
+      if (operationVertices.has(vertexIndex)) {
+        throw new Error('C8 sparse sculpt operations may target each vertex only once.');
+      }
+      operationVertices.add(vertexIndex);
+      deltaCount += 1;
+      const key = `${edit.meshIndex}:${vertexIndex}`;
+      const prior = accumulated.get(key) ?? [0, 0, 0];
+      const next = [prior[0] + x, prior[1] + y, prior[2] + z];
+      if (Math.hypot(...next) > maximumDisplacementMetres + 1e-9) {
+        throw new Error(`C8 sparse sculpt history exceeds the ${maximumDisplacementMetres} metre edit envelope.`);
+      }
+      accumulated.set(key, next);
+    }
+  }
+  if (meshEdits.length > ROCKGEN_MAX_MESH_EDIT_OPERATIONS || deltaCount > ROCKGEN_MAX_MESH_EDIT_DELTAS) {
+    throw new Error('C8 sparse sculpt history exceeds the portable operation or delta limit.');
+  }
+  return meshEdits;
+}
+
 function packMeshEdits(value) {
   const edits = meshEditsOption(value);
   if (edits.length === 0) return null;
@@ -203,14 +654,22 @@ function packMeshEdits(value) {
 
 /**
  * Portable identity for a source-GLB project. Geometry stays outside the JSON
- * document; the document stores only the stable catalog id, deterministic
- * generation/deformation seed, and exact LOD contract needed to rebuild and
- * decode the first-party GLB source.
+ * document; the document stores either the stable catalog id or the exact C8
+ * control/high hashes, plus deterministic edit state needed to rebuild and
+ * decode the source GLB.
  */
 export function createRockReferenceIdentity(options = null) {
   if (!options || typeof options !== 'object') return null;
+  const c8Intent = options.sourceMode === 'c8-custom-mesh'
+    || (options.customMeshSource !== null && options.customMeshSource !== undefined);
   const id = String(options.id ?? '').trim();
-  if (!id) return null;
+  if (!id) {
+    if (c8Intent) throw new Error('C8 custom-mesh documents require a stable source ID.');
+    return null;
+  }
+  if (c8Intent && options.sourceMode !== 'c8-custom-mesh') {
+    throw new Error('A C8 custom-mesh manifest cannot silently downgrade to a legacy mesh-template reference.');
+  }
   const lodRatios = lodRatiosOption(options.lodRatios);
   const lodTriangles = lodTrianglesOption(
     options.lodTriangles,
@@ -221,6 +680,97 @@ export function createRockReferenceIdentity(options = null) {
     .includes(options.topFinish)
     ? options.topFinish
     : 'source';
+  const identityLandmarks = identityLandmarksOption(options.identityLandmarks);
+  const customMeshSource = customMeshSourceOption(options.customMeshSource, identityLandmarks);
+  if (options.sourceMode === 'c8-custom-mesh' && !customMeshSource) {
+    throw new Error('C8 custom-mesh documents require valid content-bound control/high GLBs, landmarks, semantic regions, and edit bounds.');
+  }
+  if (options.sourceMode === 'c8-custom-mesh'
+    && !String(options.geology ?? options.surfacePackage?.geology ?? '').trim()) {
+    throw new Error('C8 custom-mesh documents require an explicit geology surface profile.');
+  }
+  const sourceMode = options.sourceMode === 'c8-custom-mesh' && customMeshSource
+    ? 'c8-custom-mesh'
+    : 'mesh-template';
+  const sourceRevision = positiveInteger(options.sourceRevision, 1);
+  if (sourceMode === 'c8-custom-mesh'
+    && (customMeshSource.control.sourceRevision > sourceRevision
+      || customMeshSource.highDetail.sourceRevision > sourceRevision)) {
+    throw new Error('C8 control/high artifacts cannot claim a future source revision.');
+  }
+  const surfacePackage = surfacePackageOption(options.surfacePackage);
+  const geology = String(options.geology ?? options.surfacePackage?.geology ?? '').trim();
+  if (sourceMode === 'c8-custom-mesh' && (!surfacePackage || surfacePackage.geology !== geology)) {
+    throw new Error('C8 custom-mesh documents require one exact saved C7 geology surface package.');
+  }
+  let meshEdits = meshEditsOption(options.meshEdits, options.meshEditsPacked, {
+    strict: sourceMode === 'c8-custom-mesh',
+  });
+  if (sourceMode === 'c8-custom-mesh') {
+    meshEdits = meshEdits.map((edit) => ({
+      ...edit,
+      deltas: edit.deltas.map(([vertexIndex, x, y, z]) => [vertexIndex, Math.fround(x), Math.fround(y), Math.fround(z)]),
+    }));
+    validateC8MeshEditSequence(meshEdits, customMeshSource);
+  }
+  const maximumVariationStrength = sourceMode === 'c8-custom-mesh'
+    ? customMeshSource.editEnvelope.maximumVariationStrength
+    : 1;
+  const variation = Math.min(Math.max(Number(options.variation) || 0, 0), maximumVariationStrength);
+  const variationSeed = Math.round(Number(options.variationSeed) || 0) >>> 0;
+  const surfaceMode = options.surfaceMode === 'generated' ? 'generated' : 'source';
+  const authoritySourceId = sourceMode === 'c8-custom-mesh'
+    ? createC8ReferenceAuthoritySourceId({ customMeshSource, sourceMode })
+    : null;
+  const geometrySourceId = sourceMode === 'c8-custom-mesh'
+    ? createC8ReferenceGeometrySourceId({
+        customMeshSource,
+        meshEdits,
+        sourceMode,
+        variation,
+        variationSeed,
+      })
+    : null;
+  const surfaceSourceId = sourceMode === 'c8-custom-mesh'
+    ? createC8ReferenceSurfaceSourceId({
+        customMeshSource,
+        geology,
+        geometrySourceId,
+        sourceMode,
+        surfaceMode,
+        surfacePackage,
+        topFinish,
+      })
+    : null;
+  if (sourceMode === 'c8-custom-mesh'
+    && ((options.authoritySourceId && options.authoritySourceId !== authoritySourceId)
+      || (options.geometrySourceId && options.geometrySourceId !== geometrySourceId)
+      || (options.surfaceSourceId && options.surfaceSourceId !== surfaceSourceId))) {
+    throw new Error('Saved C8 authority, geometry, or surface identity is stale for the admitted source and edits.');
+  }
+  const surfaceReprojection = sourceMode === 'c8-custom-mesh'
+    ? c8SurfaceReprojectionOption(options.surfaceReprojection, {
+        authoritySourceId,
+        controlContentHash: customMeshSource.control.contentHash,
+        geology,
+        geometrySourceId,
+        meshEditCount: meshEdits.length,
+        sourceId: id,
+        sourceRevision,
+        surfacePackage,
+        surfaceSourceId,
+      })
+    : null;
+  const derivedArtifactState = sourceMode === 'c8-custom-mesh'
+    ? portableDerivedArtifactState(options.derivedArtifactState, {
+        authoritySourceId,
+        customMeshSource,
+        geometrySourceId,
+        sourceRevision,
+        surfaceReprojection,
+        surfaceSourceId,
+      })
+    : null;
   return {
     archetype: String(options.archetype ?? '').trim(),
     catalogVersion: positiveInteger(options.catalogVersion, 1),
@@ -230,16 +780,29 @@ export function createRockReferenceIdentity(options = null) {
       ? lodTriangles.map((triangles) => triangles / lodTriangles[0])
       : lodRatios,
     lodTriangles,
-    meshEdits: meshEditsOption(options.meshEdits, options.meshEditsPacked),
+    meshEdits,
+    ...(sourceMode === 'c8-custom-mesh' ? {
+      authoritySourceId,
+      customMeshSource,
+      derivedArtifactState,
+      geology,
+      geometrySourceId,
+      identityLandmarks,
+      label: String(options.label ?? id),
+      sourceRevision,
+      surfaceSourceId,
+      surfaceReprojection,
+      thumbnailUrl: String(options.thumbnailUrl ?? ''),
+    } : {}),
     role: String(options.role ?? '').trim(),
     series: String(options.series ?? '').trim(),
-    sourceMode: 'mesh-template',
-    surfacePackage: surfacePackageOption(options.surfacePackage),
-    surfaceMode: options.surfaceMode === 'generated' ? 'generated' : 'source',
+    sourceMode,
+    surfacePackage,
+    surfaceMode,
     targetTriangles: positiveInteger(options.targetTriangles, lodTriangles[0] ?? 0),
     topFinish,
-    variation: Math.min(Math.max(Number(options.variation) || 0, 0), 1),
-    variationSeed: Math.round(Number(options.variationSeed) || 0) >>> 0,
+    variation,
+    variationSeed,
   };
 }
 
@@ -507,7 +1070,7 @@ export function computeDocumentBounds(document) {
 /** Serializes a document to JSON (dropping the runtime `revision`). */
 export function serializeRockDocument(document, { pretty = false } = {}) {
   const { revision, ...serializable } = document;
-  if (serializable.reference?.sourceMode === 'mesh-template') {
+  if (isRockSourceMeshReference(serializable.reference)) {
     const { meshEdits, ...reference } = serializable.reference;
     serializable.reference = {
       ...reference,
@@ -526,7 +1089,8 @@ export function serializeRockDocument(document, { pretty = false } = {}) {
 // those deltas as float32 binary in portable JSON so normal sculpt sessions
 // fit the hosted creation limit. v6 adds the optional deterministic C7 surface
 // package identity used by the 480 source-mesh catalog. Existing
-// preset/custom projects remain reference-free.
+// preset/custom projects remain reference-free. v7 preserves the content-bound
+// C8 control/high GLBs, semantic regions, landmarks, and derivative state.
 const MIGRATIONS = Object.freeze([
   (document) => ({
     ...document,
@@ -571,6 +1135,20 @@ const MIGRATIONS = Object.freeze([
       : null,
     schemaVersion: 6,
   }),
+  (document) => ({
+    ...document,
+    reference: document.reference && typeof document.reference === 'object'
+      ? {
+          ...document.reference,
+          customMeshSource: document.reference.customMeshSource ?? null,
+          derivedArtifactState: document.reference.derivedArtifactState ?? null,
+          identityLandmarks: document.reference.identityLandmarks ?? [],
+          sourceRevision: document.reference.sourceRevision ?? 1,
+          surfaceReprojection: document.reference.surfaceReprojection ?? null,
+        }
+      : null,
+    schemaVersion: 7,
+  }),
 ]);
 
 /**