Code Review & Architecture Invariants

Relevant source files

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

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

Numan enforces strict architectural boundaries and code review standards to ensure the stability, security, and reproducibility of the Nushell package management ecosystem. These invariants govern how the system interacts with the host environment, manages state transitions, and handles external package metadata. The primary goal is to ensure that package installations remain inert and do not silently corrupt the user's Nushell configuration or data.

The project follows a "Fail-Closed" philosophy, particularly regarding active plugin mutations and security boundaries. Architectural rules are non-negotiable, and violations are treated as high-severity (P0 or P1) findings during the review process.

Sources: REVIEW.md:5-7, CONTRIBUTING.md:68-70, README.md:120-125, AGENTS.md:188-190

Core Architectural Invariants

Numan's architecture is defined by ten core invariants that must be flagged if violated during code review. These rules ensure that the state of the Nushell environment is only modified through explicit, journaled actions.

Invariant	Description
Install is Inert	numan install must only write to $NUMAN_ROOT. It must not invoke Nu or touch autoload/plugin registration.
Activate is Separate	Only specific activation/deactivation commands are permitted to modify the Nushell integration state.
Mutation Lock	Every mutating command (install, remove, update, gc, import) must call acquire_mutation_lock(root).
Atomic JSON Writes	All state files (lockfile, journals) must use write_json_atomic to prevent partial writes and corruption.
Journals under state/	All pending lifecycle, activation, and autoload journals must reside under $NUMAN_ROOT/state/.
Module Autoload Identity	Autoload state is validated via a four-part match: Nu exe hash, Nu version, vendor autoload dir, and managed file path.
Managed File Ownership	Numan must never overwrite foreign autoload files; it must respect the OWNERSHIP_MARKER.
Nu Invocation Safety	Paths are passed via environment variables only. No runtime interpolation is allowed in Nu program strings.
Test Seams	Unit tests must use injectable seams (e.g., FakeCandidateRunner); they must never spawn a real nu process.
Nupm Boundary	The system is read-only toward NUPM_HOME. No execution of build.nu is permitted during import.

Sources: REVIEW.md:17-29, CONTRIBUTING.md:72-82, AGENTS.md:188-210

Mutation Serialization and State Safety

Numan utilizes an advisory file-descriptor lock to serialize mutations. This prevents concurrent destructive operations from corrupting the Numan root.

The diagram above illustrates the standard mutation flow required for any command that alters Numan state.
Sources: AGENTS.md:204-206, CONTRIBUTING.md:38-40, REVIEW.md:23-24

Review Severity & Checklist

Pull requests are evaluated against a severity scale ranging from P0 (Critical) to P3 (Style). Reviewers use a standardized checklist to ensure new code paths adhere to safety and testing requirements.

Severity Labels

• P0: Data loss, security boundary break, silent corruption, or trust bypass.
• P1: Incorrect behavior on happy path, missing error handling for common failures.
• P2: Test/fixture mismatch with documented contract, misleading docs, maintainability issues.
• P3: Style, naming, or non-blocking suggestions.

Sources: REVIEW.md:10-15

Mandatory Review Checklist

• Error Handling: Error paths must return anyhow::Result with context; library code must never panic.
• Locking: New mutating paths must acquire the mutation lock and snapshot the lockfile before changes.
• Type Safety: Function parameters must use &Path instead of &PathBuf (clippy enforced).
• Testing: Tests must cover failure modes. Unit tests must use FakeCandidateRunner or injectable registrars instead of spawning real nu.
• Documentation: AGENTS.md must be updated when structure or conventions change.

Sources: REVIEW.md:31-38, CONTRIBUTING.md:52-65

Module Autoload & Filesystem Safety

The src/nu/autoload.rs module implements strict validation for module entry resolution to prevent path traversal and unauthorized filesystem access.

Autoload Validation Flow

Numan enforces safety by validating that module payloads and entry points remain within the designated Numan root and payload directories.

This logic ensures that Numan will not follow symlinks for module entries and prevents modules from escaping the containment boundary.
Sources: src/nu/autoload.rs:55-120

Key Autoload Functions

• resolve_entry: Validates containment, file type, and extension for module entries.
• render_use_statement: Handles Nu path-literal escaping, specifically doubling backslashes for Windows paths.
• generate_autoload_content: Produces deterministic file content sorted by scoped package ID.
• write_candidate: Writes a temporary .<uuid>.candidate.tmp file to ensure atomic replacement on the same filesystem.

Sources: src/nu/autoload.rs:55, src/nu/autoload.rs:163, src/nu/autoload.rs:191, src/nu/autoload.rs:271

Nupm Compatibility & Classification

Interoperability with nupm is governed by a strict classification system defined in src/nupm_compat/classify.rs. This ensures that only compatible, safe packages are imported into Numan.

Compatibility Tiers

Tier	Description
ImportableModule	Standard module with valid metadata and safe layout.
DeferredScript	Package containing scripts; activation is currently deferred.
UnsupportedCustomBuild	Packages with build.nu scripts are rejected to maintain the inert install invariant.
UnsupportedDependencies	Packages declaring external dependencies are currently unsupported.
UnsafeFilesystemLayout	Packages containing symlinks or reparse points in the module tree are rejected.

Sources: src/nupm_compat/classify.rs:13-22, src/nupm_compat/classify.rs:80-108

Security Scanning in Classification

The classifier performs several safety checks during the discovery phase:

1. Metadata Size Limits: Prevents resource exhaustion by limiting the size of the metadata file read.
2. Symlink Detection: Explicitly checks if the metadata file or the build script are symlinks or reparse points.
3. Path Chain Safety: Validates the entire path chain to the package root.

Sources: src/nupm_compat/classify.rs:32-60, AGENTS.md:214-216

Conclusion

The architecture invariants and code review standards of Numan are designed to provide a "fail-closed" security model. By enforcing inert installations, serializing mutations with advisory locks, and strictly validating filesystem interactions, Numan ensures that Nushell package management remains predictable and secure across Linux, macOS, and Windows. Developers must prioritize these invariants and ensure all new code paths are accompanied by tests that utilize the project's injectable seams rather than interacting with real system binaries.

Sources: CONTRIBUTING.md:68-85, AGENTS.md:188-210