/ components / infra.cspec
infra.cspec
1 # Infrastructure Domain Aggregate 2 # Contains: I001-I005 (Dev Infrastructure) 3 # Stability: stable 4 5 metadata: 6 domain: infra 7 version: 1.5.0 8 stability: stable 9 updated: 2026-01-20 10 component_ids: [I001, I002, I003, I004, I005] 11 implementation_status: 12 I001: complete # Phase 1 complete 13 I002: complete # Operational infrastructure 14 I003: complete # Operational infrastructure 15 I004: complete # Operational infrastructure 16 I005: spec_only # Interface defined, implementation pending 17 roles: 18 primary: [Ops, Dev] 19 review: [] 20 expertise: 21 required: [devops, ci_cd] 22 helpful: [rust, forgejo, radicle] 23 context_tags: [repos, ci, build, forgejo, radicle, cargo, adl] 24 25 dependencies: 26 upstream: [] 27 downstream: [ACDC] 28 29 # === INTERFACES === 30 interfaces: 31 interface_repo_structure: 32 description: Canonical repository paths, purposes, and organization 33 stability: stable 34 available_from: phase_1 35 consumers: [ACDC] 36 provides: 37 repos: 38 core: 39 - name: alphavm 40 path: source.ac-dc.network/alpha-delta-network/alphavm 41 purpose: alpha_chain_vm 42 source: snarkvm_fork 43 - name: alphaos 44 path: source.ac-dc.network/alpha-delta-network/alphaos 45 purpose: alpha_node_software 46 source: snarkos_fork 47 - name: deltavm 48 path: source.ac-dc.network/alpha-delta-network/deltavm 49 purpose: delta_chain_vm 50 source: snarkvm_copy 51 - name: deltaos 52 path: source.ac-dc.network/alpha-delta-network/deltaos 53 purpose: delta_node_software 54 source: snarkos_copy 55 tooling: 56 - name: adl 57 path: source.ac-dc.network/alpha-delta-network/adl 58 purpose: smart_contract_compiler 59 source: leo_derived 60 - name: acdc-core 61 path: source.ac-dc.network/alpha-delta-network/acdc-core 62 purpose: shared_utilities 63 source: aleo-std 64 - name: sdk 65 path: source.ac-dc.network/alpha-delta-network/sdk 66 purpose: developer_sdk 67 source: aleo-sdk 68 - name: adnet 69 path: source.ac-dc.network/alpha-delta-network/adnet 70 purpose: unified_binary 71 combines: [alphavm, alphaos, deltavm, deltaos] 72 - name: ac-dc 73 path: source.ac-dc.network/alpha-delta-network/ac-dc 74 purpose: unified_installer_launcher 75 orchestration: 76 - name: alpha-delta-context 77 path: source.ac-dc.network/alpha-delta-network/alpha-delta-context 78 purpose: project_documentation_context_and_tooling 79 total_repos: 12 80 functions: 81 get_repo_path: {inputs: [repo_name: string], outputs: [path: string]} 82 get_repo_purpose: {inputs: [repo_name: string], outputs: [purpose: string]} 83 list_repos_by_type: {inputs: [type: string], outputs: [repos: array]} 84 85 interface_ci_pipeline: 86 description: CI pipeline execution and status 87 stability: stable 88 available_from: phase_4 89 consumers: [ACDC] 90 provides: 91 stages: [check, build, test, deploy] 92 runner: forgejo_native_shell 93 docker_forbidden: true 94 functions: 95 get_pipeline_status: {inputs: [repo: string, branch: string], outputs: [status: object]} 96 trigger_build: {inputs: [repo: string, branch: string], outputs: [run_id: string]} 97 98 interface_build_system: 99 description: Cargo build configuration and targets 100 stability: stable 101 available_from: phase_3 102 consumers: [ACDC] 103 provides: 104 toolchain: stable 105 workspace_members: [alphavm, deltavm, adnet, sdk] 106 targets: [adnet, sdk, adl] 107 arch: x86_64-unknown-linux-gnu 108 functions: 109 get_build_target: {inputs: [name: string], outputs: [config: object]} 110 list_workspace_members: {inputs: [], outputs: [members: array]} 111 112 interface_adl_compiler: 113 description: ADL compilation functions 114 stability: unstable 115 available_from: phase_5 116 consumers: [] 117 provides: 118 source: leo_derived 119 components: [parser, type_checker, circuit_gen] 120 functions: 121 compile: {inputs: [source: string], outputs: [circuit: object]} 122 type_check: {inputs: [source: string], outputs: [errors: array]} 123 124 # === I001: REPOSITORY STRUCTURE === 125 I001_repo_structure: 126 metadata: 127 id: I001 128 name: repo_structure 129 cascade_priority: 80 130 131 spec: 132 repos: 133 alphavm: 134 source: snarkvm_fork 135 purpose: alpha_chain_vm 136 content: [zk_circuits, record_state, credits.alpha] 137 138 alphaos: 139 source: snarkos_fork 140 purpose: alpha_node_software 141 content: [consensus, p2p, storage, api] 142 143 deltavm: 144 source: snarkvm_copy 145 purpose: delta_chain_vm 146 content: [exchange_engine, governance, account_state] 147 148 deltaos: 149 source: snarkos_copy 150 purpose: delta_node_software 151 content: [consensus, p2p, storage, api] 152 153 adl: 154 source: leo_derived 155 purpose: smart_contract_compiler 156 content: [parser, type_checker, circuit_gen] 157 158 acdc-core: 159 source: aleo-std 160 purpose: shared_utilities 161 content: [crypto, encoding, common_types] 162 163 sdk: 164 source: aleo-sdk 165 purpose: developer_sdk 166 content: [client_lib, wallet, transaction_builder] 167 168 adnet: 169 purpose: unified_binary 170 combines: [alphavm, alphaos, deltavm, deltaos] 171 172 ac-dc: 173 purpose: unified_installer_launcher 174 content: [system_checks, install, setup_wizard, service_mgmt, monitoring] 175 176 tools: 177 alpha-delta-context: 178 purpose: project_documentation_context_and_tooling 179 repo: source.ac-dc.network/alpha-delta-network/alpha-delta-context 180 note: r-wrapper tooling merged from alpha-delta-tooling 181 182 # === I002: FORGEJO/RADICLE VCS === 183 I002_forgejo_radicle: 184 metadata: 185 id: I002 186 name: forgejo_radicle 187 cascade_priority: 80 188 189 spec: 190 forgejo: 191 url: source.ac-dc.network 192 vpc_ip: 10.106.0.2 193 role: [git_hosting, ui, ci_actions] 194 auth: ssh_keys 195 ssh: devops@source.ac-dc.network 196 197 ci_server: 198 url: ci.ac-dc.network 199 vpc_ip: 10.106.0.3 200 role: forgejo_runner 201 specs: 32vCPU/64GB, 500GB_NVMe 202 ssh: ssh -p 2584 devops@ci.ac-dc.network 203 health_api: http://ci.ac-dc.network:8080/health/status 204 205 private_vpc: 206 subnet: 10.106.0.0/20 207 interface: eth1 208 purpose: server_to_server_ci_comms 209 210 radicle: 211 url: rad.ac-dc.network 212 role: decentralized_backup 213 push_flow: forgejo -> radicle_sync 214 215 workflow: 216 dev_push: -> source.ac-dc.network 217 admin_sync: forgejo -> radicle 218 ci_trigger: ci.ac-dc.network (via VPC) 219 220 # === I003: BUILD SYSTEM === 221 I003_build_system: 222 metadata: 223 id: I003 224 name: build_system 225 cascade_priority: 80 226 227 spec: 228 toolchain: 229 lang: rust 230 version: stable # standardized 2026-01-07 231 channels: [stable] # all repos now use stable 232 standardized_repos: 233 - adl: "1.92.0 -> stable" 234 - alphavm: "1.88 -> stable" 235 - deltavm: "1.88 -> stable" 236 - deltaos: "1.88 -> stable" 237 - alphaos: "1.88 -> stable" 238 - sdk: "nightly-2025-08-28 -> stable" 239 - ac-dc: "already stable" 240 - acdc-core: "no toolchain file (uses system)" 241 - adnet: "no toolchain file (uses system)" 242 243 cargo_config: 244 workspace: yes 245 members: [alphavm, deltavm, adnet, sdk] 246 247 build_targets: 248 adnet: unified_validator_binary 249 sdk: client_libraries 250 adl: compiler_binary 251 252 # === I004: CI/CD === 253 I004_ci_cd: 254 metadata: 255 id: I004 256 name: ci_cd 257 cascade_priority: 80 258 259 spec: 260 runner: forgejo_native_shell 261 docker: NO (explicitly_forbidden) 262 263 # === MASTER WORKFLOWS === 264 master_workflows: 265 location: alpha-delta-context/.forgejo/workflows/ 266 rust: rust-master.yml 267 js_ts: js-master.yml 268 python: python-master.yml 269 adl: adl-examples.yml 270 271 # === UNIVERSAL TASK RUNNER (just) === 272 task_runner: 273 tool: just 274 purpose: local_ci_parity # `just ci` == CI pipeline 275 location: alpha-delta-context/justfiles/ 276 files: 277 - common.just: base_commands_all_languages 278 - rust.just: cargo_specific_commands 279 - js.just: npm_pnpm_yarn_commands 280 - python.just: pip_poetry_commands 281 commands: 282 ci: full_pipeline (fmt, lint, audit, test, build) 283 dev: quick_checks (fmt, lint, test) 284 fmt: format_check 285 lint: linter 286 audit: security_audit 287 test: run_tests 288 build: production_build 289 sbom: generate_software_bill_of_materials 290 clean: remove_artifacts 291 292 # === SBOM (Software Bill of Materials) === 293 sbom: 294 purpose: supply_chain_transparency 295 format: spdx_json 296 generation: on_main_branch_merge 297 retention: 90_days 298 tools: 299 rust: cargo-sbom 300 js: cyclonedx-npm 301 python: cyclonedx-bom 302 303 pipeline_stages: 304 verify: 305 - cargo_fmt_check 306 - cargo_clippy 307 - cargo_audit 308 - cargo_deny_licenses 309 - cargo_nextest 310 311 quality: 312 - cargo_llvm_cov (coverage) 313 - cargo_mutants (mutation_testing) 314 - continue_on_error: true 315 316 release: 317 - sbom_generation 318 - artifact_upload 319 - radicle_sync 320 321 # === NIGHTLY QUALITY GATES (2026-01-20) === 322 nightly_workflows: 323 dead_code: 324 schedule: "0 4 * * *" # 04:00 UTC 325 tools: [cargo-machete, knip] 326 repos: ALL 327 mutation_testing: 328 schedule: "0 6 * * *" # 06:00 UTC 329 tool: cargo-mutants 330 repos: RUST_REPOS 331 dashboard_aggregation: 332 schedule: "0 7 * * *" # 07:00 UTC 333 repo: ci-dashboard 334 335 # === CI TOOLING === 336 ci_tools: 337 rust: 338 - cargo-nextest (parallel_test_runner) 339 - cargo-llvm-cov (coverage) 340 - cargo-mutants (mutation_testing) 341 - cargo-audit (security) 342 - cargo-deny (licenses) 343 - cargo-machete (dead_code) 344 - cargo-sbom (supply_chain) 345 typescript: 346 - vitest/jest (testing) 347 - eslint (linting) 348 - knip (dead_code) 349 - cyclonedx-npm (sbom) 350 shared: 351 - grype (sbom_vulnerability_scanner) 352 - pre-commit (git_hooks_framework) 353 354 # === PRE-COMMIT HOOKS === 355 hooks: 356 framework: pre-commit 357 replaces: rusty-hook (deprecated 2026-01-20) 358 config_file: .pre-commit-config.yaml 359 install: "pre-commit install && pre-commit install --hook-type commit-msg" 360 361 # === CI REPORT (AI-Consumable) === 362 ci_report: 363 generator: scripts/ci-report-generator.py 364 output: ci-report.yaml 365 mcp_tools: 366 - remediation_plan(repo) 367 - apply_remediation(repo, action_id) 368 - dashboard_status() 369 370 # === AUTOMATED WORKFLOW RUNNER === 371 automated_workflows: 372 runner: scripts/claude-workflow-runner.py 373 config: scripts/workflows.yaml 374 cron_template: scripts/claude-workflows.cron 375 purpose: scheduled_ai_agent_execution 376 window: "2:00-8:00 UTC daily" # Significant daily code generation 377 workflows: 378 dead-code-cleanup: {schedule: "0 2 * * *", description: "Remove dead code (first)"} 379 dependency-update: {schedule: "0 3 * * *", description: "Update vulnerable deps"} 380 sync-docs: {schedule: "0 4 * * *", description: "Sync cspec to markdown"} 381 mutation-survivors: {schedule: "0 5 * * *", description: "Fix tests missing mutants"} 382 coverage-improve: {schedule: "0 6 * * *", description: "Improve test coverage"} 383 dashboard-check: {schedule: "0 7 * * *", description: "Report fleet health"} 384 ci-repair: {schedule: "0 8 * * *", description: "Fix CI pipelines (last)"} 385 requirements: 386 - Claude Code CLI in PATH 387 - Python 3.8+ with pyyaml 388 - "Global hooks: scripts/setup-workflow-hooks.sh" 389 authentication: 390 option_a: ANTHROPIC_API_KEY (API account, pay-per-use) 391 option_b: "claude login (Max subscription, OAuth persists in ~/.claude/)" 392 token_optimization: 393 input: "cspec-style compressed prompts (~80% reduction)" 394 output: "posttool-output-compression.py (~60-80% reduction)" 395 grammar: "workflow-grammar.yaml (one-time ~500 token overhead)" 396 397 legacy_stages: # Preserved for reference 398 check: 399 - cargo_fmt_check 400 - cargo_clippy 401 402 build: 403 - cargo_build_release 404 - target: [x86_64-unknown-linux-gnu] 405 406 test: 407 - cargo_test 408 - integration_tests 409 410 deploy: 411 - artifact_upload 412 - optional_node_restart 413 414 # === I005: ADL COMPILER === 415 I005_adl_compiler: 416 metadata: 417 id: I005 418 name: adl_compiler 419 cascade_priority: 80 420 421 interface: 422 functions: 423 compile: {inputs: [source: string], outputs: [circuit]} 424 type_check: {inputs: [source: string], outputs: [errors]} 425 426 spec: 427 source: leo_derived 428 purpose: smart_contract_compiler 429 content: [parser, type_checker, circuit_gen] 430 431 changelog: 432 - version: 1.5.0 433 date: 2026-01-20 434 type: feature 435 description: "Add automated Claude Code workflow runner" 436 details: 437 - "Added scripts/claude-workflow-runner.py for scheduled AI agent execution" 438 - "Added scripts/workflows.yaml with 7 predefined workflows" 439 - "Added scripts/claude-workflows.cron template for cron installation" 440 - "Workflows: ci-repair, coverage-improve, mutation-survivors, dead-code-cleanup, dependency-update, dashboard-check, sync-docs" 441 - "Supports dry-run mode and verbose output for testing" 442 breaking: false 443 444 - version: 1.4.0 445 date: 2026-01-20 446 type: feature 447 description: "Comprehensive CI pipeline optimization" 448 details: 449 - "Added nightly workflows: mutation testing (6:00 UTC), dead-code cleanup (4:00 UTC), dashboard aggregation (7:00 UTC)" 450 - "Added grype SBOM vulnerability scanning" 451 - "Added pre-commit framework, replacing deprecated rusty-hook" 452 - "Added deny.toml license compliance to all Rust repos" 453 - "Added ci-report.yaml generator for AI-consumable structured data" 454 - "Added MCP tools: remediation_plan, apply_remediation, dashboard_status" 455 - "Deployed nightly.yml, dead-code.yml to all repos" 456 - "Deployed .pre-commit-config.yaml to all repos" 457 breaking: false 458 459 - version: 1.3.0 460 date: 2026-01-19 461 type: feature 462 description: "Add just task runner and SBOM generation" 463 details: 464 - "Added justfiles/ directory with common.just, rust.just, js.just, python.just" 465 - "Added SBOM generation to rust-master.yml (cargo-sbom, SPDX JSON format)" 466 - "SBOM artifacts retained for 90 days" 467 - "Updated I004_ci_cd with master_workflows, task_runner, and sbom sections" 468 - "`just ci` provides local/CI parity for all language types" 469 breaking: false 470 471 - version: 1.2.1 472 date: 2026-01-12 473 type: enhancement 474 description: "Added alpha-delta-tooling repo to orchestration section" 475 details: 476 - "Added alpha-delta-tooling (workspace_tooling_command_proxy) to interface_repo_structure" 477 - "Added alpha-delta-tooling to I001_repo_structure tools section" 478 - "Updated total_repos from 11 to 12" 479 breaking: false 480 - version: 1.2.0 481 date: 2026-01-08 482 type: interface 483 description: "INFRA Phase 1 complete: Added interface_repo_structure and all infrastructure interfaces" 484 details: 485 - "Added interfaces section with interface_repo_structure, interface_ci_pipeline, interface_build_system, interface_adl_compiler" 486 - "interface_repo_structure provides canonical paths for all 12 repositories" 487 - "Added implementation_status tracking for I001-I005" 488 - "Added ACDC as downstream consumer" 489 - "All 12 repositories documented: 4 core (alphavm, alphaos, deltavm, deltaos), 6 tooling (adl, adl-examples, acdc-core, sdk, adnet, ac-dc), 1 utility (ci-dashboard), 1 context (alpha-delta-context)" 490 affected_interfaces: [interface_repo_structure, interface_ci_pipeline, interface_build_system, interface_adl_compiler] 491 breaking: false 492 - version: 1.1.0 493 date: 2026-01-07 494 type: enhancement 495 description: "Standardized all repos to stable Rust toolchain" 496 details: 497 - "Fixed rust-toolchain.toml in 6 repos: adl, alphavm, deltavm, deltaos, alphaos, sdk" 498 - "Removed non-existent toolchain versions (1.88, 1.92.0, nightly-2025-08-28)" 499 - "Fixed clippy warnings in deltaos/node/consensus/src/ipc_hooks.rs" 500 breaking: false 501 - version: 1.0.0 502 date: 2026-01-07 503 type: initial 504 description: "Migrated from infrastructure.cspec" 505 breaking: false