lockfree/typestates/constructs

===========================================================================
First-Class Domain Typestate Extension Constructs (`lockfree/typestates/constructs`)
===========================================================================

Bridges user-defined `nim-typestates` state machines with `lockfree`
transport primitives (`BQueue`, `Queue`, `Bound`, `Channel`, `TreiberStack`,
`BStack`, `ChaseLevDeque`, `BroadcastRing`, `RendezvousChannel`).

Features:
- Re-exports the `nim-typestates` DSL (`typestate`, `transition`,
  `notATransition`, `destructorTransition`, `verifyTypestates`, `TypestateOp`)
  so consumer projects can author compile-time state machines directly via
  `import lockfree/typestates` or `import lockfree`.
- `TypestateGate[Base, InState, OutState, Transport]`: Zero-overhead
  type-safe transport gate that accepts `sink InState` on ingress (`sendState` /
  `trySendState` / `pushBottom`) and yields `Option[OutState]` on egress
  (`recvState` / `tryRecvState` / `stealState`), enforcing domain state
  transitions across thread/channel boundaries with move-only ARC/ORC safety.
- `TypestatePipelineStage[Base, InState, MidState, OutState, InTransport, OutTransport]`:
  Composable multi-stage typestate actor/pipeline step that consumes `InState`
  from `inbound`, applies a `InState -> MidState` transition proc, and forwards
  `MidState -> OutState` into `outbound`.

Types

TypestateGate

TypestateGate[Base; InState; OutState; Transport] = object
  transport*: ptr Transport

Zero-overhead typestate transport gate parameterized by:

• Base: The underlying carrier type stored in Transport
• InState: Required source typestate (distinct Base) on ingress
• OutState: Resulting target typestate (distinct Base) on egress
• Transport: Any lockfree queue, stack, deque, ring, channel, or Bound endpoint

TypestatePipelineStage

TypestatePipelineStage[Base; InState; MidState; OutState; InTransport;
                       OutTransport] = object
  inbound*: TypestateGate[Base, InState, InState, InTransport]
  outbound*: TypestateGate[Base, MidState, OutState, OutTransport]

Composable pipeline stage bridging an inbound transport (Base -> InState) and an outbound transport (MidState -> OutState).

Procedures & Functions

initTypestateGate

proc initTypestateGate[Base, InState, OutState, Transport](
    transport: var Transport): TypestateGate[Base, InState, OutState, Transport] {.
    inline, notATransition.}

Wraps transport in a compile-time InState -> OutState typestate gate.

trySendState

proc trySendState[Base, InState, OutState, Transport, ItemT](
    gate: TypestateGate[Base, InState, OutState, Transport]; item: sink ItemT): bool {.
    inline, notATransition.}

Consumes item in state InState via move (preserving ARC/ORC ownership without extra copies) and enqueues/pushes it into gate.transport.

sendState

proc sendState[Base, InState, OutState, Transport, ItemT](
    gate: TypestateGate[Base, InState, OutState, Transport]; item: sink ItemT): bool {.
    discardable, inline, notATransition.}

Consumes item in state InState and sends/pushes it through gate.transport.

recvState

proc recvState[Base, InState, OutState, Transport](
    gate: TypestateGate[Base, InState, OutState, Transport]): Option[OutState] {.
    inline, notATransition.}

Pops/receives the next payload from gate.transport and transitions it into OutState via move.

tryRecvState

proc tryRecvState[Base, InState, OutState, Transport](
    gate: TypestateGate[Base, InState, OutState, Transport];
    outItem: var OutState): bool {.inline, notATransition.}

Non-blocking receive into outItem in state OutState.

stealState

proc stealState[Base, InState, OutState, Transport](
    gate: TypestateGate[Base, InState, OutState, Transport]): Option[OutState] {.
    inline, notATransition.}

Work-stealing egress for ChaseLevDeque or thief Bound endpoints, yielding Option[OutState] via move.

initTypestatePipelineStage

proc initTypestatePipelineStage[Base, InState, MidState, OutState, InTransport,
                                OutTransport](inbound: var InTransport;
    outbound: var OutTransport): TypestatePipelineStage[Base, InState, MidState,
    OutState, InTransport, OutTransport] {.inline, notATransition.}

Initializes a typed pipeline stage that pops InState from inbound, transforms InState -> MidState, and pushes MidState -> OutState to outbound.

stepStage

proc stepStage[Base, InState, MidState, OutState, InTransport, OutTransport](
    stage: TypestatePipelineStage[Base, InState, MidState, OutState,
                                  InTransport, OutTransport];
    transform: proc (s: sink InState): MidState {.gcsafe.}): bool {.inline,
    notATransition.}

Pulls one InState item from stage.inbound, applies transform to transition InState -> MidState, and sends MidState into stage.outbound. Returns true if an item was processed and forwarded, or false if inbound was empty.