journal_machines 0.7.1-x86_64-darwin

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: 2ce9d116b2b78f5e71ac0786b421d74f9600687f04895dba2c5952fa9da5b393
4
+ data.tar.gz: 9ab7ce7b3101eed2f4f6e65cf31ab56f74b9170202e8525236096ade00dc302d
5
+ SHA512:
6
+ metadata.gz: 79da0d1a737b0261db444d67b250eb50948acf27b6e33dc97fdab4a3a2360299407205a588723319c53ecc97a8fb7568e8c41abba0b92ef3391be478fea54bed
7
+ data.tar.gz: 660e2ca66ef0c7bb842bc52297f72b1cd712985ba7c210be94b9f934b477ce0ba69957479c95d48c3280e4bebf6ff1fd9eb147839d40cede0f46bd3428bcea59
data/CHANGELOG.md ADDED
@@ -0,0 +1,95 @@
1
+ # Changelog
2
+
3
+ ## [0.7.1](https://github.com/seuros/journal_machines/compare/journal_machines/v0.7.0...journal_machines/v0.7.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a handle runs no Ruby ([f87e049](https://github.com/seuros/journal_machines/commit/f87e049d521da4c49f9b160a5247c2a94307aaf5))
9
+
10
+ ## [0.7.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.6.1...journal_machines/v0.7.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * replace Segment pinned bool with a Retention enum
16
+
17
+ ### Features
18
+
19
+ * replace Segment pinned bool with a Retention enum ([98d6904](https://github.com/seuros/journal_machines/commit/98d690430cea94988b5ceb7389d7238999896dcd))
20
+
21
+ ## [0.6.1](https://github.com/seuros/journal_machines/compare/journal_machines/v0.6.0...journal_machines/v0.6.1) (2026-11-14)
22
+
23
+
24
+ ### Bug Fixes
25
+
26
+ * **deps:** require matryona-machines >= 0.4 and read the Segment replacement with optional_typed ([f318c31](https://github.com/seuros/journal_machines/commit/f318c317503a121503ce9865fd51f0289e6398c0))
27
+
28
+ ## [0.6.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.5.0...journal_machines/v0.6.0) (2026-11-14)
29
+
30
+
31
+ ### ⚠ BREAKING CHANGES
32
+
33
+ * adopt matryona 0.3: optional_positive, integer_in and boolean readers, names_only refusal table
34
+
35
+ ### Features
36
+
37
+ * adopt matryona 0.3: optional_positive, integer_in and boolean readers, names_only refusal table ([ab0f05d](https://github.com/seuros/journal_machines/commit/ab0f05dc11b473e24308f7696af71be55674ee11))
38
+
39
+ ## [0.5.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.4.0...journal_machines/v0.5.0) (2026-11-14)
40
+
41
+
42
+ ### ⚠ BREAKING CHANGES
43
+
44
+ * adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables
45
+
46
+ ### Features
47
+
48
+ * adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables ([53ef3b1](https://github.com/seuros/journal_machines/commit/53ef3b10ded3b1b994e2da14f04ecd5dcf5c7a7c))
49
+
50
+ ## [0.4.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.3.0...journal_machines/v0.4.0) (2026-11-14)
51
+
52
+
53
+ ### ⚠ BREAKING CHANGES
54
+
55
+ * validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim
56
+
57
+ ### Features
58
+
59
+ * validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim ([5b00d40](https://github.com/seuros/journal_machines/commit/5b00d406d92bdfb6f1ec331b60c61243ec013994))
60
+
61
+ ## [0.3.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.2.0...journal_machines/v0.3.0) (2026-11-13)
62
+
63
+
64
+ ### ⚠ BREAKING CHANGES
65
+
66
+ * 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. Handles of a journal no longer share raw values; release of a pin that is not held is Stale; the Ruby owner tag is gone.
67
+
68
+ ### Features
69
+
70
+ * draw segment ids, pin generations and attempts from one scoped periscope sequence; add Journal::resumed ([6a9b959](https://github.com/seuros/journal_machines/commit/6a9b9597aceffa452dee5d74903f99b184a15d2e))
71
+
72
+ ## [0.2.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.1.2...journal_machines/v0.2.0) (2026-11-13)
73
+
74
+
75
+ ### ⚠ BREAKING CHANGES
76
+
77
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires offset-machines >= 0.3. A repeated confirm with another payload is Mismatch; releasing a pin that is not held is Stale.
78
+
79
+ ### Features
80
+
81
+ * one Refusal enum with Result everywhere, provable repeats only, Duration time, Ruby Policy and _from pin calls ([f820899](https://github.com/seuros/journal_machines/commit/f8208990722b8407f206f8714c5708720f72dc74))
82
+
83
+ ## [0.1.2](https://github.com/seuros/journal_machines/compare/journal_machines/v0.1.1...journal_machines/v0.1.2) (2026-11-13)
84
+
85
+
86
+ ### Features
87
+
88
+ * add pin_checkpoint_from and checkpoint_from to the Ruby journal ([a42f1da](https://github.com/seuros/journal_machines/commit/a42f1dace271d39d47264133d63bcd3d1101e441))
89
+
90
+ ## [0.1.1](https://github.com/seuros/journal_machines/compare/journal_machines-v0.1.0...journal_machines/v0.1.1) (2026-11-12)
91
+
92
+
93
+ ### Features
94
+
95
+ * initial extraction ([1e4f7a9](https://github.com/seuros/journal_machines/commit/1e4f7a9c3344bd27293fc3f51ee66e22d266e183))
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,401 @@
1
+ # JournalMachines
2
+
3
+ > Deleting a log segment is easy. Deleting it at the right time is the job.
4
+
5
+ Segment bookkeeping for a segmented log, in Ruby. You tell the journal what your log files look like: how big the active one is, which records in the old ones are dead, who is still reading, how far recovery has got. It tells you when to roll, which segments are worth compacting, and when an old file may finally be deleted. It never touches a file itself.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ gem 'journal_machines'
11
+ ```
12
+
13
+ ```ruby
14
+ HOUR = 3600 * 1_000_000_000 # time is Integer nanoseconds
15
+ clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) }
16
+
17
+ # max_bytes, max_records, max_age, min_dead_per_mille. nil turns a threshold off.
18
+ policy = JournalMachines::Policy.new(64 * 1024 * 1024, nil, HOUR, 500)
19
+ journal = JournalMachines::Journal.new(policy, 0, clock.call) # first offset 0, opened now
20
+ checkpoint = journal.pin_checkpoint(1, 0) # recovery replays from offset 0
21
+
22
+ # Writer loop: ask before every append batch.
23
+ if journal.roll_decision(file.size, file.records, clock.call) != :keep
24
+ file.fsync_and_close
25
+ rolled = journal.roll(file.size, file.records, clock.call)
26
+ file = open_segment(rolled.opened, rolled.next_offset)
27
+ end
28
+
29
+ # Compactor loop.
30
+ journal.compaction_candidates(nil, 64).each do |segment|
31
+ replacement = journal.propose(segment.id)
32
+ bytes, live = rewrite_and_fsync(segment) # your code, your fsync
33
+ journal.confirm_rewritten(replacement, bytes, live)
34
+ end
35
+
36
+ # Reaper loop: only what the journal lets go.
37
+ journal.reclaimable(nil, 64).each do |segment|
38
+ reclaimed = journal.reclaim(segment.replacement)
39
+ delete_file(reclaimed.segment, reclaimed.revision) if reclaimed.is_a?(JournalMachines::Reclaimed)
40
+ end
41
+ ```
42
+
43
+ One journal, three loops. Offsets, sizes and times are Integers. Time is Integer nanoseconds on one monotonic clock, `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, for instants (`now`, a segment's `opened_at`) and spans (`max_age`) alike. No floats, no seconds, no `Time.now`.
44
+
45
+ ## A Message to the Resistance
46
+
47
+ So you wrote an append-only log. Appending was the easy part. Then the disk filled, and you wrote a cleaner. The cleaner copied the live records of an old segment into a new file and deleted the old one.
48
+
49
+ Then a consumer that had been paused for an hour woke up holding a byte position into the file you deleted. So you added a check: don't delete while someone is reading. Then the machine lost power between the delete and the fsync of the new file, and the new file came back zero bytes long. So you added another check: fsync first. Then recovery replayed from the last checkpoint, which pointed into a segment the cleaner had judged finished. So you added a third check, in a third place, guarded by a third boolean.
50
+
51
+ Every one of those was the same rule, discovered one outage at a time. An original may go only when its replacement is durable *and* nobody who needs it is still behind it. The rule is small. The trouble is that it lived in three places and was enforced by remembering. This gem is the one place.
52
+
53
+ ## Chapter 1: Stardate 2026.316, the AMS Rosenblum
54
+
55
+ > **AMS Rosenblum**, NCC-4228, *Rosenblum*-class archive cutter.
56
+ > Nothing leaves the hold until its copy is stowed and nobody is still reading it.
57
+
58
+ The archive cutter doesn't write the logbooks and doesn't shred them. It keeps the register of volumes: which one is open, which are closed, which have been recopied onto fresh stock, and who has one checked out. The shredder crew works from the register and from nothing else.
59
+
60
+ On a bridge somewhere, a cadet volunteers:
61
+
62
+ ```ruby
63
+ def clean(segment)
64
+ compacted = rewrite(segment)
65
+ File.delete(segment.path)
66
+ compacted
67
+ end
68
+ ```
69
+
70
+ "That," says the cutter's archivist, "deletes the only copy between two lines, while the reader on deck four is halfway through it."
71
+
72
+ ## The Flight Plan
73
+
74
+ Every segment the journal knows about is in one of these states:
75
+
76
+ ```mermaid
77
+ stateDiagram-v2
78
+ [*] --> active
79
+ active --> sealed: roll
80
+ sealed --> proposed: propose
81
+ proposed --> durable: confirm_rewritten / confirm_superseded
82
+ proposed --> sealed: abort
83
+ durable --> sealed: abort
84
+ durable --> reclaimable: last pin moves past the segment
85
+ reclaimable --> durable: a new pin lands on it
86
+ reclaimable --> sealed: reclaim, rewritten (new revision)
87
+ reclaimable --> [*]: reclaim, superseded
88
+ ```
89
+
90
+ And the afternoon the cleaner wanted segment 1 while a reader was still in it:
91
+
92
+ ```mermaid
93
+ sequenceDiagram
94
+ participant C as Compactor
95
+ participant J as Journal
96
+ participant R as Reader
97
+
98
+ R->>J: pin_reader(3)
99
+ J-->>R: Pin
100
+ C->>J: propose(1)
101
+ J-->>C: Replacement
102
+ C->>C: rewrite live records, fsync
103
+ C->>J: reclaim(replacement)
104
+ J-->>C: :not_durable
105
+ C->>J: confirm_rewritten(replacement, 30, 4)
106
+ J-->>C: :recorded
107
+ C->>J: reclaim(replacement)
108
+ J-->>C: :pinned
109
+ Note over C: keeps both files
110
+ R->>J: advance(pin, 10)
111
+ J-->>R: :moved
112
+ C->>J: reclaim(replacement)
113
+ J-->>C: Reclaimed
114
+ Note over C: deletes revision 0. The reader never noticed.
115
+ ```
116
+
117
+ ## How the Journal Works
118
+
119
+ ### Roll
120
+
121
+ ```ruby
122
+ policy = JournalMachines::Policy.new(100, 10, 50, 500)
123
+ policy.max_age # => 50
124
+ journal = JournalMachines::Journal.new(policy, 0, 1000)
125
+ journal.policy == policy # => true
126
+
127
+ journal.roll_decision(99, 9, 1049) # => :keep
128
+ journal.roll_decision(100, 9, 1000) # => #<data JournalMachines::Due reason=:size>
129
+ journal.roll_decision(1, 10, 1000) # => #<data JournalMachines::Due reason=:records>
130
+ journal.roll_decision(1, 1, 1050) # => #<data JournalMachines::Due reason=:age>
131
+ journal.roll_decision(0, 0, 9999) # => :keep, an empty segment is never due
132
+ ```
133
+
134
+ `roll_decision` answers the core's `Roll`: the symbol `:keep`, or a `Due(reason)` naming the first threshold reached. It only reads. You pass what you observed about the active segment, bytes, records and the time, and it compares them with the thresholds, in that order. Leave a threshold out and it never triggers.
135
+
136
+ `now` and `max_age` are nanoseconds, so the segment above was opened at 1000 ns and is due by age 50 ns later. Real code passes the monotonic clock reading and a `max_age` like `30 * 60 * 1_000_000_000`. `segment.opened_at` reads back the same nanoseconds.
137
+
138
+ When you have actually sealed the file, say so:
139
+
140
+ ```ruby
141
+ rolled = journal.roll(100, 9, 1000)
142
+ rolled.sealed # => 1
143
+ rolled.opened # => 2
144
+ rolled.next_offset # => 9
145
+ ```
146
+
147
+ `Policy.new(max_bytes, max_records, max_age, min_dead_per_mille)` holds the three roll thresholds and the dead-record ratio for compaction. `Journal.new(policy, base_offset, now)` opens one active segment at `base_offset`, at instant `now`. Neither has defaults: every argument is yours to choose. A threshold of `nil` never triggers. A threshold of zero, or a ratio above 1000, raises `RangeError` from `Policy.new`, so a bad policy never exists.
148
+
149
+ A roll doesn't have to be due. Sealing early is your call. Sealing an empty segment is `:empty`.
150
+
151
+ ### Compaction candidates
152
+
153
+ The journal doesn't know which records are dead. You do, so you tell it:
154
+
155
+ ```ruby
156
+ policy = JournalMachines::Policy.new(nil, nil, nil, 500) # no roll thresholds, compact at half dead
157
+ journal = JournalMachines::Journal.new(policy, 0, 0)
158
+ 3.times { journal.roll(100, 10, 0) } # segments 1, 2, 3 sealed; 4 active
159
+
160
+ journal.observe_live(1, 5) # => :recorded, half dead
161
+ journal.observe_live(2, 6) # => :recorded, not dead enough
162
+ journal.observe_live(3, 0) # => :recorded, all dead
163
+
164
+ journal.compaction_candidates(nil, 64).map(&:id) # => [1, 3]
165
+ journal.compaction_candidates(nil, 1).map(&:id) # => [1]
166
+ journal.compaction_candidates(1, 1).map(&:id) # => [3]
167
+ ```
168
+
169
+ A sealed segment is a candidate when at least `min_dead_per_mille` of its stored records are dead (500 here, so half) and it has no replacement in flight. Candidates come oldest first, at most `limit` at a time. Pass the last id you handled to get the next batch.
170
+
171
+ ### Replacement
172
+
173
+ ```ruby
174
+ replacement = journal.propose(1)
175
+ replacement.class # => JournalMachines::Replacement
176
+ journal.segment(1).state # => :proposed
177
+ journal.propose(1) # => :busy
178
+
179
+ journal.confirm_rewritten(replacement, 40, 5) # => :recorded
180
+ journal.confirm_rewritten(replacement, 40, 5) # => :already_durable, a repeat
181
+ journal.confirm_rewritten(replacement, 41, 5) # => :mismatch, that is not what was recorded
182
+ journal.confirm_superseded(replacement) # => :mismatch
183
+ journal.segment(1).state # => :reclaimable
184
+ ```
185
+
186
+ Confirming twice with the same numbers is not an error. The attempt is durable with exactly that, which is what you asked for, so the answer is `:already_durable`. Confirming it again with anything else, other bytes, another record count, or the other method, is `:mismatch`: the journal never recorded that, so it won't tell you it did. The first confirmation stands. If it was wrong, `abort` and propose again.
187
+
188
+ `propose` marks a segment as being replaced. `confirm_rewritten(replacement, bytes, live_records)` says a compacted copy of the same offsets is on disk and synced. `confirm_superseded(replacement)` says something else now covers the range, a snapshot or an archive, or nothing at all because every record was dead. The journal takes your word for it. It cannot see your disk.
189
+
190
+ The core has one call here, `confirm_durable(replacement, durable)`, where `durable` is `Rewritten { bytes, live_records }` or `Superseded`. Ruby has one method per variant, named after it and taking that variant's fields in order. Both answer `:recorded` the first time.
191
+
192
+ Changed your mind, or the rewrite failed?
193
+
194
+ ```ruby
195
+ journal.abort(replacement) # => :aborted
196
+ journal.segment(1).state # => :sealed
197
+ journal.abort(replacement) # => :stale
198
+ ```
199
+
200
+ ### Pins
201
+
202
+ A pin says "everything at or after this offset is still needed."
203
+
204
+ ```ruby
205
+ journal = JournalMachines::Journal.new(policy, 0, 0)
206
+ 2.times { journal.roll(100, 10, 0) } # segment 1 holds 0...10, segment 2 holds 10...20
207
+
208
+ reader = journal.pin_reader(3)
209
+ reader.class # => JournalMachines::Pin
210
+ journal.low_pin # => 3
211
+ journal.segment(1).retention # => :pinned
212
+
213
+ journal.advance(reader, 10) # => :moved
214
+ journal.advance(reader, 10) # => :unchanged, already there
215
+ journal.advance(reader, 4) # => :regressed
216
+ journal.segment(1).retention # => :unpinned
217
+
218
+ journal.release(reader) # => :released
219
+ journal.release(reader) # => :stale
220
+ journal.advance(reader, 11) # => :stale
221
+ ```
222
+
223
+ Release is checked against the acquisition, not the slot. Once released, a pin handle never names a pin again, even after the journal hands the same slot to someone else: `advance`, `checkpoint` and `pin_offset` answer `:stale` (or `nil`) and leave the new holder alone. A second `release` is `:stale` too, and changes nothing. The journal keeps no list of released pins, and it can't work the answer out: pins, segments and attempts are numbered from one sequence, so "one of my numbers that no pin holds" is just as true of a segment id. It only honours a repeat it can prove. A pin it never issued, from a journal of another scope or with a number it hasn't reached, is `:stale` as well.
224
+
225
+ Moving a pin to where it already sits is `:unchanged`, an answer and not a refusal. Moving it back is `:regressed`, a refusal: the journal may already have let go of what lies behind the pin, so it cannot promise it again.
226
+
227
+ A checkpoint pin also carries the generation of the consumer assignment that reported it:
228
+
229
+ ```ruby
230
+ checkpoint = journal.pin_checkpoint(3, 20) # assignment generation 3, offset 20
231
+
232
+ journal.checkpoint(checkpoint, 3, 25) # => :advanced
233
+ journal.checkpoint(checkpoint, 2, 99) # => :stale_assignment
234
+ journal.checkpoint(checkpoint, 4, 8) # => :reassigned
235
+ journal.pin_offset(checkpoint) # => 8
236
+ ```
237
+
238
+ A consumer that was fenced off can't drag retention forward with an offset it committed before it lost the partition. A newer assignment takes over at whatever offset it reports, even a lower one.
239
+
240
+ If the generation and the offset come from an offset tracker, hand over the tracker instead of two loose integers:
241
+
242
+ ```ruby
243
+ tracker = OffsetMachines::Tracker.new # gem 'offset_machines'
244
+ journal.pin_checkpoint_from(tracker) # => :unassigned, nothing pinned
245
+
246
+ tracker.assign(3, 20)
247
+ checkpoint = journal.pin_checkpoint_from(tracker)
248
+ journal.pin_offset(checkpoint) # => 20
249
+
250
+ tracker.ack(3, 20) # acknowledged, not committed
251
+ journal.checkpoint_from(checkpoint, tracker) # => :unchanged
252
+ tracker.mark_committed(3, 21)
253
+ journal.checkpoint_from(checkpoint, tracker) # => :advanced, now at 21
254
+
255
+ zombie = OffsetMachines::Tracker.new
256
+ zombie.assign(2, 99)
257
+ journal.checkpoint_from(checkpoint, zombie) # => :stale_assignment
258
+ ```
259
+
260
+ `pin_checkpoint_from(tracker)` is `pin_checkpoint(tracker.generation, tracker.base)` and `checkpoint_from(pin, tracker)` is `checkpoint(pin, tracker.generation, tracker.base)`, with the same answers. Both numbers are read from the one object you pass, so they can't come from two different trackers. This gem doesn't depend on `offset_machines`: any object with public `generation` and `base` readers fits, `OffsetMachines::Tracker` being the one they were written for. The binding asks for both before calling either, so an object missing one raises `TypeError` naming it (`expected an offset tracker responding to #generation and #base, Object lacks #base`) and runs neither.
261
+
262
+ ### Reclaim
263
+
264
+ ```ruby
265
+ journal = JournalMachines::Journal.new(policy, 0, 0)
266
+ journal.roll(100, 10, 0)
267
+ reader = journal.pin_reader(3)
268
+ replacement = journal.propose(1)
269
+
270
+ journal.reclaim(replacement) # => :not_durable
271
+ journal.confirm_rewritten(replacement, 30, 4) # => :recorded
272
+ journal.reclaim(replacement) # => :pinned
273
+ journal.reclaimable(nil, 64) # => []
274
+
275
+ journal.advance(reader, 10) # => :moved
276
+ reclaimed = journal.reclaim(replacement)
277
+ reclaimed.revision # => 0, the file to delete
278
+ reclaimed.bytes # => 100
279
+ reclaimed.replaced_by # => 4, the revision now serving 0...10: the attempt number
280
+ ```
281
+
282
+ Two conditions, both required: the replacement is confirmed durable, and no pin of either kind sits below the segment's end. Miss one and you get a symbol and nothing changes. A rewritten segment keeps its id and its offsets under a new revision. A superseded one leaves the journal and `replaced_by` is `nil`.
283
+
284
+ ### Capacity
285
+
286
+ The journal tracks 64 segments and 32 pins. Past that it refuses:
287
+
288
+ ```ruby
289
+ journal = JournalMachines::Journal.new(policy, 0, 0)
290
+ journal.segment_capacity # => 64
291
+ 63.times { journal.roll(1, 1, 0) }
292
+ journal.roll(1, 1, 0) # => :segments_full
293
+
294
+ 32.times { journal.pin_reader(0) }
295
+ journal.pin_reader(0) # => :pins_full
296
+ ```
297
+
298
+ A `:segments_full` roll means your writer keeps appending to the segment it has until you reclaim something. Nothing is dropped to make room.
299
+
300
+ ### Time only moves forward
301
+
302
+ ```ruby
303
+ journal = JournalMachines::Journal.new(JournalMachines::Policy.new(nil, nil, 10, 500), 0, 100)
304
+ journal.roll_decision(1, 1, 99) # => :time_regression
305
+ journal.roll(1, 1, 99) # => :time_regression
306
+ ```
307
+
308
+ A clock reading earlier than the moment the active segment was opened is refused, not guessed at.
309
+
310
+ ### Every answer
311
+
312
+ A call that is honoured answers with a value. A call that is not honoured answers with one of the refusal symbols below, and only those, and changes nothing. A repeat of something that already holds is honoured: it gets its own answer in the Honoured column, marked *repeat*, and it changes nothing either.
313
+
314
+ | Call | Honoured | Refusals | Records the clock |
315
+ | --- | --- | --- | --- |
316
+ | `Journal.new`, `with_scope`, `resumed` | a `Journal` | none; bad input raises | yes: the first segment opens at `now` |
317
+ | `roll_decision(bytes, records, now)` | `:keep`, `Due(:size)`, `Due(:records)`, `Due(:age)` | `:time_regression`, `:overflow`, `:no_active` | no, a read: the journal keeps no watermark, and `now` is judged against the active segment's opening |
318
+ | `roll(bytes, records, now)` | `Rolled` | `:empty`, `:time_regression`, `:overflow`, `:segments_full`, `:exhausted`, `:no_active` | yes: the new active segment opens at `now` |
319
+ | `observe_live(id, live_records)` | `:recorded` | `:unknown`, `:active`, `:exceeds` | no clock |
320
+ | `pin_reader(offset)` | `Pin` | `:pins_full`, `:exhausted` | no clock |
321
+ | `pin_checkpoint(assignment, offset)`, `pin_checkpoint_from(tracker)` | `Pin` | `:unassigned`, `:pins_full`, `:exhausted` | no clock |
322
+ | `advance(pin, offset)` | `:moved`, `:unchanged` (*repeat*) | `:stale`, `:wrong_kind`, `:regressed` | no clock |
323
+ | `checkpoint(pin, assignment, offset)`, `checkpoint_from(pin, tracker)` | `:advanced`, `:reassigned`, `:unchanged` (*repeat*) | `:stale`, `:wrong_kind`, `:unassigned`, `:stale_assignment`, `:regressed` | no clock |
324
+ | `release(pin)` | `:released` | `:stale` | no clock |
325
+ | `propose(id)` | `Replacement` | `:unknown`, `:active`, `:busy`, `:exhausted` | no clock |
326
+ | `confirm_rewritten(replacement, bytes, live_records)` | `:recorded`, `:already_durable` (*repeat*) | `:stale`, `:mismatch`, `:exceeds` | no clock |
327
+ | `confirm_superseded(replacement)` | `:recorded`, `:already_durable` (*repeat*) | `:stale`, `:mismatch` | no clock |
328
+ | `reclaim(replacement)` | `Reclaimed` | `:stale`, `:not_durable`, `:pinned` | no clock |
329
+ | `abort(replacement)` | `:aborted` | `:stale` | no clock |
330
+ | `Policy.new`, `Due.new`, `Rolled.new`, `Reclaimed.new`, `Segment.new` | the value | none; a value no journal could hold or answer raises `RangeError`, a wrong type `TypeError` | no clock |
331
+
332
+ Each refusal is the snake_case of one core `Refusal` variant. There is no catch-all symbol. The only instants the journal keeps are its segments' opening times, and only the constructors and an honoured `roll` set one; no repeat takes a clock at all.
333
+
334
+ The repeats. Only one the journal can prove from its own state is honoured:
335
+
336
+ | Repeat | Meaning |
337
+ | --- | --- |
338
+ | `:unchanged` | The pin already sits at that offset (for a checkpoint: under that same assignment generation). |
339
+ | `:already_durable` | This attempt was confirmed before by the same method with the same bytes and record count. |
340
+
341
+ Each refusal means one thing wherever it shows up:
342
+
343
+ | Refusal | Meaning |
344
+ | --- | --- |
345
+ | `:no_active` | There is no active segment. Not reachable with the compiled capacity of 64. |
346
+ | `:empty` | The active segment holds no records, so there is nothing to seal. |
347
+ | `:time_regression` | `now` is earlier than the moment the active segment was opened. |
348
+ | `:overflow` | The offset range would pass `2**64 - 1`. |
349
+ | `:segments_full` | All 64 segment slots are taken. Reclaim one. |
350
+ | `:pins_full` | All 32 pin slots are held. Release one. |
351
+ | `:exhausted` | The journal ran out of numbers for segment ids, pin generations and attempts. That takes `2**48 - 1` of them, all kinds together, per scope. |
352
+ | `:unknown` | No segment has that id. |
353
+ | `:active` | That is the active segment, still being written. |
354
+ | `:busy` | The segment already has a replacement in flight. |
355
+ | `:exceeds` | More live records than the segment stores. |
356
+ | `:mismatch` | The attempt is already durable, but not with this: `confirm_superseded` after `confirm_rewritten` or the reverse, or `confirm_rewritten` with other bytes or another record count. The first confirmation stands. |
357
+ | `:stale` | The `Pin` or `Replacement` is not current: released, aborted, reclaimed, superseded by a newer attempt, or one this journal never issued (another scope, or a number it hasn't reached). Releasing a pin twice is `:stale`. |
358
+ | `:wrong_kind` | `advance` on a checkpoint pin, or `checkpoint` on a reader pin. |
359
+ | `:unassigned` | Assignment generation zero is not an assignment. |
360
+ | `:stale_assignment` | The assignment generation is older than the one the checkpoint holds. |
361
+ | `:regressed` | The offset is behind the pin. |
362
+ | `:not_durable` | The replacement hasn't been confirmed durable. |
363
+ | `:pinned` | A pin still sits below the segment's end. |
364
+
365
+ The queries `active`, `segment`, `covering`, `segments`, `compaction_candidates`, `reclaimable`, `pin_offset`, `low_pin`, `pins`, `policy`, `size`, `empty?`, `segment_capacity` and `pin_capacity` never refuse. They answer a value, `nil` or an empty array. `segments(after, limit)`, `compaction_candidates(after, limit)` and `reclaimable(after, limit)` take both arguments every time: `after` is the last segment id you were given, or `nil` to begin, and `limit` bounds the Array (the core hands out an iterator instead). `after` has to be a number this journal issued: one whose segment has since been reclaimed still works as a position, but a number it never issued (another scope, sequence zero such as a bare `0`, or one it hasn't reached) is no position here, and the scan answers `[]`. Begin with `nil`, not `0`.
366
+
367
+ ## The Rules of the Archivist
368
+
369
+ - **Everything is an Integer** in `0..2**64-1`: offsets, sizes, counts, times, ids, generations. Floats, nil, and strings raise `TypeError`. Out of range raises `RangeError`. A threshold may be `nil`, never zero. A missing argument raises `ArgumentError`: nothing has a default.
370
+ - **Time is Integer nanoseconds.** `now` (in `Journal.new`, `roll_decision` and `roll`), `max_age` and `Segment#opened_at` are nanoseconds on one monotonic clock: `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`. A Float or any other non-Integer raises `TypeError`; a negative value or one past `2**64-1` raises `RangeError`.
371
+ - **Scopes.** A `Pin`, a `Replacement` and a segment id are only meaningful to the `Journal` that issued them. They are numbered from 1, so two journals hand out the same ones, and a handle given to the wrong journal would name a live pin or attempt there. One journal never repeats itself, though: segment ids, pin generations and attempt numbers come from a single sequence (the first segment is 1, and every roll, pin and proposal takes the next number), so a generation or an attempt passed where a segment id goes names no segment. Segment ids still ascend; they aren't consecutive. Give each journal its own scope: `Journal.with_scope(policy, base_offset, now, scope)`, any Integer in `0..65_535` (a non-Integer raises `TypeError`, anything outside the range raises `RangeError`). `Journal.new(policy, base_offset, now)` is scope zero. The scope rides in the top 16 bits of every segment id, pin generation and attempt number (and so of a rewritten segment's `revision`); `journal.scope`, `pin.scope` and `replacement.scope` read it back. A journal that never issued it, of another scope or not that far along, answers `:stale` to a pin or replacement (`nil` from `pin_offset`) and `:unknown` to a segment id (`nil` from `segment`, `[]` from the scans), and changes nothing. The journal can't pick a scope for you, and two journals left in the same scope still mix up each other's handles. `Pin` and `Replacement` objects can't be built by hand. They are values: two handles to the same pin acquisition or replacement attempt are `==` and `eql?` and hash alike, so the `replacement` of two reads of one proposed segment compares equal, and so do the two `Segment`s.
372
+ - **Values are valid or do not exist.** `Policy`, `Due`, `Rolled`, `Reclaimed` and `Segment` check themselves through the core when they are built, by hand or by the journal: `Due.new(:nope)`, `Rolled.new(2, 2, 10)`, `Reclaimed.new(1, 0, 9, 1)` or a `Segment` that is `:active` with records all raise `RangeError`; a String for a Symbol, `true` for `retention`, or an Integer for a `Replacement` raises `TypeError`. What the journal answers always passes, so `==` against a value you built means what it says. The values, and the `Pin` and `Replacement` handles, are final: subclassing one raises `TypeError` and `allocate` is gone. That stops accidents, not reflection (a named subclass still leaves its constant behind; `Marshal.load` and a hand-bound `Data#initialize` skip the check), so the extension is the authority: the `Policy` a journal opens with must be exactly a `Policy` (`TypeError` otherwise, a subclass included), and its fields are read natively and checked again by the core (`RangeError`).
373
+ - **The journal never loses work.** Every argument is converted before the journal is asked, and the value classes are resolved once, when the extension loads. So are the classes of `Journal`, `Pin` and `Replacement`: a handle is built with no Ruby code run, an instance of the class the gem defined even if the constant is later redefined, and a redefined `Object.const_get` is never consulted. Building an answer runs Ruby code (`new`, which a reopened class can redefine), so `roll` and `reclaim` decide on a copy, build the `Rolled` or `Reclaimed`, and keep the copy only if the journal is still unfrozen and unchanged: a `new` that raises applies nothing, one that freezes the journal raises `FrozenError`, one that calls back in and changes it raises `RuntimeError`, and the outer call is not applied.
374
+ - **The binding never loses work.** Everything that can raise (a bad argument, a frozen journal, a tracker whose readers raise) happens before the journal is asked; after it has changed, the binding only builds values from its answer. The scans read their segments into a buffer before building a single Ruby value.
375
+ - **Refusals don't raise.** `:segments_full`, `:pinned`, `:not_durable`, `:stale` and the rest are answers. A refused call changes nothing. Only malformed input raises.
376
+ - **Restarts.** A journal built again with `new` or `with_scope` numbers from 1 again, so a pin or replacement that outlived the restart could name a new entry. Either resume the numbering, `Journal.resumed(policy, base_offset, now, scope, issued)` with the `journal.issued` you saved from the journal before it, or give each incarnation its own scope. `resumed` restores the numbering and nothing else: segments and pins are yours to replay, and the one active segment takes the next number. It raises `RangeError` for an `issued` outside `0..2**48-2`. Save `issued` before you hand a number out: resuming from too low a count reissues.
377
+ - **Repeats aren't refusals, when they can be proved.** `:unchanged` and `:already_durable` mean the journal can see that exactly what you asked for was already done. Treat them as success. They change nothing. A repeat it can't prove is refused: a second `release`, `reclaim` or `abort` is `:stale` (it keeps neither the pins it released nor how an attempt ended), a second confirmation with different contents is `:mismatch`.
378
+ - **No pins means no objection.** The journal protects what is pinned. If nobody pinned a checkpoint, nothing stops a durable replacement from being reclaimed.
379
+ - **Frozen means frozen.** `freeze` the journal and every mutating call raises `FrozenError`.
380
+
381
+ ## What You Think You're Doing vs Reality
382
+
383
+ ### You Think: "The compacted file is written, so the old one can go."
384
+ ### Reality: Written is not durable, and durable is not unread.
385
+
386
+ A file you wrote and didn't sync is a promise from the page cache. A file you synced can still be the wrong one to keep alone, if a reader holds a position in the original or recovery intends to replay through it. `reclaim` won't say yes until you've confirmed the first and every pin has cleared the second.
387
+
388
+ ### You Think: "The consumer acknowledged it, so the checkpoint can move."
389
+ ### Reality: Acknowledged is not committed.
390
+
391
+ Move the checkpoint pin to the offset your commit actually persisted, not to the one a worker says it finished. `pin_checkpoint_from` and `checkpoint_from` pair with `offset_machines` for exactly this: they pin at the tracker's confirmed base, never at what was merely acknowledged.
392
+
393
+ ## What's Yours
394
+
395
+ Everything that touches a disk. You write the records, seal the files, rewrite the compacted copies, fsync, and delete. The journal keeps metadata in your process and loses it when the process dies. After a restart, rebuild a journal from what's on disk and from your own durable manifest (see Restarts above for its numbering), then re-pin readers and checkpoints before letting the reaper run. A half-finished replacement found on disk after a crash is yours to finish or discard. This is not a log writer, not a byte compactor and not a Raft log. It's an initial release and the API will move.
396
+
397
+ ## License
398
+
399
+ MIT License. See [LICENSE.txt](LICENSE.txt) for details.
400
+
401
+ **Remember: anyone can delete a file. The question is whether someone was still reading it.**
@@ -0,0 +1,77 @@
1
+ # Changelog
2
+
3
+ ## [0.8.1](https://github.com/seuros/journal_machines/compare/journal-machines-v0.8.0...journal-machines-v0.8.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a handle runs no Ruby ([f87e049](https://github.com/seuros/journal_machines/commit/f87e049d521da4c49f9b160a5247c2a94307aaf5))
9
+
10
+ ## [0.8.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.7.0...journal-machines-v0.8.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * replace Segment pinned bool with a Retention enum
16
+
17
+ ### Features
18
+
19
+ * replace Segment pinned bool with a Retention enum ([98d6904](https://github.com/seuros/journal_machines/commit/98d690430cea94988b5ceb7389d7238999896dcd))
20
+
21
+ ## [0.7.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.6.0...journal-machines-v0.7.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables
27
+
28
+ ### Features
29
+
30
+ * adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables ([53ef3b1](https://github.com/seuros/journal_machines/commit/53ef3b10ded3b1b994e2da14f04ecd5dcf5c7a7c))
31
+
32
+ ## [0.6.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.5.0...journal-machines-v0.6.0) (2026-11-14)
33
+
34
+
35
+ ### ⚠ BREAKING CHANGES
36
+
37
+ * validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim
38
+
39
+ ### Features
40
+
41
+ * validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim ([5b00d40](https://github.com/seuros/journal_machines/commit/5b00d406d92bdfb6f1ec331b60c61243ec013994))
42
+
43
+ ## [0.5.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.4.0...journal-machines-v0.5.0) (2026-11-13)
44
+
45
+
46
+ ### ⚠ BREAKING CHANGES
47
+
48
+ * 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. Handles of a journal no longer share raw values; release of a pin that is not held is Stale; the Ruby owner tag is gone.
49
+
50
+ ### Features
51
+
52
+ * draw segment ids, pin generations and attempts from one scoped periscope sequence; add Journal::resumed ([6a9b959](https://github.com/seuros/journal_machines/commit/6a9b9597aceffa452dee5d74903f99b184a15d2e))
53
+
54
+ ## [0.4.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.3.0...journal-machines-v0.4.0) (2026-11-13)
55
+
56
+
57
+ ### ⚠ BREAKING CHANGES
58
+
59
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires offset-machines >= 0.3. A repeated confirm with another payload is Mismatch; releasing a pin that is not held is Stale.
60
+
61
+ ### Features
62
+
63
+ * one Refusal enum with Result everywhere, provable repeats only, Duration time, Ruby Policy and _from pin calls ([f820899](https://github.com/seuros/journal_machines/commit/f8208990722b8407f206f8714c5708720f72dc74))
64
+
65
+ ## [0.3.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.2.0...journal-machines-v0.3.0) (2026-11-13)
66
+
67
+
68
+ ### Features
69
+
70
+ * add pin_checkpoint_from and checkpoint_from to the Ruby journal ([a42f1da](https://github.com/seuros/journal_machines/commit/a42f1dace271d39d47264133d63bcd3d1101e441))
71
+
72
+ ## [0.2.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.1.0...journal-machines-v0.2.0) (2026-11-12)
73
+
74
+
75
+ ### Features
76
+
77
+ * initial extraction ([1e4f7a9](https://github.com/seuros/journal_machines/commit/1e4f7a9c3344bd27293fc3f51ee66e22d266e183))
@@ -0,0 +1,261 @@
1
+ # journal-machines
2
+
3
+ > **AMS Rosenblum**, NCC-4228, *Rosenblum*-class archive cutter.
4
+
5
+ Engine-room flight manual: know which log segments exist, and which may go.
6
+
7
+ Pre-1.0. Allocation-free `no_std` segment metadata policy for a
8
+ segmented log: when the active segment should roll, which sealed segments are
9
+ worth compacting, and when an original may be deleted.
10
+
11
+ This is not a log writer, a byte compactor or a Raft log. The journal never
12
+ touches a file. The caller writes, seals, compacts, fsyncs and deletes; the
13
+ journal holds the bookkeeping and refuses the unsafe order. `Journal<SEGMENTS,
14
+ PINS>` has compile-time capacities and refuses rather than grows.
15
+
16
+ Every call that can refuse returns `Result<T, Refusal>`. `T` says only what
17
+ was honoured; `Refusal` is the one enum for "this call was not honoured", and
18
+ a refused call leaves the journal exactly as it was. An idempotent repeat is
19
+ honoured, not refused: when what the caller asked for already holds, the call
20
+ answers `Ok` with a variant that says so, and still changes nothing. Only a
21
+ repeat the journal can prove is honoured: it must see, in its own state, that
22
+ the same call with the same arguments was already applied.
23
+ No public enum is `#[non_exhaustive]`: a new variant is a breaking change every
24
+ caller matches on.
25
+
26
+ Time is `core::time::Duration` on a monotonic clock whose epoch the caller
27
+ picks: `now`, a segment's `opened_at` and the policy's `max_age`. Offsets,
28
+ record and byte counts, ids, revisions and generations are `u64`.
29
+
30
+ - `Rolled::new(sealed, opened, next_offset)`, `Reclaimed::new(segment,
31
+ revision, bytes, replaced_by)` and `Segment::new(id, revision, base_offset,
32
+ records, stored_records, live_records, bytes, opened_at, state,
33
+ retention, replacement)` answer `Some` only for a value some journal could have
34
+ answered (issued ids of one scope, revisions and attempts drawn after their
35
+ segment, a segment whose counts, state, pin and replacement agree, storing its
36
+ whole range at revision 0). Their
37
+ fields are private: read them through the accessor of the same name, so no
38
+ value skips the check.
39
+ - `SegmentId`, `Pin` and `Replacement` are values: two handles to the same
40
+ identity are equal and hash alike. They have no order: an id carries its
41
+ journal's scope, so ids of two journals compare by nothing meaningful.
42
+ - `Segment::retention` is `Retention::Pinned` while a pin sits below the
43
+ segment's end, otherwise `Retention::Unpinned` (always, while active).
44
+ - `Policy::new(max_bytes, max_records, max_age, min_dead_per_mille)` takes
45
+ `Option<NonZeroU64>` sizes and an `Option<Duration>` age; `None` disables a
46
+ threshold. It answers `None` for a per-mille above 1000 or a zero age.
47
+ - `Journal::new(policy, base_offset, now)` opens the first segment at `now`,
48
+ in scope zero. `Journal::with_scope(policy, base_offset, now, scope)` does
49
+ the same under `scope`; `scope()` reads it back. See Scopes below.
50
+ - `Journal::resumed(policy, base_offset, now, scope, issued) -> Option<Journal>`
51
+ does the same after a restart, continuing the identity sequence after the
52
+ `issued()` count saved from the journal before it. See Restarts below.
53
+ - `roll_decision(bytes, records, now) -> Result<Roll, Refusal>` reads the
54
+ caller's observation of the active segment and answers `Keep` or
55
+ `Due(Size | Records | Age)` against the `Policy`. An empty segment is never
56
+ due. Refuses `NoActive`, `TimeRegression`, `Overflow`.
57
+ - `roll(bytes, records, now) -> Result<Rolled, Refusal>` records that the
58
+ caller sealed the active segment and opened the next. Refuses `NoActive`,
59
+ `Empty`, `TimeRegression`, `Overflow`, `SegmentsFull`, `Exhausted`.
60
+ - `observe_live(id, live) -> Result<(), Refusal>` records how many stored
61
+ records are still live. Refuses `Unknown`, `Active`, `Exceeds`.
62
+ `compaction_candidates(after)` iterates sealed segments whose dead share
63
+ meets `min_dead_per_mille`, oldest first; resume by passing the last id.
64
+ - `pin_reader(offset)` and `pin_checkpoint(assignment, offset)`
65
+ `-> Result<Pin, Refusal>` retain every offset at or after the pin. Refuse
66
+ `PinsFull`, `Exhausted`, and for a checkpoint `Unassigned`.
67
+ - `advance(pin, offset) -> Result<Advanced, Refusal>` moves a reader pin
68
+ forward and answers `Moved`, or `Unchanged` when the pin already sits
69
+ there. Refuses `Stale`, `WrongKind`, `Regressed`.
70
+ - `checkpoint(pin, assignment, offset) -> Result<Checkpointed, Refusal>`
71
+ answers `Advanced`, `Reassigned` when a newer assignment generation takes
72
+ over, or `Unchanged` when the same generation reports the offset the pin
73
+ already sits at. Refuses `Stale`, `WrongKind`, `Unassigned`,
74
+ `StaleAssignment`, `Regressed`: an older assignment cannot move the pin.
75
+ - `release(pin) -> Result<(), Refusal>` is checked against the acquisition
76
+ generation. Refuses `Stale` for a pin that is not held: released already,
77
+ or never issued here. Whoever holds the slot now keeps it.
78
+ - `propose(id) -> Result<Replacement, Refusal>` opens a replacement attempt.
79
+ Refuses `Unknown`, `Active`, `Busy`, `Exhausted`.
80
+ - `confirm_durable(handle, Rewritten { .. } | Superseded)`
81
+ `-> Result<Confirmed, Refusal>` records the caller's word that the
82
+ replacement is durable and answers `Recorded`, or `AlreadyDurable` when the
83
+ attempt was confirmed before with that same `Durable`. Refuses `Stale`,
84
+ `Exceeds`, and `Mismatch` when the attempt is already durable with a
85
+ different `Durable` (the other variant, or other `bytes` or `live_records`):
86
+ the first confirmation stands.
87
+ - `abort(handle) -> Result<(), Refusal>` gives up and keeps the original.
88
+ Refuses `Stale`.
89
+ - `reclaim(handle) -> Result<Reclaimed, Refusal>` succeeds only when the
90
+ replacement is durable **and** no pin of either kind sits below the
91
+ segment's end. Refuses `Stale`, `NotDurable`, `Pinned { offset }`. A
92
+ rewritten segment keeps its slot under a new revision; a superseded one
93
+ leaves the journal.
94
+
95
+ ## Contract
96
+
97
+ ### Scopes
98
+
99
+ Segment ids, `Pin` and `Replacement` handles are only meaningful to the
100
+ journal that issued them. Each is built on an integer (a segment id; a slot
101
+ and a pin generation; a segment id and an attempt number) drawn from one
102
+ sequence the journal counts from one, so two journals issue the same ones,
103
+ and a handle given to the wrong journal names a live pin or attempt there. Give each journal its own scope with
104
+ `Journal::with_scope`: the scope rides in the top 16 bits of every segment
105
+ id, pin generation and attempt number, in the
106
+ [`periscope-machines`](https://crates.io/crates/periscope-machines) layout,
107
+ and `SegmentId::scope()`, `Pin::scope()` and `Replacement::scope()` read it.
108
+ `Journal::new` is scope zero and issues the plain numbers 1, 2, 3.
109
+
110
+ One sequence serves all three kinds: the active segment takes 1, and every
111
+ roll, pin and proposal takes the next number. No two handles of a journal
112
+ share a raw value, so a pin generation or an attempt (which is also a
113
+ rewritten segment's `revision`) passed to `SegmentId::from_raw` names no
114
+ segment. Segment ids still ascend in offset order; they are not consecutive.
115
+
116
+ An identity this journal never issued, of another scope or beyond what it
117
+ has issued, names nothing here, and is refused before anything is looked up,
118
+ with nothing changed: a pin or a replacement is
119
+ `Stale` (`None` from `pin_offset`), a segment id is `Unknown` (`None` from
120
+ `segment`, an empty iterator as a resume position). A `Replacement` is
121
+ refused if either its attempt or its segment was never issued here. The
122
+ journal reads no clock and no random source, so it cannot pick a scope; two
123
+ journals left in the same scope still alias. A scope holds 2^48 - 1
124
+ identities, all kinds together. A rewritten segment's `revision` is the
125
+ attempt that rewrote it, so it carries the scope too.
126
+
127
+ ### Restarts
128
+
129
+ A journal started again with `new` or `with_scope` counts from one again, so
130
+ a handle that outlived the restart could name a new entry. Either resume the
131
+ sequence, `Journal::resumed(policy, base_offset, now, scope, issued)` with
132
+ the `issued()` saved from the journal before it, or give each incarnation a
133
+ scope of its own. `resumed` restores the sequence and nothing else: segments
134
+ and pins are replayed by the caller, and the one active segment takes the
135
+ next number. It is `None` when `issued` is more than a scope holds or leaves
136
+ no identity for the active segment. Resuming from a count lower than what was
137
+ really issued reissues: save `issued()` before handing an identity out.
138
+
139
+ ### Repeats
140
+
141
+ `Advanced::Unchanged`, `Checkpointed::Unchanged` and
142
+ `Confirmed::AlreadyDurable` are answered from a live pin or a live attempt,
143
+ which only a handle this journal issued reaches. No repeat is honoured on a
144
+ handle that is no longer live. A second `release` is `Stale`: pin
145
+ generations share the sequence with segment ids and attempts, so "issued
146
+ here and held in no slot" is as true of a segment id as of a released pin,
147
+ and the journal keeps no record of which numbers were pins. A second
148
+ `reclaim` or `abort` is `Stale` too: an attempt that is no longer current was
149
+ aborted, reclaimed as a rewrite or reclaimed as superseded, and the journal
150
+ does not keep which.
151
+
152
+ `Stale` always means a handle that is not current, pin or replacement, or one
153
+ this journal never issued.
154
+ `Mismatch` always means a repeat that carries something other than what was
155
+ recorded.
156
+ `Regressed` stays a refusal: a pin asked to move back is asking for retention
157
+ the journal can no longer promise.
158
+ `Exhausted` always means the journal's identity sequence is spent: 2^48 - 1
159
+ segment ids, pin generations and attempts together per scope. `Overflow` is
160
+ only the offset range.
161
+ `active`, `segment`, `covering`, the iterators, `pin_offset`, `low_pin` and
162
+ `pins` read only and never refuse.
163
+
164
+ ### Resume positions
165
+
166
+ `segments`, `compaction_candidates` and `reclaimable` take `after:
167
+ Option<SegmentId>`, a position rather than a handle: nothing is looked up by
168
+ it, and the segment it named may have left the journal since. It must still
169
+ be a number this journal issued (`Issuer::owns`): one of another scope, a
170
+ zero sequence or one not reached is no position, and the iterator is empty.
171
+ That is the same line every other call draws for identities, and it keeps a
172
+ bare `0` (a common stand-in for "from the start") from silently meaning
173
+ "everything". `None` is the one way to begin. Any issued number works, a pin
174
+ generation or an attempt included, because one sequence orders them all.
175
+
176
+ ### Which answers record the clock
177
+
178
+ The journal keeps no watermark. The only instants it holds are its segments'
179
+ opening times, and a regression is judged against the active segment's.
180
+ `new`, `with_scope`, `resumed` and an honoured `roll` record `now` as the
181
+ opening of the new active segment: their answer depends on the instant.
182
+ `roll_decision` reads only and records nothing; its answer is about the
183
+ instant supplied. No other call takes a clock, and no honoured repeat
184
+ (`Unchanged`, `AlreadyDurable`) records anything.
185
+
186
+ ### Unreachable arms
187
+
188
+ There are none, and no slot is indexed by a number that could be out of
189
+ range. A lookup by segment id or pin hands back the slot itself, so nothing
190
+ is looked up twice; `roll` takes the active slot and the one after it as one
191
+ pair, whose absence is `SegmentsFull`; a superseded segment leaves by a walk
192
+ over the tracked slots; and the issuer's `Exhausted` is the journal's own
193
+ `Exhausted` (`From<periscope_machines::Refusal>`).
194
+
195
+ Checkpoint pins compose with `offset-machines`: `pin_checkpoint_from(&tracker)`
196
+ and `checkpoint_from(pin, &tracker)` pin at the tracker's confirmed-committed
197
+ base under its assignment generation, never at merely acknowledged offsets. An
198
+ unassigned tracker is refused as `Unassigned`, an older assignment as
199
+ `StaleAssignment`; a tracker whose base has not moved is `Unchanged`. The Ruby gem offers the same two calls over any object
200
+ with `generation` and `base` readers, such as `OffsetMachines::Tracker`.
201
+
202
+ Durability is the caller's claim; the journal cannot check it. Filesystem
203
+ operations, crash recovery and rebuilding this metadata after a restart stay
204
+ outside. Persist what you need and replay it into a resumed journal.
205
+
206
+ ```rust
207
+ use core::{num::NonZeroU64, time::Duration};
208
+ use journal_machines::{
209
+ Advanced, Checkpointed, Confirmed, Durable, Journal, Policy, Refusal, Roll, RollReason,
210
+ };
211
+ # fn main() -> Result<(), Box<dyn core::error::Error>> {
212
+
213
+ let hour = Duration::from_secs(3600);
214
+ let policy = Policy::new(NonZeroU64::new(1024), None, Some(hour), 500).ok_or("policy")?;
215
+ let mut journal = Journal::<8, 4>::new(policy, 0, Duration::ZERO);
216
+ let now = Duration::from_secs(5);
217
+ assert_eq!(journal.roll_decision(2048, 10, now), Ok(Roll::Due(RollReason::Size)));
218
+ assert_eq!(journal.roll_decision(1, 1, hour), Ok(Roll::Due(RollReason::Age)));
219
+ let rolled = journal.roll(2048, 10, now)?;
220
+
221
+ let checkpoint = journal.pin_checkpoint(1, 0)?;
222
+ let reader = journal.pin_reader(0)?;
223
+ assert_eq!(journal.observe_live(rolled.sealed(), 2), Ok(()));
224
+ assert_eq!(journal.compaction_candidates(None).next().map(|s| s.id()), Some(rolled.sealed()));
225
+
226
+ let replacement = journal.propose(rolled.sealed())?;
227
+ assert_eq!(journal.reclaim(replacement), Err(Refusal::NotDurable));
228
+ let rewritten = Durable::Rewritten { bytes: 400, live_records: 2 };
229
+ assert_eq!(journal.confirm_durable(replacement, rewritten), Ok(Confirmed::Recorded));
230
+ assert_eq!(journal.confirm_durable(replacement, rewritten), Ok(Confirmed::AlreadyDurable));
231
+ assert_eq!(journal.confirm_durable(replacement, Durable::Superseded), Err(Refusal::Mismatch));
232
+ assert_eq!(journal.reclaim(replacement), Err(Refusal::Pinned { offset: 0 }));
233
+
234
+ assert_eq!(journal.advance(reader, 10), Ok(Advanced::Moved));
235
+ assert_eq!(journal.advance(reader, 10), Ok(Advanced::Unchanged));
236
+ assert_eq!(journal.release(reader), Ok(()));
237
+ assert_eq!(journal.release(reader), Err(Refusal::Stale));
238
+ assert_eq!(journal.advance(reader, 11), Err(Refusal::Stale));
239
+
240
+ // One sequence for every kind: no two handles share a raw value.
241
+ assert_eq!((rolled.sealed().raw(), rolled.opened().raw()), (1, 2));
242
+ assert_eq!((checkpoint.generation(), reader.generation()), (3, 4));
243
+ assert_eq!((replacement.attempt(), journal.issued()), (5, 5));
244
+
245
+ // A journal of another scope issues the same sequence numbers under its own
246
+ // scope, and neither takes the other's handles.
247
+ let mut other = Journal::<8, 4>::with_scope(policy, 0, Duration::ZERO, 7);
248
+ let theirs = other.pin_checkpoint(1, 0)?;
249
+ assert_eq!((checkpoint.scope(), theirs.scope()), (0, 7));
250
+ assert_eq!(journal.release(theirs), Err(Refusal::Stale));
251
+ assert_eq!(other.checkpoint(checkpoint, 1, 10), Err(Refusal::Stale));
252
+ assert_eq!(journal.checkpoint(checkpoint, 1, 10), Ok(Checkpointed::Advanced));
253
+ assert_eq!(journal.checkpoint(checkpoint, 1, 10), Ok(Checkpointed::Unchanged));
254
+ assert_eq!(journal.reclaim(replacement)?.bytes(), 2048);
255
+
256
+ // After a restart, continue the sequence from the saved count.
257
+ let resumed = Journal::<8, 4>::resumed(policy, 20, now, 0, journal.issued()).ok_or("resume")?;
258
+ assert_eq!(resumed.active().map(|segment| segment.id().raw()), Some(6));
259
+ # Ok(())
260
+ # }
261
+ ```
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+ module JournalMachines
3
+ VERSION = '0.7.1'
4
+ end
@@ -0,0 +1,138 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'journal_machines/version'
4
+
5
+ module JournalMachines
6
+ # Roll thresholds and the dead-record ratio that makes a segment worth
7
+ # compacting. A nil threshold never triggers; `max_age` is a span in Integer
8
+ # nanoseconds. Like the core's `Policy::new`, an invalid policy cannot be
9
+ # built: a zero threshold or a ratio above 1000 raises RangeError.
10
+ Policy = Data.define(:max_bytes, :max_records, :max_age, :min_dead_per_mille) do
11
+ def initialize(max_bytes:, max_records:, max_age:, min_dead_per_mille:)
12
+ Journal.__send__(:__check_policy, max_bytes, max_records, max_age, min_dead_per_mille)
13
+ super
14
+ end
15
+ end
16
+ # Immutable point-in-time view of one segment's metadata. `opened_at` is
17
+ # Integer nanoseconds on the monotonic clock the journal was given. Like the
18
+ # core's `Segment::checked`, it holds only what some journal could answer:
19
+ # anything else raises RangeError (TypeError for a wrong type: Integers,
20
+ # a state Symbol, a retention Symbol (:pinned or :unpinned), a Replacement
21
+ # or nil).
22
+ Segment = Data.define(
23
+ :id, :revision, :base_offset, :records, :stored_records, :live_records,
24
+ :bytes, :opened_at, :state, :retention, :replacement
25
+ ) do
26
+ def initialize(id:, revision:, base_offset:, records:, stored_records:, live_records:, bytes:, opened_at:,
27
+ state:, retention:, replacement:)
28
+ Journal.__send__(:__check_segment, [id, revision, base_offset, records],
29
+ [stored_records, live_records, bytes, opened_at], state, retention, replacement)
30
+ super
31
+ end
32
+
33
+ def end_offset = base_offset + records
34
+ end
35
+ # Journal#roll_decision when a threshold was reached: the core's
36
+ # `Roll::Due(reason)`. `reason` is :size, :records or :age, checked in that
37
+ # order. The other answer, `Roll::Keep`, is the symbol :keep. Any other
38
+ # Symbol raises RangeError, a non-Symbol TypeError.
39
+ Due = Data.define(:reason) do
40
+ def initialize(reason:)
41
+ Journal.__send__(:__check_due, reason)
42
+ super
43
+ end
44
+ end
45
+ # A recorded roll: the sealed segment, the new active one and its first
46
+ # offset. Like the core's `Rolled::new`: two issued ids of one scope, the
47
+ # opened one drawn after the sealed one, and a positive next offset, or
48
+ # RangeError (TypeError for a non-Integer).
49
+ Rolled = Data.define(:sealed, :opened, :next_offset) do
50
+ def initialize(sealed:, opened:, next_offset:)
51
+ Journal.__send__(:__check_rolled, sealed, opened, next_offset)
52
+ super
53
+ end
54
+ end
55
+ # Permission to delete one original segment file. Like the core's
56
+ # `Reclaimed::new`: an issued segment id, a revision of 0 or an attempt drawn
57
+ # after it, and a replaced_by (nil or Integer) later still, or RangeError
58
+ # (TypeError for a non-Integer).
59
+ Reclaimed = Data.define(:segment, :revision, :bytes, :replaced_by) do
60
+ def initialize(segment:, revision:, bytes:, replaced_by:)
61
+ Journal.__send__(:__check_reclaimed, segment, revision, bytes, replaced_by)
62
+ super
63
+ end
64
+ end
65
+
66
+ end
67
+
68
+ # Native is required: no algorithm fallback. It resolves the Data values above
69
+ # once, so they must exist first.
70
+ require 'journal_machines_native/journal_machines_native'
71
+
72
+ module JournalMachines
73
+ # Pin and Replacement handles are values: two handles naming the same pin
74
+ # acquisition or replacement attempt are == and eql?, and hash alike. Only
75
+ # the journal builds them, and they are final like the values below.
76
+
77
+ # The values are final. `initialize` is where each validates, and a subclass
78
+ # could override it, or `allocate` build an instance that never ran it:
79
+ # subclassing raises TypeError and `allocate` is gone. That stops accidents,
80
+ # not reflection (Ruby binds a named subclass's constant before `inherited`
81
+ # raises; `Marshal.load` and a hand-bound `Data#initialize` skip the check),
82
+ # so the extension is the authority: the one value it reads back, a Policy,
83
+ # must be exactly a Policy and is checked again by the core.
84
+ [Policy, Segment, Due, Rolled, Reclaimed, Pin, Replacement].each do |value|
85
+ value.singleton_class.undef_method(:allocate)
86
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
87
+ end
88
+
89
+ class Journal
90
+ private_class_method :__open, :__check_policy, :__check_due, :__check_rolled, :__check_reclaimed,
91
+ :__check_segment
92
+
93
+ # One active segment at `base_offset`, opened at `now`: Integer nanoseconds
94
+ # of a monotonic clock (Process.clock_gettime(Process::CLOCK_MONOTONIC,
95
+ # :nanosecond)). Every later `now` passed to #roll_decision and #roll is
96
+ # read on the same clock. The journal is in scope zero.
97
+ def self.new(policy, base_offset, now) = with_scope(policy, base_offset, now, 0)
98
+
99
+ # As Journal.new, with every segment id, pin generation and attempt number
100
+ # the journal issues carrying `scope`: an Integer in 0..65_535. A journal
101
+ # of another scope answers :stale to its pins and replacements and
102
+ # :unknown to its segment ids. Give each journal its own scope.
103
+ def self.with_scope(policy, base_offset, now, scope) = resumed(policy, base_offset, now, scope, 0)
104
+
105
+ # As Journal.with_scope after a restart: the journal continues the one
106
+ # sequence its ids, generations and attempts are drawn from after
107
+ # `issued`, the #issued saved from the journal before it, so nothing that
108
+ # journal handed out is issued again. Segments and pins are not restored.
109
+ # RangeError when `issued` leaves no number for the active segment.
110
+ # `policy` must be exactly a Policy (TypeError otherwise); the extension
111
+ # reads its fields and checks them again.
112
+ def self.resumed(policy, base_offset, now, scope, issued) = __open(base_offset, now, [scope, issued], policy)
113
+
114
+ def policy = Policy.new(*__policy)
115
+
116
+ def segment_capacity = SEGMENT_CAPACITY
117
+
118
+ def pin_capacity = PIN_CAPACITY
119
+
120
+ # The binding builds every answer (Segment, Rolled, Reclaimed, Due) after
121
+ # the core call, from what the core returned; #roll and #reclaim decide on
122
+ # a copy and keep it only once the answer is built and the journal is
123
+ # still unfrozen and unchanged (FrozenError, RuntimeError otherwise, with
124
+ # nothing applied). #segments,
125
+ # #compaction_candidates and #reclaimable answer at most `limit` segments
126
+ # after segment id `after` (nil to begin), in ascending id order; resume by
127
+ # passing the last id answered. An `after` this journal never issued
128
+ # (another scope, sequence zero, not reached) is no position: [].
129
+
130
+ # Pin a checkpoint at a tracker's confirmed-committed base, under its
131
+ # assignment generation, and move a checkpoint pin to one
132
+ # (#checkpoint_from(pin, tracker)): both are native. The tracker is a
133
+ # sibling gem's value, read by its public `generation` and `base` readers,
134
+ # each asked for before either runs; TypeError naming the reader it lacks.
135
+
136
+ private :__policy
137
+ end
138
+ end
@@ -0,0 +1,209 @@
1
+ module JournalMachines
2
+ VERSION: String
3
+ SEGMENT_CAPACITY: Integer
4
+ PIN_CAPACITY: Integer
5
+ type roll_reason = :size | :records | :age
6
+ type segment_state = :active | :sealed | :proposed | :durable | :reclaimable
7
+ type retention = :unpinned | :pinned
8
+ # Integer nanoseconds on one monotonic clock, for instants and spans alike:
9
+ # Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond). A non-Integer
10
+ # raises TypeError; a value outside 0..2**64-1 raises RangeError.
11
+ type nanoseconds = Integer
12
+ # Every symbol that means "this call was not honoured and changed nothing".
13
+ # One per core `Refusal` variant, no catch-all. Each method below lists
14
+ # exactly the ones it can answer.
15
+ type refusal = :no_active | :empty | :time_regression | :overflow | :segments_full | :pins_full | :exhausted
16
+ | :unknown | :active | :busy | :exceeds | :mismatch | :stale | :wrong_kind | :unassigned
17
+ | :stale_assignment | :regressed | :not_durable | :pinned
18
+ # Honoured idempotent repeats the journal can prove: what was asked for
19
+ # already holds, nothing changed. :unchanged (advance, checkpoint,
20
+ # checkpoint_from) and :already_durable (confirm_rewritten,
21
+ # confirm_superseded, with the payload that was recorded) are answers, not
22
+ # refusals. A second release, reclaim or abort is not one: it is :stale.
23
+ type repeat = :unchanged | :already_durable
24
+ type roll_refusal = :no_active | :empty | :time_regression | :overflow | :segments_full | :exhausted
25
+ type roll_decision_refusal = :no_active | :time_regression | :overflow
26
+ type observe_refusal = :unknown | :active | :exceeds
27
+ type pin_reader_refusal = :pins_full | :exhausted
28
+ type pin_checkpoint_refusal = :unassigned | :pins_full | :exhausted
29
+ type advance_refusal = :stale | :wrong_kind | :regressed
30
+ type checkpoint_refusal = :stale | :wrong_kind | :unassigned | :stale_assignment | :regressed
31
+ type release_refusal = :stale
32
+ type propose_refusal = :unknown | :active | :busy | :exhausted
33
+ type confirm_rewritten_refusal = :stale | :mismatch | :exceeds
34
+ type confirm_superseded_refusal = :stale | :mismatch
35
+ type reclaim_refusal = :stale | :not_durable | :pinned
36
+ type abort_refusal = :stale
37
+ interface _Tracker
38
+ def generation: () -> Integer
39
+ def base: () -> Integer
40
+ end
41
+ # A Pin, a Replacement or a segment id is only meaningful to the Journal
42
+ # that issued it. Each carries that journal's scope in the top 16 bits of
43
+ # its generation, attempt or id, above a number of the one sequence the
44
+ # journal counts from 1 for all three, so no two of them are equal. A
45
+ # Journal that never issued it answers :stale to a Pin or Replacement (nil
46
+ # from pin_offset) and :unknown to a segment id (nil from segment, [] from
47
+ # the scans as a resume position). Two Journals left in the same scope
48
+ # cannot tell their handles apart.
49
+ class Pin
50
+ def kind: () -> (:reader | :checkpoint)
51
+ def generation: () -> Integer
52
+ # The scope of the Journal that issued this pin.
53
+ def scope: () -> Integer
54
+ # A value: equal to, and hashing like, any handle to the same identity.
55
+ def ==: (untyped other) -> bool
56
+ def eql?: (untyped other) -> bool
57
+ def hash: () -> Integer
58
+ end
59
+ class Replacement
60
+ def segment: () -> Integer
61
+ def attempt: () -> Integer
62
+ # The scope of the Journal that issued this attempt.
63
+ def scope: () -> Integer
64
+ # A value: equal to, and hashing like, any handle to the same identity.
65
+ def ==: (untyped other) -> bool
66
+ def eql?: (untyped other) -> bool
67
+ def hash: () -> Integer
68
+ end
69
+ # The core's Policy: same fields, same order, no defaults. A zero threshold
70
+ # or a ratio above 1000 raises RangeError; a non-Integer raises TypeError.
71
+ class Policy < Data
72
+ attr_reader max_bytes: Integer?
73
+ attr_reader max_records: Integer?
74
+ attr_reader max_age: nanoseconds?
75
+ attr_reader min_dead_per_mille: Integer
76
+ def self.new: (Integer? max_bytes, Integer? max_records, nanoseconds? max_age, Integer min_dead_per_mille) -> Policy
77
+ | (max_bytes: Integer?, max_records: Integer?, max_age: nanoseconds?, min_dead_per_mille: Integer) -> Policy
78
+ end
79
+ # The core's Segment. `new` mirrors `Segment::checked`: RangeError unless
80
+ # some journal could answer these eleven values together (an issued id; an
81
+ # active segment holding nothing; a closed one with records >= stored >=
82
+ # live; a replacement exactly when proposed, durable or reclaimable;
83
+ # durable :pinned, reclaimable :unpinned, active :unpinned). TypeError for a
84
+ # wrong type.
85
+ class Segment < Data
86
+ attr_reader id: Integer
87
+ attr_reader revision: Integer
88
+ attr_reader base_offset: Integer
89
+ attr_reader records: Integer
90
+ attr_reader stored_records: Integer
91
+ attr_reader live_records: Integer
92
+ attr_reader bytes: Integer
93
+ attr_reader opened_at: nanoseconds
94
+ attr_reader state: segment_state
95
+ attr_reader retention: retention
96
+ attr_reader replacement: Replacement?
97
+ def self.new: (Integer id, Integer revision, Integer base_offset, Integer records, Integer stored_records,
98
+ Integer live_records, Integer bytes, nanoseconds opened_at, segment_state state, retention retention,
99
+ Replacement? replacement) -> Segment
100
+ | (id: Integer, revision: Integer, base_offset: Integer, records: Integer, stored_records: Integer,
101
+ live_records: Integer, bytes: Integer, opened_at: nanoseconds, state: segment_state, retention: retention,
102
+ replacement: Replacement?) -> Segment
103
+ def end_offset: () -> Integer
104
+ end
105
+ # The core's Roll::Due(reason); Roll::Keep is the symbol :keep. Another
106
+ # Symbol raises RangeError, a non-Symbol TypeError.
107
+ class Due < Data
108
+ attr_reader reason: roll_reason
109
+ def self.new: (roll_reason reason) -> Due
110
+ | (reason: roll_reason) -> Due
111
+ end
112
+ # The core's Rolled. `new` mirrors `Rolled::new`: RangeError unless both ids
113
+ # are issued ids of one scope, opened drawn after sealed, and next_offset is
114
+ # positive. TypeError for a non-Integer.
115
+ class Rolled < Data
116
+ attr_reader sealed: Integer
117
+ attr_reader opened: Integer
118
+ attr_reader next_offset: Integer
119
+ def self.new: (Integer sealed, Integer opened, Integer next_offset) -> Rolled
120
+ | (sealed: Integer, opened: Integer, next_offset: Integer) -> Rolled
121
+ end
122
+ # The core's Reclaimed. `new` mirrors `Reclaimed::new`: RangeError unless the
123
+ # segment id is issued, revision is 0 or an attempt drawn after it, and
124
+ # replaced_by is nil or a later attempt still. TypeError for a non-Integer.
125
+ class Reclaimed < Data
126
+ attr_reader segment: Integer
127
+ attr_reader revision: Integer
128
+ attr_reader bytes: Integer
129
+ attr_reader replaced_by: Integer?
130
+ def self.new: (Integer segment, Integer revision, Integer bytes, Integer? replaced_by) -> Reclaimed
131
+ | (segment: Integer, revision: Integer, bytes: Integer, replaced_by: Integer?) -> Reclaimed
132
+ end
133
+ class Journal
134
+ # A journal in scope zero.
135
+ def self.new: (Policy policy, Integer base_offset, nanoseconds now) -> Journal
136
+ # A journal whose segment ids, pin generations and attempt numbers carry
137
+ # `scope`, an Integer in 0..65_535 (TypeError for a non-Integer,
138
+ # RangeError outside the range).
139
+ def self.with_scope: (Policy policy, Integer base_offset, nanoseconds now, Integer scope) -> Journal
140
+ # A journal of `scope` after a restart, continuing the sequence after
141
+ # `issued`: the #issued saved from the journal before it. Segments and
142
+ # pins are not restored. RangeError for an `issued` outside 0..2**48-2,
143
+ # which would leave no number for the active segment.
144
+ def self.resumed: (Policy policy, Integer base_offset, nanoseconds now, Integer scope, Integer issued) -> Journal
145
+ def scope: () -> Integer
146
+ # How many segment ids, pin generations and attempts, together, the
147
+ # journal has issued. Save it to resume after a restart.
148
+ def issued: () -> Integer
149
+ def policy: () -> Policy
150
+ def segment_capacity: () -> Integer
151
+ def pin_capacity: () -> Integer
152
+ def size: () -> Integer
153
+ def empty?: () -> bool
154
+ def roll_decision: (Integer bytes, Integer records, nanoseconds now) -> (:keep | Due | roll_decision_refusal)
155
+ def roll: (Integer bytes, Integer records, nanoseconds now) -> (Rolled | roll_refusal)
156
+ def observe_live: (Integer id, Integer live_records) -> (:recorded | observe_refusal)
157
+ def active: () -> Segment?
158
+ def segment: (Integer id) -> Segment?
159
+ def covering: (Integer offset) -> Segment?
160
+ # `after` must be an id this journal issued (any of its segment ids, pin
161
+ # generations or attempts, even one whose segment has left); one it never
162
+ # issued (another scope, sequence zero, not reached) is no position: [].
163
+ def segments: (Integer? after, Integer limit) -> Array[Segment]
164
+ def compaction_candidates: (Integer? after, Integer limit) -> Array[Segment]
165
+ def reclaimable: (Integer? after, Integer limit) -> Array[Segment]
166
+ def pin_reader: (Integer offset) -> (Pin | pin_reader_refusal)
167
+ def pin_checkpoint: (Integer assignment, Integer offset) -> (Pin | pin_checkpoint_refusal)
168
+ def pin_checkpoint_from: (_Tracker tracker) -> (Pin | pin_checkpoint_refusal)
169
+ def advance: (Pin, Integer offset) -> (:moved | :unchanged | advance_refusal)
170
+ def checkpoint: (Pin, Integer assignment, Integer offset) -> (:advanced | :reassigned | :unchanged | checkpoint_refusal)
171
+ def checkpoint_from: (Pin, _Tracker tracker) -> (:advanced | :reassigned | :unchanged | checkpoint_refusal)
172
+ # :stale for a pin that is not held: one already released included.
173
+ def release: (Pin) -> (:released | release_refusal)
174
+ def pin_offset: (Pin) -> Integer?
175
+ def low_pin: () -> Integer?
176
+ def pins: () -> Integer
177
+ def propose: (Integer id) -> (Replacement | propose_refusal)
178
+ # The core's confirm_durable(replacement, durable), one method per variant
179
+ # of its `Durable` argument: Rewritten { bytes, live_records } and Superseded.
180
+ # On an attempt that is already durable: :already_durable for the payload
181
+ # that was recorded, :mismatch for any other (the other method, or
182
+ # different bytes or live_records).
183
+ def confirm_rewritten: (Replacement, Integer bytes, Integer live_records) -> (:recorded | :already_durable | confirm_rewritten_refusal)
184
+ def confirm_superseded: (Replacement) -> (:recorded | :already_durable | confirm_superseded_refusal)
185
+ def reclaim: (Replacement) -> (Reclaimed | reclaim_refusal)
186
+ def abort: (Replacement) -> (:aborted | abort_refusal)
187
+
188
+ # Private native hooks. `__open` is the one constructor `new`,
189
+ # `with_scope` and `resumed` reach (scope and issued as a pair, policy
190
+ # last); the `__check_*` hooks validate a Data value's fields at
191
+ # `initialize`, answering nil or raising.
192
+ private def self.__open: (Integer base_offset, nanoseconds now, [Integer, Integer] scope_and_issued, Policy policy) -> Journal
193
+ private def self.__check_policy: (Integer? max_bytes, Integer? max_records, nanoseconds? max_age,
194
+ Integer min_dead_per_mille) -> nil
195
+ private def self.__check_due: (roll_reason reason) -> nil
196
+ private def self.__check_rolled: (Integer sealed, Integer opened, Integer next_offset) -> nil
197
+ private def self.__check_reclaimed: (Integer segment, Integer revision, Integer bytes, Integer? replaced_by) -> nil
198
+ # Segment's id, revision, base_offset, records, then stored_records,
199
+ # live_records, bytes, opened_at.
200
+ private def self.__check_segment: ([Integer, Integer, Integer, Integer] head,
201
+ [Integer, Integer, Integer, nanoseconds] counts, segment_state state,
202
+ retention retention, Replacement? replacement) -> nil
203
+
204
+ private
205
+
206
+ # The Policy fields `policy` builds its value from, in order.
207
+ def __policy: () -> [Integer?, Integer?, nanoseconds?, Integer]
208
+ end
209
+ end
metadata ADDED
@@ -0,0 +1,64 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: journal_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.7.1
5
+ platform: x86_64-darwin
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: 'Decides when to roll a log segment, which sealed segments are worth
14
+ compacting, and when a replaced segment file may be deleted without losing what
15
+ a reader or checkpoint pin still needs. Metadata only: not a log writer, byte compactor
16
+ or recovery runtime.'
17
+ email:
18
+ - oss@seuros.com
19
+ executables: []
20
+ extensions: []
21
+ extra_rdoc_files: []
22
+ files:
23
+ - CHANGELOG.md
24
+ - LICENSE.txt
25
+ - README.md
26
+ - ext/journal_machines_native/core/CHANGELOG.md
27
+ - ext/journal_machines_native/core/README.md
28
+ - ext/journal_machines_native/extconf.rb
29
+ - lib/journal_machines.rb
30
+ - lib/journal_machines/version.rb
31
+ - lib/journal_machines_native/journal_machines_native.bundle
32
+ - sig/journal_machines.rbs
33
+ homepage: https://github.com/seuros/journal_machines
34
+ licenses:
35
+ - MIT
36
+ metadata:
37
+ source_code_uri: https://github.com/seuros/journal_machines
38
+ rubygems_mfa_required: 'true'
39
+ cargo_crate_name: journal_machines_native
40
+ cargo_manifest_path: ext/journal_machines_native/ffi/Cargo.toml
41
+ post_install_message:
42
+ rdoc_options: []
43
+ require_paths:
44
+ - lib
45
+ required_ruby_version: !ruby/object:Gem::Requirement
46
+ requirements:
47
+ - - ">="
48
+ - !ruby/object:Gem::Version
49
+ version: '4.0'
50
+ - - "<"
51
+ - !ruby/object:Gem::Version
52
+ version: 4.1.dev
53
+ required_rubygems_version: !ruby/object:Gem::Requirement
54
+ requirements:
55
+ - - ">="
56
+ - !ruby/object:Gem::Version
57
+ version: '0'
58
+ requirements: []
59
+ rubygems_version: 3.5.23
60
+ signing_key:
61
+ specification_version: 4
62
+ summary: 'Log segment metadata for Ruby: roll decisions, compaction candidates, pin-gated
63
+ reclaim'
64
+ test_files: []