Neith Domain — Technical Specifications

Technical specification for the Neith sovereign runtime kernel: Cargo workspace organization, public Rust API contracts, the type system of the foundational core workspace, build targets, and integration interfaces.

Status: IMPLEMENTED. Neith is a polyglot domain consisting of ~60 Cargo workspaces under libs/neith/ plus a small set of standalone TypeScript packages. The crate workspaces contain real, production-quality Rust — for example the core workspace alone spans ~19,600 lines across six crates, and the audio-runtime workspace spans ~74,000 lines. This document is grounded in the source of the foundational core, crypto, hal, net, renderer and ui workspaces, which were read directly. Crates outside those six workspaces are inventoried by name and described from their Cargo.toml manifests and crate-level documentation; their exhaustive type surfaces are not enumerated here. Any item below labelled (planned) does not yet exist in source.

This document serves as the engineering reference for Neith's public API surface and workspace organization. A new engineer should read features.md first for a conceptual overview of what each workspace does, then return here when they need the actual types, method signatures, enums, and configuration parameters that code must use.

The document is organized from the ground up: the technology stack table comes first (what versions of what libraries underpin everything), then the workspace inventory (what exists in source), then the full type surfaces of the six foundational engine workspaces in dependency order — core first, then crypto, then hal, net, renderer, and ui. Build integration and the sovereignty invariant close the document.

Technology Stack#

The table below lists every third-party crate that the foundational six workspaces depend on, together with the pinned version. Anything not listed here is either a Neith-internal crate (no third-party dependency) or is used only in the extended workspaces (audio-suite, creative tools, etc.) that are inventoried separately.

Common misconceptions to avoid: the renderer/hal crates do not depend on wgpu, and neith-physics does not depend on rapier3d. neith-gpu is a self-contained GPU abstraction with its own Backend enum and handle types; neith-physics implements its own broadphase, GJK/EPA narrowphase, and constraint solver over plain [f32; 3] math types. The only external real-time crate actually used in the six core workspaces is cpal (audio HAL). There is also no wasm-bindgen or napi-rs dependency in the core six workspaces — the engine crates are consumed as native Rust crates, not via WASM/Node bindings.

Workspace Organization#

Neith is not six workspaces — libs/neith/ now contains roughly 290 workspace directories, each with its own Cargo.toml ([workspace] manifest), crates/ directory, project.json (Nx wiring), and usually a rust-toolchain.toml. A small number of directories are standalone TypeScript packages instead (they carry package.json + tsconfig.json + src/). The tables below inventory the foundational, audio, and creative workspaces; the sovereignty-closure families (Phases 156–174) are inventoried in the "Closure workspace families" section below. Consult features.md's sovereignty roadmap section for the per-phase capability envelopes and for the later-phase workspaces that do not yet have directories.

Foundational engine workspaces (six)#

The renderer/ workspace is a 16-crate workspace — it contains not only the ten rendering crates but also neith-physics, neith-audio, neith-ecs, neith-scripting, neith-animation and neith-gaussian-splatting as workspace members. The ui/ workspace also has a crate named neith-animation; it is distinct from the renderer's neith-animation crate.

Game-AI, scene, asset, and platform workspaces#

The workspaces below extend the foundational six with higher-level engine capabilities. Each follows the same structure: a Cargo.toml workspace manifest, a crates/ directory, and a project.json for Nx integration.

Audio-suite workspaces#

The audio suite is a collection of Cargo workspaces covering the full professional audio stack from driver HAL to DAW features. These are all present in source. Their crate-level type surfaces are not enumerated in this document but are described in features.md under Phases 132–133.

audio-runtime/, audio-graph/, audio-fileio/, audio-telemetry/, audio/ (crate neith-diff-audio), midi-io/, net-audio/, controllers/, vst3-host/, au-host/, lv2-host/, clap-host/, plugin-sandbox/, plugin-validator/, composer/ (crates neith-daw-core, neith-mixer, neith-midi, neith-synth, neith-spatial-audio), notation/, session-view/, comping/, restoration/, pitch/, mastering/, synth-advanced/, modular/, patch-lab/, live-code/, scoring/, sample-content/, dj/, adr-foley/, foley/, realtime-assist/.

Creative-tool workspaces#

The creative tools are Cargo workspaces (not npm packages) that implement the Blender-class 3D creation suite. See features.md Phase 44 for the feature description of each tool.

sculptor/ (crates neith-mesh-edit, neith-sculpt, neith-uv, neith-tex-paint, neith-sculptor-render), animator/ (crates neith-motion, neith-rig, neith-timeline, neith-mocap, neith-facial), cutter/ (crates neith-video-timeline, neith-vfx, neith-color-grade, neith-export), forge-core/ (crate forge-doc-graph).

Standalone TypeScript packages#

These directories are TypeScript libraries (package.json + src/), not Cargo workspaces. They provide infrastructure concerns — cloud management, observability, domain integration adapters — that do not belong in the Rust crates. Each is built with tsup/tsc and participates in the Nx graph via a project.json, but it does not expose any Rust bindings.

The core/ and scene/ workspaces additionally carry a package.json (@neith/core, etc.) alongside their Cargo manifest; this declares the Nx project so the Rust workspace participates in the Nx graph. It does not indicate a published JavaScript surface.

Closure workspace families (Phases 156–174)#

The sovereignty-closure phases are present in source as workspace families under libs/neith/ (roughly 200 workspaces beyond the foundational/audio/ creative sets above). Each family's per-phase capability envelope is in features.md; the family members are:

Note the engine-audio family (Phase 167) deliberately names its bus/graph crate audio-bus-graph to avoid colliding with the Phase-132 audio-graph runtime workspace.

core Workspace — Sovereign Runtime Kernel#

The core workspace is the bedrock every other Neith crate builds on. It provides the async executor that runs all tasks, the memory allocators that serve all subsystems, the serialization layer that crosses all boundaries, the reflection system that powers editors and scripting, the event bus that connects subsystems, and the diagnostics layer that makes everything observable. No Neith crate may depend on a third-party async runtime instead of neith-runtime, and no Neith crate may use serde directly instead of routing through neith-serde.

libs/neith/core/Cargo.toml declares the workspace, pins all third-party dependency versions in [workspace.dependencies], and sets three Cargo profiles: dev/test at opt-level = 0, release with lto = true, codegen-units = 1, opt-level = 3. The six member crates path-depend on each other via neith-runtime = { path = "crates/neith-runtime" } style entries.

neith-runtime — Async Executor#

neith-runtime is a custom work-stealing async executor designed for game engines and real-time systems. Unlike Tokio, it has no implicit global thread pool and makes no assumptions about blocking I/O patterns — tasks carry explicit priority levels, and the executor can be driven from a game loop's fixed-tick cadence. A consumer creates exactly one Runtime instance, spawns tasks onto it, and drives it with block_on or from a dedicated thread.

Source: core/crates/neith-runtime/src/. The crate's lib.rs re-exports the public surface; the crate is organized into modules affinity, backpressure, cancel, channel, executor, fiber, io, local, metrics, pool, scheduler, sync, timer.

Runtime and configuration#

Runtime (executor/mod.rs) is the primary entry point and the only type most consumers need directly. It wraps an Arc<RuntimeInner> so it can be cheaply cloned and passed across subsystems. The table below lists every public method on Runtime.

Drop for Runtime calls shutdown(Duration::from_secs(5)).

RuntimeConfig is the read-only configuration snapshot returned by RuntimeBuilder::build. All fields have sensible defaults; most consumers only need to override worker_threads to match the target CPU count.

RuntimeBuilder exposes chainable setters worker_threads (asserts >= 1), thread_name, thread_stack_size, max_blocking_threads, io_poll_interval, and build() -> Result<Runtime, RuntimeError>.

RuntimeError (thiserror):

• ThreadSpawn(std::io::Error) — a worker thread failed to spawn (#[from]).
• ShutDown — the runtime was already shut down.

Scheduler internals. Understanding the scheduler helps when diagnosing latency spikes. RuntimeInner holds four per-priority Injector queues (PriorityInjectors = Arc<[Arc<Injector<RawTask>>; 4]>, index 0 = Critical … 3 = Low), a Vec<Stealer<RawTask>>, a park condvar pair (Arc<(Mutex<usize>, Condvar)>) for sleeping workers, a shutdown_flag (AtomicBool), a task_counter (AtomicU64), the MetricsCollector, the IoDriver, and the TimerWheel. Each worker owns a Chase-Lev LIFO deque (Worker::new_lifo()); the worker poll loop drains its own deque (LIFO, warm cache), then steals from the global priority injectors (FIFO), then steals from a random peer, then parks on the I/O reactor.

TaskPriority (scheduler.rs)#

Every spawned task carries a TaskPriority. The scheduler processes higher priority tasks before lower priority ones within the same tick. Critical tasks are polled before all other work, making them suitable for physics ticks and input processing; Low tasks are only scheduled when nothing higher is pending.

#[repr(u8)] enum, Default = Normal:

Helpers: TaskPriority::ALL (the four variants in descending priority order), name() -> &'static str, poll_weight() -> u32, beats(self, other) -> bool (true when (self as u8) < (other as u8)). Implements Display.

TaskState (executor/task.rs)#

Tasks progress through a defined lifecycle. The TaskState enum models that lifecycle as a #[repr(u8)] value that can be read atomically without locks: Runnable = 0, Running = 1, Waiting = 2, Completed = 3, Cancelled = 4.

Fibers (fiber.rs)#

"Fibers" are cooperative coroutines built on Rust's native stackless async/await — they run as normal tasks inside the work-stealing executor. The fiber API provides named handles, explicit yield points, one-shot synchronization signals, and a counted variant for fan-out/join patterns.

• FiberId(pub u64) — monotonically increasing fiber identifier.
• FiberPriority — a re-export of scheduler::TaskPriority.
• FiberState enum — externally observable lifecycle state: Runnable, Yielded, WaitingSignal, WaitingLatch, WaitingTimer, Completed, Cancelled.
• yield_now() -> YieldNow — relinquish the executor for exactly one poll cycle, then resume.
• yield_ticks(n: u32) -> YieldTicks — yield for exactly n cycles.
• Signal — one-shot synchronisation primitive (fired: AtomicBool, waiters: Mutex<Vec<Waker>>). Signal::new() -> Arc<Self>, fire() wakes all waiters, is_fired() -> bool. wait_signal(Arc<Signal>) -> WaitSignal parks until fired.
• CountedSignal — fires its inner Signal when an AtomicU64 counter reaches zero. CountedSignal::new(count: u64) -> Arc<Self>, decrement(), wait() -> WaitSignal, remaining() -> u64.

Cancellation (cancel.rs)#

• CancellationToken — new(), cancelled() (already-cancelled token), cancel(), is_cancelled() -> bool, cancelled_future() -> CancelledFuture (a future that resolves on cancellation), child_token() -> CancellationTokenChild.
• CancellationTokenChild — a child token whose cancellation propagates from its parent (tree propagation).
• CancelledFuture — the future yielded by cancelled_future().

Timers (timer.rs)#

• TimerWheel — hierarchical timer wheel. new(), insert(deadline: Instant, waker: Waker) -> Arc<AtomicBool> (returns a cancellation flag), advance() -> usize (fires due timers, returns count fired).
• TimerHandle — cancel().
• Sleep — future created by sleep(duration: Duration) -> Sleep or sleep_until(deadline: Instant) -> Sleep.
• timeout(...) — wraps a future with a deadline; on expiry yields Elapsed.
• Instant — runtime instant type re-exported at crate root.

Channels (channel/)#

neith-runtime provides three async channel families for task coordination, each suited to a different producer/consumer cardinality. All three are pub use-d at the crate root:

• mpsc — mpsc_channel(), MpscSender, MpscReceiver.
• mpmc — mpmc_channel(), MpmcSender, MpmcReceiver.
• broadcast — broadcast_channel(), BroadcastSender, BroadcastReceiver.

Backpressure (backpressure.rs)#

bounded_channel() yields a BoundedSender / BoundedReceiver pair; the sender applies async back-pressure when the bound is reached.

Async sync primitives (sync/)#

• AsyncMutex + AsyncMutexGuard
• AsyncRwLock + AsyncReadGuard + AsyncWriteGuard
• AsyncSemaphore + SemaphorePermit
• AsyncBarrier + BarrierWaitResult
• AsyncLatch

Task-local storage (local.rs)#

TaskLocal — per-task storage slot analogous to thread-local storage.

Blocking pool (pool.rs)#

BlockingPool + BlockingPoolConfig — a dynamically sized thread pool for CPU-bound / blocking work, kept off the async worker threads.

RuntimeMetrics (metrics.rs)#

RuntimeMetrics is a Clone + Default point-in-time snapshot returned by Runtime::metrics(). Use it to diagnose scheduler imbalance, excessive steal contention, or stalled tasks. The derived methods make the raw counters actionable without requiring arithmetic at the call site.

Derived methods: tasks_active() (spawned − completed − cancelled, saturating), steal_efficiency() -> f64 (successes / attempts; 1.0 if zero attempts), avg_polls_per_worker() -> f64, busiest_worker() -> Option<(usize, u64)>, idlest_worker() -> Option<(usize, u64)>, load_imbalance() -> f64 ((busiest − idlest) / busiest; 0.0 balanced, 1.0 fully unbalanced). Implements Display.

neith-alloc — Memory Allocators#

neith-alloc provides a suite of specialized allocators, each optimized for a specific access pattern. Using the right allocator for each subsystem eliminates GC pauses, reduces fragmentation, and ensures predictable allocation latency — all critical concerns for a real-time game engine. The system allocator is appropriate for setup code; everything inside a frame tick should use one of the allocators below.

Source: core/crates/neith-alloc/src/ — fifteen modules. Allocators target distinct allocation patterns:

Additional modules without re-exports at the crate root: defrag (defragmentation strategies), huge (huge-page support), shared (shared memory / IPC).

neith-serde — Serialization#

neith-serde is the serialization layer used wherever Neith data crosses a boundary: writing save files, sending game state over the network, persisting editor state, or passing data between Rust and TypeScript. Its primary format is NBF (Neith Binary Format), a custom zero-copy binary format. It also supports JSON (human-readable debugging and Neith-to-JS interop), MessagePack (compact interop), and CBOR (constrained environments). All formats share the same schema definition and versioning infrastructure.

Source: core/crates/neith-serde/src/lib.rs. Modules: nbf, schema, json_ext, compress, partial, validate.

Neith Binary Format (nbf)#

NBF is a custom compact binary format designed for zero-copy deserialization: the in-memory layout matches the wire format closely enough that serialized data can be memory-mapped and accessed without a separate parsing step. Every NBF frame starts with a fixed 20-byte header that identifies the type and payload length, followed by the payload (MessagePack by default, or JSON for the debug variant).

The wire layout is:

[0..6]   magic       b"NEITH\x01"          (constant MAGIC)
[6..8]   version     u16 big-endian         (FORMAT_VERSION = 1; 0x8001 = JSON payload)
[8..16]  type_hash   u64 big-endian         (first 8 bytes of BLAKE3 of the type name)
[16..20] payload_len u32 big-endian
[20..]   payload     raw bytes              (MessagePack by default, or JSON)

• MAGIC: &[u8; 6] = b"NEITH\x01", FORMAT_VERSION: u16 = 1, HEADER_LEN: usize = 20.
• type_hash_for(type_name: &str) -> u64 — BLAKE3-derived 8-byte type hash.
• NbfHeader { version: u16, type_hash: u64, payload_len: u32 }.
• NbfEncoder { strict_types: bool } (default true) — encode<T: Serialize>(type_name, value) -> Result<Bytes, NbfError> (MessagePack payload), encode_json<T>(...) (JSON payload, version word 0x8001).
• NbfDecoder { strict_types: bool } — decodes NBF frames back into typed values, validating the type hash when strict_types is set.
• NbfError variants: BadMagic, UnsupportedVersion(u16), LengthMismatch { expected: u32, actual: usize }, TypeHashMismatch { encoded: u64, expected: u64 }, MsgPack(String), Io(String).

Schema, compression, deltas, validation#

• schema — SchemaVersion, SchemaMigration, SchemaRegistry (versioning and migration chains for forward/backward compatibility).
• compress — compress_lz4 / decompress_lz4, compress_zstd / decompress_zstd, CompressionLevel.
• partial — DeltaEncoder, DeltaDecoder, FieldDelta (serialize only changed fields for network state sync).
• validate — Validator, ValidationError, ValidationResult.

neith-reflect — Runtime Reflection#

neith-reflect provides runtime type metadata that enables editor property panels, scripting language bindings, automated serialization, and diff/patch workflows — all without hand-written glue code per type. Any Rust type annotated with impl_reflect_struct! (or a custom Reflect implementation) becomes inspectable at runtime: the editor can read and write its fields by name, the scripting layer can create and clone instances, and the undo/redo system can diff two instances and produce a minimal change patch.

Source: core/crates/neith-reflect/src/lib.rs. Modules: type_info, reflect, registry, access, diff, attr, impls, macros.

• TypeKind enum — Struct, Enum, Primitive, Opaque.
• FieldInfo { name: &'static str, type_name: &'static str, byte_offset: usize, is_optional: bool }. Constructed const-ly via FieldInfo::new(name, type_name, byte_offset); .optional() marks is_optional = true.
• TypeInfo { type_name: &'static str, kind: TypeKind, fields: &'static [FieldInfo], size: usize, align: usize }. Constructors new_struct(...), new_primitive(...). Methods field(name) -> Option<&FieldInfo>, field_count() -> usize.
• Reflect trait + ReflectValue (reflect module) — dynamic field inspection / mutation.
• ReflectRegistry + RegistryError — global type registry with factory and clone support.
• get_field / set_field + AccessError — name-keyed runtime field access.
• ReflectDiff + FieldChange — reflection-based diff/patch (undo-redo, network delta sync).
• AttributeMap + AttributeValue — attribute/annotation system read by editors.
• impl_reflect_struct! macro (macros module) — derives a Reflect implementation for a struct.

neith-events — Typed Event Bus#

neith-events is the in-process messaging backbone between engine subsystems. The key design decision is that channels are typed at the Rust type level: trying to publish an event of the wrong type is a compile error, not a runtime panic. This eliminates an entire class of string-keyed event bus bugs common in other game engines.

The crate supports both synchronous delivery (for input events and physics callbacks that need to be processed immediately) and asynchronous queued delivery (for less latency-sensitive events). It also supports event sourcing patterns — where state is derived entirely from event history — enabling complete undo and deterministic replay for debugging.

Source: core/crates/neith-events/src/lib.rs (~2,555 lines, single file with inline modules). Modules: event, channel, bus, reader, filter, batch, replay, source, stats, async_dispatch, priority_channel, cancellable, weak_bus, ipc, flow_graph.

Core event types (event)#

Note that Priority values here are ordered from Low = 0 upward, which is the reverse of runtime::TaskPriority where Critical = 0. This is an intentional design choice: event priority represents urgency on a rising scale, while task priority uses a descending representation for efficient array indexing. Be careful not to confuse the two.

• Priority enum (Serialize/Deserialize, ordered) — Low = 0, Normal = 1, High = 2, Critical = 3. Default = Normal.
• EventMeta { sequence: u64, timestamp_ms: u64, source_id: Option<u64>, priority: Priority }. EventMeta::new(sequence) sets timestamp_ms from the system clock; builders .with_priority(p), .with_source(id).
• EventInstance<T> { payload: T, meta: EventMeta } — a concrete event.
• Event — blanket marker trait, auto-implemented for every Clone + Send + Sync + 'static type.

Channels and the bus#

• EventChannel<T> (channel) — a double-buffered typed channel: writers send(payload) / send_with_meta(payload, meta) into the write buffer; swap() atomically swaps write↔read at the frame boundary; read_events() returns a guard over the stable read buffer; drain_immediate() takes all pending events without swapping. Sequence numbers assigned via an internal AtomicU64.
• EventBus (bus) — type-erased router holding HashMap<TypeId, BoxedChannel>. register::<T>(type_name) adds a channel (idempotent), send::<T>(event) -> Result<(), BusError>, is_registered::<T>() -> bool, registered_count() -> usize.
• BusError — NoChannel(String) (no channel for the given type name), TypeMismatch (downcast failure).
• SwappingBus — an EventBus variant that also stores per-type swap closures so swap_all() can swap every registered channel at the frame boundary.

Reading, filtering, batching, replay, sourcing#

• EventCursor / EventReader (reader) — cursor-based incremental reads.
• EventFilter / FilterResult (filter) — predicate-based routing.
• EventBatch (batch) — collect events and submit atomically.
• EventReplay (replay) — record events and replay deterministically for debugging.
• EventSource / Projection (source) — append-only event log with projection and snapshots (event-sourcing pattern).
• EventStats (stats) — per-type counts and dropped-event counts.
• AsyncEventDispatcher / AsyncEventQueue (async_dispatch) — priority-ordered queued (async) dispatch.
• PriorityEventChannel (priority_channel) — four-tier priority queues.
• CancellableEvent / CancellationContext / EventChain (cancellable) — stoppable propagation chains.
• WeakEventBus (weak_bus) — listeners held via Weak; dead listeners are auto-culled. subscribe(f) returns the Arc<ListenerFn<T>> the caller must retain; subscribe_weak(Weak<...>) registers without ownership.
• IpcEvent / IpcEventBus / IpcEventReader (ipc) — file-based cross-process event bus.
• EventFlowGraph (flow_graph) — DOT/Mermaid dispatch tracing.

neith-log — Diagnostics#

neith-log is the observability layer for Rust code. It bridges to the TypeScript observability stack at domain boundaries via W3C Trace Context propagation, so a span started in a Rust game-loop can be correlated with a TypeScript API call that triggered it. Log calls below the configured level are compiled out entirely in release builds, ensuring zero overhead on hot paths.

Source: core/crates/neith-log/src/lib.rs (~4,337 lines). Modules: structured, custom, error_info, level, rotate, metric, health, assert_sys, perf, crash, async_log, binary, tracing_otel, profiling, remote, analysis.

• LogLevel enum (level) — Trace = 0, Debug = 1, Info = 2, Warn = 3, Error = 4, Fatal = 5, Off = 6 (Serialize/Deserialize, ordered). LevelFilter applies a runtime threshold.
• StructuredLogger + LogRecord (structured) — key-value structured records, JSON output.
• CustomLogger family (custom) — CustomLogger trait, CallbackLogger, CustomLogSink, CustomLoggerConfig, CustomLoggerRegistry, CustomLoggerError, CustomLoggerFailure, CustomLogResult.
• error_info — DetailedErrorInfo, DetailedErrorBuilder, ErrorCategory, ErrorCause, ErrorLocation, ErrorSeverity, DetailedResult + DetailedResultExt.
• RotationPolicy + LogRotator (rotate) — size / count / date-based rotation.
• MetricRegistry + Counter + Gauge + Histogram (metric).
• HealthChecker + HealthStatus + CheckResult (health).
• PerformanceMarker + ScopeTimer (perf).
• CrashReporter + CrashReport + BacktraceMode + DebugBacktrace (crash) — catch_unwind-based crash capture with minidump-style reports.
• AsyncLogger (async_log) — non-blocking background writer.
• binary — BinaryLogEncoder/BinaryLogDecoder, BinaryLogSink/BinaryLogReader, BinaryLogRecord.
• tracing_otel — OpenTelemetry-style distributed tracing: TraceId, SpanId, SpanContext, Span, SpanEvent, SpanStatus, SpanRecord, Tracer, TracerProvider, SpanExporter, ConsoleSpanExporter, and W3CTraceContext (W3C Trace Context propagation).
• profiling — ProfilingSpan, ProfilingSession, ProfilingReport, ProfilingSummary (wall / CPU / alloc reporting).
• remote — RemoteLogSink, RemoteLogTarget, RemoteLogFormat, SyslogFormatter (RFC 5424).
• analysis — LogAnalyzer, LogPattern, AlertRule, AlertTrigger, LogStats.

crypto Workspace — Cryptographic Primitives#

The crypto workspace owns every cryptographic operation in Neith — hashing, symmetric encryption, asymmetric signatures and key exchange, random number generation, and TLS. Centralizing cryptography in a single workspace ensures consistent primitive selection, avoids duplicate dependencies on incompatible crates, and makes security audits tractable.

libs/neith/crypto/Cargo.toml pins rand, rand_core, rustls (features = ["ring"]), rustls-pki-types, webpki-roots, and rcgen. Each of the five crates is a single substantial lib.rs covering one cryptographic concern area.

• neith-sym (~2,400 lines) — SymError and SymResult<T>. Implements AES-256-GCM from FIPS 197 primitives (S-box, MixColumns, ShiftRows, KeyExpansion present in source), ChaCha20-Poly1305 AEAD, HKDF, PBKDF2, streaming encryption, and secure memory wiping. Errors: AuthTagMismatch, AuthenticationFailed, InvalidKeyLength { expected, actual }, InvalidNonceLength { expected, actual }, CiphertextTooShort, StreamNotInitialized, ChunkTooLarge(usize), InvalidInput(String).
• neith-asym (~5,545 lines) — AsymError and AsymResult<T>. Ed25519 signing/verification over Twisted-Edwards Curve25519 field arithmetic (prime p = 2^255 − 19, 4×u64 little-endian limbs), X25519 ECDH key exchange, key serialization, certificate-like structures. Errors: InvalidPublicKey, InvalidPrivateKey, VerificationFailed, InvalidSignatureFormat, SerializationError(String), UnsupportedAlgorithm(String).
• neith-hash (~1,838 lines) — HashError and HashResult<T>. SHA-256 and SHA-512 (FIPS 180-4 constant tables in source), BLAKE3, HMAC, incremental hasher, Merkle trees, a content-addressable store, Argon2id password hashing, HKDF, and timing-safe comparison. Errors: EmptyInput, InvalidProof, HashNotFound(String), Argon2Error(String).
• neith-rand (~797 lines) — RandError and RandResult<T>. NeithCsprng wraps OsRng (next_u64/next_u32); plus a hardware-RDRAND source, a deterministic ChaCha20-based RNG, UUID v4 generation, an entropy pool, a health monitor, a fork-safe RNG, bias-free sampling, a Fisher-Yates shuffle, and serializable RNG state. Errors: HardwareRngUnavailable, HealthCheckFailed(String), InvalidRange { min, max }, EmptyCharset, Serialization(String).
• neith-tls (~3,627 lines) — TLS 1.3 / secure-channel layer built on rustls. The crate additionally contains a Noise-protocol-style secure channel whose symmetric primitives are documented in source as simulated for portability (the structure mirrors the real protocol; this is explicitly stated, not a hidden stub).

hal Workspace — Hardware Abstraction Layer#

The hal workspace is the portability layer between Neith's engine code and the physical hardware it runs on. Every platform API difference — GPU backends, audio drivers, input event formats, camera capture APIs — is absorbed here. Above the HAL, all code is platform-agnostic; below it, platform-specific backend implementations handle the details. libs/neith/hal/Cargo.toml pins cpal 0.15, rustls, bitflags, sha2, and aes-gcm. The workspace contains seven crates.

neith-gpu — GPU Abstraction#

neith-gpu is the most critical crate in the HAL workspace: all rendering code in Neith is written against the GpuDevice trait defined here, and never against a concrete backend. Switching the backend (Vulkan → Metal, for example) requires only changing the Backend variant passed at device initialization, not rewriting any rendering code.

Source: hal/crates/neith-gpu/src/lib.rs (~1,566 lines). A self-contained GPU abstraction — it defines its own backend, handle, and descriptor types rather than wrapping wgpu.

The GpuDevice trait is the central abstraction. Concrete backends implement it; renderer crates call it. The key enums, handle newtypes, and descriptor structs below define the full vocabulary of the GPU API:

• Backend — Vulkan, Metal, DirectX12, WebGPU, Software.
• DeviceType — Integrated, Discrete, Virtual (plus further variants).
• Vendor — GPU vendor identification.
• ShaderStage, ShaderSource.
• MemoryLocation, AllocationStrategy.
• CommandBufferState, Command.
• LoadOp, StoreOp, ImageLayout.
• TextureFormat.
• PrimitiveTopology, CullMode, FrontFace, PolygonMode.
• BlendFactor, BlendOp (Add, Subtract, ReverseSubtract, Min, Max).
• DescriptorType, QueueFamily, PipelineVariant, FenceState (Unsignaled, Signaled).

All GPU resources are referenced via opaque integer handle newtypes. This prevents accidental mixing of handle types (e.g. passing a ShaderModuleHandle where a PipelineHandle is expected) at compile time. The full set: DeviceId(u32), ShaderModuleHandle(u64), AllocationHandle(u64), CommandBufferHandle(u64), CommandPoolHandle(u64), RenderPassHandle(u64), PipelineHandle(u64), PipelineLayoutHandle(u64), DescriptorSetHandle(u64), DescriptorLayoutHandle(u64), QueueHandle(u64), FenceHandle(u64), SemaphoreHandle(u64).

Descriptor / resource structs include DriverInfo, GpuDeviceInfo, GpuCapabilities, ShaderModule, AllocationRequest, Allocation, VmaAllocator (a VMA-style suballocator with allocate(req: AllocationRequest) -> GpuResult<Allocation>), CommandBuffer, CommandPool, AttachmentDesc, RenderPassDesc, RenderPass, BlendState, GraphicsPipelineDesc, ComputePipelineDesc, Pipeline, DescriptorBinding, DescriptorLayout, DescriptorSet, PipelineLayout, SubmitInfo, Queue, Fence.

The device interface is the GpuDevice trait (Send + Sync). Concrete backends provide a struct that implements this trait; renderer code holds Arc<dyn GpuDevice> and calls only these methods:

pub trait GpuDevice: Send + Sync {
    fn id(&self) -> DeviceId;
    fn info(&self) -> &GpuDeviceInfo;
    fn capabilities(&self) -> &GpuCapabilities;
    fn backend(&self) -> Backend;
    fn allocator(&self) -> &VmaAllocator;
    fn create_shader_module(&self, source: ShaderSource, stage: ShaderStage, entry_point: &str) -> GpuResult<ShaderModule>;
    fn create_command_pool(&self, family: QueueFamily) -> GpuResult<CommandPool>;
    fn create_render_pass(&self, desc: RenderPassDesc) -> GpuResult<RenderPass>;
    fn create_graphics_pipeline(&self, desc: GraphicsPipelineDesc) -> GpuResult<Pipeline>;
    fn create_compute_pipeline(&self, desc: ComputePipelineDesc) -> GpuResult<Pipeline>;
    fn create_descriptor_layout(&self, bindings: Vec<DescriptorBinding>) -> GpuResult<DescriptorLayout>;
    fn create_descriptor_set(&self, layout: &DescriptorLayout) -> GpuResult<DescriptorSet>;
    fn create_pipeline_layout(&self, desc_layouts: Vec<DescriptorLayoutHandle>, push_constants: Vec<(ShaderStage, u32, u32)>) -> GpuResult<PipelineLayout>;
    fn create_fence(&self, signaled: bool) -> GpuResult<Fence>;
    fn create_semaphore(&self, kind: SemaphoreKind) -> GpuResult<Semaphore>;
    fn graphics_queue(&self) -> Option<&Queue>;
    fn compute_queue(&self) -> Option<&Queue>;
    fn transfer_queue(&self) -> Option<&Queue>;
    fn profiler(&self) -> &GpuProfiler;
    fn wait_idle(&self) -> GpuResult<()>;
}

A GpuInstance enumerates devices: enumerate_devices(&self) -> &[Arc<dyn GpuDevice>]. GpuError is the failure type (with GpuResult<T> alias) — variants include NoDevicesFound, DeviceNotFound(DeviceId), UnsupportedBackend(Backend), ShaderCompilation(String), OutOfMemory { requested, available }, NotRecording, NotExecutable, SubmissionFailed(String), SyncTimeout(u64), FeatureNotSupported(String), InvalidHandle, PipelineLayoutMismatch, and a descriptor-set out-of-bounds variant.

Other HAL crates#

The remaining six HAL crates follow the same pattern as neith-gpu: they define a platform-agnostic trait or type set, with platform-specific backends hidden behind it. Their sizes reflect their implementation scope:

• neith-audio-hal (~1,301 lines) — audio device streams over cpal (CpalBackend); device enumeration and stream management.
• neith-input (~3,336 lines, two source files) — unified input event abstraction across keyboard, mouse, gamepad, touch and XR sources.
• neith-sensor (~671 lines) — IMU / sensor abstraction.
• neith-camera (~1,445 lines) — camera capture abstraction.
• neith-net-hal (~1,641 lines) — network-interface HAL.
• neith-storage (~1,586 lines) — async file I/O and storage abstraction.

net Workspace — Networking Stack#

The net workspace provides game-optimized networking that standard TCP/HTTP libraries cannot deliver. Game networking requires sub-20ms latency, reliable delivery without head-of-line blocking, lag compensation, and delta compression. @neith/net addresses all of these. libs/neith/net/Cargo.toml pins hmac, sha1, aes, ctr, and digest. The workspace contains four crates, each targeting a different layer of the network stack.

• neith-transport (~1,533 lines) — reliable-UDP transport: acknowledgement, retransmission, ordered/unordered channels, congestion control.
• neith-game-net (~1,422 lines) — game networking: client-side prediction, server reconciliation, snapshot interpolation, lag compensation, delta compression, interest management, RPC.
• neith-webrtc (~4,007 lines) — WebRTC data channels and media, including a STUN implementation.
• neith-http (~4,965 lines) — HTTP client/server stack.

renderer Workspace — Rendering, Physics, ECS, Scripting#

The renderer workspace is the largest and most complex workspace in Neith. Its 16 crates implement everything needed for a frame: the render graph that orchestrates pass ordering, the physically-based rendering pipeline, global illumination, post-processing, and the supporting runtime systems (physics, ECS, audio, scripting, animation) that determine what to render each frame.

libs/neith/renderer/Cargo.toml is a 16-member workspace. It pins bitflags (features = ["serde"]), smallvec, slotmap, indexmap, ahash, notify (file watching for hot-reload), petgraph, and bytemuck.

neith-render-graph — Frame Graph#

The frame graph is the central coordination mechanism for the entire rendering pipeline. Rather than calling GPU commands imperatively, renderer code declares passes and their resource dependencies as nodes in a directed acyclic graph. The frame graph compiler then automatically determines execution order (via Kahn topological sort), inserts GPU pipeline barriers, and aliases transient resources to minimize GPU memory usage. The result is that renderer crates never need to write manual synchronization.

Source: renderer/crates/neith-render-graph/src/ (22 files, ~7,256 lines). A production-quality frame graph. Modules (each mapped to a build task in the crate's own doc comment): graph (builder + compiled graph), lifetime (resource lifetime management), compiler + compiler::ordering (Kahn topological sort for pass ordering), aliasing (resource aliasing / memory reuse), async_compute, transient, conditional (conditional passes, FeatureFlags), debug (visualization), serial (JSON / msgpack serialization), multiview (VR stereo), tiled (tile-based rendering), profiler (GPU + CPU timings), dynamic_res (dynamic resolution scaling), hot_reload, fragment_density (fragment density map attachments), vulkan_mobile, resource (TextureDesc, TextureFormat), pass (TextureAccess). The builder entry point is RenderGraphBuilder::new(name) with add_texture, add_graphics_pass, etc.

neith-physics — Multi-Physics Simulation#

neith-physics is a fully self-contained physics engine with no dependency on rapier3d or any other third-party physics library. It implements its own sweep-and-prune/BVH broadphase, GJK/EPA narrowphase, and iterative constraint solver from first principles. This gives Neith complete control over the physics simulation step — including deterministic reproduction, custom constraint types, and tight integration with the ECS component model — without being limited by rapier3d's API surface.

Source: renderer/crates/neith-physics/src/ (12 files, ~10,062 lines). Modules: rigid_body, character, vehicle, ragdoll, cloth, soft_body, fluid, destruction, math, collision_merge, tilemap2d.

Math types (math module) are plain arrays: Vec3 = [f32; 3], Vec4 = [f32; 4], Mat3 = [[f32; 3]; 3], Quat = [f32; 4], plus an Aabb struct.

rigid_body module key types:

• CollisionShape enum — Sphere { r: f32 }, Box { half: Vec3 }, Capsule { r: f32, h: f32 }, ConvexHull { verts: Vec<Vec3> }, TriangleMesh { verts: Vec<Vec3>, tris: Vec<[usize; 3]> }.
• CompoundShape — a collection of shapes with local transforms.
• CollisionFilter { ... } — new(layer: u32, mask: u32); layer/mask filtering.
• PhysicsMaterial — restitution / friction material parameters.
• RigidBody — fields pos: Vec3, rot: Quat, vel: Vec3, ang_vel: Vec3, mass: f32, inv_mass: f32, inertia_tensor_inv: Mat3, restitution: f32 (default 0.3), friction: f32 (default 0.5), force_accum: Vec3, torque_accum: Vec3. RigidBody::new(pos, mass) derives inv_mass (0.0 when mass <= 0.0, i.e. a static body) and a diagonal inverse inertia tensor. Methods apply_force(f: Vec3), apply_impulse(impulse: Vec3, contact_point: Vec3).
• JointType enum — Fixed; Hinge { axis: Vec3, limits: Option<[f32; 2]> }; Slider { axis: Vec3, limits: Option<[f32; 2]> }; Ball; Spring { rest_len: f32, stiffness: f32, damping: f32 }.
• Joint, MotorConstraint, BreakableJoint (new(joint, max_force)).
• SapBroadphase — sweep-and-prune broadphase; BvhTree / BvhNode — a BVH broadphase alternative.
• Narrowphase: gjk_closest_points(...), epa_penetration(...), generate_contacts(...), with ContactInfo, ContactManifold, ManifoldCache.
• SleepState + update_sleep(...) + wake_body(...) — island sleeping.
• Continuous collision detection: ccd_sphere_sphere(...), ccd_aabb_aabb(...).
• InterpolatedTransform — physics-to-render interpolation.
• PhysicsWorld — the simulation container: PhysicsWorld::new(), add_body(body: RigidBody, shape: Option<CollisionShape>) -> usize, step(dt: f32).

Other renderer-workspace crates#

The remaining renderer crates each own a specific sub-pipeline. The source sizes below give a rough sense of implementation depth; all are real, substantial crates with domain-specific algorithms (not CRUD wrappers).

ui Workspace — GPU-Accelerated UI Toolkit#

The ui workspace provides a self-contained, GPU-accelerated UI toolkit independent of any web-technology stack. libs/neith/ui/Cargo.toml pins accesskit 0.24 (for accessibility tree integration) and bitflags. The six crates form a layered stack — neith-render2d and neith-text are the rendering foundation, neith-layout positions elements, neith-widgets provides controls, neith-animation handles motion, and neith-theme provides the design token system.

Build and Nx Integration#

Every Cargo workspace has a project.json exposing Nx targets via the nx:run-commands executor. This lets the monorepo's Nx build graph treat Rust crates as first-class projects alongside TypeScript packages — dependency tracking, affected builds, and caching all work uniformly. The core workspace's project.json is representative of the pattern; every other workspace follows the same four-target structure:

Each workspace pins its toolchain via a rust-toolchain.toml file. The standalone TypeScript packages instead carry a tsconfig.json, a Vitest config (vitest.config.ts) where tests exist, and a tsup build config where they ship a bundle (e.g. cloud/tsup.config.ts).

Because the worktree layout can produce duplicate Nx project names (each worktree registers the same projects), Nx sometimes fails with a duplicate project error. In that situation, bypass Nx entirely and run the Cargo commands directly (cargo build/cargo test/cargo clippy) — the commands above work identically when run from the workspace directory.

Sovereignty Invariant#

Neith is the lowest layer of the Oshun stack. The Rust workspaces import nothing from other Oshun domains or libs/shared/ — they depend only on third-party crates pinned in each workspace's [workspace.dependencies]. This keeps every Neith crate independently buildable and embeddable outside the Oshun monorepo.

The invariant is enforced architecturally, not just by convention: because libs/neith/ is a set of isolated Cargo workspaces, any attempt to add a path-dependency on another Oshun domain would require adding it to the Cargo manifest — which would be immediately visible in code review.

Downstream domains (Maya's game engine and metaverse layer, Bellona's external-engine export bridges, and others) consume Neith crates; Neith never depends on them. The TypeScript integration packages (@neith/integration-maya, @neith/integration-bellona, etc.) provide the Neith → domain boundary for TypeScript consumers; they are TypeScript libraries, not Rust crates, and do not violate the sovereignty invariant.

Acceptance Criteria#

Every change to a Neith crate must pass all five criteria below before merging. These checks are automated via the Nx lint, build, and test targets, but the final review must verify criteria 4 and 5 manually.

A change to a Neith crate is acceptable when:

1. The crate compiles under its workspace toolchain (cargo build --manifest-path libs/neith/<workspace>/Cargo.toml).
2. cargo clippy -- -D warnings is clean for the workspace.
3. The crate's own #[test] modules pass (cargo test); the foundational crates carry inline mod tests exercising domain correctness (priority ordering, NBF round-trips, metric arithmetic, GJK/EPA contact generation, etc.).
4. New public types are added to the relevant crate lib.rs re-export block so the workspace surface stays discoverable.
5. The sovereignty invariant holds — no dependency on other Oshun domains or libs/shared/.

Planned Surface#

The Neith feature inventory (features.md) and TODO phases describe further sovereign systems that extend beyond what is specified in this document.

Where directories already exist under libs/neith/ — for example audio-runtime/, browser/, linux/, ai-runtime/, embedded/, vr-os/, and the creative-tool and audio-suite workspaces — those workspaces are present in source and inventoried in the workspace tables above. Their internal type surfaces are described in features.md but not enumerated in full here.

Items in features.md for which no directory exists under libs/neith/ — including the @neith/os-kernel, @neith/drivers, @neith/fs, and @neith/pkg operating-system packages mentioned in Phase 45, and the named packages of the Phase 132–174 sovereignty-closure roadmap that have no corresponding folder — are (planned) and are not specified here. Any such item added to the codebase should be inventoried in the workspace tables above and, if it is part of the foundational six workspaces, have its public type surface documented in this file.