escrow_machines 0.7.2-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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: '0277184e829ca0e999251b466a7815f25c7de70c3efa466492513f39989829be'
4
+ data.tar.gz: 818776eb2f70dc1106cae4371d35f27c99f8c53ec18f0eee658280030ff80b47
5
+ SHA512:
6
+ metadata.gz: 7d8c3f036099854be93661e05162e30b4ff34dd66d9d9e5974babc4dd24117c0b2851dd5d2150609454bea003627b7d37e6523d68789a87a3dfd4e0863dacbca
7
+ data.tar.gz: db99428c4afd5d18ba90b8ef67eaf2d7188b0371fe26d84f80161c7e3b61e2445d6144970c9452bf9367774683a99f030088862525b2e62f863fd18466325c09
data/CHANGELOG.md ADDED
@@ -0,0 +1,88 @@
1
+ # Changelog
2
+
3
+ ## [0.7.2](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.7.1...escrow_machines/v0.7.2) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([3e0238a](https://github.com/seuros/escrow_machines/commit/3e0238a43954f3fe90537ac42df5c48cd77868c5))
9
+
10
+ ## [0.7.1](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.7.0...escrow_machines/v0.7.1) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * refuse merges that disagree on a transfer's cumulative total ([cbcafa5](https://github.com/seuros/escrow_machines/commit/cbcafa54cbb866a9f5c425dbcbbad90b09694f6e))
16
+
17
+ ## [0.7.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.6.0...escrow_machines/v0.7.0) (2026-11-16)
18
+
19
+
20
+ ### ⚠ BREAKING CHANGES
21
+
22
+ * fold FrameError into Refusal, new 0xE6 frame of plain tallies
23
+
24
+ ### Features
25
+
26
+ * fold FrameError into Refusal, new 0xE6 frame of plain tallies ([04c0d32](https://github.com/seuros/escrow_machines/commit/04c0d32b6be44d1fdff8a3cec23cd39fbbf54233))
27
+
28
+ ## [0.6.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.5.0...escrow_machines/v0.6.0) (2026-11-14)
29
+
30
+
31
+ ### ⚠ BREAKING CHANGES
32
+
33
+ * escrow partner refusals name the class received
34
+
35
+ ### Features
36
+
37
+ * escrow partner refusals name the class received ([0efa5da](https://github.com/seuros/escrow_machines/commit/0efa5dae455c8a2b571983024753116c57f3c89f))
38
+
39
+ ## [0.5.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.4.0...escrow_machines/v0.5.0) (2026-11-14)
40
+
41
+
42
+ ### ⚠ BREAKING CHANGES
43
+
44
+ * adopt matryona 0.3: decode takes exactly a String, names_only refusals
45
+
46
+ ### Features
47
+
48
+ * adopt matryona 0.3: decode takes exactly a String, names_only refusals ([73f1174](https://github.com/seuros/escrow_machines/commit/73f1174ac829f6b089626409483be444de4ae562))
49
+
50
+ ## [0.4.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.3.0...escrow_machines/v0.4.0) (2026-11-14)
51
+
52
+
53
+ ### ⚠ BREAKING CHANGES
54
+
55
+ * adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged
56
+
57
+ ### Features
58
+
59
+ * adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged ([78045e6](https://github.com/seuros/escrow_machines/commit/78045e6f0722a55c2804920207ae197a1e472ac9))
60
+
61
+ ## [0.3.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.2.0...escrow_machines/v0.3.0) (2026-11-14)
62
+
63
+
64
+ ### ⚠ BREAKING CHANGES
65
+
66
+ * private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound
67
+
68
+ ### Features
69
+
70
+ * private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound ([223b8cb](https://github.com/seuros/escrow_machines/commit/223b8cb5dcb34e5cb615c8f7667b17bb7eac8e16))
71
+
72
+ ## [0.2.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.1.1...escrow_machines/v0.2.0) (2026-11-13)
73
+
74
+
75
+ ### ⚠ BREAKING CHANGES
76
+
77
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. replica/dump/load are local/encode/decode; transfer answers Transfer::Applied or Transfer::Replayed.
78
+
79
+ ### Features
80
+
81
+ * Ruby uses the core's names and positional arguments, Transfer variants as values ([8d83f20](https://github.com/seuros/escrow_machines/commit/8d83f20731ca496ebfb251480f9895e7726b3367))
82
+
83
+ ## [0.1.1](https://github.com/seuros/escrow_machines/compare/escrow_machines-v0.1.0...escrow_machines/v0.1.1) (2026-11-12)
84
+
85
+
86
+ ### Features
87
+
88
+ * initial extraction ([d0edc22](https://github.com/seuros/escrow_machines/commit/d0edc223cc69da6ca9b35d07940545a439464356))
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,254 @@
1
+ # EscrowMachines
2
+
3
+ > You cannot sell the seat twice if you only ever sell the seats you are holding. 🏦
4
+
5
+ A rights ledger for Ruby replicas that can't always talk to each other. A fixed set of replicas shares a fixed supply: seats, credits, stock, quota. Each replica holds part of it and spends only from its own part, with no round trip to anyone. Rights move between replicas by transfer, never by wishful thinking. Merge the replicas in any order, any number of times, and they agree. The total spent never exceeds the supply, partitioned or not.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ gem 'escrow_machines'
11
+ ```
12
+
13
+ ```ruby
14
+ # 100 seats, three regions. Every region builds the same allotment.
15
+ paris = EscrowMachines::Escrow.new(0, [60, 30, 10])
16
+ tokyo = EscrowMachines::Escrow.new(2, [60, 30, 10])
17
+
18
+ tokyo.spend(8) # => 2, seats left in Tokyo
19
+ tokyo.spend(5) # => :insufficient. Paris has 60. Tokyo has 2.
20
+
21
+ receipt = paris.transfer(2, 1, 20).receipt
22
+ save(paris.encode) # persist before the receipt leaves the building
23
+ tokyo.accept(receipt) # => :applied
24
+ tokyo.accept(receipt) # => :replayed, the relay stuttered
25
+ tokyo.spend(5) # => 17
26
+ ```
27
+
28
+ One escrow per replica. `Escrow.new` takes what the core's constructor takes, in its order: `local`, the index of this replica, and `allotted`, every replica's starting rights. `transfer` takes `to`, `id` and `amount`. Amounts, replica indexes and transfer ids are Integers. No clock, no network, no storage: you bring those.
29
+
30
+ ## A Message to the Resistance
31
+
32
+ So you have a hundred seats and three regions, and you put the count in a replicated counter because the conference talk said CRDTs never conflict. They don't. Each region decremented happily through a forty-second partition, the counters merged without a single conflict, and the merged value was minus eleven. Eleven people are now standing in a lobby holding a confirmation email.
33
+
34
+ A PN-counter converges. Converging on a negative number is still converging. What it can't do is say no, because saying no requires knowing something about the other replicas, and the entire point was not asking them.
35
+
36
+ The other fix is asking them: a lock, a leader, a quorum on every sale. Now Tokyo can't sell a seat while the link to Paris is down, which is the outage you bought replicas to avoid.
37
+
38
+ There's a third option from 1986. Split the hundred up front. Each replica owns a share and sells from its share alone. A replica that runs low asks a neighbour for some of theirs, and the neighbour gives away only what it still holds. Nobody ever needs a global answer, because nobody ever spends a right they aren't holding. That's escrow, and the bookkeeping for it is this gem.
39
+
40
+ ## Chapter 1: Stardate 2026.316, the AMS O'Neil
41
+
42
+ > **AMS O'Neil**, NCC-4233, *O'Neil*-class treasury escort.
43
+ > The hold carries what was counted aboard. Nothing more is for sale.
44
+
45
+ The escort doesn't make money. It moves a counted amount between stations and refuses to let anyone spend a chit that isn't physically in the hold. Each station's strongbox has one keyholder. A station can hand chits to another station and log the handover; it cannot reach into someone else's box, and it cannot print.
46
+
47
+ On a bridge somewhere, a cadet volunteers:
48
+
49
+ ```ruby
50
+ def sell(region, seats)
51
+ counter = PNCounter.for(:seats)
52
+ return :sold_out if counter.value < seats
53
+ counter.decrement(region, seats)
54
+ end
55
+ ```
56
+
57
+ "That," says the escort's purser, "checks a number three stations are changing, and then changes it. You've sold the same eleven seats in three time zones."
58
+
59
+ ## The Flight Plan
60
+
61
+ Every right in the supply is in exactly one place at any moment:
62
+
63
+ ```mermaid
64
+ stateDiagram-v2
65
+ [*] --> held: allotted at construction
66
+ held --> spent: spend, by the holder only
67
+ spent --> held: refund, by the replica that spent it
68
+ held --> in_flight: transfer, giver deducts at once
69
+ in_flight --> held: accept or merge, receiver credits
70
+ ```
71
+
72
+ Held plus spent plus in flight always equals the supply. Nothing mints, nothing leaks, and an in-flight right belongs to nobody until its receipt lands.
73
+
74
+ And the afternoon Tokyo ran low while the relay was repeating itself:
75
+
76
+ ```mermaid
77
+ sequenceDiagram
78
+ participant T as Tokyo
79
+ participant P as Paris
80
+ participant D as Paris disk
81
+
82
+ T->>P: need 20, transfer id 1
83
+ P->>P: transfer(2, 1, 20)
84
+ P->>D: encode
85
+ P-->>T: Receipt (lost in the relay)
86
+
87
+ T->>P: need 20, transfer id 1 (retry)
88
+ P->>P: transfer(2, 1, 20)
89
+ Note over P: same id, same Receipt, nothing moves twice
90
+ P-->>T: Receipt
91
+ P-->>T: Receipt (the relay finds the first one)
92
+
93
+ T->>T: accept → :applied
94
+ T->>T: accept → :replayed
95
+ Note over T: 20 seats, once.
96
+ ```
97
+
98
+ ## How the Escrow Works
99
+
100
+ ### Spend
101
+
102
+ ```ruby
103
+ escrow = EscrowMachines::Escrow.new(0, [10, 5])
104
+
105
+ escrow.spend(7) # => 3, what this replica has left
106
+ escrow.spend(4) # => :insufficient
107
+ escrow.available # => 3
108
+ ```
109
+
110
+ `spend` looks at one number: what this replica holds. The other replica's 5 are not part of the question. A refused spend changes nothing.
111
+
112
+ ### Refund
113
+
114
+ ```ruby
115
+ escrow.refund(2) # => 5, back in this replica's hold
116
+ escrow.refund(6) # => :exceeds_spent
117
+ escrow.outstanding(0) # => 5, spent and not refunded
118
+ ```
119
+
120
+ A refund returns rights this replica spent. It can't return more than that, because that would be printing. Refund where you spent: the rights come back to the replica that let them go.
121
+
122
+ ### Transfer
123
+
124
+ ```ruby
125
+ left = EscrowMachines::Escrow.new(0, [10, 0])
126
+ right = EscrowMachines::Escrow.new(1, [10, 0])
127
+
128
+ transfer = left.transfer(1, 1, 4)
129
+ transfer # => #<data EscrowMachines::Transfer::Applied receipt=...>
130
+ receipt = transfer.receipt
131
+ receipt # => #<data EscrowMachines::Receipt from=0, to=1, id=1, amount=4, total=4>
132
+ left.available # => 6, deducted now
133
+
134
+ again = left.transfer(1, 1, 4)
135
+ again.class # => EscrowMachines::Transfer::Replayed. Nothing moved again.
136
+ again.receipt == receipt # => true, the same Receipt
137
+ left.transfer(1, 1, 9) # => :id_conflict
138
+ left.transfer(1, 0, 4) # => :stale_id
139
+ left.transfer(1, 2, 7) # => :insufficient
140
+ ```
141
+
142
+ `transfer` answers the core's `Transfer`: a `Transfer::Applied` when the rights moved now, a `Transfer::Replayed` when this id had already moved them. Both carry the `receipt` to deliver, so `transfer.receipt` works either way. You choose the id. It has to go up for each destination, and a retry reuses the one it's retrying. The latest id is answered `Transfer::Replayed` with its original receipt for as long as it stays the latest. Anything older is `:stale_id`: refused, not repeated.
143
+
144
+ ```ruby
145
+ left.last_transfer(0, 1) # => #<data EscrowMachines::Mark id=1, amount=4>
146
+ left.last_transfer(1, 0) # => nil, nothing has gone that way
147
+ ```
148
+
149
+ ### Accept
150
+
151
+ ```ruby
152
+ right.accept(receipt) # => :applied
153
+ right.accept(receipt) # => :replayed
154
+ right.available # => 4
155
+ ```
156
+
157
+ A receipt says how much `from` has granted `to` in total, not "add four". Deliver it twice, deliver it after a newer one, deliver it to a bystander: the answer is the same grant. A receipt that contradicts what the replica already knows is `:malformed`, `:id_conflict`, or `:forged`, and changes nothing.
158
+
159
+ ### Merge
160
+
161
+ ```ruby
162
+ right.spend(1)
163
+ left.merge(right) # => :merged
164
+ left.balance(1) # => 3, what left now believes right holds
165
+ left.available # => 6, still only its own
166
+ ```
167
+
168
+ `merge` folds in everything another replica knows. Any order, any number of times, any gossip topology. It never makes someone else's rights spendable here. `balance` for another replica is an estimate, and it can be negative when you've seen rights leave a replica before you've seen them arrive there.
169
+
170
+ ### Persist, and what happens when you didn't
171
+
172
+ ```ruby
173
+ frame = left.encode # binary String, Escrow::ENCODED_LEN bytes
174
+ left = EscrowMachines::Escrow.decode(frame) # RangeError if it isn't a sane frame
175
+ ```
176
+
177
+ A replica that restarts from an old frame has forgotten spends it already made. The first peer that remembers them proves it:
178
+
179
+ ```ruby
180
+ stale = EscrowMachines::Escrow.decode(old_frame)
181
+ stale.merge(right) # => :diverged, and stale is untouched
182
+ stale.recover(right) # => :recovered, adopts what right saw of it
183
+ # => :overdrawn if the two histories can't both be true
184
+ ```
185
+
186
+ `recover` is a decision, which is why it isn't `merge`. It restores what some peer witnessed. A spend that never left the lost replica is gone, and no method can find it.
187
+
188
+ ### Capacity
189
+
190
+ ```ruby
191
+ EscrowMachines::CAPACITY # => 8
192
+ EscrowMachines::Escrow.new(0, [1] * 9) # RangeError
193
+ ```
194
+
195
+ Up to eight replicas, fixed when you build the escrow. The set doesn't grow, shrink, or rename itself afterwards.
196
+
197
+ ### What each verb can answer
198
+
199
+ Escrow takes no clock, so no answer records one: every honoured answer, repeats included, depends only on the state and the arguments.
200
+
201
+ | Verb | Honoured | Refusals |
202
+ | --- | --- | --- |
203
+ | `spend` | the Integer left | `:zero_amount`, `:insufficient`, `:overflow` |
204
+ | `refund` | the Integer now held | `:zero_amount`, `:exceeds_spent`, `:overflow` |
205
+ | `transfer` | a `Transfer::Applied`, or the repeat `Transfer::Replayed` | `:zero_amount`, `:unknown_replica`, `:self_transfer`, `:stale_id`, `:id_conflict`, `:insufficient`, `:overflow` |
206
+ | `accept` | `:applied`, or the repeat `:replayed` | `:unknown_replica`, `:malformed`, `:id_conflict`, `:forged`, `:overflow` |
207
+ | `merge` | `:merged` | `:config_mismatch`, `:diverged`, `:overflow` |
208
+ | `recover` | `:recovered` | `:config_mismatch`, `:diverged`, `:overdrawn`, `:overflow` |
209
+
210
+ `Receipt`, `Mark`, `Transfer::Applied` and `Transfer::Replayed` are frozen `Data` values with the fields of the core types they are named after. Method names are the core's: `local`, `replicas`, `supply`, `allotted`, `available`, `balance`, `spent`, `refunded`, `outstanding`, `granted`, `last_transfer`, `encode`, `decode`. The core's `Refusal` has sixteen variants, each with its own symbol and no catch-all. Thirteen come back from calls; the three frame refusals (`:truncated`, `:wrong_structure`, `:wrong_shape`), like a `:malformed` frame, appear only in `decode`'s `RangeError` message, `"the frame is refused: wrong_shape"`. Four of them carry a number in the core (`Insufficient { available }`, `ExceedsSpent { outstanding }`, `StaleId { latest }`, `IdConflict { amount }`); a refusal in Ruby is a bare symbol, and the same numbers are what the readers answer: `available` for `:insufficient`, `outstanding(local)` for `:exceeds_spent`, `last_transfer(local, to).id` for `:stale_id` and `last_transfer(from, to).amount` for `:id_conflict`.
211
+
212
+ `Receipt`, `Mark` and the `Transfer` values are checked by the core when they are built, by hand or by the escrow alike: a receipt naming one replica on both ends, moving zero, or moving more than its `total` raises `RangeError`, as does a `Mark` of zero; a non-Integer field raises `TypeError`, and a `Transfer` value holding anything but a `Receipt` raises `TypeError`. So `accept` never sees a receipt that contradicts itself (the core's `Receipt` has private fields for the same reason), and `:self_transfer` is `transfer`'s answer alone. The four classes are sealed: subclassing one raises `TypeError` and `allocate` is undefined. Sealing stops accidents, not reflection (a named subclass's constant is bound before the raise, `Marshal.load` skips `initialize`), so the binding is the authority: a receipt it reads must be exactly a `Receipt` and is checked by `Receipt::new` again, raising `TypeError` or `RangeError` before the core sees it.
213
+
214
+ ## The Rules of the Escort
215
+
216
+ - **Everything is an Integer** in `0..2**64-1`: amounts, replica indexes, ids. Floats, nil and strings raise `TypeError`. Out of range raises `RangeError`. So does an allotment that adds up past `2**64-1`, a frame `decode` cannot read, and a `Receipt` or `Mark` the core would not build. Nothing raises `ArgumentError` except Ruby itself, for a wrong number of arguments.
217
+ - **A raise changes nothing.** Every argument is checked before the core is called, and every class was resolved once when the extension loaded, so a call that raises left the escrow untouched.
218
+ - **Same allotment everywhere.** Every replica is built from the same `allotted` array. Views built from different ones answer `:config_mismatch` and don't merge.
219
+ - **The binding never loses work.** Every argument is read before the core is called. `transfer` builds its answer from a copy of the escrow kept only once the `Transfer` exists: a build that raises moves no rights, one that freezes the escrow raises `FrozenError`, and one that changes the escrow meanwhile (a redefined `new` calling back in) raises `RuntimeError`; in each case the outer transfer is not applied.
220
+ - **Refusals don't raise.** `:insufficient`, `:exceeds_spent`, `:zero_amount`, `:unknown_replica`, `:self_transfer`, `:stale_id`, `:id_conflict`, `:malformed`, `:forged`, `:config_mismatch`, `:diverged`, `:overdrawn` and `:overflow` are answers. A refused call leaves the escrow exactly as it was.
221
+ - **Counters are lifetime totals.** Grants and spends only count up. A pair that has moved `2**64-1` rights between them over the years answers `:overflow` instead of wrapping.
222
+ - **Frozen means frozen.** `freeze` the escrow and `spend`, `refund`, `transfer`, `accept`, `merge` and `recover` raise `FrozenError`, before any argument is read.
223
+
224
+ ## What You Think You're Doing vs Reality
225
+
226
+ ### You Think: "CRDTs can't conflict, so my counter is safe."
227
+ ### Reality: It merged cleanly to minus eleven.
228
+
229
+ Convergence means everyone ends up with the same number. It doesn't mean the number is one you can live with. An invariant like "never below zero" is a promise about the sum of decisions made by replicas that can't see each other, and the only way to keep it without asking is to hand each replica a budget in advance. That's the difference between a counter and an escrow: one records what happened, the other can refuse.
230
+
231
+ ### You Think: "The transfer timed out, so I'll send it again with a new id."
232
+ ### Reality: Now two transfers happened.
233
+
234
+ The id is the transfer's name. A retry is the same transfer, so it has the same name. A new id is a new transfer, and Paris will cheerfully send another twenty.
235
+
236
+ ## What's Yours
237
+
238
+ This is an early release of a policy core. The API will change. It decides; it doesn't run anything.
239
+
240
+ **Durable replica identity is yours.** `encode` the escrow and get it onto disk before you act on a successful `spend`, `refund` or `transfer`, and before a receipt leaves the process. A replica that comes back from an older frame under the same index can spend the same rights twice, and `:diverged` only tells you after a peer notices. Never run two live processes as the same replica.
241
+
242
+ **Transfer ids are yours.** Per destination, strictly increasing, reused on retry. Only the latest id for a pair replays; keep your retries ahead of your next request.
243
+
244
+ **Transport is yours.** Receipts and frames are values. How they cross the wire, who asks whom for rights, and how much to ask for are your call. Rights in flight are spendable by nobody until the receipt or a merge arrives, so a lost receipt strands rights until gossip catches up.
245
+
246
+ **Authenticity is yours.** `accept` and `merge` catch contradictions, not liars. A fabricated receipt from a replica that never granted anything will be believed. Don't accept frames from anyone you wouldn't hand the strongbox key.
247
+
248
+ **Membership is yours.** The replica set is fixed. Retiring a replica means transferring its rights out first and never using the index again.
249
+
250
+ ## License
251
+
252
+ MIT License. See [LICENSE.txt](LICENSE.txt) for details.
253
+
254
+ **Remember: the counter will merge either way. The question is whether it ever said no.**
@@ -0,0 +1,59 @@
1
+ # Changelog
2
+
3
+ ## [0.6.1](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.6.0...escrow-machines-v0.6.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * refuse merges that disagree on a transfer's cumulative total ([cbcafa5](https://github.com/seuros/escrow_machines/commit/cbcafa54cbb866a9f5c425dbcbbad90b09694f6e))
9
+
10
+ ## [0.6.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.5.0...escrow-machines-v0.6.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * fold FrameError into Refusal, new 0xE6 frame of plain tallies
16
+
17
+ ### Features
18
+
19
+ * fold FrameError into Refusal, new 0xE6 frame of plain tallies ([04c0d32](https://github.com/seuros/escrow_machines/commit/04c0d32b6be44d1fdff8a3cec23cd39fbbf54233))
20
+
21
+ ## [0.5.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.4.0...escrow-machines-v0.5.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged
27
+
28
+ ### Features
29
+
30
+ * adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged ([78045e6](https://github.com/seuros/escrow_machines/commit/78045e6f0722a55c2804920207ae197a1e472ac9))
31
+
32
+ ## [0.4.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.3.0...escrow-machines-v0.4.0) (2026-11-14)
33
+
34
+
35
+ ### ⚠ BREAKING CHANGES
36
+
37
+ * private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound
38
+
39
+ ### Features
40
+
41
+ * private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound ([223b8cb](https://github.com/seuros/escrow_machines/commit/223b8cb5dcb34e5cb615c8f7667b17bb7eac8e16))
42
+
43
+ ## [0.3.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.2.0...escrow-machines-v0.3.0) (2026-11-13)
44
+
45
+
46
+ ### ⚠ BREAKING CHANGES
47
+
48
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. replica/dump/load are local/encode/decode; transfer answers Transfer::Applied or Transfer::Replayed.
49
+
50
+ ### Features
51
+
52
+ * Ruby uses the core's names and positional arguments, Transfer variants as values ([8d83f20](https://github.com/seuros/escrow_machines/commit/8d83f20731ca496ebfb251480f9895e7726b3367))
53
+
54
+ ## [0.2.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.1.0...escrow-machines-v0.2.0) (2026-11-12)
55
+
56
+
57
+ ### Features
58
+
59
+ * initial extraction ([d0edc22](https://github.com/seuros/escrow_machines/commit/d0edc223cc69da6ca9b35d07940545a439464356))
@@ -0,0 +1,64 @@
1
+ # escrow-machines
2
+
3
+ > **AMS O'Neil**, NCC-4233, *O'Neil*-class treasury escort.
4
+
5
+ Engine-room flight manual: move counted rights between stations and never spend what is not in the hold.
6
+
7
+ Allocation-free `no_std` bounded-counter CRDT. A fixed set of up to `N` replicas
8
+ shares a fixed supply of rights. `Escrow<N>` is one replica's view: a matrix of
9
+ cumulative grants between replicas plus per-replica spent and refunded counters.
10
+ `spend` and `transfer` are checked against the rights the local replica holds,
11
+ so the total spent cannot exceed the supply under any partition. `refund`
12
+ returns only what the local replica itself spent. Nothing is minted after
13
+ construction.
14
+
15
+ `merge` is a cell-wise join: commutative, associative, idempotent. `transfer`
16
+ takes a caller-chosen id, strictly increasing per `(from, to)` pair; repeating
17
+ the latest id returns the original `Receipt` and moves nothing. Receipts carry
18
+ the cumulative grant, so `accept` is idempotent and order-insensitive. Every
19
+ refusal is a `Refusal` value and leaves the state untouched; counters refuse at
20
+ `u64::MAX` instead of wrapping.
21
+
22
+ `Escrow` implements the `merge-machines` `Merge` trait. Replica ids are
23
+ dense, `0..replicas` with `replicas <= N`, so every per-replica table is a
24
+ plain `[T; N]` read through a position that is below `N` by construction: a
25
+ lookup cannot miss. The counters are such tables, one `u64` cell per replica
26
+ joined by `max`, so raising one never needs a free slot and its only refusal
27
+ is `Overflow`. Frame refusals are `Refusal` variants like every other
28
+ (`Truncated`, `WrongStructure`, `WrongShape`, `Malformed`); there is no second
29
+ error type. The frame stores each counter as `N` 64-bit fields; it leads with
30
+ `0xE6`, and a frame from before (`0xE5`, which embedded `merge-machines`
31
+ counter frames) is `WrongStructure`.
32
+
33
+ The escrow adds what a PN-counter lacks: writes are restricted to the local
34
+ replica's own cells and bounded by its balance.
35
+
36
+ Contracts the caller owns:
37
+
38
+ - **Durable replica identity.** Persist `encode`'s fixed-length frame before
39
+ acting on a successful call. A replica restarted from an older frame can
40
+ double-spend; `merge` answers `Diverged` once a peer proves it, and `recover`
41
+ adopts the peer's record explicitly (`Overdrawn` if the histories cannot both
42
+ hold). Spends no peer saw are unrecoverable.
43
+ - **Transfer ids.** Monotonic per destination, reused on retry. Only the latest
44
+ id per pair replays; older ids answer `StaleId`.
45
+ - **Authenticity and transport.** Contradictory receipts and frames are refused;
46
+ fabricated but self-consistent ones are not detectable here.
47
+ - **Membership.** The replica set and allotment are fixed at construction and
48
+ must be identical on every replica.
49
+
50
+ `Receipt::new` and `Mark::new` build only values some call could produce
51
+ (`None` for a receipt naming one replica twice, moving zero or more than its
52
+ `total`, and for a mark of zero). Their fields are private, read through
53
+ `from()`, `to()`, `id()`, `amount()`, `total()`, so no receipt contradicts
54
+ itself and `accept` needs no check for one: its `Malformed` is a receipt that
55
+ contradicts the grants already seen.
56
+
57
+ No call takes a clock, so no answer records one.
58
+
59
+ The Ruby gem mirrors `Receipt` and `Mark` as `Data` values of the same names,
60
+ validated through those constructors, and `Transfer` as one `Data` per
61
+ variant, `Transfer::Applied` and `Transfer::Replayed`, each carrying the
62
+ `receipt`.
63
+
64
+ Pre-1.0: breaking changes land in minor versions. No clock, I/O, hashing, or randomness.
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+ module EscrowMachines
3
+ VERSION = '0.7.2'
4
+ end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'escrow_machines/version'
4
+
5
+ module EscrowMachines
6
+ # Proof of one transfer. `total` is everything `from` has ever granted `to`,
7
+ # so delivering a receipt twice, late, or out of order changes nothing.
8
+ # Like the core's `Receipt::new`, it cannot be built contradicting itself:
9
+ # `from == to`, `amount` zero or `amount` above `total` raise RangeError,
10
+ # a non-Integer TypeError.
11
+ Receipt = Data.define(:from, :to, :id, :amount, :total) do
12
+ def initialize(from:, to:, id:, amount:, total:)
13
+ from, to, id, amount, total = EscrowMachines.__send__(:__receipt, from, to, id, amount, total)
14
+ super
15
+ end
16
+ end
17
+
18
+ # What a transfer request did: one of two values, each carrying the
19
+ # `receipt` to deliver, which must be a Receipt (TypeError otherwise).
20
+ module Transfer
21
+ # The rights moved now.
22
+ Applied = Data.define(:receipt) do
23
+ def initialize(receipt:)
24
+ super(receipt: EscrowMachines.__send__(:__transfer, receipt))
25
+ end
26
+ end
27
+ # This id already moved these rights; nothing moved again.
28
+ Replayed = Data.define(:receipt) do
29
+ def initialize(receipt:)
30
+ super(receipt: EscrowMachines.__send__(:__transfer, receipt))
31
+ end
32
+ end
33
+ end
34
+
35
+ # The latest transfer one replica made to another. Like the core's
36
+ # `Mark::new`, an `amount` of zero raises RangeError.
37
+ Mark = Data.define(:id, :amount) do
38
+ def initialize(id:, amount:)
39
+ id, amount = EscrowMachines.__send__(:__mark, id, amount)
40
+ super
41
+ end
42
+ end
43
+ end
44
+
45
+ # Native is required: no algorithm fallback. It validates and builds the Data
46
+ # values above, so they must exist first.
47
+ require 'escrow_machines_native/escrow_machines_native'
48
+
49
+ module EscrowMachines
50
+ private_class_method :__receipt, :__mark, :__transfer
51
+
52
+ # The values are final. `initialize` is where each validates, and a subclass
53
+ # could override it, or `allocate` build an instance that never ran it:
54
+ # subclassing raises TypeError (as subclassing Class does) and `allocate`
55
+ # is gone. `new`, keywords, `with` and `dup` all still run the check.
56
+ [Receipt, Transfer::Applied, Transfer::Replayed, Mark].each do |value|
57
+ value.singleton_class.undef_method(:allocate)
58
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
59
+ end
60
+ end
@@ -0,0 +1,112 @@
1
+ module EscrowMachines
2
+ VERSION: String
3
+ CAPACITY: Integer
4
+
5
+ # Every refusal symbol. A refused call changed nothing. Each method below
6
+ # lists exactly the ones it can answer. No answer records a clock: escrow
7
+ # takes none. Four refusals carry a number in the core and are bare symbols
8
+ # here; read the number instead: :insufficient from `available`,
9
+ # :exceeds_spent from `outstanding(local)`, :stale_id from
10
+ # `last_transfer(local, to).id`, :id_conflict from `last_transfer(from,
11
+ # to).amount`.
12
+ type refusal = :zero_amount | :insufficient | :exceeds_spent | :unknown_replica | :self_transfer
13
+ | :stale_id | :id_conflict | :malformed | :forged | :config_mismatch | :diverged
14
+ | :overdrawn | :overflow
15
+
16
+ # Validated like the core's `Receipt::new`: RangeError when `from == to`,
17
+ # `amount` is zero or `amount` exceeds `total`, or a field is outside
18
+ # 0..2**64-1; TypeError for a non-Integer.
19
+ class Receipt < Data
20
+ attr_reader from: Integer
21
+ attr_reader to: Integer
22
+ attr_reader id: Integer
23
+ attr_reader amount: Integer
24
+ attr_reader total: Integer
25
+ def self.new: (Integer from, Integer to, Integer id, Integer amount, Integer total) -> Receipt
26
+ | (from: Integer, to: Integer, id: Integer, amount: Integer, total: Integer) -> Receipt
27
+ end
28
+
29
+ # Mirrors the core's `Transfer`: one `Data` per variant, each carrying the
30
+ # receipt to deliver. TypeError unless `receipt` is a Receipt.
31
+ module Transfer
32
+ class Applied < Data
33
+ attr_reader receipt: Receipt
34
+ def self.new: (Receipt receipt) -> Applied
35
+ | (receipt: Receipt) -> Applied
36
+ end
37
+
38
+ class Replayed < Data
39
+ attr_reader receipt: Receipt
40
+ def self.new: (Receipt receipt) -> Replayed
41
+ | (receipt: Receipt) -> Replayed
42
+ end
43
+ end
44
+
45
+ type transfer = Transfer::Applied | Transfer::Replayed
46
+
47
+ # Mirrors the core's `Mark`, validated like `Mark::new`: RangeError for an
48
+ # `amount` of zero or a field outside 0..2**64-1, TypeError for a
49
+ # non-Integer.
50
+ class Mark < Data
51
+ attr_reader id: Integer
52
+ attr_reader amount: Integer
53
+ def self.new: (Integer id, Integer amount) -> Mark
54
+ | (id: Integer, amount: Integer) -> Mark
55
+ end
56
+
57
+ class Escrow
58
+ # Bytes of an `encode` frame.
59
+ ENCODED_LEN: Integer
60
+
61
+ # The arguments of the core's `Escrow::new`, in order: the local replica
62
+ # and every replica's starting rights. Raises RangeError when the core
63
+ # answers `ConfigError`: no replica, more than CAPACITY, a `local` outside
64
+ # `allotted`, or a supply past 2**64-1.
65
+ def self.new: (Integer local, Array[Integer] allotted) -> Escrow
66
+ # Raises RangeError for a frame the core cannot decode, TypeError for a
67
+ # non-String.
68
+ def self.decode: (String bytes) -> Escrow
69
+ def encode: () -> String
70
+ # Honoured: the rights this replica has left. Refused: :zero_amount,
71
+ # :insufficient, :overflow.
72
+ def spend: (Integer amount) -> (Integer | :zero_amount | :insufficient | :overflow)
73
+ # Honoured: the rights this replica now holds. Refused: :zero_amount,
74
+ # :exceeds_spent, :overflow.
75
+ def refund: (Integer amount) -> (Integer | :zero_amount | :exceeds_spent | :overflow)
76
+ # Honoured: a Transfer::Applied, or the repeat Transfer::Replayed. Refused:
77
+ # :zero_amount, :unknown_replica, :self_transfer, :stale_id, :id_conflict,
78
+ # :insufficient, :overflow.
79
+ def transfer: (Integer to, Integer id, Integer amount)
80
+ -> (transfer | :zero_amount | :unknown_replica | :self_transfer | :stale_id | :id_conflict
81
+ | :insufficient | :overflow)
82
+ # Honoured: :applied, or the repeat :replayed. Refused: :unknown_replica,
83
+ # :malformed, :id_conflict, :forged, :overflow. A Receipt cannot name one
84
+ # replica twice, so :self_transfer is `transfer`'s alone.
85
+ def accept: (Receipt receipt)
86
+ -> (:applied | :replayed | :unknown_replica | :malformed | :id_conflict | :forged | :overflow)
87
+ # Honoured: :merged. Refused: :config_mismatch, :diverged, :overflow.
88
+ def merge: (Escrow other) -> (:merged | :config_mismatch | :diverged | :overflow)
89
+ # Honoured: :recovered. Refused: :config_mismatch, :diverged, :overdrawn,
90
+ # :overflow.
91
+ def recover: (Escrow other) -> (:recovered | :config_mismatch | :diverged | :overdrawn | :overflow)
92
+ def local: () -> Integer
93
+ def replicas: () -> Integer
94
+ def capacity: () -> Integer
95
+ def supply: () -> Integer
96
+ def available: () -> Integer
97
+ def allotted: (Integer replica) -> Integer?
98
+ def balance: (Integer replica) -> Integer?
99
+ def spent: (Integer replica) -> Integer?
100
+ def refunded: (Integer replica) -> Integer?
101
+ def outstanding: (Integer replica) -> Integer?
102
+ def granted: (Integer from, Integer to) -> Integer?
103
+ def last_transfer: (Integer from, Integer to) -> Mark?
104
+ end
105
+
106
+ # Private native hooks each Data value's `initialize` validates through and
107
+ # stores the answer of.
108
+ private def self.__receipt: (Integer from, Integer to, Integer id, Integer amount, Integer total)
109
+ -> [Integer, Integer, Integer, Integer, Integer]
110
+ private def self.__mark: (Integer id, Integer amount) -> [Integer, Integer]
111
+ private def self.__transfer: (Receipt receipt) -> Receipt
112
+ end
metadata ADDED
@@ -0,0 +1,64 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: escrow_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.7.2
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: 'A fixed set of replicas shares a fixed supply; each spends only from
14
+ the rights it holds and moves rights by transfer, so merges in any order agree and
15
+ the total spent never exceeds the supply. Bound to Ruby from the no_std escrow-machines
16
+ crate: the accounting only, with the transport and durable storage left to the caller.'
17
+ email:
18
+ - oss@seuros.com
19
+ executables: []
20
+ extensions: []
21
+ extra_rdoc_files: []
22
+ files:
23
+ - CHANGELOG.md
24
+ - LICENSE.txt
25
+ - README.md
26
+ - ext/escrow_machines_native/core/CHANGELOG.md
27
+ - ext/escrow_machines_native/core/README.md
28
+ - ext/escrow_machines_native/extconf.rb
29
+ - lib/escrow_machines.rb
30
+ - lib/escrow_machines/version.rb
31
+ - lib/escrow_machines_native/escrow_machines_native.so
32
+ - sig/escrow_machines.rbs
33
+ homepage: https://github.com/seuros/escrow_machines
34
+ licenses:
35
+ - MIT
36
+ metadata:
37
+ source_code_uri: https://github.com/seuros/escrow_machines
38
+ rubygems_mfa_required: 'true'
39
+ cargo_crate_name: escrow_machines_native
40
+ cargo_manifest_path: ext/escrow_machines_native/ffi/Cargo.toml
41
+ post_install_message:
42
+ rdoc_options: []
43
+ require_paths:
44
+ - lib
45
+ required_ruby_version: !ruby/object:Gem::Requirement
46
+ requirements:
47
+ - - ">="
48
+ - !ruby/object:Gem::Version
49
+ version: '4.0'
50
+ - - "<"
51
+ - !ruby/object:Gem::Version
52
+ version: 4.1.dev
53
+ required_rubygems_version: !ruby/object:Gem::Requirement
54
+ requirements:
55
+ - - ">="
56
+ - !ruby/object:Gem::Version
57
+ version: '0'
58
+ requirements: []
59
+ rubygems_version: 3.5.23
60
+ signing_key:
61
+ specification_version: 4
62
+ summary: 'Bounded-counter escrow for Ruby: conserved rights, local spends, replay-safe
63
+ transfers'
64
+ test_files: []