503 lines
19 KiB
JSON
503 lines
19 KiB
JSON
{
|
|
"capabilities": [
|
|
{
|
|
"adrs": [
|
|
"adr-016-workspace-formula-dag"
|
|
],
|
|
"artifacts": [
|
|
"schemas/lib/formula.ncl",
|
|
"platform/crates/orchestrator/src/formula.rs",
|
|
"platform/crates/orchestrator/src/batch.rs"
|
|
],
|
|
"how": "Workspace TOML declares Formula nodes; orchestrator's formula.rs converts to DependencyGraph via topological sort; BatchExecutor executes ready nodes in parallel via NATS work queues.",
|
|
"id": "formula-dag-execution",
|
|
"name": "Formula DAG Execution Engine",
|
|
"nodes": [
|
|
"formula-dag-execution"
|
|
],
|
|
"rationale": "Positional task arrays collapse on dependency ambiguity and lack parallelism signals. Formula nodes declare depends_on, on_error, parallel, max_retries — enabling the orchestrator to derive a topological execution plan without imperative scripting.",
|
|
"summary": "Typed DAG-based workflow execution with topological parallelism, retry, and rollback."
|
|
},
|
|
{
|
|
"adrs": [],
|
|
"artifacts": [
|
|
"schemas/config/workspace_config/",
|
|
"core/crates/",
|
|
"examples/workspaces/"
|
|
],
|
|
"how": "CLI validates workspace TOML against schemas/config/workspace_config/ contracts via nickel export before submitting to orchestrator. Orchestrator re-validates on receipt.",
|
|
"id": "workspace-contract",
|
|
"name": "Typed Workspace Contracts",
|
|
"nodes": [
|
|
"workspace-contract"
|
|
],
|
|
"rationale": "Raw TOML workspace files have no type safety — invalid configs surface as runtime errors. Nickel schemas catch structural errors at write time, before any provider API is called.",
|
|
"summary": "Nickel-validated workspace definitions that compose providers, taskservs, and ingredients into infrastructure DAGs."
|
|
},
|
|
{
|
|
"adrs": [],
|
|
"artifacts": [
|
|
"catalog/providers/",
|
|
"platform/crates/orchestrator/src/"
|
|
],
|
|
"how": "Each provider implements the ProviderInterface trait (25 functions). Orchestrator dispatches operations via the interface; provider implementations are loaded from catalog/providers/.",
|
|
"id": "provider-plugin-system",
|
|
"name": "Provider Plugin System",
|
|
"nodes": [
|
|
"provider-abstraction",
|
|
"taskserv-pattern"
|
|
],
|
|
"rationale": "Hardcoded provider logic makes multi-cloud support a fork, not an extension. The provider interface isolates provider specifics behind a stable contract.",
|
|
"summary": "25-function pluggable interface for infrastructure providers — add a provider without changing the platform."
|
|
},
|
|
{
|
|
"adrs": [
|
|
"adr-015-solo-mode-architecture"
|
|
],
|
|
"artifacts": [
|
|
"platform/crates/control-center/src/middleware/",
|
|
"platform/crates/orchestrator/src/nats.rs"
|
|
],
|
|
"how": "--mode solo flag activates solo_auth_middleware (auto-injects admin session), SurrealDB switches to kv-surrealkv (RocksDB), NATS starts as child process. service-manager.nu orchestrates startup.",
|
|
"id": "solo-mode-deployment",
|
|
"name": "Solo Mode — Full-Architecture Single-Operator Deployment",
|
|
"nodes": [
|
|
"solo-mode"
|
|
],
|
|
"rationale": "Simplified mono-binary for solo creates two divergent code paths. Solo mode keeps the same binaries and NATS subjects — scripts written for solo work in multi-user unchanged.",
|
|
"summary": "Run the full platform on a laptop: embedded SurrealDB (RocksDB), child NATS server, solo_auth_middleware replacing JWT+Cedar."
|
|
},
|
|
{
|
|
"adrs": [
|
|
"adr-012-nats-event-broker"
|
|
],
|
|
"artifacts": [
|
|
"platform/crates/orchestrator/src/workflow.rs",
|
|
"platform/crates/platform-nats/"
|
|
],
|
|
"how": "Orchestrator publishes tasks to JetStream streams per provider type. Taskserv workers consume via pull consumers with ack/nack. Task state machine tracks pending → running → completed/failed in SurrealDB.",
|
|
"id": "nats-brokered-orchestration",
|
|
"name": "NATS JetStream Orchestration",
|
|
"nodes": [
|
|
"platform-dispatch"
|
|
],
|
|
"rationale": "HTTP synchronous task dispatch couples orchestrator latency to provider API latency. NATS decouples dispatch from execution, enables fan-out to taskserv workers, and provides durable state even if a worker crashes mid-task.",
|
|
"summary": "All inter-service task dispatch via NATS JetStream work queues with at-least-once delivery and state machine tracking."
|
|
},
|
|
{
|
|
"adrs": [
|
|
"adr-013-surrealdb-global-store"
|
|
],
|
|
"artifacts": [
|
|
"platform/crates/platform-config/src/format.rs",
|
|
"schemas/config/"
|
|
],
|
|
"how": "platform-config's ConfigLoader trait runs collect_env_overrides() → nickel export → serde::Deserialize. Override files are written to config/*.overrides.ncl and merged via & at the entry point.",
|
|
"id": "nickel-config-hierarchy",
|
|
"name": "Nickel-Validated Configuration Hierarchy",
|
|
"nodes": [
|
|
"config-hierarchy",
|
|
"type-safety-nickel"
|
|
],
|
|
"rationale": "Ad-hoc env var overrides without schema validation cause silent misconfiguration. The Nickel merge layer validates every override level against the same contracts before deserialization.",
|
|
"summary": "5-level config precedence with NCL contracts: runtime args > env vars > user config > infra config > system defaults."
|
|
},
|
|
{
|
|
"adrs": [
|
|
"adr-014-solid-enforcement"
|
|
],
|
|
"artifacts": [
|
|
"platform/crates/orchestrator/",
|
|
"platform/crates/control-center/",
|
|
"platform/secretumvault/"
|
|
],
|
|
"how": "Clippy rules, grep CI checks, Cedar policies, and runtime middleware enforce the boundaries. solo_auth_middleware is the only documented auth bypass and requires --mode solo.",
|
|
"id": "solid-enforcement",
|
|
"name": "SOLID Boundary Enforcement",
|
|
"nodes": [
|
|
"solid-boundaries"
|
|
],
|
|
"rationale": "Without enforced boundaries, authorization and secrets logic diffuses across services. ADR-014 documents 6 hard boundaries with 6 enforcement layers (compile-time, dev-time, pre-commit, CI, runtime, audit).",
|
|
"summary": "6 compile-time and runtime SOLID boundaries: orchestrator-only provider calls, control-center-only auth, vault-only secrets."
|
|
}
|
|
],
|
|
"claude": {
|
|
"guidelines": [
|
|
"bash",
|
|
"nushell"
|
|
],
|
|
"session_hook": true,
|
|
"stratum_commands": true
|
|
},
|
|
"config_surface": {
|
|
"config_root": ".typedialog/provisioning/",
|
|
"contracts_path": ".typedialog/provisioning/schemas",
|
|
"entry_point": "config.ncl",
|
|
"kind": "TypeDialog",
|
|
"overrides_dir": ".typedialog/provisioning/generated",
|
|
"sections": [
|
|
{
|
|
"consumers": [
|
|
{
|
|
"fields": [
|
|
"services",
|
|
"deployment",
|
|
"database"
|
|
],
|
|
"id": "orchestrator",
|
|
"kind": "RustStruct",
|
|
"ref": "provisioning_orchestrator::config::OrchestratorConfig"
|
|
},
|
|
{
|
|
"fields": [],
|
|
"id": "configure-nu",
|
|
"kind": "NuScript",
|
|
"ref": ".typedialog/provisioning/configure.nu"
|
|
},
|
|
{
|
|
"fields": [],
|
|
"id": "ci-woodpecker",
|
|
"kind": "CiPipeline",
|
|
"ref": ".woodpecker/ci.yml"
|
|
}
|
|
],
|
|
"contract": "schemas/provisioning-config.ncl",
|
|
"description": "Root workspace configuration generated by TypeDialog — project metadata, services, database, deployment target, network, storage, monitoring, security.",
|
|
"file": "config.ncl",
|
|
"id": "provisioning",
|
|
"mutable": true,
|
|
"rationale": "Consumer projects declare what infrastructure they need via an interactive TypeDialog form. The NCL output is the single source of truth fed to the orchestrator. TypeDialog fragments (database-postgres, deployment-k8s, etc.) ensure only valid combinations are generated."
|
|
},
|
|
{
|
|
"consumers": [
|
|
{
|
|
"fields": [
|
|
"database"
|
|
],
|
|
"id": "orchestrator",
|
|
"kind": "RustStruct",
|
|
"ref": "provisioning_orchestrator::config::OrchestratorConfig"
|
|
}
|
|
],
|
|
"contract": "schemas/database.ncl",
|
|
"description": "Database type and connection parameters — supports sqlite, postgres, surrealdb, mysql. Generated into the root config via TypeDialog database-* fragments.",
|
|
"file": "schemas/database.ncl",
|
|
"id": "database",
|
|
"mutable": false,
|
|
"rationale": "Database configuration is the most provider-specific section. TypeDialog fragments enforce valid parameter combinations per engine (e.g. journal_mode only valid for SQLite)."
|
|
},
|
|
{
|
|
"consumers": [
|
|
{
|
|
"fields": [
|
|
"deployment"
|
|
],
|
|
"id": "orchestrator",
|
|
"kind": "RustStruct",
|
|
"ref": "provisioning_orchestrator::config::OrchestratorConfig"
|
|
}
|
|
],
|
|
"contract": "schemas/deployment.ncl",
|
|
"description": "Deployment target — docker-compose or kubernetes. Drives which taskservs are activated and which providers are called.",
|
|
"file": "schemas/deployment.ncl",
|
|
"id": "deployment",
|
|
"mutable": false,
|
|
"rationale": "Deployment target selection is the primary branching decision in workspace execution. TypeDialog deployment-docker and deployment-k8s fragments capture the full parameter space for each target."
|
|
},
|
|
{
|
|
"consumers": [
|
|
{
|
|
"fields": [
|
|
"monitoring"
|
|
],
|
|
"id": "orchestrator",
|
|
"kind": "RustStruct",
|
|
"ref": "provisioning_orchestrator::config::OrchestratorConfig"
|
|
}
|
|
],
|
|
"contract": "schemas/monitoring.ncl",
|
|
"description": "Observability configuration — metrics, logging, alerting. Optional; defaults from .typedialog/provisioning/defaults/monitoring-defaults.ncl.",
|
|
"file": "schemas/monitoring.ncl",
|
|
"id": "monitoring",
|
|
"mutable": false,
|
|
"rationale": ""
|
|
}
|
|
]
|
|
},
|
|
"consumption_modes": [
|
|
{
|
|
"audit_level": "Standard",
|
|
"consumer": "Developer",
|
|
"description": "Uses provisioning CLI and workspace definitions to manage infrastructure. Extends via providers and taskservs.",
|
|
"needs": [
|
|
"OntologyExport"
|
|
]
|
|
},
|
|
{
|
|
"audit_level": "Quick",
|
|
"consumer": "Agent",
|
|
"description": "Reads .ontology/core.ncl to understand constraints and boundaries. Uses CLI and orchestrator APIs for infrastructure operations.",
|
|
"needs": [
|
|
"OntologyExport",
|
|
"JsonSchema"
|
|
]
|
|
}
|
|
],
|
|
"content_assets": [],
|
|
"critical_deps": [
|
|
{
|
|
"failure_impact": "All stateful operations (task tracking, policy evaluation, audit) stop. Solo mode continues via kv-surrealkv but loses SurrealDB WS protocol.",
|
|
"id": "surrealdb-crate",
|
|
"mitigation": "Feature-gated: --no-default-features disables SurrealDB for dev builds. Solo mode uses embedded kv-surrealkv (RocksDB).",
|
|
"name": "SurrealDB client crate",
|
|
"ref": "surrealdb@3",
|
|
"used_for": "Task state machine persistence, Cedar policy storage, audit log, workspace history."
|
|
},
|
|
{
|
|
"failure_impact": "Orchestrator cannot dispatch workflows; taskserv workers go idle. Solo mode manages nats-server as child — child crash is fatal.",
|
|
"id": "async-nats",
|
|
"mitigation": "Feature-gated via platform-nats crate. Solo mode restarts nats-server on SIGTERM.",
|
|
"name": "async-nats",
|
|
"ref": "async-nats@0.46",
|
|
"used_for": "All inter-service task dispatch, NATS JetStream work queues, taskserv worker consumers."
|
|
},
|
|
{
|
|
"failure_impact": "All authorization decisions in multi-user mode fail closed. Solo mode unaffected (solo_auth_middleware bypasses Cedar).",
|
|
"id": "cedar-policy-crate",
|
|
"mitigation": "Compile-time link; no runtime loading. cedar-policy is the Cedar Reference Implementation — stable API surface.",
|
|
"name": "cedar-policy",
|
|
"ref": "cedar-policy@4.8",
|
|
"used_for": "Authorization decisions in control-center: policy evaluation, RBAC, resource-level access control."
|
|
},
|
|
{
|
|
"failure_impact": "Vault service cannot start; provider credential injection fails. All infrastructure operations that require provider API keys stop.",
|
|
"id": "secretumvault",
|
|
"mitigation": "Local path dependency — pinned to checkout. Solo mode uses filesystem backend (age key).",
|
|
"name": "secretumvault",
|
|
"ref": "secretumvault (local path ../../../Development/secretumvault)",
|
|
"used_for": "Secrets management: age key management, Shamir threshold unsealing, secret storage for provider credentials."
|
|
},
|
|
{
|
|
"failure_impact": "All HTTP API surfaces become unavailable. CLI falls back to NATS direct where supported.",
|
|
"id": "axum",
|
|
"mitigation": "axum@0.8 is maintained by the Tokio project; API stability is high.",
|
|
"name": "axum",
|
|
"ref": "axum@0.8",
|
|
"used_for": "HTTP API layer for orchestrator, control-center, extension-registry, ai-service, mcp-server."
|
|
}
|
|
],
|
|
"default_audit": "Standard",
|
|
"default_mode": "dev",
|
|
"description": "Multi-crate Rust platform for cloud infrastructure provisioning: typed Nickel schemas validated at the NCL layer, formula DAG execution engine, SOLID-enforced service boundaries, pluggable providers and taskservs, NATS-brokered orchestration, Cedar authorization, and full-architecture solo mode for single-operator deployments.",
|
|
"domain_provides": {
|
|
"description": "Workspace infrastructure contracts: cluster topology, state dimensions, gate membranes, and operational modes for DevWorkspace projects.",
|
|
"id": "provisioning-platform",
|
|
"impl_repo_kind": "DevWorkspace",
|
|
"kind": "Implicit",
|
|
"name": "Provisioning Platform",
|
|
"schema_path": "reflection/schemas/"
|
|
},
|
|
"justfile": {
|
|
"required_modules": [
|
|
"build",
|
|
"test",
|
|
"dev",
|
|
"ci"
|
|
],
|
|
"required_recipes": [
|
|
"default",
|
|
"help"
|
|
],
|
|
"system": "Mod"
|
|
},
|
|
"layers": [
|
|
{
|
|
"committed": true,
|
|
"description": "Nickel type schemas for all infrastructure configuration: providers, workspaces, platform services, extensions.",
|
|
"id": "schemas",
|
|
"paths": [
|
|
"schemas/"
|
|
]
|
|
},
|
|
{
|
|
"committed": true,
|
|
"description": "CLI, libraries, plugins, Nushell scripts — the user-facing surface of provisioning.",
|
|
"id": "core",
|
|
"paths": [
|
|
"core/"
|
|
]
|
|
},
|
|
{
|
|
"committed": true,
|
|
"description": "Orchestrator, Control Center, Vault, Extension Registry — the control plane services.",
|
|
"id": "platform",
|
|
"paths": [
|
|
"platform/"
|
|
]
|
|
},
|
|
{
|
|
"committed": true,
|
|
"description": "Providers, taskservs, clusters, components, domain artifacts — IaC building block catalog and federated integration domain contracts.",
|
|
"id": "catalog",
|
|
"paths": [
|
|
"catalog/"
|
|
]
|
|
},
|
|
{
|
|
"committed": true,
|
|
"description": "Default configuration files and infrastructure templates.",
|
|
"id": "config",
|
|
"paths": [
|
|
"config/",
|
|
"templates/"
|
|
]
|
|
},
|
|
{
|
|
"committed": true,
|
|
"description": "Provisioning consuming on+re: axioms, tensions, practices, state, gates, ADRs.",
|
|
"id": "self-description",
|
|
"paths": [
|
|
".ontology/"
|
|
]
|
|
}
|
|
],
|
|
"level": {
|
|
"index": "Domain",
|
|
"name": "provisioning-domain",
|
|
"parent": "ontoref-base"
|
|
},
|
|
"ontology_node": "",
|
|
"operational_modes": [
|
|
{
|
|
"audit_level": "Standard",
|
|
"description": "Full development view — all layers visible.",
|
|
"id": "dev",
|
|
"post_activate": [],
|
|
"pre_activate": [],
|
|
"visible_layers": [
|
|
"schemas",
|
|
"core",
|
|
"platform",
|
|
"catalog",
|
|
"config",
|
|
"self-description"
|
|
]
|
|
},
|
|
{
|
|
"audit_level": "Standard",
|
|
"description": "Platform engineering focus — schemas, platform services, and configuration.",
|
|
"id": "platform-focus",
|
|
"post_activate": [],
|
|
"pre_activate": [],
|
|
"visible_layers": [
|
|
"schemas",
|
|
"platform",
|
|
"config"
|
|
]
|
|
},
|
|
{
|
|
"audit_level": "Standard",
|
|
"description": "Catalog development focus — schemas, providers, taskservs, components, and configuration.",
|
|
"id": "catalog-focus",
|
|
"post_activate": [],
|
|
"pre_activate": [],
|
|
"visible_layers": [
|
|
"schemas",
|
|
"catalog",
|
|
"config"
|
|
]
|
|
}
|
|
],
|
|
"project": "provisioning",
|
|
"publication_services": [],
|
|
"registry_provides": {
|
|
"participant": "provisioning",
|
|
"registries": {
|
|
"default": "primary",
|
|
"registries": [
|
|
{
|
|
"endpoint": "reg.librecloud.online",
|
|
"id": "primary",
|
|
"namespaces": {
|
|
"own": [
|
|
"domains/provisioning/",
|
|
"modes/provisioning/"
|
|
],
|
|
"prefixes": [
|
|
"domains/provisioning/",
|
|
"modes/provisioning/"
|
|
],
|
|
"replicate_to": []
|
|
},
|
|
"role": "primary",
|
|
"tls": true
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"repo_kind": "Mixed",
|
|
"requirements": [
|
|
{
|
|
"env": "Development",
|
|
"id": "rust",
|
|
"impact": "Platform services and CLI cannot compile.",
|
|
"kind": "Tool",
|
|
"name": "Rust toolchain",
|
|
"provision": "rustup toolchain install stable",
|
|
"required": true,
|
|
"version": "1.75+"
|
|
},
|
|
{
|
|
"env": "Both",
|
|
"id": "nushell",
|
|
"impact": "Reflection modes, service-manager.nu, and CLI scripts cannot execute.",
|
|
"kind": "Tool",
|
|
"name": "Nushell",
|
|
"provision": "cargo install nu",
|
|
"required": true,
|
|
"version": "0.110+"
|
|
},
|
|
{
|
|
"env": "Both",
|
|
"id": "nickel",
|
|
"impact": "Schema validation and config export cannot run. platform-config's ConfigLoader cannot operate.",
|
|
"kind": "Tool",
|
|
"name": "Nickel",
|
|
"provision": "cargo install nickel-lang-cli",
|
|
"required": true,
|
|
"version": "1.15+"
|
|
},
|
|
{
|
|
"env": "Production",
|
|
"id": "surrealdb",
|
|
"impact": "Multi-user deployments cannot persist task state, Cedar policies, or audit logs. Solo mode uses embedded RocksDB.",
|
|
"kind": "Service",
|
|
"name": "SurrealDB",
|
|
"provision": "Deploy surrealdb container or binary; solo mode uses kv-surrealkv.",
|
|
"required": false,
|
|
"version": "2.3+"
|
|
},
|
|
{
|
|
"env": "Both",
|
|
"id": "nats-server",
|
|
"impact": "Orchestrator cannot dispatch tasks; taskserv workers cannot receive work items. Solo mode manages nats-server as a child process.",
|
|
"kind": "Service",
|
|
"name": "NATS Server (JetStream)",
|
|
"provision": "Install nats-server in PATH for solo mode; deploy NATS cluster for multi-user.",
|
|
"required": true,
|
|
"version": ""
|
|
},
|
|
{
|
|
"env": "Production",
|
|
"id": "cedar-policy",
|
|
"impact": "Cedar-based authorization unavailable in multi-user mode. Solo mode uses solo_auth_middleware which bypasses Cedar entirely.",
|
|
"kind": "Infrastructure",
|
|
"name": "Cedar policy engine",
|
|
"provision": "Policies stored in SurrealDB; loaded by control-center at startup.",
|
|
"required": false,
|
|
"version": ""
|
|
}
|
|
],
|
|
"templates": [],
|
|
"tools": []
|
|
}
|