refactor(core): split sans-IO traits from Tokio runtime

[zeon256]

Problem

The current public core traits are Tokio-spawn shaped rather than runtime-neutral:

• Collector, Sink, and Store require Send at the trait level.
• Their returned futures also require + Send.
• Associated errors require Send + Sync + 'static.
• Records and dedupe keys are pushed toward Send + 'static by the core/runtime boundary.

Those constraints are not intrinsic to collection, buffering, window storage, replay, or sink composition. They are requirements of the current Tokio supervisor, which spawns each pipeline onto a multi-thread Tokio runtime.

This makes the core hard to use in thread-per-core/local runtimes such as Glommio, where !Send futures and shard-local state are normal and desirable.

There is also Tokio coupling outside runtime.rs:

• Pipeline::run owns the scheduling loop and hardcodes tokio::time, tokio::select!, and tokio_util::sync::CancellationToken.
• runtime.rs hardcodes Tokio spawning, signals, timers, and JoinSet.
• JsonlStore currently performs blocking std::fs work inside async trait methods; fixing that with tokio::fs or tokio::task::spawn_blocking would make that backend Tokio-specific unless it is split from the runtime-neutral core.
• Cargo dependencies/features are not currently structured around a truly runtime-free core.

Proposed design

Split the crate into a runtime-neutral core plus runtime-specific adapters/features.

Core

Core should contain the dataflow and storage abstractions without executor policy:

• Collector
• Sink
• Store
• Segment
• WindowMeta
• FlushPolicy
• Tier
• Tee
• MemStore
• pipeline state-machine operations such as tick(...) and flush(...)

Core traits should not require Send unless a specific operation semantically needs it. In particular, local !Send implementations should be valid.

Pipeline should not own Tokio timers, cancellation, or spawning. Runtime adapters should drive the pipeline loop.

Tokio runtime adapter

A Tokio feature/module/crate should contain:

• the Meathook supervisor
• Tokio signal handling
• Tokio timers
• cancellation token integration
• tokio::spawn / JoinSet usage
• Tokio-specific Send + 'static bounds at the runtime entrypoint
• optionally a TokioJsonlStore using tokio::fs or spawn_blocking

This is where Send belongs, because Tokio's multi-thread spawning requires it.

Local / thread-per-core runtimes

The core split should allow a Glommio-style runtime adapter to drive the same pipeline logic using local tasks without Send bounds.

This enables shard-local implementations using types such as Rc, RefCell, local executor resources, and runtime-native file/network handles.

Store backends

Avoid treating one JSONL backend as universally async-runtime-correct.

Possible split:

• BlockingJsonlStore: uses std::fs; explicitly documented as blocking.
• TokioJsonlStore: uses Tokio offloading (tokio::fs or spawn_blocking).
• future GlommioJsonlStore: uses Glommio-native file APIs / shard-local IO.

The core Store trait should permit each backend; the backend implementation should own its runtime-specific IO strategy.

Trait design options

There are two viable stable approaches, with different tradeoffs.

Option A: associated future GATs

Use associated future types so runtime adapters can add Send bounds only where needed:

pub trait Sink<R> {
    type Error: std::error::Error + 'static;

    type Ingest<'a>: std::future::Future<Output = Result<(), Self::Error>> + 'a
    where
        Self: 'a,
        R: 'a;

    type Flush<'a>: std::future::Future<Output = Result<(), Self::Error>> + 'a
    where
        Self: 'a;

    fn ingest<'a>(
        &'a mut self,
        meta: &'a WindowMeta,
        records: Vec<R>,
    ) -> Self::Ingest<'a>;

    fn flush(&mut self) -> Self::Flush<'_>;
}

Then the Tokio adapter can require:

for<'a> S::Ingest<'a>: Send,
for<'a> S::Flush<'a>: Send,

Tradeoff: on stable Rust, implementations usually need boxed futures unless they write manual future types, because impl Trait in associated types is not stable for the crate's current Rust target.

Option B: keep RPITIT and split local/send trait families

Keep zero-cost impl Future in trait methods, but separate local runtime-neutral traits from Tokio-spawnable traits.

Tradeoff: lower per-call overhead, but duplicated APIs/adapters.

Future Rust direction

Return type notation and/or stable impl Trait in associated types would make the ideal design easier: core traits could use RPITIT without Send, and Tokio adapters could bound returned futures as Send at the spawn boundary.

Benefits

• Makes the core genuinely runtime-neutral / Sans-IO-oriented.
• Allows Glommio and other thread-per-core runtimes to use local !Send collectors, sinks, stores, and futures.
• Moves Send/Sync constraints to the actual Tokio spawn boundary.
• Makes Tokio an optional runtime integration instead of a core assumption.
• Clarifies where timers, cancellation, signals, spawning, and runtime-specific IO belong.
• Prevents blocking filesystem fixes in JsonlStore from accidentally making the core Tokio-specific.
• Creates a path for runtime-native store backends instead of one-size-fits-all async file IO.
• Aligns the crate's architecture with the stated goal of composable core abstractions.

Acceptance criteria

• Core traits compile without Tokio-specific bounds or types.
• Pipeline core logic can be driven without Tokio timers or cancellation tokens.
• Tokio runtime integration still supports existing Meathook behavior with explicit Send bounds.
• Non-Send local implementations are possible outside the Tokio adapter.
• JSONL store strategy is explicit: blocking, Tokio-offloaded, or runtime-native.
• Cargo features/dependencies reflect the split so users can depend on the core without pulling Tokio runtime integration.

[zeon256]

Option A boxing example

If we choose associated future GATs for the core traits, the trait can cleanly separate runtime policy from core semantics:

pub trait Sink<R> {
    type Error: std::error::Error + 'static;

    type Ingest<'a>: std::future::Future<Output = Result<(), Self::Error>> + 'a
    where
        Self: 'a,
        R: 'a;

    type Flush<'a>: std::future::Future<Output = Result<(), Self::Error>> + 'a
    where
        Self: 'a;

    fn ingest<'a>(
        &'a mut self,
        meta: &'a WindowMeta,
        records: Vec<R>,
    ) -> Self::Ingest<'a>;

    fn flush(&mut self) -> Self::Flush<'_>;
}

Then a Tokio runtime adapter can add Send only at the spawn boundary:

where
    S: Sink<R> + Send + 'static,
    R: Send + 'static,
    S::Error: Send + Sync + 'static,
    for<'a> S::Ingest<'a>: Send,
    for<'a> S::Flush<'a>: Send,

The stable-Rust drawback is in implementations. The implementation cannot currently write this on stable:

impl<R> Sink<R> for MySink {
    type Ingest<'a> = impl std::future::Future<Output = Result<(), Self::Error>> + 'a
    where
        Self: 'a,
        R: 'a;

    fn ingest<'a>(
        &'a mut self,
        meta: &'a WindowMeta,
        records: Vec<R>,
    ) -> Self::Ingest<'a> {
        async move {
            // ...
            Ok(())
        }
    }
}

impl Trait in associated types is still unstable, so normal async-block implementations need to erase the future type, usually with a boxed future:

use std::future::Future;
use std::pin::Pin;

type LocalBoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;
type SendBoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

impl<R> Sink<R> for MySink {
    type Error = MyError;

    type Ingest<'a> = SendBoxFuture<'a, Result<(), Self::Error>>
    where
        Self: 'a,
        R: 'a;

    type Flush<'a> = SendBoxFuture<'a, Result<(), Self::Error>>
    where
        Self: 'a;

    fn ingest<'a>(
        &'a mut self,
        meta: &'a WindowMeta,
        records: Vec<R>,
    ) -> Self::Ingest<'a> {
        Box::pin(async move {
            // ...
            Ok(())
        })
    }

    fn flush(&mut self) -> Self::Flush<'_> {
        Box::pin(async move {
            // ...
            Ok(())
        })
    }
}

A local/thread-per-core implementation could use LocalBoxFuture instead of SendBoxFuture. That keeps the core trait runtime-neutral, but costs one allocation per async method call unless the implementation provides a hand-written concrete future type.

So Option A gives the cleanest single trait family and lets runtimes add Send precisely where needed, but on stable Rust it likely trades that cleanliness for boxed futures in ordinary implementations.

[zeon256]

RTN stabilization note

Preferred long-term design should probably use return type notation (RTN), not explicit associated future GATs, once RTN is stable.

With RTN, the core traits can stay runtime-neutral and box-free:

pub trait Sink<R> {
    type Error: std::error::Error + 'static;

    async fn ingest(
        &mut self,
        meta: &WindowMeta,
        records: Vec<R>,
    ) -> Result<(), Self::Error>;

    async fn flush(&mut self) -> Result<(), Self::Error>;
}

Then the Tokio runtime adapter can add Send only at the spawn boundary:

where
    S: Sink<R> + Send + 'static,
    R: Send + 'static,
    S::Error: Send + Sync + 'static,
    S::ingest(..): Send,
    S::flush(..): Send,

Local/thread-per-core runtimes such as Glommio would omit those Send return-type bounds.

Status as of 2026-07-02:

• RTN has an accepted RFC: https://rust-lang.github.io/rfcs/3654-return-type-notation.html
• Tracking issue remains open: Tracking Issue for return type notation rust-lang/rust#109417
• RTN is implemented on nightly behind #![feature(return_type_notation)].
• The previous stabilization PR was closed/deferred: Stabilize return type notation (RFC 3654) rust-lang/rust#138424
• The 2026 Rust Project Goals include preparing TAIT + RTN for stabilization: https://rust-lang.github.io/rust-project-goals/2026/rtn.html
• That project goal says full stabilization is blocked on next-gen trait solver work and is intended late 2026.

Implication for this issue:

• If we need this split on stable immediately, associated future GATs + boxed futures remain the stable single-trait-family option.
• If we can wait, RTN gives the cleaner target API: one async trait family, no boxed futures, no duplicated local/send traits, and Send added by the runtime caller.

Suggested revisit: late 2026, after checking RTN/TAIT stabilization progress.