causal_machines 0.6.1-aarch64-linux
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +84 -0
- data/LICENSE.txt +21 -0
- data/README.md +288 -0
- data/ext/causal_machines_native/core/CHANGELOG.md +59 -0
- data/ext/causal_machines_native/core/README.md +118 -0
- data/ext/causal_machines_native/extconf.rb +2 -0
- data/lib/causal_machines/version.rb +5 -0
- data/lib/causal_machines.rb +93 -0
- data/lib/causal_machines_native/causal_machines_native.so +0 -0
- data/sig/causal_machines.rbs +148 -0
- metadata +62 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 625bd3c7e93ed190123dac498306bc5e49d96f66ae276c65a36ba097062190ad
|
|
4
|
+
data.tar.gz: 136e2407b0ef91549e1852caa0f9cff8b5bfc787d808c802206c925e2b1af46a
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: ebb810755188d285ac883694ec5e83df7c446774fe22d821b94f5193a113356d169513c0f7b5697e1b7cb3a4b0a8804f1079ae33217627055bd62574f86b62dd
|
|
7
|
+
data.tar.gz: a377230cb64ec2a78684140c4da5d2010f513d00b06c76ca1e544dc45d3d1d3721fe1f18c72410f3646b1d80f21d9ece2c0256c0db3a50cb5b41625a30647063
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.6.1](https://github.com/seuros/causal_machines/compare/causal_machines/v0.6.0...causal_machines/v0.6.1) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* fix wrapped classes at load so building a value runs no Ruby ([f94dbaf](https://github.com/seuros/causal_machines/commit/f94dbaf0302fe295327dcaf133830caf33551cc2))
|
|
9
|
+
|
|
10
|
+
## [0.6.0](https://github.com/seuros/causal_machines/compare/causal_machines/v0.5.1...causal_machines/v0.6.0) (2026-11-16)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### ⚠ BREAKING CHANGES
|
|
14
|
+
|
|
15
|
+
* make Stamp fields private and rename Page::written to gaps
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* make Stamp fields private and rename Page::written to gaps ([72e7251](https://github.com/seuros/causal_machines/commit/72e72511df535122c04c82b59293b7fbb7634063))
|
|
20
|
+
|
|
21
|
+
## [0.5.1](https://github.com/seuros/causal_machines/compare/causal_machines/v0.5.0...causal_machines/v0.5.1) (2026-11-14)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Bug Fixes
|
|
25
|
+
|
|
26
|
+
* **deps:** require matryona-machines >= 0.4 ([c0738ff](https://github.com/seuros/causal_machines/commit/c0738ffd0a2e4f98d60d7ad36d0b5fa4506107b5))
|
|
27
|
+
|
|
28
|
+
## [0.5.0](https://github.com/seuros/causal_machines/compare/causal_machines/v0.4.0...causal_machines/v0.5.0) (2026-11-14)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### ⚠ BREAKING CHANGES
|
|
32
|
+
|
|
33
|
+
* adopt matryona 0.3 integer_in for the missing limit
|
|
34
|
+
|
|
35
|
+
### Features
|
|
36
|
+
|
|
37
|
+
* adopt matryona 0.3 integer_in for the missing limit ([af296fc](https://github.com/seuros/causal_machines/commit/af296fc8d2d545e22594a39cf4f3bb271dd6cefc))
|
|
38
|
+
|
|
39
|
+
## [0.4.0](https://github.com/seuros/causal_machines/compare/causal_machines/v0.3.0...causal_machines/v0.4.0) (2026-11-14)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### ⚠ BREAKING CHANGES
|
|
43
|
+
|
|
44
|
+
* adopt matryona-machines 0.2: exact readers, symbols! tables, struct-only field reads
|
|
45
|
+
|
|
46
|
+
### Features
|
|
47
|
+
|
|
48
|
+
* adopt matryona-machines 0.2: exact readers, symbols! tables, struct-only field reads ([929e75f](https://github.com/seuros/causal_machines/commit/929e75f291a4e87ee25226b0c6e05e99f284339d))
|
|
49
|
+
|
|
50
|
+
## [0.3.0](https://github.com/seuros/causal_machines/compare/causal_machines/v0.2.0...causal_machines/v0.3.0) (2026-11-14)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
### ⚠ BREAKING CHANGES
|
|
54
|
+
|
|
55
|
+
* validate Page and Gap in the core, refuse unissued missing cursors, seal values, clone-then-keep stamp/release
|
|
56
|
+
|
|
57
|
+
### Features
|
|
58
|
+
|
|
59
|
+
* validate Page and Gap in the core, refuse unissued missing cursors, seal values, clone-then-keep stamp/release ([87b24f6](https://github.com/seuros/causal_machines/commit/87b24f6c6c4c295e142fdafa01de7ab5e2dee17b))
|
|
60
|
+
|
|
61
|
+
## [0.2.0](https://github.com/seuros/causal_machines/compare/causal_machines/v0.1.2...causal_machines/v0.2.0) (2026-11-13)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
### ⚠ BREAKING CHANGES
|
|
65
|
+
|
|
66
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. check and missing can answer Conflict; the Ruby class is Causal; release answers Deliver or Obsolete values.
|
|
67
|
+
|
|
68
|
+
### Features
|
|
69
|
+
|
|
70
|
+
* check conflicts on every receive path, Conflict and Full are refusals, forget answers Forgetting ([b2867a8](https://github.com/seuros/causal_machines/commit/b2867a83677cdc2180e9b771ce36eb4ed78624a9))
|
|
71
|
+
|
|
72
|
+
## [0.1.2](https://github.com/seuros/causal_machines/compare/causal_machines/v0.1.1...causal_machines/v0.1.2) (2026-11-13)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
### Features
|
|
76
|
+
|
|
77
|
+
* implement Default for Gap ([5aa1b2c](https://github.com/seuros/causal_machines/commit/5aa1b2c5029d9d45da2f1f8ca3fdfd19a659b8f7))
|
|
78
|
+
|
|
79
|
+
## [0.1.1](https://github.com/seuros/causal_machines/compare/causal_machines-v0.1.0...causal_machines/v0.1.1) (2026-11-12)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
### Features
|
|
83
|
+
|
|
84
|
+
* initial extraction ([cc9d39b](https://github.com/seuros/causal_machines/commit/cc9d39b5451f58f4762377dfa5dee280be0cbd9f))
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Abdelkader Boudih
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# CausalMachines
|
|
2
|
+
|
|
3
|
+
> The answer does not get to arrive before the question. 🧭
|
|
4
|
+
|
|
5
|
+
A causal-order tracker for Ruby. Every message travels with a stamp: a version vector saying what its sender had already seen. Before you act on a message, you show the tracker its stamp. The tracker tells you whether everything it depends on has been delivered here, exactly what is still missing if not, or that you already had it. Messages that arrive early wait as stamps, not payloads, and come back out the moment their dependencies land.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
gem 'causal_machines'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
members = CausalMachines::Membership.new([1, 2, 3])
|
|
15
|
+
tracker = CausalMachines::Causal.new(members, 3, 0) # members, me, generation
|
|
16
|
+
|
|
17
|
+
def on_message(tracker, stamp, payload, buffer)
|
|
18
|
+
case tracker.receive(stamp)
|
|
19
|
+
when :delivered then apply(payload)
|
|
20
|
+
when :held then buffer[[stamp.sender, stamp.clock]] = payload
|
|
21
|
+
when :duplicate, :already_held then return # seen before, nothing changed
|
|
22
|
+
else raise "tracker refused #{stamp}" # every other symbol is a refusal
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
while (released = tracker.release) # a Deliver or an Obsolete
|
|
26
|
+
ready = released.stamp
|
|
27
|
+
payload = buffer.delete([ready.sender, ready.clock])
|
|
28
|
+
apply(payload) if released.is_a?(CausalMachines::Deliver)
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
stamp = tracker.stamp # for a message you are about to send
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
One tracker per replica. Replica ids, generations and counters are Integers; clocks are `VersionVector` values and the member list a `Membership`. The tracker keeps stamps. The payloads stay with you.
|
|
36
|
+
|
|
37
|
+
## A Message to the Resistance
|
|
38
|
+
|
|
39
|
+
So you built a chat room on three servers. Alice asks "who broke the build?" on server one. Bob, on server two, sees it and answers "you did." Server three hears from Bob first, because networks are like that, and shows Carol an accusation with no question attached.
|
|
40
|
+
|
|
41
|
+
You know the usual fixes. Sort by wall-clock timestamp, and discover that server two's clock runs four seconds ahead, so Bob now answers questions before they are asked on every screen. Switch to a Lamport counter, and get one neat total order that still cannot tell you whether Bob had *seen* Alice's message or just happened to draw a bigger number. A single number can order events. It cannot say which ones were waiting on which.
|
|
42
|
+
|
|
43
|
+
What you need is a partial order: this happened after that, and those two never knew about each other. A version vector is the smallest thing that carries it. One counter per replica, compared entry by entry. The piece you would otherwise rebuild is the delivery rule on top: a message is ready when it is its sender's next one and everything the sender had seen is already here. That rule, the list of what is missing when it fails, and a bounded waiting room for the early arrivals, is this gem.
|
|
44
|
+
|
|
45
|
+
## Chapter 1: Stardate 2026.316, the AMS Fidge
|
|
46
|
+
|
|
47
|
+
> **AMS Fidge**, NCC-4231, *Fidge*-class causality cutter.
|
|
48
|
+
> A reply does not clear customs before the hail it answers.
|
|
49
|
+
|
|
50
|
+
The cutter does not carry cargo and does not chase anyone. It sits on the shipping lane and reads manifests. Every dispatch lists what its sender had on board when it left. The cutter compares that list against its own log and says one of three things: cleared, already logged, or waiting on these specific dispatches from those specific ships.
|
|
51
|
+
|
|
52
|
+
On a bridge somewhere, a cadet volunteers:
|
|
53
|
+
|
|
54
|
+
```ruby
|
|
55
|
+
def on_message(message)
|
|
56
|
+
@inbox << message
|
|
57
|
+
@inbox.sort_by!(&:sent_at).each { |m| show(m) }
|
|
58
|
+
end
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
"That," says the cutter's navigator, "orders the fleet by whose chronometer is the most wrong."
|
|
62
|
+
|
|
63
|
+
## The Flight Plan
|
|
64
|
+
|
|
65
|
+
Each stamp the tracker is shown ends up in one of these states:
|
|
66
|
+
|
|
67
|
+
```mermaid
|
|
68
|
+
stateDiagram-v2
|
|
69
|
+
[*] --> unseen
|
|
70
|
+
unseen --> delivered: receive, dependencies delivered
|
|
71
|
+
unseen --> held: receive, dependencies missing
|
|
72
|
+
unseen --> unseen: receive refused, hold table full, returns :full
|
|
73
|
+
held --> delivered: release, returns Deliver(stamp)
|
|
74
|
+
held --> dropped: release after absorb, returns Obsolete(stamp)
|
|
75
|
+
held --> unseen: forget
|
|
76
|
+
delivered --> delivered: receive again, returns :duplicate
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
And the afternoon Bob's answer overtook Alice's question:
|
|
80
|
+
|
|
81
|
+
```mermaid
|
|
82
|
+
sequenceDiagram
|
|
83
|
+
participant A as Alice (1)
|
|
84
|
+
participant B as Bob (2)
|
|
85
|
+
participant C as Carol (3)
|
|
86
|
+
|
|
87
|
+
A->>B: question [1,0,0]
|
|
88
|
+
Note over B: :delivered
|
|
89
|
+
B->>C: answer [1,1,0]
|
|
90
|
+
Note over C: :held, missing replica 1 counter 1
|
|
91
|
+
A->>C: question [1,0,0]
|
|
92
|
+
Note over C: :delivered
|
|
93
|
+
Note over C: release gives Deliver(answer)
|
|
94
|
+
A->>C: question [1,0,0] (retry)
|
|
95
|
+
Note over C: :duplicate
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## How the Tracker Works
|
|
99
|
+
|
|
100
|
+
### Stamp
|
|
101
|
+
|
|
102
|
+
```ruby
|
|
103
|
+
members = CausalMachines::Membership.new([1, 2, 3])
|
|
104
|
+
alice = CausalMachines::Causal.new(members, 1, 0)
|
|
105
|
+
bob = CausalMachines::Causal.new(members, 2, 0)
|
|
106
|
+
carol = CausalMachines::Causal.new(members, 3, 0)
|
|
107
|
+
|
|
108
|
+
question = alice.stamp
|
|
109
|
+
# => #<data CausalMachines::Stamp generation=0, sender=1,
|
|
110
|
+
# clock=#<data CausalMachines::VersionVector counters=[1, 0, 0, 0, 0, 0, 0, 0]>>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`stamp` numbers your next message and hands back what to send with it. The clock has one counter per membership slot, in the order you listed the members; like the core's `VersionVector<8>`, it always holds `CausalMachines::MEMBERS` counters, the slots past your members at zero. Your own message counts as delivered to you from that moment. At counter `2**64 - 1` it answers `:exhausted` instead.
|
|
114
|
+
|
|
115
|
+
### Receive
|
|
116
|
+
|
|
117
|
+
```ruby
|
|
118
|
+
bob.receive(question) # => :delivered
|
|
119
|
+
answer = bob.stamp # clock counters [1, 1, 0, ...]: Bob had seen Alice's first
|
|
120
|
+
|
|
121
|
+
carol.receive(answer) # => :held, the question is not here yet
|
|
122
|
+
carol.receive(answer) # => :already_held
|
|
123
|
+
carol.receive(question) # => :delivered
|
|
124
|
+
carol.receive(question) # => :duplicate
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`:delivered` means act on it now. `:held` means keep the payload somewhere; the tracker kept the stamp. `:already_held` and `:duplicate` are repeats: the tracker already has what you showed it, so the call is honoured and nothing changes. Anything else `receive` answers is a refusal. `check(stamp)` gives the same verdict (`:deliverable`, `:duplicate`, `:missing`) without changing anything, and the same refusals short of `:full`.
|
|
128
|
+
|
|
129
|
+
### Release
|
|
130
|
+
|
|
131
|
+
```ruby
|
|
132
|
+
carol.release # => #<data CausalMachines::Deliver stamp=answer>
|
|
133
|
+
carol.release # => nil
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
After any delivery, call `release` until it returns `nil`. `nil` means nothing is ready; `release` never refuses. Each call hands back the core's `Release`: a `Deliver(stamp)` for one held stamp whose dependencies have arrived, which now counts as delivered, or an `Obsolete(stamp)` (see Absorb below). One delivery can unblock a chain, so loop.
|
|
137
|
+
|
|
138
|
+
### Missing
|
|
139
|
+
|
|
140
|
+
```ruby
|
|
141
|
+
node = CausalMachines::Causal.new(CausalMachines::Membership.new([1, 2, 3]), 3, 0)
|
|
142
|
+
wanted = CausalMachines::Stamp.new(0, 2, CausalMachines::VersionVector.new([3, 4, 2]))
|
|
143
|
+
|
|
144
|
+
page = node.missing(wanted, 0, 2)
|
|
145
|
+
# page.gaps => [Gap(replica=1, from=1, through=3), Gap(replica=2, from=1, through=3)]
|
|
146
|
+
# page.next => 2
|
|
147
|
+
node.missing(wanted, page.next, 2)
|
|
148
|
+
# => Page(gaps=[Gap(replica=3, from=1, through=2)], next=nil)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`missing(stamp, cursor, limit)` lists what stands between you and that message: per replica, the inclusive run of counters not delivered here. It answers a `Page`. Start at cursor 0, take at most `limit` gaps a call (up to `CausalMachines::MEMBERS`), and pass `page.next` back until it is `nil`. A cursor is a member slot; one past the last member was never handed out, so it is refused with `:unknown_member` (after the stamp itself is judged). These are the ranges to ask your peers for.
|
|
152
|
+
|
|
153
|
+
### Absorb
|
|
154
|
+
|
|
155
|
+
```ruby
|
|
156
|
+
vv = ->(*counters) { CausalMachines::VersionVector.new(counters) }
|
|
157
|
+
node = CausalMachines::Causal.new(CausalMachines::Membership.new([1, 2, 3]), 3, 0)
|
|
158
|
+
late = CausalMachines::Stamp.new(0, 1, vv[2, 0, 0])
|
|
159
|
+
node.receive(late) # => :held
|
|
160
|
+
|
|
161
|
+
node.absorb(0, vv[4, 0, 0]) # => :absorbed, a snapshot already covers 1..4 from replica 1
|
|
162
|
+
node.absorb(0, vv[3, 0, 0]) # => :already_covered, nothing new, nothing changed
|
|
163
|
+
node.clock # => VersionVector counters [4, 0, 0, ...]
|
|
164
|
+
node.release # => #<data CausalMachines::Obsolete stamp=late>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
When you install state that already reflects a clock, `absorb` folds that clock into yours by taking the larger counter in every position, and answers `:absorbed`. When your clock already covers it, the call is an honoured repeat: `:already_covered`, nothing changed. A clock counting a slot outside the membership is refused with `:malformed`. Held stamps it covers come out of `release` as `Obsolete(stamp)`: drop their payloads, do not apply them.
|
|
168
|
+
|
|
169
|
+
### Vectors and memberships
|
|
170
|
+
|
|
171
|
+
```ruby
|
|
172
|
+
vv = ->(*counters) { CausalMachines::VersionVector.new(counters) }
|
|
173
|
+
vv[1, 2].compare(vv[1, 3]) # => :before
|
|
174
|
+
vv[2, 1].compare(vv[1, 2]) # => :concurrent
|
|
175
|
+
vv[1, 3].dominates?(vv[1, 2]) # => true
|
|
176
|
+
vv[2, 1].concurrent?(vv[1, 2]) # => true
|
|
177
|
+
vv[5, 0].merged(vv[2, 9]) # => VersionVector counters [5, 9, 0, ...]
|
|
178
|
+
vv[5, 0].get(0) # => 5
|
|
179
|
+
vv[5, 0].increment(1) # => VersionVector counters [5, 1, 0, ...]
|
|
180
|
+
vv[2**64 - 1].increment(0) # => :exhausted
|
|
181
|
+
vv[1].increment(8) # => :unknown_member
|
|
182
|
+
CausalMachines::VersionVector.new # => all zeros, the core's VersionVector::new
|
|
183
|
+
|
|
184
|
+
members = CausalMachines::Membership.new([10, 20, 30])
|
|
185
|
+
members.slot(20) # => 1
|
|
186
|
+
members.replica(2) # => 30
|
|
187
|
+
members.len # => 3
|
|
188
|
+
members.admits?(vv[0, 0, 0, 1]) # => false, counts a slot outside the members
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
`VersionVector` and `Membership` mirror the core types. `VersionVector.new(counters)` is the core's `from_counters`: up to `MEMBERS` counters, the rest zero. A vector is a value, so `increment` answers a new vector (the core's new counter is its `get(slot)`) or a refusal symbol, and `merged` answers the merge. `compare` answers `:equal`, `:before`, `:after` or `:concurrent`. `Membership.new(ids)` is `Membership::from_slice`: distinct ids, at most `MEMBERS`.
|
|
192
|
+
|
|
193
|
+
### Capacity
|
|
194
|
+
|
|
195
|
+
The tracker holds 64 early stamps and up to 8 members. Past that, `receive` refuses a stamp that would have to wait with `:full`:
|
|
196
|
+
|
|
197
|
+
```ruby
|
|
198
|
+
node = CausalMachines::Causal.new(CausalMachines::Membership.new([1, 2, 3]), 3, 0)
|
|
199
|
+
from_one = ->(n) { CausalMachines::Stamp.new(0, 1, CausalMachines::VersionVector.new([n])) }
|
|
200
|
+
CausalMachines::CAPACITY # => 64
|
|
201
|
+
CausalMachines::MEMBERS # => 8
|
|
202
|
+
(2..65).each { |n| node.receive(from_one[n]) }
|
|
203
|
+
node.receive(from_one[66]) # => :full
|
|
204
|
+
|
|
205
|
+
node.forget(1, 65) # => :forgotten
|
|
206
|
+
node.forget(1, 65) # => :not_held, nothing changed
|
|
207
|
+
node.receive(from_one[66]) # => :held
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
A held stamp is never evicted to make room. `forget(sender, counter)` drops one you have decided to stop waiting for; the sender will have to send it again. It answers `:forgotten` when it dropped one and `:not_held` when none was held. Both are honoured: asking to forget a stamp that isn't held is a repeat that changes nothing. A sender outside the membership is refused with `:unknown_member`.
|
|
211
|
+
|
|
212
|
+
### Conflict
|
|
213
|
+
|
|
214
|
+
```ruby
|
|
215
|
+
vv = ->(*counters) { CausalMachines::VersionVector.new(counters) }
|
|
216
|
+
node = CausalMachines::Causal.new(CausalMachines::Membership.new([1, 2, 3]), 3, 0)
|
|
217
|
+
waiting = CausalMachines::Stamp.new(0, 1, vv[2, 1, 0])
|
|
218
|
+
node.receive(waiting) # => :held
|
|
219
|
+
node.receive(CausalMachines::Stamp.new(0, 1, vv[1, 0, 0])) # => :delivered
|
|
220
|
+
|
|
221
|
+
other = CausalMachines::Stamp.new(0, 1, vv[2, 0, 0]) # same sender, same counter, another clock
|
|
222
|
+
node.check(other) # => :conflict
|
|
223
|
+
node.receive(other) # => :conflict, though nothing it depends on is missing
|
|
224
|
+
node.held # => 1, the held stamp is still there
|
|
225
|
+
node.forget(1, 2) # => :forgotten, you have chosen
|
|
226
|
+
node.receive(other) # => :delivered
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Two stamps with the same sender and counter but different clocks cannot both be that sender's message, and the tracker has no way to know which one is. So it refuses the newcomer with `:conflict` whatever it would otherwise have been, ready to deliver, waiting, or already covered, and it never drops or replaces the held stamp to make the answer simpler. `check` and `missing` refuse the same way. The held stamp leaves only through `release`, or through `forget` when you decide the other one is right.
|
|
230
|
+
|
|
231
|
+
### Generations
|
|
232
|
+
|
|
233
|
+
```ruby
|
|
234
|
+
vv = ->(*counters) { CausalMachines::VersionVector.new(counters) }
|
|
235
|
+
node = CausalMachines::Causal.new(CausalMachines::Membership.new([1, 2, 3]), 3, 5)
|
|
236
|
+
node.receive(CausalMachines::Stamp.new(4, 1, vv[1, 0, 0])) # => :stale_generation
|
|
237
|
+
node.receive(CausalMachines::Stamp.new(6, 1, vv[1, 0, 0])) # => :future_generation
|
|
238
|
+
node.receive(CausalMachines::Stamp.new(5, 9, vv[1, 0, 0])) # => :unknown_member
|
|
239
|
+
node.receive(CausalMachines::Stamp.new(5, 1, vv[0, 1, 0])) # => :malformed, sender entry 0
|
|
240
|
+
node.receive(CausalMachines::Stamp.new(5, 1, vv[1, 0, 0, 1])) # => :malformed, outside the members
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### What each call can answer
|
|
244
|
+
|
|
245
|
+
| Call | Honoured | Refusals |
|
|
246
|
+
| --- | --- | --- |
|
|
247
|
+
| `stamp` | a `Stamp` | `:exhausted` |
|
|
248
|
+
| `check` | `:deliverable`, `:duplicate`, `:missing` | `:conflict`, `:stale_generation`, `:future_generation`, `:unknown_member`, `:malformed` |
|
|
249
|
+
| `receive` | `:delivered`, `:held`, `:already_held`, `:duplicate` | `:conflict`, `:full`, `:stale_generation`, `:future_generation`, `:unknown_member`, `:malformed` |
|
|
250
|
+
| `release` | `Deliver(stamp)`, `Obsolete(stamp)`, `nil` | none |
|
|
251
|
+
| `forget` | `:forgotten`, `:not_held` | `:unknown_member` |
|
|
252
|
+
| `missing` | a `Page` (`gaps`, `next`) | `:conflict`, `:stale_generation`, `:future_generation`, `:unknown_member` (sender, or a cursor past the last member), `:malformed` |
|
|
253
|
+
| `absorb` | `:absorbed`, `:already_covered` | `:stale_generation`, `:future_generation`, `:malformed` |
|
|
254
|
+
| `VersionVector#increment` | a new `VersionVector` | `:unknown_member`, `:exhausted` |
|
|
255
|
+
|
|
256
|
+
Each refusal is the snake_case of one core `Refusal` variant. There is no catch-all symbol. No answer records a clock: the tracker takes no time at all, so the clock rule (an answer records `now` exactly when it depends on it) has nothing to apply to. There are no scoped ids either: replica ids, generations and counters are the caller's, not issued by the tracker.
|
|
257
|
+
|
|
258
|
+
Membership is fixed for the life of a tracker. Vectors from a different set of replicas mean nothing here, so the member list carries a generation number and stamps from any other generation are refused. Changing the membership means agreeing on a new generation somewhere else and building new trackers.
|
|
259
|
+
|
|
260
|
+
## The Rules of the Cutter
|
|
261
|
+
|
|
262
|
+
- **Ids, generations and counters are Integers** in `0..2**64-1`. Floats, nil, and strings raise `TypeError`. Out of range raises `RangeError`.
|
|
263
|
+
- **Values are valid or do not exist.** `VersionVector`, `Membership`, `Stamp`, `Gap`, `Page`, `Deliver` and `Obsolete` validate when built, by hand or by the tracker, through the core: a wrong type (an Array where a `VersionVector` belongs, say) raises `TypeError`, a value the core would not build raises `RangeError` (more than `MEMBERS` counters or members, duplicate members, a `Gap` from 0 or running backwards, a `Page` no listing answers: a cursor past the last slot, or more gaps than slots before its cursor). Every value class is final: subclassing one raises `TypeError` and `allocate` is gone, so nothing skips that check.
|
|
264
|
+
- **The binding trusts no value it reads.** Sealing stops accidents, not reflection: a named subclass's constant is bound before `inherited` raises, and `Marshal.load` skips `initialize`. So every value passed in must be an instance of exactly the gem's class (a subclass raises `TypeError`), and its fields are rebuilt through the core's constructors (a forged field raises `RangeError`). A forged value never reaches the core.
|
|
265
|
+
- **The binding never loses work.** Every conversion happens before the core is called, and the classes are resolved once, at load. Building an answer runs Ruby code (`new`), so `stamp` and `release` decide on a copy, build the answer, and keep the copy only if the tracker is still unfrozen and unchanged: if building raises, nothing is applied (no counter spent, no stamp taken from the hold table); if it freezes the tracker, `FrozenError`; if it re-enters and changes the tracker, `RuntimeError`, and the outer call is not applied.
|
|
266
|
+
- **Members are distinct and include you.** Duplicate members raise `RangeError` from `Membership.new`; a local id outside the membership, or a restored clock counting a slot outside it, raises `RangeError` from `Causal.new`/`Causal.restore`.
|
|
267
|
+
- **Refusals don't raise.** `:full`, `:conflict`, `:stale_generation`, `:future_generation`, `:unknown_member`, `:malformed` and `:exhausted` are answers. A refused call changes nothing. `:duplicate`, `:already_held`, `:not_held` and `:already_covered` are not refusals: the call was honoured and there was nothing left to do.
|
|
268
|
+
- **No work is lost to an exception.** Every argument is checked and every class looked up before the tracker changes; `release` cannot hand a stamp out of the hold table and then raise.
|
|
269
|
+
- **Mutating calls never answer a boolean.** Every answer is a value or a symbol, so no refusal can pass for `true` in an `if`. Only the predicates `dominates?`, `concurrent?`, `admits?` and `empty?` answer `true` or `false`.
|
|
270
|
+
- **One stamp per sender and counter.** A second stamp with the same sender and counter but a different clock is a `:conflict` while the first is held, even when the second could be delivered on the spot. The held one is never dropped for it.
|
|
271
|
+
- **Frozen means frozen.** `freeze` the tracker and `stamp`, `receive`, `release`, `forget` and `absorb` raise `FrozenError`. `check` and `missing` still answer.
|
|
272
|
+
|
|
273
|
+
## What You Think You're Doing vs Reality
|
|
274
|
+
|
|
275
|
+
### You Think: "I'll sort by timestamp, then process."
|
|
276
|
+
### Reality: A timestamp orders messages. It does not know which ones had met.
|
|
277
|
+
|
|
278
|
+
Two messages with timestamps 5 and 6 might be a question and its answer, or two strangers typing at once. A sort treats both cases the same, and gets the first one wrong whenever a clock drifts or a packet is slow. The stamp carries what the sender had actually seen, so the tracker can hold the answer for exactly the question it needs and let unrelated messages through without waiting.
|
|
279
|
+
|
|
280
|
+
## What's Yours
|
|
281
|
+
|
|
282
|
+
The tracker lives in your process and forgets everything when the process does. Persist `clock` and rebuild with `Causal.restore` if a restart must not reuse counters or redeliver. Payloads, the buffer that holds them while their stamp waits, the network, retransmission of the gaps `missing` reports, and any agreement on who the members are: all yours. Pre-1.0: breaking changes land in minor versions. It is the rulebook for causal order, not a broadcast runtime.
|
|
283
|
+
|
|
284
|
+
## License
|
|
285
|
+
|
|
286
|
+
MIT License. See [LICENSE.txt](LICENSE.txt) for details.
|
|
287
|
+
|
|
288
|
+
**Remember: the network will deliver the answer first. The question is whether you show it.**
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.7.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.6.0...causal-machines-v0.7.0) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* make Stamp fields private and rename Page::written to gaps
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* make Stamp fields private and rename Page::written to gaps ([72e7251](https://github.com/seuros/causal_machines/commit/72e72511df535122c04c82b59293b7fbb7634063))
|
|
13
|
+
|
|
14
|
+
## [0.6.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.5.0...causal-machines-v0.6.0) (2026-11-14)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### ⚠ BREAKING CHANGES
|
|
18
|
+
|
|
19
|
+
* adopt matryona-machines 0.2: exact readers, symbols! tables, struct-only field reads
|
|
20
|
+
|
|
21
|
+
### Features
|
|
22
|
+
|
|
23
|
+
* adopt matryona-machines 0.2: exact readers, symbols! tables, struct-only field reads ([929e75f](https://github.com/seuros/causal_machines/commit/929e75f291a4e87ee25226b0c6e05e99f284339d))
|
|
24
|
+
|
|
25
|
+
## [0.5.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.4.0...causal-machines-v0.5.0) (2026-11-14)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### ⚠ BREAKING CHANGES
|
|
29
|
+
|
|
30
|
+
* validate Page and Gap in the core, refuse unissued missing cursors, seal values, clone-then-keep stamp/release
|
|
31
|
+
|
|
32
|
+
### Features
|
|
33
|
+
|
|
34
|
+
* validate Page and Gap in the core, refuse unissued missing cursors, seal values, clone-then-keep stamp/release ([87b24f6](https://github.com/seuros/causal_machines/commit/87b24f6c6c4c295e142fdafa01de7ab5e2dee17b))
|
|
35
|
+
|
|
36
|
+
## [0.4.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.3.0...causal-machines-v0.4.0) (2026-11-13)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### ⚠ BREAKING CHANGES
|
|
40
|
+
|
|
41
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. check and missing can answer Conflict; the Ruby class is Causal; release answers Deliver or Obsolete values.
|
|
42
|
+
|
|
43
|
+
### Features
|
|
44
|
+
|
|
45
|
+
* check conflicts on every receive path, Conflict and Full are refusals, forget answers Forgetting ([b2867a8](https://github.com/seuros/causal_machines/commit/b2867a83677cdc2180e9b771ce36eb4ed78624a9))
|
|
46
|
+
|
|
47
|
+
## [0.3.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.2.0...causal-machines-v0.3.0) (2026-11-13)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
### Features
|
|
51
|
+
|
|
52
|
+
* implement Default for Gap ([5aa1b2c](https://github.com/seuros/causal_machines/commit/5aa1b2c5029d9d45da2f1f8ca3fdfd19a659b8f7))
|
|
53
|
+
|
|
54
|
+
## [0.2.0](https://github.com/seuros/causal_machines/compare/causal-machines-v0.1.0...causal-machines-v0.2.0) (2026-11-12)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
### Features
|
|
58
|
+
|
|
59
|
+
* initial extraction ([cc9d39b](https://github.com/seuros/causal_machines/commit/cc9d39b5451f58f4762377dfa5dee280be0cbd9f))
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# causal-machines
|
|
2
|
+
|
|
3
|
+
> **AMS Fidge**, NCC-4231, *Fidge*-class causality cutter.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: decide whether a dispatch may be opened yet, from
|
|
6
|
+
the vector it was stamped with.
|
|
7
|
+
|
|
8
|
+
Allocation-free `no_std` version vectors over a fixed membership, plus the
|
|
9
|
+
causal-delivery readiness check built on them. `VersionVector<N>` compares as a
|
|
10
|
+
partial order (`Equal`, `Before`, `After`, `Concurrent`), answers dominance and
|
|
11
|
+
concurrency, and merges by pointwise maximum. `Membership<N>` binds up to `N`
|
|
12
|
+
distinct replica ids to slots once; a different set of replicas is a different
|
|
13
|
+
membership generation.
|
|
14
|
+
|
|
15
|
+
`Causal<N, P>` is one replica's delivery state: the delivered clock and `P` hold
|
|
16
|
+
slots for the stamps of messages that arrived ahead of their dependencies. A
|
|
17
|
+
stamp is `Deliverable` when it is the sender's next message and everything the
|
|
18
|
+
sender had delivered is delivered here; `Duplicate` when the delivered clock
|
|
19
|
+
already covers it; otherwise `Missing`. `receive` delivers or parks, `release`
|
|
20
|
+
hands back parked stamps one at a time as their dependencies arrive (`None`
|
|
21
|
+
means nothing is ready), `forget` drops a parked stamp and says whether there
|
|
22
|
+
was one (`Forgetting::Forgotten` or `Forgetting::NotHeld`), and
|
|
23
|
+
`missing` lists the undelivered runs per replica into a caller buffer, resumable
|
|
24
|
+
by cursor. A cursor is a membership slot: 0 or a `Page::next` the tracker
|
|
25
|
+
handed out. One past the last slot was never issued and is refused with
|
|
26
|
+
`UnknownMember`, after the stamp itself is judged. It writes the first
|
|
27
|
+
`Page::gaps` entries of `out` and leaves the rest untouched (a refusal
|
|
28
|
+
writes none); build the buffer as `[Gap::default(); K]`. The default is a
|
|
29
|
+
placeholder the core never emits, because counters start at 1. A `Page`'s
|
|
30
|
+
fields are private: `Page::new::<N>(gaps, next)` rebuilds one and answers
|
|
31
|
+
`None` for a page `missing` could not have answered (more gaps than slots, a
|
|
32
|
+
cursor past the slots, or more gaps than slots before the cursor).
|
|
33
|
+
|
|
34
|
+
`Refusal` is the only refusal type, and no public enum is `#[non_exhaustive]`:
|
|
35
|
+
a new variant is a breaking change every caller matches on. A refused call was not honoured and leaves
|
|
36
|
+
the whole value untouched; `Causal` is `PartialEq`, so comparing against a
|
|
37
|
+
clone proves it. A stamp from another membership generation is refused with
|
|
38
|
+
`StaleGeneration` or `FutureGeneration`, an unknown sender with
|
|
39
|
+
`UnknownMember`, a clock counting outside the membership (or a zero sender
|
|
40
|
+
entry) with `Malformed`, and a counter at `u64::MAX` with `Exhausted`. A stamp
|
|
41
|
+
that must wait is refused with `Full` when no hold slot is free.
|
|
42
|
+
|
|
43
|
+
A stamp is refused with `Conflict` when a different stamp with the same sender
|
|
44
|
+
and counter is parked, on every path: whether the incoming stamp would have
|
|
45
|
+
been delivered, parked, or called a duplicate. Two stamps numbered alike with
|
|
46
|
+
different clocks cannot both be the sender's message, and the tracker cannot
|
|
47
|
+
tell which is, so it never drops or replaces the parked one for the other.
|
|
48
|
+
`check` and `missing` refuse the same way, so `check` answers what `receive`
|
|
49
|
+
would do. Parked stamps leave the hold table three ways only: handed back by
|
|
50
|
+
`release` (`Deliver` or `Obsolete`), dropped by name with `forget`, which is
|
|
51
|
+
how a caller resolves a conflict in favour of the refused stamp, or delivered
|
|
52
|
+
by `receive` when the identical stamp arrives again and is now ready. `absorb`
|
|
53
|
+
never touches the hold table.
|
|
54
|
+
|
|
55
|
+
`absorb` answers `Absorbing::Absorbed` when the clock advanced the delivered
|
|
56
|
+
clock and `Absorbing::AlreadyCovered` when the delivered clock already
|
|
57
|
+
dominated it: an idempotent repeat, provable from the delivered clock alone,
|
|
58
|
+
that changes nothing.
|
|
59
|
+
|
|
60
|
+
| Operation | Honoured | Refusals |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `stamp() -> Result<Stamp, Refusal>` | the stamp | `Exhausted` |
|
|
63
|
+
| `check(&stamp) -> Result<Readiness, Refusal>` | `Deliverable`, `Duplicate`, `Missing` | `StaleGeneration`, `FutureGeneration`, `UnknownMember`, `Malformed`, `Conflict` |
|
|
64
|
+
| `receive(&stamp) -> Result<Receipt, Refusal>` | `Delivered`, `Held`, `AlreadyHeld`, `Duplicate` | as `check`, plus `Full` |
|
|
65
|
+
| `release() -> Option<Release>` | a release, or `None` when nothing is ready | none |
|
|
66
|
+
| `forget(sender, counter) -> Result<Forgetting, Refusal>` | `Forgotten`, `NotHeld` | `UnknownMember` |
|
|
67
|
+
| `missing(&stamp, cursor, out) -> Result<Page, Refusal>` | the page | as `check`, then `UnknownMember` for a cursor past the last membership slot |
|
|
68
|
+
| `absorb(generation, &clock) -> Result<Absorbing, Refusal>` | `Absorbed`, `AlreadyCovered` | `StaleGeneration`, `FutureGeneration`, `Malformed` |
|
|
69
|
+
| `VersionVector::increment(slot) -> Result<u64, Refusal>` | the new counter | `UnknownMember`, `Exhausted` |
|
|
70
|
+
|
|
71
|
+
`Receipt::AlreadyHeld`, `Receipt::Duplicate`, `Forgetting::NotHeld` and
|
|
72
|
+
`Absorbing::AlreadyCovered` are idempotent repeats: what the caller asked for
|
|
73
|
+
already holds, so the call is honoured and changes nothing. In Ruby every
|
|
74
|
+
honoured outcome is the snake-case symbol of its variant.
|
|
75
|
+
|
|
76
|
+
No operation takes or records a clock: the core has no notion of time, so no
|
|
77
|
+
answer depends on `now`. It issues no ids either: replicas, generations and
|
|
78
|
+
counters are the caller's.
|
|
79
|
+
|
|
80
|
+
The values validate where they are built. `Membership::from_slice` refuses
|
|
81
|
+
duplicates and more than `N` ids, `Gap::new` refuses a run starting at 0 or
|
|
82
|
+
ending before it starts (its fields are private, read through `replica()`,
|
|
83
|
+
`from()` and `through()`, so no `Gap` skips that check), and `Stamp::new` and
|
|
84
|
+
`VersionVector::from_counters` accept every input; the receiving tracker judges
|
|
85
|
+
a stamp. A `Stamp` reads its parts through `generation()`, `sender()` and
|
|
86
|
+
`clock()`. In release builds no operation panics: an arm the invariants rule
|
|
87
|
+
out (a membership slot past `N`) is a `debug_assert!` that answers the most
|
|
88
|
+
conservative result with nothing changed.
|
|
89
|
+
|
|
90
|
+
This is a policy core. It stores stamps, never payloads. It has no transport, no
|
|
91
|
+
retransmission, no persistence, no clock and no membership change protocol. The
|
|
92
|
+
caller keys its own payload buffer by `(sender, counter)`, asks peers for the
|
|
93
|
+
gaps `missing` reports, and persists the delivered clock if a restart must not
|
|
94
|
+
reissue counters (`Causal::restore`).
|
|
95
|
+
|
|
96
|
+
```rust
|
|
97
|
+
use causal_machines::{Causal, Gap, Membership, Receipt, Release};
|
|
98
|
+
|
|
99
|
+
let members = Membership::<3>::from_slice(&[1, 2, 3]).expect("distinct ids");
|
|
100
|
+
let mut alice = Causal::<3, 4>::new(members, 1, 0).expect("member");
|
|
101
|
+
let mut bob = Causal::<3, 4>::new(members, 2, 0).expect("member");
|
|
102
|
+
let mut carol = Causal::<3, 4>::new(members, 3, 0).expect("member");
|
|
103
|
+
|
|
104
|
+
let question = alice.stamp().expect("counter has room");
|
|
105
|
+
assert_eq!(bob.receive(&question), Ok(Receipt::Delivered));
|
|
106
|
+
let answer = bob.stamp().expect("counter has room");
|
|
107
|
+
|
|
108
|
+
// The answer overtakes the question on the way to Carol.
|
|
109
|
+
assert_eq!(carol.receive(&answer), Ok(Receipt::Held));
|
|
110
|
+
let mut gaps = [Gap::default(); 3];
|
|
111
|
+
let page = carol.missing(&answer, 0, &mut gaps).expect("well formed");
|
|
112
|
+
assert_eq!((page.gaps(), page.next()), (1, None));
|
|
113
|
+
assert_eq!(Some(gaps[0]), Gap::new(1, 1, 1));
|
|
114
|
+
|
|
115
|
+
assert_eq!(carol.receive(&question), Ok(Receipt::Delivered));
|
|
116
|
+
assert_eq!(carol.release(), Some(Release::Deliver(answer)));
|
|
117
|
+
assert_eq!(carol.release(), None);
|
|
118
|
+
```
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'causal_machines/version'
|
|
4
|
+
|
|
5
|
+
# Every value below validates at construction through the core: a wrong type
|
|
6
|
+
# raises TypeError, a value the core would not build raises RangeError. A value
|
|
7
|
+
# built by hand is held to the same rule as one the gem returned.
|
|
8
|
+
module CausalMachines
|
|
9
|
+
# The core's `VersionVector<MEMBERS>`: one counter per membership slot.
|
|
10
|
+
# `VersionVector.new` is the core's `new()` (nothing seen) and
|
|
11
|
+
# `VersionVector.new(counters)` its `from_counters`: at most MEMBERS
|
|
12
|
+
# Integers in 0..2**64-1; slots not given count zero, so `counters` always
|
|
13
|
+
# holds MEMBERS entries. Methods (native): get, increment, compare,
|
|
14
|
+
# dominates?, concurrent?, merged.
|
|
15
|
+
VersionVector = Data.define(:counters) do
|
|
16
|
+
def initialize(counters: [])
|
|
17
|
+
super(counters: CausalMachines.__send__(:__counters, counters))
|
|
18
|
+
end
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# The core's `Membership<MEMBERS>`: up to MEMBERS distinct replica ids,
|
|
22
|
+
# each bound to the slot of its position, as `Membership::from_slice`
|
|
23
|
+
# accepts them (duplicates or too many raise RangeError). Methods (native):
|
|
24
|
+
# slot, replica, len, empty?, admits?.
|
|
25
|
+
Membership = Data.define(:ids) do
|
|
26
|
+
def initialize(ids:)
|
|
27
|
+
super(ids: CausalMachines.__send__(:__ids, ids))
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# Causal metadata one message travels with: the sender's VersionVector at
|
|
32
|
+
# send time. Like the core's `Stamp::new`, any generation and sender build
|
|
33
|
+
# one; the receiving tracker judges it.
|
|
34
|
+
Stamp = Data.define(:generation, :sender, :clock) do
|
|
35
|
+
def initialize(generation:, sender:, clock:)
|
|
36
|
+
generation, sender, clock = CausalMachines.__send__(:__stamp, generation, sender, clock)
|
|
37
|
+
super
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# Causal#release: a held stamp whose dependencies arrived; it is now
|
|
42
|
+
# delivered, so apply its payload. The core's `Release::Deliver(stamp)`.
|
|
43
|
+
Deliver = Data.define(:stamp) do
|
|
44
|
+
def initialize(stamp:)
|
|
45
|
+
super(stamp: CausalMachines.__send__(:__release, stamp))
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Causal#release: a held stamp the delivered clock already covers; drop its
|
|
50
|
+
# payload. The core's `Release::Obsolete(stamp)`.
|
|
51
|
+
Obsolete = Data.define(:stamp) do
|
|
52
|
+
def initialize(stamp:)
|
|
53
|
+
super(stamp: CausalMachines.__send__(:__release, stamp))
|
|
54
|
+
end
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
# An inclusive run of undelivered counters from one replica, as `Gap::new`
|
|
58
|
+
# accepts it: 1 <= from <= through.
|
|
59
|
+
Gap = Data.define(:replica, :from, :through) do
|
|
60
|
+
def initialize(replica:, from:, through:)
|
|
61
|
+
replica, from, through = CausalMachines.__send__(:__gap, replica, from, through)
|
|
62
|
+
super
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# One bounded page of a missing-dependency listing. `gaps` holds the entries
|
|
67
|
+
# the core writes to its output buffer (it reports their count as `written`),
|
|
68
|
+
# at most MEMBERS; `next` is the cursor for the next call, a slot below
|
|
69
|
+
# MEMBERS, or nil when the listing is done.
|
|
70
|
+
Page = Data.define(:gaps, :next) do
|
|
71
|
+
def initialize(gaps:, next:)
|
|
72
|
+
gaps, cursor = CausalMachines.__send__(:__page, gaps, binding.local_variable_get(:next))
|
|
73
|
+
super(gaps: gaps, next: cursor)
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# Native is required: no algorithm fallback. It validates and builds the Data
|
|
79
|
+
# values above, so they must exist first.
|
|
80
|
+
require 'causal_machines_native/causal_machines_native'
|
|
81
|
+
|
|
82
|
+
module CausalMachines
|
|
83
|
+
private_class_method :__counters, :__ids, :__stamp, :__release, :__gap, :__page
|
|
84
|
+
|
|
85
|
+
# The values are final. `initialize` is where each validates, and a subclass
|
|
86
|
+
# could override it, or `allocate` build an instance that never ran it:
|
|
87
|
+
# subclassing raises TypeError (as subclassing Class does) and `allocate`
|
|
88
|
+
# is gone. `new`, keywords, `with` and `dup` all still run the check.
|
|
89
|
+
[VersionVector, Membership, Stamp, Deliver, Obsolete, Gap, Page].each do |value|
|
|
90
|
+
value.singleton_class.undef_method(:allocate)
|
|
91
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
92
|
+
end
|
|
93
|
+
end
|
|
Binary file
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
module CausalMachines
|
|
2
|
+
VERSION: String
|
|
3
|
+
MEMBERS: Integer
|
|
4
|
+
CAPACITY: Integer
|
|
5
|
+
|
|
6
|
+
# Why a stamp is not acceptable here at all. A refused call changed nothing.
|
|
7
|
+
# Every refusal is the snake_case of one core `Refusal` variant; there is no
|
|
8
|
+
# catch-all symbol.
|
|
9
|
+
type unfit = :stale_generation | :future_generation | :unknown_member | :malformed
|
|
10
|
+
|
|
11
|
+
# Every value validates at construction through the core: TypeError for a
|
|
12
|
+
# wrong type, RangeError for a value the core would not build. They are
|
|
13
|
+
# final: subclassing one raises TypeError, and `allocate` is undefined.
|
|
14
|
+
|
|
15
|
+
# The core's `VersionVector<MEMBERS>`. `new` with no counters is the core's
|
|
16
|
+
# `new()`; with counters, its `from_counters` (at most MEMBERS, the rest
|
|
17
|
+
# zero, so `counters` always holds MEMBERS entries).
|
|
18
|
+
class VersionVector < Data
|
|
19
|
+
attr_reader counters: Array[Integer]
|
|
20
|
+
def self.new: (?Array[Integer] counters) -> VersionVector
|
|
21
|
+
| (?counters: Array[Integer]) -> VersionVector
|
|
22
|
+
|
|
23
|
+
# The counter at `slot`, or nil past the last slot.
|
|
24
|
+
def get: (Integer slot) -> Integer?
|
|
25
|
+
# Honoured: a new vector counting one more event at `slot` (self is
|
|
26
|
+
# unchanged; the new counter is its `get(slot)`). Refusals:
|
|
27
|
+
# :unknown_member past the last slot, :exhausted at 2**64 - 1.
|
|
28
|
+
def increment: (Integer slot) -> (VersionVector | :unknown_member | :exhausted)
|
|
29
|
+
def compare: (VersionVector other) -> (:equal | :before | :after | :concurrent)
|
|
30
|
+
def dominates?: (VersionVector other) -> bool
|
|
31
|
+
def concurrent?: (VersionVector other) -> bool
|
|
32
|
+
# The core's `merged`: the pointwise maximum.
|
|
33
|
+
def merged: (VersionVector other) -> VersionVector
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# The core's `Membership<MEMBERS>`: distinct replica ids, as
|
|
37
|
+
# `Membership::from_slice` accepts them.
|
|
38
|
+
class Membership < Data
|
|
39
|
+
attr_reader ids: Array[Integer]
|
|
40
|
+
def self.new: (Array[Integer] ids) -> Membership
|
|
41
|
+
| (ids: Array[Integer]) -> Membership
|
|
42
|
+
|
|
43
|
+
def slot: (Integer replica) -> Integer?
|
|
44
|
+
def replica: (Integer slot) -> Integer?
|
|
45
|
+
def len: () -> Integer
|
|
46
|
+
def empty?: () -> bool
|
|
47
|
+
# Whether the vector counts nothing outside these slots.
|
|
48
|
+
def admits?: (VersionVector clock) -> bool
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
class Stamp < Data
|
|
52
|
+
attr_reader generation: Integer
|
|
53
|
+
attr_reader sender: Integer
|
|
54
|
+
attr_reader clock: VersionVector
|
|
55
|
+
def self.new: (Integer generation, Integer sender, VersionVector clock) -> Stamp
|
|
56
|
+
| (generation: Integer, sender: Integer, clock: VersionVector) -> Stamp
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# The core's `Release::Deliver(stamp)`: now delivered, apply its payload.
|
|
60
|
+
class Deliver < Data
|
|
61
|
+
attr_reader stamp: Stamp
|
|
62
|
+
def self.new: (Stamp stamp) -> Deliver
|
|
63
|
+
| (stamp: Stamp) -> Deliver
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# The core's `Release::Obsolete(stamp)`: already covered, drop its payload.
|
|
67
|
+
class Obsolete < Data
|
|
68
|
+
attr_reader stamp: Stamp
|
|
69
|
+
def self.new: (Stamp stamp) -> Obsolete
|
|
70
|
+
| (stamp: Stamp) -> Obsolete
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# As `Gap::new` accepts it: 1 <= from <= through.
|
|
74
|
+
class Gap < Data
|
|
75
|
+
attr_reader replica: Integer
|
|
76
|
+
attr_reader from: Integer
|
|
77
|
+
attr_reader through: Integer
|
|
78
|
+
def self.new: (Integer replica, Integer from, Integer through) -> Gap
|
|
79
|
+
| (replica: Integer, from: Integer, through: Integer) -> Gap
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# At most MEMBERS gaps; `next` is a slot below MEMBERS, or nil.
|
|
83
|
+
class Page < Data
|
|
84
|
+
attr_reader gaps: Array[Gap]
|
|
85
|
+
attr_reader next: Integer?
|
|
86
|
+
def self.new: (Array[Gap] gaps, Integer? next) -> Page
|
|
87
|
+
| (gaps: Array[Gap], next: Integer?) -> Page
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
class Causal
|
|
91
|
+
# RangeError when `local` is not a member (restore: or `delivered` counts
|
|
92
|
+
# a slot outside the membership).
|
|
93
|
+
def self.new: (Membership members, Integer local, Integer generation) -> Causal
|
|
94
|
+
def self.restore: (Membership members, Integer local, Integer generation,
|
|
95
|
+
VersionVector delivered) -> Causal
|
|
96
|
+
|
|
97
|
+
# Honoured: a Stamp. Refusal: :exhausted.
|
|
98
|
+
def stamp: () -> (Stamp | :exhausted)
|
|
99
|
+
|
|
100
|
+
# Answers: :deliverable, :duplicate, :missing. Refusals: the unfit symbols,
|
|
101
|
+
# and :conflict when a different stamp with the same sender and counter
|
|
102
|
+
# is held, whichever of the three the stamp would otherwise be.
|
|
103
|
+
def check: (Stamp stamp) -> (:deliverable | :duplicate | :missing | :conflict | unfit)
|
|
104
|
+
|
|
105
|
+
# Honoured: :delivered, :held, and the repeats :already_held and :duplicate.
|
|
106
|
+
# Refusals: the unfit symbols, :conflict as for check (a held stamp is
|
|
107
|
+
# never dropped or replaced for a different one), and :full when the
|
|
108
|
+
# stamp must wait and no hold slot is free.
|
|
109
|
+
def receive: (Stamp stamp) -> (:delivered | :held | :already_held | :duplicate | :conflict | :full | unfit)
|
|
110
|
+
|
|
111
|
+
# nil when nothing is ready. Never refuses.
|
|
112
|
+
def release: () -> (Deliver | Obsolete | nil)
|
|
113
|
+
|
|
114
|
+
# Honoured: :forgotten when a held stamp was dropped, and the repeat
|
|
115
|
+
# :not_held when none was held. Refusal: :unknown_member. The only call
|
|
116
|
+
# that discards a held stamp without handing it back.
|
|
117
|
+
def forget: (Integer sender, Integer counter) -> (:forgotten | :not_held | :unknown_member)
|
|
118
|
+
|
|
119
|
+
# Honoured: a Page. Refusals: the unfit symbols, :conflict as for check,
|
|
120
|
+
# then :unknown_member when `cursor` is past the last member slot (a
|
|
121
|
+
# cursor the tracker never handed out). RangeError for a limit above
|
|
122
|
+
# MEMBERS.
|
|
123
|
+
def missing: (Stamp stamp, Integer cursor, Integer limit) -> (Page | :conflict | unfit)
|
|
124
|
+
|
|
125
|
+
# Honoured: :absorbed when the delivered clock advanced, and the repeat
|
|
126
|
+
# :already_covered when it already covered `clock` (nothing changed).
|
|
127
|
+
# Refusals: :stale_generation, :future_generation, and :malformed when
|
|
128
|
+
# `clock` counts a slot outside the membership.
|
|
129
|
+
def absorb: (Integer generation, VersionVector clock)
|
|
130
|
+
-> (:absorbed | :already_covered | :stale_generation | :future_generation | :malformed)
|
|
131
|
+
|
|
132
|
+
def clock: () -> VersionVector
|
|
133
|
+
def held: () -> Integer
|
|
134
|
+
def membership: () -> Membership
|
|
135
|
+
def local: () -> Integer
|
|
136
|
+
def generation: () -> Integer
|
|
137
|
+
def capacity: () -> Integer
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
# Private native hooks each Data value's `initialize` validates through.
|
|
141
|
+
# The Arrays answered are frozen copies.
|
|
142
|
+
private def self.__counters: (Array[Integer] counters) -> Array[Integer]
|
|
143
|
+
private def self.__ids: (Array[Integer] ids) -> Array[Integer]
|
|
144
|
+
private def self.__stamp: (Integer generation, Integer sender, VersionVector clock) -> [Integer, Integer, VersionVector]
|
|
145
|
+
private def self.__release: (Stamp stamp) -> Stamp
|
|
146
|
+
private def self.__gap: (Integer replica, Integer from, Integer through) -> [Integer, Integer, Integer]
|
|
147
|
+
private def self.__page: (Array[Gap] gaps, Integer? next) -> [Array[Gap], Integer?]
|
|
148
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: causal_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.6.1
|
|
5
|
+
platform: aarch64-linux
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
autorequire:
|
|
9
|
+
bindir: bin
|
|
10
|
+
cert_chain: []
|
|
11
|
+
date: 2026-11-16 00:00:00.000000000 Z
|
|
12
|
+
dependencies: []
|
|
13
|
+
description: 'Causal-order policy core: parks early stamps until their dependencies
|
|
14
|
+
land; holds no payloads and owns no transport or execution.'
|
|
15
|
+
email:
|
|
16
|
+
- oss@seuros.com
|
|
17
|
+
executables: []
|
|
18
|
+
extensions: []
|
|
19
|
+
extra_rdoc_files: []
|
|
20
|
+
files:
|
|
21
|
+
- CHANGELOG.md
|
|
22
|
+
- LICENSE.txt
|
|
23
|
+
- README.md
|
|
24
|
+
- ext/causal_machines_native/core/CHANGELOG.md
|
|
25
|
+
- ext/causal_machines_native/core/README.md
|
|
26
|
+
- ext/causal_machines_native/extconf.rb
|
|
27
|
+
- lib/causal_machines.rb
|
|
28
|
+
- lib/causal_machines/version.rb
|
|
29
|
+
- lib/causal_machines_native/causal_machines_native.so
|
|
30
|
+
- sig/causal_machines.rbs
|
|
31
|
+
homepage: https://github.com/seuros/causal_machines
|
|
32
|
+
licenses:
|
|
33
|
+
- MIT
|
|
34
|
+
metadata:
|
|
35
|
+
source_code_uri: https://github.com/seuros/causal_machines
|
|
36
|
+
rubygems_mfa_required: 'true'
|
|
37
|
+
cargo_crate_name: causal_machines_native
|
|
38
|
+
cargo_manifest_path: ext/causal_machines_native/ffi/Cargo.toml
|
|
39
|
+
post_install_message:
|
|
40
|
+
rdoc_options: []
|
|
41
|
+
require_paths:
|
|
42
|
+
- lib
|
|
43
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
44
|
+
requirements:
|
|
45
|
+
- - ">="
|
|
46
|
+
- !ruby/object:Gem::Version
|
|
47
|
+
version: '4.0'
|
|
48
|
+
- - "<"
|
|
49
|
+
- !ruby/object:Gem::Version
|
|
50
|
+
version: 4.1.dev
|
|
51
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
52
|
+
requirements:
|
|
53
|
+
- - ">="
|
|
54
|
+
- !ruby/object:Gem::Version
|
|
55
|
+
version: '0'
|
|
56
|
+
requirements: []
|
|
57
|
+
rubygems_version: 3.5.23
|
|
58
|
+
signing_key:
|
|
59
|
+
specification_version: 4
|
|
60
|
+
summary: Fixed-membership version vectors and causal-delivery readiness with a native
|
|
61
|
+
Rust core
|
|
62
|
+
test_files: []
|