From 3720a8d39d37e2b8a98d74b38fb01cba9ff2af39 Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Sat, 27 Jun 2026 18:30:17 +0100
Subject: [PATCH] Add snapshot endpoint document bindings

---
 src/GameCult.Mesh/CultMeshSnapshots.cs        | 71 +++++++++++++++++++
 .../CultMeshStreamingTests.cs                 |  4 +-
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/src/GameCult.Mesh/CultMeshSnapshots.cs b/src/GameCult.Mesh/CultMeshSnapshots.cs
index eb60a8d6..62978b35 100644
--- a/src/GameCult.Mesh/CultMeshSnapshots.cs
+++ b/src/GameCult.Mesh/CultMeshSnapshots.cs
@@ -83,6 +83,55 @@ namespace GameCult.Mesh
         public TimeSpan PollInterval { get; set; } = TimeSpan.FromMilliseconds(250);
     }
 
+    /// <summary>
+    /// Describes one typed document handle to bind from a snapshot endpoint.
+    /// </summary>
+    public interface ICultMeshSnapshotDocumentBinding
+    {
+        /// <summary>Gets the CLR document type requested by this binding.</summary>
+        Type DocumentType { get; }
+
+        /// <summary>Gets the remote record key to read.</summary>
+        string RecordKey { get; }
+
+        /// <summary>Gets the optional semantic document id for the resulting handle.</summary>
+        string? DocumentId { get; }
+
+        /// <summary>Binds this document request to an endpoint-backed handle.</summary>
+        ICultMeshDocumentHandle Bind(CultMeshSnapshotEndpoint endpoint);
+    }
+
+    /// <summary>
+    /// Describes one typed document handle to bind from a snapshot endpoint.
+    /// </summary>
+    public sealed class CultMeshSnapshotDocumentBinding<TDocument> : ICultMeshSnapshotDocumentBinding
+        where TDocument : class
+    {
+        internal CultMeshSnapshotDocumentBinding(string recordKey, string? documentId)
+        {
+            RecordKey = string.IsNullOrWhiteSpace(recordKey)
+                ? throw new ArgumentException("Value must be non-empty.", nameof(recordKey))
+                : recordKey;
+            DocumentId = documentId;
+        }
+
+        /// <inheritdoc />
+        public Type DocumentType => typeof(TDocument);
+
+        /// <inheritdoc />
+        public string RecordKey { get; }
+
+        /// <inheritdoc />
+        public string? DocumentId { get; }
+
+        /// <inheritdoc />
+        public ICultMeshDocumentHandle Bind(CultMeshSnapshotEndpoint endpoint)
+        {
+            if (endpoint == null) throw new ArgumentNullException(nameof(endpoint));
+            return endpoint.Document<TDocument>(RecordKey, DocumentId);
+        }
+    }
+
     /// <summary>
     /// Result from syncing a remote snapshot into a local CultMesh node.
     /// </summary>
@@ -266,6 +315,17 @@ namespace GameCult.Mesh
             return CultMesh.Documents(documents);
         }
 
+        /// <summary>Creates a schema-aware catalog from endpoint-backed typed document bindings.</summary>
+        public CultMeshDocumentCatalog Documents(params ICultMeshSnapshotDocumentBinding[] documents)
+        {
+            if (documents == null) throw new ArgumentNullException(nameof(documents));
+            return CultMesh.Documents(documents.Select(document =>
+            {
+                if (document == null) throw new ArgumentNullException(nameof(documents));
+                return document.Bind(this);
+            }));
+        }
+
         private CultMeshSnapshotRequestOptions CreateRequest(
             IReadOnlyList<string>? schemaIds,
             IReadOnlyList<string>? recordKeys)
@@ -318,6 +378,17 @@ namespace GameCult.Mesh
             return new CultMeshSnapshotEndpoint(endpoint, options);
         }
 
+        /// <summary>
+        /// Describes one typed document to bind from a CultMesh snapshot endpoint.
+        /// </summary>
+        public static CultMeshSnapshotDocumentBinding<TDocument> SnapshotDocument<TDocument>(
+            string recordKey,
+            string? documentId = null)
+            where TDocument : class
+        {
+            return new CultMeshSnapshotDocumentBinding<TDocument>(recordKey, documentId);
+        }
+
         /// <summary>
         /// Fetches one scoped raw CultNet snapshot from an endpoint.
         /// </summary>
diff --git a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
index 6f8fae18..01443beb 100644
--- a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
+++ b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
@@ -1221,13 +1221,15 @@ public sealed class CultMeshStreamingTests
         var syncedAlias = await surface.SyncDocumentAsync<MeshNoteAliasDocument>(node, key.Value);
         var aliasHandle = surface.Document<MeshNoteAliasDocument>(key.Value);
         var aliasLatest = await aliasHandle.LatestAsync();
-        var catalog = surface.Documents(surface.Document<MeshNoteDocument>(key.Value));
+        var catalog = surface.Documents(
+            CultMesh.SnapshotDocument<MeshNoteDocument>(key.Value, "daemon:mesh-note:snapshot-endpoint"));
         var catalogAlias = await catalog.LatestAsync<MeshNoteAliasDocument>();
 
         fetchedAlias.Text.Should().Be("snapshot-endpoint");
         syncedAlias.Text.Should().Be("snapshot-endpoint");
         node.Cache.Get<MeshNoteDocument>(key)!.Revision.Should().Be(19);
         aliasLatest.Revision.Should().Be(19);
+        catalog.Document<MeshNoteDocument>().DocumentId.Should().Be("daemon:mesh-note:snapshot-endpoint");
         catalogAlias.Text.Should().Be("snapshot-endpoint");
         requests.Should().HaveCount(4);
         requests.Should().OnlyContain(request =>