Add CultNet simulation witness consensus
This commit is contained in:
parent
ffedd6e973
commit
75ebc727f2
5 changed files with 430 additions and 3 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
293
src/GameCult.Networking/CultNetSimulationConsensus.cs
Normal file
293
src/GameCult.Networking/CultNetSimulationConsensus.cs
Normal 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);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue