Refinements: clarify HLC packing, optimize VectorClock coordinator, simplify deterministic simulation

[dexcompiler]

Summary

This PR refines several distributed-systems demo and library implementation details to be more explicit and efficient [closer to “systems library” standards], while preserving existing behavior and wire formats.

HlcTimestamp:

• Clarified packed Int64 encoding semantics [explicit constant + XML docs]
• Made NodeId truncation in packed form explicit; full-fidelity remains WriteTo(Span<byte>) and ReadFrom(ReadOnlySpan<byte>)

VectorClock and VectorClockCoordinator:

• Added IsEmpty for explicit checks
• Added internal helpers to support efficient snapshotting
• Added internal VectorClockBuilder and updated VectorClockCoordinator to use it to reduce allocation churn on merge/increment hot paths
• Clarified canonical binary wire format docs [big-endian, sorted/canonical output]

Deterministic distributed showcase demo:

• Switched from ConcurrentDictionary to Dictionary / HashSet [since the initial demo is single-threaded by design]
• Reworked simulated network in-flight scheduling to a PriorityQueue with deterministic tie-breaking
• Modeled reordering as bounded delivery-time jitter clamped to >= for now [time-driven delivery preserved]

[dexcompiler]

@cursoragent review this PR

[cursor]

PR Review

Overall this is a strong refinement pass: the wire-format docs are clearer, the VectorClockCoordinator hot path is less allocation-happy, and the demo simulation looks genuinely more deterministic (canonical scheduling + stable tie-break).

What looks good

• HlcTimestamp: explicit constants + docs for packed layout, and calling out NodeId truncation vs full-fidelity WriteTo/ReadFrom is exactly the kind of “library-grade” clarity you want.
• VectorClock: IsEmpty is a nice ergonomic addition; the binary format docs now clearly describe big-endian + canonical/sorted output.
• Coordinator/builder: the builder reuse pattern in VectorClockCoordinator should reduce churn in merge/increment-heavy workloads.
• Demo: moving from ConcurrentDictionary to Dictionary/HashSet matches the “single-threaded by design” premise; the PriorityQueue + (DeliverAt, Sequence) priority is a good deterministic schedule.

Nits / follow-ups to consider (non-blocking)

• HlcTimestamp.FromPackedInt64 signed-shift edge case: it currently does packed >> 16 on a long. For very large wall times (when bit 63 becomes set after packing), this becomes a sign-extending shift and would decode a negative wall time. A follow-up that decodes via ulong (logical shift) or range-checks/masks the wall-time bits would make the new “48-bit wall time” docs airtight.
• VectorClockBuilder.Merge buffer path: the byte[]? pooled local is unused (harmless, but confusing name). If you want to push the “reduce allocation churn” theme further, consider using ArrayPool<byte> for the >1024-byte case, or (if you’re comfortable relying on internals) merging via spans directly instead of encode/decode.

Verification

• I ran dotnet test Clockworks.sln -c Release locally on the branch: all tests passed.

 

[dexcompiler]

@copilot review this PR

[Copilot]

@dexcompiler I've opened a new pull request, #47, to work on those changes. Once the pull request is ready, I'll request review from you.

[dexcompiler]

@copilot I made some more changes. Review

[Copilot]

@dexcompiler I've opened a new pull request, #48, to work on those changes. Once the pull request is ready, I'll request review from you.

[dexcompiler]

@cursoragent I made more changes since your last review. Take a look at the latest commits!

[cursor]

Yep — I pulled the PR branch again and reviewed the latest commits (now up through 020611d), and re-ran the full suite: dotnet test -c Release is green.

What changed since my last review (and looks good)

• HlcTimestamp.FromPackedInt64: fixed the signed-shift/sign-extension edge case by decoding via ulong + masking (and you added a focused regression test in tests/HlcTimestampTests.cs). This directly addresses my prior nit.
• VectorClockBuilder.Merge: switched the large-buffer path to ArrayPool<byte> (keeping stackalloc for small sizes). Nice improvement and keeps the “allocation-conscious hot path” story consistent.
• VectorClock canonicalization: CreateCanonical now uses a max-by-node dictionary + CollectionsMarshal.GetValueRefOrAddDefault and then sorts keys; behavior stays canonical/deterministic and should be faster on messy inputs.
• Docs/tests: README got wire-format clarification, and UuidV7Factory got a throughput-oriented batch path plus additional tests and analyzer cleanup (CA2208, unreachable default).

Minor nits (non-blocking)

• ArrayPool<byte>.Shared.Return(rented): consider explicitly passing clearArray: false/true to make intent obvious (perf vs data hygiene). Not required, just a readability/intent tweak.