R001-unified_binary.plan.cspec
1 # R001-unified_binary.plan.cspec 2 # Implementation Plan for Unified Binary (adnet) 3 4 # === PLAN METADATA === 5 plan_metadata: 6 component_id: R001 7 component_ref: components/runtime/R001-unified_binary.component.cspec 8 plan_version: 1.1.0 9 plan_status: phase_1_complete 10 created: 2026-01-07 11 updated: 2026-01-09 12 13 # === WAVE CONTEXT === 14 wave_context: 15 topological_level: 0 16 is_root: true 17 upstream_components: [] 18 downstream_components: [R002, R003, R005] 19 critical_path: true 20 cascade_group: runtime 21 22 # === PHASES === 23 phases: 24 - phase_id: phase_1 25 name: Core Binary Structure and CLI Entry 26 status: pending 27 blocked_by: [] 28 29 tasks: 30 - task_id: R001-T001 31 name: Define unified binary CLI entry point 32 description: | 33 Create main.rs with clap-based CLI structure. 34 Commands: run, init, version, config. 35 Subcommands for alpha-only, delta-only, or dual mode. 36 target_files: 37 - path: src/main.rs 38 action: create 39 estimate: 40 effort: medium 41 confidence: high 42 risk: 43 level: low 44 factors: 45 - standard_cli_pattern 46 47 - task_id: R001-T002 48 name: Define binary-wide configuration types 49 description: | 50 Configuration structures for: 51 - Node identity (keypair, peer_id) 52 - Network settings (ports, bootstrap peers) 53 - Chain-specific settings (alpha vs delta) 54 - Storage paths 55 target_files: 56 - path: src/config/mod.rs 57 action: create 58 - path: src/config/types.rs 59 action: create 60 estimate: 61 effort: medium 62 confidence: high 63 risk: 64 level: low 65 factors: 66 - straightforward_config 67 68 - task_id: R001-T003 69 name: Implement configuration loading 70 description: | 71 Load config from: CLI args > env vars > config file > defaults. 72 Support TOML config file format. 73 Validate configuration at startup. 74 target_files: 75 - path: src/config/loader.rs 76 action: create 77 estimate: 78 effort: small 79 confidence: high 80 risk: 81 level: low 82 factors: [] 83 84 deliverables: 85 - deliverable_id: R001-D001 86 name: CLI entry point 87 type: code 88 verification: cargo build --release && ./target/release/adnet --help 89 - deliverable_id: R001-D002 90 name: Configuration module 91 type: code 92 verification: cargo test config:: 93 94 test_requirements: 95 unit: 96 - test_id: R001-U001 97 description: Verify CLI argument parsing 98 - test_id: R001-U002 99 description: Verify config loading priority 100 - test_id: R001-U003 101 description: Verify config validation rejects invalid values 102 103 success_criteria: 104 - Binary compiles and runs with --help 105 - Configuration loads from file, env, and CLI 106 - Invalid configurations rejected with clear errors 107 108 estimated_duration: 2d 109 110 - phase_id: phase_2 111 name: Node Orchestration Module 112 status: pending 113 blocked_by: 114 - dependency_ref: R001.phase_1 115 reason: Requires CLI and config infrastructure 116 wait_for: complete 117 118 tasks: 119 - task_id: R001-T004 120 name: Create node orchestration framework 121 description: | 122 Central node module that: 123 - Initializes shared components (network, storage) 124 - Spawns Alpha and Delta runtimes 125 - Manages graceful shutdown 126 - Handles signals (SIGTERM, SIGINT) 127 target_files: 128 - path: src/node/mod.rs 129 action: create 130 estimate: 131 effort: large 132 confidence: medium 133 risk: 134 level: medium 135 factors: 136 - async_coordination 137 - shutdown_ordering 138 139 - task_id: R001-T005 140 name: Implement shared state manager 141 description: | 142 Thread-safe shared state for: 143 - Peer list (Arc<RwLock>) 144 - Block cache (bounded) 145 - Attestation pool 146 Efficient cross-chain access patterns. 147 target_files: 148 - path: src/node/shared_state.rs 149 action: create 150 estimate: 151 effort: medium 152 confidence: medium 153 risk: 154 level: medium 155 factors: 156 - concurrency_correctness 157 - memory_pressure 158 159 - task_id: R001-T006 160 name: Implement health and metrics 161 description: | 162 Health check endpoint for orchestration. 163 Metrics for: runtime status, memory, threads. 164 Prometheus-compatible exposition format. 165 target_files: 166 - path: src/node/health.rs 167 action: create 168 - path: src/node/metrics.rs 169 action: create 170 estimate: 171 effort: small 172 confidence: high 173 risk: 174 level: low 175 factors: [] 176 177 deliverables: 178 - deliverable_id: R001-D003 179 name: Node orchestration module 180 type: code 181 verification: cargo test node:: 182 - deliverable_id: R001-D004 183 name: Shared state module 184 type: code 185 verification: cargo test node::shared_state 186 - deliverable_id: R001-D005 187 name: Health and metrics 188 type: code 189 verification: curl localhost:9090/metrics 190 191 test_requirements: 192 unit: 193 - test_id: R001-U004 194 description: Verify orchestration startup sequence 195 - test_id: R001-U005 196 description: Verify graceful shutdown on SIGTERM 197 - test_id: R001-U006 198 description: Verify shared state thread safety 199 - test_id: R001-U007 200 description: Verify metrics exposition format 201 202 success_criteria: 203 - Node starts and initializes both runtimes 204 - Graceful shutdown completes within timeout 205 - Shared state accessible from both runtimes 206 - Metrics endpoint serves valid Prometheus data 207 208 estimated_duration: 4d 209 210 - phase_id: phase_3 211 name: Alpha Runtime Integration 212 status: pending 213 blocked_by: 214 - dependency_ref: R001.phase_2 215 reason: Requires orchestration framework 216 wait_for: complete 217 218 tasks: 219 - task_id: R001-T007 220 name: Implement Alpha runtime wrapper 221 description: | 222 AlphaVM runtime with: 223 - Privacy chain state management 224 - Record sparse merkle tree 225 - credits.alpha program execution 226 - 15s block time coordination 227 target_files: 228 - path: src/node/alpha_runtime.rs 229 action: create 230 estimate: 231 effort: large 232 confidence: medium 233 risk: 234 level: high 235 factors: 236 - alphavm_integration 237 - privacy_guarantees 238 - state_complexity 239 240 - task_id: R001-T008 241 name: Implement Alpha API server 242 description: | 243 REST/RPC API on port 3030. 244 Endpoints: balance, transfer, mint, burn. 245 Authentication via signed requests. 246 target_files: 247 - path: src/api/alpha_api.rs 248 action: create 249 estimate: 250 effort: medium 251 confidence: high 252 risk: 253 level: medium 254 factors: 255 - api_security 256 - request_validation 257 258 - task_id: R001-T009 259 name: Alpha P2P networking 260 description: | 261 P2P networking on port 4130. 262 Transaction gossip, block propagation. 263 Integration with unified peer discovery. 264 target_files: 265 - path: src/network/alpha_p2p.rs 266 action: create 267 estimate: 268 effort: medium 269 confidence: medium 270 risk: 271 level: medium 272 factors: 273 - network_partitions 274 - message_ordering 275 276 deliverables: 277 - deliverable_id: R001-D006 278 name: Alpha runtime module 279 type: code 280 verification: cargo test node::alpha_runtime 281 - deliverable_id: R001-D007 282 name: Alpha API server 283 type: code 284 verification: cargo test api::alpha_api 285 - deliverable_id: R001-D008 286 name: Alpha P2P module 287 type: code 288 verification: cargo test network::alpha_p2p 289 290 test_requirements: 291 unit: 292 - test_id: R001-U008 293 description: Verify Alpha runtime initialization 294 - test_id: R001-U009 295 description: Verify 15s block production 296 - test_id: R001-U010 297 description: Verify Alpha API endpoints 298 - test_id: R001-U011 299 description: Verify Alpha P2P message handling 300 integration: 301 - test_id: R001-I001 302 description: Alpha runtime end-to-end transaction flow 303 dependencies: [phase_2] 304 305 success_criteria: 306 - Alpha runtime starts and produces blocks at 15s intervals 307 - API accepts and processes requests on port 3030 308 - P2P network forms and propagates transactions 309 - Runtime emits alpha_runtime_started event 310 311 estimated_duration: 5d 312 313 - phase_id: phase_4 314 name: Delta Runtime Integration 315 status: pending 316 blocked_by: 317 - dependency_ref: R001.phase_2 318 reason: Requires orchestration framework 319 wait_for: complete 320 321 tasks: 322 - task_id: R001-T010 323 name: Implement Delta runtime wrapper 324 description: | 325 DeltaVM runtime with: 326 - Exchange chain state management 327 - Account-based state model 328 - Full VM program execution 329 - 3s block time coordination 330 target_files: 331 - path: src/node/delta_runtime.rs 332 action: create 333 estimate: 334 effort: large 335 confidence: medium 336 risk: 337 level: high 338 factors: 339 - deltavm_integration 340 - exchange_semantics 341 - faster_block_time 342 343 - task_id: R001-T011 344 name: Implement Delta API server 345 description: | 346 REST/RPC API on port 4030. 347 Endpoints: DEX operations, governance, staking. 348 High-throughput request handling. 349 target_files: 350 - path: src/api/delta_api.rs 351 action: create 352 estimate: 353 effort: medium 354 confidence: high 355 risk: 356 level: medium 357 factors: 358 - api_security 359 - throughput_requirements 360 361 - task_id: R001-T012 362 name: Delta P2P networking 363 description: | 364 P2P networking on port 4131. 365 Higher throughput for DEX traffic. 366 Integration with unified peer discovery. 367 target_files: 368 - path: src/network/delta_p2p.rs 369 action: create 370 estimate: 371 effort: medium 372 confidence: medium 373 risk: 374 level: medium 375 factors: 376 - higher_throughput 377 - latency_sensitive 378 379 deliverables: 380 - deliverable_id: R001-D009 381 name: Delta runtime module 382 type: code 383 verification: cargo test node::delta_runtime 384 - deliverable_id: R001-D010 385 name: Delta API server 386 type: code 387 verification: cargo test api::delta_api 388 - deliverable_id: R001-D011 389 name: Delta P2P module 390 type: code 391 verification: cargo test network::delta_p2p 392 393 test_requirements: 394 unit: 395 - test_id: R001-U012 396 description: Verify Delta runtime initialization 397 - test_id: R001-U013 398 description: Verify 3s block production 399 - test_id: R001-U014 400 description: Verify Delta API endpoints 401 - test_id: R001-U015 402 description: Verify Delta P2P message handling 403 integration: 404 - test_id: R001-I002 405 description: Delta runtime end-to-end DEX operation 406 dependencies: [phase_2] 407 408 success_criteria: 409 - Delta runtime starts and produces blocks at 3s intervals 410 - API accepts and processes requests on port 4030 411 - P2P network forms and propagates transactions 412 - Runtime emits delta_runtime_started event 413 414 estimated_duration: 5d 415 416 - phase_id: phase_5 417 name: IPC Channel Implementation 418 status: pending 419 blocked_by: 420 - dependency_ref: R001.phase_3 421 reason: Requires Alpha runtime 422 wait_for: complete 423 - dependency_ref: R001.phase_4 424 reason: Requires Delta runtime 425 wait_for: complete 426 427 tasks: 428 - task_id: R001-T013 429 name: Implement internal IPC channel 430 description: | 431 Cross-chain IPC using internal channels (not network calls). 432 Microsecond latency for attestation. 433 Message types: attestation, state_query, finality_proof. 434 target_files: 435 - path: src/node/ipc.rs 436 action: create 437 estimate: 438 effort: large 439 confidence: medium 440 risk: 441 level: high 442 factors: 443 - cross_chain_semantics 444 - ordering_guarantees 445 - deadlock_prevention 446 447 - task_id: R001-T014 448 name: Implement attestation module 449 description: | 450 Cross-chain attestation over IPC. 451 AlphaVM attestations to DeltaVM. 452 Verifiable proofs without bridge. 453 target_files: 454 - path: src/node/attestation.rs 455 action: create 456 estimate: 457 effort: large 458 confidence: medium 459 risk: 460 level: high 461 factors: 462 - attestation_security 463 - proof_verification 464 465 - task_id: R001-T015 466 name: IPC message serialization 467 description: | 468 Efficient serialization for IPC messages. 469 Zero-copy where possible. 470 Schema versioning for upgrades. 471 target_files: 472 - path: src/node/ipc_types.rs 473 action: create 474 estimate: 475 effort: small 476 confidence: high 477 risk: 478 level: low 479 factors: 480 - schema_evolution 481 482 deliverables: 483 - deliverable_id: R001-D012 484 name: IPC channel module 485 type: code 486 verification: cargo test node::ipc 487 - deliverable_id: R001-D013 488 name: Attestation module 489 type: code 490 verification: cargo test node::attestation 491 - deliverable_id: R001-D014 492 name: IPC types module 493 type: code 494 verification: cargo test node::ipc_types 495 496 test_requirements: 497 unit: 498 - test_id: R001-U016 499 description: Verify IPC channel message delivery 500 - test_id: R001-U017 501 description: Verify microsecond latency target 502 - test_id: R001-U018 503 description: Verify attestation creation and verification 504 - test_id: R001-U019 505 description: Verify IPC serialization round-trip 506 integration: 507 - test_id: R001-I003 508 description: End-to-end cross-chain attestation flow 509 dependencies: [phase_3, phase_4] 510 - test_id: R001-I004 511 description: IPC under load (concurrent attestations) 512 dependencies: [phase_3, phase_4] 513 514 success_criteria: 515 - IPC channel establishes between runtimes 516 - Attestations flow from Alpha to Delta 517 - Latency under 1ms for local attestation 518 - ipc_channel_established event emitted 519 520 estimated_duration: 5d 521 522 - phase_id: phase_6 523 name: Unified Storage Backend 524 status: pending 525 blocked_by: 526 - dependency_ref: R001.phase_2 527 reason: Requires shared state framework 528 wait_for: complete 529 530 tasks: 531 - task_id: R001-T016 532 name: Implement dual-chain storage layer 533 description: | 534 RocksDB backend with column families: 535 - alpha_state, alpha_blocks, alpha_txs 536 - delta_state, delta_blocks, delta_txs 537 - shared_attestations, shared_peers 538 Separate namespaces, shared backend. 539 target_files: 540 - path: src/storage/ledger.rs 541 action: create 542 - path: src/storage/rocksdb.rs 543 action: create 544 estimate: 545 effort: large 546 confidence: medium 547 risk: 548 level: medium 549 factors: 550 - storage_corruption 551 - concurrent_access 552 - disk_pressure 553 554 - task_id: R001-T017 555 name: Implement storage pruning 556 description: | 557 Configurable retention policies per chain. 558 Safe pruning of old blocks and state. 559 Archive node mode option. 560 target_files: 561 - path: src/storage/pruning.rs 562 action: create 563 estimate: 564 effort: medium 565 confidence: medium 566 risk: 567 level: medium 568 factors: 569 - data_loss_prevention 570 - pruning_safety 571 572 - task_id: R001-T018 573 name: Storage backup and recovery 574 description: | 575 Online backup capability. 576 Snapshot creation without stopping node. 577 Recovery from backup. 578 target_files: 579 - path: src/storage/backup.rs 580 action: create 581 estimate: 582 effort: medium 583 confidence: medium 584 risk: 585 level: medium 586 factors: 587 - consistency_during_backup 588 589 deliverables: 590 - deliverable_id: R001-D015 591 name: Storage ledger module 592 type: code 593 verification: cargo test storage::ledger 594 - deliverable_id: R001-D016 595 name: RocksDB backend 596 type: code 597 verification: cargo test storage::rocksdb 598 - deliverable_id: R001-D017 599 name: Pruning module 600 type: code 601 verification: cargo test storage::pruning 602 - deliverable_id: R001-D018 603 name: Backup module 604 type: code 605 verification: cargo test storage::backup 606 607 test_requirements: 608 unit: 609 - test_id: R001-U020 610 description: Verify column family isolation 611 - test_id: R001-U021 612 description: Verify concurrent read/write correctness 613 - test_id: R001-U022 614 description: Verify pruning removes correct data 615 - test_id: R001-U023 616 description: Verify backup creates consistent snapshot 617 integration: 618 - test_id: R001-I005 619 description: Storage under dual-chain load 620 dependencies: [phase_3, phase_4] 621 622 success_criteria: 623 - Both chains read/write to shared backend 624 - No cross-chain data corruption 625 - Pruning reduces disk usage safely 626 - Backups are consistent and restorable 627 628 estimated_duration: 4d 629 630 - phase_id: phase_7 631 name: Unified P2P Network Stack 632 status: pending 633 blocked_by: 634 - dependency_ref: R001.phase_3 635 reason: Requires Alpha P2P 636 wait_for: complete 637 - dependency_ref: R001.phase_4 638 reason: Requires Delta P2P 639 wait_for: complete 640 641 tasks: 642 - task_id: R001-T019 643 name: Implement unified peer discovery 644 description: | 645 Single peer discovery for both chains. 646 DHT-based peer finding. 647 Peer metadata includes chain support. 648 target_files: 649 - path: src/network/p2p.rs 650 action: create 651 - path: src/network/discovery.rs 652 action: create 653 estimate: 654 effort: large 655 confidence: medium 656 risk: 657 level: medium 658 factors: 659 - network_topology 660 - peer_churn 661 662 - task_id: R001-T020 663 name: Implement gossip protocol 664 description: | 665 Efficient gossip for transactions and blocks. 666 Separate topics per chain. 667 Deduplication and rate limiting. 668 target_files: 669 - path: src/network/gossip.rs 670 action: create 671 estimate: 672 effort: medium 673 confidence: medium 674 risk: 675 level: medium 676 factors: 677 - gossip_amplification 678 - spam_prevention 679 680 - task_id: R001-T021 681 name: Network security hardening 682 description: | 683 Peer authentication. 684 Message signing and verification. 685 Eclipse attack prevention. 686 target_files: 687 - path: src/network/security.rs 688 action: create 689 estimate: 690 effort: medium 691 confidence: medium 692 risk: 693 level: high 694 factors: 695 - security_critical 696 - attack_surface 697 698 deliverables: 699 - deliverable_id: R001-D019 700 name: Unified P2P module 701 type: code 702 verification: cargo test network::p2p 703 - deliverable_id: R001-D020 704 name: Peer discovery module 705 type: code 706 verification: cargo test network::discovery 707 - deliverable_id: R001-D021 708 name: Gossip protocol module 709 type: code 710 verification: cargo test network::gossip 711 - deliverable_id: R001-D022 712 name: Network security module 713 type: code 714 verification: cargo test network::security 715 716 test_requirements: 717 unit: 718 - test_id: R001-U024 719 description: Verify peer discovery finds nodes 720 - test_id: R001-U025 721 description: Verify gossip message propagation 722 - test_id: R001-U026 723 description: Verify peer authentication 724 - test_id: R001-U027 725 description: Verify rate limiting prevents spam 726 integration: 727 - test_id: R001-I006 728 description: Multi-node network formation 729 dependencies: [phase_3, phase_4] 730 - test_id: R001-I007 731 description: Network partition recovery 732 dependencies: [phase_3, phase_4] 733 734 success_criteria: 735 - Nodes discover peers automatically 736 - Messages propagate to all interested nodes 737 - Unauthorized peers rejected 738 - Network recovers from partitions 739 740 estimated_duration: 5d 741 742 - phase_id: phase_8 743 name: Integration and System Tests 744 status: pending 745 blocked_by: 746 - dependency_ref: R001.phase_5 747 reason: Requires IPC 748 wait_for: complete 749 - dependency_ref: R001.phase_6 750 reason: Requires storage 751 wait_for: complete 752 - dependency_ref: R001.phase_7 753 reason: Requires networking 754 wait_for: complete 755 756 tasks: 757 - task_id: R001-T022 758 name: Create integration test harness 759 description: | 760 Test harness for multi-node testing. 761 Simulated network conditions. 762 Deterministic test execution. 763 target_files: 764 - path: tests/integration/mod.rs 765 action: create 766 - path: tests/integration/harness.rs 767 action: create 768 estimate: 769 effort: medium 770 confidence: high 771 risk: 772 level: low 773 factors: [] 774 775 - task_id: R001-T023 776 name: Implement full system tests 777 description: | 778 End-to-end tests covering: 779 - Dual-runtime startup and shutdown 780 - Cross-chain attestation flow 781 - Multi-node consensus 782 - Failure and recovery scenarios 783 target_files: 784 - path: tests/integration/dual_runtime_tests.rs 785 action: create 786 - path: tests/integration/cross_chain_tests.rs 787 action: create 788 - path: tests/integration/consensus_tests.rs 789 action: create 790 estimate: 791 effort: large 792 confidence: medium 793 risk: 794 level: medium 795 factors: 796 - test_flakiness 797 - environment_sensitivity 798 799 - task_id: R001-T024 800 name: Performance benchmarks 801 description: | 802 Benchmark suite for: 803 - IPC latency 804 - Block production rate 805 - Transaction throughput 806 - Storage operations 807 target_files: 808 - path: benches/ipc_bench.rs 809 action: create 810 - path: benches/consensus_bench.rs 811 action: create 812 estimate: 813 effort: medium 814 confidence: high 815 risk: 816 level: low 817 factors: [] 818 819 deliverables: 820 - deliverable_id: R001-D023 821 name: Integration test suite 822 type: test 823 verification: cargo test --test '*' 824 - deliverable_id: R001-D024 825 name: Performance benchmarks 826 type: test 827 verification: cargo bench 828 829 test_requirements: 830 integration: 831 - test_id: R001-I008 832 description: Full dual-runtime lifecycle test 833 dependencies: [phase_3, phase_4, phase_5, phase_6, phase_7] 834 - test_id: R001-I009 835 description: Cross-chain attestation under load 836 dependencies: [phase_5] 837 - test_id: R001-I010 838 description: Node restart and state recovery 839 dependencies: [phase_6] 840 - test_id: R001-I011 841 description: Multi-node network consensus 842 dependencies: [phase_7] 843 844 success_criteria: 845 - All integration tests pass 846 - Performance benchmarks meet targets 847 - No memory leaks detected 848 - Graceful degradation under load 849 850 estimated_duration: 4d 851 852 # === PARALLEL WORKSTREAMS === 853 # Tests, CI, and docs evolve alongside implementation 854 parallel_workstreams: 855 856 testing: 857 strategy: test_alongside 858 coverage_targets: 859 unit_minimum: 80 860 integration_required: true 861 862 per_phase_requirements: 863 - phase_ref: phase_1 864 unit_tests: 865 - CLI argument parsing 866 - Config loading priority 867 - Config validation 868 test_files: 869 - path: src/config/tests.rs 870 action: create 871 - path: src/main_tests.rs 872 action: create 873 874 - phase_ref: phase_2 875 unit_tests: 876 - Orchestration startup sequence 877 - Graceful shutdown 878 - Shared state thread safety 879 - Metrics exposition 880 test_files: 881 - path: src/node/tests.rs 882 action: create 883 884 - phase_ref: phase_3 885 unit_tests: 886 - Alpha runtime initialization 887 - 15s block timing 888 - Alpha API endpoints 889 - Alpha P2P message handling 890 integration_tests: 891 - Alpha end-to-end transaction flow 892 test_files: 893 - path: src/node/alpha_runtime_tests.rs 894 action: create 895 - path: tests/integration/alpha_e2e.rs 896 action: create 897 898 - phase_ref: phase_4 899 unit_tests: 900 - Delta runtime initialization 901 - 3s block timing 902 - Delta API endpoints 903 - Delta P2P message handling 904 integration_tests: 905 - Delta end-to-end DEX operation 906 test_files: 907 - path: src/node/delta_runtime_tests.rs 908 action: create 909 - path: tests/integration/delta_e2e.rs 910 action: create 911 912 - phase_ref: phase_5 913 unit_tests: 914 - IPC channel message delivery 915 - Microsecond latency verification 916 - Attestation creation/verification 917 - IPC serialization round-trip 918 integration_tests: 919 - End-to-end cross-chain attestation 920 - IPC under concurrent load 921 test_files: 922 - path: src/node/ipc_tests.rs 923 action: create 924 - path: tests/integration/cross_chain.rs 925 action: create 926 927 - phase_ref: phase_6 928 unit_tests: 929 - Column family isolation 930 - Concurrent read/write correctness 931 - Pruning removes correct data 932 - Backup consistency 933 test_files: 934 - path: src/storage/tests.rs 935 action: create 936 937 - phase_ref: phase_7 938 unit_tests: 939 - Peer discovery 940 - Gossip propagation 941 - Peer authentication 942 - Rate limiting 943 integration_tests: 944 - Multi-node network formation 945 - Network partition recovery 946 test_files: 947 - path: src/network/tests.rs 948 action: create 949 - path: tests/integration/network.rs 950 action: create 951 952 - phase_ref: phase_8 953 integration_tests: 954 - Full dual-runtime lifecycle 955 - Cross-chain attestation under load 956 - Node restart and recovery 957 - Multi-node consensus 958 test_files: 959 - path: tests/integration/mod.rs 960 action: create 961 - path: tests/integration/harness.rs 962 action: create 963 - path: benches/ipc_bench.rs 964 action: create 965 - path: benches/consensus_bench.rs 966 action: create 967 968 ci_test_gates: 969 - gate_id: unit_tests 970 command: cargo test --workspace 971 required: true 972 - gate_id: integration_tests 973 command: cargo test --test '*' 974 required: true 975 - gate_id: clippy 976 command: cargo clippy --workspace -- -D warnings 977 required: true 978 - gate_id: fmt 979 command: cargo fmt --check 980 required: true 981 982 ci_workflows: 983 affected_workflows: 984 - workflow_file: .forgejo/workflows/ci.yml 985 repo: adnet 986 triggers: [phase_1, phase_3, phase_4, phase_8] 987 988 per_phase_ci_tasks: 989 - phase_ref: phase_1 990 workflow_changes: 991 - file: .forgejo/workflows/ci.yml 992 change_type: modify_job 993 description: Ensure basic build and test job exists 994 995 - phase_ref: phase_3 996 workflow_changes: 997 - file: .forgejo/workflows/ci.yml 998 change_type: add_step 999 description: Add Alpha runtime integration test step 1000 1001 - phase_ref: phase_4 1002 workflow_changes: 1003 - file: .forgejo/workflows/ci.yml 1004 change_type: add_step 1005 description: Add Delta runtime integration test step 1006 1007 - phase_ref: phase_8 1008 workflow_changes: 1009 - file: .forgejo/workflows/ci.yml 1010 change_type: add_job 1011 description: Add benchmarks job (non-blocking) 1012 - file: .forgejo/workflows/ci.yml 1013 change_type: add_artifact 1014 description: Archive benchmark results 1015 1016 required_ci_checks: 1017 - check_name: build 1018 check_type: build 1019 blocking: true 1020 - check_name: test 1021 check_type: test 1022 blocking: true 1023 - check_name: clippy 1024 check_type: lint 1025 blocking: true 1026 - check_name: fmt 1027 check_type: lint 1028 blocking: true 1029 - check_name: bench 1030 check_type: bench 1031 blocking: false 1032 1033 documentation: 1034 cspec_update_policy: on_interface_change 1035 1036 component_cspec_updates: 1037 - cspec_file: components/runtime/R001-unified_binary.component.cspec 1038 update_triggers: 1039 - phase_ref: phase_1 1040 fields_to_update: [implementation_status] 1041 description: Mark CLI foundation complete 1042 - phase_ref: phase_5 1043 fields_to_update: [implementation_status, interfaces] 1044 description: Mark IPC interface as available 1045 - phase_ref: phase_8 1046 fields_to_update: [implementation_status, interfaces] 1047 description: Mark all interfaces stable 1048 1049 session_logging: 1050 required: true 1051 log_location: sessions/ 1052 log_format: cspec 1053 log_triggers: 1054 - phase_complete 1055 - blocker_encountered 1056 - interface_change 1057 - major_decision 1058 - cross_component_coordination 1059 1060 changelog_policy: 1061 update_frequency: per_phase 1062 required_fields: 1063 - version 1064 - date 1065 - type 1066 - description 1067 - affected_interfaces 1068 1069 human_doc_derivation: 1070 target_human_doc: project/architecture/human/unified-binary.md 1071 regenerate_triggers: 1072 - phase_5 # IPC interface stable 1073 - phase_8 # All interfaces stable 1074 1075 # === INTERFACE COMMITMENTS === 1076 interface_commitments: 1077 provides: 1078 - interface_id: interface_adnet_binary 1079 name: Unified adnet Binary Interface 1080 stability: unstable 1081 available_from: phase_1 1082 stable_from: phase_8 1083 consumers: [R002, R003, R005, N001, N002, N003] 1084 1085 - interface_id: interface_ipc_channel 1086 name: Internal IPC Channel Interface 1087 stability: experimental 1088 available_from: phase_5 1089 stable_from: phase_8 1090 consumers: [R005] 1091 1092 - interface_id: interface_dual_runtime 1093 name: Dual Runtime Orchestration Interface 1094 stability: experimental 1095 available_from: phase_2 1096 stable_from: phase_8 1097 consumers: [R002, R003] 1098 1099 - interface_id: interface_alpha_api 1100 name: Alpha Chain API Interface 1101 stability: unstable 1102 available_from: phase_3 1103 stable_from: phase_8 1104 consumers: [A001, A002, A003] 1105 1106 - interface_id: interface_delta_api 1107 name: Delta Chain API Interface 1108 stability: unstable 1109 available_from: phase_4 1110 stable_from: phase_8 1111 consumers: [D001, D002, D003] 1112 1113 - interface_id: interface_unified_storage 1114 name: Unified Storage Backend Interface 1115 stability: experimental 1116 available_from: phase_6 1117 stable_from: phase_8 1118 consumers: [R002, R003] 1119 1120 - interface_id: interface_unified_p2p 1121 name: Unified P2P Network Interface 1122 stability: experimental 1123 available_from: phase_7 1124 stable_from: phase_8 1125 consumers: [R002, R003] 1126 1127 requires: [] 1128 1129 # === REPOSITORY TARGETS === 1130 repository_targets: 1131 primary_repo: 1132 name: adnet 1133 branch_strategy: feature_branch 1134 1135 file_manifest: 1136 # Phase 1: Core Binary Structure 1137 - path: src/main.rs 1138 action: create 1139 purpose: CLI entry point 1140 phase: phase_1 1141 - path: src/config/mod.rs 1142 action: create 1143 purpose: Configuration module root 1144 phase: phase_1 1145 - path: src/config/types.rs 1146 action: create 1147 purpose: Configuration type definitions 1148 phase: phase_1 1149 - path: src/config/loader.rs 1150 action: create 1151 purpose: Configuration loading logic 1152 phase: phase_1 1153 1154 # Phase 2: Node Orchestration 1155 - path: src/node/mod.rs 1156 action: create 1157 purpose: Node orchestration framework 1158 phase: phase_2 1159 - path: src/node/shared_state.rs 1160 action: create 1161 purpose: Thread-safe shared state 1162 phase: phase_2 1163 - path: src/node/health.rs 1164 action: create 1165 purpose: Health check endpoint 1166 phase: phase_2 1167 - path: src/node/metrics.rs 1168 action: create 1169 purpose: Prometheus metrics 1170 phase: phase_2 1171 1172 # Phase 3: Alpha Runtime 1173 - path: src/node/alpha_runtime.rs 1174 action: create 1175 purpose: AlphaVM runtime wrapper 1176 phase: phase_3 1177 - path: src/api/alpha_api.rs 1178 action: create 1179 purpose: Alpha REST/RPC API 1180 phase: phase_3 1181 - path: src/network/alpha_p2p.rs 1182 action: create 1183 purpose: Alpha P2P networking 1184 phase: phase_3 1185 1186 # Phase 4: Delta Runtime 1187 - path: src/node/delta_runtime.rs 1188 action: create 1189 purpose: DeltaVM runtime wrapper 1190 phase: phase_4 1191 - path: src/api/delta_api.rs 1192 action: create 1193 purpose: Delta REST/RPC API 1194 phase: phase_4 1195 - path: src/network/delta_p2p.rs 1196 action: create 1197 purpose: Delta P2P networking 1198 phase: phase_4 1199 1200 # Phase 5: IPC Channel 1201 - path: src/node/ipc.rs 1202 action: create 1203 purpose: Internal IPC channel 1204 phase: phase_5 1205 - path: src/node/attestation.rs 1206 action: create 1207 purpose: Cross-chain attestation 1208 phase: phase_5 1209 - path: src/node/ipc_types.rs 1210 action: create 1211 purpose: IPC message types 1212 phase: phase_5 1213 1214 # Phase 6: Storage Backend 1215 - path: src/storage/ledger.rs 1216 action: create 1217 purpose: Dual-chain ledger abstraction 1218 phase: phase_6 1219 - path: src/storage/rocksdb.rs 1220 action: create 1221 purpose: RocksDB backend implementation 1222 phase: phase_6 1223 - path: src/storage/pruning.rs 1224 action: create 1225 purpose: Storage pruning logic 1226 phase: phase_6 1227 - path: src/storage/backup.rs 1228 action: create 1229 purpose: Backup and recovery 1230 phase: phase_6 1231 1232 # Phase 7: P2P Network 1233 - path: src/network/p2p.rs 1234 action: create 1235 purpose: Unified P2P stack 1236 phase: phase_7 1237 - path: src/network/discovery.rs 1238 action: create 1239 purpose: Peer discovery 1240 phase: phase_7 1241 - path: src/network/gossip.rs 1242 action: create 1243 purpose: Gossip protocol 1244 phase: phase_7 1245 - path: src/network/security.rs 1246 action: create 1247 purpose: Network security 1248 phase: phase_7 1249 1250 # Phase 8: Integration Tests 1251 - path: tests/integration/mod.rs 1252 action: create 1253 purpose: Integration test module 1254 phase: phase_8 1255 - path: tests/integration/harness.rs 1256 action: create 1257 purpose: Test harness 1258 phase: phase_8 1259 - path: tests/integration/dual_runtime_tests.rs 1260 action: create 1261 purpose: Dual runtime tests 1262 phase: phase_8 1263 - path: tests/integration/cross_chain_tests.rs 1264 action: create 1265 purpose: Cross-chain tests 1266 phase: phase_8 1267 - path: tests/integration/consensus_tests.rs 1268 action: create 1269 purpose: Consensus tests 1270 phase: phase_8 1271 - path: benches/ipc_bench.rs 1272 action: create 1273 purpose: IPC benchmarks 1274 phase: phase_8 1275 - path: benches/consensus_bench.rs 1276 action: create 1277 purpose: Consensus benchmarks 1278 phase: phase_8 1279 1280 secondary_repos: [] 1281 1282 # === COMPLEXITY ASSESSMENT === 1283 complexity_assessment: 1284 overall_complexity: very_high 1285 1286 risk_summary: 1287 - risk_id: RISK-001 1288 description: AlphaVM and DeltaVM integration complexity 1289 likelihood: high 1290 impact: critical 1291 mitigation: Incremental integration, extensive mocking, clear interfaces 1292 1293 - risk_id: RISK-002 1294 description: Cross-chain IPC ordering and deadlock 1295 likelihood: medium 1296 impact: high 1297 mitigation: Async channels, timeout handling, deadlock detection 1298 1299 - risk_id: RISK-003 1300 description: Concurrent access to shared state 1301 likelihood: medium 1302 impact: high 1303 mitigation: RwLock granularity, lock ordering discipline, testing 1304 1305 - risk_id: RISK-004 1306 description: Storage corruption under dual-chain writes 1307 likelihood: low 1308 impact: critical 1309 mitigation: Column family isolation, transactional writes, checksums 1310 1311 - risk_id: RISK-005 1312 description: Network partition affecting only one chain 1313 likelihood: medium 1314 impact: medium 1315 mitigation: Independent chain operation, graceful degradation 1316 1317 - risk_id: RISK-006 1318 description: Performance regression from unified binary overhead 1319 likelihood: medium 1320 impact: medium 1321 mitigation: Benchmarks, profiling, optimization passes 1322 1323 # === DEPENDENCIES SUMMARY === 1324 dependencies_summary: 1325 blocks: [R002, R003, R005] 1326 blocked_by: [] 1327 parallel_candidates: [] 1328 1329 # === CHANGELOG === 1330 changelog: 1331 - version: 1.1.0 1332 date: 2026-01-07 1333 type: revision 1334 description: "Add parallel_workstreams section (tests, CI, docs)" 1335 affected_interfaces: [] 1336 1337 - version: 1.0.0 1338 date: 2026-01-07 1339 type: initial 1340 description: "Initial implementation plan for unified adnet binary"