diff --git a/src/GameCult.Mesh/CultMesh.cs b/src/GameCult.Mesh/CultMesh.cs
index dab5dd28..460584b6 100644
--- a/src/GameCult.Mesh/CultMesh.cs
+++ b/src/GameCult.Mesh/CultMesh.cs
@@ -380,6 +380,7 @@ namespace GameCult.Mesh
return local;
}
}
+
///
/// A locally hosted CultMesh node over CultCache, CultNet transport, and the mesh database facade.
///
@@ -680,6 +681,110 @@ namespace GameCult.Mesh
return new CultMeshStreamCatalog();
}
+ ///
+ /// Packs bytes into content-addressed CDN chunk documents and a versioned artifact manifest.
+ ///
+ public static CultMeshCdnArtifact PackCdnArtifact(
+ string artifactId,
+ byte[] payload,
+ CultMeshCdnPackOptions? options = null)
+ {
+ return CultMeshCdn.PackArtifact(artifactId, payload, options);
+ }
+
+ ///
+ /// Publishes a packed CDN artifact into a local cache.
+ ///
+ public static Task PublishCdnArtifactAsync(
+ CultCache cache,
+ CultMeshCdnArtifact artifact)
+ {
+ return CultMeshCdn.PublishAsync(cache, artifact);
+ }
+
+ ///
+ /// Publishes a packed CDN artifact into a distributed CultNet database.
+ ///
+ public static Task PublishCdnArtifactAsync(
+ CultNetDatabase database,
+ CultMeshCdnArtifact artifact)
+ {
+ return CultMeshCdn.PublishAsync(database, artifact);
+ }
+
+ ///
+ /// Reassembles and verifies a CDN artifact from a local cache.
+ ///
+ public static byte[] ReadCdnArtifact(
+ CultCache cache,
+ CultMeshCdnArtifactManifest manifest)
+ {
+ return CultMeshCdn.ReadArtifact(cache, manifest);
+ }
+
+ ///
+ /// Reassembles and verifies a CDN artifact from a distributed CultNet database.
+ ///
+ public static Task ReadCdnArtifactAsync(
+ CultNetDatabase database,
+ CultMeshCdnArtifactManifest manifest)
+ {
+ return CultMeshCdn.ReadArtifactAsync(database, manifest);
+ }
+
+ ///
+ /// Creates a CultNet document registry for CDN artifact manifests and chunks.
+ ///
+ public static CultNetDocumentRegistry CreateCdnDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ return CultMeshCdn.CreateDocumentRegistry(documents);
+ }
+
+ ///
+ /// Computes and stamps the content hash for a portable entity prefab package.
+ ///
+ public static CultMeshEntityPrefabPackage FinalizeEntityPrefabPackage(
+ CultMeshEntityPrefabPackage package)
+ {
+ return CultMeshEntityPrefabs.FinalizePackage(package);
+ }
+
+ ///
+ /// Publishes a portable entity prefab package into a local cache.
+ ///
+ public static Task PublishEntityPrefabPackageAsync(
+ CultCache cache,
+ CultMeshEntityPrefabPackage package)
+ {
+ return CultMeshEntityPrefabs.PublishAsync(cache, package);
+ }
+
+ ///
+ /// Publishes a portable entity prefab package into a distributed CultNet database.
+ ///
+ public static Task PublishEntityPrefabPackageAsync(
+ CultNetDatabase database,
+ CultMeshEntityPrefabPackage package)
+ {
+ return CultMeshEntityPrefabs.PublishAsync(database, package);
+ }
+
+ ///
+ /// Creates a CultNet document registry for portable entity prefab packages.
+ ///
+ public static CultNetDocumentRegistry CreateEntityPrefabDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ return CultMeshEntityPrefabs.CreateDocumentRegistry(documents);
+ }
+
+ ///
+ /// Creates a CultNet document registry for CDN assets and portable entity prefab packages.
+ ///
+ public static CultNetDocumentRegistry CreateAssetPipelineDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ return CultMeshEntityPrefabs.CreateAssetPipelineDocumentRegistry(documents);
+ }
+
///
/// Creates a managed Verse context for generated domain sugar.
///
@@ -1700,6 +1805,7 @@ namespace GameCult.Mesh
if (verse == null) throw new ArgumentNullException(nameof(verse));
return DocumentsFromPublication(source, bindings, verse.Context, storeOptions, peerOptions);
}
+
///
/// Reads configured publication documents, hydrates them into a local node, and returns local handles as a catalog.
///
@@ -1751,6 +1857,7 @@ namespace GameCult.Mesh
peerOptions,
flush);
}
+
///
/// Reads one typed document from a configured publication source and hydrates it into a local node.
///
@@ -1834,6 +1941,7 @@ namespace GameCult.Mesh
peerOptions,
flush);
}
+
internal static CultMeshStoreDocumentOptions WithPublicationBindingOptions(
CultMeshStoreDocumentOptions? options,
CultRecordKey key,
@@ -1881,6 +1989,7 @@ namespace GameCult.Mesh
RudpResendDelayMs = options?.RudpResendDelayMs ?? 25
};
}
+
///
/// Creates a typed document handle directly over one distributed CultNet database record.
///
diff --git a/src/GameCult.Mesh/CultMeshCdn.cs b/src/GameCult.Mesh/CultMeshCdn.cs
new file mode 100644
index 00000000..72f38c6a
--- /dev/null
+++ b/src/GameCult.Mesh/CultMeshCdn.cs
@@ -0,0 +1,578 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading.Tasks;
+using GameCult.Caching;
+using GameCult.Networking;
+using MessagePack;
+
+namespace GameCult.Mesh
+{
+ ///
+ /// Schema versions for CultMesh distributed CDN documents.
+ ///
+ public static class CultMeshCdnSchemaVersions
+ {
+ /// Manifest document schema id.
+ public const string ArtifactManifest = "gamecult.mesh.cdn_artifact_manifest.v1";
+ /// Chunk document schema id.
+ public const string ArtifactChunk = "gamecult.mesh.cdn_artifact_chunk.v1";
+ }
+
+ ///
+ /// Well-known CultMesh CDN artifact kinds.
+ ///
+ public static class CultMeshCdnArtifactKinds
+ {
+ /// Game, UI, shader, texture, audio, or data asset payload.
+ public const string Asset = "asset";
+ /// Executable build or install/update payload.
+ public const string Build = "build";
+ /// Generic packaged payload.
+ public const string Package = "package";
+ }
+
+ ///
+ /// Options for packing bytes into CultMesh CDN documents.
+ ///
+ public sealed class CultMeshCdnPackOptions
+ {
+ /// Default CDN chunk size.
+ public const int DefaultChunkSizeBytes = 256 * 1024;
+
+ /// Maximum bytes per content chunk.
+ public int ChunkSizeBytes { get; set; } = DefaultChunkSizeBytes;
+
+ /// Artifact kind, such as asset or build.
+ public string Kind { get; set; } = CultMeshCdnArtifactKinds.Asset;
+
+ /// Caller-defined artifact version.
+ public string Version { get; set; } = string.Empty;
+
+ /// Artifact MIME type.
+ public string MimeType { get; set; } = "application/octet-stream";
+
+ /// Search and routing tags copied to the manifest.
+ public string[] Tags { get; set; } = Array.Empty();
+
+ /// Caller metadata copied to the manifest.
+ public Dictionary Metadata { get; set; } = new();
+
+ /// Override manifest creation timestamp in round-trip UTC format.
+ public string? CreatedAtUtc { get; set; }
+ }
+
+ ///
+ /// Reference from an artifact manifest to one content-addressed chunk document.
+ ///
+ [MessagePackObject]
+ public sealed class CultMeshCdnChunkRef
+ {
+ /// SHA-256 hash of the referenced chunk payload.
+ [Key(0)]
+ public string ChunkHash { get; set; } = string.Empty;
+
+ /// Byte offset of this chunk inside the materialized artifact.
+ [Key(1)]
+ public long Offset { get; set; }
+
+ /// Number of payload bytes contributed by this chunk.
+ [Key(2)]
+ public int SizeBytes { get; set; }
+
+ /// CultCache record key for the referenced chunk document.
+ [Key(3)]
+ public string RecordKey { get; set; } = string.Empty;
+ }
+
+ ///
+ /// Content-addressed artifact chunk stored in CultCache and replicated through CultNet.
+ ///
+ [MessagePackObject]
+ [CultDocument("gamecult.mesh.cdn_artifact_chunk", CultMeshCdnSchemaVersions.ArtifactChunk)]
+ public sealed class CultMeshCdnArtifactChunk
+ {
+ /// SHA-256 hash of the chunk payload.
+ [Key(0)]
+ [CultName]
+ public string ChunkHash { get; set; } = string.Empty;
+
+ /// Payload byte count.
+ [Key(1)]
+ public int SizeBytes { get; set; }
+
+ /// Raw chunk payload bytes.
+ [Key(2)]
+ public byte[] Payload { get; set; } = Array.Empty();
+
+ /// Builds the deterministic content-addressed chunk record key.
+ public static CultRecordKey CreateRecordKey(CultMeshCdnArtifactChunk chunk)
+ {
+ if (chunk == null) throw new ArgumentNullException(nameof(chunk));
+ return CreateRecordKey(chunk.ChunkHash);
+ }
+
+ /// Builds the deterministic content-addressed chunk record key.
+ public static CultRecordKey CreateRecordKey(string chunkHash)
+ {
+ return new CultRecordKey("mesh:cdn:chunk:" + CultMeshCdn.NormalizeHash(chunkHash, nameof(chunkHash)));
+ }
+ }
+
+ ///
+ /// Manifest for one versioned CDN artifact assembled from content-addressed chunks.
+ ///
+ [MessagePackObject]
+ [CultDocument("gamecult.mesh.cdn_artifact_manifest", CultMeshCdnSchemaVersions.ArtifactManifest)]
+ public sealed class CultMeshCdnArtifactManifest
+ {
+ /// Stable artifact id, such as a logical asset or build path.
+ [Key(0)]
+ [CultName]
+ public string ArtifactId { get; set; } = string.Empty;
+
+ /// Artifact kind, such as asset, build, or package.
+ [Key(1)]
+ [CultIndex]
+ public string Kind { get; set; } = CultMeshCdnArtifactKinds.Asset;
+
+ /// Caller-defined artifact version.
+ [Key(2)]
+ [CultIndex]
+ public string Version { get; set; } = string.Empty;
+
+ /// SHA-256 hash of the full materialized artifact.
+ [Key(3)]
+ [CultIndex]
+ public string ContentHash { get; set; } = string.Empty;
+
+ /// Full materialized artifact size.
+ [Key(4)]
+ public long SizeBytes { get; set; }
+
+ /// Artifact MIME type.
+ [Key(5)]
+ public string MimeType { get; set; } = "application/octet-stream";
+
+ /// Manifest creation timestamp in round-trip UTC format.
+ [Key(6)]
+ public string CreatedAtUtc { get; set; } = string.Empty;
+
+ /// Ordered chunk references needed to materialize the artifact.
+ [Key(7)]
+ public CultMeshCdnChunkRef[] Chunks { get; set; } = Array.Empty();
+
+ /// Search and routing tags.
+ [Key(8)]
+ public string[] Tags { get; set; } = Array.Empty();
+
+ /// Caller metadata, such as platform or texture channel layout.
+ [Key(9)]
+ public Dictionary Metadata { get; set; } = new();
+
+ /// Builds the deterministic versioned artifact manifest record key.
+ public static CultRecordKey CreateRecordKey(CultMeshCdnArtifactManifest manifest)
+ {
+ if (manifest == null) throw new ArgumentNullException(nameof(manifest));
+ return CreateRecordKey(manifest.ArtifactId, manifest.Version, manifest.ContentHash);
+ }
+
+ /// Builds the deterministic versioned artifact manifest record key.
+ public static CultRecordKey CreateRecordKey(string artifactId, string version, string contentHash)
+ {
+ var artifactToken = CultMeshCdn.StableToken(artifactId, nameof(artifactId));
+ var versionToken = string.IsNullOrWhiteSpace(version)
+ ? "unversioned"
+ : CultMeshCdn.StableToken(version, nameof(version));
+ return new CultRecordKey(
+ "mesh:cdn:artifact:" + artifactToken + ":" + versionToken + ":" + CultMeshCdn.NormalizeHash(contentHash, nameof(contentHash)));
+ }
+ }
+
+ ///
+ /// Packed CDN artifact ready to publish into a cache or database.
+ ///
+ public sealed class CultMeshCdnArtifact
+ {
+ /// Creates a packed artifact container.
+ public CultMeshCdnArtifact(
+ CultMeshCdnArtifactManifest manifest,
+ IReadOnlyList chunks)
+ {
+ Manifest = manifest ?? throw new ArgumentNullException(nameof(manifest));
+ Chunks = chunks ?? throw new ArgumentNullException(nameof(chunks));
+ }
+
+ /// Artifact manifest document.
+ public CultMeshCdnArtifactManifest Manifest { get; }
+
+ /// Content-addressed chunk documents.
+ public IReadOnlyList Chunks { get; }
+
+ /// Deterministic manifest record key.
+ public CultRecordKey ManifestKey => CultMeshCdnArtifactManifest.CreateRecordKey(Manifest);
+
+ /// All unique record keys required to replicate this artifact.
+ public IReadOnlyList RecordKeys =>
+ new[] { ManifestKey }.Concat(Chunks.Select(CultMeshCdnArtifactChunk.CreateRecordKey)).Distinct().ToArray();
+ }
+
+ ///
+ /// Content-addressed byte artifact helpers for distributing assets and builds through CultMesh clients.
+ ///
+ public static class CultMeshCdn
+ {
+ ///
+ /// Splits a payload into content-addressed chunk documents and a versioned manifest.
+ ///
+ public static CultMeshCdnArtifact PackArtifact(
+ string artifactId,
+ byte[] payload,
+ CultMeshCdnPackOptions? options = null)
+ {
+ if (string.IsNullOrWhiteSpace(artifactId))
+ {
+ throw new ArgumentException("Artifact id must be non-empty.", nameof(artifactId));
+ }
+
+ if (payload == null) throw new ArgumentNullException(nameof(payload));
+ options ??= new CultMeshCdnPackOptions();
+ if (options.ChunkSizeBytes <= 0)
+ {
+ throw new ArgumentOutOfRangeException(nameof(options), "ChunkSizeBytes must be greater than zero.");
+ }
+
+ var chunks = new List();
+ var refs = new List();
+ for (var offset = 0; offset < payload.Length; offset += options.ChunkSizeBytes)
+ {
+ var count = Math.Min(options.ChunkSizeBytes, payload.Length - offset);
+ var chunkPayload = new byte[count];
+ Buffer.BlockCopy(payload, offset, chunkPayload, 0, count);
+ var chunkHash = HashBytes(chunkPayload);
+ var chunk = new CultMeshCdnArtifactChunk
+ {
+ ChunkHash = chunkHash,
+ SizeBytes = count,
+ Payload = chunkPayload
+ };
+ chunks.Add(chunk);
+ refs.Add(new CultMeshCdnChunkRef
+ {
+ ChunkHash = chunkHash,
+ Offset = offset,
+ SizeBytes = count,
+ RecordKey = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value
+ });
+ }
+
+ if (payload.Length == 0)
+ {
+ var chunkHash = HashBytes(Array.Empty());
+ var chunk = new CultMeshCdnArtifactChunk
+ {
+ ChunkHash = chunkHash,
+ SizeBytes = 0,
+ Payload = Array.Empty()
+ };
+ chunks.Add(chunk);
+ refs.Add(new CultMeshCdnChunkRef
+ {
+ ChunkHash = chunkHash,
+ Offset = 0,
+ SizeBytes = 0,
+ RecordKey = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value
+ });
+ }
+
+ var manifest = new CultMeshCdnArtifactManifest
+ {
+ ArtifactId = artifactId,
+ Kind = string.IsNullOrWhiteSpace(options.Kind) ? CultMeshCdnArtifactKinds.Asset : options.Kind,
+ Version = options.Version ?? string.Empty,
+ ContentHash = HashBytes(payload),
+ SizeBytes = payload.LongLength,
+ MimeType = string.IsNullOrWhiteSpace(options.MimeType) ? "application/octet-stream" : options.MimeType,
+ CreatedAtUtc = options.CreatedAtUtc ?? DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture),
+ Chunks = refs.ToArray(),
+ Tags = options.Tags ?? Array.Empty(),
+ Metadata = options.Metadata ?? new Dictionary()
+ };
+
+ return new CultMeshCdnArtifact(manifest, chunks);
+ }
+
+ ///
+ /// Publishes all chunk documents and the manifest into a local CultCache.
+ ///
+ public static async Task PublishAsync(
+ CultCache cache,
+ CultMeshCdnArtifact artifact)
+ {
+ if (cache == null) throw new ArgumentNullException(nameof(cache));
+ if (artifact == null) throw new ArgumentNullException(nameof(artifact));
+
+ ValidateArtifact(artifact);
+ foreach (var chunk in artifact.Chunks)
+ {
+ await cache.UpsertAsync(
+ chunk,
+ new CultRecordHandle(
+ CultMeshCdnArtifactChunk.CreateRecordKey(chunk))).ConfigureAwait(false);
+ }
+
+ await cache.UpsertAsync(
+ artifact.Manifest,
+ new CultRecordHandle(
+ CultMeshCdnArtifactManifest.CreateRecordKey(artifact.Manifest))).ConfigureAwait(false);
+
+ return artifact.Manifest;
+ }
+
+ ///
+ /// Publishes all chunk documents and the manifest into a distributed CultNet database.
+ ///
+ public static async Task PublishAsync(
+ CultNetDatabase database,
+ CultMeshCdnArtifact artifact)
+ {
+ if (database == null) throw new ArgumentNullException(nameof(database));
+ if (artifact == null) throw new ArgumentNullException(nameof(artifact));
+
+ ValidateArtifact(artifact);
+ foreach (var chunk in artifact.Chunks)
+ {
+ await database.PutAsync(CultMeshCdnArtifactChunk.CreateRecordKey(chunk), chunk)
+ .ConfigureAwait(false);
+ }
+
+ await database.PutAsync(CultMeshCdnArtifactManifest.CreateRecordKey(artifact.Manifest), artifact.Manifest)
+ .ConfigureAwait(false);
+ return artifact.Manifest;
+ }
+
+ ///
+ /// Reassembles and verifies an artifact from a local CultCache.
+ ///
+ public static byte[] ReadArtifact(CultCache cache, CultMeshCdnArtifactManifest manifest)
+ {
+ if (cache == null) throw new ArgumentNullException(nameof(cache));
+ if (manifest == null) throw new ArgumentNullException(nameof(manifest));
+
+ ValidateManifestShape(manifest);
+ var output = new byte[checked((int)manifest.SizeBytes)];
+ foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset))
+ {
+ var recordKey = string.IsNullOrWhiteSpace(reference.RecordKey)
+ ? CultMeshCdnArtifactChunk.CreateRecordKey(reference.ChunkHash)
+ : new CultRecordKey(reference.RecordKey);
+ var chunk = cache.Get(recordKey)
+ ?? throw new FileNotFoundException("CDN artifact chunk is missing from the cache.", recordKey.Value);
+ ValidateChunk(reference, chunk);
+ Buffer.BlockCopy(chunk.Payload, 0, output, checked((int)reference.Offset), reference.SizeBytes);
+ }
+
+ var actualHash = HashBytes(output);
+ if (!string.Equals(NormalizeHash(manifest.ContentHash, nameof(manifest.ContentHash)), actualHash, StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("CDN artifact content hash does not match its manifest.");
+ }
+
+ return output;
+ }
+
+ ///
+ /// Reassembles and verifies an artifact from a distributed CultNet database.
+ ///
+ public static async Task ReadArtifactAsync(
+ CultNetDatabase database,
+ CultMeshCdnArtifactManifest manifest)
+ {
+ if (database == null) throw new ArgumentNullException(nameof(database));
+ if (manifest == null) throw new ArgumentNullException(nameof(manifest));
+
+ ValidateManifestShape(manifest);
+ var output = new byte[checked((int)manifest.SizeBytes)];
+ foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset))
+ {
+ var recordKey = string.IsNullOrWhiteSpace(reference.RecordKey)
+ ? CultMeshCdnArtifactChunk.CreateRecordKey(reference.ChunkHash)
+ : new CultRecordKey(reference.RecordKey);
+ var chunk = await database.GetAsync(recordKey).ConfigureAwait(false)
+ ?? throw new FileNotFoundException("CDN artifact chunk is missing from the database.", recordKey.Value);
+ ValidateChunk(reference, chunk);
+ Buffer.BlockCopy(chunk.Payload, 0, output, checked((int)reference.Offset), reference.SizeBytes);
+ }
+
+ var actualHash = HashBytes(output);
+ if (!string.Equals(NormalizeHash(manifest.ContentHash, nameof(manifest.ContentHash)), actualHash, StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("CDN artifact content hash does not match its manifest.");
+ }
+
+ return output;
+ }
+
+ ///
+ /// Creates a raw CultNet document registry for CDN manifests and chunks.
+ ///
+ public static CultNetDocumentRegistry CreateDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ documents ??= CultDocumentRegistry.Shared;
+ return new CultNetDocumentRegistry(documents)
+ .Register(CultNetDocumentBinding.ForDocument(documents))
+ .Register(CultNetDocumentBinding.ForDocument(documents));
+ }
+
+ internal static string HashBytes(byte[] bytes)
+ {
+ using var sha256 = SHA256.Create();
+ var hash = sha256.ComputeHash(bytes);
+ var builder = new StringBuilder(hash.Length * 2);
+ foreach (var value in hash)
+ {
+ builder.Append(value.ToString("x2", CultureInfo.InvariantCulture));
+ }
+
+ return builder.ToString();
+ }
+
+ private static void ValidateArtifact(CultMeshCdnArtifact artifact)
+ {
+ ValidateManifestShape(artifact.Manifest);
+ var expectedRefs = artifact.Chunks
+ .Select(chunk => new
+ {
+ Hash = HashBytes(chunk.Payload),
+ ChunkHash = NormalizeHash(chunk.ChunkHash, nameof(chunk.ChunkHash)),
+ chunk.SizeBytes,
+ Key = CultMeshCdnArtifactChunk.CreateRecordKey(chunk).Value
+ })
+ .ToArray();
+
+ if (artifact.Manifest.Chunks.Length != expectedRefs.Length)
+ {
+ throw new InvalidDataException("CDN artifact manifest chunk count does not match chunk payloads.");
+ }
+
+ for (var i = 0; i < expectedRefs.Length; i++)
+ {
+ var reference = artifact.Manifest.Chunks[i];
+ var expected = expectedRefs[i];
+ if (!string.Equals(NormalizeHash(reference.ChunkHash, nameof(reference.ChunkHash)), expected.Hash, StringComparison.Ordinal) ||
+ !string.Equals(expected.ChunkHash, expected.Hash, StringComparison.Ordinal) ||
+ reference.SizeBytes != expected.SizeBytes ||
+ !string.Equals(reference.RecordKey, expected.Key, StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("CDN artifact manifest chunk reference does not match its chunk payload.");
+ }
+ }
+
+ var materialized = new byte[checked((int)artifact.Manifest.SizeBytes)];
+ foreach (var reference in artifact.Manifest.Chunks.OrderBy(chunk => chunk.Offset))
+ {
+ var chunk = artifact.Chunks.First(candidate =>
+ string.Equals(
+ CultMeshCdnArtifactChunk.CreateRecordKey(candidate).Value,
+ reference.RecordKey,
+ StringComparison.Ordinal));
+ Buffer.BlockCopy(chunk.Payload, 0, materialized, checked((int)reference.Offset), reference.SizeBytes);
+ }
+
+ if (!string.Equals(
+ NormalizeHash(artifact.Manifest.ContentHash, nameof(artifact.Manifest.ContentHash)),
+ HashBytes(materialized),
+ StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("CDN artifact content hash does not match its manifest.");
+ }
+ }
+
+ private static void ValidateManifestShape(CultMeshCdnArtifactManifest manifest)
+ {
+ if (manifest.SizeBytes < 0)
+ {
+ throw new InvalidDataException("CDN artifact manifest has a negative size.");
+ }
+
+ if (manifest.SizeBytes > int.MaxValue)
+ {
+ throw new InvalidDataException("CDN artifact is too large to materialize into one byte array.");
+ }
+
+ var expectedOffset = 0L;
+ foreach (var reference in manifest.Chunks.OrderBy(chunk => chunk.Offset))
+ {
+ if (reference.Offset != expectedOffset)
+ {
+ throw new InvalidDataException("CDN artifact chunks are not contiguous.");
+ }
+
+ if (reference.SizeBytes < 0)
+ {
+ throw new InvalidDataException("CDN artifact chunk has a negative size.");
+ }
+
+ expectedOffset += reference.SizeBytes;
+ }
+
+ if (expectedOffset != manifest.SizeBytes)
+ {
+ throw new InvalidDataException("CDN artifact chunk sizes do not sum to the manifest size.");
+ }
+ }
+
+ private static void ValidateChunk(CultMeshCdnChunkRef reference, CultMeshCdnArtifactChunk chunk)
+ {
+ if (chunk.Payload.Length != reference.SizeBytes ||
+ chunk.SizeBytes != reference.SizeBytes)
+ {
+ throw new InvalidDataException("CDN artifact chunk payload metadata does not match its manifest reference.");
+ }
+
+ var actualHash = HashBytes(chunk.Payload);
+ if (!string.Equals(NormalizeHash(reference.ChunkHash, nameof(reference.ChunkHash)), actualHash, StringComparison.Ordinal) ||
+ !string.Equals(NormalizeHash(chunk.ChunkHash, nameof(chunk.ChunkHash)), actualHash, StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("CDN artifact chunk hash does not match its payload.");
+ }
+ }
+
+ internal static string NormalizeHash(string hash, string parameterName)
+ {
+ if (string.IsNullOrWhiteSpace(hash))
+ {
+ throw new ArgumentException("Hash must be non-empty.", parameterName);
+ }
+
+ var value = hash.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase)
+ ? hash.Substring("sha256:".Length)
+ : hash;
+ return value.Trim().ToLowerInvariant();
+ }
+
+ internal static string StableToken(string value, string parameterName)
+ {
+ if (string.IsNullOrWhiteSpace(value))
+ {
+ throw new ArgumentException("Value must be non-empty.", parameterName);
+ }
+
+ var normalized = value.Trim().ToLowerInvariant();
+ var builder = new StringBuilder(normalized.Length);
+ foreach (var c in normalized)
+ {
+ builder.Append(char.IsLetterOrDigit(c) || c == '-' || c == '_' || c == '.' ? c : '-');
+ }
+
+ var token = builder.ToString().Trim('-');
+ return string.IsNullOrWhiteSpace(token)
+ ? HashBytes(Encoding.UTF8.GetBytes(value))
+ : token;
+ }
+ }
+}
diff --git a/src/GameCult.Mesh/CultMeshEntityPrefabs.cs b/src/GameCult.Mesh/CultMeshEntityPrefabs.cs
new file mode 100644
index 00000000..194c9360
--- /dev/null
+++ b/src/GameCult.Mesh/CultMeshEntityPrefabs.cs
@@ -0,0 +1,395 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using GameCult.Caching;
+using GameCult.Networking;
+using MessagePack;
+
+namespace GameCult.Mesh
+{
+ ///
+ /// Schema versions for portable entity prefab packages.
+ ///
+ public static class CultMeshEntityPrefabSchemaVersions
+ {
+ /// Portable prefab package schema id.
+ public const string Package = "gamecult.mesh.entity_prefab_package.v1";
+ }
+
+ ///
+ /// Well-known portable prefab node kinds.
+ ///
+ public static class CultMeshEntityPrefabNodeKinds
+ {
+ /// Transform-only node.
+ public const string Empty = "empty";
+ /// Renderable mesh node.
+ public const string Mesh = "mesh";
+ /// Collider node.
+ public const string Collider = "collider";
+ /// Particle or projectile effect node.
+ public const string Effect = "effect";
+ /// Camera or view anchor node.
+ public const string Camera = "camera";
+ /// Runtime attachment point.
+ public const string Socket = "socket";
+ }
+
+ ///
+ /// Well-known prefab asset roles.
+ ///
+ public static class CultMeshEntityPrefabAssetRoles
+ {
+ /// Mesh geometry payload.
+ public const string Mesh = "mesh";
+ /// Texture image payload.
+ public const string Texture = "texture";
+ /// Material definition payload.
+ public const string Material = "material";
+ /// Animation clip payload.
+ public const string Animation = "animation";
+ /// Audio payload.
+ public const string Audio = "audio";
+ }
+
+ ///
+ /// Portable transform using Blender/CultMesh source coordinates before runtime lowering.
+ ///
+ [MessagePackObject]
+ public sealed class CultMeshEntityPrefabTransform
+ {
+ /// Local position vector.
+ [Key(0)]
+ public float[] Position { get; set; } = [0f, 0f, 0f];
+
+ /// Local rotation quaternion.
+ [Key(1)]
+ public float[] Rotation { get; set; } = [0f, 0f, 0f, 1f];
+
+ /// Local scale vector.
+ [Key(2)]
+ public float[] Scale { get; set; } = [1f, 1f, 1f];
+ }
+
+ ///
+ /// Runtime component intent attached to a portable prefab node.
+ ///
+ [MessagePackObject]
+ public sealed class CultMeshEntityPrefabComponent
+ {
+ /// Portable component kind or runtime adapter type.
+ [Key(0)]
+ public string Type { get; set; } = string.Empty;
+
+ /// String-valued component properties for runtime-specific lowering.
+ [Key(1)]
+ public Dictionary Properties { get; set; } = new();
+ }
+
+ ///
+ /// Reference from a prefab package to a CDN artifact manifest.
+ ///
+ [MessagePackObject]
+ public sealed class CultMeshEntityPrefabAssetRef
+ {
+ /// Stable source asset id inside the prefab package.
+ [Key(0)]
+ public string AssetId { get; set; } = string.Empty;
+
+ /// Semantic role, such as mesh, texture, material, or animation.
+ [Key(1)]
+ public string Role { get; set; } = string.Empty;
+
+ /// CultCache record key for the referenced CDN artifact manifest.
+ [Key(2)]
+ public string CdnManifestRecordKey { get; set; } = string.Empty;
+
+ /// Full artifact content hash copied from the referenced CDN manifest.
+ [Key(3)]
+ public string ContentHash { get; set; } = string.Empty;
+
+ /// Artifact MIME type copied from the referenced CDN manifest.
+ [Key(4)]
+ public string MimeType { get; set; } = string.Empty;
+
+ /// Runtime and source metadata for the asset reference.
+ [Key(5)]
+ public Dictionary Metadata { get; set; } = new();
+ }
+
+ ///
+ /// One node in a portable entity prefab graph.
+ ///
+ [MessagePackObject]
+ public sealed class CultMeshEntityPrefabNode
+ {
+ /// Stable node id inside the package.
+ [Key(0)]
+ public string NodeId { get; set; } = string.Empty;
+
+ /// Source object name.
+ [Key(1)]
+ public string Name { get; set; } = string.Empty;
+
+ /// Optional parent node id.
+ [Key(2)]
+ public string ParentNodeId { get; set; } = string.Empty;
+
+ /// Node kind.
+ [Key(3)]
+ public string Kind { get; set; } = CultMeshEntityPrefabNodeKinds.Empty;
+
+ /// Local transform.
+ [Key(4)]
+ public CultMeshEntityPrefabTransform Transform { get; set; } = new();
+
+ /// Optional mesh asset id used by this node.
+ [Key(5)]
+ public string MeshAssetId { get; set; } = string.Empty;
+
+ /// Material asset ids used by this node.
+ [Key(6)]
+ public string[] MaterialAssetIds { get; set; } = Array.Empty();
+
+ /// Runtime component intents attached to this node.
+ [Key(7)]
+ public CultMeshEntityPrefabComponent[] Components { get; set; } = Array.Empty();
+
+ /// Runtime tags copied from source metadata.
+ [Key(8)]
+ public string[] Tags { get; set; } = Array.Empty();
+
+ /// Additional source metadata.
+ [Key(9)]
+ public Dictionary Metadata { get; set; } = new();
+ }
+
+ ///
+ /// Portable entity prefab package authored from a Blender collection and lowerable into multiple runtimes.
+ ///
+ [MessagePackObject]
+ [CultDocument("gamecult.mesh.entity_prefab_package", CultMeshEntityPrefabSchemaVersions.Package)]
+ public sealed class CultMeshEntityPrefabPackage
+ {
+ /// Stable logical prefab id.
+ [Key(0)]
+ [CultName]
+ public string PrefabId { get; set; } = string.Empty;
+
+ /// Caller-defined package version.
+ [Key(1)]
+ [CultIndex]
+ public string Version { get; set; } = string.Empty;
+
+ /// Tool that authored the package, such as Brokkr Blender.
+ [Key(2)]
+ [CultIndex]
+ public string SourceTool { get; set; } = string.Empty;
+
+ /// Source scene name or path.
+ [Key(3)]
+ public string SourceScene { get; set; } = string.Empty;
+
+ /// Source Blender collection name.
+ [Key(4)]
+ [CultIndex]
+ public string SourceCollection { get; set; } = string.Empty;
+
+ /// Stable hash of graph structure and referenced assets.
+ [Key(5)]
+ [CultIndex]
+ public string ContentHash { get; set; } = string.Empty;
+
+ /// Package creation timestamp in round-trip UTC format.
+ [Key(6)]
+ public string CreatedAtUtc { get; set; } = string.Empty;
+
+ /// Referenced CDN assets.
+ [Key(7)]
+ public CultMeshEntityPrefabAssetRef[] Assets { get; set; } = Array.Empty();
+
+ /// Prefab hierarchy nodes.
+ [Key(8)]
+ public CultMeshEntityPrefabNode[] Nodes { get; set; } = Array.Empty();
+
+ /// Search and routing tags.
+ [Key(9)]
+ public string[] Tags { get; set; } = Array.Empty();
+
+ /// Package-level metadata.
+ [Key(10)]
+ public Dictionary Metadata { get; set; } = new();
+
+ /// Builds the deterministic package record key.
+ public static CultRecordKey CreateRecordKey(CultMeshEntityPrefabPackage package)
+ {
+ if (package == null) throw new ArgumentNullException(nameof(package));
+ return CreateRecordKey(package.PrefabId, package.Version, package.ContentHash);
+ }
+
+ /// Builds the deterministic package record key.
+ public static CultRecordKey CreateRecordKey(string prefabId, string version, string contentHash)
+ {
+ var prefabToken = CultMeshCdn.StableToken(prefabId, nameof(prefabId));
+ var versionToken = string.IsNullOrWhiteSpace(version)
+ ? "unversioned"
+ : CultMeshCdn.StableToken(version, nameof(version));
+ return new CultRecordKey(
+ "mesh:entity-prefab:" + prefabToken + ":" + versionToken + ":" + CultMeshCdn.NormalizeHash(contentHash, nameof(contentHash)));
+ }
+ }
+
+ ///
+ /// Helpers for publishing and validating portable entity prefab packages.
+ ///
+ public static class CultMeshEntityPrefabs
+ {
+ ///
+ /// Computes a stable package content hash from graph structure and referenced asset hashes.
+ ///
+ public static string ComputeContentHash(CultMeshEntityPrefabPackage package)
+ {
+ if (package == null) throw new ArgumentNullException(nameof(package));
+ var builder = new StringBuilder();
+ builder.Append(package.PrefabId).Append('\u001F')
+ .Append(package.Version).Append('\u001F')
+ .Append(package.SourceTool).Append('\u001F')
+ .Append(package.SourceScene).Append('\u001F')
+ .Append(package.SourceCollection).Append('\u001F');
+
+ foreach (var asset in package.Assets.OrderBy(asset => asset.AssetId, StringComparer.Ordinal))
+ {
+ builder.Append("asset").Append('\u001E')
+ .Append(asset.AssetId).Append('\u001E')
+ .Append(asset.Role).Append('\u001E')
+ .Append(asset.CdnManifestRecordKey).Append('\u001E')
+ .Append(CultMeshCdn.NormalizeHash(asset.ContentHash, nameof(asset.ContentHash))).Append('\u001E')
+ .Append(asset.MimeType).Append('\u001E')
+ .Append(StableMap(asset.Metadata)).Append('\u001F');
+ }
+
+ foreach (var node in package.Nodes.OrderBy(node => node.NodeId, StringComparer.Ordinal))
+ {
+ builder.Append("node").Append('\u001E')
+ .Append(node.NodeId).Append('\u001E')
+ .Append(node.Name).Append('\u001E')
+ .Append(node.ParentNodeId).Append('\u001E')
+ .Append(node.Kind).Append('\u001E')
+ .Append(StableFloats(node.Transform.Position)).Append('\u001E')
+ .Append(StableFloats(node.Transform.Rotation)).Append('\u001E')
+ .Append(StableFloats(node.Transform.Scale)).Append('\u001E')
+ .Append(node.MeshAssetId).Append('\u001E')
+ .Append(string.Join(",", node.MaterialAssetIds.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001E')
+ .Append(StableComponents(node.Components)).Append('\u001E')
+ .Append(string.Join(",", node.Tags.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001E')
+ .Append(StableMap(node.Metadata)).Append('\u001F');
+ }
+
+ builder.Append(string.Join(",", package.Tags.OrderBy(value => value, StringComparer.Ordinal))).Append('\u001F')
+ .Append(StableMap(package.Metadata));
+
+ return CultMeshCdn.HashBytes(Encoding.UTF8.GetBytes(builder.ToString()));
+ }
+
+ ///
+ /// Stamps the current content hash and creation timestamp on a package.
+ ///
+ public static CultMeshEntityPrefabPackage FinalizePackage(CultMeshEntityPrefabPackage package)
+ {
+ if (package == null) throw new ArgumentNullException(nameof(package));
+ package.CreatedAtUtc = string.IsNullOrWhiteSpace(package.CreatedAtUtc)
+ ? DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture)
+ : package.CreatedAtUtc;
+ package.ContentHash = ComputeContentHash(package);
+ return package;
+ }
+
+ ///
+ /// Publishes a finalized portable entity prefab package into a local cache.
+ ///
+ public static async Task PublishAsync(
+ CultCache cache,
+ CultMeshEntityPrefabPackage package)
+ {
+ if (cache == null) throw new ArgumentNullException(nameof(cache));
+ if (package == null) throw new ArgumentNullException(nameof(package));
+ ValidatePackage(package);
+ await cache.UpsertAsync(
+ package,
+ new CultRecordHandle(
+ CultMeshEntityPrefabPackage.CreateRecordKey(package))).ConfigureAwait(false);
+ return package;
+ }
+
+ ///
+ /// Publishes a finalized portable entity prefab package into a distributed CultNet database.
+ ///
+ public static async Task PublishAsync(
+ CultNetDatabase database,
+ CultMeshEntityPrefabPackage package)
+ {
+ if (database == null) throw new ArgumentNullException(nameof(database));
+ if (package == null) throw new ArgumentNullException(nameof(package));
+ ValidatePackage(package);
+ await database.PutAsync(CultMeshEntityPrefabPackage.CreateRecordKey(package), package)
+ .ConfigureAwait(false);
+ return package;
+ }
+
+ ///
+ /// Creates a raw CultNet document registry for entity prefab packages.
+ ///
+ public static CultNetDocumentRegistry CreateDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ documents ??= CultDocumentRegistry.Shared;
+ return new CultNetDocumentRegistry(documents)
+ .Register(CultNetDocumentBinding.ForDocument(documents));
+ }
+
+ ///
+ /// Creates a raw CultNet document registry for CDN assets and portable entity prefab packages.
+ ///
+ public static CultNetDocumentRegistry CreateAssetPipelineDocumentRegistry(CultDocumentRegistry? documents = null)
+ {
+ documents ??= CultDocumentRegistry.Shared;
+ return CultMeshCdn.CreateDocumentRegistry(documents)
+ .Register(CultNetDocumentBinding.ForDocument(documents));
+ }
+
+ private static void ValidatePackage(CultMeshEntityPrefabPackage package)
+ {
+ if (string.IsNullOrWhiteSpace(package.PrefabId))
+ {
+ throw new ArgumentException("Prefab id must be non-empty.", nameof(package));
+ }
+
+ var expectedHash = ComputeContentHash(package);
+ if (!string.Equals(CultMeshCdn.NormalizeHash(package.ContentHash, nameof(package.ContentHash)), expectedHash, StringComparison.Ordinal))
+ {
+ throw new InvalidOperationException("Entity prefab package content hash does not match its graph.");
+ }
+ }
+
+ private static string StableComponents(IEnumerable components)
+ {
+ return string.Join("|", components
+ .OrderBy(component => component.Type, StringComparer.Ordinal)
+ .Select(component => component.Type + "=" + StableMap(component.Properties)));
+ }
+
+ private static string StableFloats(IEnumerable values)
+ {
+ return string.Join(",", values.Select(value => value.ToString("R", CultureInfo.InvariantCulture)));
+ }
+
+ private static string StableMap(Dictionary values)
+ {
+ return string.Join("|", values
+ .OrderBy(pair => pair.Key, StringComparer.Ordinal)
+ .Select(pair => pair.Key + "=" + pair.Value));
+ }
+ }
+}
diff --git a/src/GameCult.Mesh/README.md b/src/GameCult.Mesh/README.md
index 4689136a..3bf3beb7 100644
--- a/src/GameCult.Mesh/README.md
+++ b/src/GameCult.Mesh/README.md
@@ -45,6 +45,23 @@ using var node = await CultMesh.StartNodeAsync("world.ccmp", new CultMeshNodeOpt
If `ShardLogPath` is omitted, CultMesh stores logs beside the cache under
`world.cultmesh/shard-logs`.
+## Distributed CDN
+
+CultMesh can distribute signed, content-addressed game assets through the same
+typed document lane as gameplay state. Asset manifests, chunks, and portable
+entity prefab packages are CultCache documents that can be replicated by
+CultNet snapshots, shard logs, central servers, LAN peers, or opted-out-capable
+internet peer caches.
+
+This is the canonical asset pipeline target for Aetheria. Brokkr-authored
+Blender prefab snapshots deploy into `CultMeshEntityPrefabPackage` documents
+that reference CDN artifact manifests for meshes, textures, materials, and
+other payloads. Unity and TypeScript clients should unpack the same package
+graph rather than maintaining separate Unity-prefab and Electron asset formats.
+
+See [docs/distributed-cdn.md](docs/distributed-cdn.md) for document shapes,
+publish/read helpers, peer asset sharing policy, and the Brokkr prefab flow.
+
## Verses
A Verse is a rule-bearing consensus graph. Aetheria Main can be a
@@ -378,5 +395,6 @@ hot frame bodies remain in the cheapest storage both endpoints can share.
- [Public API](docs/public-api.md)
- [Durable Node Quickstart](docs/durable-node-quickstart.md)
- [Typed Document Path](docs/typed-document-path.md)
+- [Distributed CDN Documents](docs/distributed-cdn.md)
- [Research Notes](docs/research.md)
- [Verse Model](docs/verses.md)
diff --git a/src/GameCult.Mesh/docs/distributed-cdn.md b/src/GameCult.Mesh/docs/distributed-cdn.md
new file mode 100644
index 00000000..fef4e276
--- /dev/null
+++ b/src/GameCult.Mesh/docs/distributed-cdn.md
@@ -0,0 +1,197 @@
+# Distributed CDN Documents
+
+CultMesh CDN artifacts are typed CultCache documents, not a separate asset
+transport. The same manifest and chunk records can be written by an asset
+pipeline daemon, replicated through CultNet raw snapshots or shard logs, and
+read by Unity, TypeScript, or another runtime that implements the CultCache
+document contract.
+
+This is the canonical path for moving Aetheria assets into CultLib. Starbridge
+Unity and Starbridge Electron should consume the same records so UI textures,
+map icons, environment layers, shaders, and build payloads do not fork by
+client.
+
+## Feature Overview
+
+The CDN feature has four layers:
+
+1. `CultMeshCdnArtifactManifest` describes one versioned payload.
+2. `CultMeshCdnArtifactChunk` stores content-addressed payload bytes.
+3. `CultMeshEntityPrefabPackage` describes a portable entity/prefab graph and
+ references CDN artifact manifests for meshes, textures, materials, animation,
+ audio, or other runtime payloads.
+4. Mesh asset sharing moves those signed manifests and chunks through central
+ servers, LAN peers, or internet peers without granting peers authority over
+ game state.
+
+This is not a Unity asset bundle system and not a raw FBX distribution system.
+Blender is the authoring ground truth for entity prefabs. Brokkr can mirror a
+legacy Unity prefab into Blender for migration, but the deployed CDN artifact is
+the Brokkr/Blender-authored snapshot lowered into CultMesh documents.
+
+Typical flow:
+
+1. Unity publishes a one-time `brokkr.unity.prefab_mirror_snapshot.v0` for an
+ existing prefab.
+2. Brokkr Blender imports that snapshot into a collection so artists can
+ configure renderable entity requirements in Blender.
+3. Brokkr Blender publishes a `brokkr.prefab.snapshot.v0` deploy snapshot from
+ the collection.
+4. A deployer packages referenced meshes, textures, and materials as CDN
+ artifacts.
+5. The deployer writes a `CultMeshEntityPrefabPackage` that references those CDN
+ artifact manifests.
+6. Unity, TypeScript, and later clients fetch the same package and lower it into
+ their runtime entity/component model.
+
+## Document Shape
+
+`CultMeshCdnArtifactManifest` is the versioned asset handle. It carries:
+
+- `ArtifactId`: logical id, such as `aetheria/ui/icons/minimap`.
+- `Kind`: `asset`, `build`, or `package`.
+- `Version`: caller-defined release or content version.
+- `ContentHash`: SHA-256 of the full materialized payload.
+- `SizeBytes`: full payload size.
+- `MimeType`: byte interpretation hint.
+- `Chunks`: ordered `CultMeshCdnChunkRef` placements.
+- `Tags` and `Metadata`: routing and domain hints.
+
+`CultMeshCdnArtifactChunk` is content-addressed by SHA-256. It carries only the
+chunk hash, byte count, and raw payload. Placement is deliberately in the
+manifest reference, so equal chunk bytes can be reused across assets and build
+updates.
+
+## Runtime Contract
+
+Clients should:
+
+1. Fetch or receive a manifest by record key, tag, or index.
+2. Fetch every chunk record referenced by `manifest.Chunks`.
+3. Verify each chunk hash before copying bytes.
+4. Reassemble chunks by `Offset`.
+5. Verify the full `ContentHash`.
+6. Interpret bytes according to `MimeType` plus domain metadata.
+
+Single-channel data stays single-channel. For example, a gravity map can use
+raw bytes with metadata such as `channels=r32` instead of pretending to be an
+RGBA texture.
+
+## Mesh Asset Sharing Policy
+
+CultMesh asset distribution is allowed to use installed clients as a peer asset
+cache because Aetheria cannot assume enough central infrastructure to serve all
+game files authoritatively. This must be visible to players and configurable in
+the client, but the initial product policy is opt-out rather than opt-in.
+
+The default policy should be:
+
+- Local cache is always enabled.
+- LAN asset sharing is enabled by default.
+- Internet peer asset sharing is enabled by default for signed asset chunks and
+ prefab packages.
+- Executable or build-update seeding is disabled by default until the UX and
+ signing story is mature.
+- Uploading is disabled or heavily throttled during gameplay.
+- Uploading has conservative default rate and daily caps.
+- Metered, cellular, battery-constrained, VPN, or corporate-network cases should
+ disable or throttle peer upload when detectable.
+- The client must expose a clear `Do not upload game assets to other players`
+ control.
+- The client must expose telemetry: cache size, current upload/download rate,
+ bytes served to peers, and bytes received from peers.
+
+Suggested runtime configuration:
+
+```csharp
+var policy = new MeshAssetSharingPolicy
+{
+ EnabledByDefault = true,
+ AllowLanPeers = true,
+ AllowInternetPeers = true,
+ AllowBuildArtifacts = false,
+ DisableDuringGameplay = true,
+ DisableOnMeteredNetwork = true,
+ RequireSignedManifests = true,
+ ShowStatusTelemetry = true
+};
+```
+
+Peers are never trusted as authority. They only serve bytes. Every chunk is
+content-addressed, every artifact is reconstructed from a manifest, and game
+clients must verify hashes and signatures before using the result.
+
+## C# Publishing
+
+```csharp
+var artifact = CultMesh.PackCdnArtifact(
+ "aetheria/environment/gravity/ragnarok",
+ gravityBytes,
+ new CultMeshCdnPackOptions
+ {
+ Kind = CultMeshCdnArtifactKinds.Asset,
+ Version = "2026.06.27",
+ MimeType = "application/octet-stream",
+ Tags = ["aetheria", "environment", "gravity"],
+ Metadata =
+ {
+ ["channels"] = "r32",
+ ["width"] = "1024",
+ ["height"] = "1024"
+ }
+ });
+
+await CultMesh.PublishCdnArtifactAsync(node.Cache, artifact);
+```
+
+For build distribution, use the same API with `Kind = CultMeshCdnArtifactKinds.Build`
+and metadata such as `platform=windows-x64` or `channel=internal`.
+
+## CultNet Replication
+
+CDN documents use the regular raw document lane:
+
+```csharp
+var registry = CultMesh.CreateCdnDocumentRegistry(node.Cache.Registry);
+var request = registry.CreateSnapshotRequest(
+ "cdn-request",
+ schemaIds:
+ [
+ node.Cache.Registry.GetRequired().SchemaId,
+ node.Cache.Registry.GetRequired().SchemaId
+ ],
+ recordKeys: artifact.RecordKeys.Select(key => key.Value));
+
+var response = registry.CreateRawSnapshotResponse(node.Cache, "cdn-response", request);
+```
+
+The TypeScript client should mirror the C# schema names, schema versions,
+record-key rules, chunk hashing, and verification order. C# remains the
+reference implementation.
+
+## Entity Prefabs
+
+Entity prefabs are distributed as Brokkr-authored snapshots, then deployed into
+portable CultMesh prefab packages. Brokkr's Blender UI publishes
+`brokkr.prefab.snapshot.v0` records for a collection-scoped prefab. A deployer
+can consume that snapshot, publish meshes/textures/material payloads as CDN
+artifacts, and write a `CultMeshEntityPrefabPackage` that references those
+artifact manifests.
+
+That keeps Blender as the authoring ground truth while avoiding Unity prefab
+files as the interchange format. Unity, TypeScript, and later runtimes unpack
+the same package graph into their native entity/component model.
+
+## Client Responsibilities
+
+Unity and TypeScript clients should implement the same rules:
+
+- Fetch prefab packages by record key, tag, or version catalog.
+- Fetch every referenced artifact manifest and chunk.
+- Verify signed manifests before trusting package membership.
+- Verify chunk hashes and full artifact hashes before import.
+- Cache artifacts locally by content hash.
+- Lower package nodes into local runtime objects without writing back Unity-owned
+ or Electron-owned prefab truth.
+- Respect `MeshAssetSharingPolicy` for peer upload, status telemetry, and
+ opt-out behavior.
diff --git a/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs b/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs
new file mode 100644
index 00000000..9a28a164
--- /dev/null
+++ b/tests/GameCult.Mesh.Tests/CultMeshCdnTests.cs
@@ -0,0 +1,123 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using FluentAssertions;
+using GameCult.Caching;
+using GameCult.Networking;
+using NUnit.Framework;
+
+namespace GameCult.Mesh.Tests;
+
+public sealed class CultMeshCdnTests
+{
+ [Test]
+ public async Task Artifact_PacksPublishesAndReassembles_FromCultCache()
+ {
+ var cache = new CultCache();
+ var payload = Encoding.UTF8.GetBytes("abcdefghijklmnopqrstuvwxyz");
+ var artifact = CultMesh.PackCdnArtifact(
+ "aetheria/ui/icons/minimap-pack",
+ payload,
+ new CultMeshCdnPackOptions
+ {
+ ChunkSizeBytes = 8,
+ Version = "2026.06.27",
+ MimeType = "application/octet-stream",
+ Tags = ["aetheria", "ui"],
+ Metadata = new Dictionary
+ {
+ ["channel"] = "dev"
+ }
+ });
+
+ artifact.Manifest.Kind.Should().Be(CultMeshCdnArtifactKinds.Asset);
+ artifact.Manifest.SizeBytes.Should().Be(payload.Length);
+ artifact.Manifest.Chunks.Should().HaveCount(4);
+ artifact.Manifest.Chunks.Select(chunk => chunk.Offset).Should().Equal(0, 8, 16, 24);
+ artifact.Manifest.Chunks.Select(chunk => chunk.SizeBytes).Should().Equal(8, 8, 8, 2);
+
+ var manifest = await CultMesh.PublishCdnArtifactAsync(cache, artifact);
+ var manifestKey = CultMeshCdnArtifactManifest.CreateRecordKey(manifest);
+ cache.Get(manifestKey).Should().NotBeNull();
+
+ var roundTrip = CultMesh.ReadCdnArtifact(cache, manifest);
+ roundTrip.Should().Equal(payload);
+ }
+
+ [Test]
+ public async Task BuildArtifact_Replicates_ThroughCultNetRawSnapshot()
+ {
+ var sourceCache = new CultCache();
+ var targetCache = new CultCache();
+ var registry = CultMesh.CreateCdnDocumentRegistry(sourceCache.Registry);
+ var payload = Encoding.UTF8.GetBytes("starbridge-build-update");
+ var artifact = CultMesh.PackCdnArtifact(
+ "starbridge/windows/client",
+ payload,
+ new CultMeshCdnPackOptions
+ {
+ ChunkSizeBytes = 7,
+ Kind = CultMeshCdnArtifactKinds.Build,
+ Version = "0.4.0-preview",
+ Tags = ["starbridge", "build"],
+ Metadata = new Dictionary
+ {
+ ["platform"] = "windows-x64"
+ }
+ });
+ var manifest = await CultMesh.PublishCdnArtifactAsync(sourceCache, artifact);
+ var manifestSchemaId = sourceCache.Registry.GetRequired().SchemaId;
+ var chunkSchemaId = sourceCache.Registry.GetRequired().SchemaId;
+ var recordKeys = artifact.RecordKeys.Select(key => key.Value).ToArray();
+
+ var request = registry.CreateSnapshotRequest(
+ "cdn-snapshot-request",
+ schemaIds: [manifestSchemaId, chunkSchemaId],
+ recordKeys: recordKeys);
+ var response = registry.CreateRawSnapshotResponse(sourceCache, "cdn-snapshot", request);
+
+ response.Documents.Should().HaveCount(artifact.Chunks.Count + 1);
+ response.Documents.Select(document => document.RecordKey).Should().BeEquivalentTo(recordKeys);
+
+ await registry.ApplyRawSnapshotResponseAsync(targetCache, response);
+ var replicatedManifest = targetCache.Get(
+ CultMeshCdnArtifactManifest.CreateRecordKey(manifest));
+ replicatedManifest.Should().NotBeNull();
+ replicatedManifest!.Kind.Should().Be(CultMeshCdnArtifactKinds.Build);
+ replicatedManifest.Metadata["platform"].Should().Be("windows-x64");
+
+ var roundTrip = CultMesh.ReadCdnArtifact(targetCache, replicatedManifest);
+ roundTrip.Should().Equal(payload);
+ }
+
+ [Test]
+ public async Task ArtifactRead_RejectsTamperedChunkPayload()
+ {
+ var cache = new CultCache();
+ var artifact = CultMesh.PackCdnArtifact(
+ "aetheria/gravity/layer0",
+ [1, 1, 2, 3, 5, 8],
+ new CultMeshCdnPackOptions
+ {
+ ChunkSizeBytes = 3,
+ Metadata = new Dictionary
+ {
+ ["channels"] = "r32"
+ }
+ });
+ var manifest = await CultMesh.PublishCdnArtifactAsync(cache, artifact);
+ var firstChunk = artifact.Chunks[0];
+ firstChunk.Payload[0] = 99;
+ await cache.UpsertAsync(
+ firstChunk,
+ new CultRecordHandle(
+ CultMeshCdnArtifactChunk.CreateRecordKey(firstChunk)));
+
+ Action read = () => CultMesh.ReadCdnArtifact(cache, manifest);
+ read.Should().Throw()
+ .WithMessage("*chunk hash*");
+ }
+}
diff --git a/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs b/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs
new file mode 100644
index 00000000..ec8bbcf7
--- /dev/null
+++ b/tests/GameCult.Mesh.Tests/CultMeshEntityPrefabTests.cs
@@ -0,0 +1,197 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using FluentAssertions;
+using GameCult.Caching;
+using NUnit.Framework;
+
+namespace GameCult.Mesh.Tests;
+
+public sealed class CultMeshEntityPrefabTests
+{
+ [Test]
+ public async Task EntityPrefabPackage_PublishesBrokkrAuthoredGraph_WithCdnAssetRefs()
+ {
+ var cache = new CultCache();
+ var meshArtifact = CultMesh.PackCdnArtifact(
+ "aetheria/prefabs/ships/scout/mesh/body",
+ Encoding.UTF8.GetBytes("portable-mesh-bytes"),
+ new CultMeshCdnPackOptions
+ {
+ Version = "authoring-1",
+ MimeType = "model/gltf-binary",
+ Tags = ["brokkr", "mesh"],
+ });
+ var textureArtifact = CultMesh.PackCdnArtifact(
+ "aetheria/prefabs/ships/scout/texture/albedo",
+ Encoding.UTF8.GetBytes("texture-bytes"),
+ new CultMeshCdnPackOptions
+ {
+ Version = "authoring-1",
+ MimeType = "image/png",
+ Tags = ["brokkr", "texture"],
+ });
+ await CultMesh.PublishCdnArtifactAsync(cache, meshArtifact);
+ await CultMesh.PublishCdnArtifactAsync(cache, textureArtifact);
+
+ var package = CultMesh.FinalizeEntityPrefabPackage(new CultMeshEntityPrefabPackage
+ {
+ PrefabId = "aetheria/entity/ship/scout",
+ Version = "authoring-1",
+ SourceTool = "brokkr.blender",
+ SourceScene = "ships.blend",
+ SourceCollection = "prefab.ship.scout",
+ Tags = ["aetheria", "ship", "brokkr"],
+ Assets =
+ [
+ AssetRef("mesh.body", CultMeshEntityPrefabAssetRoles.Mesh, meshArtifact.Manifest),
+ AssetRef("texture.albedo", CultMeshEntityPrefabAssetRoles.Texture, textureArtifact.Manifest)
+ ],
+ Nodes =
+ [
+ new CultMeshEntityPrefabNode
+ {
+ NodeId = "root",
+ Name = "Scout",
+ Kind = CultMeshEntityPrefabNodeKinds.Empty,
+ Tags = ["entity-root"],
+ Components =
+ [
+ new CultMeshEntityPrefabComponent
+ {
+ Type = "aetheria.ship",
+ Properties = new Dictionary
+ {
+ ["hullClass"] = "scout"
+ }
+ }
+ ]
+ },
+ new CultMeshEntityPrefabNode
+ {
+ NodeId = "body",
+ Name = "Body",
+ ParentNodeId = "root",
+ Kind = CultMeshEntityPrefabNodeKinds.Mesh,
+ MeshAssetId = "mesh.body",
+ MaterialAssetIds = ["texture.albedo"],
+ Transform = new CultMeshEntityPrefabTransform
+ {
+ Position = [0f, 0f, 0f],
+ Rotation = [0f, 0f, 0f, 1f],
+ Scale = [1f, 1f, 1f]
+ }
+ }
+ ],
+ Metadata = new Dictionary
+ {
+ ["authoringAxis"] = "blender",
+ ["runtimeLowering"] = "unity,ts"
+ }
+ });
+
+ await CultMesh.PublishEntityPrefabPackageAsync(cache, package);
+
+ var key = CultMeshEntityPrefabPackage.CreateRecordKey(package);
+ var stored = cache.Get(key);
+ stored.Should().NotBeNull();
+ stored!.SourceTool.Should().Be("brokkr.blender");
+ stored.SourceCollection.Should().Be("prefab.ship.scout");
+ stored.Nodes.Should().Contain(node => node.Kind == CultMeshEntityPrefabNodeKinds.Mesh);
+ stored.Assets.Select(asset => asset.CdnManifestRecordKey)
+ .Should()
+ .Contain(meshArtifact.ManifestKey.Value)
+ .And.Contain(textureArtifact.ManifestKey.Value);
+ }
+
+ [Test]
+ public async Task EntityPrefabPackage_ReplicatesWithReferencedCdnArtifacts_ThroughRawSnapshot()
+ {
+ var sourceCache = new CultCache();
+ var targetCache = new CultCache();
+ var registry = CultMesh.CreateAssetPipelineDocumentRegistry(sourceCache.Registry);
+ var meshArtifact = CultMesh.PackCdnArtifact(
+ "aetheria/prefabs/projectiles/bolt/mesh",
+ Encoding.UTF8.GetBytes("bolt-mesh"),
+ new CultMeshCdnPackOptions { Version = "v1", MimeType = "model/gltf-binary" });
+ await CultMesh.PublishCdnArtifactAsync(sourceCache, meshArtifact);
+
+ var package = CultMesh.FinalizeEntityPrefabPackage(new CultMeshEntityPrefabPackage
+ {
+ PrefabId = "aetheria/entity/projectile/bolt",
+ Version = "v1",
+ SourceTool = "brokkr.blender",
+ SourceScene = "projectiles.blend",
+ SourceCollection = "prefab.projectile.bolt",
+ Assets = [AssetRef("mesh", CultMeshEntityPrefabAssetRoles.Mesh, meshArtifact.Manifest)],
+ Nodes =
+ [
+ new CultMeshEntityPrefabNode
+ {
+ NodeId = "bolt",
+ Name = "Bolt",
+ Kind = CultMeshEntityPrefabNodeKinds.Mesh,
+ MeshAssetId = "mesh",
+ Components =
+ [
+ new CultMeshEntityPrefabComponent
+ {
+ Type = "aetheria.projectile",
+ Properties = new Dictionary
+ {
+ ["damage"] = "10"
+ }
+ }
+ ]
+ }
+ ]
+ });
+ await CultMesh.PublishEntityPrefabPackageAsync(sourceCache, package);
+
+ var packageSchema = sourceCache.Registry.GetRequired().SchemaId;
+ var manifestSchema = sourceCache.Registry.GetRequired().SchemaId;
+ var chunkSchema = sourceCache.Registry.GetRequired().SchemaId;
+ var recordKeys = new[] { CultMeshEntityPrefabPackage.CreateRecordKey(package) }
+ .Concat(meshArtifact.RecordKeys)
+ .Select(key => key.Value)
+ .ToArray();
+
+ var request = registry.CreateSnapshotRequest(
+ "entity-prefab-request",
+ schemaIds: [packageSchema, manifestSchema, chunkSchema],
+ recordKeys: recordKeys);
+ var response = registry.CreateRawSnapshotResponse(sourceCache, "entity-prefab-response", request);
+
+ response.Documents.Should().HaveCount(meshArtifact.Chunks.Count + 2);
+ await registry.ApplyRawSnapshotResponseAsync(targetCache, response);
+
+ var replicatedPackage = targetCache.Get(
+ CultMeshEntityPrefabPackage.CreateRecordKey(package));
+ replicatedPackage.Should().NotBeNull();
+ replicatedPackage!.Nodes.Single().Components.Single().Type.Should().Be("aetheria.projectile");
+
+ var meshManifest = targetCache.Get(meshArtifact.ManifestKey);
+ meshManifest.Should().NotBeNull();
+ CultMesh.ReadCdnArtifact(targetCache, meshManifest!).Should().Equal(Encoding.UTF8.GetBytes("bolt-mesh"));
+ }
+
+ private static CultMeshEntityPrefabAssetRef AssetRef(
+ string assetId,
+ string role,
+ CultMeshCdnArtifactManifest manifest)
+ {
+ return new CultMeshEntityPrefabAssetRef
+ {
+ AssetId = assetId,
+ Role = role,
+ CdnManifestRecordKey = CultMeshCdnArtifactManifest.CreateRecordKey(manifest).Value,
+ ContentHash = manifest.ContentHash,
+ MimeType = manifest.MimeType,
+ Metadata = new Dictionary
+ {
+ ["sourceArtifactId"] = manifest.ArtifactId
+ }
+ };
+ }
+}