Lockfile Schema

Lockfile Schema

Numan utilizes a JSON-based lockfile as the authoritative record of installed packages and their activation states. This schema ensures reproducibility by pinning specific versions, payload hashes, and installation origins. The lockfile is considered the "ground truth" for the system, meaning that any derived projections (like autoload states) must always be reconciled against the lockfile.

The schema evolved from v1 to v2 to support immutable content-addressed payloads, improved drift detection via revision_id, and explicit provenance tracking for imports from external tools like nupm.

Core Data Structures

The lockfile is structured around a central Lockfile object containing a map of LockfileEntry records. Each entry represents a single installed package, identified by a ScopedId (e.g., owner/name).

The Lockfile Object

The root object contains global metadata about the environment and a collection of all installed packages.

Field	Type	Description
packages	BTreeMap<String, LockfileEntry>	Map of package IDs to their respective installation data.
generated_at	String	Timestamp of the last lockfile modification.
nu_version	String	The version of Nushell active during the last modification.
platform	String	The platform triple (e.g., x86_64-unknown-linux-gnu).

The LockfileEntry (v2)

Each entry pins the specific state of a package at the time of installation. This includes artifact locations, integrity hashes, and activation identity.

classDiagram
    class LockfileEntry {
        +String version
        +String package_type
        +String source
        +String payload_path
        +String revision_id
        +Option~String~ payload_sha256
        +Option~String~ origin
        +Option~ModuleActivation~ module_activation
        +BTreeMap~String_String~ locked_dependencies
    }
    class ModuleActivation {
        +String entry_path
        +String vendor_autoload_dir
        +String managed_file_path
        +String nu_executable_sha256
        +String nu_version
    }
    LockfileEntry --> ModuleActivation : optional

Loading

This diagram shows the relationship between a general package entry and the specific activation metadata required for Nushell modules.

Metadata and Provenance

The schema distinguishes between different origins of installation to maintain trust boundaries.

Installation Origins

The origin field identifies how a package entered the Numan root.

• Registry: Prefixed with registry:, indicating a package sourced from a signed index (e.g., registry:official).
• nupm Import: Marked as nupm_import, indicating a local snapshot taken from a nupm installation. These entries are treated as local foreign imports and lack registry-level trust signatures.

Integrity and Drift Detection

Numan uses multiple identifiers to ensure the integrity of the installed files:

1. payload_sha256: The SHA256 hash of the archive payload.
2. revision_id: A deterministic hash computed from the extracted payload directory. This is used to detect "drift" (manual changes to files within the Numan root).
3. executable_sha256: Specifically for plugins, the hash of the binary executable.

Activation State

Activation records are not simple booleans; they are complex structures that bind a package to a specific Nushell environment.

Module Activation

For modules, Numan tracks the specific vendor-autoload directory and the path of the managed numan.nu file. A module is only considered "active" if the current Nushell executable's hash and version match the values stored in the ModuleActivation record.

flowchart TD
    subgraph LockfileRecord [Lockfile Module Record]
        A[entry_path]
        B[nu_executable_sha256]
        C[nu_version]
    end
    subgraph RuntimeProbe [Runtime Nu Probe]
        D[Current Nu Hash]
        E[Current Nu Version]
    end
    A --> F{Validation}
    B --> F
    C --> F
    D --> F
    E --> F
    F -- Match --> G[Active Status]
    F -- Mismatch --> H[Stale/Drift Status]

Loading

This diagram illustrates the multi-factor validation process Numan uses to determine if a module activation is still valid after a Nu upgrade.

Dependency Locking

Registry-defined dependencies are persisted at install time in locked_dependencies. This ensures that even if a registry index changes later, the package's resolution remains pinned to the versions resolved during the initial transaction.

File Path Conventions

The lockfile uses relative paths for payload_path to ensure the root directory remains portable across different base paths (e.g., moving the entire Numan root to a new location). The immutable install path follows the pattern: <root>/packages/<type>/<owner>/<name>/<version>-<sha8prefix>/

Summary of Schema Evolution (v2)

Feature	Implementation	Purpose
Immutable Paths	Hash-prefixed directories	Prevents overwriting in place and allows side-by-side versions.
Revision IDs	Directory content hashing	Enables numan doctor to detect manual tampering within payloads.
Environment Binding	Executable SHA256 in activation	Prevents "ghost" activations where plugins fail after Nu binary upgrades.
Provenance Tracking	origin and selection_reason	Distinguishes between manual version pins and automatic resolver choices.

The Numan Lockfile Schema provides a robust, environment-aware foundation for package management. By pinning content-addressed revisions and binding activation state to specific binary identities, it prevents the common "stale state" issues found in cross-platform plugin management.