window_machines 0.1.4 → 0.4.4

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9587883520f31642bd8ef66526e42dfe82c863f19d5eb282d91dd01d078fe22c
4
- data.tar.gz: c3d6d27cfc1557e9b1adf5675f5b67f6a1a2d60a201988964840d9c402962577
3
+ metadata.gz: 794af1c774e3fe19c9956a46eece4dc2719499806bf32c1bdb4d50681040b49c
4
+ data.tar.gz: 28fa291b1c631b03c2d1e2edf85066244628c1bf2e5c3cf60f59afceee82c98a
5
5
  SHA512:
6
- metadata.gz: b861a7b54a3e228649b94e4c21679edab4a23bfe0d0dd0d8969c04e7284f3ad5c782931588e6577b7574813374fe715d476b574af239eae82544f046780d896a
7
- data.tar.gz: b11786fd6ce936ee32627894fcff863aa52190ce57cce53ae6442cc5919cb196d3972c84fa0953a9f3d5b30000c9be01f2ab8b22ad8123660b9df849639c93fa
6
+ metadata.gz: 7c518bc501020b548b53d4881e464a98d0ee47e41479a0d0047429107891a2e2ad94d4c29a1972481eab30a3d13661b3f50bc81c920f2402b2ed4d7048682733
7
+ data.tar.gz: 6e74af139d73ca809252fe9f50d2e506a2d343c2060b82242d0fb4632c44ce01d31378dd73bef2cd58851f5fad357137605883e507524198e0c0a7a9e3af7103
data/CHANGELOG.md CHANGED
@@ -1,5 +1,66 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.4](https://github.com/seuros/window_machines/compare/window_machines/v0.4.3...window_machines/v0.4.4) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([1a7cbe5](https://github.com/seuros/window_machines/commit/1a7cbe5d4341935857f7c32a16b8cde42b37f091))
9
+
10
+ ## [0.4.3](https://github.com/seuros/window_machines/compare/window_machines/v0.4.2...window_machines/v0.4.3) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * drop slice indexing from the window core ([7f03bb9](https://github.com/seuros/window_machines/commit/7f03bb90791d681a37d24d69f0d8a574dcb1a438))
16
+
17
+ ## [0.4.2](https://github.com/seuros/window_machines/compare/window_machines/v0.4.1...window_machines/v0.4.2) (2026-11-14)
18
+
19
+
20
+ ### Bug Fixes
21
+
22
+ * **deps:** require matryona-machines >= 0.4 ([e21f59f](https://github.com/seuros/window_machines/commit/e21f59f8f81d42b58a04b8e867644f2124c4e6d3))
23
+
24
+ ## [0.4.1](https://github.com/seuros/window_machines/compare/window_machines/v0.4.0...window_machines/v0.4.1) (2026-11-14)
25
+
26
+
27
+ ### Bug Fixes
28
+
29
+ * **deps:** require matryona-machines >= 0.3 with symbols! tables for refusals and advancing ([055ad4d](https://github.com/seuros/window_machines/commit/055ad4d22456e4ab3dd940ed92cf5dc57941612d))
30
+
31
+ ## [0.4.0](https://github.com/seuros/window_machines/compare/window_machines/v0.3.0...window_machines/v0.4.0) (2026-11-14)
32
+
33
+
34
+ ### ⚠ BREAKING CHANGES
35
+
36
+ * adopt matryona-machines 0.2 (exact_fields, frozen-first, missing_docs)
37
+
38
+ ### Features
39
+
40
+ * adopt matryona-machines 0.2 (exact_fields, frozen-first, missing_docs) ([9ac31a3](https://github.com/seuros/window_machines/commit/9ac31a39d0a1138ea78fadb8a5ff3e65d33dda19))
41
+
42
+ ## [0.3.0](https://github.com/seuros/window_machines/compare/window_machines/v0.2.0...window_machines/v0.3.0) (2026-11-14)
43
+
44
+
45
+ ### ⚠ BREAKING CHANGES
46
+
47
+ * seal window values, check exact classes natively, re-check frozen before keeping
48
+
49
+ ### Features
50
+
51
+ * seal window values, check exact classes natively, re-check frozen before keeping ([9a891df](https://github.com/seuros/window_machines/commit/9a891dfdb502048734b2a4db99823e800ff11e81))
52
+
53
+ ## [0.2.0](https://github.com/seuros/window_machines/compare/window_machines/v0.1.4...window_machines/v0.2.0) (2026-11-13)
54
+
55
+
56
+ ### ⚠ BREAKING CHANGES
57
+
58
+ * converted to the fleet conventions. One exhaustive Refusal per crate, Result from every operation that can refuse, a refusal changes nothing, provable idempotent repeats are honoured, Ruby mirrors the core. No compatibility aliases. A late event inside a still-held session is Covered; Ruby refusals are symbols and no longer raise.
59
+
60
+ ### Features
61
+
62
+ * answer refusals as Result<_, Refusal>, honour repeats, write sliding windows into a caller buffer ([520e126](https://github.com/seuros/window_machines/commit/520e126842a5065411eae7dafed05151da2919ff))
63
+
3
64
  ## [0.1.4](https://github.com/seuros/window_machines/compare/window_machines/v0.1.3...window_machines/v0.1.4) (2026-11-06)
4
65
 
5
66
 
data/Cargo.lock ADDED
@@ -0,0 +1,307 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "aho-corasick"
7
+ version = "1.1.5"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
10
+ dependencies = [
11
+ "memchr",
12
+ ]
13
+
14
+ [[package]]
15
+ name = "bindgen"
16
+ version = "0.72.1"
17
+ source = "registry+https://github.com/rust-lang/crates.io-index"
18
+ checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
19
+ dependencies = [
20
+ "bitflags",
21
+ "cexpr",
22
+ "clang-sys",
23
+ "itertools",
24
+ "proc-macro2",
25
+ "quote",
26
+ "regex",
27
+ "rustc-hash",
28
+ "shlex",
29
+ "syn",
30
+ ]
31
+
32
+ [[package]]
33
+ name = "bitflags"
34
+ version = "2.13.2"
35
+ source = "registry+https://github.com/rust-lang/crates.io-index"
36
+ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
37
+
38
+ [[package]]
39
+ name = "bytes"
40
+ version = "1.12.1"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
43
+
44
+ [[package]]
45
+ name = "cexpr"
46
+ version = "0.6.0"
47
+ source = "registry+https://github.com/rust-lang/crates.io-index"
48
+ checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
49
+ dependencies = [
50
+ "nom",
51
+ ]
52
+
53
+ [[package]]
54
+ name = "cfg-if"
55
+ version = "1.0.5"
56
+ source = "registry+https://github.com/rust-lang/crates.io-index"
57
+ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
58
+
59
+ [[package]]
60
+ name = "clang-sys"
61
+ version = "1.9.1"
62
+ source = "registry+https://github.com/rust-lang/crates.io-index"
63
+ checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
64
+ dependencies = [
65
+ "glob",
66
+ "libc",
67
+ "libloading",
68
+ ]
69
+
70
+ [[package]]
71
+ name = "either"
72
+ version = "1.19.0"
73
+ source = "registry+https://github.com/rust-lang/crates.io-index"
74
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
75
+
76
+ [[package]]
77
+ name = "glob"
78
+ version = "0.3.4"
79
+ source = "registry+https://github.com/rust-lang/crates.io-index"
80
+ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
81
+
82
+ [[package]]
83
+ name = "itertools"
84
+ version = "0.13.0"
85
+ source = "registry+https://github.com/rust-lang/crates.io-index"
86
+ checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
87
+ dependencies = [
88
+ "either",
89
+ ]
90
+
91
+ [[package]]
92
+ name = "lazy_static"
93
+ version = "1.5.1"
94
+ source = "registry+https://github.com/rust-lang/crates.io-index"
95
+ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
96
+
97
+ [[package]]
98
+ name = "libc"
99
+ version = "0.2.191"
100
+ source = "registry+https://github.com/rust-lang/crates.io-index"
101
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
102
+
103
+ [[package]]
104
+ name = "libloading"
105
+ version = "0.8.9"
106
+ source = "registry+https://github.com/rust-lang/crates.io-index"
107
+ checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
108
+ dependencies = [
109
+ "cfg-if",
110
+ "windows-link",
111
+ ]
112
+
113
+ [[package]]
114
+ name = "magnus"
115
+ version = "0.9.3"
116
+ source = "registry+https://github.com/rust-lang/crates.io-index"
117
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
118
+ dependencies = [
119
+ "bytes",
120
+ "magnus-macros",
121
+ "rb-sys",
122
+ "rb-sys-env",
123
+ "seq-macro",
124
+ ]
125
+
126
+ [[package]]
127
+ name = "magnus-macros"
128
+ version = "0.9.1"
129
+ source = "registry+https://github.com/rust-lang/crates.io-index"
130
+ checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
131
+ dependencies = [
132
+ "proc-macro2",
133
+ "quote",
134
+ "syn",
135
+ ]
136
+
137
+ [[package]]
138
+ name = "matryona-machines"
139
+ version = "0.6.0"
140
+ source = "registry+https://github.com/rust-lang/crates.io-index"
141
+ checksum = "cf8a06ab02efd767270815a1f515a40bbf3bfc77038e9360676ebe8d47833b07"
142
+ dependencies = [
143
+ "magnus",
144
+ ]
145
+
146
+ [[package]]
147
+ name = "memchr"
148
+ version = "2.8.3"
149
+ source = "registry+https://github.com/rust-lang/crates.io-index"
150
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
151
+
152
+ [[package]]
153
+ name = "minimal-lexical"
154
+ version = "0.2.1"
155
+ source = "registry+https://github.com/rust-lang/crates.io-index"
156
+ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
157
+
158
+ [[package]]
159
+ name = "nom"
160
+ version = "7.1.3"
161
+ source = "registry+https://github.com/rust-lang/crates.io-index"
162
+ checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
163
+ dependencies = [
164
+ "memchr",
165
+ "minimal-lexical",
166
+ ]
167
+
168
+ [[package]]
169
+ name = "proc-macro2"
170
+ version = "1.0.107"
171
+ source = "registry+https://github.com/rust-lang/crates.io-index"
172
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
173
+ dependencies = [
174
+ "unicode-ident",
175
+ ]
176
+
177
+ [[package]]
178
+ name = "quote"
179
+ version = "1.0.47"
180
+ source = "registry+https://github.com/rust-lang/crates.io-index"
181
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
182
+ dependencies = [
183
+ "proc-macro2",
184
+ ]
185
+
186
+ [[package]]
187
+ name = "rb-sys"
188
+ version = "0.9.130"
189
+ source = "registry+https://github.com/rust-lang/crates.io-index"
190
+ checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
191
+ dependencies = [
192
+ "rb-sys-build",
193
+ ]
194
+
195
+ [[package]]
196
+ name = "rb-sys-build"
197
+ version = "0.9.130"
198
+ source = "registry+https://github.com/rust-lang/crates.io-index"
199
+ checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
200
+ dependencies = [
201
+ "bindgen",
202
+ "lazy_static",
203
+ "proc-macro2",
204
+ "quote",
205
+ "regex",
206
+ "shell-words",
207
+ "syn",
208
+ ]
209
+
210
+ [[package]]
211
+ name = "rb-sys-env"
212
+ version = "0.2.3"
213
+ source = "registry+https://github.com/rust-lang/crates.io-index"
214
+ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
215
+
216
+ [[package]]
217
+ name = "regex"
218
+ version = "1.13.1"
219
+ source = "registry+https://github.com/rust-lang/crates.io-index"
220
+ checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
221
+ dependencies = [
222
+ "aho-corasick",
223
+ "memchr",
224
+ "regex-automata",
225
+ "regex-syntax",
226
+ ]
227
+
228
+ [[package]]
229
+ name = "regex-automata"
230
+ version = "0.4.18"
231
+ source = "registry+https://github.com/rust-lang/crates.io-index"
232
+ checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
233
+ dependencies = [
234
+ "aho-corasick",
235
+ "memchr",
236
+ "regex-syntax",
237
+ ]
238
+
239
+ [[package]]
240
+ name = "regex-syntax"
241
+ version = "0.8.11"
242
+ source = "registry+https://github.com/rust-lang/crates.io-index"
243
+ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
244
+
245
+ [[package]]
246
+ name = "rustc-hash"
247
+ version = "2.1.3"
248
+ source = "registry+https://github.com/rust-lang/crates.io-index"
249
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
250
+
251
+ [[package]]
252
+ name = "seq-macro"
253
+ version = "0.3.6"
254
+ source = "registry+https://github.com/rust-lang/crates.io-index"
255
+ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
256
+
257
+ [[package]]
258
+ name = "shell-words"
259
+ version = "1.1.1"
260
+ source = "registry+https://github.com/rust-lang/crates.io-index"
261
+ checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
262
+
263
+ [[package]]
264
+ name = "shlex"
265
+ version = "1.3.0"
266
+ source = "registry+https://github.com/rust-lang/crates.io-index"
267
+ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
268
+
269
+ [[package]]
270
+ name = "syn"
271
+ version = "2.0.119"
272
+ source = "registry+https://github.com/rust-lang/crates.io-index"
273
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
274
+ dependencies = [
275
+ "proc-macro2",
276
+ "quote",
277
+ "unicode-ident",
278
+ ]
279
+
280
+ [[package]]
281
+ name = "unicode-ident"
282
+ version = "1.0.27"
283
+ source = "registry+https://github.com/rust-lang/crates.io-index"
284
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
285
+
286
+ [[package]]
287
+ name = "window-machines"
288
+ version = "0.5.1"
289
+ dependencies = [
290
+ "matryona-machines",
291
+ ]
292
+
293
+ [[package]]
294
+ name = "window_machines_native"
295
+ version = "0.1.7"
296
+ dependencies = [
297
+ "magnus",
298
+ "matryona-machines",
299
+ "rb-sys",
300
+ "window-machines",
301
+ ]
302
+
303
+ [[package]]
304
+ name = "windows-link"
305
+ version = "0.2.1"
306
+ source = "registry+https://github.com/rust-lang/crates.io-index"
307
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
data/Cargo.toml CHANGED
@@ -8,11 +8,13 @@ rust-version = "1.99"
8
8
  license = "MIT"
9
9
  [workspace.dependencies]
10
10
  window-machines = { path = "ext/window_machines_native/core" }
11
+ matryona-machines = { version = ">=0.6", default-features = false }
11
12
  magnus = { version = "0.9.3", default-features = false }
12
13
  rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
13
14
  [workspace.lints.rust]
14
15
  unsafe_code = "deny"
15
16
  unused_must_use = "warn"
17
+ missing_docs = "warn"
16
18
  [workspace.lints.clippy]
17
19
  all = { level = "warn", priority = -1 }
18
20
  pedantic = { level = "warn", priority = -1 }
data/README.md CHANGED
@@ -12,21 +12,26 @@ gem 'window_machines'
12
12
 
13
13
  ```ruby
14
14
  # Every event lands in a ten-minute bucket, keyed by its own timestamp.
15
- WindowMachines.tumbling(event.at, 600) # => [start, end] of its bucket
15
+ bucket = WindowMachines.tumbling(event.at, 600) # => a Window with start and end
16
16
 
17
17
  # Nothing gets reported until the watermark says the bucket is done.
18
18
  watermark = WindowMachines::Watermark.new
19
- watermark.advance(latest_timestamp_seen)
20
- watermark.closes?(start, finish, 120) # => true once start..finish is two minutes behind
19
+ watermark.advance(latest_timestamp_seen) # => :advanced
20
+ watermark.closes?(bucket, 120) # => true once the bucket is two minutes behind
21
21
 
22
22
  # Activity bursts, split by five minutes of silence, merged if something fills the gap.
23
23
  sessions = WindowMachines::Sessions.new(300)
24
- sessions.insert(event.at) # => [first, last] of the session it joined
25
- sessions.advance_watermark(latest_timestamp_seen)
26
- sessions.take_closed # => the oldest finished session, or nil
24
+ case sessions.insert(event.at)
25
+ in WindowMachines::Opened[session] then start_aggregate(session)
26
+ in WindowMachines::Extended[session] then merge_aggregates_inside(session)
27
+ in WindowMachines::Covered[session] then add_to_aggregate(session)
28
+ in :late | :full | :overflow => refused then park(event, refused)
29
+ end
30
+ sessions.advance_watermark(latest_timestamp_seen) # => :advanced
31
+ sessions.take_closed # => the oldest finished Session, or nil
27
32
  ```
28
33
 
29
- Timestamps are Integers in whatever unit you pick. Seconds, milliseconds, ticks. The gem never looks at a clock.
34
+ Timestamps, widths, gaps and lateness are Integers in one event-time unit you pick. Seconds, milliseconds, ticks. They are event time, not a monotonic clock, so they are not nanoseconds unless you say so. The gem never looks at a clock.
30
35
 
31
36
  ## A Message to the Resistance
32
37
 
@@ -36,7 +41,7 @@ Then the mobile app ships an offline queue. A user signs up on a plane at 14:03,
36
41
 
37
42
  The event knew when it happened. Your pipeline threw that away and used arrival time instead, because arrival time is what the clock on the wall gives you for free.
38
43
 
39
- This gem is the other way around. The event's own timestamp decides the bucket. A watermark you advance decides when a bucket has waited long enough for stragglers. Late arrivals land in the right bucket or get rejected loudly, never quietly misfiled.
44
+ This gem is the other way around. The event's own timestamp decides the bucket. A watermark you advance decides when a bucket has waited long enough for stragglers. Late arrivals land in the right bucket or get refused with an answer that says why, never quietly misfiled.
40
45
 
41
46
  ## Chapter 1: Stardate 2025.186, the AMS Akidau
42
47
 
@@ -66,8 +71,8 @@ stateDiagram-v2
66
71
  open --> closable: watermark reaches window end plus allowed lateness
67
72
  closable --> reported: you emit it and take_closed hands it over
68
73
  reported --> [*]
69
- open --> rejected: insert at or below the watermark
70
- rejected --> [*]
74
+ open --> refused: insert at or below the watermark, outside every held session
75
+ refused --> [*]
71
76
  ```
72
77
 
73
78
  And the signup that flew in from a plane:
@@ -81,7 +86,7 @@ sequenceDiagram
81
86
  Q->>B: signup at 14:03 (arrived 16:40)
82
87
  Note over B: tumbling(14:03, 600) picks this bucket
83
88
  Q->>W: advance(16:40)
84
- W-->>B: closes?(14:00, 14:10, 120) => true
89
+ W-->>B: closes?(bucket, 120) => true
85
90
  Note over B: safe to report, 14:03 included
86
91
  ```
87
92
 
@@ -94,20 +99,21 @@ With the grace period set to two minutes, a bucket closes once the watermark is
94
99
  Fixed-size, back-to-back buckets. A timestamp belongs to exactly one.
95
100
 
96
101
  ```ruby
97
- WindowMachines.tumbling(12, 10) # => [10, 20]
98
- WindowMachines.tumbling(19, 10) # => [10, 20]
99
- WindowMachines.tumbling(20, 10) # => [20, 30]
102
+ WindowMachines.tumbling(12, 10) # => #<data WindowMachines::Window start=10, end=20>
103
+ WindowMachines.tumbling(19, 10) # => the same window
104
+ WindowMachines.tumbling(20, 10) # => #<data WindowMachines::Window start=20, end=30>
105
+ WindowMachines.tumbling(2**64 - 1, 10) # => :overflow, that bucket would end past the last timestamp
100
106
  ```
101
107
 
102
- Windows are half-open. The start is inside, the end is not, so 20 begins the next bucket.
108
+ Windows are half-open. The start is inside, the end is not, so 20 begins the next bucket. A `Window` is a frozen `Data` with `start` and `end`.
103
109
 
104
110
  ### Sliding
105
111
 
106
112
  Overlapping buckets of one width, started every `slide`. A timestamp can sit in several at once. You get them newest first.
107
113
 
108
114
  ```ruby
109
- WindowMachines.sliding(12, 10, 5) # => [[10, 20], [5, 15]]
110
- WindowMachines.sliding(7, 10, 5) # => [[5, 15], [0, 10]]
115
+ WindowMachines.sliding(12, 10, 5) # => [Window(10, 20), Window(5, 15)]
116
+ WindowMachines.sliding(7, 10, 5) # => [Window(5, 15), Window(0, 10)]
111
117
  ```
112
118
 
113
119
  A slide wider than the width leaves holes. A timestamp that falls into a hole gets an empty list, not a guess:
@@ -116,6 +122,12 @@ A slide wider than the width leaves holes. A timestamp that falls into a hole ge
116
122
  WindowMachines.sliding(12, 1, 5) # => []
117
123
  ```
118
124
 
125
+ One call answers at most `WindowMachines::CAPACITY` (32) windows. A width-to-slide ratio that needs more is `:undersized`: you get no list rather than a truncated one.
126
+
127
+ ```ruby
128
+ WindowMachines.sliding(100, 33, 1) # => :undersized
129
+ ```
130
+
119
131
  ### Watermarks
120
132
 
121
133
  A watermark is your claim that nothing older than this will still turn up. You advance it. It never moves backwards.
@@ -123,62 +135,92 @@ A watermark is your claim that nothing older than this will still turn up. You a
123
135
  ```ruby
124
136
  watermark = WindowMachines::Watermark.new
125
137
  watermark.value # => nil, nothing seen yet
126
- watermark.advance(22) # => true
127
- watermark.advance(9) # => false, ignored
138
+ watermark.advance(22) # => :advanced
139
+ watermark.advance(22) # => :repeated, already there, nothing changed
140
+ watermark.advance(9) # => :regressed, refused, nothing changed
128
141
  watermark.value # => 22
129
142
  ```
130
143
 
144
+ Repeating the value it already holds is not a refusal: the claim you are making already stands. Only a value behind it is refused. `WindowMachines::Watermark.at(22)` builds one that already stands at 22, for progress you saved or read from somewhere else.
145
+
131
146
  `closes?` answers whether a window has waited long enough. It takes the window plus how much lateness you're willing to absorb:
132
147
 
133
148
  ```ruby
134
- watermark.closes?(10, 20, 2) # => true, 20 + 2 is not past 22
135
- watermark.closes?(10, 20, 3) # => false, give it one more tick
136
- watermark.closes?(20, 30, 0) # => false, still open
149
+ bucket = WindowMachines::Window.new(10, 20)
150
+ watermark.closes?(bucket, 2) # => true, 20 + 2 is not past 22
151
+ watermark.closes?(bucket, 3) # => false, give it one more tick
152
+ watermark.closes?(WindowMachines::Window.new(20, 30), 0) # => false, still open
137
153
  ```
138
154
 
155
+ `closes?` is a question, so it never refuses. It reads only the window's `end`; an end plus lateness past `2**64-1` is a point no watermark can reach, and the answer is `false`.
156
+
139
157
  ### Sessions
140
158
 
141
- Sessions have no fixed size. A session is a run of events where no two neighbours are more than `gap` apart. Insert returns the span of whichever session the event ended up in.
159
+ Sessions have no fixed size. A session is a run of events where no two neighbours are more than `gap` apart. Insert says what the event did and hands back the `Session` (`first`, `last`) it ended up in.
142
160
 
143
161
  ```ruby
144
162
  sessions = WindowMachines::Sessions.new(5)
145
- sessions.insert(10) # => [10, 10], a new session
146
- sessions.insert(15) # => [10, 15], five apart, still one session
147
- sessions.insert(30) # => [30, 30], too far, a second session
148
- sessions.insert(21) # => [21, 21], nine from 30, a third
163
+ sessions.insert(10) # => Opened[Session(10, 10)], a new session
164
+ sessions.insert(15) # => Extended[Session(10, 15)], five apart, still one session
165
+ sessions.insert(30) # => Opened[Session(30, 30)], too far, a second session
166
+ sessions.insert(21) # => Opened[Session(21, 21)], nine from 30, a third
167
+ sessions.insert(12) # => Covered[Session(10, 15)], already inside, nothing changed
149
168
  ```
150
169
 
151
170
  Then the late one shows up:
152
171
 
153
172
  ```ruby
154
- sessions.insert(26) # => [21, 30], bridges the gap and merges two sessions into one
173
+ sessions.insert(26) # => Extended[Session(21, 30)], bridges the gap and merges two sessions into one
155
174
  ```
156
175
 
176
+ `Opened`, `Extended` and `Covered` are small `Data` values with one reader, `session`. On `Extended`, merge every aggregate you keep whose old session lies inside the new boundaries. `Covered` means the boundaries already include that timestamp. The tracker keeps boundaries, not events, so it cannot tell a replayed event from a second event at the same time; if that matters, dedupe by your own event id.
177
+
157
178
  A session is finished once the watermark is a full `gap` past its last event. `take_closed` hands you the oldest finished session and forgets it. Call it until it returns `nil`.
158
179
 
159
180
  ```ruby
160
181
  sessions.advance_watermark(25)
161
- sessions.take_closed # => [10, 15], 15 + 5 is behind 25
162
- sessions.take_closed # => nil, [21, 30] is still open
163
-
164
- sessions.advance_watermark(40)
165
- sessions.take_closed # => [21, 30]
182
+ sessions.take_closed # => Session(10, 15), 15 + 5 is behind 25
183
+ sessions.take_closed # => nil, Session(21, 30) is still open
166
184
  ```
167
185
 
168
- Anything at or below the watermark is late by definition and raises, leaving the sessions untouched:
186
+ An event at or below the watermark that would have to open or move a session is late. It is refused and the sessions are untouched. One that a held session already covers moves nothing, so it is still `Covered`, right up until you drain that session:
169
187
 
170
188
  ```ruby
171
- sessions.insert(40) # => raises ArgumentError
189
+ sessions.insert(24) # => Covered[Session(21, 30)], below the watermark but already inside
190
+ sessions.insert(20) # => :late, it would have to stretch a session backwards
191
+
192
+ sessions.advance_watermark(40)
193
+ sessions.take_closed # => Session(21, 30)
194
+ sessions.insert(24) # => :late, that session is gone and nothing remembers it
172
195
  ```
173
196
 
174
197
  ## The Rules of the Survey
175
198
 
176
- - **Everything is an Integer** in `0..2**64-1`. Floats, strings, and anything else raise `TypeError`. Negative or oversized values raise `RangeError`.
177
- - **Zero widths, slides, and gaps are rejected** with `ArgumentError`. A bucket of size zero holds nothing.
178
- - **Sliding is capped at 32 windows per timestamp.** A width-to-slide ratio that would produce more raises `RangeError` rather than truncating the list.
179
- - **Sessions hold at most 32 open sessions at once.** A 33rd raises `RangeError` and nothing is dropped to make room. Close some first.
180
- - **Late inserts raise.** An event at or below the sessions watermark is refused, not silently folded into something.
181
- - **Frozen means frozen.** `freeze` a watermark or a sessions tracker and every mutation raises `FrozenError`.
199
+ - **Everything is an Integer** in `0..2**64-1`, in the event-time unit you chose. Floats, strings, `nil` and anything else raise `TypeError`. Negative or oversized values raise `RangeError`.
200
+ - **Zero widths, sizes, slides, and gaps raise `RangeError`.** A bucket of size zero holds nothing, and the core cannot even be asked.
201
+ - **Refusals don't raise.** `:overflow`, `:undersized`, `:regressed`, `:late` and `:full` are answers, each with its own symbol and no catch-all, and a refused call changes nothing. Only malformed input raises.
202
+ - **Every answer, by method.**
203
+
204
+ | Method | Honoured | Refused | Records the clock |
205
+ | --- | --- | --- | --- |
206
+ | `WindowMachines.tumbling(timestamp, width)` | a `Window` | `:overflow` | no clock, nothing recorded |
207
+ | `WindowMachines.sliding(timestamp, size, slide)` | an Array of `Window`, newest first, `[]` in a hole | `:overflow`, `:undersized` | no clock, nothing recorded |
208
+ | `Window.new(start, end)`, `Session.new(first, last)` | the value | never refuses; an invalid value raises `RangeError` | no clock, nothing recorded |
209
+ | `Session#covers?(timestamp)` | `true` or `false` | never refuses | no clock, nothing recorded |
210
+ | `Watermark#advance(value)` | `:advanced`, or `:repeated` when it already held `value` | `:regressed` | no clock; `:advanced` records the watermark, `:repeated` nothing |
211
+ | `Watermark#closes?(window, allowed_lateness)` | `true` or `false` | never refuses | no clock, nothing recorded |
212
+ | `Sessions#insert(timestamp)` | `Opened`, `Extended`, or `Covered` when a held session already covers it | `:late`, `:overflow`, `:full` | no clock, nothing recorded |
213
+ | `Sessions#advance_watermark(value)` | `:advanced`, or `:repeated` when it already held `value` | `:regressed` | no clock; `:advanced` records the watermark, `:repeated` nothing |
214
+ | `Sessions#take_closed` | a `Session`, `nil` when none is closed | never refuses | no clock, nothing recorded |
215
+ - **Repeats are honoured when they can be proven.** A watermark repeated at its own value is `:repeated`. A timestamp inside a held session is `Covered`, even below the watermark. Once `take_closed` drained the session there is no history left to prove it with, and the same timestamp is `:late`.
216
+ - **`:overflow` means past the end of event time.** A window whose end, or a session whose `last + gap`, would exceed `2**64-1` is refused.
217
+ - **Sliding answers at most 32 windows** (`WindowMachines::CAPACITY`). More is `:undersized`, never a truncated list.
218
+ - **Sessions hold at most 32 sessions at once**, closed-but-undrained ones included. A 33rd that joins none of them is `:full` and nothing is dropped to make room. Advance the watermark and drain first.
219
+ - **Values mirror the core, and are valid or do not exist.** `Window(start, end)`, `Session(first, last)`, `Opened`/`Extended`/`Covered(session)` are frozen `Data`, checked by the core when built, by hand or by the gem, `with` included. `Window.new(20, 10)` and `Window.new(10, 10)` raise `RangeError` (a window holds at least one timestamp); `Session.new(5, 3)` raises `RangeError`; a non-Integer raises `TypeError`, and so does an `Opened`/`Extended`/`Covered` holding anything but a `Session`. `closes?` takes a `Window`; loose Integers or an Array in its place raise `TypeError`. Every value class is sealed: `allocate` is gone and subclassing raises `TypeError`. Sealing stops accidents, not reflection (a named `class X < Session` still binds its constant, `Data#initialize` can be bound directly, `Marshal.load` skips `initialize`), so the native side is the authority: `closes?`, `covers?` and the `Opened`/`Extended`/`Covered` constructors accept only an instance of exactly `Window` or `Session` (`TypeError` otherwise), read its members without calling any method, and check them through the core again (`RangeError` for an invalid one). The classes are resolved once when the gem loads; swapping a constant later changes nothing the gem builds or accepts.
220
+ - **A call that raises changed nothing.** `insert` and `take_closed` build their answer before the tracker keeps the change, so if building it raises the event was not inserted and the closed session is still there to take. If building it changed the tracker (a redefined `Opened.new` or `Session.new` calling back in), the outer call raises `RuntimeError`, is not applied, and that inner change stands. If building it froze the tracker, the call raises `FrozenError` and is not applied.
221
+ - **No clock is recorded.** Everything here is event time you pass in; nothing reads or records a monotonic clock. The only progress kept is the watermark, which `advance`/`advance_watermark` record on `:advanced` and leave alone on `:repeated` or `:regressed`.
222
+ - **Nothing here issues ids or survives a restart by itself.** There are no handles and no scopes. To resume, rebuild a watermark with `Watermark.at(saved_value)`; sessions are rebuilt by re-inserting.
223
+ - **Frozen means frozen.** `freeze` a watermark or a sessions tracker and every mutating call (`advance`, `insert`, `advance_watermark`, `take_closed`) raises `FrozenError`, repeats included.
182
224
 
183
225
  ## What You Think You're Doing vs Reality
184
226
 
@@ -189,7 +231,7 @@ Mobile sync, retried webhooks, a consumer that fell behind for an hour. A fixed
189
231
 
190
232
  ## What's Yours
191
233
 
192
- The gem decides boundaries. It never stores a payload. Keep your own counts or rows per `[start, end]` pair, add to them when an event is bucketed, and emit them when `closes?` says so or `take_closed` returns a span. Advancing the watermark is also your call. Drive it from the timestamps you've actually seen, with whatever lag your sources deserve.
234
+ The gem decides boundaries. It never stores a payload. Keep your own counts or rows per `Window` or `Session` (both are `Data`, so they work as Hash keys), add to them when an event is bucketed, and emit them when `closes?` says so or `take_closed` returns a session. Advancing the watermark is also your call. Drive it from the timestamps you've actually seen, with whatever lag your sources deserve.
193
235
 
194
236
  ## License
195
237