Make Eve onboarding one coherent game

This commit is contained in:
Meta Vens 2026-08-18 06:05:15 +02:00
commit e74ba6e94c
9 changed files with 161 additions and 152 deletions

View file

@ -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.

View file

@ -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<CounterState>());
using var node = await CultMesh.StartNodeAsync("world.cc", new CultMeshNodeOptions
{
DatabaseOptions = new CultNetDatabaseOptions
{
RuntimeId = "counter-provider",
DocumentRegistry = documents
}
});
var player = await node.Database.GetAsync<PlayerData>(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<CounterState>(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<DaemonHealth>(
"daemon-publication.ccmp",
"daemon-publication.cc",
new CultRecordKey("daemon:aetheria.health.v1"),
verse);

View file

@ -55,7 +55,7 @@ var key = new CultRecordKey("note:intro");
var documents = new CultNetDocumentRegistry()
.Register(CultNetDocumentBinding.ForDocument<MeshNote>());
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

View file

@ -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<CounterState>(
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).

View file

@ -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<CounterState>(
"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).

View file

@ -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`.

View file

@ -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.

View file

@ -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

View file

@ -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
{