Crate proxima_core 

Foundation primitives for the proxima workspace — the layer everything else is built out of, and the one crate that cannot itself be expressed as a pipe (proxima_primitives::Pipe is defined one level up, on top of this).

Every module carries the finest tier it can reach, so a bare-metal consumer takes a subset rather than a fork:

• unconditional, down to no_std + no-alloc: arch, datagram_batch, factory::Named, markers, per_core, ring, time. The buffered ones (datagram_batch, per_core, ring) carry an inline fixed-cap form sized by build.rs alongside the heap form behind alloc. CI builds both --features alloc and bare --no-default-features for thumbv7m-none-eabi (scripts/thumbv7m-cliff-gate.sh).
• alloc: arena, batch
• std: buffer, signal, and the factory registry (registry / config) and live, which ride their own default-off features
• orthogonal gates: io (io-async) is no-alloc for the traits and alloc for Prepend; park (park) is no_std but needs an OS futex; histogram needs 64-bit atomics, so it is absent on cortex-m.

ProximaError is the shared error type. It carries two surfaces: the String-payload variants (Decode(String), Config(String), …) that most of the workspace still constructs, and the typed *Kind variants (DecodeKind(DecodeError), ConfigKind(ConfigError), …) that let a caller match on the failure without parsing a message. Typed is the convention; this crate constructs only typed kinds. The String variants remain until their owning crates migrate, and render identically either way.

Typed sources are erased through Box<dyn core::error::Error + Send + Sync + 'static> so the sub-enum surface is uniform regardless of whether the underlying source is std::io::Error, serde_json::Error, FromUtf8Error, … core::error::Error is stable since Rust 1.81 and the workspace is edition 2024 (1.85+), so it is always available.

Re-exports

pub use factory::Named;

pub use serving_state::ServingFsmError;

pub use serving_state::ServingState;

Modules

accept_rule

The accept decision for speculative rows as loadable data: AcceptRule::accepted_rows is the pure decision, and its count is the accepted argument of crate::serving_state::ServingState::accept_rows.

arch

Per-chipset CPU hint intrinsics. This is the ONE place in the workspace that expresses architecture hints, so a primitive that wants one depends on this.

arena

Reused byte arena — append bytes, reference them by (offset, len), read them back without copying. One backing allocation grown power-of-two; the store-once / reference-many shape (mirrors a consumer crate’s ByteBuffer/HeapBuffer, but single-writer so no atomics). The consumer owns the reclamation policy: reset drops everything at once, which is the right primitive for a bounded in-flight window that fully drains (e.g. a per-connection retransmit buffer between quiescent points). A ring / free-list layer can sit on top when out-of-order partial reclaim is needed.

batch

Batched terminal writes: accumulate many encoded items into one buffer, then flush the whole accumulation to a sink in a SINGLE write. The discipline that turns N per-item writes into one — the expensive terminal op (a syscall, a DMA submit) is paid once per batch instead of per item, so a producer is never stalled per-item on a slow terminal.

buffer

BufferPool/PooledBuf — per-worker byte-buffer reservoir. Folded in from the former proxima-lib satellite crate: BufferPool leans on thread_local::ThreadLocal for its per-worker routing, which has no no_std/alloc analog (it resolves OS thread identity), so the whole pool is std-only; alloc-only builds carry no public API here.

datagram_batch

Canonical tiered datagram-I/O buffers.

factory

A generic, lock-free registry of named factories — the composition-from-config primitive shared by every name→thing registry in the workspace.

histogram

Lock-free latency/size histogram with a branchless base-2 bucket pick.

kv_decision

markers

Compile-time marker traits for dispatch units.

per_core

Per-core sharded storage: count slots, each emitting thread/core routed to one to cut contention on a shared structure (e.g. one MPMC ring per core).

ring

serving_state

The serving control plane as one sans-IO state machine over the algebra: every transition performs exactly one program evaluation, or placement copies only, and the per-layer cache lives inside the variant a transition returns rather than in a cache object patched from outside.

signal

Sticky one-shot level signal — the cancellation / shutdown scope primitive.

sized

Build-time sizing constants emitted by build.rs from proxima-core.toml (principle 12). Only the no_std + no-alloc tier is bounded by these; the alloc tier grows dynamically.

time

proxima_core::time (re-exported as proxima::time) — runtime-agnostic timer primitives shaped like tokio::time. The active backend (host thread, embassy, prime’s per-core wheel, deterministic mock, or a user-supplied hardware driver) is selected by the active proxima_build::Profile via the timer axis; build.rs bakes a &'static dyn Driver symbol into the build, so Sleep::poll’s only runtime cost is one virtual dispatch.

Enums

BodyError

Body-stream / worker-side failure.

ConfigError

Configuration / spec error.

DecodeError

Decode failure during wire / format parsing.

EncodeError

Encode failure during wire / format serialization.

NotFoundError

Resource-not-found error.

ProximaError

RecordError

Recording / replay sink-side error.

RegistryError

Registry-level error (factories, listen protocols, codecs).

UpstreamError

Upstream / I/O-side failure.

Type Aliases

ErrorSource

Erased source for typed sub-enum variants. Concrete error types (std::io::Error, serde_json::Error, FromUtf8Error, ParseIntError, etc.) all impl core::error::Error and box cleanly through this alias.

ProximaResult