Nexus Kernel Architecture¶

Status: Active — kernel architecture SSOT Rule: Keep this file 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.       │
└──────────────────────────────────────────────────────────────┘

Kernel minimality: The kernel is the minimal compilable unit — it cannot run alone (like Linux's vmlinuz needs bootloader + init). It defines interfaces; drivers provide implementations via DI at startup.

Three 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.

Drivers use constructor DI at startup — same binary, different config (NEXUS_METASTORE=redb, NEXUS_RECORD_STORE=postgresql). Immutable after init.

Services have two maturity phases, both preserving the invariant above:

Phase 1 — Init-time DI (distro composition). factory.py acts as the init system (like systemd): creates selected services and injects them via KernelServices dataclass. Different distros select different service sets at startup — nexus-server loads all 22+, nexus-embedded loads zero.

Resolved (Issue #643): factory.py gates all services via DeploymentProfile + enabled_bricks frozenset (see §5.1). _wire_services() migrated to factory._boot_wired_services() — NexusFS constructor no longer imports or creates services. Two-phase init: NexusFS(...) → _boot_wired_services(nx, ...) → nx._bind_wired_services(dict).

Phase 2 — Runtime hot-swap (Linux LKM model). A ServiceRegistry manages in-process service modules following the Loadable Kernel Module pattern:

• Lifecycle protocol: service_init() → service_start() → service_stop() → service_cleanup(), plus service_name and service_dependencies declarations
• Capability registration: services register the Protocols they implement (like LKMs call register_filesystem() or register_chrdev())
• Dependency graph: load_service() rejects when dependencies missing; unload_service() rejects when dependents still loaded
• Reference counting: prevents unloading while callers hold references

Why LKM, not systemd? Nexus services are in-process components (shared memory, zero IPC overhead), not separate daemon processes. LKMs have the same property — in-kernel modules that register capabilities with subsystems.

Gap: No ServiceRegistry, no lifecycle protocol, no load_service()/unload_service(). Path: extract remaining mixins → standalone service classes (in progress) → introduce ServiceRegistry with LKM lifecycle.

2. The Four Storage Pillars¶

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

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

Kernel Self-Inclusiveness¶

Kernel compiles and inits with 1 pillar (Metastore). ObjectStore is mounted post-init. Like Linux: kernel defines VFS + block device interface but doesn't ship a filesystem.

Kernel does NOT need: JOINs, FK, vector search, TTL, pub/sub (all service-layer).

CacheStore Graceful Degradation¶

No CacheStore → EventBus disabled, PermissionCache falls back to RecordStore, TigerCache O(n), UserSession stays in RecordStore. NullCacheStore provides no-op impl.

RecordStoreABC Usage Pattern¶

Services consume RecordStoreABC.session_factory + SQLAlchemy ORM. Direct SQL or raw driver access is an abstraction break. This ensures driver interchangeability (PostgreSQL ↔ SQLite) without code changes.

Dual-Axis ABC Architecture¶

Two independent ABC axes, composed via DI:

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

A concrete class sits at the intersection: e.g. ReBACManager implements PermissionProtocol (Ops) and internally uses RecordStoreABC (Data). The Protocol itself has no storage opinion. See ops-scenario-matrix.md for full Ops-Scenario affinity proof.

3. Kernel vs Services Boundary¶

Kernel Interfaces (nexus.core)¶

MetastoreABC is kernel because it IS the inode layer — the typed contract between VFS and storage. Without it, the kernel cannot describe files.

NexusFS — Syscall Dispatch Layer¶

NexusFS is the kernel entry point, analogous to Linux's syscall layer (sys_open, sys_read). It wires VFSRouter + MetastoreABC + ObjectStoreABC into user-facing operations (read, write, list, mkdir, mount). NexusFS contains no service business logic — services are accessed through ServiceRegistry (Phase 2) or thin delegation stubs (Phase 1).

factory.py is the init system (analogous to systemd): constructs kernel + drivers + services and wires them together. NexusFS receives pre-built dependencies via its constructor and never auto-creates services.

Resolved: Event mixins fully extracted — NexusFSEventsMixin removed (#573), FileWatcher moved to services/watch/ (#706), orphaned kernel attrs cleaned (#656). _wire_services() deleted — all service creation moved to factory._boot_wired_services() (#643). Remaining: replace KernelServices dataclass with ServiceRegistry.

Service Protocols (nexus.services.protocols)¶

29 scenario domains mapped to Ops ABCs. 23 Protocols exist, 9 gaps remain.

All use typing.Protocol with @runtime_checkable. See ops-scenario-matrix.md §2–§3 for full enumeration and affinity matching.

3.1. Tier-Neutral Layers (contracts/, lib/)¶

Two packages sit outside the Kernel → Services → Drivers stack. Any layer may import from them; they must not import from nexus.core, nexus.services, nexus.fuse, nexus.bricks, or any other tier-specific package.

Core distinction: contracts/ = what (shapes of data). lib/ = how (behavior). When you see from nexus.contracts import X you know X is a lightweight type/exception with near-zero deps. from nexus.lib import Y means Y is a function that does something.

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.

What Goes Where — Examples¶

4. Zone¶

A Zone is the fundamental isolation and consensus unit in NexusFS.

What a Zone determines: - Data isolation: Each zone has its own independent redb database (no shared metadata) - Consensus boundary: 1 Zone = 1 Raft group (consistency guarantees scope) - Visibility: Only nodes participating in a zone can see its metadata - Scalability unit: Zones scale horizontally; adding zones adds capacity without coordination

What a Zone does NOT determine: - Permissions: Read/write access controlled by ReBAC (service layer), not zone membership - User identity: Authentication and user management are services, not zone concerns - File content location: ObjectStore (S3, local disk) is independent of zone topology

Operations: - Mount = create new zone, all participants are equal Voters (no Learner asymmetry) - DT_MOUNT entries in Metastore compose zones into a namespace tree (NFS-style) - DNS-style hierarchical discovery — each zone only knows direct children, no global registry

See federation-memo.md §5–§6 for implementation details.

5. Deployment Modes¶

5.1 Deployment Profiles (Distro)¶

Like Linux distros (Ubuntu, Alpine, BusyBox) select which packages to include from the same kernel, Nexus deployment profiles select which bricks to enable from the same codebase. Two orthogonal axes:

• Mode = network topology (standalone, client-server, federation)
• Profile = feature set (which bricks are enabled)

Profile hierarchy: embedded ⊂ lite ⊂ full ⊆ cloud

Mechanism: factory.py (the init system) resolves the active profile via NEXUS_PROFILE env var -> DeploymentProfile enum -> resolve_enabled_bricks() -> frozenset[str]. Each service in the 3-tier boot (_boot_kernel_services, _boot_system_services, _boot_brick_services) checks brick membership before construction. Individual brick overrides via FeaturesConfig YAML always win over profile defaults.

Source of truth: src/nexus/core/deployment_profile.py (22 canonical brick names, 4 profile-to-brick mappings, resolve_enabled_bricks() merge function).

5.2 Network Modes¶

Driver selection is config-time: same binary, different NEXUS_METASTORE, NEXUS_RECORD_STORE, etc.

6. Communication¶

Messaging Tiers¶

Three tiers, mirroring Linux's kernel → system → user space communication:

Selection rule: Consensus write path → System (gRPC, 1:1). Agent-to-agent messaging → System (IPC, 1:1 queue). Notification read path → User Space (EventBus, 1:N fan-out to 100s of observers). Internal signaling → Kernel (Pipe, zero-copy).

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

System Tier¶

gRPC for consensus (Raft node-to-node, zone API) and Exchange (agent-to-agent value exchange). IPC for agent messaging — 1:1 queue semantics using VFS as transport.

SSOT: Proto files in proto/ define all RPC services. See federation-memo.md §2–§5. IPC details in ops-scenario-matrix.md S29.

User Space Tier: EventBus¶

EventBusProtocol (service protocol in nexus.services.event_bus.protocol) provides pub/sub for file system change notifications. Kernel defines only the event data types (FileEvent, FileEventType in nexus.core.event_bus).

Linux analogue: dbus-daemon (1:N broadcast). Consumed by WatchProtocol (S8) and EventLogProtocol (S17). Backends: Redis/Dragonfly (current default), NATS JetStream (preferred long-term). All should route through CacheStoreABC pub/sub.

Federation gap: EventBus is currently zone-local. Cross-zone event propagation not yet designed.

7. RecordStoreABC Pattern¶

Services consume RecordStoreABC.session_factory + SQLAlchemy ORM. Direct SQL or raw driver access is an abstraction break. This ensures driver interchangeability (PostgreSQL ↔ SQLite) without code changes.

Cross-References¶