# 📦 nexus **Package Formats and Their Purposes**

Let’s clearly and strategically structure the packaging and distribution strategy for **NexusOS** and the **Nexus ecosystem**, focusing on a clear, robust, modern, and future-proof format separation.

---

## 🎯 **Goals**

* **Clear naming & extension conventions**
* **Future-proof design** (quantum-resilient hashing, etc.)
* **Fast, efficient compression & decompression**
* **Logical separation of package concerns**

---

# 📦 **Package Formats and Their Purposes**

NexusOS will employ a clear, distinct separation between different packaging artifacts:

| Artifact Type                                                 | File Extension                          | Content & Usage                                                                                   | Compression       | Integrity                  |
| ------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------- | -------------------------- |
| **Source Recipes** (Fragments, purely declarative)            | `.npr` (*Nexus Package Recipe*)         | **KDL** metadata describing build instructions; minimal logs; no binaries.                        | None (plain text) | Signed metadata (Ed25519)  |
| **Compiled Binary Packages** (ready-to-install)               | `.npk.zst` (*Nexus Package, Zstandard*) | Tar archives compressed with **zstd** containing binaries, manifests, metadata (KDL), build logs. | `zstd --fast`     | BLAKE3, Ed25519 signatures |
| **CAS Archive Chunks** (Merkle Tree storage)                  | `.nca` (*Nexus Content-Addressable*)    | Binary blobs stored in CAS with Merkle Trees; content-addressable only.                           | Optional zstd     | BLAKE3 Merkle Tree hashes  |
| **System Snapshots** (environment reproducibility)            | `.nss.zst` (*Nexus System Snapshot*)    | Full reproducible environment snapshots (lockfile, package manifests, build logs, KDL metadata)   | `zstd --fast`     | BLAKE3, Ed25519 signatures |
| **Overlay Fragments** (system modifications for immutable OS) | `.nof` (*Nexus Overlay Fragment*)       | Declarative overlay configurations in KDL                                                         | None (plain text) | Signed metadata (Ed25519)  |

---

## 🧠 **Reasoning & Justification**

### Why `.npk.zst` explicitly?

* Aligns clearly with **Arch Linux conventions**, explicitly indicating Zstandard compression.
* Immediately recognizable to sysadmins familiar with modern Linux distributions.
* Avoids ambiguity and clearly communicates the compression method at a glance.

**Example:**

```
neofetch-7.1.0.npk.zst
```

### Why `.npr` (recipe format)?

* Clearly distinguishes source-level recipes (KDL) from binary packages.
* Explicitly uncompressed for easy human readability, version control (Git-friendly).

**Example:**

```
neofetch-7.1.0.npr
```

### Why `.nca` (CAS archives)?

* Clearly indicates the file is part of NexusOS’s content-addressable storage.
* Binary blobs optimized for high deduplication rates and rapid verification.

### Why `.nss.zst` (system snapshots)?

* Identifies clearly as a snapshot artifact for reproducible environments.
* Explicit Zstandard compression for storage efficiency and decompression speed.

### Why `.nof` (Overlay fragments)?

* Short, clear, distinctive naming.
* Explicitly uncompressed, easily readable and editable in immutable configuration management workflows.

---

## 🔐 **Future-Proofing & Quantum-Resilience**

To ensure long-term future-proofing (quantum-resistant hashing/signatures):

* **Short Term** (now → 2026):

  * Standardize **BLAKE3** hashing for all integrity checks (currently strongest practical hash).
  * **Ed25519** for digital signatures (fast, secure, widely used).

* **Medium Term** (2026+ → quantum era):

  * Prepare a transparent upgrade path to quantum-resistant algorithms like **Dilithium** (post-quantum signatures) or similar NIST PQC standards.
  * Package format includes a “version field” in KDL metadata, explicitly stating cryptographic algorithms used for hashing and signing, allowing graceful transitions without format breaks.

Example metadata snippet (future-proof):

```kdl
package "neofetch" {
  version "7.1.0"
  
  integrity {
    hash "blake3-abcdef1234567890..."
    signature "ed25519-abcdef1234567890..."
    algorithm "BLAKE3"
    signingAlgorithm "Ed25519"
  }
}
```

When transitioning:

```kdl
integrity {
  hash "sha3-512-abcdef1234567890..."
  signature "dilithium-abcdef1234567890..."
  algorithm "SHA3-512"
  signingAlgorithm "Dilithium"
}
```

This approach ensures clarity, auditability, and forward compatibility.

---

## 📌 **Final Recommended Structure**

A clearly summarized and recommended standard moving forward:

| Type                   | Extension  | Compression   | Integrity                 | Quantum-Ready               |
| ---------------------- | ---------- | ------------- | ------------------------- | --------------------------- |
| **Package Recipes**    | `.npr`     | None          | Signed metadata (Ed25519) | ✅ Yes (metadata upgradable) |
| **Binary Packages**    | `.npk.zst` | zstd (fast)   | BLAKE3, Ed25519           | ✅ Yes (algorithm metadata)  |
| **CAS Archive Chunks** | `.nca`     | Optional zstd | BLAKE3 Merkle Trees       | ✅ Yes (algorithm metadata)  |
| **System Snapshots**   | `.nss.zst` | zstd (fast)   | BLAKE3, Ed25519           | ✅ Yes (algorithm metadata)  |
| **Overlay Fragments**  | `.nof`     | None          | Signed metadata (Ed25519) | ✅ Yes (metadata upgradable) |

---

## 🚩 **Next Steps (Practical Implementation)**

1. **Implement `.npk.zst` explicitly:**

   * Ensure `createNpkArchive` and `loadNpkArchive` use `.npk.zst`.
   * Update all documentation, tooling, and repository conventions accordingly.

2. **Formalize `.npr`, `.nof`, `.nss.zst`, and `.nca` formats:**

   * Define clear schemas and metadata templates for each type.

3. **Metadata quantum-resilience:**

   * Begin adding explicit cryptographic algorithm metadata now.
   * Prepare and document clear procedures for algorithm migration.

4. **Documentation & Examples:**

   * Thoroughly document all formats, purposes, and conventions in `docs/package_formats.md`.

5. **Testing & Validation:**

   * Comprehensive unit and integration tests validating correctness, speed, compression ratio, and integrity for each format.