provisioning/schemas/platform/configs/README.md

# Configurations

Mode-specific Nickel configurations for all services (NOT manually edited).

## Purpose

Configurations are **automatically generated** by composing:
1. Service base defaults (defaults/{service}-defaults.ncl)
2. Mode overlay (defaults/deployment/{mode}-defaults.ncl)
3. User customization (values/{service}.{mode}.ncl)
4. Schema validation (schemas/{service}.ncl)
5. Constraint validation (validators/{service}-validator.ncl)

## File Organization

```bash
configs/
├── README.md                           # This file
├── orchestrator.solo.ncl               # Orchestrator solo mode
├── orchestrator.multiuser.ncl          # Orchestrator multi-user mode
├── orchestrator.cicd.ncl               # Orchestrator CI/CD mode
├── orchestrator.enterprise.ncl         # Orchestrator enterprise mode
├── control-center.solo.ncl
├── control-center.multiuser.ncl
├── control-center.cicd.ncl
├── control-center.enterprise.ncl
├── mcp-server.solo.ncl
├── mcp-server.multiuser.ncl
├── mcp-server.cicd.ncl
├── mcp-server.enterprise.ncl
├── installer.solo.ncl
├── installer.multiuser.ncl
├── installer.cicd.ncl
└── installer.enterprise.ncl
```

## Configuration Composition

Each config is built from layers:

```toml
# configs/orchestrator.solo.ncl
let schemas = import "../schemas/orchestrator.ncl" in
let defaults = import "../defaults/orchestrator-defaults.ncl" in
let solo_defaults = import "../defaults/deployment/solo-defaults.ncl" in
let validators = import "../validators/orchestrator-validator.ncl" in

{
  # Merge: base defaults + mode overrides + user customization
  orchestrator = defaults.orchestrator & solo_defaults.services.orchestrator & {
    # User customization goes here (from values/orchestrator.solo.ncl)
  },
} | schemas.OrchestratorConfig  # Apply schema validation
```

## Example Configuration

### Base Defaults

```bash
# defaults/orchestrator-defaults.ncl
orchestrator = {
  workspace = {
    name = "default",
    path = "/var/lib/provisioning/orchestrator",
    enabled = true,
  },
  server = {
    host = "127.0.0.1",
    port = 9090,
    workers = 4,
  },
  queue = {
    max_concurrent_tasks = 5,
  },
}
```

### Solo Mode Override

```bash
# defaults/deployment/solo-defaults.ncl
services.orchestrator = {
  workers = 2,                    # Fewer workers
  queue_max_concurrent_tasks = 3,  # Limited concurrency
  storage_backend = 'filesystem,
}
```

### Generated Config

```toml
# configs/orchestrator.solo.ncl (auto-generated)
{
  orchestrator = {
    workspace = {
      name = "default",           # From base defaults
      path = "/var/lib/provisioning/orchestrator",
      enabled = true,
    },
    server = {
      host = "127.0.0.1",         # From base defaults
      port = 9090,                # From base defaults
      workers = 2,                # OVERRIDDEN by solo mode
    },
    queue = {
      max_concurrent_tasks = 3,   # OVERRIDDEN by solo mode
    },
  },
}
```

## Updating Configurations

**DO NOT manually edit** configs/ files. Instead:

1. **Modify service defaults** (defaults/{service}-defaults.ncl)
2. **Modify mode overrides** (defaults/deployment/{mode}-defaults.ncl)
3. **Modify user values** (values/{service}.{mode}.ncl)
4. **Regenerate configs** (via TypeDialog or manual rebuild)

### Regenerating Configs

#### Via TypeDialog (Recommended)

```nushell
nu provisioning/.typedialog/provisioning/platform/scripts/configure.nu orchestrator solo
```

Automatically:
1. Loads existing config as defaults
2. Shows form with validated constraints
3. User edits configuration
4. Generates updated config

#### Manual Rebuild

```bash
# (Future) Script to rebuild all configs from sources
nu provisioning/.typedialog/provisioning/platform/scripts/generate-configs.nu orchestrator solo
```

## Config Types

### Orchestrator (Workflow Engine)
- Workspace configuration
- Server settings
- Storage backend (filesystem, RocksDB, SurrealDB)
- Queue configuration (concurrency, retries, timeout)
- Batch workflow settings
- Optional: monitoring, rollback, extensions

### Control Center (Policy/RBAC)
- Workspace configuration
- Server settings
- Database configuration
- Security (JWT, RBAC, encryption)
- Optional: compliance, audit logging

### MCP Server (Protocol Server)
- Workspace configuration
- Server settings
- MCP capabilities (tools, prompts, resources)
- Optional: custom tools, resource limits

### Installer (Setup Automation)
- Target configuration
- Provider settings
- Pre-flight checks
- Installation options

## Configuration Values Hierarchy

```toml
1. Explicit user customization (values/{service}.{mode}.ncl)
2. Mode-specific defaults (defaults/deployment/{mode}-defaults.ncl)
3. Service base defaults (defaults/{service}-defaults.ncl)
4. Common shared defaults (defaults/common/*.ncl)
```

## Validation Levels

Configurations are validated at three levels:

### 1. Schema Validation
Type checking when config is evaluated:

```toml
| schemas.OrchestratorConfig
```

### 2. Constraint Validation
Range checking via validators:

```bash
max_concurrent_tasks = validators.ValidConcurrentTasks 5
```

### 3. Business Logic Validation
Service-specific rules in validators.

## Usage in Rust Services

Configs are exported to TOML for Rust services:

```toml
# Generate TOML
nu provisioning/.typedialog/provisioning/platform/scripts/generate-configs.nu orchestrator solo

# Output: provisioning/platform/config/orchestrator.solo.toml
```

Rust services load the TOML:

```javascript
let config_path = "provisioning/platform/config/orchestrator.solo.toml";
let config = Config::from_file(config_path)?;
```

## Deployment Mode Specifics

### Solo Mode Config
- Minimal resources (2 CPU, 4GB)
- Filesystem storage (no DB infrastructure)
- Single worker, low concurrency
- Simplified security (no MFA)

### MultiUser Mode Config
- Team resources (4 CPU, 8GB)
- PostgreSQL or SurrealDB
- Moderate concurrency (4-8 workers)
- RBAC enabled

### CI/CD Mode Config
- Ephemeral (cleanup after run)
- API-driven (no UI/forms)
- High concurrency (8+ workers)
- Minimal security overhead

### Enterprise Mode Config
- Production HA (16+ CPU, 32+ GB)
- SurrealDB cluster with replication
- High concurrency (16+ workers)
- Full security (MFA, KMS, compliance)

## Testing Configurations

```toml
# Typecheck a config
nickel typecheck provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl

# Evaluate and view
nickel eval provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl | head -50

# Export to TOML
nickel export --format toml provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl

# Export to JSON
nickel export --format json provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl
```

## Configuration Merge Example

```toml
# Base
{
  server = {
    host = "127.0.0.1",
    port = 9090,
    workers = 4,
  },
}

# + Mode override
& {
  server.workers = 2,
}

# = Result
{
  server = {
    host = "127.0.0.1",
    port = 9090,
    workers = 2,  # OVERRIDDEN
  },
}
```

Nickel's `&` operator is a **shallow merge** - only top-level fields are replaced, deeper nesting is preserved.

## Generated Config Structure

All generated configs follow this structure:

```toml
# Service config
{
  {service} = {
    # Workspace
    workspace = { ... },

    # Server
    server = { ... },

    # Storage/Database
    [storage | database] = { ... },

    # Service-specific
    [queue | rbac | capabilities] = { ... },

    # Optional
    [monitoring | security | compliance] = { ... },
  },
}
```

---

**Version**: 1.0.0
**Last Updated**: 2025-01-05