Add CultNet simulation witness consensus

This commit is contained in:
Meta Vens 2026-05-19 18:35:16 +01:00
commit 75ebc727f2
5 changed files with 430 additions and 3 deletions

View file

@ -173,6 +173,7 @@ Shard catalog exchange now exists:
implementation
- client authority scopes for predicted local input documents
- predicted/reconciled change events for client-side prediction
- simulation witness observations and deterministic consensus candidates
## Next Cut
@ -183,6 +184,7 @@ Build durable authoritative mutation logs:
- 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 observation gossip once the local witness model has earned its shape
That is the next foundation needed before membership, Raft-style failover, or
CRDT policy work can be honest.

View file

@ -61,6 +61,8 @@ Implemented:
implementation
- client-authority scopes for locally predicted input documents
- predicted and reconciled database change kinds for client-side prediction
- simulation witness observations for mesh-side opinions about frame facts
- deterministic consensus candidates derived from witness observations
Not implemented yet:
@ -68,6 +70,7 @@ Not implemented yet:
- leader election or automatic shard failover
- durable log persistence and compaction
- snapshot fallback for compacted log history
- transport messages/documents for witness observation gossip
- rollback/resimulation helpers for simulation frames
- declared CRDT merge policies
@ -87,6 +90,11 @@ Not implemented yet:
- Predicted input state is not authoritative shared state. The shard log still
decides the committed ordering and emits reconciliation when it corrects or
confirms local prediction.
- Witness observations are immutable reports about a shard epoch, frame,
subject, claim kind, and claim hash.
- Consensus candidates are derived from observations. They may inform the
authoritative commit path, but they are not themselves committed world state
until a shard owner writes them into the log.
## Next Coherent Slice
@ -97,10 +105,14 @@ Add durable mutation-log storage and snapshot fallback:
- return `ResyncRequired` when a replica asks for compacted history
- after that, add simulation-frame rollback/resimulation helpers around
predicted input streams
- add schema-v0 observation gossip once the local consensus document shape is
stable
The log is wire-readable, replicas can apply it explicitly, a pull loop can
drive non-primary shards from primary endpoints, and replica cursors can survive
restart. Client-owned input documents can now be predicted locally and
reconciled when the authoritative log arrives. The next useful layer is making
authoritative mutation logs durable and compaction-aware. Membership and leader
election should wait until basic replica catch-up is boring.
reconciled when the authoritative log arrives. Nodes can also aggregate witness
observations into deterministic consensus candidates for simulation facts like
"who shot first." The next useful layer is making authoritative mutation logs
durable and compaction-aware. Membership and leader election should wait until
basic replica catch-up is boring.

View file

@ -0,0 +1,293 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using MessagePack;
namespace GameCult.Networking
{
/// <summary>
/// One witness report about a deterministic simulation fact.
/// </summary>
[MessagePackObject]
public sealed class CultNetSimulationObservation
{
/// <summary>
/// Gets or sets the observing runtime id.
/// </summary>
[Key("witnessRuntimeId")] public string WitnessRuntimeId { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the shard id containing the observed simulation.
/// </summary>
[Key("shardId")] public string ShardId { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the shard epoch observed by the witness.
/// </summary>
[Key("shardEpoch")] public long ShardEpoch { get; set; }
/// <summary>
/// Gets or sets the simulation frame or tick.
/// </summary>
[Key("frame")] public long Frame { get; set; }
/// <summary>
/// Gets or sets the subject this observation is about.
/// </summary>
[Key("subjectId")] public string SubjectId { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the kind of claim, such as hit, input, collision, or ownership.
/// </summary>
[Key("claimKind")] public string ClaimKind { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the content hash of the witness claim.
/// </summary>
[Key("claimHash")] public string ClaimHash { get; set; } = string.Empty;
/// <summary>
/// Gets or sets optional human-readable or app-specific claim detail.
/// </summary>
[Key("claimSummary")] public string? ClaimSummary { get; set; }
/// <summary>
/// Gets or sets the witness weight. Normal clients should use 1.
/// </summary>
[Key("weight")] public double Weight { get; set; } = 1d;
/// <summary>
/// Gets or sets the observation timestamp.
/// </summary>
[Key("observedAt")] public string ObservedAt { get; set; } = string.Empty;
/// <summary>
/// Computes a stable claim hash from ordered claim parts.
/// </summary>
public static string ComputeClaimHash(params string[] parts)
{
if (parts == null) throw new ArgumentNullException(nameof(parts));
var canonical = string.Join("\u001F", parts.Select(part => part ?? string.Empty));
using var sha = SHA256.Create();
var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(canonical));
return string.Concat(bytes.Select(value => value.ToString("x2")));
}
}
/// <summary>
/// Controls deterministic witness aggregation.
/// </summary>
public sealed class CultNetSimulationConsensusOptions
{
/// <summary>
/// Gets or sets the minimum distinct witnesses required before a claim can be accepted.
/// </summary>
public int MinimumWitnesses { get; set; } = 1;
/// <summary>
/// Gets or sets the minimum weight required before a claim can be accepted.
/// </summary>
public double MinimumWeight { get; set; } = 1d;
/// <summary>
/// Gets or sets the fraction of observed weight required for quorum.
/// </summary>
public double QuorumRatio { get; set; } = 0.5d;
}
/// <summary>
/// A deterministic consensus candidate derived from witness observations.
/// </summary>
public sealed class CultNetSimulationConsensusCandidate
{
/// <summary>
/// Creates a consensus candidate.
/// </summary>
public CultNetSimulationConsensusCandidate(
string shardId,
long shardEpoch,
long frame,
string subjectId,
string claimKind,
string claimHash,
string? claimSummary,
int witnessCount,
double supportWeight,
double totalWeight,
bool hasQuorum)
{
ShardId = shardId;
ShardEpoch = shardEpoch;
Frame = frame;
SubjectId = subjectId;
ClaimKind = claimKind;
ClaimHash = claimHash;
ClaimSummary = claimSummary;
WitnessCount = witnessCount;
SupportWeight = supportWeight;
TotalWeight = totalWeight;
HasQuorum = hasQuorum;
}
/// <summary>
/// Gets the shard id.
/// </summary>
public string ShardId { get; }
/// <summary>
/// Gets the shard epoch.
/// </summary>
public long ShardEpoch { get; }
/// <summary>
/// Gets the simulation frame.
/// </summary>
public long Frame { get; }
/// <summary>
/// Gets the subject id.
/// </summary>
public string SubjectId { get; }
/// <summary>
/// Gets the claim kind.
/// </summary>
public string ClaimKind { get; }
/// <summary>
/// Gets the claim hash.
/// </summary>
public string ClaimHash { get; }
/// <summary>
/// Gets optional claim detail.
/// </summary>
public string? ClaimSummary { get; }
/// <summary>
/// Gets the distinct witness count supporting this candidate.
/// </summary>
public int WitnessCount { get; }
/// <summary>
/// Gets supporting witness weight.
/// </summary>
public double SupportWeight { get; }
/// <summary>
/// Gets total observed witness weight for the same subject/frame/kind.
/// </summary>
public double TotalWeight { get; }
/// <summary>
/// Gets whether the candidate crossed the configured quorum.
/// </summary>
public bool HasQuorum { get; }
/// <summary>
/// Gets support divided by total observed weight.
/// </summary>
public double Confidence => TotalWeight <= 0d ? 0d : SupportWeight / TotalWeight;
}
/// <summary>
/// Aggregates simulation observations into deterministic consensus candidates.
/// </summary>
public sealed class CultNetSimulationConsensus
{
private readonly CultNetSimulationConsensusOptions _options;
/// <summary>
/// Creates a consensus aggregator.
/// </summary>
public CultNetSimulationConsensus(CultNetSimulationConsensusOptions? options = null)
{
_options = options ?? new CultNetSimulationConsensusOptions();
}
/// <summary>
/// Returns the strongest candidate for each observed shard/frame/subject/claim kind.
/// </summary>
public IReadOnlyList<CultNetSimulationConsensusCandidate> BuildCandidates(
IEnumerable<CultNetSimulationObservation> observations)
{
if (observations == null) throw new ArgumentNullException(nameof(observations));
var clean = observations
.Where(IsValid)
.GroupBy(DeduplicationKey)
.Select(group => group
.OrderByDescending(observation => observation.Weight)
.ThenBy(observation => observation.WitnessRuntimeId, StringComparer.Ordinal)
.First())
.ToArray();
return clean
.GroupBy(SubjectKey)
.Select(BuildCandidate)
.OrderBy(candidate => candidate.ShardId, StringComparer.Ordinal)
.ThenBy(candidate => candidate.ShardEpoch)
.ThenBy(candidate => candidate.Frame)
.ThenBy(candidate => candidate.SubjectId, StringComparer.Ordinal)
.ThenBy(candidate => candidate.ClaimKind, StringComparer.Ordinal)
.ToArray();
}
private CultNetSimulationConsensusCandidate BuildCandidate(
IGrouping<string, CultNetSimulationObservation> subjectGroup)
{
var totalWeight = subjectGroup.Sum(WeightOf);
var bestClaim = subjectGroup
.GroupBy(observation => observation.ClaimHash, StringComparer.Ordinal)
.Select(group => new
{
ClaimHash = group.Key,
Observations = group.ToArray(),
Weight = group.Sum(WeightOf)
})
.OrderByDescending(candidate => candidate.Weight)
.ThenBy(candidate => candidate.ClaimHash, StringComparer.Ordinal)
.First();
var first = bestClaim.Observations
.OrderBy(observation => observation.WitnessRuntimeId, StringComparer.Ordinal)
.First();
var witnessCount = bestClaim.Observations
.Select(observation => observation.WitnessRuntimeId)
.Distinct(StringComparer.Ordinal)
.Count();
var hasQuorum = witnessCount >= _options.MinimumWitnesses &&
bestClaim.Weight >= _options.MinimumWeight &&
totalWeight > 0d &&
bestClaim.Weight / totalWeight >= _options.QuorumRatio;
return new CultNetSimulationConsensusCandidate(
first.ShardId,
first.ShardEpoch,
first.Frame,
first.SubjectId,
first.ClaimKind,
bestClaim.ClaimHash,
first.ClaimSummary,
witnessCount,
bestClaim.Weight,
totalWeight,
hasQuorum);
}
private static bool IsValid(CultNetSimulationObservation observation)
{
return observation != null &&
!string.IsNullOrWhiteSpace(observation.WitnessRuntimeId) &&
!string.IsNullOrWhiteSpace(observation.ShardId) &&
!string.IsNullOrWhiteSpace(observation.SubjectId) &&
!string.IsNullOrWhiteSpace(observation.ClaimKind) &&
!string.IsNullOrWhiteSpace(observation.ClaimHash) &&
observation.Weight > 0d;
}
private static double WeightOf(CultNetSimulationObservation observation)
{
return observation.Weight <= 0d ? 0d : observation.Weight;
}
private static string DeduplicationKey(CultNetSimulationObservation observation)
{
return string.Join("|",
observation.WitnessRuntimeId,
observation.ShardId,
observation.ShardEpoch,
observation.Frame,
observation.SubjectId,
observation.ClaimKind);
}
private static string SubjectKey(CultNetSimulationObservation observation)
{
return string.Join("|",
observation.ShardId,
observation.ShardEpoch,
observation.Frame,
observation.SubjectId,
observation.ClaimKind);
}
}
}

View file

@ -154,6 +154,13 @@ local cache immediately and emits a `Predicted` change; when the authoritative
shard log arrives for the same record, the database emits `Reconciled` and the
cache holds the committed value.
For mesh-side simulation agreement, `CultNetSimulationObservation` records what
a witness saw for one shard epoch, frame, subject, and claim kind.
`CultNetSimulationConsensus` deterministically aggregates those observations
into candidates with support weight, total observed weight, confidence, and
quorum status. Those candidates are opinions ready for an authoritative commit
path, not committed world state by themselves.
The first coherent shard policy is primary ownership. Each shard has one
authoritative writer at a time. Clients may connect to any node; a non-owner
node forwards a write to the owner or rejects it honestly when forwarding is

View file

@ -1213,6 +1213,119 @@ namespace GameCult.Networking.Tests
}
}
[Test]
public void CultNetSimulationConsensus_Builds_QuorumCandidate_FromWitnesses()
{
var hitA = CultNetSimulationObservation.ComputeClaimHash("hit", "alice", "bob", "frame:100");
var hitB = CultNetSimulationObservation.ComputeClaimHash("hit", "charlie", "bob", "frame:100");
var consensus = new CultNetSimulationConsensus(new CultNetSimulationConsensusOptions
{
MinimumWitnesses = 2,
QuorumRatio = 0.6d
});
var candidates = consensus.BuildCandidates(
[
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-1",
ShardId = "arena",
ShardEpoch = 4,
Frame = 100,
SubjectId = "bob",
ClaimKind = "hit",
ClaimHash = hitA,
ClaimSummary = "alice hit bob first"
},
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-2",
ShardId = "arena",
ShardEpoch = 4,
Frame = 100,
SubjectId = "bob",
ClaimKind = "hit",
ClaimHash = hitA
},
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-3",
ShardId = "arena",
ShardEpoch = 4,
Frame = 100,
SubjectId = "bob",
ClaimKind = "hit",
ClaimHash = hitB,
ClaimSummary = "charlie hit bob first"
}
]);
Assert.That(candidates, Has.Count.EqualTo(1));
Assert.That(candidates[0].ClaimHash, Is.EqualTo(hitA));
Assert.That(candidates[0].WitnessCount, Is.EqualTo(2));
Assert.That(candidates[0].SupportWeight, Is.EqualTo(2d));
Assert.That(candidates[0].TotalWeight, Is.EqualTo(3d));
Assert.That(candidates[0].HasQuorum, Is.True);
}
[Test]
public void CultNetSimulationConsensus_DeduplicatesWitness_AndBreaksTiesDeterministically()
{
var lowerHash = CultNetSimulationObservation.ComputeClaimHash("a");
var higherHash = CultNetSimulationObservation.ComputeClaimHash("b");
if (string.CompareOrdinal(lowerHash, higherHash) > 0)
{
(lowerHash, higherHash) = (higherHash, lowerHash);
}
var consensus = new CultNetSimulationConsensus(new CultNetSimulationConsensusOptions
{
QuorumRatio = 0.5d
});
var candidates = consensus.BuildCandidates(
[
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-1",
ShardId = "arena",
ShardEpoch = 1,
Frame = 20,
SubjectId = "door",
ClaimKind = "state",
ClaimHash = higherHash,
Weight = 1d
},
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-1",
ShardId = "arena",
ShardEpoch = 1,
Frame = 20,
SubjectId = "door",
ClaimKind = "state",
ClaimHash = lowerHash,
Weight = 0.5d
},
new CultNetSimulationObservation
{
WitnessRuntimeId = "watcher-2",
ShardId = "arena",
ShardEpoch = 1,
Frame = 20,
SubjectId = "door",
ClaimKind = "state",
ClaimHash = lowerHash,
Weight = 1d
}
]);
Assert.That(candidates, Has.Count.EqualTo(1));
Assert.That(candidates[0].ClaimHash, Is.EqualTo(lowerHash));
Assert.That(candidates[0].TotalWeight, Is.EqualTo(2d));
Assert.That(candidates[0].SupportWeight, Is.EqualTo(1d));
Assert.That(candidates[0].HasQuorum, Is.True);
}
[Test]
public void CultNetDatabaseServer_Creates_Filtered_SubscriptionChange()
{