pipeline_machines 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a949ac7222dd3fda0495facd3720e00cb13f4b78870048127310c844f1ebc18d
+  data.tar.gz: 4c8988104a0977410f93fe8396246eb0401a820d289a88cc7bda0a3a6a3ad76c
+SHA512:
+  metadata.gz: a59cda3f44680fbc3e915cc41d73f52d27b335722ce3697e91983e6d2ce75473bfc5a7bd5419fe80bb8a430738d0b0563a0c820fd71aafd4e074b6d468952ea1
+  data.tar.gz: 8ce58b5a751886b228fde6d99e5305e1b2ca830ce49ff534db56fde249f451ddd8607cd5944b22b08218c647d694245662cf6ace7637a5958a98871229d7af5b

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/pipeline_machines/compare/pipeline_machines/v0.1.3...pipeline_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* extract has_queued lane check ([8c9510f](https://github.com/seuros/pipeline_machines/commit/8c9510fbd5987c2d2f9d4c653ad7aff983e30955))
+
+## [0.1.3](https://github.com/seuros/pipeline_machines/compare/pipeline_machines/v0.1.2...pipeline_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([f308575](https://github.com/seuros/pipeline_machines/commit/f30857529c4ac61c145128710bb916770699f760))
+
+## [0.1.2](https://github.com/seuros/pipeline_machines/compare/pipeline_machines/v0.1.1...pipeline_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([cd46e0d](https://github.com/seuros/pipeline_machines/commit/cd46e0d8adb4868270b1278fb7cd24c001c89c72))
+
+## [0.1.1](https://github.com/seuros/pipeline_machines/compare/pipeline_machines-v0.1.0...pipeline_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([5e3f8da](https://github.com/seuros/pipeline_machines/commit/5e3f8dadd4cb7159e5fcbdf64a0c8d2de110c680))
+
+
+### Bug Fixes
+
+* name the gemspec block spec so the release workflow detects the extension ([4a86b80](https://github.com/seuros/pipeline_machines/commit/4a86b80992c296d0157d5488daea23c1295665c4))

data/Cargo.toml

@@ -0,0 +1,24 @@
+[workspace]
+members = ["ext/pipeline_machines_native/core", "ext/pipeline_machines_native/ffi"]
+default-members = ["ext/pipeline_machines_native/core"]
+resolver = "3"
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+[workspace.dependencies]
+pipeline-machines = { path = "ext/pipeline_machines_native/core" }
+magnus = { version = "0.9.3", default-features = false }
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
+priority-machines = ">=0.2"
+flow-machines = ">=0.2"
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+missing_docs = "warn"
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+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,250 @@
+# PipelineMachines
+
+> A job you cancelled is still on the ship until someone signs for it. 🛤️
+
+A stage coordinator for Ruby. You submit work into one of four weighted lanes, pull it out in fair order, report what happened, and collect the receipt. Fan a job out across several lanes and join on all of them. The stage keeps count of every slot, including the ones holding work you told to stop but that hasn't stopped yet.
+
+## Quick Start
+
+```bash
+gem 'pipeline_machines'
+```
+
+```ruby
+# Four lanes: transcode, thumbnail, captions, notify. Thumbnails get double share.
+stage = PipelineMachines::Stage.new([1, 2, 1, 1])
+
+# One upload, three lanes at once.
+jobs = stage.fan_out([0, 1, 2], upload.id)
+
+# The worker loop. dispatch hands back [job, payload, lane].
+while (job, payload, lane = stage.dispatch)
+  run_lane(lane, payload)
+  stage.complete(job)
+end
+
+stage.join(jobs)                     # => :ready
+jobs.each { |job| stage.reap(job) }  # collect receipts, free the slots
+```
+
+## A Message to the Resistance
+
+So you built the upload pipeline. A job comes in, you push three tasks onto a queue, three workers pick them up, the video gets transcoded, thumbnailed, and captioned. Then product asked for cancel.
+
+You added a `cancelled` flag. Workers check it before starting. Great. Except the transcode worker checked it four seconds ago and is now thirty seconds into an ffmpeg call that doesn't care about your flag. The user sees "cancelled", uploads a replacement, and now two transcodes of the same video are fighting over one CPU. Meanwhile your concurrency limit says there's a free slot, because the cancelled job was removed from the queue the moment the flag flipped.
+
+The queue was honest about what was *waiting*. It lied about what was *running*. A slot isn't free when you decide a job should stop. It's free when the job has actually stopped and you've collected the outcome.
+
+This gem keeps that count. Queued work can be cancelled outright. Running work stays on the books until the worker confirms it quit, or finishes anyway. Nothing frees a slot except reaping the receipt.
+
+## Chapter 1: Stardate 2025.186, the AMS Welsh
+
+> **AMS Welsh**, NCC-4212, *Welsh*-class stage carrier.
+> Freight is not gone merely because it left the waiting deck.
+
+The carrier doesn't run any of the work. It holds the manifest: which berths are charged, which descriptors are on the waiting deck, which are on the work deck, and which outcomes are still unsigned. A berth stays charged until the receipt is collected. Not when the job is dispatched, not when it's cancelled. Collected.
+
+Somewhere on the bridge, a junior officer proposes:
+
+```ruby
+def cancel(job)
+  queue.delete(job)
+  job.update(status: :cancelled)   # the worker will notice. probably.
+end
+```
+
+"That," says the deck officer, "is how a berth gets charged twice."
+
+## The Flight Plan
+
+Every job is in exactly one of these states. Only reaping frees its slot.
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued: submit / fan_out
+    queued --> running: dispatch
+    queued --> cancelled: cancel
+    running --> complete: complete
+    running --> cancelling: cancel (worker not yet stopped)
+    cancelling --> cancelled: confirm_cancel
+    cancelling --> complete: complete (finished anyway)
+    complete --> [*]: reap
+    cancelled --> [*]: reap
+```
+
+And the upload that got cancelled mid-transcode:
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant Stage
+    participant W as Worker
+
+    You->>Stage: submit(lane 0, upload 42)
+    W->>Stage: dispatch
+    Stage-->>W: job, 42, lane 0
+    Note over W: ffmpeg starts, 30 seconds to go
+
+    You->>Stage: cancel(job)
+    Stage-->>You: true
+    You->>Stage: join([job])
+    Stage-->>You: pending
+    Note over Stage: slot still charged
+
+    Note over W: ffmpeg killed
+    W->>Stage: confirm_cancel(job)
+    Stage-->>W: true
+    You->>Stage: reap(job)
+    Stage-->>You: [42, cancelled]
+    Note over Stage: slot free
+```
+
+## How the Deck Works
+
+### Submit and dispatch
+
+Lanes are numbered 0 to 3. Each lane has a weight you choose at construction. Dispatch walks the lanes in weighted round robin, first in first out within a lane.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 2, 1, 1])
+stage.lanes      # => 4
+stage.capacity   # => 64
+
+stage.submit(0, 100)
+stage.submit(0, 101)
+stage.submit(1, 200)
+stage.submit(1, 201)
+stage.submit(2, 300)
+
+job, payload, lane = stage.dispatch
+[payload, lane]   # => [100, 0]
+```
+
+Lane 1 has weight 2, so it gets two turns per round. With the queue above, dispatch order is lane 0, lane 1, lane 1, lane 2, then lane 0 again. Payloads are Integers: ids, pointers into your own tables, whatever names the work. The stage never sees the work itself.
+
+A lane that doesn't exist, or a full stage, returns `nil` from `submit`. It never raises for that.
+
+### Fan out and join
+
+One payload, several lanes, admitted atomically. Either every lane gets a job or none does.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+jobs = stage.fan_out([3, 1], 9)
+jobs.size             # => 2
+stage.join(jobs)      # => :pending
+
+2.times do
+  job, = stage.dispatch
+  stage.complete(job)
+end
+stage.join(jobs)      # => :ready
+```
+
+`join` answers for the whole group. `:ready` when every job completed, `:cancelled` when any was cancelled, `:pending` while any is still queued, running, or waiting on a cancel confirmation, and `:unknown` if any handle has been reaped or belongs to another stage. Lanes in a fan-out must be distinct, and asking for a lane that doesn't exist returns `nil` without admitting anything.
+
+### Cancel, and what cancel actually means
+
+Cancel a queued job and it's done. Terminal. Reap it whenever you like.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+job = stage.submit(2, 77)
+
+stage.cancel(job)     # => true
+stage.join([job])     # => :cancelled
+stage.reap(job)       # => [77, :cancelled]
+stage.dispatch        # => nil, nothing left
+```
+
+Cancel a *running* job and you've only asked. The slot stays charged until the worker says it stopped.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+stage.submit(0, 5)
+job, = stage.dispatch
+
+stage.cancel(job)           # => true, request noted
+stage.reap(job)             # => nil, not terminal yet
+stage.join([job])           # => :pending
+
+stage.confirm_cancel(job)   # => true, worker has stopped
+stage.reap(job)             # => [5, :cancelled]
+```
+
+If the worker finishes before it sees the request, `complete` wins and the cancel is moot:
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+stage.submit(0, 1)
+job, = stage.dispatch
+
+stage.cancel(job)           # => true
+stage.complete(job)         # => true, it finished anyway
+stage.confirm_cancel(job)   # => false, nothing to confirm
+stage.reap(job)             # => [1, :complete]
+```
+
+### Reap, or the slot never comes back
+
+The stage holds 64 jobs. Not 64 queued, not 64 running. 64 *unreaped*. A completed job you never reap is a slot you never get back.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+jobs = 64.times.map { |i| stage.submit(0, i) }
+stage.submit(0, 65)         # => nil, full
+
+job, = stage.dispatch
+stage.complete(job)
+stage.submit(0, 65)         # => nil, still full. complete isn't reap.
+
+stage.reap(job)             # => [0, :complete]
+stage.submit(0, 65)         # now admitted
+```
+
+`reap` only returns for terminal jobs: `[payload, :complete]` or `[payload, :cancelled]`. Anything else is `nil`. After reaping, the handle is dead. Every call with it returns `false` or `nil`, and `join` reports `:unknown`.
+
+### Drain
+
+Shutting down a worker pool means two things: stop taking work, and know when the last job is gone.
+
+```ruby
+stage = PipelineMachines::Stage.new([1, 1, 1, 1])
+job = stage.submit(0, 5)
+
+stage.begin_drain
+stage.submit(0, 6)          # => nil, closed
+stage.drained?              # => false, one job still charged
+
+work, = stage.dispatch      # draining still dispatches what's queued
+stage.complete(work)
+stage.drained?              # => false, completed but not reaped
+stage.reap(job)
+stage.drained?              # => true
+```
+
+## The Rules of the Carrier
+
+- **Four lanes, sixty-four slots.** Weights are an Array of exactly four Integers in `1..2**32-1`. Anything else raises `TypeError` or `ArgumentError`.
+- **Lanes and payloads are Integers** in `0..2**64-1`. Floats and strings raise `TypeError`. Negative or too large raises `RangeError`.
+- **Bad lanes and full stages return `nil`.** Only malformed input raises.
+- **Handles belong to one stage.** A job from another stage, or one already reaped, mutates nothing: `cancel`, `complete`, and `confirm_cancel` return `false`, `reap` returns `nil`, `join` says `:unknown`.
+- **`join` takes up to 64 handles.** An empty Array is `:ready`.
+- **Frozen means frozen.** Every mutation raises `FrozenError`. `join` and `drained?` still answer.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I cancelled it, so the slot is free."
+### Reality: You cancelled it, so the slot is spoken for by a job nobody is watching.
+
+Removing work from a queue is instant. Stopping work that has already started is a negotiation with a process that may be deep inside a syscall. Between those two moments the resources are still in use, and any capacity count that says otherwise will admit one job too many, every time, right when the system is under the most pressure.
+
+## What's Yours
+
+The stage counts. It doesn't run, schedule, persist, or time anything out. You run the worker loop and call `dispatch` when you have a free worker. You decide what a payload means. You tell the stage `complete` or `confirm_cancel` when the work really stopped, and you `reap` every job, every time, or the slots drain away. Across a restart, the manifest is gone, so write down what you dispatched before you dispatch it.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The transcode you cancelled at 14:02 is still burning a core at 14:03. The stage knows. Your queue didn't.**

data/ext/pipeline_machines_native/core/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.2.3](https://github.com/seuros/pipeline_machines/compare/pipeline-machines-v0.2.2...pipeline-machines-v0.2.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* extract has_queued lane check ([8c9510f](https://github.com/seuros/pipeline_machines/commit/8c9510fbd5987c2d2f9d4c653ad7aff983e30955))
+
+## [0.2.2](https://github.com/seuros/pipeline_machines/compare/pipeline-machines-v0.2.1...pipeline-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([f308575](https://github.com/seuros/pipeline_machines/commit/f30857529c4ac61c145128710bb916770699f760))
+
+## [0.2.1](https://github.com/seuros/pipeline_machines/compare/pipeline-machines-v0.2.0...pipeline-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([cd46e0d](https://github.com/seuros/pipeline_machines/commit/cd46e0d8adb4868270b1278fb7cd24c001c89c72))
+
+## [0.2.0](https://github.com/seuros/pipeline_machines/compare/pipeline-machines-v0.1.0...pipeline-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([5e3f8da](https://github.com/seuros/pipeline_machines/commit/5e3f8dadd4cb7159e5fcbdf64a0c8d2de110c680))

data/ext/pipeline_machines_native/core/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "pipeline-machines"
+version = "0.2.3"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Bounded stage dispatch, fanout/join, cancellation, and draining decisions"
+readme = "README.md"
+exclude = ["src/**/tests.rs", "tests/"]
+keywords = ["pipeline", "fanout", "join", "cancellation", "no-std"]
+categories = ["no-std", "algorithms", "concurrency"]
+[dependencies]
+priority-machines.workspace = true
+flow-machines.workspace = true
+[lints]
+workspace = true

data/ext/pipeline_machines_native/core/README.md

@@ -0,0 +1,38 @@
+# pipeline-machines
+
+> **AMS Welsh**, NCC-4212, *Welsh*-class stage carrier.
+
+Engine-room flight manual: account for bounded cargo stages and unresolved flights.
+
+Allocation-free `no_std` coordinator for fixed lanes and shared bounded job slots.
+Copyable payloads should be command IDs or small descriptors; adapters own actual
+resources and execute work. WRR selects ready lanes, FIFO within each lane.
+External eligibility masks can incorporate arbitration or deadline policy.
+
+Flow credits bound **all unreaped jobs**, including running and terminal jobs.
+Fanout admission is atomic across distinct lanes. Fan-in reports readiness over
+unreaped handles, not an output aggregation or distributed transaction.
+
+Queued cancellation is immediate. Running cancellation becomes `Cancelling` and
+keeps its capacity until the executor confirms cancellation or reports completion.
+This never assumes an unresolved external effect has disappeared. Reap only
+terminal jobs to return credit; generation checks reject stale handles.
+Handle namespaces are scoped to one stage lifetime.
+
+Draining refuses submissions while allowing dispatch and completion. No async
+runtime, multi-stage graph orchestration, automatic propagation, result payloads,
+durability, or Ruby binding is implemented.
+
+```rust
+use core::num::NonZeroU32;
+use pipeline_machines::{Stage, State};
+# fn example() -> Option<()> {
+let mut stage = Stage::<u64, 1, 4>::new([NonZeroU32::MIN])?;
+let id = stage.submit(0, 42)?;
+assert_eq!(stage.dispatch(&[true])?.id, id);
+assert!(stage.complete(id));
+assert_eq!(stage.reap(id), Some((42, State::Complete)));
+# Some(())
+# }
+# assert_eq!(example(), Some(()));
+```

data/ext/pipeline_machines_native/core/src/lib.rs

@@ -0,0 +1,261 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+use core::num::NonZeroU32;
+use flow_machines::CreditWindow;
+use priority_machines::WeightedRoundRobin;
+
+/// Stage-local generation-checked job identity.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct JobId {
+    slot: usize,
+    generation: u64,
+}
+/// Job lifecycle; cancellation is not inferred from a timeout.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum State {
+    /// Awaiting dispatch.
+    Queued,
+    /// Executor owns an unresolved action.
+    Running,
+    /// Executor was asked to cancel, but has not confirmed.
+    Cancelling,
+    /// Executor reported completion.
+    Complete,
+    /// Queued work was cancelled, or the executor confirmed cancellation.
+    Cancelled,
+}
+/// Fan-in readiness for handles not yet reaped.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Join {
+    /// All jobs completed.
+    Ready,
+    /// Some jobs remain unresolved.
+    Pending,
+    /// At least one job was cancelled.
+    Cancelled,
+    /// A handle is stale/unknown/already reaped.
+    Unknown,
+}
+/// Descriptor returned for external execution.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Dispatch<T> {
+    /// Handle to resolve after execution.
+    pub id: JobId,
+    /// Copyable command descriptor.
+    pub payload: T,
+    /// Originating lane.
+    pub lane: usize,
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct Job<T> {
+    generation: u64,
+    lane: usize,
+    payload: T,
+    state: State,
+}
+/// Bounded stage with caller-driven execution.
+#[derive(Debug)]
+pub struct Stage<T, const N: usize, const C: usize> {
+    jobs: [Option<Job<T>>; C],
+    sequence: u64,
+    credits: CreditWindow,
+    scheduler: WeightedRoundRobin<N>,
+    draining: bool,
+}
+impl<T: Copy, const N: usize, const C: usize> Stage<T, N, C> {
+    /// Construct positive lane/capacity bounds; capacity must fit in `u32`.
+    #[must_use]
+    pub fn new(weights: [NonZeroU32; N]) -> Option<Self> {
+        if N == 0 {
+            return None;
+        }
+        let Ok(capacity) = u32::try_from(C) else {
+            return None;
+        };
+        Some(Self {
+            jobs: [None; C],
+            sequence: 0,
+            credits: CreditWindow::new(NonZeroU32::new(capacity)?),
+            scheduler: WeightedRoundRobin::new(weights),
+            draining: false,
+        })
+    }
+    /// Submit one descriptor, failing without changing state if admission is impossible.
+    pub fn submit(&mut self, lane: usize, payload: T) -> Option<JobId> {
+        if self.draining || lane >= N {
+            return None;
+        }
+        let slot = self.jobs.iter().position(Option::is_none)?;
+        let generation = self.sequence.checked_add(1)?;
+        if !self.credits.try_acquire(NonZeroU32::MIN) {
+            return None;
+        }
+        self.sequence = generation;
+        self.jobs[slot] = Some(Job {
+            generation,
+            lane,
+            payload,
+            state: State::Queued,
+        });
+        Some(JobId { slot, generation })
+    }
+    /// Atomically submit the same descriptor to distinct lanes.
+    ///
+    /// # Panics
+    /// Panics only if internal prevalidated admission invariants are inconsistent.
+    pub fn fan_out(&mut self, lanes: &[usize], payload: T) -> Option<[Option<JobId>; C]> {
+        if self.draining {
+            return None;
+        }
+        let Ok(count) = u32::try_from(lanes.len()) else {
+            return None;
+        };
+        if count > self.credits.available() || self.sequence.checked_add(u64::from(count)).is_none()
+        {
+            return None;
+        }
+        for (index, lane) in lanes.iter().enumerate() {
+            if *lane >= N || lanes[..index].contains(lane) {
+                return None;
+            }
+        }
+        let mut ids = [None; C];
+        for (slot, &lane) in lanes.iter().enumerate() {
+            ids[slot] = self.submit(lane, payload);
+            assert!(ids[slot].is_some());
+        }
+        Some(ids)
+    }
+    /// Dispatch FIFO within a WRR-selected eligible lane.
+    ///
+    /// # Panics
+    /// Panics only if internal ready-lane invariants are inconsistent.
+    pub fn dispatch(&mut self, eligible: &[bool; N]) -> Option<Dispatch<T>> {
+        let ready = core::array::from_fn(|lane| eligible[lane] && self.has_queued(lane));
+        let lane = self.scheduler.select(&ready)?;
+        let slot = self
+            .jobs
+            .iter()
+            .enumerate()
+            .filter_map(|(slot, job)| {
+                job.filter(|job| job.lane == lane && job.state == State::Queued)
+                    .map(|job| (slot, job.generation))
+            })
+            .min_by_key(|&(_, generation)| generation)
+            .map(|(slot, _)| slot)?;
+        let job = self.jobs[slot].as_mut()?;
+        job.state = State::Running;
+        let dispatch = Dispatch {
+            id: JobId {
+                slot,
+                generation: job.generation,
+            },
+            payload: job.payload,
+            lane,
+        };
+        self.reset_drained_lane(lane);
+        Some(dispatch)
+    }
+    /// Request cancellation; running jobs retain their credit and unresolved state.
+    #[must_use]
+    pub fn cancel(&mut self, id: JobId) -> bool {
+        let Some(job) = self.job_mut(id) else {
+            return false;
+        };
+        job.state = match job.state {
+            State::Queued => State::Cancelled,
+            State::Running | State::Cancelling => State::Cancelling,
+            _ => return false,
+        };
+        let lane = job.lane;
+        self.reset_drained_lane(lane);
+        true
+    }
+    /// Record successful execution, including a completion racing cancellation.
+    #[must_use]
+    pub fn complete(&mut self, id: JobId) -> bool {
+        let Some(job) = self.job_mut(id) else {
+            return false;
+        };
+        if job.state != State::Running && job.state != State::Cancelling {
+            return false;
+        }
+        job.state = State::Complete;
+        true
+    }
+    /// Confirm that a requested cancellation actually stopped the action.
+    #[must_use]
+    pub fn confirm_cancel(&mut self, id: JobId) -> bool {
+        let Some(job) = self.job_mut(id) else {
+            return false;
+        };
+        if job.state != State::Cancelling {
+            return false;
+        }
+        job.state = State::Cancelled;
+        true
+    }
+    /// Remove a terminal descriptor and return its bounded slot credit.
+    ///
+    /// # Panics
+    /// Panics only if internal credit accounting is inconsistent.
+    pub fn reap(&mut self, id: JobId) -> Option<(T, State)> {
+        let job = *self.job_mut(id)?;
+        if job.state != State::Complete && job.state != State::Cancelled {
+            return None;
+        }
+        self.jobs[id.slot] = None;
+        assert!(self.credits.release(NonZeroU32::MIN));
+        Some((job.payload, job.state))
+    }
+    /// Query readiness before reaping any constituent handle.
+    #[must_use]
+    pub fn join(&self, ids: &[JobId]) -> Join {
+        let mut result = Join::Ready;
+        for id in ids {
+            let Some(Some(job)) = self.jobs.get(id.slot) else {
+                return Join::Unknown;
+            };
+            if job.generation != id.generation {
+                return Join::Unknown;
+            }
+            if job.state == State::Cancelled {
+                result = Join::Cancelled;
+            } else if job.state != State::Complete && result != Join::Cancelled {
+                result = Join::Pending;
+            }
+        }
+        result
+    }
+    /// Refuse future submissions; existing queued/running work may finish.
+    pub const fn begin_drain(&mut self) {
+        self.draining = true;
+    }
+    /// Draining is complete only after all descriptors are terminal and reaped.
+    #[must_use]
+    pub const fn is_drained(&self) -> bool {
+        self.draining && self.credits.in_flight() == 0
+    }
+    fn job_mut(&mut self, id: JobId) -> Option<&mut Job<T>> {
+        self.jobs
+            .get_mut(id.slot)?
+            .as_mut()
+            .filter(|job| job.generation == id.generation)
+    }
+    /// Whether `lane` still holds a job waiting for dispatch.
+    fn has_queued(&self, lane: usize) -> bool {
+        self.jobs
+            .iter()
+            .flatten()
+            .any(|job| job.lane == lane && job.state == State::Queued)
+    }
+    fn reset_drained_lane(&mut self, lane: usize) {
+        if !self.has_queued(lane) {
+            assert!(self.scheduler.deactivate(lane));
+        }
+    }
+}
+#[cfg(test)]
+mod tests;

data/ext/pipeline_machines_native/extconf.rb

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

data/ext/pipeline_machines_native/ffi/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "pipeline_machines_native"
+version = "0.1.4"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+
+[dependencies]
+pipeline-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+
+[lints]
+workspace = true

data/ext/pipeline_machines_native/ffi/extconf.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('pipeline_machines_native/pipeline_machines_native') do |e|
+  e.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  e.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(makefile, File.read(makefile).gsub(
+  /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+  "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+))

data/ext/pipeline_machines_native/ffi/src/init.rs

@@ -0,0 +1,27 @@
+//! Private native entry point.
+use crate::Wrapper;
+use magnus::{Error, Ruby, function, method, prelude::*};
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("PipelineMachines")?;
+    module
+        .define_class("Job", ruby.class_object())?
+        .undef_default_alloc_func();
+    let class = module.define_class("Stage", ruby.class_object())?;
+    class.undef_default_alloc_func();
+    class.define_singleton_method("new", function!(Wrapper::new, 1))?;
+    class.define_method("submit", method!(Wrapper::submit, 2))?;
+    class.define_method("fan_out", method!(Wrapper::fan_out, 2))?;
+    class.define_method("dispatch", method!(Wrapper::dispatch, 0))?;
+    class.define_method("cancel", method!(Wrapper::cancel, 1))?;
+    class.define_method("complete", method!(Wrapper::complete, 1))?;
+    class.define_method("confirm_cancel", method!(Wrapper::confirm_cancel, 1))?;
+    class.define_method("reap", method!(Wrapper::reap, 1))?;
+    class.define_method("join", method!(Wrapper::join, 1))?;
+    class.define_method("begin_drain", method!(Wrapper::begin_drain, 0))?;
+    class.define_method("drained?", method!(Wrapper::is_drained, 0))?;
+    class.define_method("capacity", function!(Wrapper::capacity, 0))?;
+    class.define_method("lanes", function!(Wrapper::lanes, 0))?;
+    Ok(())
+}

data/ext/pipeline_machines_native/ffi/src/lib.rs

@@ -0,0 +1,203 @@
+//! Native boundary: all lifecycle decisions are delegated to the stage core.
+mod init;
+
+use magnus::{
+    Error, Integer, RArray, Ruby, Symbol, TryConvert, Value, prelude::*, typed_data::Obj,
+};
+use pipeline_machines::{JobId, Join, Stage, State};
+use std::{cell::RefCell, num::NonZeroU32, sync::Arc};
+
+const LANES: usize = 4;
+const CAPACITY: usize = 64;
+
+#[derive(Clone, Copy)]
+struct Number(u64);
+
+impl TryConvert for Number {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                Ruby::get_with(value).exception_type_error(),
+                "expected an unsigned Integer",
+            ));
+        }
+        u64::try_convert(value).map(Self)
+    }
+}
+
+#[magnus::wrap(class = "PipelineMachines::Job", free_immediately, size)]
+struct Handle {
+    owner: Arc<()>,
+    id: JobId,
+}
+
+#[magnus::wrap(class = "PipelineMachines::Stage", free_immediately, size)]
+struct Wrapper {
+    owner: Arc<()>,
+    core: RefCell<Stage<u64, LANES, CAPACITY>>,
+}
+
+impl Wrapper {
+    fn new(ruby: &Ruby, weights: RArray) -> Result<Self, Error> {
+        let values = weights.to_value_array::<LANES>()?;
+        let mut converted = [NonZeroU32::MIN; LANES];
+        for (slot, value) in converted.iter_mut().zip(values) {
+            let number = Number::try_convert(value)?.0;
+            *slot = u32::try_from(number)
+                .ok()
+                .and_then(NonZeroU32::new)
+                .ok_or_else(|| {
+                    Error::new(ruby.exception_arg_error(), "weights must be in 1..2**32-1")
+                })?;
+        }
+        let core = Stage::new(converted)
+            .ok_or_else(|| Error::new(ruby.exception_arg_error(), "invalid stage bounds"))?;
+        Ok(Self {
+            owner: Arc::new(()),
+            core: RefCell::new(core),
+        })
+    }
+
+    fn handle(&self, id: JobId) -> Handle {
+        Handle {
+            owner: Arc::clone(&self.owner),
+            id,
+        }
+    }
+
+    fn submit(this: Obj<Self>, lane: Number, payload: Number) -> Result<Option<Handle>, Error> {
+        this.check_frozen()?;
+        let lane = usize::try_from(lane.0).map_err(|_| {
+            Error::new(
+                Ruby::get_with(this).exception_range_error(),
+                "lane out of range",
+            )
+        })?;
+        let id = this.core.borrow_mut().submit(lane, payload.0);
+        Ok(id.map(|id| this.handle(id)))
+    }
+
+    fn fan_out(
+        ruby: &Ruby,
+        this: Obj<Self>,
+        lanes: RArray,
+        payload: Number,
+    ) -> Result<Option<RArray>, Error> {
+        this.check_frozen()?;
+        if lanes.len() > LANES {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "at most four distinct lanes",
+            ));
+        }
+        let mut converted = Vec::with_capacity(lanes.len());
+        for index in 0..lanes.len() {
+            let number = Number::try_convert(lanes.entry(index.cast_signed())?)?.0;
+            converted.push(
+                usize::try_from(number)
+                    .map_err(|_| Error::new(ruby.exception_range_error(), "lane out of range"))?,
+            );
+        }
+        let ids = this.core.borrow_mut().fan_out(&converted, payload.0);
+        let Some(ids) = ids else {
+            return Ok(None);
+        };
+        let result = ruby.ary_new();
+        for id in ids.into_iter().flatten() {
+            result.push(this.handle(id))?;
+        }
+        Ok(Some(result))
+    }
+
+    fn dispatch(ruby: &Ruby, this: Obj<Self>) -> Result<Option<RArray>, Error> {
+        this.check_frozen()?;
+        let work = this.core.borrow_mut().dispatch(&[true; LANES]);
+        let Some(work) = work else {
+            return Ok(None);
+        };
+        let result = ruby.ary_new();
+        result.push(this.handle(work.id))?;
+        result.push(work.payload)?;
+        result.push(work.lane)?;
+        Ok(Some(result))
+    }
+
+    fn cancel(this: Obj<Self>, handle: Obj<Handle>) -> Result<bool, Error> {
+        this.check_frozen()?;
+        Ok(Arc::ptr_eq(&this.owner, &handle.owner) && this.core.borrow_mut().cancel(handle.id))
+    }
+
+    fn complete(this: Obj<Self>, handle: Obj<Handle>) -> Result<bool, Error> {
+        this.check_frozen()?;
+        Ok(Arc::ptr_eq(&this.owner, &handle.owner) && this.core.borrow_mut().complete(handle.id))
+    }
+
+    fn confirm_cancel(this: Obj<Self>, handle: Obj<Handle>) -> Result<bool, Error> {
+        this.check_frozen()?;
+        Ok(Arc::ptr_eq(&this.owner, &handle.owner)
+            && this.core.borrow_mut().confirm_cancel(handle.id))
+    }
+
+    fn reap(
+        ruby: &Ruby,
+        this: Obj<Self>,
+        handle: Obj<Handle>,
+    ) -> Result<Option<(u64, Symbol)>, Error> {
+        this.check_frozen()?;
+        if !Arc::ptr_eq(&this.owner, &handle.owner) {
+            return Ok(None);
+        }
+        let result = this.core.borrow_mut().reap(handle.id);
+        Ok(result.map(|(payload, state)| (payload, ruby.to_symbol(state_name(state)))))
+    }
+
+    fn join(ruby: &Ruby, this: Obj<Self>, handles: RArray) -> Result<Symbol, Error> {
+        if handles.len() > CAPACITY {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "at most 64 join handles",
+            ));
+        }
+        let mut ids = Vec::with_capacity(handles.len());
+        for index in 0..handles.len() {
+            let handle: Obj<Handle> = handles.entry(index.cast_signed())?;
+            if !Arc::ptr_eq(&this.owner, &handle.owner) {
+                return Ok(ruby.to_symbol("unknown"));
+            }
+            ids.push(handle.id);
+        }
+        let result = this.core.borrow().join(&ids);
+        Ok(ruby.to_symbol(match result {
+            Join::Ready => "ready",
+            Join::Pending => "pending",
+            Join::Cancelled => "cancelled",
+            _ => "unknown",
+        }))
+    }
+
+    fn begin_drain(this: Obj<Self>) -> Result<(), Error> {
+        this.check_frozen()?;
+        this.core.borrow_mut().begin_drain();
+        Ok(())
+    }
+
+    fn is_drained(&self) -> bool {
+        self.core.borrow().is_drained()
+    }
+    const fn capacity() -> usize {
+        CAPACITY
+    }
+    const fn lanes() -> usize {
+        LANES
+    }
+}
+
+const fn state_name(state: State) -> &'static str {
+    match state {
+        State::Queued => "queued",
+        State::Running => "running",
+        State::Cancelling => "cancelling",
+        State::Complete => "complete",
+        _ => "cancelled",
+    }
+}

data/lib/pipeline_machines/version.rb

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

data/lib/pipeline_machines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'pipeline_machines/version'
+require 'pipeline_machines_native/pipeline_machines_native'

data/sig/pipeline_machines.rbs

@@ -0,0 +1,20 @@
+module PipelineMachines
+  VERSION: String
+  class Job
+  end
+  class Stage
+    def self.new: (Array[Integer] weights) -> Stage
+    def capacity: () -> Integer
+    def lanes: () -> Integer
+    def submit: (Integer lane, Integer payload) -> Job?
+    def fan_out: (Array[Integer] lanes, Integer payload) -> Array[Job]?
+    def dispatch: () -> [Job, Integer, Integer]?
+    def cancel: (Job) -> bool
+    def complete: (Job) -> bool
+    def confirm_cancel: (Job) -> bool
+    def reap: (Job) -> [Integer, Symbol]?
+    def join: (Array[Job]) -> Symbol
+    def begin_drain: () -> nil
+    def drained?: () -> bool
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: pipeline_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Local unstable stage policy model, not a durable pipeline runtime.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/pipeline_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/pipeline_machines_native/core/CHANGELOG.md
+- ext/pipeline_machines_native/core/Cargo.toml
+- ext/pipeline_machines_native/core/README.md
+- ext/pipeline_machines_native/core/src/lib.rs
+- ext/pipeline_machines_native/extconf.rb
+- ext/pipeline_machines_native/ffi/Cargo.toml
+- ext/pipeline_machines_native/ffi/extconf.rb
+- ext/pipeline_machines_native/ffi/src/init.rs
+- ext/pipeline_machines_native/ffi/src/lib.rs
+- lib/pipeline_machines.rb
+- lib/pipeline_machines/version.rb
+- sig/pipeline_machines.rbs
+homepage: https://github.com/seuros/pipeline_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/pipeline_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: pipeline_machines_native
+  cargo_manifest_path: ext/pipeline_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Initial native bounded stage lifecycle and fanout decisions
+test_files: []