cultcache.store.v1!epiphany.repo_personality_profile!epiphany.repo_personality_profile$epiphany.repo_personality_profile.v1!epiphany.repo_personality_profilev{"schemaName":"epiphany.repo_personality_profile","schemaVersion":"epiphany.repo_personality_profile.v1","members":[]}!epiphany.repo_personality_profileepiphany.repo_terrain_reportepiphany.repo_terrain_reportepiphany.repo_terrain_report.v1epiphany.repo_terrain_reportl{"schemaName":"epiphany.repo_terrain_report","schemaVersion":"epiphany.repo_terrain_report.v1","members":[]}epiphany.repo_terrain_reportepiphany.repo_trajectory_reportepiphany.repo_trajectory_report"epiphany.repo_trajectory_report.v1epiphany.repo_trajectory_reportr{"schemaName":"epiphany.repo_trajectory_report","schemaVersion":"epiphany.repo_trajectory_report.v1","members":[]}epiphany.repo_trajectory_report$epiphany.role_personality_projection$epiphany.role_personality_projection'epiphany.role_personality_projection.v1$epiphany.role_personality_projection|{"schemaName":"epiphany.role_personality_projection","schemaVersion":"epiphany.role_personality_projection.v1","members":[]}$epiphany.role_personality_projectioncultlib!epiphany.repo_personality_profile2026-06-14T18:16:10Z)$epiphany.repo_personality_profile.v0cultlibCultLib projects as cult_protocol_storage + gamecult_web_lore_ops + unity_runtime_body with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00, content_canon_bias:0.90, sensory_salience:0.88, protocol_intolerance:0.85.cult_protocol_storage?O;dZgamecult_web_lore_ops?O;dZunity_runtime_body?O;dZactuation_risk?9XbMӲaesthetic_appetite?Sٱboundary_severity? =p burstiness?+ Jchurn_spiral_risk?"`Bconsolidation_drive?$/content_canon_bias?Econtract_strictness?editorial_restraint?nevidence_appetite?Vuexperimental_heat?C$ݫguardedness??|hsinitiative_drive?nPinterface_orientation?mood_lability?xFnovelty_hunger?XbMproduction_pressure?Ͼvȴ9Xprotocol_intolerance?333333rumination_bias?QRruntime_proximity?sensory_salience?1&xծsocial_surface?tjsource_fidelity?\(ïspeech_pressure?XbMstate_hygiene?|hrtemporal_pressure?+verification_environment_need?C$actuation_risk?aesthetic_appetite?boundary_severity?burstiness?churn_spiral_risk?consolidation_drive?content_canon_bias?contract_strictness?editorial_restraint?evidence_appetite?experimental_heat?guardedness?initiative_drive?interface_orientation?mood_lability?novelty_hunger?production_pressure?protocol_intolerance?rumination_bias?runtime_proximity?sensory_salience?social_surface?source_fidelity?speech_pressure?state_hygiene?temporal_pressure?verification_environment_need?contract_strictness:1.00interface_orientation:1.00runtime_proximity:1.00content_canon_bias:0.90sensory_salience:0.88protocol_intolerance:0.85actuation_risk:0.51'epiphany.role_personality_projection.v0cultlib::coordinatorcultlibcoordinatorboundary_severity˿$/churn_spiral_risk˿$/contract_strictness?333333production_pressure˿Sstate_hygiene˿tj~ۂcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QيSelf should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.LAdapt Self behavior to CultLib without storing project facts in role memory.LCoordinate through typed authority and challenge pattern-completion theater.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::facecultlibfaceeditorial_restraint?A7Kƨinterface_orientation?333333sensory_salience?hr!social_surface˿^5?|푯speech_pressure˿7KƧcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QيFace should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.LAdapt Face behavior to CultLib without storing project facts in role memory.USurface state through the public mouth without turning internals into chat endpoints.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::imaginationcultlibimaginationaesthetic_appetite?hr Ĝchurn_spiral_risk˿$/content_canon_bias?+ experimental_heat˿tjnovelty_hunger˿7KƧcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QّImagination should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.SAdapt Imagination behavior to CultLib without storing project facts in role memory.STurn future-shape pressure into drafts and plans, not accidental active objectives.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::researchcultlibresearchnovelty_hunger˿7KƧprotocol_intolerance?Gzruntime_proximity?333333source_fidelity?Sٽverification_environment_need?hr ĜcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QيEyes should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.LAdapt Eyes behavior to CultLib without storing project facts in role memory.%Find existing truth before invention.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::modelingcultlibmodelingcontent_canon_bias?+ contract_strictness?333333runtime_proximity?333333source_fidelity?S٭state_hygiene˿tj~ۂcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QٔProprioception should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.VAdapt Proprioception behavior to CultLib without storing project facts in role memory.-Build source-grounded maps before Hands cuts.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::implementationcultlibimplementationactuation_risk?pbMchurn_spiral_risk˿$/consolidation_drive˿contract_strictness?333333production_pressure˿ScooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QًHands should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.MAdapt Hands behavior to CultLib without storing project facts in role memory.5Leave reviewable diffs or explicit failure artifacts.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy history'epiphany.role_personality_projection.v0cultlib::verificationcultlibverificationactuation_risk?pbMcontent_canon_bias?+ evidence_appetite?\(õinterface_orientation?333333verification_environment_need?hr ĜcooldownMultiplierDelta˿vȴ9XinitiativeSpeedDelta˿anxiety?r ěcuriosity?Eurgency?QيSoul should treat CultLib as a repo with dominant pressures: contract_strictness:1.00, interface_orientation:1.00, runtime_proximity:1.00.LAdapt Soul behavior to CultLib without storing project facts in role memory.9Demand receipts from the environment that owns the claim.\Projection is deterministic and confidence-scored at 1.00; Self must review before mutation.VRole projection from repo terrain, commit history, and persisted doctrine for CultLib.Iactuation_risk: runtime, auth, ops, or service writes can hurt real usersFaesthetic_appetite: visual, lore, rendered, or artifact-heavy surfacesHboundary_severity: auth, ops, workspace, protocol, or service boundaries;burstiness: sampled commits compressed into few active daysBchurn_spiral_risk: large churn, experiment heat, and weak receiptsOconsolidation_drive: refactor/remove/extract keywords or deletion-heavy historycultlibepiphany.repo_terrain_report2026-06-14T18:15:59Z6|epiphany.repo_terrain_report.v0cultlibCultLib\\?\E:\Projects\CultLib'https://github.com/GameCult/CultLib.gitcult_protocol_storagegamecult_web_lore_opsunity_runtime_body.jsona.csS.md,.asset.ts.prefab.png.csproj.mat .rs .html.ttf.voidbot/state/README.md.voidbot/state/libby.ccAGENTS.md'-packages/cultcache-ts/test/cult-cache.test.ts(packages/cultcache-ts/tsconfig.test.json*packages/cultmesh-ts/test/cultmesh.test.ts'packages/cultmesh-ts/tsconfig.test.json$packages/cultnet-rs/tests/cultnet.rs9packages/cultnet-rs/tests/fixtures/cultnet-ts-hello.frame@packages/cultnet-rs/tests/fixtures/cultnet-ts-legacy-login.frame(packages/cultnet-ts/test/cultnet.test.ts8packages/cultnet-ts/test/interop/cultnet-interop-peer.ts:packages/cultnet-ts/test/interop/cultnet-interop-shared.ts8packages/cultnet-ts/test/interop/cultnet-interop.test.ts&packages/cultnet-ts/tsconfig.test.json@research/cultnet-distributed-database/dynamo-amazon-science.htmlMsrc/GameCult.Networking/Contracts/cultnet.witness-artifact-bundle.schema.json4src/GameCult.Networking/CultWitnessArtifactBundle.csMsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Fill.pngUsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Outline-Half.pngPsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Outline.pngDsrc/GameCult.Unity/Assets/UI/Resources/Materials/ColorCircle_HCY.matDsrc/GameCult.Unity/Assets/UI/Resources/Materials/ColorCircle_HSL.matDsrc/GameCult.Unity/Assets/UI/Resources/Materials/ColorCircle_HSV.mat7src/GameCult.Unity/Assets/UI/Shaders/ColorCircle.shaderFtests/GameCult.Caching.InteropPeer/GameCult.Caching.InteropPeer.csproj-tests/GameCult.Caching.InteropPeer/Program.cs1tests/GameCult.Caching.Tests/BackingStoreTests.cs:tests/GameCult.Caching.Tests/GameCult.Caching.Tests.csproj&tests/GameCult.Caching.Tests/README.mdNtests/GameCult.Geometry.Tests/Fixtures/vg-csg-ragnarok/ragnarok-domain.msgpackStests/GameCult.Geometry.Tests/Fixtures/vg-csg-ragnarok/ragnarok-first-chunk.msgpacksrc/GameCult.Unity/Assets/Plugins/AutoExpandGridLayoutGroup.cs2src/GameCult.Unity/Assets/Resources/Settings.assetMsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Fill.pngUsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Outline-Half.pngPsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Circle-Outline.pngPsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Rectangle-Fill.pngXsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Rectangle-Outline-Half.pngSsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Rectangle-Outline.pngQsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Tab-Bottom-Fill.pngTsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Tab-Bottom-Outline.pngNsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Tab-Top-Fill.pngQsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/32px/Flat-Tab-Top-Outline.pngAsrc/GameCult.Unity/Assets/Resources/Sprites/Flat UI/areaFade1.png4src/GameCult.Unity/Assets/Resources/Sprites/nail.png0src/GameCult.Unity/Assets/Resources/particle.hdr0src/GameCult.Unity/Assets/Resources/particle.mat2src/GameCult.Unity/Assets/Scenes/SampleScene.unityWsrc/GameCult.Unity/Assets/Scenes/SampleScene_Profiles/Post-process Volume Profile.asset*src/GameCult.Unity/Assets/UI/Attributes.cs/src/GameCult.Unity/Assets/UI/ColorConversion.cs4src/GameCult.Unity/Assets/UI/Components/BoolField.cs6src/GameCult.Unity/Assets/UI/Components/ButtonField.cs7src/GameCult.Unity/Assets/UI/Components/ClickCatcher.cs5src/GameCult.Unity/Assets/UI/Components/ColorModal.cs>src/GameCult.Unity/Assets/UI/Components/ConstrainedSlider2D.cs4src/GameCult.Unity/Assets/UI/Components/EnumField.cs;src/GameCult.Unity/Assets/UI/Components/GeneratorFoldout.cs:src/GameCult.Unity/Assets/UI/Components/HorizontalGroup.cs9src/GameCult.Unity/Assets/UI/Components/IncrementField.cs5src/GameCult.Unity/Assets/UI/Components/InputField.cs0src/GameCult.Unity/Assets/UI/Components/Label.cs:src/GameCult.Unity/Assets/UI/Components/LayoutComponent.cs0src/GameCult.Unity/Assets/UI/Components/Modal.cs8src/GameCult.Unity/Assets/UI/Components/ProgressField.cssrc/GameCult.Unity/Assets/UI/Resources/Sprites/Icons/check.png>src/GameCult.Unity/Assets/UI/Resources/Sprites/Icons/cross.png?src/GameCult.Unity/Assets/UI/Resources/Sprites/Icons/remove.pngCsrc/GameCult.Unity/Assets/UI/Resources/Sprites/Icons/rightArrow.png7src/GameCult.Unity/Assets/UI/Shaders/ColorCircle.shader:src/GameCult.Unity/Assets/UI/Shaders/ColorConversion.cginc7src/GameCult.Unity/Assets/UI/Shaders/ColorSlider.shader0src/GameCult.Unity/Assets/UI/StringExtensions.cs#src/GameCult.Unity/Assets/UI/UI.txt)src/GameCult.Unity/Assets/UI/package.json)src/GameCult.Unity/Assets/packages.config1src/GameCult.Unity/GameCult.Unity.sln.DotSettings5src/GameCult.Unity/ProjectSettings/AudioManager.assetprototype, experiment, scaffold, or research-workbench signalsguardedness*authority and mutation risk demand cautioninitiative_drive>work pressure and experiment heat increase heartbeat readinessinterface_orientation4UI, web, Tauri, component, DOM, or Aquarium surfacesmood_lability4risk, urgency, and churn make reactions swing hardernovelty_hunger/experimental and aesthetic exploration pressureproduction_pressure fix/deploy/auth/queue/CI signalsprotocol_intolerance@strict contract surfaces imply low tolerance for ad hoc mutationrumination_bias@state hygiene and consolidation favor distillation before actionruntime_proximity&Unity/editor/runtime/provider surfacessensory_salience:motion, visuals, rendered outputs, scenes, or UI organismssocial_surface;Discord, auth, accounts, public site, or service boundariessource_fidelity1state maps, lore/canon, or runtime truth surfacesspeech_pressure%public speech or user-facing surfacesstate_hygiene1state, map, evidence, handoff, or memory surfacestemporal_pressure9service, runtime, queue, or live-provider timing pressureverification_environment_needCclaims need runtime, editor, browser, provider, or service receipts?cultlibepiphany.repo_trajectory_report2026-06-14T18:16:10ZP@"epiphany.repo_trajectory_report.v0cultlibCultLib is currently steered by worldbuilding_depth recent 0.00, current 0.50, delta 0.00; material_grounding recent 0.00, current 0.40, delta 0.00; historical_dialectic recent 0.00, current 0.50, delta 0.00.CultLib behaves like a cult_protocol_storage + gamecult_web_lore_ops + unity_runtime_body workspace that has been moving toward systems_formalization, worldbuilding_depth, historical_dialectic.'Seed Libby social interpretation biases Add CultCache geometry documents2Prove geometry documents replicate through CultNet.Align geometry document fingerprints with Rust4Exercise geometry chunks through CultMesh node state%Document geometry state over CultMesh$Verify Rust geometry payload interop-Bring language packages into CultLib monorepo$Document CultLib language workspaces$Add Kotlin CultMesh client substrate Add Kotlin Eve surface contracts)Add Kotlin Eve media observation contract"Page CultCache MessagePack records#Add CultMesh streaming mode surface!Add C# CultMesh streaming surface,Keep Huginn runtime out of CultCache packageAdd CultCache SoA happy path'Make SoA cache-managed document storage'Make SoA cache-managed document storageAdd CultCache SoA happy path,Keep Huginn runtime out of CultCache package!Add C# CultMesh streaming surface#Add CultMesh streaming mode surface"Page CultCache MessagePack records)Add Kotlin Eve media observation contract Add Kotlin Eve surface contracts$Add Kotlin CultMesh client substrate$Document CultLib language workspaces-Bring language packages into CultLib monorepo$Verify Rust geometry payload interop%Document geometry state over CultMesh4Exercise geometry chunks through CultMesh node state.Align geometry document fingerprints with Rust2Prove geometry documents replicate through CultNet Add CultCache geometry documents'Seed Libby social interpretation biasesAGENTS.mddoctrine# AGENTS.md ## Repository Guidance - Refrain from commenting on current changes in README files unless the user explicitly asks for that commentary. - Treat clean API surface as a core project priority. - Favor developer ergonomics in public APIs, examples, naming, defaults, and documentation. - Prefer interfaces and behaviors that are predictable, easy to discover, and easy to integrate correctly. - Keep public abstractions small and coherent; avoid exposing internal workflow complexity through the API when it can be encapsulated. - When adding documentation or examples, optimize for practical usage by downstream developers. - When proposing or implementing changes, consider how they affect usability, readability, and maintenance for library consumers. README.mdreadme2#(# CultLib CultLib is a set of reusable C# libraries for game backends, game-adjacent services, and Unity-integrated tooling, including a declarative runtime UI composition framework for Unity. The libraries cover three main areas: - logging primitives and implementations - a typed in-memory cache with pluggable persistence - LiteNetLib-based networking with encrypted credential exchange and signed session tokens - CultMesh distributed realtime database and simulation-consensus primitives - typed geometry domain/chunk documents for distributed CSG and LOD streaming - declarative Unity UI composition and reflective runtime inspector tooling ## Which Package Do I Want? If the job is shared game state, start here before inventing a fourth drawer and pretending the label makes it furniture. | Job | Start With | Owns | Use When | Do Not Use It For | | --- | --- | --- | --- | --- | | Local typed state | `GameCult.Caching` / CultCache | Document identity, schema compatibility, record keys, indexes, globals, and local persistence | You need a typed cache, file-compatible save data, local reactive reads, or a stable domain document model | Peer discovery, transport security, shard routing, or mesh consensus | | Procedural geometry state | `GameCult.Geometry` | CultCache-native domain trees, LOD build requests, selected-cut diagnostics, and chunk artifact payloads | Rust, Unity, or remote workers need to share CSG/LOD geometry and graph metadata as typed state | Transport policy, peer discovery, or gameplay authority | | Network transport and database plumbing | `GameCult.Networking` / CultNet | LiteNetLib transport, authentication, schema-v0 wire contracts, shard authority, raw document replication, snapshots, and subscriptions | You need a client/server pipe, login/session flow, schema discovery, or a low-level distributed CultCache lane | Gameplay-facing mesh ergonomics, Verse policy, mod branches, or simulation consensus composition | | Distributed realtime gameplay state | `GameCult.Mesh` / CultMesh | Public mesh entrypoints, Verse discovery, peer exchange, shard replication defaults, authority leases, client prediction, and witness consensus | You want the game to treat clients and servers as one reactive database for persistent state, input state, and simulation facts | A tiny local-only tool, a bare transport client, or a storage format contract | | Realtime media/frame streams | `GameCult.Mesh` / CultMesh streaming mode | Stream identity, authority, clock metadata, body transport negotiation, frame cursors, and backpressure state | Audio/video/tensor frames need to move between runtimes through shared memory, GPU handles, platform buffers, or CultCache page refs | Durable document mutation, mesh consensus facts, or pretending inline bytes are zero-copy | Quick rule: - Choose CultCache when the problem is "how do I model and persist typed state?" - Choose GameCult.Geometry when the problem is "how do geometry workers share domain trees, LOD build requests, and mesh chunks as typed state?" - Choose CultNet when the problem is "how do peers exchange authenticated, schema-aware database messages?" - Choose CultMesh when the problem is "how does a game join a Verse and share realtime state across a mesh?" - Choose CultMesh streaming mode when the problem is "how do these runtimes move audio/video frames while the mesh owns identity, clocks, cursors, and pressure?" CultMesh sits on CultNet, and CultNet distributes CultCache documents. That is the stack. If a design needs another peer-to-peer category, first check whether it is really Verse policy, peer exchange, or shard authority wearing a fake mustache. If you want the smallest durable "open node -> put typed doc -> get typed doc" path, start with [`src/GameCult.Mesh/docs/durable-node-quickstart.md`](src/GameCult.Mesh/docs/durable-node-quickstart.md). If you want the lower-level "typed local document -> raw wire document -> mesh/runtime watch surface" handoff, follow it with [`src/GameCult.Mesh/docs/typed-document-path.md`](src/GameCult.Mesh/docs/typed-document-path.md). ## Repository Scope The solution includes: - `GameCult.Logging`: common logging abstraction plus console and file implementations - `GameCult.Caching`: `DatabaseEntry`-based cache, indexes, global entries, and backing-store abstractions - `GameCult.Caching.MessagePack`: MessagePack-backed persistence for the cache - `GameCult.Caching.NewtonsoftJson`: Newtonsoft.Json-backed persistence for the cache - `GameCult.Caching.MessagePack.Generator`: source generator for MessagePack formatters for cache models - `GameCult.Caching.MessagePack.Analyzers`: packaging project that delivers the generator to consuming projects - `GameCult.Geometry`: CultCache-native geometry domain, selected-cut, and chunk artifact documents for VibeGeometry/Fensalir-style pipelines - `GameCult.Networking`: encrypted login/register/verify flows and message dispatch over LiteNetLib - `GameCult.Mesh`: CultMesh package home for distributed realtime database, shard replication, client prediction, Verse discovery, and mesh witness consensus - `GameCult.Caching.Tests`: NUnit tests for cache and backing-store behavior - `GameCult.Networking.Tests`: NUnit tests for networking behavior - `GameCult.Unity`: CultUI, a Unity runtime UI composition framework with reflective inspector generation, prefab-backed field resolvers, reusable controls, and a demo project packaged for UPM-style consumption - `packages/cultcache-ts`: TypeScript CultCache with MessagePack persistence and inspector tooling - `packages/cultnet-ts`: TypeScript CultNet schema-v0 contracts, framing, discovery, raw document replication, and interop tests - `packages/cultmesh-ts`: TypeScript CultMesh local node and mesh catalog surface for local runtimes such as VoidBot - `packages/cultcache-rs`: Rust CultCache and derive macro - `packages/cultnet-rs`: Rust CultNet contracts, framing, discovery, and interop peer ## Repository Layout ```text package.json src/ GameCult.Logging/ GameCult.Caching/ GameCult.Caching.MessagePack/ GameCult.Caching.NewtonsoftJson/ GameCult.Caching.MessagePack.Generator/ GameCult.Caching.MessagePack.Analyzers/ GameCult.Geometry/ GameCult.Networking/ GameCult.Mesh/ GameCult.Unity/ tests/ GameCult.Caching.Tests/ GameCult.Geometry.Tests/ GameCult.Networking.Tests/ packages/ cultcache-ts/ cultnet-ts/ cultmesh-ts/ cultcache-rs/ cultnet-rs/ ``` ## Build ```powershell dotnet build CultLib.sln ``` ## Test ```powershell dotnet test CultLib.sln ``` TypeScript package tests: ```powershell npm test --workspace packages/cultcache-ts npm test --workspace packages/cultnet-ts npm run test:interop --workspace packages/cultnet-ts npm test --workspace packages/cultmesh-ts ``` Rust package tests: ```powershell cargo test --manifest-path packages/cultcache-rs/Cargo.toml cargo test --manifest-path packages/cultnet-rs/Cargo.toml ``` ## Common Concepts ### `DatabaseEntry` The cache-centric libraries revolve around `DatabaseEntry`. Every entry has a stable `Guid` identifier and can optionally: - expose a human-readable name through `INamedEntry` - participate in generic indexes registered at runtime - be treated as a global singleton entry through `GlobalSettingsAttribute` Typical entry shape: ```csharp using GameCult.Caching; public class ItemData : DatabaseEntry, INamedEntry { public string Name = string.Empty; public int Value; public string EntryName { get => Name; set => Name = value; } } ``` ### `CultCache` and Backing Stores `CultCache` is an in-memory index over `DatabaseEntry` objects. It can operate entirely in memory, or it can be attached to one or more backing stores for persistence and synchronization. - the cache is the query surface - backing stores are persistence adapters - indexes and name maps are maintained inside the cache, not inside the store ### Important: Multiple Backing Stores When multiple backing stores are added, behavior depends on how they are registered. If a store is added with domain types: ```csharp cache.AddBackingStore(playerStore, typeof(PlayerData)); cache.AddBackingStore(settingsStore, typeof(AppSettings)); ``` then that store becomes the direct persistence target for those types. If a store is added without domain types: ```csharp cache.AddBackingStore(primaryStore); cache.AddBackingStore(mirrorStore); ``` then the first generic store acts as the primary writable store for non-domain-specific entries. Additional generic stores subscribe to the existing stores and mirror their change events. Implications: - order matters for generic stores - `AddAsync` writes to the type-specific store when one exists - otherwise `AddAsync` writes to the first generic store - later generic stores do not become co-primaries; they mirror earlier snotes/operator-interventions.mddocumentation# Operator Interventions ## 2026-05-08 - External Codex session from `E:\Projects\EpiphanyAgent` added `src/GameCult.Caching/Contracts/cultcache-persistence-format.md`. - Intent: write down the next canonical CultCache persistence-format design in the C# source-of-truth repo before Rust/TS implementations harden the wrong shape. - Existing unrelated worktree changes in `src/GameCult.Networking/PlayerData.cs` and `src/GameCult.Unity/Assets/UI/Default Resolver.asset` were left alone. .research/cultnet-distributed-database/swim.pdfresearch&%PDF-1.2 %���� 35 0 obj << /Linearized 1 /O 37 /H [ 5122 1132 ] /L 133069 /E 57214 /N 10 /T 132251 >> endobj xref 35 235 0000000016 00000 n 0000005049 00000 n 0000006254 00000 n 0000006560 00000 n 0000006625 00000 n 0000006733 00000 n 0000006839 00000 n 0000006928 00000 n 0000006949 00000 n 0000010404 00000 n 0000011912 00000 n 0000012019 00000 n 0000012133 00000 n 0000013163 00000 n 0000013184 00000 n 0000013270 00000 n 0000014189 00000 n 0000014210 00000 n 0000015099 00000 n 0000015120 00000 n 0000016100 00000 n 0000016121 00000 n 0000017102 00000 n 0000017123 00000 n 0000018048 00000 n 0000018069 00000 n 0000018962 00000 n 0000018983 00000 n 0000019160 00000 n 0000019376 00000 n 0000019596 00000 n 0000019775 00000 n 0000020079 00000 n 0000020316 00000 n 0000020565 00000 n 0000020804 00000 n 0000021022 00000 n 0000021309 00000 n 0000021545 00000 n 0000021802 00000 n 0000022011 00000 n 0000022242 00000 n 0000022541 00000 n 0000022803 00000 n 0000023071 00000 n 0000023314 00000 n 0000023507 00000 n 0000023741 00000 n 0000023918 00000 n 0000024149 00000 n 0000024370 00000 n 0000024616 00000 n 0000024867 00000 n 0000025088 00000 n 0000025292 00000 n 0000025507 00000 n 0000025716 00000 n 0000025929 00000 n 0000026147 00000 n 0000026371 00000 n 0000026595 00000 n 0000026816 00000 n 0000026994 00000 n 0000027221 00000 n 0000027434 00000 n 0000027662 00000 n 0000027942 00000 n 0000028200 00000 n 0000028467 00000 n 0000028709 00000 n 0000028982 00000 n 0000029259 00000 n 0000029466 00000 n 0000029722 00000 n 0000030047 00000 n 0000030301 00000 n 0000030538 00000 n 0000030776 00000 n 0000031062 00000 n 0000031265 00000 n 0000031503 00000 n 0000031755 00000 n 0000031947 00000 n 0000032198 00000 n 0000032449 00000 n 0000032686 00000 n 0000032934 00000 n 0000033141 00000 n 0000033445 00000 n 0000033644 00000 n 0000033858 00000 n 0000034127 00000 n 0000034339 00000 n 0000034560 00000 n 0000034775 00000 n 0000034982 00000 n 0000035194 00000 n 0000035416 00000 n 0000035673 00000 n 0000035949 00000 n 0000036236 00000 n 0000036520 00000 n 0000036754 00000 n 0000037025 00000 n 0000037312 00000 n 0000037500 00000 n 0000037755 00000 n 0000037977 00000 n 0000038211 00000 n 0000038499 00000 n 0000038710 00000 n 0000038921 00000 n 0000039188 00000 n 0000039405 00000 n 0000039619 00000 n 0000039839 00000 n 0000040059 00000 n 0000040320 00000 n 0000040563 00000 n 0000040805 00000 n 0000041093 00000 n 0000041327 00000 n 0000041588 00000 n 0000041846 00000 n 0000042141 00000 n 0000042404 00000 n 0000042658 00000 n 0000042860 00000 n 0000043103 00000 n 0000043356 00000 n 0000043625 00000 n 0000043694 00000 n 0000043763 00000 n 0000043832 00000 n 0000043901 00000 n 0000043970 00000 n 0000044039 00000 n 0000044108 00000 n 0000044177 00000 n 0000044246 00000 n 0000044315 00000 n 0000044384 00000 n 0000044453 00000 n 0000044522 00000 n 0000044591 00000 n 0000044660 00000 n 0000044729 00000 n 0000044798 00000 n 0000044867 00000 n 0000044936 00000 n 0000045005 00000 n 0000045074 00000 n 0000045143 00000 n 0000045212 00000 n 0000045281 00000 n 0000045350 00000 n 0000045419 00000 n 0000045488 00000 n 0000045557 00000 n 0000045626 00000 n 0000045695 00000 n 0000045765 00000 n 0000045835 00000 n 0000045905 00000 n 0000045975 00000 n 0000046045 00000 n 0000046115 00000 n 0000046185 00000 n 0000046254 00000 n 0000046323 00000 n 0000046392 00000 n 0000046461 00000 n 0000046530 00000 n 0000046599 00000 n 0000046668 00000 n 0000046737 00000 n 0000046806 00000 n 0000046875 00000 n 0000046944 00000 n 0000047013 00000 n 0000047082 00000 n 0000047151 00000 n 0000047401 00000 n 0000047662 00000 n 0000047901 00000 n 0000048126 00000 n 0000048349 00000 n 0000048575 00000 n 0000048822 00000 n 0000049044 00000 n 0000049277 00000 n 0000049515 00000 n 0000049741 00000 n 0000050062 00000 n 0000050309 00000 n 0000050544 00000 n 0000050777 00000 n 0000051018 00000 n 0000051204 00000 n 0000051424 00000 n 0000051681 00000 n 0000051915 00000 n 0000052162 00000 n 0000052408 00000 n 0000052653 00000 n 0000052885 00000 n 0000053111 00000 n 0000053312 00000 n 0000053381 00000 n 0000053450 00000 n 0000053519 00000 n 0000053588 00000 n 0000053657 00000 n 0000053726 00000 n 0000053795 00000 n 0000053864 00000 n 0000053933 00000 n 0000054002 00000 n 0000054071 00000 n 0000054140 00000 n 0000054209 00000 n 0000054488 00000 n 0000054762 00000 n 0000054987 00000 n 0000055221 00000 n 0000055431 00000 n 0000055668 00000 n 0000055737 00000 n 0000055806 00000 n 0000055875 00000 n 0000055944 00000 n 0000056013 00000 n 0000056082 00000 n 0000005122 00000 n 0000006231 00000 n trailer << /Size 270 /Info 33 0 R /Root 36 0 R /Prev 132241 /ID[] >> startxref 0 %%EOF 36 0 obj << /Type /Catalog /Pages 32 0 R /Metadata 34 0 R >> endobj 268 0 obj << /S 2996 /Filter /FlateDecode /Length 269 0 R >> stream H�b```f`ab�``�\� ��@1�'p�5u L���MY�8XED.21_�|��k׮_�`�������QRJFZNV^UQIAEYW]CSK[�HO��P�������������������������;���? 0(8$4,<"2*:&6.>!1)9%5-=#3+�07/����������������������������������I��L�6}��Y��̝7��E��,]�|��U�׬]�~��M��lݶ}��]���ݷ���C��=v���S�Ϝ=w���K��\�v���[��ܽw���G��<�d�`gafd�������UPTRVQՇxJW��)cTO99�@=�G�S9���:D����'�)F&v6N��,/^�y [J�� *��0���9�x������/D��A�=v���s��RC���gt�᫂�I��9؆��@q����2�|��񜅙�񕔬��������������v�������������������������������������㓟�ꫦ����F��Z;�&��L���;e��S���֕����߶e��};��=~����O;}��]��^�y����7.]���έ{g��~�����O89����bfyJ�HNUAQZYE �)=CdO;(�=E(��rr� PV�j~�P����+zY%�F/���gC}�b`q�[2'`kq=+���KH?���f�(��ւP�kKϳ&�� 0�710�00�g`>��������0���8�Ciކ'� � ,��w`����w�kx��*��x�Ӱ�Ga�Q� �y��<8����7� v�m4��p�w"'w�M���| �xs/��V8�߰������<���(�ʿ����τ��q?���p���8?�=ދܼ�. �+����������$`CX<�g��s�υG<��N8+t�o��Ky ��<�x�kp���^��<�r_�1wpaY�2G �X��_ endstream endobj 269 0 obj 1021 endobj 37 0 obj << /Type /Page /MediaBox [ 0 0 612 792 ] /Parent 32 0 R /Resources << /ProcSet [ /PDF /ImageB /Text ] /Font << /R13 49 0 R /A 43 0 R /R8 45 0 R /R7 39 0 R /R6 40 0 R >> >> /Contents [ 47 0 R 50 0 R 52 0 R 54 0 R 56 0 R 58 0 R 60 0 R 267 0 R ] /CropBox [ 0 0 612 792 ] /Rotate 0 >> endobj 38 0 obj << /Type /Encoding /Differences [ 2 /fi ] >> endobj 39 0 obj << /Type /Font /Name /R7 /Subtype /Type1 /BaseFont /Times-Italic /Encoding 38 0 R >> endobj 40 0 obj << /Type /Font /Name /R6 /Subtype /Type1 /BaseFont /Times-Bold /Encoding 41 0 R >> endobj 41 0 obj << /Type /Encoding /Differences [ 2 /fi 150 /endash 173 /hyphen ] >> endobj 42 0 obj 952 endobj 43 0 obj << /Type /Font /Name /A /Subtype /Type3 /Encoding 44 0 R /FirstChar 0 /LastChar 204 /CharProcs << /a203 129 0 R /a202 130 0 R /a201 128 0 R /a200 126 0 R /a199 127 0 R /a198 131 0 R /a195 135 0 R /a194 136 0 R /a193 137 0 R /a192 134 0 R /a190 132 0 R /a189 133 0 R /a187 125 0 R /a186 117 0 R /a185 118 0 R /a183 116 0 R /a182 114 0 R /a181 115 0 R /a180 119 0 R /a179 123 0 R /a178 124 0 R /a177 122 0 R /a176 120 0 R /a175 121 0 R /a174 138 0 R /a173 155 0 R /a171 156 0 R /a170 154 0 R /a169 152 0 R /a168 153 0 R /a167 157 0 R /a166 161 0 R /a165 162 0 R /a164 163 0 R /a163 160 0 R /a162 158 0 R /a161 159 0 R /a160 151 0 R /a154 142 0 R /a152 143 0 R /a151 141 0 R /a150 139 0 R /a148 140 0 R /a147 144 0 R /a146 148 0 R /a145 149 0 R /a143 113 0 R /a141 147 0 R /a139 145 0 R /a138 146 0 R /a137 150 0 R /a135 79 0 R /a133 80 0 R /a132 78 0 R /a131 76 0 R /a130 77 0 R /a128 81 0 R /a127 85 0 R /a124 86 0 R /a121 75 0 R /a119 84 0 R /a118 82 0 R /a117 83 0 R /a115 87 0 R /a113 67 0 R /a111 68 0 R /a108 66 0 R /a106 63 0 R /a104 62 0 R /a101 65 0 R /a100 64 0 R /a99 72 0 R /a98 73 0 R /a97 74 0 R /a96 69 0 R /a94 70 0 R /a93 71 0 R /a91 103 0 R /a89 104 0 R /a87 105 0 R /a85 88 0 R /a83 101 0 R /a82 102 0 R /a80 106 0 R /a78 110 0 R /a76 111 0 R /a73 112 0 R /a72 109 0 R /a71 107 0 R /a69 108 0 R /a68 100 0 R /a67 92 0 R /a65 93 0 R /a64 91 0 R /a62 89 0 R /a61 90 0 R /a59 94 0 R /a58 98 0 R /a57 99 0 R /a55 97 0 R /a54 95 0 R /a52 96 0 R /a50 233 0 R /a48 232 0 R /a45 164 0 R /a43 231 0 R /a41 229 0 R /a40 230 0 R /a38 234 0 R /a35 238 0 R /a31 239 0 R /a29 240 0 R /a27 237 0 R /a26 235 0 R /a25 236 0 R /a23 228 0 R /a22 219 0 R /a20 220 0 R /a18 218 0 R /a16 216 0 R /a15 217 0 R /a14 221 0 R /a13 225 0 R /a11 226 0 R /a10 227 0 R /a9 224 0 R /a8 222 0 R /a7 223 0 R /a6 241 0 R /a5 258 0 R /a4 259 0 R /a3 257 0 R /a2 255 0 R /a1 256 0 R /a0 260 0 R /a66 264 0 R /a42 265 0 R /a36 266 0 R /a39 263 0 R /a47 261 0 R /a92 262 0 R /a77 254 0 R /a125 245 0 R /a44 246 0 R /a63 244 0 R /0research/cultnet-distributed-database/summary.mdresearch!!!!# CultNet Distributed Database Research Summary Purpose: ground CultNet's distributed realtime database design in prior art before adding more machinery. The goal is a coherent local-first mesh database over CultCache, not a hand-rolled distributed-systems costume party. ## Sources Stored Here - `hashgraph-swirlds-tr-2016-01.pdf` - Source: - Topic: gossip-about-gossip, virtual voting, fair ordering, asynchronous BFT. - `raft-extended.html` - Source: - Topic: understandable consensus, leader election, log replication, safety. - `raft-extended.pdf` - Source: - Topic: canonical Raft paper copy. - `dynamo-amazon-science.html` - Source: - Topic: Dynamo publication page and abstract. - `dynamo-sosp2007.pdf` - Source: - Topic: highly available key-value store, consistent hashing, versioning, quorums, hinted handoff, anti-entropy. - `swim.pdf` - Source: - Topic: scalable weakly consistent process-group membership. - `rethinkdb-changefeeds.html` - Source: - Topic: realtime query/changefeed ergonomics. - `firebase-realtime-offline.html` - Source: - Topic: offline behavior, presence, server-side disconnect operations. - `crdt-arxiv-1805.06358.html` - Source: - Topic: conflict-free replicated data types and deterministic convergence. ## Design Takeaways ### RethinkDB Keep: changefeeds as the product feel. Subscribers should receive document changes continuously, with enough old/new context to render, reconcile, or debug. Point subscriptions and filtered subscriptions are both first-class. CultNet implication: database subscriptions should be explicit schema-v0 messages. The server should stream raw document changes that clients can apply through the same CultCache reconciliation path as snapshots. ### Firebase Realtime Database Keep: realtime sync and local/offline ergonomics. Presence and disconnect behavior are database features, not application afterthoughts. Defer: full offline writes. CultNet should not pretend arbitrary offline multi-writer changes merge safely. Offline/local-first behavior needs declared per-document conflict policy. CultNet implication: add presence/disconnect records later as ordinary CultCache documents with server authority, not as hidden transport state. ### Raft Keep: the understandable authority model. One leader/primary owns ordered writes for a shard. Decompose the problem into ownership, log/mutation replication, and safety. Defer: full automatic leader election and replicated logs until shard catalogs and explicit epochs exist. CultNet implication: the current primary-shard policy is the correct first foundation. Every write should either hit the primary, be forwarded to the primary, or fail with routing information. ### Dynamo Keep: partitioning, replication metadata, vector-ish causality, hinted recovery, anti-entropy, and application-visible conflicts. Reject for now: "always writeable" semantics. That is attractive, expensive, and easy to lie about. CultNet implication: shard descriptors should grow into a shard catalog with owner runtime id, epoch, schema/key ranges, and later replica/preference-list metadata. Conflicts must surface as data, not disappear into last-writer-wins unless a document explicitly chose that policy. ### SWIM Keep: gossip-shaped membership once the mesh grows beyond a small static cluster. SWIM separates failure detection from membership dissemination and keeps per-node message load stable. Defer: membership implementation until there is a shard catalog to disseminate. CultNet implication: do not build peer discovery as a side-channel registry. When it arrives, it should update membership and shard-catalog state together. ### CRDTs Keep: CRDTs for documents whose merge law is explicit and deterministic. Reject: generic automatic merge for arbitrary domain objects. That is a language cop with a nicer hat. CultNet implication: CRDT support belongs in schema metadata or document contract metadata. A document type can opt into a known merge strategy; the default distributed write policy remains primary authority. ### Hashgraph Keep: gossip-about-gossip as an idea for compact event provenance and possible fair ordering research. Virtual voting is interesting when every member sees the same gossip history. Reject for now: adopting hashgraph consensus as CultNet's core. The public ledger/crypto smell is not the main issue; the issue is that CultNet does not currently need asynchronous Byzantine total ordering to become a good mesh database. Dragging that in now would make the machine harder to explain. CultNet implication: if we later need decentralized event ordering, use a dedicated design pass. Do not smuggle hashgraph metadata into ordinary document replication because it sounds powerful. ## Current CultNet Direction The coherent path is: 1. Primary-shard authority. 2. Explicit schema-v0 snapshot, put, delete, subscribe, unsubscribe, and change messages. 3. Shard catalog exchange with owner runtime id and epoch. 4. Optional forwarding from non-owner nodes to owners. 5. Membership/failure detection, likely SWIM-shaped. 6. Replication and failover, likely Raft-shaped per shard. 7. Optional CRDT policies for document types that deserve offline multi-writer semantics. 8. Optional gossip-history research if fair decentralized ordering becomes a real requirement. ## Live Invariants - CultCache owns document identity, schema compatibility, local indexes, and reconciliation. - CultNet owns transport, shard authority, subscriptions, and remote mutation delivery. - Raw wire records must pass through `CultNetDatabase` before mutating local cache state. - A write without authority is rejected or explicitly forwarded. It is never silently applied. - Realtime change streams publish domain changes, not storage implementation details. - Conflict policy must be declared before conflicting writes are accepted. ## Current Cut Shard catalog exchange now exists: - `cultnet.shard_catalog_request.v0` - `cultnet.shard_catalog_response.v0` - per-shard id, owner runtime id, epoch, schema ids, key prefix/range - stale epoch rejection on writes - routing error that tells clients where the primary lives when known - injectable non-primary write forwarding policy - concrete schema-v0 write forwarder for `cultnet://host:port` primary endpoints - in-memory per-shard mutation logs and catch-up by last seen sequence - wire-level shard mutation log catch-up with raw put/delete entries - replica-side application of shard log responses with epoch checks, gap rejection, and idempotent replay - background shard log replicator plus schema-v0 fetcher for primary endpoints - restart-safe replica cursor store with a local MessagePack file implementation - client authority scopes for predicted local input documents - predicted/reconciled change events for client-side prediction - simulation witness observations and deterministic consensus candidates - schema-v0 simulation observation and candidate messages - reactive observation hub for witness gossip and consensus candidates - server-side observation bridge for observation messages and candidate replies ## Next Cut Build durable authoritative mutation logs: - persist per-shard primary logs - define the snapshot fallback boundary for compacted history - return explicit resync-required responses when requested history is gone - then add simulation-frame rollback and resimulation helpers on top of predicted input streams - add peer-to-peer fanout for observation gossip and candidate propagation That is the next foundation needed before membership, Raft-style failover, or CRDT policy work can be honest. 7research/cultnet-distributed-database/raft-extended.pdfresearchZ:4%PDF-1.4 %���� 120 0 obj <> endobj xref 120 32 0000000016 00000 n 0000001664 00000 n 0000001730 00000 n 0000001974 00000 n 0000002007 00000 n 0000002076 00000 n 0000002185 00000 n 0000010658 00000 n 0000011226 00000 n 0000011907 00000 n 0000011999 00000 n 0000017965 00000 n 0000018414 00000 n 0000018854 00000 n 0000018897 00000 n 0000020780 00000 n 0000022482 00000 n 0000022579 00000 n 0000030097 00000 n 0000030533 00000 n 0000031055 00000 n 0000032778 00000 n 0000034750 00000 n 0000034850 00000 n 0000035314 00000 n 0000035533 00000 n 0000035774 00000 n 0000035967 00000 n 0000037616 00000 n 0000039244 00000 n 0000040734 00000 n 0000000936 00000 n trailer <]/Prev 571253>> startxref 0 %%EOF 151 0 obj <>stream h�b```�W � �|   ��������qI�C��Wؓ�a6O�_պ(�e���Z-*�w���ۅ�%YU|M��<9�j��R�/Y3l^p��G�a�s����I�X�9D !����{��(�)� ��pl�S�X�4ڢ�I�k�^��>n����y� ��T�*w�=����B c�5�]@%�ii� q ���� .�JS�<��qLP���Ri8�`7��+P���� > ~��I.z淀G!��N���@�� ͼ����` ���E�ݥon�ЁX����>JJ..����&.@06NKK��2������ e��@UՆF�9�@ ��iHj1� @cBA5� 2qq```!l��R�(ALB*4a`["�e�8l�"?�2� ,G�Z�0X�E�5��`X��q����-��� � �b.0:H:ވ���q@���1��{� e��_�ڶ2�0amT� � }@��,�%�9l��X6p3�b��(�^���q |c3��6 ���o� kNǰ[0�`,�tz�p�A����� �b x$�S�d�g�7�+�5�u9��P(�.@�� � endstream endobj 121 0 obj <> endobj 122 0 obj <>/Rotate 0/Type/Page>> endobj 123 0 obj <> endobj 124 0 obj <> endobj 125 0 obj <> endobj 126 0 obj <>stream x��xyXS����!9�uhK���&i���y�S�qFEe!̐@$�����$@�<� ��,�V����mk��}����no�������?0{���z�Z�z�fN���}4^�!��#[�6�C����¢�O�g�����5#�Z4���`�S��Yw�G>{id� ��/����jd �F�xy|s��y�eru\xh�R�xժU��jɿV$�RExh�� �G�4J&���(H�K�e�T%�l���c�6ɜm{�$ۤ1Ҹ�(�{�Ѩ� �[x�4F!}S"��D��G$� W��b $�@�B. �IUAR9�0O"��E�+�oI�B��K�2IxLPT|0s=�=D����dx=���e �"(.\����]��ۨ T2�*��D�w˂�o��� �QH�R����T��G���(y\�� ��пn�'����GIc�2����?��ˣ�c���v���p�B�`<��� ��M�D7*0�W����_ ����I�Y���%n�b�r{�������TG��A����H����� ����u ��բ5��f�Y���� ����K,\��l��eˋ�^�� ^#���� wb51��G�!f��~b6�I�!��7��[�Ab.�Ml"�>�fb>�K� ?b ���J,"�����b���I,#v� 7�mb7���C�$�.���Np -A��s��x�x��DD��b1��///�D�#^&��+D"1�B� W�DH��,���'�p���}����)���=…d:� @�|n�sQ��=����'&O�L ��?���y�єuSN�0��"�b�������|��ʫyy��|'~�+_��J�T�� � ������6y��i��h��q�O���k�:#mFی�3n��V������b����]r��7_�z�̛2л�~��9`��3���E��5A"���Bo�$�e U��N�%Z��� |�mܾ�ers,� A\RځlJ��Q,�C6B 5r�Й�FO;���1t}�.�_�����X�+F9$��k�3( �����2�I�v����6@ �F�#) �tI>̦`�[�R�(�&� ���?*i�6�#Ҙ��{& �\���qy��RU�sY�F��:&q�Hxi�E?����-�1G`G�U��J�?���2Z������ᝁ]���}��"Pl���A8�|�$m���@#�dCxv�g�0��� 5%G��'l�7��ke��c����~ҥ�;C�3��l5$��ު�v�l*�qz�l�F�I�Q�[�I�"T�S�!�U�����8N�uoTSt��lg�KUImŋ���u�M�NK��F�*�9�{0�ީ��_T4�M^ �A�H�Ѵ�����a����\l pyQ���d큀�b.C#������~��y�>ze�\$B._����w��"8u��e�N�|i.��8��m��M��$nQߞ�zK��>�v���g��L0d*��4����T z%��/7U�R!�����P�C�Q��<�e���^�S��m"�2�aQ���\��-�)x��s`•��O�a���e��c��~*L�$pM �)� h�4���>E��*�2j����M �������+�r��W>�ԕ]wD�B7��q��s(� ���5|κx&!�W�i��wR5]�T��цVz�e�{�a�ө��bz�8� ��n6����^�n�xo$�t�w��ܐ�+�Rp1�Qk8(��W� ΂/n����q^��)�+!L�$�om�7_��;�Q���a�!��f��n��n} ����qZ@�.�J��c�!�zN=�x��QQU�t�z���1�O���B�BW�X����_��\Ț�����`s�n}:�7�"!~m�z�ڥ������臞��D�N4�X��MW���ũ8�yQ���-�E}O�%��=��[��GW�>��/e��RpR��h�V@�+�s�s�S��x*OG�|����`|�Ks�����/�f�|��1�Ų_�q�v %A���,K+�(�[=� }�� �!-^����$�ٔp \�(����jK��1�ǰ�wc�x6�����k�2�"�(�뀒s}A`�ќ��U *(��c`�YVR5P���fh�Z]�,�6s��66�� �S��b1U�̈́�sF��y�dт-c��E�ل�wU�]����Z��c���Ʒ����89@��H�c4�J�,h����l�"����S ���RQ���dT����-��ō���+2=�@|��]%�B�vx�?� �0�� S֨5k��� ӧ����2} VꙄP�6;�._k�)g�� M�j\BCu��^��U;�� W}0�7ހ��3�t�����j�Ƽ)4C����U���Ǻ���yk�?�pDGb�D "e��Q�j�(�.�Fw�JF�,\sI~.F��V �Y5��*L� �.�����mo����5u�A���8x�9|I CK�^��^V+�Ғ��#>�7>*Rs�3�2��l��Jp�Bo��{�ъِ �|�����h`�j� p �zB�e��=T 7 �r�&�Z� 9Om>l�/:��<��m6:�fÆ ����~'��S_����` .�Y� �)��p����l��h7N�'������d�D�TS�� �<◜A��&c�4�����E�n�E�+��\�=�&ҕ&�%�0D�����'?q�J �.;�g��36�B��� n��>0c�mQ���z�y,�+ )k����� �: &tx^@�n�v��S��i%�zu���|�1܊}�N+N�ӹ���A1�-!ymI���2�P d�Z�^� ����cb^|��В'3��O���w�z�D����$�-?딣���U��}��΂$��dk�.eE�xO^��lw�̽c�<���R�O�[.�U��q��X�=k���6PC�!�0� f�b�5� �q�*5w�Q6�!��̆��p���yi��´BP�[|�4�(47�1�������mk�O����ҏ ��*�cm5DNI�՚��"CGry,�x�<�/zWn×�L�z�!ۍ%F�4&�^�� V@e� �"ե�flf����(�;��*��P�� �@kFIV (�����|�k����*2T{C���,�H[ @����"��K���� �� ��{��APy,������v7\����>�s>��;N��OҦ�k�4Z�'ϙ�&Mm|��;��o�uS:kj�����fqVqv0S �սC 1^�=$Z�;)�4>Q"(���@�����3WD<���ʄ>�vlG7^B 1�G��&�(���@���������:��j\�0���36�xd*�,��欲4��ў�h Z.���#ӥ"��t��O�{�I�;��Q�w(������k�7�s !�j���t�c2p�N�і,�ia�z@��ʋn�,8�6ly�۸Q ��,�e�| ?c��#k�鹁y�!�0&��L��3�z�Sţ�dԓ����_�/��f��}����N=':�<<�MAl�]����Wc���5r����$�*5Ia��ꕀ��ݤ+���$�e�>*��w�gs����Utynb 󘾂K@�Ԫ �����lS�Q�jB$,4Y3,cr�f���Ւ���$�Eق�4[t�Oy(#�5J��hml�J L 5�P�2'�'�MLTD��{��8�.��YZKKj�L�ߦ9M��l�5���%T�e֢]B���>��CJą�E�Ju�W�k.l9���;1���'@� �C�W-����-���Z�KԔ�'�+CYt%�o��G}pޥ��n�� p���[�]&G�H;����\�Uq?N��0L� fjU+M���9'Հ�(z6 �GOp�\�h��5�跡 _�o�1%뒄ڤ�ToܹD\XM�ɱ��L�<��[|�f�������ob�8y��πr��FV�S��� �7���3�rR��2��Y�~���0î$a2Y�S��Ul8*F�Hi��4�G.�c�k��{��� ݎ��]����јbЫ� 1�Z��!|r���?;t�C�zG*�3���sh=��!��.��Zb��fX>EEvgZ3l�mq(�M�/�Q>���*n?����Fw�<�l:ɳ�{0dL�o˜VHv��yp%�o���]�i����6�e]��n�5CS\kt��A���ᇎ�]�* ������%H��p��a{�p��,�z�v����Վ5�:�e�?FV��~4�]�������}����%����'���n7Wt��P; �Aug�9ߖ�M�S��ʰ����� k98��a����z����j\s�n�����q�2U�����*�!�RT[f�T����3�~��r�Xql@Zh�jU���}.ؤO������Rp����)���q��g0�'��a8��ϪȮ�����˭�W�upL�-o X�8gE�W�� ���,I3�7�W�;y��������\=4�-wD&jsr��1���:��:�S��j�&?hhd���߳�Lij`�9�H /��F�`��En ��b�Z�dJ���%�ΐP�җ�zPB�������QwKE+�Wۘ�����qŠ8�:�����y��e�.]������h��@Sz���B��i�6㇦!@}٦ ݷ>q��k�1[������;[ꓢ�E�ae� ���7��w�vy��,ه��7o���_oX:+{�^��rlJ�G��L�@�)�f�K�D=����'<7ށ������'S"%��q��<7{N��悧� �����M�u���~�����68�Q�u_=~L�!j��Ɩ����b�G�Ƽ�j������O�sWJu�j��9�\[N �'ှ@���q�D�A��`0'U�k��ɸ骓�#{����K��kb�O�#���*�cA3����?�I�����L�<��~���(��s$�ju �@�rMpg� ׄ�qj���Uc�N��J�cb�k$���*���u���+�Ә���l;Ơ�[�S���tk���x4�^Z�[:FAo#��SJ�y���{0Ijؚ$k�#�����_��{>�Rd �(O�F�G�4~q'�؄�n-a��Js���]EeY��K`���ƅq�pۣ�ғXi��qlf�a=} ݘl;�ߒWļ�'��Q!c�f6�-�F�Ք� v� ���l�����@u&",1���L�)m�G��\�`���V9����bJ���}F�If#cs�su��G��������y����/�7x� Ӯt���\oU��S#���8��dp�j�t:�AL�z }%@�MVAjuv�0��d�������CE^�.Im_ӶJ Ah&=�X�1�(Zm5���[�T��t��k>�mg�Z@���F�pl�'�Z�Y���Li��&����vjd5žχN���C�ܿ_Ѕ����M\�rASn����c�}gEG� Ė�y��G� 1#U�*S��B����x��rU���QW��O�/G�q��!�@6 N���q�Q1uqM-�uM-���b����7�:F�p�`:��G��uej�t)��RMe ��oq��&G�/0��?�씞�����W�7��/��ԩ���a��p/3�Z�Uh��)��r����"e!^!�n�!�'�o F���fX�^� ��j�M�+�a\ݵ�0�~*����b��#�=�^Z{�������sm��� i�N�9�����MzH��a ���>��q�qCoce ���`��wP�n�f���?���D� �MD�-g=��wt��Ϝm}�kVYze��2� �zso ����$������~ab�h)�Y���a���c� �D<ΓsM��-. 7�0ݪ+KoJ���Z��� ���[@�С+�פ���"4��P?�o�‚�z������o;~��+�#kT���s1���0�8research/cultnet-distributed-database/raft-extended.htmlresearch̓I#( In Search of an Understandable Consensus Algorithm (Extended Version)

In Search of an Understandable Consensus Algorithm (Extended Version)

DECLARATION

This page is the In Search of an Understandable Consensus Algorithm (Extended Version) paper. Original Paper Link is: https://raft.github.io/raft.pdf

In Search of an Understandable Consensus Algorithm
(Extended Version)
Diego Ongaro and John Ousterhout
Stanford University

Abstract

Raft is a consensus algorithm for managing a replicated log. It produces a result equivalent to (multi-)Paxos, and it is as efficient as Paxos, but its structure is different from Paxos; this makes Raft more understandable than Paxos and also provides a better foundation for building practical systems. In order to enhance understandability, Raft separates the key elements of consensus, such as leader election, log replication, and safety, and it enforces a stronger degree of coherency to reduce the number of states that must be considered. Results from a user study demonstrate that Raft is easier for students to learn than Paxos. Raft also includes a new mechanism for changing the cluster membership, which uses overlapping majorities to guarantee safety.

1 Introduction

Consensus algorithms allow a collection of machines to work as a coherent group that can survive the failures of some of its members. Because of this, they play a key role in building reliable large-scale software systems. Paxos [15, 16] has dominated the discussion of consensus algorithms over the last decade: most implementations of consensus are based on Paxos or influenced by it, and Paxos has become the primary vehicle used to teach students about consensus.

Unfortunately, Paxos is quite difficult to understand, in spite of numerous attempts to make it more approachable. Furthermore, its architecture requires complex changes to support practical systems. As a result, both system builders and students struggle with Paxos.

After struggling with Paxos ourselves, we set out to find a new consensus algorithm that could provide a better foundation for system building and education. Our approach was unusual in that our primary goal was understandability: could we define a consensus algorithm for practical systems and describe it in a way that is significantly easier to learn than Paxos? Furthermore, we wanted the algorithm to facilitate the development of intuitions that are essential for system builders. It was important not just for the algorithm to work, but for it to be obvious why it works.

The result of this work is a consensus algorithm called Raft. In designing Raft we applied specific techniques to improve understandability,including decomposition (Raft separates leader election, log replication, and safety) and This tech report is an extended version of [32]; additional material is noted with a gray bar in the margin. Published May 20, 2014. state space reduction (relative to Paxos, Raft reduces the degree of nondeterminism and the ways servers can be inconsistent with each other). A user study with 43 students at two universities shows that Raft is significantly easier to understand than Paxos: after learning both algorithms, 33 of these students were able to answer questions about Raft better than questions about Paxos.

Raft is similar in many ways to existing consensus algorithms (most notably, Oki and Liskov's Viewstamped Replication [29, 22]), but it has several novel features:

1/. Strong leader: Raft uses a stronger form of leadership than other consensus algorithms. For example, log entries only flow from the leader to other servers. This simplifies the management of the replicated log and makes Raft easier to understand.

2/. Leader election: Raft uses randomized timers to elect leaders. This adds only a small amount of mechanism to the heartbeats already required for any consensus algorithm, while resolving conflicts simply and rapidly.

3/. Membership changes: Raft's mechanism for changing the set of servers in the cluster uses a new joint consensus approach where the majorities of two different configurations overlap during transitions. This allows the cluster to continue operating normally during configuration changes.

We believe that Raft is superior to Paxos and other consensus algorithms, both for educational purposes and as a foundation for implementation. It is simpler and more understandable than other algorithms; it is described completely enough to meet the needs of a practical system; it has several open-source implementations and is used by several companies; its safety properties have been formally specified and proven; and its efficiency is comparable to other algorithms.

The remainder of the paper introduces the replicated state machine problem (Section 2), discusses the strengths and weaknesses of Paxos (Section 3), describes our general approach to understandability (Section 4), presents the Raft consensus algorithm (Sections 5–8), evaluates Raft (Section 9), and discusses related work (Section 10).

2 Replicated state machines

Consensus algorithms typically arise in the context of replicated state machines [37]. In this approach, state machines on a collection of servers compute identical copies of the same state and can continue operating even if some of the servers are down. Replicated state machines are used to solve a variety of fault tolerance problems in distributed systems. For example, large-scale systems that have a single cluster leader, such as GFS [8], HDFS [38], and RAMCloud [33], typically use a separate replicated state machine to manage leader election and store configuration information that must survive leader crashes. Examples of replicated state machines include Chubby [2] and ZooKeeper [11].

raft-figure1.jpg

Figure 1: Replicated state machine architecture. The consensus algorithm manages a replicated log containing state machine commands from clients. The state machines process identical sequences of commands from the logs, so they produce the same outputs.

Replicated state machines are typically implemented using a replicated log, as shown in Figure 1. Each server s9research/cultnet-distributed-database/dynamo-sosp2007.pdfresearch t-%PDF-1.3 %���� 101 0 obj <> endobj xref 101 29 0000000016 00000 n 0000001444 00000 n 0000001525 00000 n 0000001727 00000 n 0000001863 00000 n 0000002320 00000 n 0000002760 00000 n 0000003302 00000 n 0000004074 00000 n 0000004327 00000 n 0000004601 00000 n 0000004869 00000 n 0000004982 00000 n 0000005229 00000 n 0000006383 00000 n 0000006918 00000 n 0000007199 00000 n 0000008288 00000 n 0000009351 00000 n 0000010473 00000 n 0000011530 00000 n 0000012622 00000 n 0000013685 00000 n 0000014725 00000 n 0000035703 00000 n 0000072079 00000 n 0000119236 00000 n 0000150351 00000 n 0000000876 00000 n trailer <]>> startxref 0 %%EOF 129 0 obj<>stream x�b```�� � � �  cc`a�������Ȣ���됺���qņ�lݬ|;��Y.wh�+x��6ljl��z����UH�1(�q��NOh��ql29��jr((Y��Q�!2٧,+��,���$Y&_y �&IB�Hh� ��f T� dL2����2�qr�I���ި}�!2� f���,w��@5* � ��]��s�X���B����� N�Zv+�DG���GG��K(��I9 J 1���3�)�0�ll���4�*�,a �V� �1b`���2 ��� v4�@`�����X ,�� �0�!�qc'�{�� �3�epb8�������c�O,��?��}���2&�#��K �:�I�13|�T�pIU��1��O�`�'��1T1X ����J {��s��}�P�V+ ���@���sd?T�K����z endstream endobj 102 0 obj<> endobj 103 0 obj<> endobj 104 0 obj<>/ProcSet[/PDF/Text]/ExtGState<>>> endobj 105 0 obj<> endobj 106 0 obj<> endobj 107 0 obj<> endobj 108 0 obj<> endobj 109 0 obj<> endobj 110 0 obj<> endobj 111 0 obj<> endobj 112 0 obj<> endobj 113 0 obj<> endobj 114 0 obj<>stream H�lUێ�6}�W�#X�D��'' l��@ �â\��ٕ(W��n>#_�!)��E�X�™9g�\��q��A�>��m� �v�JkH�/UCU�Q��J���m�Jh�$h{Y��WŇ�� �Ǩ~j�,��6g.{�� �*^�3�g[3N��o �/`̃1h��e�A7���ɾ;J|�^��0+Z$]����3�����QZ�oˆ ��>�_xd�n�Ӹ��*G�?Ť��A�ڹ�h����XU� ��JZ��η��ꮸQAK�"D� ��!�xͯ%̰L%��j�.��z���1K-��Ѯ�!�|ܶ�U��O�����wlHEE��2L��g���$�E/�sTњ�^:����F��@� n`�RF3�#dT��Y��x�ӆ��eJ�{�C��.�li0K�����#FoP��2"`�{4s�,��4Q�tGg�E O�"r��Y���3�kl�ڒ^`�.�� Z.�s���NJ؋A(#v�`��ϒ� �xZ��]�R�'_Cm��CQ���ܙ�[[e����[�S�'a�5VQ��N�6ќ�rp����$+��5��% ��X�Λ2���X����-�ՏG �4�bJm�6��X֩U������G�&}dzy�u|����B�i���u)l >a p���x�K�0Nr�Į��o�`�D6_�C\�(q��?�V!o endstream endobj 115 0 obj<> endobj 116 0 obj<> endobj 117 0 obj<>stream H�tU˖�6 ��+��ΉTQ/K˞z�l��w9Ypd�f"�>zx2���� ��x&�J6 \�e��Y�Iq�vY*%�z�E�n�j;O�L/��]��AQ�D����xرs���%�/𶳱�[��%N괈���>��I�W-��z|��d��M�hF�����N���-@�h|1�j��Lb`�N2$��:��2����4�����p��<�����>R�$��mT�����Wd3��\��(��$�,�}��;��jԂ�k#�)s������V��T< 6�1p��+��+�)tD�F�O���Nz2�a(F�^[#W�"�0T�n���f�,�w� �Ģ��wk �Pk{���ee��j.�(%-� $߹]h3\����N=�o>I,argCE�m�/��(-a1{w7��vW�A�1��cj!�ȟk���ݟ����{z���P���۪XW�{]DSw�h��edh�0��N,| ���Kw7'> ��.v�1���������� `D���e�=���i10F,���7G�ˉ�� R��k��w�0�� �Q����!��ʟC� d��b�A{*^��"-���]5����6h�;�P�4/V @���PՍ���=��V�$ ��Y��u�9��f���>�bOغN���xqդ� ��Ӵ2(o4nJ���y�g_��Q�wH�?��� ��1™A����� ��򐵕��NJ���h���U�ۭ7/y��zb*N��g�7:�o�����3 fH������S� %q� f�o�{�*�&��7�O=�BfhDs���==��z�1��w>Y�A�Fٚ 70�����Fh"�=^{��� � �9�v<�=>C8�� |�R ��qx`%�Z����m74�����v�S7���Ɖ�c�7�e�V�E���K`̟^���ޖ萖��b�����t������ч&���B^X�g��B�j��I�*�*�`h� endstream endobj 118 0 obj<>stream H�|Uێ�6}�W�# �X��'OE(�� �>-�i[�,��E���ΐ�/�m��K�2g�3���槶�AB���"�� Rh�7�HӴ���+�C��yb_y%{�)2��X���5��M�.YG� ���=܋�/O��Y�k�q��T�M�>�9�G$0���?(�2$�� �.��sr2&�p⹨���&��sJ����'��ٌG9s����q���rpR�A�  1�b=�E�C���26�/������K*�SA�TL�ӊW�x� x���^s�V ��#P����Gi�0ev�S�lk|YW�hdd����ؾT�Y۝��n���(�LF!�欀� �I�/+(r�2% �1D/�A�.Q�_�����j�Մ8��Ƈi@f��u��9<2VUf�u.C�f*���7vp��|G&��3�u7��Y�'Ff��nV�ůC(}�%�ǜ���_�t�� �Q3�C��K� �2 r���"�uP�]�-�D���`u0s���Ӎ�Q"UDI$�I�VkWUE�������"��~>�_������ �m)��YS *W}J��s�͍��v�f�Qgu�e����q�� [ :Azs֛�2= �:4��5�� n�$�M�xܡs�7�|4Q]�G!�9p���' �Y�q����8����� ��΀�'@research/cultnet-distributed-database/crdt-arxiv-1805.06358.htmlresearchʹ#( [1805.06358] Conflict-free Replicated Data Types (CRDTs)

Skip to main content
We gratefully acknowledge support from the Simons Foundation, member institutions, and all contributors. Donate
arXiv logo
Dynamo: Amazon’s highly available key-value store - Amazon Science