nip/docs/nipcell-usage.md

# NipCell Usage Guide

## Overview

NipCells provide isolated environments for packages with conflicting dependencies. When the dependency resolver cannot unify variant demands, it suggests creating separate NipCells to maintain isolation while allowing both packages to coexist.

## When to Use NipCells

NipCells are automatically suggested when:
- **Variant conflicts** occur in exclusive domains (e.g., different init systems)
- **Circular dependencies** cannot be resolved
- **Incompatible version requirements** exist between packages

## Automatic Fallback

The resolver automatically detects unresolvable conflicts and suggests NipCell isolation:

```
❌ [VariantConflict] Cannot unify conflicting variant demands
🔍 Context: Package 'openssl' has conflicting exclusive variant flags in domain 'crypto'

🔀 [IsolationSuggested] NipCell isolation recommended

The following packages have irreconcilable conflicts:
  • openssl (conflicts with: nginx)

NipCell isolation allows you to install these packages in separate environments,
each with its own dependency graph. This avoids the conflict while maintaining
full functionality of each package.

💡 Suggested commands:

  $ nip cell create openssl-cell --isolation=standard
  $ nip cell activate openssl-cell
  $ nip install openssl
```

## Manual Cell Management

### Creating Cells

```bash
# Create a new cell
nip cell create dev-env --isolation=standard

# Create with specific profile
nip cell create prod-env --profile=server --isolation=strict
```

### Activating Cells

```bash
# Activate a cell
nip cell activate dev-env

# Check active cell
nip cell list
```

### Installing Packages in Cells

```bash
# Install in active cell
nip cell activate dev-env
nip install nginx

# Install directly to specific cell
nip install --cell=dev-env nginx
```

### Switching Between Cells

```bash
# Switch to different cell
nip cell activate prod-env

# Deactivate current cell
nip cell deactivate
```

### Removing Cells

```bash
# Remove cell and clean up packages
nip cell delete dev-env

# Remove without cleanup (keep packages)
nip cell delete dev-env --no-cleanup
```

## Cell Isolation Levels

- **None**: No isolation (not recommended for conflicts)
- **Standard**: Mount + filesystem namespaces (default)
- **Strict**: Mount + PID + network + IPC namespaces
- **Quantum**: All namespaces + cryptographic boundaries

## Resolver Integration

The resolver maintains separate dependency graphs for each cell:

```nim
# Resolver automatically uses active cell context
let manager = newResolverCellManager()

# Activate cell for resolution
discard manager.activateCell("dev-env")

# Resolve dependencies in cell context
let graph = manager.resolveInCell("dev-env", "nginx", variantDemand)

# Packages are isolated between cells
discard manager.addPackageToActiveCell("nginx")
```

## Best Practices

1. **Use descriptive cell names**: `dev-env`, `prod-env`, `testing-env`
2. **Document cell purpose**: Use `--description` flag when creating
3. **Regular cleanup**: Remove unused cells to save disk space
4. **Isolation level**: Use `standard` for most cases, `strict` for security-critical
5. **Conflict resolution**: Let the resolver suggest cells automatically

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Conflict Detection                                         │
│  ─────────────────────────────────────────────────────────  │
│  Resolver detects unresolvable conflicts                    │
└────────────────────┬────────────────────────────────────────┘
                     │
                     v
┌─────────────────────────────────────────────────────────────┐
│  Isolation Suggestion                                       │
│  ─────────────────────────────────────────────────────────  │
│  Suggests NipCell isolation with commands                   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     v
┌─────────────────────────────────────────────────────────────┐
│  Cell Management                                            │
│  ─────────────────────────────────────────────────────────  │
│  Create, activate, switch, remove cells                     │
│  Maintain separate dependency graphs                        │
└─────────────────────────────────────────────────────────────┘
```

## Implementation Details

### Modules

- **`nipcell_fallback.nim`**: Conflict detection and isolation suggestions
- **`cell_manager.nim`**: Cell management and resolver integration

### Key Types

- `NipCellGraph`: Cell with its own dependency graph
- `NipCellGraphManager`: Manages multiple cells
- `ResolverCellManager`: Integrates cells with resolver
- `IsolationSuggestion`: Suggested cell configuration

### Requirements Satisfied

- **10.1**: Detect unresolvable conflicts and suggest NipCell isolation
- **10.2**: Create separate NipCells for conflicting packages
- **10.3**: Maintain separate dependency graphs per cell
- **10.4**: Support cell switching
- **10.5**: Clean up cell-specific packages when removing cells

## Testing

The NipCell system has comprehensive test coverage:

- **41 tests** for fallback mechanism (`test_nipcell_fallback.nim`)
- **29 tests** for cell management (`test_cell_manager.nim`)
- **70 total tests** covering all functionality

All tests pass with 100% success rate.

## Future Enhancements

- Integration with existing NipCell CLI commands
- Automatic cell suggestions during package installation
- Cell templates for common use cases
- Cell export/import for sharing configurations
- Performance optimizations for large cell counts

---

**Last Updated:** November 26, 2025
**Status:** Complete - Phase 8 NipCell Integration