window_machines 0.1.4-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9e33ca0fae5b8290f3beb14591dd39cc89ca5e00036c7759bc056f0a13742c0
+  data.tar.gz: 917cb912fd766034f36f67c0f2be31ae14117d48a5b901452e3b19394ea431eb
+SHA512:
+  metadata.gz: f6b1fa15e46de0310445a33b2470e3e42e98e4df09f58b1a40164f0afb440be0426d4699cc9519321dd0fd38521edbfd16a876bf569c959840d95d185949687a
+  data.tar.gz: 18a9d6f676d9e965379cb05563bb4e0ce81f620f16fe3d89873a0715762f2bbd99f9a959e053936bfcbaac1ac8d64928a9963b43303f616c13bd5fdf255c147d

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/window_machines/compare/window_machines/v0.1.3...window_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b8098d7](https://github.com/seuros/window_machines/commit/b8098d7d280dfd4e48ba7ade3a72b7f891853ec4))
+
+## [0.1.3](https://github.com/seuros/window_machines/compare/window_machines/v0.1.2...window_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([db7ff81](https://github.com/seuros/window_machines/commit/db7ff817e11a2448c17640631c2f8a6a254447a3))
+
+## [0.1.2](https://github.com/seuros/window_machines/compare/window_machines/v0.1.1...window_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([ca5ad94](https://github.com/seuros/window_machines/commit/ca5ad94ba196793f6366a9a5025903bd5bd22c51))
+
+## [0.1.1](https://github.com/seuros/window_machines/compare/window_machines-v0.1.0...window_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3bd753e](https://github.com/seuros/window_machines/commit/3bd753ec5ae5890e4e54272e5df4523c9d685d4b))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+# WindowMachines
+
+> Bucket events by when they happened, not by when they finally showed up. 🔭
+
+Event-time windows for Ruby. Give it a timestamp and it tells you which tumbling or sliding bucket the event belongs in. Give it a `Watermark` and it tells you when a bucket is safe to close. Give it a `Sessions` tracker and it groups bursts of activity, merging two bursts into one when a late arrival turns out to bridge the gap.
+
+## Quick Start
+
+```bash
+gem 'window_machines'
+```
+
+```ruby
+# Every event lands in a ten-minute bucket, keyed by its own timestamp.
+WindowMachines.tumbling(event.at, 600)      # => [start, end] of its bucket
+
+# Nothing gets reported until the watermark says the bucket is done.
+watermark = WindowMachines::Watermark.new
+watermark.advance(latest_timestamp_seen)
+watermark.closes?(start, finish, 120)       # => true once start..finish is two minutes behind
+
+# Activity bursts, split by five minutes of silence, merged if something fills the gap.
+sessions = WindowMachines::Sessions.new(300)
+sessions.insert(event.at)                   # => [first, last] of the session it joined
+sessions.advance_watermark(latest_timestamp_seen)
+sessions.take_closed                        # => the oldest finished session, or nil
+```
+
+Timestamps are Integers in whatever unit you pick. Seconds, milliseconds, ticks. The gem never looks at a clock.
+
+## A Message to the Resistance
+
+So you built the signups-per-ten-minutes chart. You bucket each event by `Time.now` as it comes off the queue, you flush the bucket when the clock crosses the boundary, product loves it.
+
+Then the mobile app ships an offline queue. A user signs up on a plane at 14:03, the phone syncs at 16:40, and your chart puts the signup in the 16:40 bucket. The 14:00 bucket was flushed two hours ago and will never be corrected. Nobody notices until finance reconciles the month and the numbers don't add up.
+
+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.
+
+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.
+
+## Chapter 1: Stardate 2025.186, the AMS Akidau
+
+> **AMS Akidau**, NCC-4219, *Akidau*-class survey vessel.
+> The order telemetry arrives is not the order the stars emitted it.
+
+Light from a near star reaches the survey deck in minutes. Light from a far one takes years. The deck doesn't log a supernova under the day the photons hit the sensor. It logs it under the day it happened, and it waits a stated grace period before declaring any day's catalogue final.
+
+Somewhere in the chart room, a cadet files:
+
+```ruby
+def bucket_for(event)
+  (Time.now.to_i / 600) * 600   # close enough
+end
+```
+
+"That," says the survey officer, "is how a supernova ends up catalogued two years late."
+
+## The Flight Plan
+
+Each window moves through three states as the watermark catches up with it:
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> open: event with timestamp inside the window
+    open --> closable: watermark reaches window end plus allowed lateness
+    closable --> reported: you emit it and take_closed hands it over
+    reported --> [*]
+    open --> rejected: insert at or below the watermark
+    rejected --> [*]
+```
+
+And the signup that flew in from a plane:
+
+```mermaid
+sequenceDiagram
+    participant Q as Queue
+    participant W as Watermark
+    participant B as Bucket 14:00-14:10
+
+    Q->>B: signup at 14:03 (arrived 16:40)
+    Note over B: tumbling(14:03, 600) picks this bucket
+    Q->>W: advance(16:40)
+    W-->>B: closes?(14:00, 14:10, 120) => true
+    Note over B: safe to report, 14:03 included
+```
+
+With the grace period set to two minutes, a bucket closes once the watermark is two minutes past its end. Any event that still claims to belong in a closed bucket is refused instead of miscounted.
+
+## How Windows Work
+
+### Tumbling
+
+Fixed-size, back-to-back buckets. A timestamp belongs to exactly one.
+
+```ruby
+WindowMachines.tumbling(12, 10)   # => [10, 20]
+WindowMachines.tumbling(19, 10)   # => [10, 20]
+WindowMachines.tumbling(20, 10)   # => [20, 30]
+```
+
+Windows are half-open. The start is inside, the end is not, so 20 begins the next bucket.
+
+### Sliding
+
+Overlapping buckets of one width, started every `slide`. A timestamp can sit in several at once. You get them newest first.
+
+```ruby
+WindowMachines.sliding(12, 10, 5)   # => [[10, 20], [5, 15]]
+WindowMachines.sliding(7, 10, 5)    # => [[5, 15], [0, 10]]
+```
+
+A slide wider than the width leaves holes. A timestamp that falls into a hole gets an empty list, not a guess:
+
+```ruby
+WindowMachines.sliding(12, 1, 5)    # => []
+```
+
+### Watermarks
+
+A watermark is your claim that nothing older than this will still turn up. You advance it. It never moves backwards.
+
+```ruby
+watermark = WindowMachines::Watermark.new
+watermark.value           # => nil, nothing seen yet
+watermark.advance(22)     # => true
+watermark.advance(9)      # => false, ignored
+watermark.value           # => 22
+```
+
+`closes?` answers whether a window has waited long enough. It takes the window plus how much lateness you're willing to absorb:
+
+```ruby
+watermark.closes?(10, 20, 2)   # => true, 20 + 2 is not past 22
+watermark.closes?(10, 20, 3)   # => false, give it one more tick
+watermark.closes?(20, 30, 0)   # => false, still open
+```
+
+### Sessions
+
+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.
+
+```ruby
+sessions = WindowMachines::Sessions.new(5)
+sessions.insert(10)   # => [10, 10], a new session
+sessions.insert(15)   # => [10, 15], five apart, still one session
+sessions.insert(30)   # => [30, 30], too far, a second session
+sessions.insert(21)   # => [21, 21], nine from 30, a third
+```
+
+Then the late one shows up:
+
+```ruby
+sessions.insert(26)   # => [21, 30], bridges the gap and merges two sessions into one
+```
+
+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`.
+
+```ruby
+sessions.advance_watermark(25)
+sessions.take_closed      # => [10, 15], 15 + 5 is behind 25
+sessions.take_closed      # => nil, [21, 30] is still open
+
+sessions.advance_watermark(40)
+sessions.take_closed      # => [21, 30]
+```
+
+Anything at or below the watermark is late by definition and raises, leaving the sessions untouched:
+
+```ruby
+sessions.insert(40)   # => raises ArgumentError
+```
+
+## The Rules of the Survey
+
+- **Everything is an Integer** in `0..2**64-1`. Floats, strings, and anything else raise `TypeError`. Negative or oversized values raise `RangeError`.
+- **Zero widths, slides, and gaps are rejected** with `ArgumentError`. A bucket of size zero holds nothing.
+- **Sliding is capped at 32 windows per timestamp.** A width-to-slide ratio that would produce more raises `RangeError` rather than truncating the list.
+- **Sessions hold at most 32 open sessions at once.** A 33rd raises `RangeError` and nothing is dropped to make room. Close some first.
+- **Late inserts raise.** An event at or below the sessions watermark is refused, not silently folded into something.
+- **Frozen means frozen.** `freeze` a watermark or a sessions tracker and every mutation raises `FrozenError`.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'll just add a small delay before flushing. Late events are rare."
+### Reality: Late is a distribution, not an edge case.
+
+Mobile sync, retried webhooks, a consumer that fell behind for an hour. A fixed delay picks one point on that curve and misfiles everything past it. A watermark you advance from the data itself moves with the curve, and `closes?` with explicit lateness makes the trade-off a number you chose, not one you guessed.
+
+## What's Yours
+
+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.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The signup happened at 14:03. The phone only admitted it at 16:40.**

data/ext/window_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/window_machines/compare/window-machines-v0.2.1...window-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b8098d7](https://github.com/seuros/window_machines/commit/b8098d7d280dfd4e48ba7ade3a72b7f891853ec4))
+
+## [0.2.1](https://github.com/seuros/window_machines/compare/window-machines-v0.2.0...window-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([db7ff81](https://github.com/seuros/window_machines/commit/db7ff817e11a2448c17640631c2f8a6a254447a3))
+
+## [0.2.0](https://github.com/seuros/window_machines/compare/window-machines-v0.1.0...window-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3bd753e](https://github.com/seuros/window_machines/commit/3bd753ec5ae5890e4e54272e5df4523c9d685d4b))

data/ext/window_machines_native/core/README.md

@@ -0,0 +1,22 @@
+# window-machines
+
+> **AMS Akidau**, NCC-4219, *Akidau*-class survey vessel.
+
+Engine-room flight manual: divide observation time into bounded survey windows.
+
+Allocation-free `no_std` window boundaries and one-key bounded session tracking.
+All timestamps and widths use one caller-selected unsigned unit and origin.
+Tumbling/sliding windows are aligned to zero and half-open `[start, end)`.
+Sliding results are newest-start-first; too-small output capacity rejects rather
+than silently truncating. Overflowing boundaries reject.
+
+Watermarks never regress. A window closes when watermark reaches its end plus
+allowed lateness; arithmetic overflow means it cannot yet close.
+
+Sessions merge events whose inactivity gaps are **at most** the configured gap,
+including out-of-order bridging events. Events at/below the current watermark
+are late and rejected; session allowed lateness is zero in this version. Advancing
+a watermark does not discard sessions: explicitly drain `take_closed()`.
+Full tables reject events that cannot merge. Callers retain aggregation payloads
+and apply the same merges; the core stores boundaries only. Multi-key indexing,
+retractions, and distributed watermark coordination are not implemented.

data/ext/window_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/lib/window_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WindowMachines
+  VERSION = '0.1.4'
+end

data/lib/window_machines.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'window_machines/version'
+require 'window_machines_native/window_machines_native'

data/sig/window_machines.rbs

@@ -0,0 +1,17 @@
+module WindowMachines
+  VERSION: String
+  def self.tumbling: (Integer timestamp, Integer width) -> [Integer, Integer]
+  def self.sliding: (Integer timestamp, Integer width, Integer slide) -> Array[[Integer, Integer]]
+  class Watermark
+    def self.new: () -> instance
+    def advance: (Integer value) -> bool
+    def value: () -> Integer?
+    def closes?: (Integer start, Integer end, Integer lateness) -> bool
+  end
+  class Sessions
+    def self.new: (Integer gap) -> instance
+    def insert: (Integer timestamp) -> [Integer, Integer]
+    def advance_watermark: (Integer value) -> bool
+    def take_closed: () -> [Integer, Integer]?
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: window_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: x86_64-linux-musl
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Initial allocation-free window policy core and thin native Ruby binding.
+  Caller owns payloads, clocks, and execution.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/window_machines_native/core/CHANGELOG.md
+- ext/window_machines_native/core/README.md
+- ext/window_machines_native/extconf.rb
+- lib/window_machines.rb
+- lib/window_machines/version.rb
+- lib/window_machines_native/window_machines_native.so
+- sig/window_machines.rbs
+homepage: https://github.com/seuros/window_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/window_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: window_machines_native
+  cargo_manifest_path: ext/window_machines_native/ffi/Cargo.toml
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native event-time window boundaries for Ruby
+test_files: []