System Architecture Principles

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• CONTRIBUTING.md
• REVIEW.md
• src/nu/autoload.rs
• src/nupm_compat/classify.rs

Introduction

Numan is designed as a cross-platform, production-grade package manager for Nushell, prioritizing security, reproducibility, and system stability. The architecture is built around the core philosophy that package installation should be decoupled from shell activation, ensuring that the system remains in a known, stable state unless explicitly modified by the user.

The system manages a variety of artifact types—including plugins, modules, scripts, and completions—using a content-addressed, immutable storage model. By enforcing strict boundaries between the package manager and the Nushell environment, Numan prevents the "silent drift" or corruption common in dynamic shell environments.

Sources: README.md:9-25, AGENTS.md:5-10

Core Architecture Invariants

Numan operates under a set of non-negotiable architectural rules that govern how data is modified and how the system interacts with the host environment.

Separation of Concerns: Install vs. Activate

A primary principle is that numan install is inert. Installation only writes files to the Numan root directory and does not modify the Nushell configuration or invoke the Nushell binary. Only the activate and deactivate commands are permitted to modify the Nushell integration state, such as registering plugins or updating vendor autoload files.

Sources: CONTRIBUTING.md:73-75, REVIEW.md:21-23, AGENTS.md:144-147

Ground Truth and State Management

The Lockfile (v2) is the single source of truth for the system. All other projections, such as the autoload-state.json, are derived from the lockfile and are not considered authoritative. Any mutation to the system state requires acquiring a global Mutation Lock to prevent concurrent writes and data corruption.

Sources: CONTRIBUTING.md:76-78, REVIEW.md:24-27, AGENTS.md:104-110

Immutability and Atomic Operations

Payloads are stored in immutable, versioned, content-addressed paths. Numan never overwrites a payload in place; updates result in new directories. Furthermore, all critical JSON state files (lockfiles, journals, paths) utilize Atomic Writes—writing to a temporary file before persisting the move—to prevent partial-write corruption.

Sources: CONTRIBUTING.md:77-79, REVIEW.md:28-29, AGENTS.md:124-126

Component Interaction and Data Flow

The following diagram illustrates the relationship between user commands, the Numan root, and the Nushell environment.

Module Autoload and Candidate Validation

The module activation system employs a "Candidate Validation" pattern to ensure that generated Nushell code is syntactically valid before it is applied to the live environment.

1. ResolvedEntry: Validates absolute paths, import modes (Module vs. All), and containment within the Numan root.
2. Deterministic Content Generation: Generates use statements sorted by scoped ID for reproducibility.
3. Candidate Placement: Writes content to a .<uuid>.candidate.tmp file to avoid incidental loading by Nushell.
4. Validation: Executes the candidate file using nu -n (no-config mode) via a CandidateRunner.
5. Atomic Replacement: Renames the validated candidate over the live numan.nu file.

Sources: src/nu/autoload.rs:13-35, AGENTS.md:113-118

Autoload Logic Flow

Data Structures and Configuration

Numan categorizes its managed data into specific subdirectories within the root to maintain isolation and facilitate garbage collection.

Path	Description	Authoritative
config.toml	Registry configuration and user defaults.	Yes
lockfile	Pinned installations, version metadata, and activation records.	Yes
packages/	Immutable versioned payloads (modules, plugins, etc.).	Yes
state/	Pending-activation journals and lifecycle recovery data.	No (Transient)
nu_state/	Cached Nushell paths and activation identity markers.	No (Cache)

Sources: README.md:225-235, AGENTS.md:104-112

Error Handling and Recovery

The system is designed to be "fail-closed." If an operation is interrupted, Numan uses Journals (stored in state/) to reconcile the state upon the next execution of a relevant command.

• Plugin Activation Journal: Tracks Prepared vs. Registered states.
• Autoload Journal: Reconciles PendingAutoload states into the lockfile.
• Migration Journal: Manages transitions between legacy and versioned layouts.

Sources: AGENTS.md:127-140, REVIEW.md:30-34

Security and Trust Principles

Security is enforced through artifact verification and cryptographic signatures.

• Registry Trust: Uses Ed25519 signatures over registry indexes.
• Integrity: Mandatory SHA256 verification for plugin binaries during the install transaction.
• Nu Invocation Safety: Plugin paths are passed via environment variables (e.g., NUMAN_PLUGIN_BINARY) rather than string interpolation to prevent injection attacks.

Sources: AGENTS.md:144-160, README.md:17-25, CONTRIBUTING.md:82-84

Conclusion

The architecture of Numan is defined by strict boundaries and a commitment to state reproducibility. By treating the Nushell environment as a target for explicit activation rather than a repository for implicit modification, Numan provides a robust and secure foundation for managing the Nushell package ecosystem.

Sources: README.md:265-275, AGENTS.md:144-155