# NimPak Types Module Reference

## Overview

The `types.nim` file defines the core data structures for the NimPak package management system, which is a fundamental component of the NexusOS project. This module establishes the type system that powers the package management operations.

## Key Components

### 1. Result Type for Error Handling

The module implements a functional `Result[T, E]` pattern for error handling, which is preferred over exceptions for expected failures:

```nim
type
  Result*[T, E] = object
    case isOk*: bool
    of true:
      value*: T
    of false:
      error*: E
```

This allows for more explicit error handling with helper functions like `ok()`, `err()`, `isOk()`, `isErr()`, `get()`, and `getError()`.

### 2. Error Types

The module defines comprehensive error types for package management operations:

```nim
type
  NimPakError* = object of CatchableError
    code*: ErrorCode
    context*: string
    suggestions*: seq[string]

  ErrorCode* = enum
    PackageNotFound, DependencyConflict, ChecksumMismatch,
    PermissionDenied, NetworkError, BuildFailed,
    InvalidMetadata, AculViolation, CellNotFound,
    FilesystemError, CasError, GraftError
```

### 3. Package Identification

Packages are identified using a structured `PackageId` type:

```nim
type
  PackageStream* = enum
    Stable, Testing, Dev, LTS, Custom

  PackageId* = object
    name*: string
    version*: string
    stream*: PackageStream
```

### 4. Package Sources and Building

The module defines types for package sources and build systems:

```nim
type
  SourceMethod* = enum
    Git, Http, Local, Grafted

  Source* = object
    url*: string
    hash*: string  # BLAKE2b hash, will support BLAKE3 later
    hashAlgorithm*: string
    method*: SourceMethod
    timestamp*: DateTime

  BuildSystemType* = enum
    CMake, Meson, Autotools, Cargo, Nim, Custom
```

### 5. Runtime Configuration

System configuration is handled through types like:

```nim
type
  LibcType* = enum
    Musl, Glibc, None

  AllocatorType* = enum
    Jemalloc, Internal, GlibcMalloc, System

  RuntimeProfile* = object
    libc*: LibcType
    allocator*: AllocatorType
    systemdAware*: bool
    reproducible*: bool
    tags*: seq[string]
```

### 6. ACUL Compliance

The module includes types for ACUL (Astral Cooperative Use License) compliance:

```nim
type
  AculCompliance* = object
    required*: bool
    membership*: string
    attribution*: string
    buildLog*: string
```

### 7. Package Definitions

The `Fragment` type represents a complete package definition:

```nim
type
  Fragment* = object
    id*: PackageId
    source*: Source
    dependencies*: seq[PackageId]
    buildSystem*: BuildSystemType
    metadata*: PackageMetadata
    acul*: AculCompliance
```

### 8. Multi-Variant OS Support

The module supports multiple OS variants through types like:

```nim
type
  OSVariant* = enum
    NexusOS, NexusBSD, NexusSafeCore, NexusUnikernel

  KernelType* = enum
    Linux, DragonflyBSD, Redox, Theseus, Unikernel

  UserspaceType* = enum
    GnuFree, Minimal, NimOnly, Custom

  LicenseModel* = enum
    MitAcul, BsdAcul, ApacheMit, EmbeddedAcul
```

### 9. Content-Addressable Storage (CAS)

The module includes types for content-addressable storage:

```nim
type
  CasObject* = object
    hash*: string            # Multihash (BLAKE2b-512 by default)
    size*: int64
    compressed*: bool

  CasStats* = object
    objectCount*: int
    totalSize*: int64
    compressionRatio*: float

  CasError* = enum
    ObjectNotFound, CorruptedObject, StorageError, CompressionError
```

### 10. Package Files and Manifests

File management is handled through types like:

```nim
type
  FilePermissions* = object
    mode*: int
    owner*: string
    group*: string

  PackageFile* = object
    path*: string
    hash*: string
    hashAlgorithm*: string
    permissions*: FilePermissions
    chunks*: Option[seq[ChunkRef]]  # For large files with chunk-level deduplication
```

### 11. Transaction Management

The module includes types for atomic operations with rollback capability:

```nim
type
  OperationKind* = enum
    CreateDir, CreateFile, CreateSymlink, RemoveFile, RemoveDir

  Transaction* = object
    id*: string
    operations*: seq[Operation]
    rollbackData*: seq[RollbackInfo]
```

## Usage in the Project

The types defined in this module are exported by the main `nimpak.nim` module and used throughout the project. The `nip.nim` file implements the command-line interface for the package manager, using these types to represent packages, operations, and errors.

## Design Principles

The types module follows several key design principles:

1. **Type Safety**: Leveraging Nim's type system for compile-time safety
2. **Result Pattern**: Using `Result[T, E]` for error handling instead of exceptions
3. **Atomicity**: Supporting atomic operations with rollback capability
4. **Immutability**: Enabling immutable package management
5. **ACUL Compliance**: Enforcing license compliance throughout the system

This comprehensive type system forms the foundation of the NimPak package manager, enabling the core functionality of the NexusOS project.
