# Constraint Interpolation Guide\n\n## Overview\n\nTypeDialog form fields can reference constraints from `constraints.toml` using Jinja2-style template syntax. This provides a **single source of truth** for validation limits across forms, Nickel schemas, and validators.\n\n## Pattern\n\nAll numeric form fields should use constraint interpolation for `min` and `max` values:\n\n```\n[[elements]]\nname = "field_name"\ntype = "number"\ndefault = 5\nhelp = "Field description (range: ${constraint.path.to.constraint.min}-${constraint.path.to.constraint.max})"\nmin = "${constraint.path.to.constraint.min}"\nmax = "${constraint.path.to.constraint.max}"\nnickel_path = ["path", "to", "field"]\nprompt = "Field Label"\n```\n\n## Benefits\n\n1. **Single Source of Truth**: Constraints defined once in `constraints.toml`, used everywhere\n2. **Dynamic Validation**: If constraint changes, all forms automatically get updated ranges\n3. **User-Friendly**: Forms show actual valid ranges in help text\n4. **Type Safety**: Constraints match Nickel schema contract ranges\n\n## Complete Constraint Mapping\n\n### Orchestrator Fragments\n\n| Fragment | Field | Constraint Path | Min | Max |\n| ---------- | ------- | ----------------- | ----- | ----- |\n| `queue-section.toml` | `queue_max_concurrent_tasks` | `orchestrator.queue.concurrent_tasks` | 1 | 100 |\n| `queue-section.toml` | `queue_retry_attempts` | `orchestrator.queue.retry_attempts` | 0 | 10 |\n| `queue-section.toml` | `queue_retry_delay` | `orchestrator.queue.retry_delay` | 1000 | 60000 |\n| `queue-section.toml` | `queue_task_timeout` | `orchestrator.queue.task_timeout` | 60000 | 86400000 |\n| `batch-section.toml` | `batch_parallel_limit` | `orchestrator.batch.parallel_limit` | 1 | 50 |\n| `batch-section.toml` | `batch_operation_timeout` | `orchestrator.batch.operation_timeout` | 60000 | 3600000 |\n| `extensions-section.toml` | `extensions_max_concurrent` | `orchestrator.extensions.max_concurrent` | 1 | 20 |\n| `extensions-section.toml` | `extensions_discovery_interval` | Not in constraints (use reasonable bounds) | 300 | 86400 |\n| `extensions-section.toml` | `extensions_init_timeout` | Not in constraints (use reasonable bounds) | 1000 | 300000 |\n| `extensions-section.toml` | `extensions_sandbox_max_memory_mb` | Not in constraints (use reasonable bounds) | 64 | 4096 |\n| `performance-section.toml` | `memory_max_heap_mb` | Not in constraints (use mode-based bounds) | 256 | 131072 |\n| `performance-section.toml` | `profiling_sample_rate` | Not in constraints (use reasonable bounds) | 10 | 1000 |\n| `storage-section.toml` | `storage_cache_ttl` | Not in constraints (use 60-3600) | 60 | 3600 |\n| `storage-section.toml` | `storage_cache_max_entries` | Not in constraints (use 10-100000) | 10 | 100000 |\n| `storage-section.toml` | `storage_compression_level` | Not in constraints (zstd: 1-19) | 1 | 19 |\n| `storage-section.toml` | `storage_gc_retention` | Not in constraints (use 3600-31536000) | 3600 | 31536000 |\n| `storage-section.toml` | `storage_gc_interval` | Not in constraints (use 300-86400) | 300 | 86400 |\n\n### Control Center Fragments\n\n| Fragment | Field | Constraint Path | Min | Max |\n| ---------- | ------- | ----------------- | ----- | ----- |\n| `security-section.toml` | `jwt_token_expiration` | `control_center.jwt.token_expiration` | 300 | 604800 |\n| `security-section.toml` | `jwt_refresh_expiration` | `control_center.jwt.refresh_expiration` | 3600 | 2592000 |\n| `security-section.toml` | `rate_limiting_max_requests` | `control_center.rate_limiting.max_requests` | 10 | 10000 |\n| `security-section.toml` | `rate_limiting_window` | `control_center.rate_limiting.window_seconds` | 1 | 3600 |\n| `security-section.toml` | `users_sessions_max_active` | Not in constraints (use 1-100) | 1 | 100 |\n| `security-section.toml` | `users_sessions_idle_timeout` | Not in constraints (use 300-86400) | 300 | 86400 |\n| `security-section.toml` | `users_sessions_absolute_timeout` | Not in constraints (use 3600-2592000) | 3600 | 2592000 |\n| `policy-section.toml` | `policy_cache_ttl` | Not in constraints (use 60-86400) | 60 | 86400 |\n| `policy-section.toml` | `policy_cache_max_policies` | Not in constraints (use 100-10000) | 100 | 10000 |\n| `policy-section.toml` | `policy_versioning_max_versions` | Not in constraints (use 1-100) | 1 | 100 |\n| `users-section.toml` | `users_registration_auto_role` | Not in constraints (select field, not numeric) | - | - |\n| `users-section.toml` | `users_sessions_max_active` | Not in constraints (use 1-100) | 1 | 100 |\n| `users-section.toml` | `users_sessions_idle_timeout` | Not in constraints (use 300-86400) | 300 | 86400 |\n| `users-section.toml` | `users_sessions_absolute_timeout` | Not in constraints (use 3600-2592000) | 3600 | 2592000 |\n| `compliance-section.toml` | `audit_retention_days` | `control_center.audit.retention_days` | 1 | 3650 |\n| `compliance-section.toml` | `compliance_validation_interval` | Not in constraints (use 1-168 hours) | 1 | 168 |\n| `compliance-section.toml` | `compliance_data_retention_years` | Not in constraints (use 1-30) | 1 | 30 |\n| `compliance-section.toml` | `compliance_audit_log_days` | Not in constraints (use 90-10950) | 90 | 10950 |\n\n### MCP Server Fragments\n\n| Fragment | Field | Constraint Path | Min | Max |\n| ---------- | ------- | ----------------- | ----- | ----- |\n| `tools-section.toml` | `tools_max_concurrent` | `mcp_server.tools.max_concurrent` | 1 | 20 |\n| `tools-section.toml` | `tools_timeout` | `mcp_server.tools.timeout` | 5000 | 600000 |\n| `prompts-section.toml` | `prompts_max_templates` | `mcp_server.prompts.max_templates` | 1 | 100 |\n| `prompts-section.toml` | `prompts_cache_ttl` | Not in constraints (use 60-86400) | 60 | 86400 |\n| `prompts-section.toml` | `prompts_versioning_max_versions` | Not in constraints (use 1-100) | 1 | 100 |\n| `resources-section.toml` | `resources_max_size` | `mcp_server.resources.max_size` | 1048576 | 1073741824 |\n| `resources-section.toml` | `resources_cache_max_size_mb` | Not in constraints (use 10-10240) | 10 | 10240 |\n| `resources-section.toml` | `resources_cache_ttl` | `mcp_server.resources.cache_ttl` | 60 | 3600 |\n| `resources-section.toml` | `resources_validation_max_depth` | Not in constraints (use 1-100) | 1 | 100 |\n| `sampling-section.toml` | `sampling_max_tokens` | `mcp_server.sampling.max_tokens` | 100 | 100000 |\n| `sampling-section.toml` | `sampling_temperature` | Not in constraints (use 0.0-2.0) | 0.0 | 2.0 |\n| `sampling-section.toml` | `sampling_cache_ttl` | Not in constraints (use 60-3600) | 60 | 3600 |\n\n### Common/Shared Fragments\n\n| Fragment | Field | Constraint Path | Min | Max |\n| ---------- | ------- | ----------------- | ----- | ----- |\n| `server-section.toml` | `server_port` | `common.server.port` | 1024 | 65535 |\n| `server-section.toml` | `server_workers` | `common.server.workers` | 1 | 32 |\n| `server-section.toml` | `server_max_connections` | `common.server.max_connections` | 10 | 10000 |\n| `server-section.toml` | `server_keep_alive` | `common.server.keep_alive` | 0 | 600 |\n| `monitoring-section.toml` | `monitoring_metrics_interval` | `common.monitoring.metrics_interval` | 10 | 300 |\n| `monitoring-section.toml` | `monitoring_health_check_interval` | `common.monitoring.health_check_interval` | 5 | 300 |\n| `logging-section.toml` | `logging_max_file_size` | `common.logging.max_file_size` | 1048576 | 1073741824 |\n| `logging-section.toml` | `logging_max_backups` | `common.logging.max_backups` | 1 | 100 |\n| `database-rocksdb-section.toml` | `database_pool_size` | Not in constraints (use 1-100) | 1 | 100 |\n| `database-rocksdb-section.toml` | `database_timeout` | Not in constraints (use 10-3600) | 10 | 3600 |\n| `database-rocksdb-section.toml` | `database_retry_attempts` | Not in constraints (use 0-10) | 0 | 10 |\n| `database-rocksdb-section.toml` | `database_retry_delay` | Not in constraints (use 1000-60000) | 1000 | 60000 |\n| `database-surrealdb-section.toml` | `pool_size` | Not in constraints (use 1-200) | 1 | 200 |\n| `database-surrealdb-section.toml` | `timeout` | Not in constraints (use 10-3600) | 10 | 3600 |\n| `database-postgres-section.toml` | `postgres_port` | Not in constraints (use 1024-65535) | 1024 | 65535 |\n| `database-postgres-section.toml` | `postgres_pool_size` | Not in constraints (use 5-200) | 5 | 200 |\n\n### Installer Fragments\n\n| Fragment | Field | Constraint Path | Min | Max |\n| ---------- | ------- | ----------------- | ----- | ----- |\n| `target-section.toml` | `remote_ssh_port` | `common.server.port` | 1024 | 65535 |\n| `preflight-section.toml` | `min_disk_gb` | `deployment.solo.disk_gb.min` (mode-dependent) | Variable | Variable |\n| `preflight-section.toml` | `min_memory_gb` | `deployment.solo.memory_mb.min` (mode-dependent) | Variable | Variable |\n| `preflight-section.toml` | `min_cpu_cores` | `deployment.solo.cpu.min` (mode-dependent) | Variable | Variable |\n| `installation-section.toml` | `parallel_services` | Not in constraints (use 1-10) | 1 | 10 |\n| `installation-section.toml` | `installation_timeout_seconds` | Not in constraints (use 0-14400) | 0 | 14400 |\n| `installation-section.toml` | `log_level` | Not in constraints (select field, not numeric) | - | - |\n| `installation-section.toml` | `validation_timeout` | Not in constraints (use 5000-300000) | 5000 | 300000 |\n| `services-section.toml` | `orchestrator_port` | `common.server.port` | 1024 | 65535 |\n| `services-section.toml` | `control_center_port` | `common.server.port` | 1024 | 65535 |\n| `services-section.toml` | `mcp_server_port` | `common.server.port` | 1024 | 65535 |\n| `services-section.toml` | `api_gateway_port` | `common.server.port` | 1024 | 65535 |\n| `database-section.toml` | `connection_pool_size` | Not in constraints (use 1-100) | 1 | 100 |\n| `database-section.toml` | `connection_pool_timeout` | Not in constraints (use 10-3600) | 10 | 3600 |\n| `database-section.toml` | `connection_idle_timeout` | Not in constraints (use 60-14400) | 60 | 14400 |\n| `storage-section.toml` | `storage_size_gb` | Not in constraints (use 10-100000) | 10 | 100000 |\n| `storage-section.toml` | `storage_replication_factor` | Not in constraints (use 2-10) | 2 | 10 |\n| `networking-section.toml` | `load_balancer_http_port` | `common.server.port` | 1024 | 65535 |\n| `networking-section.toml` | `load_balancer_https_port` | `common.server.port` | 1024 | 65535 |\n| `ha-section.toml` | `ha_cluster_size` | Not in constraints (use 3-256) | 3 | 256 |\n| `ha-section.toml` | `ha_db_quorum_size` | Not in constraints (use 1-max_cluster_size) | 1 | 256 |\n| `ha-section.toml` | `ha_health_check_interval` | Not in constraints (use 1-120) | 1 | 120 |\n| `ha-section.toml` | `ha_health_check_failure_threshold` | Not in constraints (use 1-10) | 1 | 10 |\n| `ha-section.toml` | `ha_failover_delay` | Not in constraints (use 0-600) | 0 | 600 |\n| `upgrades-section.toml` | `rolling_upgrade_parallel` | Not in constraints (use 1-10) | 1 | 10 |\n| `upgrades-section.toml` | `canary_percentage` | Not in constraints (use 1-50) | 1 | 50 |\n| `upgrades-section.toml` | `canary_duration_seconds` | Not in constraints (use 30-3600) | 30 | 3600 |\n\n## Fragments Status\n\n### ✅ Completed (Constraints Interpolated)\n- `server-section.toml` - All numeric fields updated\n- `monitoring-section.toml` - Core metrics interval updated\n- `orchestrator/queue-section.toml` - All queue fields updated\n- `orchestrator/batch-section.toml` - Parallel limit and operation timeout updated\n- `mcp-server/tools-section.toml` - Tools concurrency and timeout updated\n\n### ⏳ Remaining (Need Updates)\n- All other orchestrator fragments (extensions, performance, storage)\n- All control-center fragments (security, policy, users, compliance)\n- Remaining MCP fragments (prompts, resources, sampling)\n- All installer fragments (target, preflight, installation, services, database, storage, networking, ha, upgrades)\n- All database fragments (rocksdb, surrealdb, postgres)\n- logging-section.toml\n\n## How to Add Constraints to a Fragment\n\n1. **Identify numeric fields** with `type = "number"` that have `min` and/or `max` values\n2. **Find the constraint path** in the mapping table above\n3. **Update the field** with constraint references:\n\n```\n# Before\n[[elements]]\ndefault = 5\nmin = 1\nmax = 100\nname = "my_field"\ntype = "number"\n\n# After\n[[elements]]\ndefault = 5\nhelp = "Field description (range: ${constraint.path.to.field.min}-${constraint.path.to.field.max})"\nmin = "${constraint.path.to.field.min}"\nmax = "${constraint.path.to.field.max}"\nname = "my_field"\ntype = "number"\n```\n\n4. **For fields without existing constraints**, add reasonable bounds based on the domain:\n   - Timeouts: typically 1 second to 1 hour (1000-3600000 ms)\n   - Counters: typically 1-100 or 1-1000\n   - Memory: use deployment mode constraints (64MB-256GB)\n   - Ports: use `common.server.port` (1024-65535)\n\n5. **Test** that the constraint is accessible in `constraints.toml`\n\n## Example: Adding Constraint to a New Field\n\n```\n[[elements]]\ndefault = 3600\nhelp = "Cache timeout in seconds (range: ${constraint.common.monitoring.health_check_interval.min}-${constraint.common.monitoring.health_check_interval.max})"\nmin = "${constraint.common.monitoring.health_check_interval.min}"\nmax = "${constraint.common.monitoring.health_check_interval.max}"\nname = "cache_timeout_seconds"\nnickel_path = ["cache", "timeout_seconds"]\nprompt = "Cache Timeout (seconds)"\ntype = "number"\n```\n\n## Integration with TypeDialog\n\nWhen TypeDialog processes forms:\n\n1. **Load time**: Constraint references are resolved from `constraints.toml`\n2. **Validation**: User input is validated against resolved min/max values\n3. **Help text**: Ranges are shown to user in help messages\n4. **Nickel generation**: Jinja2 templates receive validated values\n\n## See Also\n\n- `provisioning/.typedialog/provisioning/platform/constraints/constraints.toml` - Constraint definitions\n- `constraint_update_status.md` - Progress tracking for constraint interpolation updates\n- `provisioning/.typedialog/provisioning/platform/templates/*.j2` - Jinja2 templates for code generation\n- `provisioning/schemas/` - Nickel schemas (use same ranges as constraints)
