From e2ea266136af9bd632061b52dc761937399025dd Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Tue, 16 Jun 2026 10:43:54 +0100
Subject: [PATCH] Add Kotlin schema shard facade sugar

---
 docs/cultnet-transport-parity.md              | 12 +++----
 packages/cultmesh-kotlin/README.md            |  2 ++
 .../kotlin/org/gamecult/cultmesh/CultMesh.kt  | 34 +++++++++++++++++++
 3 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md
index b642bc0a..513ed858 100644
--- a/docs/cultnet-transport-parity.md
+++ b/docs/cultnet-transport-parity.md
@@ -293,12 +293,12 @@ Current progress:
   max in-flight frame pressure, latest-frame cursors, and watch callbacks for
   stream declarations plus latest-frame publication.
 - Kotlin now has a branded `CultMesh` facade matching the C#/TypeScript/Python
-  entrypoint pattern for local nodes, Verse catalogs, peer catalogs, authority
-  lease catalogs, stream catalogs, and RUDP client/server construction. Kotlin
-  also parses advertised `rudp://host:port` endpoints and can build a RUDP
-  client directly from a peer card contact hint. The facade delegates to the
-  same owners as the top-level helpers instead of creating a second authority
-  path.
+  entrypoint pattern for local nodes, schema catalogs, shard catalogs, Verse
+  catalogs, peer catalogs, authority lease catalogs, stream catalogs, and RUDP
+  client/server construction. Kotlin also parses advertised
+  `rudp://host:port` endpoints and can build a RUDP client directly from a peer
+  card contact hint. The facade delegates to the same owners as the top-level
+  helpers instead of creating a second authority path.
 - Kotlin authority lease catalogs now also expose watch callbacks, so JVM and
   Android clients can react to lease changes without treating peer-card contact
   hints as trust.
diff --git a/packages/cultmesh-kotlin/README.md b/packages/cultmesh-kotlin/README.md
index 98015d31..1fbcdd94 100644
--- a/packages/cultmesh-kotlin/README.md
+++ b/packages/cultmesh-kotlin/README.md
@@ -14,6 +14,8 @@ val verses = CultMesh.createVerseCatalog()
 val peers = CultMesh.createPeerCatalog()
 val leases = CultMesh.createAuthorityLeaseCatalog()
 val streams = CultMesh.createStreamCatalog()
+val schemas = CultMesh.createSchemaCatalog()
+val shards = CultMesh.createShardCatalog()
 ```
 
 ## CultCache Happy Path
diff --git a/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt b/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt
index 63389c28..11f1055f 100644
--- a/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt
+++ b/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt
@@ -285,6 +285,10 @@ object CultMesh {
 
     fun createStreamCatalog(): CultMeshStreamCatalog = CultMeshStreamCatalog()
 
+    fun createSchemaCatalog(): CultNetSchemaCatalog = CultNetSchemaCatalog()
+
+    fun createShardCatalog(): CultNetShardCatalog = CultNetShardCatalog()
+
     fun createRudpServer(
         runtimeId: String,
         connectionId: Long,
@@ -2671,6 +2675,36 @@ private fun cultMeshFacadeRoutesErgonomicEntrypoints() {
 
     val streams = CultMesh.createStreamCatalog()
     check(streams.streams.isEmpty())
+
+    val schemas = CultMesh.createSchemaCatalog()
+    schemas.upsert(
+        defineCultNetSchemaDescriptor(
+            schemaId = notes.schemaVersion,
+            kind = "document_payload",
+            documentType = notes.documentType,
+            title = "Facade Note",
+            schemaJson = """{"type":"string"}""",
+        ),
+    )
+    check(schemas.get(notes.schemaVersion)?.documentType == notes.documentType)
+
+    val shards = CultMesh.createShardCatalog()
+    shards.upsert(
+        CultNetShardDescriptor(
+            shardId = "facade-shard",
+            ownerRuntimeId = "facade-owner",
+            epoch = 1,
+            isPrimary = true,
+            schemaIds = listOf(notes.schemaVersion),
+            keyPrefix = "note:",
+        ),
+    )
+    check(
+        shards.list(
+            schemaIds = listOf(notes.schemaVersion),
+            recordKeys = listOf("note:facade"),
+        ).single().shardId == "facade-shard",
+    )
 }
 
 private fun cultCacheRawSnapshotsRoundTripThroughCultNetMessages() {