Nexus Kernel Architecture¶

Kernel architecture SSOT. Keep small and precise — prefer inplace edits over additions. Delegate details to federation-memo.md and data-storage-matrix.md.

1. Design Philosophy¶

NexusFS follows an OS-inspired layered architecture.

┌──────────────────────────────────────────────────────────────┐
│  SERVICES (user space)                                       │
│  Installable/removable. ReBAC, Auth, Agents, Scheduler, etc. │
└──────────────────────────────────────────────────────────────┘
                          ↓ protocol interface
┌──────────────────────────────────────────────────────────────┐
│  KERNEL                                                      │
│  Minimal compilable unit. VFS, MetastoreABC,                 │
│  ObjectStoreABC interface definitions.                       │
└──────────────────────────────────────────────────────────────┘
                          ↓ dependency injection
┌──────────────────────────────────────────────────────────────┐
│  DRIVERS                                                     │
│  Pluggable at startup. redb, S3, LocalDisk, gRPC, etc.       │
└──────────────────────────────────────────────────────────────┘

Interface Taxonomy¶

Every kernel interface belongs to exactly one of four categories:

Tier 1 is the only user-facing interface. Tier 3 is for trusted kernel modules (federation resolvers, ACP) — analogous to Linux EXPORT_SYMBOL.

Swap Tiers¶

Follows Linux's monolithic kernel model, not microkernel:

Invariant: Services depend on kernel interfaces, never the reverse. The kernel operates with zero services loaded. Kernel code (core/nexus_fs.py) has zero reads of service containers — all service wiring flows through ServiceRegistry (nx.service("name")), factory-injected closures (functools.partial), or KernelDispatch hooks. Services flow through sys_setattr("/__sys__/services/X") — factory uses the same syscall API as runtime callers (factory = first user).

Drivers are mounted at runtime via sys_setattr(entry_type=DT_MOUNT, backend=...), unmounted via rmdir. MetastoreABC is the only startup-time driver (sole kernel init param). Other drivers are mounted post-init by factory or at runtime.

Service Lifecycle¶

factory/ acts as the init system (like systemd): creates selected services and injects them via DI. DeploymentProfile gates which bricks are constructed (see §7).

Factory boot sequence:

1. create_nexus_services() — _boot_pre_kernel_services() + _boot_independent_bricks() + _boot_dependent_bricks()
2. NexusFS() constructor — Instantiate kernel primitives (no I/O, router passed directly)
3. _wire_services() — Wire topology, boot post-kernel services, enlist into ServiceRegistry
4. _initialize_services() — Register VFS hooks, IPC adapter bind

See factory/orchestrator.py for implementation.

Service Lifecycle Protocols¶

One-dimension model: the only user-facing lifecycle dimension is background vs on-demand (BackgroundService protocol). Hook management uses duck-typed hook_spec() — the kernel auto-captures hooks via hasattr(instance, 'hook_spec') at enlist() time.

One-click contract: implement protocol / hook_spec() → ServiceRegistry.enlist() → kernel handles the rest. ServiceRegistry (kernel-owned, lifecycle integrated) scans the registry and auto-calls the appropriate methods during NexusFS.bootstrap() / NexusFS.close(). Rust ServiceRegistry calls start()/stop() on registered services during bootstrap/shutdown.

swap_service() supports all services. Unified path: refcount drain → unhook old → replace → rehook new.

AgentRegistry (kernel::core::agents::registry::AgentRegistry): kernel SSOT for agent lifecycle. PID allocation, parent/child tree, signal semantics (SIGTERM / SIGSTOP / SIGCONT / SIGKILL / SIGUSR1), transition validation (VALID_AGENT_TRANSITIONS folded into AgentState::can_transition_to), and per-PID condvar wake-ups all live here. Python callers reach the registry through the agent_registry getter on the Rust kernel handle — kernel.agent_registry.spawn(...) / signal(...) / get(...) return [PyAgentDescriptor] instances exposed under AgentDescriptor field names mirror contracts/process_types.py:AgentDescriptor. The IPC provisioner is late-bound through set_provisioner(callable); the registry stores the reference and agent_registration.py awaits its async provision(...) coroutine on the asyncio loop.

The kernel-side AgentStatusResolver (procfs view at /{zone}/proc/{pid}/status) reads the same Arc<AgentRegistry>, so every spawn / signal is visible to the procfs layer without a dual-write step. Profiles without agent workloads (REMOTE) skip the getter; the kernel boots the same way either path.

Kernel DI patterns (two mechanisms; the kernel reaches services only via ServiceRegistry lookups or factory-injected closures):

"Kernel knows" follows the Linux LSM pattern: kernel declares a default (None), factory overrides at link-time. Kernel modules import only from contracts/, lib/, and other kernel-tier packages.

Permission enforcement is a kernel primitive. The permission gate runs before NativeInterceptHook dispatch on every sys_* call with OperationContext. Pluggable PermissionProvider trait; no provider registered = zero overhead (~1ns AtomicBool).

Zone identity: self._zone_id = ROOT_ZONE_ID — kernel namespace partition (analogous to Linux sb->s_dev). VFSRouter (Rust kernel primitive) canonicalizes all paths to /{zone_id}/{path} for zone-aware LPM routing. Standalone: always "root". Federation: set at link time. All primitives (LockManager, FileEvent) receive canonical paths — zone handling is VFSRouter's responsibility, not theirs.

Source of truth: contracts/protocols/service_lifecycle.py

Entry Point: connect()¶

connect(config=...) is the mode-dispatcher factory function — the single entry point for all Nexus users. It auto-detects deployment mode (standalone/remote/federation), bootstraps the appropriate stack, and returns NexusFilesystem.

from nexus.sdk import connect
nx = connect()                    # auto-detect from env/config
nx = connect(config={"profile": "remote", "url": "http://..."})

Linux analogue: the boot sequence that selects rootfs and mounts it (mount_root() in init/do_mounts.c). After connect() returns, you have a usable filesystem. All three modes return the same NexusFilesystem contract — clients never need to know which mode is running.

Not DI — it's the user-facing entry point. The factory/DI machinery is internal.

2. User Contract — Syscall Interface¶

Category: User Contract (↑) | Audience: Users, AI, agents | Package: contracts.filesystem, core.nexus_fs

2.1 NexusFilesystem — Published Contract¶

The published user-facing contract is NexusFilesystem (Protocol, in contracts/filesystem/):

Relationship: POSIX spec (contract) vs Linux kernel (implementation) — clients program against the contract, kernel implements it.

2.2 Kernel Syscalls — POSIX-Aligned, Path-Addressed¶

NexusFS is the kernel implementation of NexusFilesystem. It wires primitives (§4) into user-facing operations. NexusFS contains no service business logic.

All kernel methods are synchronous. Blocking waits (advisory locks, stream reads, sys_watch) use Rust Condvar. Async exists only at the transport layer (gRPC, HTTP).

Kernel syscalls, all POSIX-aligned, all path-addressed:

* Vectored syscalls: sys_read, sys_write, and sys_unlink accept a slice of request structs (&[ReadRequest], &[WriteRequest], &[UnlinkRequest]) and return Vec<Result<Sys*Result, KernelError>> — one result per request, positionally matched. reqs.len() == 1 takes a zero-overhead fast path; reqs.len() > 1 takes the batch path (rayon parallel read, sorted-lock write, sequential unlink). Per-item errors are isolated. The former _read_batch / _write_batch / _delete_batch internal methods and the skip_authz hack are deleted — the vectored signatures subsume all batch functionality with per-item permission enforcement.

sys_setattr is the universal creation/management syscall: mkdir = sys_setattr(entry_type=DT_DIR), create = sys_setattr(entry_type=DT_REG) (upsert — creates regular file if absent, updates metadata if present; accepts content_id, size, version, created_at_ms, owner_id), mount = sys_setattr(entry_type=DT_MOUNT, backend=...), umount = rmdir on DT_MOUNT path, symlink = sys_setattr(entry_type=DT_LINK, link_target=...).

Lock operations are consolidated into two syscalls (POSIX fcntl(F_SETLK) pattern): - sys_lock(path, lock_id=None) — acquire (lock_id=None) or extend TTL (lock_id=existing) - sys_unlock(path, lock_id=None, force=False) — release by lock_id or force-release all holders - Lock state: sys_stat(path, include_lock=True) — zero cost when False (default) - Lock listing: sys_readdir("/__sys__/locks/") — virtual namespace (like /proc/locks) /__sys__/ paths are kernel management operations (not filesystem metadata): sys_setattr("/__sys__/services/X", service=inst) registers, sys_unlink("/__sys__/services/X") unregisters.

Primitive usage pattern:

• Mutating syscalls (write, unlink, rename, copy): full pipeline — VFSRouter → VFSLock → KernelDispatch (3-phase) → Metastore → FileEvent
• DT_PIPE / DT_STREAM I/O: the routed metastore detects entry_type early in sys_read/sys_write and dispatches to PipeManager/StreamManager inline — no VFS lock, no metastore update, no observer dispatch (matching Linux write(2) on a pipe not triggering inotify)
• DT_LINK: route() follows the link target one hop with self-loop rejection (§4.4); hooks fire on the resolved target path so audit and access checks behave identically to a direct write
• Read: same pipeline minus FileEvent (reads are not mutations)
• Read-only metadata (stat, access, readdir, is_directory): direct Metastore lookup only — no routing, locking, or dispatch
• setattr: Metastore-only. DT_REG upsert (creates if absent, updates metadata if present). Tier 2 mkdir adds routing + hooks

See syscall-design.md for the full per-syscall primitive matrix.

2.3 Tier 2 Convenience Methods¶

Tier 2 methods compose Tier 1 syscalls — concrete implementations in NexusFilesystem:

The HDFS half bypasses path resolution and metadata lookup — CAS is a driver detail. Like HDFS separates ClientProtocol (NameNode, path-based) from DataTransferProtocol (DataNode, block-based). The metadata layer above ensures etag ownership and zone isolation.

The HDFS half is kernel-internal — see §2.5 for the contract. Service-tier callers go through sys_read(path) with optional content_hash verification; features that need stable historical bytes express them as paths (workspace snapshots, version history) and read those paths through the syscall surface.

Kernel-managed metadata side effects (POSIX generic_write_end pattern): kernel updates mtime, size, version, etag in VFS lock after backend.write_content(). Drivers only manage content. Consistency is zone-level (configured at metastore layer), not per-write.

2.4 VFS Dispatch (KernelDispatch)¶

The kernel provides callback-based dispatch at 6 VFS operation points (read, write, delete, rename, mkdir, copy) plus driver lifecycle events (mount, unmount). These are kernel-owned callback lists (implemented by KernelDispatch, §4) that any authorized caller populates.

Three-phase dispatch per VFS operation:

Driver lifecycle hooks:

Mount/unmount hooks are dispatched by DriverLifecycleCoordinator (§4) via KernelDispatch. Backends declare mount hooks via hook_spec() (same pattern as VFS hooks). CASAddressingEngine uses on_mount for mount-time logging.

PRE-DISPATCH: VFSPathResolver instances checked in order; first match handles entire operation. Each resolver owns its own permission semantics.

INTERCEPT: Per-operation VFS*Hook protocols. Hooks receive a typed context dataclass, can modify context or abort. POST hooks support sync and async (classified by Rust HookRegistry). Audit is a factory-registered interceptor, not a kernel built-in.

OBSERVE: VFSObserver instances receive frozen FileEvent (§4.3) on all mutations. Strictly fire-and-forget — failures never abort the syscall. Observers needing causal ordering belong in INTERCEPT post-hooks, not OBSERVE.

Hook protocols and context dataclasses are defined in contracts/vfs_hooks.py (tier-neutral). Concrete implementations live in services/hooks/.

Registration API: Each phase has a symmetric register_*() / unregister_*() pair — runtime-callable by any authorized caller.

2.4.1 The 4 Dispatch Contracts¶

Each dispatch phase is a formal contract between the kernel and its callers. These contracts define ordering, error semantics, and performance guarantees.

Ordering guarantee: RESOLVE > Permission Gate > INTERCEPT PRE > HAL I/O > INTERCEPT POST > OBSERVE. OBSERVE always fires after VFS lock release (like Linux inotify after i_rwsem).

Permission Gate (Linux analogue: security_inode_permission()): Kernel-level permission check called before INTERCEPT PRE on every sys_* with OperationContext. Decision cascade (short-circuits on first decisive step): /__sys__/ path bypass → is_system bypass → no-provider fast-path (~1ns AtomicBool) → lease cache hit (~100-200ns DashMap per depth level) → admin bypass → zone_perms federation grant → PermissionProvider.check(). Pluggable PermissionProvider trait registered once at boot; implementations live in the services tier. PermissionLeaseCache: inheritance-aware (path, agent_id) → TTL DashMap cache; parent directory lease covers child files. Permission enum: Read, Write, Traverse. Source of truth: rust/kernel/src/kernel/dispatch.rs (gate), rust/kernel/src/core/permission_cache.rs (lease cache), rust/kernel/src/core/dispatch/mod.rs (trait + enums).

Why separate the Permission Gate from INTERCEPT PRE? The gate runs in ~100-200ns pure Rust (AtomicBool + DashMap lease cache); full ReBAC evaluation in INTERCEPT PRE requires metadata access. Separating them lets cached grants bypass INTERCEPT entirely.

Per-syscall dispatch matrix (source of truth: io.rs):

Zero-overhead invariant: Empty callback list = no-op dispatch = zero overhead when no services are registered.

Python-to-kernel boundary: Python reaches the Rust kernel via gRPC to the nexus-cluster process. Each sys_* call is one gRPC round-trip. Inside the Rust process, pillar calls, hook dispatch, and service lifecycle are all pure Rust with zero FFI crossings.

2.5 Mediation Principle¶

Services access HAL only through syscalls. For mutating syscalls the pipeline is: PRE-DISPATCH → route → permission gate → INTERCEPT pre → lock → HAL I/O → unlock → INTERCEPT post → OBSERVE. See syscall-design.md for the full per-syscall flow.

The MetaStore pillar (§3.A.1) and the ObjectStore pillar (§3.A.2) are HAL contracts the kernel implements over. Reaching them directly — MetaStore.list, MetaStore.put, Arc<dyn ObjectStore>::read_content etc. — is a kernel-internal capability. Service-tier callers (Rust peer crates in rust/services/, rust/raft/, rust/transport/, rust/backends/; Python bricks in src/nexus/bricks/, src/nexus/services/, src/nexus/server/) reach the same state through the §2.2 syscall surface (paths) or the §4 dispatch hook ABI (observers, resolvers, hooks).

The §2.3 Tier 2 HDFS half (hash-addressed read_content / write_content / streaming) is one such kernel-internal surface — used by federation cross-node fetch (KernelBlobFetcher in rust/raft/) and by other Rust kernel-internal modules that need content-hash addressing for replication, dedup, or storage GC. Service-tier features that want hash-addressed semantics (workspace versioning, transactional snapshots, etc.) express them as paths and read through sys_read(path), optionally verifying the served content_hash matches an expected value.

3. HAL — Storage HAL & Control-Plane HAL¶

Category: HAL — Driver Contract (↓) | Audience: Driver implementors

The kernel exposes two HAL flavors:

• §3.A Storage HAL — persistent-data driver contracts. The 3 ABC pillars (Metastore, ObjectStore, CacheStore) plus the Transport × Addressing composition that decomposes ObjectStore.
• §3.B Control-Plane HAL — runtime DI surfaces. Capabilities the kernel needs but does not own: distributed namespace topology (DistributedCoordinator) and backend instantiation (ObjectStoreProvider).

Both flavors live under rust/kernel/src/: abc/ for the §3.A pillars, hal/ for §3.B.

3.A Storage HAL — ABC pillars¶

NexusFS abstracts storage by Capability (access pattern + consistency guarantee), not by domain or implementation.

Rust naming note: the Rust trait MetaStore (two-word PascalCase) matches ObjectStore / CacheStore for visual symmetry across the three ABC pillars. The Python ABC stays MetastoreABC (one word) — the Python tier is on a sunset path, so the Rust trait carries the forward-looking name.

Rust-side strict layout: kernel/src/abc/ contains exactly the 3 §3.A ABC pillar trait files. kernel/src/hal/ contains the §3.B Control-Plane HAL trait files (DistributedCoordinator, ObjectStoreProvider). Kernel primitives (§4) live in kernel/src/core/ as concrete types. Connector-backend protocol extensions (e.g. LlmStreamingBackend) live in rust/backends/; the matching trait DECLARATION stays at the kernel boundary because ObjectStore::as_llm_streaming() returns Option<&dyn LlmStreamingBackend> in the kernel ABC. Concrete impls (OpenAIBackend, AnthropicBackend) live in rust/backends/transports/api/ai/. Transport-layer abstractions (PeerBlobClient, TOFU trust store) live in the tier-neutral rust/lib/ crate's transport_primitives module. Directory layout enforces the three-way split: abc/ is for §3.A pillars, hal/ is for §3.B DI surfaces, core/ is for primitives.

Orthogonality: Between pillars = different query patterns. Within pillars = interchangeable drivers (deployment-time config). See data-storage-matrix.md.

Kernel self-inclusiveness: Kernel boots with 1 pillar (Metastore); ObjectStore mounts post-init. The kernel's own data needs are intentionally minimal — O(1) KV with ordered prefix scan over zone-tagged FileMetadata rows. Higher-level shapes (JOINs, FK, vector search, TTL, pub/sub) live in the service layer, mirroring Linux's split: kernel defines VFS + block-device interfaces while filesystems ship as separate modules.

3.A.1 MetastoreABC — Inode Layer¶

Linux analogue: struct inode_operations

The typed contract between VFS and storage. Without it, the kernel cannot describe files. Operations: O(1) KV (get/put/delete), ordered prefix scan (list), batch ops, implicit directory detection. System config stored under /__sys__/ prefix.

Data type: FileMetadata — path, backend_name, etag, size, version, zone_id, owner_id, timestamps, mime_type. Every row carries a zone_id — the kernel namespace partition identifier (analogous to Linux sb->s_dev), which federation extends with Raft consensus groups while the kernel owns the concept. owner_id is the kernel's posix_uid — consumed by PermissionEnforcerProtocol.check_owner() for O(1) DAC before service-layer hooks run. Audit trail (who created a file) lives in the service layer (VersionRecorder); the kernel inode keeps the steady-state fields only.

Rust naming note: the Rust trait MetaStore (two-word PascalCase) matches ObjectStore / CacheStore for visual symmetry across the three ABC pillars. The Python ABC stays MetastoreABC (one word) — the Python tier is on a sunset path, so the Rust trait carries the forward-looking name.

3.A.2 ObjectStoreABC (= Backend) — Blob I/O¶

Linux analogue: struct file_operations

CAS-addressed blob storage: read/write/delete by etag (content hash), plus streaming variants. Directory ops (mkdir/rmdir/list_dir) for backends that support them. Rename is optional (capability-dependent).

3.A.3 CacheStoreABC — Ephemeral KV + Pub/Sub (Optional)¶

Linux analogue: /dev/shm + message bus

The only optional HAL pillar. Kernel defines the ABC (ephemeral KV + pub/sub); services consume it for caching, event fan-out, and session storage. Drivers: Dragonfly/Redis (production), InMemoryCacheStore (dev).

Graceful degradation: NullCacheStore (no-op) is the default. Without a real CacheStore, EventBus disables, permission/tiger caches fall back to RecordStore, and sessions stay in RecordStore. No kernel functionality is lost.

3.A.4 Dual-Axis ABC Architecture¶

Two independent ABC axes, composed via DI:

• Data ABCs (this section): WHERE is data stored? → 3 kernel pillars by storage capability
• Ops ABCs (§5.3): WHAT can users/agents DO? → 40+ scenario domains by ops affinity

A concrete class sits at the intersection: e.g. ReBACManager implements PermissionProtocol (Ops) and internally uses RecordStoreABC (Data). See ops-scenario-matrix.md for full proof.

3.A.5 Transport × Addressing Composition¶

Linux analogue: Block device driver (Transport) × filesystem (Addressing)

ObjectStoreABC backends decompose into two orthogonal axes: Transport (WHERE — raw key→bytes I/O) and Addressing Engine (HOW — CAS or Path). Every backend, including external API connectors, is a Transport composed with an addressing engine. REST APIs are filesystems: GET = fetch, PUT = store, DELETE = remove.

DT_EXTERNAL_STORAGE (entry_type=5): Mount-time detection via ConnectorRegistry.category for OAuth APIs and CLI tools.

See backend-architecture.md §2 for the full composition matrix and Transport protocol. See connector-transport-matrix.md for per-connector details.

3.B Control-Plane HAL — Runtime DI Surfaces¶

Storage HAL (§3.A) is the persistent-data flavor of HAL; Control-Plane HAL is the in-memory coordination flavor. The kernel calls a trait method, an external crate's impl handles the actual work. Same DI shape on both sides: trait declared in kernel/src/hal/, concrete impl in the owner crate, an Arc<dyn Trait> slot the process boots before any syscall fires.

3.B.1 DistributedCoordinator¶

Linux analogue: struct super_operations — the abstraction the VFS layer talks through to reach any concrete filesystem driver without naming the driver type. DistributedCoordinator plays the same role for distributed namespace topology: kernel-side syscalls dispatch through kernel.distributed_coordinator() instead of naming nexus_raft::* types directly.

11 methods, four families:

• Introspection (2): list_zones, cluster_info. ClusterInfo carries leader_id, term, voter_count, witness_count, links_count, commit_index, applied index — typed Rust struct, native Rust field access on the caller side.
• Zone lifecycle (3): create_zone, remove_zone (cascade-unmounts cross-zone references first; force=true honors the POSIX-style unlink while i_links > 0 bypass), join_zone (as_learner=true for non-voter membership).
• Mount wiring (2): wire_mount / unwire_mount — leader-side fast-path. The apply-cb on the state machine is the correctness guarantee, this pair is the optimization.
• Share registry (2): share_zone (atomic create-zone + copy-subtree + register-share), lookup_share returns a ShareInfo (zone_id + remote-path metadata).
• Per-zone dispatch (2): metastore_for_zone returns Arc<dyn MetaStore> backed by Raft state machine; locks_for_zone returns Arc<dyn Locks> that replicates lock acquisition via Command::AcquireLock.

Boot-time setup is a module-level install() function — a once-per-process hook that wires the slot and folds in DI plumbing (blob-fetcher slot stash) that lives outside the runtime surface. Same shape as transport::python::install_transport_wiring.

Naming convention follows the §3.A pillars (MetaStore, ObjectStore, CacheStore): the trait name describes the capability — distributed-namespace coordination — rather than the implementation (Raft) or a GoF role (Provider / Manager).

3.B.2 ObjectStoreProvider¶

Single method: build(args: &ObjectStoreProviderArgs) -> Result<ObjectStoreBuildResult, String>. ObjectStoreBuildResult bundles Option<Arc<dyn ObjectStore>> (the backend) and Option<Arc<dyn MetaStore>> (remote metastore, for "remote" backends).

Kernel::sys_setattr("backend", …) and the mount path use this to instantiate backends through trait dispatch. Cycle break is identical to the §3.A pattern: kernel declares the trait, backends crate provides the impl, process boot wires the slot.

The trait name describes the capability ("provides ObjectStore instances"), in symmetry with DistributedCoordinator and the §3.A pillars.

4. Kernel Primitives¶

Category: Kernel Primitive (internal) | Audience: Kernel-internal | Package: core.*

Primitives mediate between user-facing syscalls and HAL drivers. Users interact with them indirectly through syscalls. See §2.2 for per-syscall usage.

4.1 Unified LockManager — I/O Lock + Advisory Lock¶

Rust LockManager (rust/kernel/src/core/lock/) unifies the kernel's two locking concerns in one primitive — sharing the path-normalisation helper, the hierarchy-aware conflict logic, and the core/lock/ module home. Constructed in Kernel::new() with a default LocalLocks advisory backend; a replicated backend swaps in via install_locks(Arc<dyn Locks>) at federation mount time (first-wins, idempotent).

See lock-architecture.md for full design. See federation-memo.md for the replicated-backend install path.

4.2 IPC Primitives — Named Pipes & Streams¶

Two-layer architecture for both: VFS metadata (inode) in MetastoreABC, data (bytes) in process heap buffer (like Linux kmalloc'd pipe buffer).

DT_PIPE (PipeManager + MemoryPipeBackend):

• PipeManager (mkpipe) — VFS named pipe lifecycle (created via sys_setattr upsert, read/write via sys_read/sys_write, destroyed via sys_unlink), per-pipe lock for MPMC safety. Reads are destructive (consumed on read).
• MemoryPipeBackend (kpipe) — Lock-free SPSC kernel primitive (kfifo analogue), no internal synchronization. Kernel manages pipe lifecycle directly. Direct MemoryPipeBackend access is kernel-internal only.

DT_STREAM (StreamManager + pluggable StreamBackend):

• StreamManager (mkstream) — VFS named stream lifecycle (same syscall surface as mkpipe). Per-stream lock for concurrent writers. Reads are non-destructive — multiple readers maintain independent byte offsets (fan-out).
• StreamBackend protocol — pluggable backing store for DT_STREAM data. io_profile determines which backend is used at creation time. Implementations: MemoryStreamBackend (in-memory, default), SharedMemoryStreamBackend (mmap shared memory, cross-process, ~1-5μs), WalStreamCore (Raft-replicated WAL, durable + distributed).

io_profile — Backend Selection via sys_setattr:

sys_setattr(path, entry_type=DT_PIPE|DT_STREAM, io_profile=...) selects the backend implementation at creation time. io_profile defaults to "memory" (in-process ring buffer); "shared_memory" creates mmap-based cross-process IPC; "wal" creates a Raft-replicated WAL stream (requires federation). Rust kernel creates the backend, registers it in PipeManager/StreamManager, and returns SHM metadata (shm_path, data_rd_fd, space_rd_fd) to Python for asyncio integration. sys_read/sys_write go through Rust PipeManager regardless of io_profile — zero Python state.

See federation-memo.md §7j for design rationale.

4.3 FileWatcher + FileEvent — File Change Notification¶

4.4 DT_LINK — Path-Internal Symlink¶

A DT_LINK is a metadata-only entry whose link_target field carries the path it points at. Path resolution treats it as a redirect: every sys_* call against a DT_LINK path resolves to the equivalent operation on the link target, with hooks firing on the resolved target path. sys_unlink removes the link without touching the target; sys_stat reports the entry as a link with its link_target filled in.

Cycle handling is bounded by the one-hop rule — if target is itself a DT_LINK, the resolver returns ELOOP rather than chaining. Self-loops (link → itself) are rejected at sys_setattr time.

Use cases:

• /proc/{pid}/agent → /agents/{name}/ (runtime back-reference to image; mirrors Linux /proc/{pid}/exe)
• /proc/{pid}/workspace/chat-with-me → /proc/{pid}/chat-with-me (workspace-anchored mailbox shortcut so agents addressing each other don't have to walk the registry)

See the sudowork integration design doc (sudowork/docs/tech/nexus-integration-architecture.md) for the A2A messaging conventions that consume DT_LINK.

5. Kernel-Authored Standards¶

Category: Kernel-Authored Standard (service-tier contract) | Audience: Services

5.1 The "Standard Plug" Principle¶

The kernel defines contracts it doesn't own — so kernel infrastructure works automatically with any service that conforms.

Linux analogies:

Nexus equivalent:

Integration mechanisms: Factory auto-discovers bricks via brick_factory.py convention (RESULT_KEY + PROTOCOL + create()), validates protocol conformance at registration, and resolves kernel dependencies via EXPORT_SYMBOL() pattern (see §1 Service Lifecycle).

5.2 RecordStoreABC — Relational Storage Standard¶

Package: storage.record_store | Service-tier interface (consumed by services, defined by kernel)

The kernel is the standards body — it defines the interface shape that forces driver implementors to provide pooling, error translation, read replica routing, WAL mode, async lazy init. Both sides (drivers and services) conform to the same interface; neither needs to know the other. The value comes from bilateral interface conformance, not from kernel providing these features directly.

5.3 Service Protocols — 40+ Scenario Domains¶

Package: contracts.protocols | Service-tier standards (defined by kernel, implemented by services)

40+ typing.Protocol classes with @runtime_checkable, organized by domain (Permission, Search, Mount, Agent, Events, Memory, Domain, Audit, Cross-Cutting).

See ops-scenario-matrix.md §2–§3 for full enumeration and affinity matching.

6. Tier-Neutral Infrastructure (contracts/, lib/)¶

Two packages sit outside the Kernel → Services → Drivers stack. Any layer may import from them; their own imports stay within contracts/ and lib/ (plus the standard library), keeping them tier-neutral leaves of the dependency graph.

Core distinction: contracts/ = what (shapes of data). lib/ = how (behavior).

Python ↔ Rust Crate Mapping¶

Both tier-neutral packages have a Rust mirror. Names match so a reader jumping between the two trees finds the same module in the same place.

rust/lib/ builds against wasm32-unknown-unknown with default features.

rust/lib/ also carries the transport_primitives module — TLS config, peer addressing, connection pooling, channel creation, the TOFU trust store, and the PeerBlobClient trait. The module sits behind the optional transport feature so WASM / pure-algo callers skip the tonic + tokio dep stack. Every peer crate that speaks raft or VFS gRPC (raft, transport, kernel through the peer-client slot) enables lib's transport feature.

6.1 Workspace composition¶

The Rust workspace splits into two Cargo artifact roles:

The Linux analogue is make bzImage: rlibs compile into the final deployment binary the same way fs/built-in.a and kernel/built-in.a link into vmlinuz. Python communicates with the kernel over gRPC (the nexus-cluster process), not FFI.

Crate role taxonomy¶

The library crates split into 5 architectural roles. Every peer crate maps to exactly one role — that is the invariant that lets the dep graph stay acyclic.

The role split makes the orthogonality invariants services ⊥ backends ⊥ raft (services and backends reach raft state through kernel.sys_* syscalls, never via Cargo dep) and kernel ⊥ raft (kernel reaches raft only through trait dispatch) read directly off the table.

Kernel crate composition¶

rust/kernel/src/kernel/ hosts the Kernel struct and its syscall implementations across per-family submodules:

Every submodule writes its methods as impl Kernel { … } blocks — Rust treats each block as a member set of the same Kernel type, so self.method_in_io() from a submodule reaches self.method_in_mod() without intermediate trait dispatch.

The split between kernel/ (syscalls) and core/ (primitives) follows the data type: §4 primitives — concrete data structures like VFSRouter, AgentRegistry, LockManager — live in core/; the syscall families that operate on them live in kernel/.

Control-Plane HAL DI surface¶

The Kernel.distributed_coordinator slot holds an Arc<dyn DistributedCoordinator> that drives every federation-aware syscall (§3.B.1). Trait surface lives in kernel::hal::distributed_coordinator; concrete impl (RaftDistributedCoordinator) lives in the raft crate at nexus_raft::distributed_coordinator. The kernel ↔ raft Cargo edge is raft → kernel — kernel reaches distributed state (ZoneManager, ZoneRaftRegistry, tokio::runtime::Handle, cross_zone_mounts reverse index) through the trait dispatch, with the coordinator owning that state.

Boot wiring:

Coordinator methods all take kernel: &Kernel so the unit-struct impl forwards into kernel-side primitives without holding back-references. The §3.B.2 ObjectStoreProvider slot uses the same pattern: trait in kernel::hal::object_store_provider, impl in backends::provider, boot hook in nexus-cluster main.

Kernel boundary — gRPC (not FFI)¶

Python communicates with the Rust kernel via gRPC over the nexus-cluster process (profile binary at rust/profiles/cluster/). The kernel boundary is a network protocol (gRPC): Python spawns or connects to nexus-cluster and dispatches syscalls via typed RPCs (Read, Write, Delete, BatchRead) and a generic Call RPC.

This split lets each peer crate depend on kernel (for trait declarations: abc::ObjectStore, hal::distributed_coordinator::DistributedCoordinator, …) while the binary-side dependency nexus-cluster → {kernel, peers} flows in only one direction. PeerBlobClient lives in lib::transport_primitives so both raft (server-side handler) and transport (client-side fetch) can depend on it without depending on each other.

Dependency direction¶

                       contracts              (zero deps)
                          ↑
                         lib                  (depends on contracts;
                          ↑                    algorithms + transport_primitives
                          │                    behind opt-in features)
                       kernel                 (depends on contracts + lib;
                          ↑                    declares HAL traits)
              ↑    ↑    ↑    ↑
              │    │    │    │
       backends raft transport services       (peer crates — depend on
              ↑    ↑    ↑    ↑                kernel + lib; transport
              │    │    │    │                additionally depends on raft
              │    │    │    │                for federation proto stubs)
              └────┴────┴────┴── rust/profiles/cluster  (deployment binary sink)

Edge invariants:

lib (default features) keeps a zero peer-crate footprint so it builds against wasm32-unknown-unknown. The transport_primitives module under lib's transport feature houses TLS / pool / addressing / TOFU trust store / PeerBlobClient trait — both raft (server-side handler) and transport (client-side fetch) consume it without depending on each other.

RPC: client side vs server side¶

The remote-RPC stack lives on the network surface tier transport/, plus raft for the federation server fabric.

transport/ covers both directions of the network surface (Linux net/ analogue: same crate hosts server sockets and outgoing connection helpers). The RpcTransport type sits in the kernel crate (kernel-internal RemoteMetaStore / RemotePipeBackend / RemoteStreamBackend wrappers also wrap it directly); transport::vfs re-exports it so out-bound callers name a single canonical path.

Placement Decision Tree¶

Is it used by a SINGLE layer?
  → Yes: stays in that layer (e.g. fuse/filters.py)
  → No (multi-layer):
       Is it a type / ABC / exception / enum / constant?
         → Yes: contracts/
         → No (function / helper / I/O logic): lib/

Import Rules¶

contracts/ and lib/ may import from: each other, stdlib, third-party packages. They must never import from: nexus.core, nexus.services, nexus.server, nexus.cli, nexus.fuse, nexus.bricks, nexus.rebac.

7. Deployment Profiles¶

The kernel's layered design (§1) and DI contracts (§3) enable a range of deployment profiles. Not kernel-owned, but kernel-enabled.

Like Linux distros select packages from the same kernel, Nexus profiles select which bricks to enable and which drivers to inject.

Profile hierarchy: slim ⊂ cluster ⊂ embedded ⊂ lite ⊂ full ⊆ cloud. REMOTE is orthogonal — stateless proxy, all operations via gRPC to server.

Same kernel binary, different driver injection. See §1 connect(). Source of truth: src/nexus/contracts/deployment_profile.py.

7.1 Profile binaries (rust/profiles/)¶

A profile that runs as its own OS process lives under rust/profiles/<name>/ and produces a standalone deployment binary nexusd-<name>:

The crate composes the rlibs needed for that profile. cluster links raft + contracts + kernel + backends (the last two with their slimmest feature sets — no connectors, no Python interpreter). The binary mounts host-fs at / via PathLocalBackend at boot (--root-path) and exposes runtime mount / unmount subcommands that drive the same DLC syscalls.

Profile binaries each run as their own OS process. Python communicates with the kernel via gRPC to the nexus-cluster process (see §6.1 "Kernel boundary").

7.2 Compile-time features vs runtime driver gate¶

Driver selection is gated at two layers — pick which layer is doing the work for any given deployment:

The runtime gate is the SSOT — every dispatch goes through is_driver_enabled, no implicit local-default skip-branch.

nexusd-cluster (slim Rust binary) compiles only the drivers it needs (features = ["driver-path-local"]) and skips the runtime gate entirely — the compile-time gate is sufficient because the dispatch arms for missing drivers don't exist. Attempting to mount a non-compiled driver returns driverXnot compiled into this binary straight from the factory.

A driver name that appears in src/nexus/contracts/deployment_profile.py::ALL_DRIVER_NAMES is the canonical name in both layers — Python aliases like the historical "cas" → "cas-local" mapping live in src/nexus/core/nexus_fs_metadata.py, never in Rust.

8. Communication¶

Kernel-adjacent services built on kernel primitives (§4.2 IPC, §4.3 FileEvent). Not kernel-owned, but bottom-layer infrastructure.

See federation-memo.md §2–§5 for gRPC/consensus details.

8.1 NexusVFSService.Call — RPC dispatch order¶

The tonic Call(method, payload) handler resolves the method through two dispatch paths in order:

1. Rust services — Kernel::dispatch_rust_call(service, method, payload) routes to a RustService::dispatch impl when the method maps to a Rust-flavoured entry in ServiceRegistry. Method names follow one of two shapes:
2. Dotted: service.method (canonical) — split on the first ., dispatch the bare method on that service.
3. Flat backward-compat: methods with the prefix acp_ or managed_agent_ route to that service with the full method name preserved (matches Python @rpc_expose naming).
4. Python @rpc_expose — fallback path when the Rust dispatch returns None (no Rust service for that name) or NotFound (service exists but doesn't expose the method). The handler hands the original method string to bridge.dispatch_call, which runs the existing async dispatch_method on the FastAPI loop.

Auth is resolved before either dispatch path so admin-only checks apply uniformly. RustCallError::InvalidArgument and Internal short-circuit straight to the wire encoder; no fallback in those cases.

8.2 Registered Rust services¶

Services compose into a profile binary the same way drivers do (§7.2): each service-* feature gates a pub mod line in rust/services/src/lib.rs, and each profile's Cargo.toml (§7.1) declares the features it enables. Python callers reach a Rust service through the gRPC Call(method, payload) RPC on the profile binary that links it. One dispatch path — no per-service shortcuts — so audit / permission hooks added to the dispatch path land in one place.

9. Cross-References¶