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 +7 -0
- data/CHANGELOG.md +91 -0
- data/LICENSE.txt +21 -0
- data/README.md +326 -0
- data/ext/merkle_machines_native/core/CHANGELOG.md +66 -0
- data/ext/merkle_machines_native/core/README.md +114 -0
- data/ext/merkle_machines_native/extconf.rb +2 -0
- data/lib/merkle_machines/survey.rb +43 -0
- data/lib/merkle_machines/values.rb +63 -0
- data/lib/merkle_machines/version.rb +5 -0
- data/lib/merkle_machines.rb +8 -0
- data/lib/merkle_machines_native/merkle_machines_native.so +0 -0
- data/sig/merkle_machines.rbs +142 -0
- metadata +64 -0
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,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,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'
|
|
Binary file
|
|
@@ -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: []
|