From e74ba6e94c26c6b4ba13dbbfd320914aa498ea93 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 18 Aug 2026 06:05:15 +0200 Subject: [PATCH] Make Eve onboarding one coherent game --- samples/eve-two-runtime/README.md | 11 +- src/GameCult.Mesh/README.md | 23 +++- .../docs/durable-node-quickstart.md | 8 +- .../getting-started/01-persist-typed-state.md | 71 ++++++++-- .../getting-started/02-connect-by-identity.md | 12 +- .../04-keep-a-typescript-provider-alive.md | 122 ------------------ .../04-run-the-multiruntime-game.md | 60 +++++++++ .../docs/getting-started/README.md | 4 +- src/GameCult.Mesh/docs/typed-document-path.md | 2 +- 9 files changed, 161 insertions(+), 152 deletions(-) delete mode 100644 src/GameCult.Mesh/docs/getting-started/04-keep-a-typescript-provider-alive.md create mode 100644 src/GameCult.Mesh/docs/getting-started/04-run-the-multiruntime-game.md diff --git a/samples/eve-two-runtime/README.md b/samples/eve-two-runtime/README.md index c149e14e..0981ad1a 100644 --- a/samples/eve-two-runtime/README.md +++ b/samples/eve-two-runtime/README.md @@ -29,8 +29,9 @@ temporary consumer, and runs `sample.mjs`. Success proves: 4. the DOM binding and a separate headless observer converge on the same count; 5. the canonical receipt and state survive reopening the `.cc` store. -This is not yet the promised networked multiplayer tutorial. The DOM lowerer is -hosted by jsdom in Node and both consumers share one local CultMesh node. A real -browser transport, Odin discovery, process separation, and a second language -runtime require distinct executable gates. Keeping that limitation visible is -part of the sample contract. +This artifact checkpoint is deliberately not the network proof. The DOM lowerer +is hosted by jsdom in Node and both consumers share one local CultMesh node. The +same wrapper continues into a separate real Chromium/C# process chronology with +Odin discovery, route replacement, and persistent provider state. Keeping those +evidence layers separate prevents a fast package test from impersonating the +network. diff --git a/src/GameCult.Mesh/README.md b/src/GameCult.Mesh/README.md index b0ff9e06..8acb6c9d 100644 --- a/src/GameCult.Mesh/README.md +++ b/src/GameCult.Mesh/README.md @@ -18,12 +18,25 @@ simulation observations. ## First Node ```csharp +using GameCult.Caching; using GameCult.Mesh; +using GameCult.Networking; -using var node = await CultMesh.StartNodeAsync("world.ccmp"); +// CounterState is the typed document defined in the getting-started tutorial. +var documents = new CultNetDocumentRegistry() + .Register(CultNetDocumentBinding.ForDocument()); +using var node = await CultMesh.StartNodeAsync("world.cc", new CultMeshNodeOptions +{ + DatabaseOptions = new CultNetDatabaseOptions + { + RuntimeId = "counter-provider", + DocumentRegistry = documents + } +}); -var player = await node.Database.GetAsync(playerKey); -await node.Database.PutAsync(playerKey, player); +var key = new CultRecordKey("counter:main"); +await node.Database.PutAsync(key, new CounterState { CounterId = key.Value }); +var counter = await node.Database.GetAsync(key); ``` If you want one inspectable path that starts with a durable local cache file and @@ -88,7 +101,7 @@ Enable durable authoritative shard logs when a node should serve replica catch-up after restart: ```csharp -using var node = await CultMesh.StartNodeAsync("world.ccmp", new CultMeshNodeOptions +using var node = await CultMesh.StartNodeAsync("world.cc", new CultMeshNodeOptions { EnableDurableShardLogs = true }); @@ -240,7 +253,7 @@ shape without local store plumbing: ```csharp var health = CultMesh.DocumentFromSingleFile( - "daemon-publication.ccmp", + "daemon-publication.cc", new CultRecordKey("daemon:aetheria.health.v1"), verse); diff --git a/src/GameCult.Mesh/docs/durable-node-quickstart.md b/src/GameCult.Mesh/docs/durable-node-quickstart.md index 3d08ae0f..f85fac97 100644 --- a/src/GameCult.Mesh/docs/durable-node-quickstart.md +++ b/src/GameCult.Mesh/docs/durable-node-quickstart.md @@ -55,7 +55,7 @@ var key = new CultRecordKey("note:intro"); var documents = new CultNetDocumentRegistry() .Register(CultNetDocumentBinding.ForDocument()); -using (var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions +using (var node = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions { DatabaseOptions = new CultNetDatabaseOptions { @@ -76,7 +76,7 @@ using (var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeO await node.FlushAsync(); } -using (var reopened = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions +using (var reopened = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions { DatabaseOptions = new CultNetDatabaseOptions { @@ -92,7 +92,7 @@ using (var reopened = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshN What happened: -1. `CultMesh.CreateNodeAsync("world.ccmp", ...)` opened a durable CultCache +1. `CultMesh.CreateNodeAsync("world.cc", ...)` opened a durable CultCache snapshot file and wrapped it in a CultMesh node. 2. `node.Database.PutAsync(...)` wrote a typed document through the public CultMesh database surface. @@ -105,7 +105,7 @@ What happened: If you peel this path apart, the authority split stays simple: -- CultCache: `world.ccmp`, schema ids, record keys, typed document payloads, +- CultCache: `world.cc`, schema ids, record keys, typed document payloads, local indexes, flush/load - CultNet: `CultNetDocumentRegistry`, raw document puts/snapshots, subscriptions, shard routing, transport-facing replication diff --git a/src/GameCult.Mesh/docs/getting-started/01-persist-typed-state.md b/src/GameCult.Mesh/docs/getting-started/01-persist-typed-state.md index b2fce2a0..6e2d2b3b 100644 --- a/src/GameCult.Mesh/docs/getting-started/01-persist-typed-state.md +++ b/src/GameCult.Mesh/docs/getting-started/01-persist-typed-state.md @@ -1,22 +1,71 @@ -# 1. Persist Typed Application State +# 1. Persist The Counter -Start with a typed CultCache document and a durable CultMesh node. The complete -sample is [the durable node quickstart](../durable-node-quickstart.md). +The tutorial builds one application all the way through: a provider-owned +counter, an Increment operation, one browser lowerer, and one C# headless +client. Start with the state the provider actually owns. -At the end of that guide you should have: +```csharp +using GameCult.Caching; +using GameCult.Caching.MessagePack; +using GameCult.Networking; +using MessagePack; -- a document type with a stable schema id; -- a `CultMeshNode` whose database owns the live local document; -- a `.cc`/CultCache-backed durable state path; -- a restart proof that reads the same typed document. +[CultDocument("sample.counter_state", "sample.counter_state.v1")] +[MessagePackObject] +public sealed class CounterState +{ + [Key("counterId")] public string CounterId { get; set; } = ""; + [Key("count")] public int Count { get; set; } +} +``` -Do not create an Eve-shaped copy of this state. The Eve surface published in -chapter 3 points at typed records and commands owned by the provider. +Open a `.cc` store, register the document once, and write through the CultMesh +database boundary: -Verification: +```csharp +var key = new CultRecordKey("counter:main"); +var registry = CultDocumentRegistry.ForTypes([typeof(CounterState)]); + +using var cache = await CultCacheMessagePack.OpenAsync("counter.cc", new CultCacheOpenOptions +{ + Registry = registry, + FlushOnDispose = true, + StoreFlushOnDispose = true +}); +var documents = new CultNetDocumentRegistry(registry) + .Register(CultNetDocumentBinding.ForDocument( + registry, + "sample.counter_state.v1")); +using var database = new CultNetDatabase(cache, new CultNetDatabaseOptions +{ + RuntimeId = "sample.counter-provider", + DocumentRegistry = documents +}); + +await database.PutAsync(key, new CounterState +{ + CounterId = key.Value, + Count = 0 +}); +await cache.FlushAsync(); +``` + +CultCache owns durable local truth. CultNet owns the portable schema mapping. +CultMesh exposes the database and later carries subscriptions and operations. +The renderer owns none of them. + +The executable provider adds its receipt index to this document so the counter +mutation and idempotency decision are committed together. See +[`samples/eve-browser-network/Program.cs`](../../../../samples/eve-browser-network/Program.cs) +for the exact running type and transaction. + +Fast persistence check: ```powershell dotnet test tests/GameCult.Networking.Tests/GameCult.Networking.Tests.csproj --filter FullyQualifiedName~CultMeshNode_CanRoundTrip_DurableTypedDocument_Through_PublicDatabaseSurface ``` +This check proves the local typed state boundary. Chapter 4 boots the real +provider and proves the same state across Chromium and C# after restart. + Next: [connect a client by stable identity](02-connect-by-identity.md). diff --git a/src/GameCult.Mesh/docs/getting-started/02-connect-by-identity.md b/src/GameCult.Mesh/docs/getting-started/02-connect-by-identity.md index b7c636d4..8dffffaa 100644 --- a/src/GameCult.Mesh/docs/getting-started/02-connect-by-identity.md +++ b/src/GameCult.Mesh/docs/getting-started/02-connect-by-identity.md @@ -1,6 +1,8 @@ # 2. Connect A Client By Stable Identity -Clients address a provider or Verse by stable identity. Discovery owns the +Clients address a Verse session by stable identity. In this tutorial, +`sample.counter-provider` is the sole authority runtime Odin advertises for the +`sample.counter` Verse; neither identity is a socket address. Discovery owns current physical candidates and the session manager owns connection reuse, path rotation, and transport failure state. @@ -13,7 +15,7 @@ using var mesh = new CultMeshClient(new CultMeshClientOptions }); using var counterLease = await mesh.LeaseDocumentAsync( - "sample.counter-provider", + "sample.counter", "counter:main", cancellationToken); var counter = counterLease.Handle; @@ -49,7 +51,8 @@ using var stateWatch = session.WatchState().Subscribe(state => Application code does not reconnect, sleep, rank endpoints, or replace the session. Those decisions belong to CultMesh. -Verification: +Fast session-management check (this uses controlled transports; it is not the +network proof): ```powershell dotnet test tests/GameCult.Mesh.Tests/GameCult.Mesh.Tests.csproj --filter FullyQualifiedName~CultMeshSessionManagerTests @@ -59,4 +62,7 @@ Advanced hosts may inject lookup sources, connectors, clocks, persistence, and diagnostics through the lower-level discovery and session APIs. Application features should not need them. +Chapter 4 runs the real network chronology and proves that the retained lease +survives Odin moving `sample.counter` to a new physical provider route. + Next: [publish one Eve surface to multiple runtimes](03-publish-an-eve-surface.md). diff --git a/src/GameCult.Mesh/docs/getting-started/04-keep-a-typescript-provider-alive.md b/src/GameCult.Mesh/docs/getting-started/04-keep-a-typescript-provider-alive.md deleted file mode 100644 index 15f10a3a..00000000 --- a/src/GameCult.Mesh/docs/getting-started/04-keep-a-typescript-provider-alive.md +++ /dev/null @@ -1,122 +0,0 @@ -# 4. Keep A TypeScript Provider Alive - -A provider process should declare desired typed publications and domain command -handlers once. It should not rebuild discovery registration, lease renewal, -reconnect, republish, receipt delivery, and withdrawal loops in a renderer or -scheduled export script. - -`CultMeshProviderSession` owns that lifecycle. The application still owns its -state and command transaction. A transport connector owns the physical CultNet -route. Eve advertisements and surfaces are ordinary typed publications; the -session does not import Eve or learn provider gameplay. - -```ts -import { - CultMeshProviderSession, - type CultMeshProviderReceiptStore, - type CultMeshProviderTransport, -} from "cultmesh-ts"; - -export async function runProvider( - transport: CultMeshProviderTransport, - receipts: CultMeshProviderReceiptStore, -) { - const provider = new CultMeshProviderSession({ - identity: { - providerId: "voidbot.swarm", - serviceInstanceId: "voidbot-worker-7", - endpointId: "odin:voidbot-worker-7", - verseId: "voidbot.local", - }, - transport, - receiptStore: receipts, - publications: [ - { - publicationId: "voidbot.swarm.advertisement", - documentType: "gamecult.eve.provider_advertisement", - schemaId: "gamecult.eve.provider_advertisement.v1", - recordKey: "voidbot.swarm", - value: providerAdvertisement, - }, - { - publicationId: "voidbot.swarm.surface", - documentType: "gamecult.eve.surface_state", - schemaId: "gamecult.eve.surface_state.v1", - recordKey: "voidbot.swarm", - value: currentSurface, - }, - ], - commandHandlers: { - "swarm.set_heat": async command => - applyHeatCommandTransaction(command.commandId, command.payload), - }, - }); - - await provider.start(); - - await provider.upsertPublication({ - publicationId: "voidbot.swarm.surface", - documentType: "gamecult.eve.surface_state", - schemaId: "gamecult.eve.surface_state.v1", - recordKey: "voidbot.swarm", - value: nextSurface, - }); - - process.once("SIGTERM", () => { - provider.stop().catch(error => { - console.error("CultMesh provider shutdown completed with cleanup failures.", error); - process.exitCode = 1; - }); - }); -} -``` - -The four identities are deliberately distinct: - -- `providerId` names the product capability clients select; -- `serviceInstanceId` names the running owner incarnation; -- `endpointId` names the stable discovery/session route. -- `verseId` names the discovery and state-sharing domain. - -Do not replace any of them with a process id, socket address, body producer id, -or renderer id. - -## Receipt Rule - -The receipt store is required and must be durable in a daemon. The in-memory -store exported by the package is for tests and disposable tools only. The -domain command handler must apply its mutation idempotently using `commandId`; -the provider session deduplicates delivery and republishes the stored typed -receipt, but it cannot make an unrelated database mutation atomic by wishing -at it harder. `commandId` is the idempotency key: later delivery of the same -provider, service-instance, and command kind returns the original receipt even -if a sender incorrectly changes the payload. Reusing the ID for another kind -or identity is rejected as a conflict. - -The store is also the receipt outbox. `put` commits the receipt before any wire -publication. `listPending` supplies receipts after startup or reconnect, and -`markPublished` removes one only after the active connection accepts it. Scope -the store to the provider and service-instance identity. If the store is -unavailable, the session enters `degraded` and stops accepting commands until a -renewal can drain the outbox again; a store failure is not a transport failure. - -## Verification Checkpoint - -Use an injected scheduler and transport fault double to prove the actual -lifecycle: - -1. initial registration publishes every desired document in stable order; -2. lease renewal occurs before expiry; -3. a failed route produces `reconnecting`, then republishes current desired - state on the replacement connection; -4. duplicate command delivery runs one handler transaction and republishes the - same receipt; -5. failed receipt transport reconnects and replays the durable outbox exactly - until `markPublished` succeeds; -6. shutdown drains command persistence, withdraws the lease and remaining - publications, and closes even when cleanup reports failures; -7. stopping during registration cannot let the stale connection publish; -8. observers and conflicting command IDs cannot become lifecycle authorities. - -The package suite contains this timeline in -`packages/cultmesh-ts/test/provider-session.test.ts`. diff --git a/src/GameCult.Mesh/docs/getting-started/04-run-the-multiruntime-game.md b/src/GameCult.Mesh/docs/getting-started/04-run-the-multiruntime-game.md new file mode 100644 index 00000000..cb921ea1 --- /dev/null +++ b/src/GameCult.Mesh/docs/getting-started/04-run-the-multiruntime-game.md @@ -0,0 +1,60 @@ +# 4. Run The Multi-Runtime Game + +The counter is now one small multiplayer game: + +- a C# provider owns `CounterState`, Increment, idempotency, receipts, the + `.cc` store, and the Eve surface; +- Chromium discovers that provider through Odin, lowers the surface, and + invokes Increment; +- an independent C# client leases the same counter and invokes through the same + typed operation boundary; +- both clients remain attached when Odin moves the provider identity to a new + physical route. + +Run the whole chronology from the CultLib checkout: + +```powershell +pwsh -File ./scripts/verify-eve-getting-started.ps1 +``` + +The command owns setup and teardown. Do not start Odin, the provider, or the +browser by hand. A successful run prints two JSON records followed by: + +```text +Eve getting-started verification passed: clean artifacts, DOM and headless convergence, real Chromium and C# clients, Odin discovery, receipts, persistence, and route replacement. +``` + +## What The Command Proves + +The first checkpoint packs the TypeScript CultCache, CultNet, CultMesh, and Eve +packages, installs those artifacts into an empty temporary consumer, and proves +DOM/headless convergence plus `.cc` reopen. This rejects a sample that only +works through repository-relative source imports. + +The second checkpoint boots separate Odin, provider, Chromium, and C# headless +processes. Chromium performs the first increment. The provider then restarts on +a different route, Odin advertises the replacement, and the retained clients +resubscribe without application reconnect code. C# performs the second +increment. Both clients must observe count 2 and both canonical receipt ids. + +Finally, the retained C# session sends 10,000 typed no-op operations. The gate +records throughput, p99 latency, managed-heap growth, and private-memory growth. +It fails at 250 ms p99 or more than 8 MiB post-GC managed growth. + +## What It Does Not Prove + +The included Odin is a real CultNet Verse-catalog provider but still a local +fixture. It does not prove deployed GameCult infrastructure. The package layer +uses packed checkout artifacts until the package owners publish the named npm +packages. Those are explicit release gates, not reasons to put endpoint or +source-tree fallbacks into application code. + +The process harness lives in +[`samples/eve-browser-network`](../../../../samples/eve-browser-network/README.md). +Application code should copy the typed state, operation, and Eve composition +shape—not its benchmark flags or fixture orchestration. + +For a TypeScript provider daemon, continue with the +[`CultMeshProviderSession` guide](../../../../packages/cultmesh-ts/README.md#long-lived-providers). +That lifecycle is an alternative provider runtime for the same ownership +model, not a fifth chapter that changes this tutorial into a different product. diff --git a/src/GameCult.Mesh/docs/getting-started/README.md b/src/GameCult.Mesh/docs/getting-started/README.md index 5251c7ca..d09d10e2 100644 --- a/src/GameCult.Mesh/docs/getting-started/README.md +++ b/src/GameCult.Mesh/docs/getting-started/README.md @@ -29,7 +29,7 @@ Follow the chapters in order: 1. [Persist typed application state](01-persist-typed-state.md) 2. [Connect a client by stable identity](02-connect-by-identity.md) 3. [Publish one Eve surface to multiple runtimes](03-publish-an-eve-surface.md) -4. [Keep a TypeScript provider alive](04-keep-a-typescript-provider-alive.md) +4. [Run the multi-runtime game](04-run-the-multiruntime-game.md) The intended application shape is small: @@ -39,6 +39,8 @@ provider daemon -> typed CultCache documents -> CultMesh advertisement +------------------------+--------------------+ | | | Eve browser EveUnity another lowerer + | | | + player input player input headless / AI ``` The provider owns live truth. Eve owns the surface contract. Each runtime owns diff --git a/src/GameCult.Mesh/docs/typed-document-path.md b/src/GameCult.Mesh/docs/typed-document-path.md index 3ee3183c..aab47930 100644 --- a/src/GameCult.Mesh/docs/typed-document-path.md +++ b/src/GameCult.Mesh/docs/typed-document-path.md @@ -109,7 +109,7 @@ messages directly. ```csharp using GameCult.Mesh; -using var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions +using var node = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions { DatabaseOptions = new CultNetDatabaseOptions {