merkle_machines 0.6.3-x86_64-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: 632dbf0fe74e37622916b7e33429307d96b9a96fe8f0adfd72279cbb3c2a73dd
4
+ data.tar.gz: 7a5be07050e1c627b27eef5c8e7d848a5ad75cc43ac01d116b5937634d1ba62b
5
+ SHA512:
6
+ metadata.gz: 06c9b0ad66abe0f778ab8eeca8c4def27a27c5d567b0c7edd47731543e155eb9e23e8cb87c7ba71cdb7b3941aaa71638d1abcc805dffc071613853ebb8811481
7
+ data.tar.gz: e532aedf77c154f4c2ec568b704c2d25bdd4e9b1a740acca116978b3df8ae22667d72e541c9640720c32be6d08fcc9a7556a1ee967262c5a3574a149afe2a79d
data/CHANGELOG.md ADDED
@@ -0,0 +1,91 @@
1
+ # Changelog
2
+
3
+ ## [0.6.3](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.6.2...merkle_machines/v0.6.3) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([8dc7509](https://github.com/seuros/merkle_machines/commit/8dc7509be962e5a4ab0042cf38b5ff0b5cc6f4e5))
9
+
10
+ ## [0.6.2](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.6.1...merkle_machines/v0.6.2) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * index-free merkle survey core; Request#scope reads natively ([5e40549](https://github.com/seuros/merkle_machines/commit/5e40549c8b2bf82827a563797aa3551863da6b66))
16
+
17
+ ## [0.6.1](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.6.0...merkle_machines/v0.6.1) (2026-11-14)
18
+
19
+
20
+ ### Bug Fixes
21
+
22
+ * **deps:** require matryona-machines >= 0.4; Refusals table delegates Schema to Mismatches ([95b4343](https://github.com/seuros/merkle_machines/commit/95b43431d4acaf8ef35c31bc5a309f7157498396))
23
+
24
+ ## [0.6.0](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.5.0...merkle_machines/v0.6.0) (2026-11-14)
25
+
26
+
27
+ ### ⚠ BREAKING CHANGES
28
+
29
+ * adopt matryona 0.3: digests are exactly Strings
30
+
31
+ ### Features
32
+
33
+ * adopt matryona 0.3: digests are exactly Strings ([446543a](https://github.com/seuros/merkle_machines/commit/446543affa559cabd1e20788a8525e977d0a8e99))
34
+
35
+ ## [0.5.0](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.4.0...merkle_machines/v0.5.0) (2026-11-14)
36
+
37
+
38
+ ### ⚠ BREAKING CHANGES
39
+
40
+ * adopt matryona-machines 0.2: native exact_fields readers for every value, native begin/answer/requeue, no reader or deconstruct runs
41
+
42
+ ### Features
43
+
44
+ * adopt matryona-machines 0.2: native exact_fields readers for every value, native begin/answer/requeue, no reader or deconstruct runs ([b360c77](https://github.com/seuros/merkle_machines/commit/b360c775def2c804b7a4c5145cd3b7e855ff667d))
45
+
46
+ ## [0.4.0](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.3.0...merkle_machines/v0.4.0) (2026-11-14)
47
+
48
+
49
+ ### ⚠ BREAKING CHANGES
50
+
51
+ * seal values, check exact classes natively, clone-then-keep requests and drains, native fields helper
52
+
53
+ ### Features
54
+
55
+ * seal values, check exact classes natively, clone-then-keep requests and drains, native fields helper ([eb6ebfa](https://github.com/seuros/merkle_machines/commit/eb6ebfa88033b8f934743af11f8b370d88d60baa))
56
+
57
+ ## [0.3.0](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.2.0...merkle_machines/v0.3.0) (2026-11-13)
58
+
59
+
60
+ ### ⚠ BREAKING CHANGES
61
+
62
+ * handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. A request from another survey answers Stale.
63
+
64
+ ### Features
65
+
66
+ * scope sessions through periscope-machines, add Survey::resumed and issued ([0e54402](https://github.com/seuros/merkle_machines/commit/0e54402d670ce201fe4d18cf61544276005b87be))
67
+
68
+ ## [0.2.0](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.1.2...merkle_machines/v0.2.0) (2026-11-13)
69
+
70
+
71
+ ### ⚠ BREAKING CHANGES
72
+
73
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. requeue returns Result<(), Refusal>; abort returns Aborting; Schema.new raises where the core has no schema.
74
+
75
+ ### Features
76
+
77
+ * requeue and abort answer their real outcome, Ruby Request carries a Node and drain replaces take_ranges ([445d667](https://github.com/seuros/merkle_machines/commit/445d667f19c51a2bbf225af73d2897420a9a4d9a))
78
+
79
+ ## [0.1.2](https://github.com/seuros/merkle_machines/compare/merkle_machines/v0.1.1...merkle_machines/v0.1.2) (2026-11-13)
80
+
81
+
82
+ ### Features
83
+
84
+ * implement Default for LeafRange and name the drain buffer out ([d6e4c5e](https://github.com/seuros/merkle_machines/commit/d6e4c5ec9b67a705d52dcffea34d3a95fad059e7))
85
+
86
+ ## [0.1.1](https://github.com/seuros/merkle_machines/compare/merkle_machines-v0.1.0...merkle_machines/v0.1.1) (2026-11-12)
87
+
88
+
89
+ ### Features
90
+
91
+ * initial extraction ([43dd5e9](https://github.com/seuros/merkle_machines/commit/43dd5e92b117d600f3828fb106b9e4fa798f3f5e))
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,326 @@
1
+ # MerkleMachines
2
+
3
+ > Two replicas disagree. Find out where before you ship the whole dataset. 🧭
4
+
5
+ A divergence survey for Ruby. You have two digest trees of the same shape, one per replica, and their roots differ. The survey tells you which nodes to fetch child digests for, compares what you bring back, and hands you the ranges of leaves that actually differ. It holds a fixed number of nodes and a fixed number of ranges, so a badly diverged pair slows the survey down instead of growing it.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ gem 'merkle_machines'
11
+ ```
12
+
13
+ ```ruby
14
+ schema = MerkleMachines::Schema.new(fanout: 16, depth: 3, partitioning: 1, digest: 1)
15
+ versions = MerkleMachines::Versions.new(local: mine.version, remote: theirs.version)
16
+ # One scope per survey whose requests could meet: two Survey.new are both
17
+ # scope zero, open the same sessions, and honour each other's requests.
18
+ survey = MerkleMachines::Survey.with_scope(1)
19
+
20
+ case survey.begin(schema, theirs.schema, versions, mine.root, theirs.root)
21
+ when :identical then return
22
+ when :diverged then nil
23
+ else raise 'trees are not comparable'
24
+ end
25
+
26
+ until survey.phase == :complete
27
+ if (request = survey.next_request)
28
+ survey.answer(request, versions,
29
+ mine.children(request.node.level, request.node.index),
30
+ theirs.children(request.node.level, request.node.index))
31
+ end
32
+ survey.drain(MerkleMachines::OUTPUT_CAPACITY).each { |leaves| repair(leaves) }
33
+ end
34
+ ```
35
+
36
+ One survey, a handful of methods. Digests are Strings you computed. Everything else is an Integer.
37
+
38
+ ## A Message to the Resistance
39
+
40
+ So your two replicas drifted. A write landed on one during a partition, or a repair job died halfway, and now the row counts match and the checksums don't.
41
+
42
+ You know the textbook answer. "Use a Merkle tree." Hash the leaves, hash the hashes, compare the roots, walk down where they differ. Then you write the walk. It recurses, so a pair of replicas that disagree everywhere allocates a frontier the size of the tree. It talks to the other node from inside the recursion, so a dropped connection loses your place. Someone compacts the remote tree halfway through and you spend an afternoon repairing leaves that were never different. And one day a replica is rebuilt with sixteen children per node instead of eight, the walk compares child 3 with child 3 anyway, and every leaf looks wrong.
43
+
44
+ The walk is a small state machine: which nodes still need their children fetched, which requests are out, which leaf ranges are ready. With a refusal for trees that can't be compared, and a refusal for a tree that moved. That machine is this gem.
45
+
46
+ ## Chapter 1: Stardate 2026.316, the AMS Merkle
47
+
48
+ > **AMS Merkle**, NCC-4224, *Merkle*-class survey cutter.
49
+ > Two charts of the same sector. Mark where they disagree, and nothing else.
50
+
51
+ The cutter doesn't draw charts and doesn't correct them. Two ships surveyed the same sector and came back with two charts. The cutter lays them side by side, quadrant by quadrant, and asks for a closer look only where the summaries differ. It carries a small plotting table, so it asks for a few quadrants at a time and files its findings as it goes.
52
+
53
+ On a bridge somewhere, a cadet volunteers:
54
+
55
+ ```ruby
56
+ def diff(node)
57
+ return [node.leaf] if node.leaf?
58
+ node.children.zip(remote.children(node)).flat_map { |a, b| a.digest == b.digest ? [] : diff(a) }
59
+ end
60
+ ```
61
+
62
+ "That," says the cutter's navigator, "is a network call inside a recursion inside a hope that nobody edits the other chart."
63
+
64
+ ## The Flight Plan
65
+
66
+ A survey moves through four phases:
67
+
68
+ ```mermaid
69
+ stateDiagram-v2
70
+ [*] --> idle
71
+ idle --> complete: begin, roots equal
72
+ idle --> surveying: begin, roots differ
73
+ surveying --> surveying: next_request / answer / requeue
74
+ surveying --> draining: last node resolved
75
+ draining --> complete: drain empties the buffer
76
+ surveying --> complete: last node resolved, buffer already empty
77
+ complete --> surveying: begin again
78
+ surveying --> idle: abort
79
+ draining --> idle: abort
80
+ ```
81
+
82
+ And one exchange, over a tree of four leaves where only leaf 2 differs:
83
+
84
+ ```mermaid
85
+ sequenceDiagram
86
+ participant A as Your code
87
+ participant S as Survey
88
+ participant R as Remote replica
89
+
90
+ A->>S: begin(schema, schema, versions, root, root)
91
+ S-->>A: :diverged
92
+ A->>S: next_request
93
+ S-->>A: Request(level 0, index 0)
94
+ A->>R: children of the root, at version 57
95
+ R-->>A: two digests
96
+ A->>S: answer(request, versions, mine, theirs)
97
+ S-->>A: :accepted
98
+ A->>S: next_request
99
+ S-->>A: Request(level 1, index 1)
100
+ A->>R: children of node 1, at version 57
101
+ R-->>A: two digests
102
+ A->>S: answer(request, versions, mine, theirs)
103
+ S-->>A: :accepted
104
+ A->>S: drain(8)
105
+ S-->>A: [2...3]
106
+ ```
107
+
108
+ ## How the Survey Works
109
+
110
+ ### Schema
111
+
112
+ ```ruby
113
+ schema = MerkleMachines::Schema.new(fanout: 2, depth: 2, partitioning: 1, digest: 1)
114
+ ```
115
+
116
+ `fanout` is children per node, from 2 to 64. `depth` is the number of levels below the root, so this tree has four leaves. `partitioning` and `digest` are numbers you choose to name how keys map to leaves and how digests are computed. The survey never interprets them. It only checks that both sides say the same thing.
117
+
118
+ A shape that is not a tree is not a `Schema`. A fanout outside 2..64, or more leaves than fit in 64 bits, raises `RangeError` from `Schema.new`:
119
+
120
+ ```ruby
121
+ MerkleMachines::Schema.new(fanout: 1, depth: 2, partitioning: 1, digest: 1) # RangeError
122
+ MerkleMachines::Schema.new(fanout: 2, depth: 64, partitioning: 1, digest: 1) # RangeError
123
+ ```
124
+
125
+ ### Begin
126
+
127
+ ```ruby
128
+ versions = MerkleMachines::Versions.new(local: 40, remote: 57)
129
+ survey = MerkleMachines::Survey.new
130
+
131
+ survey.begin(schema, schema, versions, 'root-a', 'root-b') # => :diverged
132
+ survey.phase # => :surveying
133
+ ```
134
+
135
+ A schema answers the questions the core's does:
136
+
137
+ ```ruby
138
+ schema.leaves # => 4
139
+ schema.width(1) # => 2 nodes at level 1
140
+ schema.span(MerkleMachines::Node.new(1, 1)) # => 2...4, the leaves below that node
141
+ schema.span(MerkleMachines::Node.new(3, 0)) # => nil, not a node of this tree
142
+ schema.span(MerkleMachines::Node::ROOT) # => 0...4
143
+ schema.compatible(schema.with(fanout: 4)) # => :fanout_mismatch
144
+ schema.compatible(schema) # => :compatible
145
+ survey.schema # => the open session's Schema, nil when idle
146
+ survey.versions # => the Versions it pinned, nil when idle
147
+ ```
148
+
149
+ Equal roots answer `:identical` and the survey is `:complete` on the spot. Trees that can't be compared are refused by name, and no session opens:
150
+
151
+ ```ruby
152
+ other = schema.with(fanout: 4)
153
+ MerkleMachines::Survey.new.begin(schema, other, versions, 'a', 'b') # => :fanout_mismatch
154
+ ```
155
+
156
+ The others are `:depth_mismatch`, `:partitioning_mismatch` and `:digest_mismatch`. A survey that is still working answers `:busy`.
157
+
158
+ ### Request
159
+
160
+ ```ruby
161
+ request = survey.next_request
162
+ # => #<data MerkleMachines::Request session=1, node=#<data MerkleMachines::Node level=0, index=0>>
163
+ ```
164
+
165
+ A request names one node: `request.node` is a `Node` with a `level` (0 is the root) and an `index` within that level. Fetch that node's child digests from both trees, in child order. `nil` means nothing is queued right now: answers are still out, the range buffer is full, or the survey is finished. Call it as many times as you want requests in the air.
166
+
167
+ ### Answer
168
+
169
+ ```ruby
170
+ survey.answer(request, versions, %w[left same], %w[left changed]) # => :accepted
171
+
172
+ request = survey.next_request
173
+ # => #<data MerkleMachines::Request session=1, node=#<data MerkleMachines::Node level=1, index=1>>
174
+ survey.answer(request, versions, %w[x y], %w[z y]) # => :accepted
175
+ ```
176
+
177
+ The survey compares the two lists position by position and queues the children that differ. Children that match are never visited again. An answer it can't use is refused and changes nothing:
178
+
179
+ ```ruby
180
+ survey = MerkleMachines::Survey.new
181
+ survey.begin(schema, schema, versions, 'root-a', 'root-b')
182
+ request = survey.next_request
183
+
184
+ survey.answer(request, versions.with(remote: 58), %w[a b], %w[a c]) # => :version_changed
185
+ survey.answer(request, versions, %w[a], %w[a c]) # => :arity
186
+ survey.answer(request, versions, %w[a b], %w[a b]) # => :inconsistent
187
+ elsewhere = request.with(node: request.node.with(level: 1))
188
+ survey.answer(elsewhere, versions, %w[a b], %w[a c]) # => :unexpected
189
+ ```
190
+
191
+ `:inconsistent` means the parents differed and no child does, so the digests didn't come from one tree. `:stale` is the answer to a request from a session that was aborted or replaced, or from a survey in another scope.
192
+
193
+ ### Drain
194
+
195
+ ```ruby
196
+ survey.answer(request, versions, %w[a b], %w[a c]) # => :accepted
197
+ survey.answer(survey.next_request, versions, %w[x y], %w[z y])
198
+
199
+ survey.phase # => :draining
200
+ survey.drain(8) # => [2...3]
201
+ survey.phase # => :complete
202
+ survey.pop_range # => nil, nothing buffered
203
+ ```
204
+
205
+ Ranges are leaf indices, end excluded. `drain(limit)` hands back at most `limit` of them, sorted, with neighbours joined, and keeps the rest buffered; `MerkleMachines::OUTPUT_CAPACITY` takes everything there can be. `pop_range` takes just the lowest one, or `nil`. Two calls can return ranges that touch each other, because the second one was found after you took the first.
206
+
207
+ ### Requeue
208
+
209
+ A request you sent and never heard back about goes back in the queue:
210
+
211
+ ```ruby
212
+ survey = MerkleMachines::Survey.new
213
+ survey.begin(schema, schema, versions, 'root-a', 'root-b')
214
+ request = survey.next_request
215
+
216
+ survey.requeue(request) # => :requeued
217
+ survey.requeue(request) # => :unexpected, it is not in flight any more
218
+ survey.next_request == request # => true
219
+ survey.requeue_all # => 1, for when the whole connection dropped
220
+ ```
221
+
222
+ `requeue` answers `:stale` for a request from a session that was aborted or replaced, or from a survey in another scope, and `:unexpected` for a node that is not in flight. Neither changes anything.
223
+
224
+ ### Abort
225
+
226
+ ```ruby
227
+ survey.abort # => :aborted
228
+ survey.phase # => :idle
229
+ survey.abort # => :already_idle, there was no session to drop and nothing changed
230
+ ```
231
+
232
+ Abort when a tree moved under you. The buffered ranges are discarded, every outstanding request becomes `:stale`, and the next `begin` pins the new versions.
233
+
234
+ ### Scopes
235
+
236
+ A request is only meaningful to the survey that issued it. Run more than one survey (one per peer, say) and each needs its own scope, an Integer in `0..65535` carried by every session it opens and every request of that session:
237
+
238
+ ```ruby
239
+ north = MerkleMachines::Survey.with_scope(1)
240
+ south = MerkleMachines::Survey.with_scope(2)
241
+ [north, south].each { |survey| survey.begin(schema, schema, versions, 'mine', 'theirs') }
242
+
243
+ request = north.next_request
244
+ south.next_request
245
+ request.scope # => 1
246
+ request.session # => 281474976710657, scope 1 in the top 16 bits, session 1 below
247
+ south.answer(request, versions, %w[a b], %w[a c]) # => :stale, not one of mine
248
+ south.requeue(request) # => :stale
249
+ north.answer(request, versions, %w[a b], %w[a c]) # => :accepted
250
+ ```
251
+
252
+ `Survey.new` is scope zero, where sessions are plain `1, 2, 3`. The survey can't pick a scope for you: it reads no clock and rolls no dice. Leave two surveys in the same scope and they open the same sessions, so an answer meant for one lands in the other.
253
+
254
+ A restarted survey opens session 1 again, so a request that outlived the restart could name a node in flight in a new session. Resume from a saved count with `Survey.resumed(scope, survey.issued)`, or give each incarnation a new scope. `resumed` brings back the session sequence and nothing else: the survey is idle, earlier requests are `:stale`, and an `issued` above 2**48-1 raises `RangeError`.
255
+
256
+ ### What each call answers
257
+
258
+ | Call | Honoured | Refused, nothing changed |
259
+ | --- | --- | --- |
260
+ | `begin` | `:identical`, `:diverged` | `:fanout_mismatch`, `:depth_mismatch`, `:partitioning_mismatch`, `:digest_mismatch`, `:busy`, `:undersized`, `:exhausted` |
261
+ | `answer` | `:accepted` | `:stale`, `:unexpected`, `:version_changed`, `:arity`, `:inconsistent` |
262
+ | `requeue` | `:requeued` | `:stale`, `:unexpected` |
263
+ | `requeue_all` | the number requeued | never refuses |
264
+ | `drain(limit)` | an Array of Ranges, empty when none is buffered | never refuses |
265
+ | `pop_range` | a Range, or `nil` when none is buffered | never refuses |
266
+ | `next_request` | a `Request`, or `nil` when nothing is queued | never refuses |
267
+ | `abort` | `:aborted`, or `:already_idle` when no session was open (an idempotent repeat) | never refuses |
268
+ | `schema`, `versions` | the open session's `Schema` / `Versions`, or `nil` when the survey is idle | a query, never refuses |
269
+ | `session` | the latest session id issued in this scope, open or not; `nil` while none was ever begun | a query, never refuses |
270
+
271
+ No answer records a clock: the survey takes no time at all. `Versions` are tree versions the caller pins, not instants, and nothing about them is remembered beyond the open session.
272
+
273
+ `session` after `abort` is the aborted session. A resumed survey is idle until its next `begin` and answers the last session issued before the restart, or `nil` when it was resumed from a count of zero.
274
+
275
+ `:undersized` means the tree is deeper than `PENDING_CAPACITY`, and `:exhausted` means the survey has opened all 2**48-1 sessions of its scope. Every refusal has its own symbol; there is no catch-all. The core's `Refusal::Schema(Mismatch)` answers with the mismatch's symbol, the same four `Schema#compatible` uses.
276
+
277
+ ### Capacity
278
+
279
+ ```ruby
280
+ MerkleMachines::PENDING_CAPACITY # => 64
281
+ MerkleMachines::OUTPUT_CAPACITY # => 64
282
+ MerkleMachines::MAX_FANOUT # => 64
283
+
284
+ survey.pending # nodes held: queued, in flight, or answered and waiting for room
285
+ survey.in_flight # requests out
286
+ survey.buffered # ranges waiting for drain
287
+ ```
288
+
289
+ A survey holds at most 64 nodes and 64 ranges. When the range buffer is full, answered nodes wait and `next_request` returns `nil` until you call `drain` or `pop_range`. Nothing is dropped and no answer is refused for lack of room.
290
+
291
+ ## The Rules of the Navigator
292
+
293
+ - **Digests are Strings.** Use binary strings (`.b`). They are compared byte for byte, and two strings with the same bytes in incompatible encodings are different digests. Anything else raises `TypeError`.
294
+ - **Numbers are Integers** in `0..2**64-1`. `fanout`, `depth`, and `level` stop at 255. Floats, nil, and strings raise `TypeError`. Out of range raises `RangeError`.
295
+ - **Schemas, versions, nodes, and requests are value objects.** `Schema`, `Versions`, `Node` and `Request` are frozen `Data` values with the fields of the core types they are named after. An Array in their place raises `TypeError`. They are sealed (subclassing raises `TypeError`, `allocate` is undefined), and since sealing stops accidents, not reflection, the binding is the authority: every value it reads must be an instance of exactly its class, its fields are read straight from the struct and checked again by the core's constructors, so a forged value raises `TypeError` or `RangeError` and never reaches the survey.
296
+ - **Values are valid or do not exist.** Every value is checked by the core when it is built, by you or by the gem: a wrong type raises `TypeError`, a value the core has none for raises `RangeError` (`Schema.new(fanout: 1, ...)`, `Node.new(256, 0)`, `Request.new(0, Node::ROOT)`: sequence zero is no session).
297
+ - **A call that raises changed nothing.** Every check, and every class lookup, runs before the survey moves; the `Request` from `next_request` and the Ranges from `pop_range` and `drain` are built natively from what the core returned, without running any Ruby code (not even `initialize`), so no work is lost to a raise after it.
298
+ - **Scopes.** A `Request` is only meaningful to the survey that issued it. Give each survey its own scope with `Survey.with_scope(scope)`; the core cannot pick one. A `Request` from a survey in another scope is `:stale`. Two surveys in the same scope, `Survey.new` twice included, open the same sessions and alias each other's requests.
299
+ - **Restarts.** Resume from a saved count with `Survey.resumed(scope, issued)`, or give each incarnation a new scope. `resumed` restores the session sequence only; the survey is idle and comparing again is yours.
300
+ - **Refusals don't raise.** Every refusal is a Symbol, and a refused call changes nothing. Only malformed input raises.
301
+ - **One version of each tree per session.** Every answer names the versions its digests were read at. Different versions are refused.
302
+ - **Frozen means frozen.** `freeze` the survey and every method that would change it raises `FrozenError`.
303
+
304
+ ## What You Think You're Doing vs Reality
305
+
306
+ ### You Think: "Merkle trees find the difference with the fewest messages."
307
+ ### Reality: They find it without sending everything.
308
+
309
+ The survey visits the nodes whose digests differ and skips the rest. That is all it promises. It makes no claim about minimal exchange or round count: two replicas that disagree on every leaf cost you every internal node, which is more than shipping the leaves outright. How many requests you keep in the air, how you batch them, and when you give up and copy the lot are your decisions.
310
+
311
+ ### You Think: "Equal digests, equal data."
312
+ ### Reality: Equal digests, and you chose the hash.
313
+
314
+ The survey trusts a matching digest and never looks below it. A collision in your digest hides a difference, and the survey can't know.
315
+
316
+ ## What's Yours
317
+
318
+ This is an early release and the API will change. It is a policy core, not a sync runtime.
319
+
320
+ You build the trees and compute every digest. The survey does no hashing. You talk to the other replica, in whatever protocol and batch size you like, and you decide when a request is lost. You keep each tree readable at the version you pinned for as long as the session runs, or you abort and start over. You pick the `partitioning` and `digest` numbers and make sure equal numbers really mean equal layouts. You decide what a differing leaf range means: the survey locates divergence, it doesn't merge, repair, or pick a winner. And the survey lives in your process, so a restart means a new `begin`.
321
+
322
+ ## License
323
+
324
+ MIT License. See [LICENSE.txt](LICENSE.txt) for details.
325
+
326
+ **Remember: the root told you they differ. The survey tells you where. Fixing it is still your job.**
@@ -0,0 +1,66 @@
1
+ # Changelog
2
+
3
+ ## [0.7.1](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.7.0...merkle-machines-v0.7.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * index-free merkle survey core; Request#scope reads natively ([5e40549](https://github.com/seuros/merkle_machines/commit/5e40549c8b2bf82827a563797aa3551863da6b66))
9
+
10
+ ## [0.7.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.6.0...merkle-machines-v0.7.0) (2026-11-14)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * adopt matryona-machines 0.2: native exact_fields readers for every value, native begin/answer/requeue, no reader or deconstruct runs
16
+
17
+ ### Features
18
+
19
+ * adopt matryona-machines 0.2: native exact_fields readers for every value, native begin/answer/requeue, no reader or deconstruct runs ([b360c77](https://github.com/seuros/merkle_machines/commit/b360c775def2c804b7a4c5145cd3b7e855ff667d))
20
+
21
+ ## [0.6.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.5.0...merkle-machines-v0.6.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * seal values, check exact classes natively, clone-then-keep requests and drains, native fields helper
27
+
28
+ ### Features
29
+
30
+ * seal values, check exact classes natively, clone-then-keep requests and drains, native fields helper ([eb6ebfa](https://github.com/seuros/merkle_machines/commit/eb6ebfa88033b8f934743af11f8b370d88d60baa))
31
+
32
+ ## [0.5.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.4.0...merkle-machines-v0.5.0) (2026-11-13)
33
+
34
+
35
+ ### ⚠ BREAKING CHANGES
36
+
37
+ * handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. A request from another survey answers Stale.
38
+
39
+ ### Features
40
+
41
+ * scope sessions through periscope-machines, add Survey::resumed and issued ([0e54402](https://github.com/seuros/merkle_machines/commit/0e54402d670ce201fe4d18cf61544276005b87be))
42
+
43
+ ## [0.4.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.3.0...merkle-machines-v0.4.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. requeue returns Result<(), Refusal>; abort returns Aborting; Schema.new raises where the core has no schema.
49
+
50
+ ### Features
51
+
52
+ * requeue and abort answer their real outcome, Ruby Request carries a Node and drain replaces take_ranges ([445d667](https://github.com/seuros/merkle_machines/commit/445d667f19c51a2bbf225af73d2897420a9a4d9a))
53
+
54
+ ## [0.3.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.2.0...merkle-machines-v0.3.0) (2026-11-13)
55
+
56
+
57
+ ### Features
58
+
59
+ * implement Default for LeafRange and name the drain buffer out ([d6e4c5e](https://github.com/seuros/merkle_machines/commit/d6e4c5ec9b67a705d52dcffea34d3a95fad059e7))
60
+
61
+ ## [0.2.0](https://github.com/seuros/merkle_machines/compare/merkle-machines-v0.1.0...merkle-machines-v0.2.0) (2026-11-12)
62
+
63
+
64
+ ### Features
65
+
66
+ * initial extraction ([43dd5e9](https://github.com/seuros/merkle_machines/commit/43dd5e92b117d600f3828fb106b9e4fa798f3f5e))
@@ -0,0 +1,114 @@
1
+ # merkle-machines
2
+
3
+ > **AMS Merkle**, NCC-4224, *Merkle*-class survey cutter.
4
+
5
+ Engine-room flight manual: chart where two digest trees disagree, a bounded
6
+ number of nodes at a time.
7
+
8
+ Allocation-free `no_std` comparison traversal over two fixed-depth digest trees
9
+ of the same shape. The survey hands out requests for the child digests of nodes
10
+ whose digests differ, the caller answers with both trees' children, and the
11
+ survey emits the ranges of leaves that differ. It stores no digests and computes
12
+ none: hashing, storage and the exchange with the other replica belong to the
13
+ caller.
14
+
15
+ Two trees are comparable only when their `Schema` matches: fanout, depth, and the
16
+ caller's identifiers for key-to-leaf partitioning and digest algorithm. A
17
+ mismatch is refused by name and opens no session. A session pins one version of
18
+ each tree; an answer read from any other version is refused, because digests
19
+ from a tree that moved cannot be compared with digests from before it moved.
20
+
21
+ Buffers are fixed. `P` bounds the nodes held at once (queued, in flight or
22
+ partly expanded) and must be at least the tree depth; `O` bounds the buffered
23
+ leaf ranges and must be at least one. An answered node keeps its differing
24
+ children as a bit mask and releases them only as slots and output space allow,
25
+ so an answer is never refused for lack of room and a full buffer delays the
26
+ traversal instead of losing work. Lost requests are requeued one by one or all
27
+ at once. Every refusal is a `Refusal`, the crate's one refusal type, and leaves
28
+ the survey unchanged: `begin`, `answer` and `requeue` return
29
+ `Result<_, Refusal>`. Requests carry a session
30
+ id, so answers to an aborted or replaced session are stale. `abort` never
31
+ refuses: it answers `Aborting::Aborted`, or `Aborting::AlreadyIdle` when no
32
+ session was open, an idempotent repeat that changes nothing.
33
+
34
+ **Scopes.** A request is only meaningful to the survey that issued it. Session
35
+ ids come from a `periscope_machines::Issuer`: the survey's scope in the top 16
36
+ bits, a sequence counted from one below, never reissued.
37
+ `Survey::with_scope(scope)` chooses the scope and `new()` is scope zero;
38
+ `Survey::scope` and `Request::scope` read it. `answer` and `requeue` answer
39
+ `Stale` for a request whose session the survey did not issue, before looking at
40
+ any node. Give each survey its own scope: the core reads no clock and no random
41
+ source, so it cannot pick one, and two surveys left in the same scope (two
42
+ `new()` included) issue the same sessions and honour each other's requests. A
43
+ scope is `Exhausted` after 2^48 - 1 sessions. `session()` is the latest session
44
+ issued in the scope, open or not (`Issuer::last`): `None` until the first
45
+ session begins, the aborted session after `abort`. `Request::new` rebuilds a
46
+ request that crossed a wire and is `None` for a session of sequence zero, which
47
+ no survey issues.
48
+
49
+ **Restarts.** A fresh survey opens session one again, so a request that
50
+ outlived a restart could name a node in flight in a new session. Save
51
+ `Survey::issued` and rebuild with `Survey::resumed(scope, issued)`, or give
52
+ each incarnation a new scope. `resumed` restores only the session sequence: the
53
+ survey is idle, every earlier request is `Stale`, and comparing again is the
54
+ caller's job. It is `None` when `issued` is beyond
55
+ `periscope_machines::SEQUENCE_MAX`. A resumed survey's `session()` is the last
56
+ session issued before the restart, which is not open, or `None` when resumed
57
+ from zero.
58
+
59
+ **No clock.** The survey reads and records no time; `Versions` are tree
60
+ versions the caller pins for one session, not instants.
61
+
62
+ The Ruby gem mirrors `Schema`, `Versions`, `Node` and `Request` as `Data`
63
+ values of the same names and fields, each checked by the core when built: where
64
+ `Schema::new` or `Request::new` answers `None`, or a field does not fit the
65
+ core's type, `new` raises `RangeError` (`TypeError` for a wrong type). A
66
+ `LeafRange` is a half-open Ruby `Range`.
67
+
68
+ Buffered ranges are sorted, disjoint and joined when they touch. Ranges taken at
69
+ different times may still touch each other. The traversal visits only nodes
70
+ whose digests differ, deepest first; it makes no claim about minimal exchange or
71
+ round count. Equal digests are trusted to mean equal subtrees, so a digest
72
+ collision hides a difference, and a parent that differs while none of its
73
+ children do is refused as inconsistent.
74
+
75
+ `pop_range` takes one range; `drain(out)` writes as many as fit into the front
76
+ of `out`, returns the count and leaves the rest untouched. Build the buffer as
77
+ `[LeafRange::default(); N]`: the default is the empty range `0..0`, a
78
+ placeholder the survey never emits. A `LeafRange` never runs backwards: its
79
+ fields are private, read through `start()` and `end()`, and
80
+ `LeafRange::new(start, end)` answers `None` when `start > end`, so `len()`
81
+ cannot underflow.
82
+
83
+ ```rust
84
+ use merkle_machines::{Begun, LeafRange, Phase, Schema, Survey, Versions};
85
+
86
+ // Two trees of four leaves; only leaf 2 differs.
87
+ let ours = [[10_u64, 20], [1, 2], [3, 4]];
88
+ let theirs = [[10_u64, 21], [1, 2], [9, 4]];
89
+
90
+ let schema = Schema::new(2, 2, 1, 1).expect("valid shape");
91
+ let versions = Versions { local: 40, remote: 57 };
92
+ let mut survey = Survey::<4, 4>::new();
93
+ assert_eq!(survey.begin(schema, schema, versions, &100_u64, &101_u64), Ok(Begun::Diverged));
94
+
95
+ while let Some(request) = survey.next_request() {
96
+ let node = request.node();
97
+ let row = if node.level == 0 { 0 } else { 1 + node.index as usize };
98
+ assert_eq!(survey.answer(request, versions, &ours[row], &theirs[row]), Ok(()));
99
+ }
100
+ assert_eq!(survey.pop_range(), LeafRange::new(2, 3));
101
+ assert_eq!(survey.phase(), Phase::Complete);
102
+
103
+ // Another survey, another scope: it refuses a request it did not issue.
104
+ use merkle_machines::Refusal;
105
+ let mut north = Survey::<4, 4>::with_scope(1);
106
+ let mut south = Survey::<4, 4>::with_scope(2);
107
+ north.begin(schema, schema, versions, &100_u64, &101_u64).expect("comparable");
108
+ south.begin(schema, schema, versions, &100_u64, &101_u64).expect("comparable");
109
+ let request = north.next_request().expect("the root");
110
+ south.next_request().expect("the root");
111
+ assert_eq!(request.scope(), 1);
112
+ assert_eq!(south.answer(request, versions, &ours[0], &theirs[0]), Err(Refusal::Stale));
113
+ assert_eq!(north.answer(request, versions, &ours[0], &theirs[0]), Ok(()));
114
+ ```
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MerkleMachines
4
+ private_class_method :check_schema, :check_node, :check_versions, :check_request, :schema_leaves,
5
+ :schema_width, :schema_span, :schema_compatible, :request_scope
6
+
7
+ # The root of every tree.
8
+ Node::ROOT = Node.new(0, 0)
9
+
10
+ # The values are sealed. `initialize` is where each validates, and a
11
+ # subclass could override it, or `allocate` build an instance that never ran
12
+ # it: subclassing raises TypeError and `allocate` is gone. Sealing stops
13
+ # accidents, not reflection (a named subclass's constant is bound before
14
+ # `inherited` raises; `Marshal.load` skips `initialize`), so the binding is
15
+ # the authority: it takes an instance of exactly the class asked for, reads
16
+ # its fields from the struct (no reader runs) and the core's constructors
17
+ # check every field again.
18
+ [Node, Schema, Versions, Request].each do |value|
19
+ value.singleton_class.undef_method(:allocate)
20
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
21
+ end
22
+
23
+ # Value objects around the native survey. The traversal itself is native,
24
+ # and so is every value a mutating call returns (`next_request`, `pop_range`,
25
+ # `drain`), built from a copy of the survey that is kept only once the answer
26
+ # exists: frozen meanwhile is FrozenError, changed meanwhile RuntimeError,
27
+ # and in both cases nothing is applied. Each mutating call (`begin`,
28
+ # `answer`, `requeue`, ...) is native and raises FrozenError on a frozen
29
+ # survey before any argument is read.
30
+ class Survey
31
+ # The schema of the open session, nil when the survey is idle.
32
+ def schema
33
+ shape = native_schema
34
+ shape && Schema.new(*shape)
35
+ end
36
+
37
+ # The versions the open session pinned, nil when the survey is idle.
38
+ def versions
39
+ pins = native_versions
40
+ pins && Versions.new(*pins)
41
+ end
42
+ end
43
+ end
@@ -0,0 +1,63 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MerkleMachines
4
+ # The value classes are defined before the native extension loads, so it
5
+ # resolves each one once, at init. Each `initialize` calls a private native
6
+ # hook that holds the value to the core's constructor.
7
+
8
+ # Address of a tree node: `level` 0 is the root, `index` counts left to right
9
+ # within the level. `level` is an Integer in 0..255, `index` in 0...2**64.
10
+ Node = Data.define(:level, :index) do
11
+ def initialize(level:, index:)
12
+ MerkleMachines.__send__(:check_node, level, index)
13
+ super
14
+ end
15
+ end
16
+ # Shape and identity of a fixed-depth digest tree. Two trees are comparable
17
+ # only when all four fields are equal. A shape the core has no schema for
18
+ # raises: `fanout` outside 2..MAX_FANOUT, or more leaves than fit in 64 bits.
19
+ Schema = Data.define(:fanout, :depth, :partitioning, :digest) do
20
+ def initialize(fanout:, depth:, partitioning:, digest:)
21
+ MerkleMachines.__send__(:check_schema, fanout, depth, partitioning, digest)
22
+ super
23
+ end
24
+
25
+ # Total number of leaves.
26
+ def leaves = MerkleMachines.__send__(:schema_leaves, self)
27
+
28
+ # Number of nodes at `level`, saturating past the leaf level.
29
+ def width(level) = MerkleMachines.__send__(:schema_width, self, level)
30
+
31
+ # Leaves below `node` as a half-open Range, nil when the node is not part
32
+ # of the tree.
33
+ def span(node) = MerkleMachines.__send__(:schema_span, self, node)
34
+
35
+ # :compatible, or the first field on which `other` differs:
36
+ # :fanout_mismatch, :depth_mismatch, :partitioning_mismatch, :digest_mismatch.
37
+ def compatible(other) = MerkleMachines.__send__(:schema_compatible, self, other)
38
+ end
39
+
40
+ # Tree versions every digest of one session must be read from: Integers in
41
+ # 0...2**64.
42
+ Versions = Data.define(:local, :remote) do
43
+ def initialize(local:, remote:)
44
+ MerkleMachines.__send__(:check_versions, local, remote)
45
+ super
46
+ end
47
+ end
48
+
49
+ # A request for the child digests of one node, on both trees. `session` is
50
+ # the scoped id of the session it belongs to; only the survey that issued it
51
+ # honours the request. A session of sequence number zero names no session
52
+ # and raises RangeError.
53
+ Request = Data.define(:session, :node) do
54
+ def initialize(session:, node:)
55
+ MerkleMachines.__send__(:check_request, session, node)
56
+ super
57
+ end
58
+
59
+ # The scope of the survey that issued the request's session.
60
+ # Read natively from the struct, never through the readers.
61
+ def scope = MerkleMachines.__send__(:request_scope, self)
62
+ end
63
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MerkleMachines
4
+ VERSION = '0.6.3'
5
+ end
@@ -0,0 +1,8 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'merkle_machines/version'
4
+ require_relative 'merkle_machines/values'
5
+ # Native is required: no algorithm fallback. It resolves the value classes
6
+ # above once, at init.
7
+ require 'merkle_machines_native/merkle_machines_native'
8
+ require_relative 'merkle_machines/survey'
@@ -0,0 +1,142 @@
1
+ module MerkleMachines
2
+ VERSION: String
3
+ PENDING_CAPACITY: Integer
4
+ OUTPUT_CAPACITY: Integer
5
+ MAX_FANOUT: Integer
6
+
7
+ # The core's `Mismatch`: the first field on which two schemas disagree.
8
+ type mismatch = :fanout_mismatch | :depth_mismatch | :partitioning_mismatch | :digest_mismatch
9
+
10
+ # Refusals are symbols, one per core reason, and a refused call changes
11
+ # nothing. `Refusal::Schema(Mismatch)` is the mismatch's own symbol.
12
+ type begin_refusal = mismatch | :undersized | :busy | :exhausted
13
+ type answer_refusal = :stale | :unexpected | :version_changed | :arity | :inconsistent
14
+ type requeue_refusal = :stale | :unexpected
15
+ type refusal = begin_refusal | answer_refusal | requeue_refusal
16
+
17
+ # Native hooks behind the value classes, private to the module. Each
18
+ # raises (TypeError/RangeError) exactly when the core has no value for its
19
+ # arguments; the check_* hooks answer nil otherwise.
20
+ private def self.check_schema: (Integer fanout, Integer depth, Integer partitioning, Integer digest) -> nil
21
+ private def self.check_node: (Integer level, Integer index) -> nil
22
+ private def self.check_versions: (Integer local, Integer remote) -> nil
23
+ private def self.check_request: (Integer session, Node node) -> nil
24
+ private def self.schema_leaves: (Schema shape) -> Integer
25
+ private def self.schema_width: (Schema shape, Integer level) -> Integer
26
+ private def self.schema_span: (Schema shape, Node node) -> Range[Integer]?
27
+ private def self.schema_compatible: (Schema shape, Schema other) -> (:compatible | mismatch)
28
+ private def self.request_scope: (Request request) -> Integer
29
+
30
+ # Mirrors the core's `Schema`. Like `Schema::new`, `new` has no value for a
31
+ # `fanout` outside 2..MAX_FANOUT or a tree with more leaves than fit in 64
32
+ # bits: it raises RangeError (TypeError for a non-Integer).
33
+ class Schema < Data
34
+ attr_reader fanout: Integer
35
+ attr_reader depth: Integer
36
+ attr_reader partitioning: Integer
37
+ attr_reader digest: Integer
38
+ def self.new: (Integer fanout, Integer depth, Integer partitioning, Integer digest) -> Schema
39
+ | (fanout: Integer, depth: Integer, partitioning: Integer, digest: Integer) -> Schema
40
+ # Total number of leaves.
41
+ def leaves: () -> Integer
42
+ # Nodes at `level` (0..255), saturating past the leaf level.
43
+ def width: (Integer level) -> Integer
44
+ # Leaves below `node`, the core's `LeafRange` as a half-open Range; nil
45
+ # when the node is not part of the tree.
46
+ def span: (Node node) -> Range[Integer]?
47
+ # :compatible, or the first field on which `other` differs.
48
+ def compatible: (Schema other) -> (:compatible | mismatch)
49
+ end
50
+
51
+ # Mirrors the core's `Versions`: Integers in 0..2**64-1. `new` raises
52
+ # TypeError for a non-Integer and RangeError outside the range.
53
+ class Versions < Data
54
+ attr_reader local: Integer
55
+ attr_reader remote: Integer
56
+ def self.new: (Integer local, Integer remote) -> Versions
57
+ | (local: Integer, remote: Integer) -> Versions
58
+ end
59
+
60
+ # Mirrors the core's `Node`: `level` in 0..255, `index` in 0..2**64-1.
61
+ # `new` raises TypeError for a non-Integer and RangeError outside the range.
62
+ class Node < Data
63
+ ROOT: Node
64
+
65
+ attr_reader level: Integer
66
+ attr_reader index: Integer
67
+ def self.new: (Integer level, Integer index) -> Node
68
+ | (level: Integer, index: Integer) -> Node
69
+ end
70
+
71
+ # Mirrors the core's `Request`. `session` is a scoped id: the issuing
72
+ # survey's scope in the top 16 bits, its session count (from one) below.
73
+ # Like `Request::new`, `new` has no value for a session of sequence number
74
+ # zero, which no survey issues: RangeError, as for a session outside
75
+ # 0..2**64-1; TypeError for a non-Integer session or a node that is not a
76
+ # Node.
77
+ class Request < Data
78
+ attr_reader session: Integer
79
+ attr_reader node: Node
80
+ def self.new: (Integer session, Node node) -> Request
81
+ | (session: Integer, node: Node) -> Request
82
+ # The scope of the survey that issued the session, 0..65535.
83
+ def scope: () -> Integer
84
+ end
85
+
86
+ class Survey
87
+ # Scope zero.
88
+ def self.new: () -> Survey
89
+ # `scope` is an Integer in 0..65535: TypeError otherwise, RangeError
90
+ # outside the range.
91
+ def self.with_scope: (Integer scope) -> Survey
92
+ # Continues `scope` after a restart from a saved `issued` count. Restores
93
+ # only the session sequence: the survey is idle. RangeError when `issued`
94
+ # is above 2**48 - 1.
95
+ def self.resumed: (Integer scope, Integer issued) -> Survey
96
+ # The scope carried by every session, and so every Request, of this survey.
97
+ def scope: () -> Integer
98
+ # Sessions issued in this scope so far: the count to save for `resumed`.
99
+ def issued: () -> Integer
100
+ # Honoured: :identical, :diverged. Refused: begin_refusal.
101
+ def begin: (Schema local, Schema remote, Versions versions, String local_root, String remote_root) -> (:identical | :diverged | begin_refusal)
102
+ # The next node whose child digests are wanted, nil when nothing is queued.
103
+ # Never refuses.
104
+ def next_request: () -> Request?
105
+ # Honoured: :accepted. Refused: answer_refusal; :stale covers a Request
106
+ # from an earlier session or from a survey in another scope.
107
+ def answer: (Request request, Versions versions, Array[String] local, Array[String] remote) -> (:accepted | answer_refusal)
108
+ # Honoured: :requeued. Refused: requeue_refusal.
109
+ def requeue: (Request request) -> (:requeued | requeue_refusal)
110
+ # How many in-flight requests went back to the queue. Never refuses.
111
+ def requeue_all: () -> Integer
112
+ # The lowest buffered leaf range, nil when none is buffered. Never refuses.
113
+ def pop_range: () -> Range[Integer]?
114
+ # At most `limit` buffered leaf ranges, lowest first, [] when none is
115
+ # buffered. A limit above OUTPUT_CAPACITY takes them all. Never refuses.
116
+ def drain: (Integer limit) -> Array[Range[Integer]]
117
+ # Honoured: :aborted when a session was dropped, and the repeat
118
+ # :already_idle when none was open (nothing changes). Never refuses.
119
+ def abort: () -> (:aborted | :already_idle)
120
+ def phase: () -> (:idle | :surveying | :draining | :complete)
121
+ # The id of the latest session issued in this scope, open or not; nil
122
+ # while none was ever begun. After `abort` it is the aborted session; a
123
+ # resumed survey, idle until its next `begin`, answers the last session
124
+ # issued before the restart (nil when resumed from a count of zero).
125
+ def session: () -> Integer?
126
+ # The schema of the open session, nil when the survey is idle.
127
+ def schema: () -> Schema?
128
+ # The versions the open session pinned, nil when the survey is idle.
129
+ def versions: () -> Versions?
130
+ def pending: () -> Integer
131
+ def in_flight: () -> Integer
132
+ def buffered: () -> Integer
133
+
134
+ private
135
+
136
+ # The open session's schema fields (fanout, depth, partitioning, digest),
137
+ # nil when idle.
138
+ def native_schema: () -> [Integer, Integer, Integer, Integer]?
139
+ # The open session's pinned (local, remote) versions, nil when idle.
140
+ def native_versions: () -> [Integer, Integer]?
141
+ end
142
+ end
metadata ADDED
@@ -0,0 +1,64 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: merkle_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.6.3
5
+ platform: x86_64-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: Walks two digest trees of the same shape and reports the leaf ranges
14
+ that differ, in fixed memory and resumable steps. Computes no hashes and moves no
15
+ data.
16
+ email:
17
+ - oss@seuros.com
18
+ executables: []
19
+ extensions: []
20
+ extra_rdoc_files: []
21
+ files:
22
+ - CHANGELOG.md
23
+ - LICENSE.txt
24
+ - README.md
25
+ - ext/merkle_machines_native/core/CHANGELOG.md
26
+ - ext/merkle_machines_native/core/README.md
27
+ - ext/merkle_machines_native/extconf.rb
28
+ - lib/merkle_machines.rb
29
+ - lib/merkle_machines/survey.rb
30
+ - lib/merkle_machines/values.rb
31
+ - lib/merkle_machines/version.rb
32
+ - lib/merkle_machines_native/merkle_machines_native.so
33
+ - sig/merkle_machines.rbs
34
+ homepage: https://github.com/seuros/merkle_machines
35
+ licenses:
36
+ - MIT
37
+ metadata:
38
+ source_code_uri: https://github.com/seuros/merkle_machines
39
+ rubygems_mfa_required: 'true'
40
+ cargo_crate_name: merkle_machines_native
41
+ cargo_manifest_path: ext/merkle_machines_native/ffi/Cargo.toml
42
+ post_install_message:
43
+ rdoc_options: []
44
+ require_paths:
45
+ - lib
46
+ required_ruby_version: !ruby/object:Gem::Requirement
47
+ requirements:
48
+ - - ">="
49
+ - !ruby/object:Gem::Version
50
+ version: '4.0'
51
+ - - "<"
52
+ - !ruby/object:Gem::Version
53
+ version: 4.1.dev
54
+ required_rubygems_version: !ruby/object:Gem::Requirement
55
+ requirements:
56
+ - - ">="
57
+ - !ruby/object:Gem::Version
58
+ version: '0'
59
+ requirements: []
60
+ rubygems_version: 3.5.23
61
+ signing_key:
62
+ specification_version: 4
63
+ summary: Bounded digest-tree comparison for Ruby
64
+ test_files: []