1  # A004-gid_system.plan.cspec
  2  # Implementation plan for Global Identity (GID) System - Governor Registry
  3  
  4  # === PLAN METADATA ===
  5  plan_metadata:
  6    component_id: A004
  7    component_ref: components/alpha/A004-gid_system.component.cspec
  8    plan_version: 1.2.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: 1
 16    is_root: false
 17    upstream_components: [A001]
 18    downstream_components: []
 19    critical_path: true
 20    cascade_group: alpha_governance
 21  
 22  # === PHASES ===
 23  phases:
 24    - phase_id: phase_1
 25      name: "Governor Record & Storage Implementation"
 26      status: complete
 27      blocked_by:
 28        - dependency_ref: A001.phase_1
 29          reason: "Need credits.alpha account model for governor addresses"
 30          wait_for: complete
 31        - dependency_ref: A001.interface_credits_program
 32          reason: "Governor records track cumulative_mint/burn against credits program"
 33          wait_for: interface_stable
 34  
 35      tasks:
 36        - task_id: A004-T001
 37          name: "Define GovernorRecord type"
 38          description: "Create governor record with address, metadata, status, cumulative_mint/burn"
 39          target_files:
 40            - path: alphavm/programs/gid/types.rs
 41              action: create
 42          estimate:
 43            effort: small
 44            confidence: high
 45          risk:
 46            level: low
 47            factors: [well_defined_spec]
 48  
 49        - task_id: A004-T002
 50          name: "Implement GID storage mapping"
 51          description: "Create mapping<address, GovernorRecord> for governor registry"
 52          target_files:
 53            - path: alphavm/programs/gid/storage.rs
 54              action: create
 55          estimate:
 56            effort: small
 57            confidence: high
 58          risk:
 59            level: low
 60            factors: []
 61  
 62        - task_id: A004-T003
 63          name: "Create GID program module structure"
 64          description: "Set up gid program as privileged contract alongside credits.alpha"
 65          target_files:
 66            - path: alphavm/programs/gid/mod.rs
 67              action: create
 68            - path: alphavm/programs/gid/lib.rs
 69              action: create
 70          estimate:
 71            effort: small
 72            confidence: high
 73          risk:
 74            level: medium
 75            factors: [privileged_program_integration]
 76  
 77      deliverables:
 78        - deliverable_id: A004-D001
 79          name: "GovernorRecord type"
 80          type: code
 81          verification: "Type includes all required fields: address, metadata, registration_block, status, cumulative_mint, cumulative_burn"
 82        - deliverable_id: A004-D002
 83          name: "GID storage layer"
 84          type: code
 85          verification: "Mapping storage compiles and integrates with AlphaVM state"
 86  
 87      test_requirements:
 88        unit:
 89          - test_id: A004-UT001
 90            description: "GovernorRecord serialization/deserialization"
 91          - test_id: A004-UT002
 92            description: "GID storage read/write operations"
 93          - test_id: A004-UT003
 94            description: "Status enum validation (active|suspended|removed)"
 95  
 96      success_criteria:
 97        - "GovernorRecord type matches component spec definition"
 98        - "Storage mapping correctly indexes by address"
 99        - "GID program recognized as privileged contract"
100  
101      estimated_duration: 1w
102  
103    - phase_id: phase_2
104      name: "Governor Operations Implementation"
105      status: pending
106      blocked_by:
107        - dependency_ref: A004.phase_1
108          reason: "Need storage layer before implementing operations"
109          wait_for: complete
110        - dependency_ref: A001.interface_whitelisted_ops
111          reason: "Governor ops must be in whitelisted instruction set"
112          wait_for: interface_stable
113  
114      tasks:
115        - task_id: A004-T004
116          name: "Implement register_governor operation"
117          description: "Add governor to registry, requires existing_governor_or_genesis caller + governance_approval"
118          target_files:
119            - path: alphavm/programs/gid/register.rs
120              action: create
121          estimate:
122            effort: medium
123            confidence: medium
124          risk:
125            level: high
126            factors: [governance_approval_integration, genesis_bootstrap]
127  
128        - task_id: A004-T005
129          name: "Implement remove_governor operation"
130          description: "Set governor status to removed, requires critical_vote_passed"
131          target_files:
132            - path: alphavm/programs/gid/remove.rs
133              action: create
134          estimate:
135            effort: medium
136            confidence: medium
137          risk:
138            level: high
139            factors: [governance_vote_verification, irreversibility]
140  
141        - task_id: A004-T006
142          name: "Implement update_policy operation"
143          description: "Allow governance to update fee_rates, limits, thresholds"
144          target_files:
145            - path: alphavm/programs/gid/policy.rs
146              action: create
147          estimate:
148            effort: small
149            confidence: high
150          risk:
151            level: medium
152            factors: [policy_validation]
153  
154        - task_id: A004-T007
155          name: "Implement governor status checks"
156          description: "Utility functions to verify governor is active before mint/burn"
157          target_files:
158            - path: alphavm/programs/gid/checks.rs
159              action: create
160          estimate:
161            effort: small
162            confidence: high
163          risk:
164            level: low
165            factors: []
166  
167      deliverables:
168        - deliverable_id: A004-D003
169          name: "register_governor operation"
170          type: code
171          verification: "Only existing governors or genesis can register new governors"
172        - deliverable_id: A004-D004
173          name: "remove_governor operation"
174          type: code
175          verification: "Requires critical_vote_passed, sets status to removed"
176        - deliverable_id: A004-D005
177          name: "update_policy operation"
178          type: code
179          verification: "Governance can update fee_rates, limits, thresholds"
180        - deliverable_id: A004-D006
181          name: "Governor status checker"
182          type: code
183          verification: "is_active_governor returns correct status"
184  
185      test_requirements:
186        unit:
187          - test_id: A004-UT004
188            description: "register_governor requires valid caller"
189          - test_id: A004-UT005
190            description: "register_governor fails without governance_approval"
191          - test_id: A004-UT006
192            description: "remove_governor requires critical_vote_passed"
193          - test_id: A004-UT007
194            description: "update_policy validates parameter ranges"
195          - test_id: A004-UT008
196            description: "Removed governor cannot perform mint/burn"
197        integration:
198          - test_id: A004-IT001
199            description: "Full governor registration flow from genesis"
200            dependencies: [A004-UT004, A004-UT005]
201          - test_id: A004-IT002
202            description: "Governor removal with vote verification"
203            dependencies: [A004-UT006]
204  
205      success_criteria:
206        - "All 3 operations (register, remove, update_policy) implemented"
207        - "Only existing governors can register new governors"
208        - "Governor removal requires governance vote"
209        - "Status checks prevent removed governors from operating"
210  
211      estimated_duration: 2w
212  
213    - phase_id: phase_3
214      name: "Event Emission & Credits Integration"
215      status: pending
216      blocked_by:
217        - dependency_ref: A004.phase_2
218          reason: "Need operations before emitting events"
219          wait_for: complete
220        - dependency_ref: A001.phase_2
221          reason: "Credits lockdown must be complete before integrating"
222          wait_for: complete
223  
224      tasks:
225        - task_id: A004-T008
226          name: "Implement GID events"
227          description: "Emit governor_registered, governor_removed, policy_updated events"
228          target_files:
229            - path: alphavm/programs/gid/events.rs
230              action: create
231          estimate:
232            effort: small
233            confidence: high
234          risk:
235            level: low
236            factors: []
237  
238        - task_id: A004-T009
239          name: "Integrate GID with credits.alpha mint/burn"
240          description: "Credits mint/burn operations must verify caller is active governor"
241          target_files:
242            - path: alphavm/programs/credits/mint.rs
243              action: modify
244            - path: alphavm/programs/credits/burn.rs
245              action: modify
246          estimate:
247            effort: medium
248            confidence: medium
249          risk:
250            level: high
251            factors: [cross_program_integration, mint_authority_security]
252  
253        - task_id: A004-T010
254          name: "Track cumulative mint/burn per governor"
255          description: "Update GovernorRecord.cumulative_mint/burn on each operation"
256          target_files:
257            - path: alphavm/programs/gid/tracking.rs
258              action: create
259          estimate:
260            effort: small
261            confidence: high
262          risk:
263            level: low
264            factors: []
265  
266      deliverables:
267        - deliverable_id: A004-D007
268          name: "GID event system"
269          type: code
270          verification: "All 3 events emit with correct data"
271        - deliverable_id: A004-D008
272          name: "Credits-GID integration"
273          type: interface
274          verification: "Mint/burn reject non-governor callers"
275        - deliverable_id: A004-D009
276          name: "Cumulative tracking"
277          type: code
278          verification: "Governor records show accurate totals"
279  
280      test_requirements:
281        unit:
282          - test_id: A004-UT009
283            description: "Events emit with correct payload"
284          - test_id: A004-UT010
285            description: "Cumulative tracking increments correctly"
286        integration:
287          - test_id: A004-IT003
288            description: "Mint fails for non-governor"
289            dependencies: [A001-IT001]
290          - test_id: A004-IT004
291            description: "Mint succeeds for active governor, updates cumulative"
292            dependencies: [A004-IT003]
293          - test_id: A004-IT005
294            description: "Full governor lifecycle: register -> mint -> remove -> mint_fails"
295            dependencies: [A004-IT001, A004-IT004]
296  
297      success_criteria:
298        - "All events emit correctly on operations"
299        - "Credits mint/burn enforce governor check"
300        - "Cumulative mint/burn tracked accurately"
301        - "Removed governors cannot mint/burn"
302  
303      estimated_duration: 1w
304  
305    - phase_id: phase_4
306      name: "Security Hardening & Genesis Bootstrap"
307      status: pending
308      blocked_by:
309        - dependency_ref: A004.phase_3
310          reason: "Need full implementation before security hardening"
311          wait_for: complete
312        - dependency_ref: A001.phase_3
313          reason: "Security audit package should include GID"
314          wait_for: started
315  
316      tasks:
317        - task_id: A004-T011
318          name: "Implement genesis governor bootstrap"
319          description: "Define mechanism to register initial governors at chain genesis"
320          target_files:
321            - path: alphavm/programs/gid/genesis.rs
322              action: create
323            - path: alphavm/genesis/config.rs
324              action: modify
325          estimate:
326            effort: medium
327            confidence: medium
328          risk:
329            level: high
330            factors: [genesis_security, initial_trust]
331  
332        - task_id: A004-T012
333          name: "Encrypted metadata handling"
334          description: "Implement secure storage for encrypted governor metadata blobs"
335          target_files:
336            - path: alphavm/programs/gid/metadata.rs
337              action: create
338          estimate:
339            effort: medium
340            confidence: medium
341          risk:
342            level: medium
343            factors: [encryption_correctness]
344  
345        - task_id: A004-T013
346          name: "GID security audit preparation"
347          description: "Document GID attack surface and security properties"
348          target_files:
349            - path: audit/A004_gid_system_audit_package.md
350              action: create
351          estimate:
352            effort: small
353            confidence: high
354          risk:
355            level: low
356            factors: []
357  
358      deliverables:
359        - deliverable_id: A004-D010
360          name: "Genesis bootstrap mechanism"
361          type: code
362          verification: "Initial governors can be set at genesis"
363        - deliverable_id: A004-D011
364          name: "Metadata encryption"
365          type: code
366          verification: "Metadata stored as encrypted blob, only owner can decrypt"
367        - deliverable_id: A004-D012
368          name: "GID audit package"
369          type: documentation
370          verification: "Ready for external auditor review"
371  
372      test_requirements:
373        unit:
374          - test_id: A004-UT011
375            description: "Genesis governors are active post-genesis"
376          - test_id: A004-UT012
377            description: "Metadata encryption/decryption roundtrip"
378        integration:
379          - test_id: A004-IT006
380            description: "Full genesis to first non-genesis governor flow"
381            dependencies: [A004-IT001, A004-IT005]
382  
383      success_criteria:
384        - "Genesis bootstrap creates valid initial governors"
385        - "Metadata properly encrypted at rest"
386        - "Audit package documents all security considerations"
387        - "No privilege escalation paths exist"
388  
389      estimated_duration: 1w
390  
391  # === PARALLEL WORKSTREAMS ===
392  # Tests, CI, and docs evolve alongside implementation
393  parallel_workstreams:
394  
395    testing:
396      strategy: test_alongside
397      coverage_targets:
398        unit_minimum: 80
399        integration_required: true
400  
401      per_phase_requirements:
402        - phase_ref: phase_1
403          unit_tests:
404            - GovernorRecord serialization/deserialization
405            - GID storage read/write operations
406            - Status enum validation (active|suspended|removed)
407          test_files:
408            - path: alphavm/programs/gid/tests/types_tests.rs
409              action: create
410            - path: alphavm/programs/gid/tests/storage_tests.rs
411              action: create
412  
413        - phase_ref: phase_2
414          unit_tests:
415            - register_governor requires valid caller
416            - register_governor fails without governance_approval
417            - remove_governor requires critical_vote_passed
418            - update_policy validates parameter ranges
419            - Removed governor cannot perform mint/burn
420          integration_tests:
421            - Full governor registration flow from genesis
422            - Governor removal with vote verification
423          test_files:
424            - path: alphavm/programs/gid/tests/register_tests.rs
425              action: create
426            - path: alphavm/programs/gid/tests/remove_tests.rs
427              action: create
428            - path: alphavm/programs/gid/tests/policy_tests.rs
429              action: create
430            - path: alphavm/tests/gid_integration.rs
431              action: create
432  
433        - phase_ref: phase_3
434          unit_tests:
435            - Events emit with correct payload
436            - Cumulative tracking increments correctly
437          integration_tests:
438            - Mint fails for non-governor
439            - Mint succeeds for active governor, updates cumulative
440            - Full governor lifecycle (register -> mint -> remove -> mint_fails)
441          test_files:
442            - path: alphavm/programs/gid/tests/events_tests.rs
443              action: create
444            - path: alphavm/programs/gid/tests/tracking_tests.rs
445              action: create
446            - path: alphavm/tests/credits_gid_integration.rs
447              action: create
448  
449        - phase_ref: phase_4
450          unit_tests:
451            - Genesis governors are active post-genesis
452            - Metadata encryption/decryption roundtrip
453          integration_tests:
454            - Full genesis to first non-genesis governor flow
455          test_files:
456            - path: alphavm/programs/gid/tests/genesis_tests.rs
457              action: create
458            - path: alphavm/programs/gid/tests/metadata_tests.rs
459              action: create
460            - path: alphavm/tests/genesis_integration.rs
461              action: create
462  
463      ci_test_gates:
464        - gate_id: unit_tests
465          command: cargo test --package alphavm-gid
466          required: true
467        - gate_id: integration_tests
468          command: cargo test --test '*gid*' --package alphavm
469          required: true
470        - gate_id: clippy
471          command: cargo clippy --package alphavm-gid -- -D warnings
472          required: true
473        - gate_id: fmt
474          command: cargo fmt --check
475          required: true
476  
477    ci_workflows:
478      affected_workflows:
479        - workflow_file: .forgejo/workflows/ci.yml
480          repo: alphavm
481          triggers: [phase_1, phase_2, phase_3, phase_4]
482  
483      per_phase_ci_tasks:
484        - phase_ref: phase_1
485          workflow_changes:
486            - file: .forgejo/workflows/ci.yml
487              change_type: add_job
488              description: Add GID program build and test job
489  
490        - phase_ref: phase_2
491          workflow_changes:
492            - file: .forgejo/workflows/ci.yml
493              change_type: add_step
494              description: Add governor operations integration tests
495  
496        - phase_ref: phase_3
497          workflow_changes:
498            - file: .forgejo/workflows/ci.yml
499              change_type: add_step
500              description: Add credits-GID integration test step
501  
502        - phase_ref: phase_4
503          workflow_changes:
504            - file: .forgejo/workflows/ci.yml
505              change_type: add_step
506              description: Add genesis bootstrap integration test
507  
508      required_ci_checks:
509        - check_name: build
510          check_type: build
511          blocking: true
512        - check_name: test
513          check_type: test
514          blocking: true
515        - check_name: clippy
516          check_type: lint
517          blocking: true
518        - check_name: fmt
519          check_type: lint
520          blocking: true
521  
522    documentation:
523      cspec_update_policy: on_interface_change
524  
525      component_cspec_updates:
526        - cspec_file: components/alpha/A004-gid_system.component.cspec
527          update_triggers:
528            - phase_ref: phase_1
529              fields_to_update: [implementation_status]
530              description: Mark governor record and storage complete
531            - phase_ref: phase_2
532              fields_to_update: [implementation_status, interfaces]
533              description: Mark governor operations interface available
534            - phase_ref: phase_3
535              fields_to_update: [implementation_status, interfaces]
536              description: Mark credits-GID integration complete
537            - phase_ref: phase_4
538              fields_to_update: [implementation_status, interfaces]
539              description: Mark all GID interfaces stable
540  
541      session_logging:
542        required: true
543        log_location: sessions/
544        log_format: cspec
545        log_triggers:
546          - phase_complete
547          - blocker_encountered
548          - interface_change
549          - major_decision
550          - governance_integration_decision
551          - genesis_bootstrap_decision
552  
553      changelog_policy:
554        update_frequency: per_phase
555        required_fields:
556          - version
557          - date
558          - type
559          - description
560          - affected_interfaces
561  
562      human_doc_derivation:
563        target_human_doc: project/architecture/human/gid-system.md
564        regenerate_triggers:
565          - phase_2  # Governor operations defined
566          - phase_4  # Genesis and security complete
567  
568  # === INTERFACE COMMITMENTS ===
569  interface_commitments:
570    provides:
571      - interface_id: interface_governor_registry
572        name: "Governor Registry Interface"
573        stability: unstable
574        available_from: phase_1
575        stable_from: phase_4
576        consumers: []
577        description: "Mapping of addresses to GovernorRecord for privilege lookup"
578  
579      - interface_id: interface_governor_operations
580        name: "Governor Operations Interface"
581        stability: unstable
582        available_from: phase_2
583        stable_from: phase_4
584        consumers: []
585        description: "register_governor, remove_governor, update_policy operations"
586  
587      - interface_id: interface_mint_authority_check
588        name: "Mint Authority Check Interface"
589        stability: unstable
590        available_from: phase_3
591        stable_from: phase_4
592        consumers: [A001]
593        description: "is_active_governor check for credits.alpha mint/burn authorization"
594  
595    requires:
596      - interface_ref: A001.interface_credits_program
597        minimum_stability: unstable
598        required_from: phase_1
599      - interface_ref: A001.interface_whitelisted_ops
600        minimum_stability: unstable
601        required_from: phase_2
602  
603  # === REPOSITORY TARGETS ===
604  repository_targets:
605    primary_repo:
606      name: alphavm
607      branch_strategy: feature_branch
608      feature_branch_name: feat/A004-gid-system
609  
610    file_manifest:
611      # Phase 1 - Core types and storage
612      - path: alphavm/programs/gid/mod.rs
613        action: create
614        purpose: "GID program module root"
615        phase: phase_1
616      - path: alphavm/programs/gid/lib.rs
617        action: create
618        purpose: "GID program library entry"
619        phase: phase_1
620      - path: alphavm/programs/gid/types.rs
621        action: create
622        purpose: "GovernorRecord type definition"
623        phase: phase_1
624      - path: alphavm/programs/gid/storage.rs
625        action: create
626        purpose: "Governor registry mapping storage"
627        phase: phase_1
628  
629      # Phase 2 - Operations
630      - path: alphavm/programs/gid/register.rs
631        action: create
632        purpose: "register_governor operation"
633        phase: phase_2
634      - path: alphavm/programs/gid/remove.rs
635        action: create
636        purpose: "remove_governor operation"
637        phase: phase_2
638      - path: alphavm/programs/gid/policy.rs
639        action: create
640        purpose: "update_policy operation"
641        phase: phase_2
642      - path: alphavm/programs/gid/checks.rs
643        action: create
644        purpose: "Governor status verification utilities"
645        phase: phase_2
646  
647      # Phase 3 - Events and integration
648      - path: alphavm/programs/gid/events.rs
649        action: create
650        purpose: "GID event emission"
651        phase: phase_3
652      - path: alphavm/programs/gid/tracking.rs
653        action: create
654        purpose: "Cumulative mint/burn tracking"
655        phase: phase_3
656      - path: alphavm/programs/credits/mint.rs
657        action: modify
658        purpose: "Add governor check to mint"
659        phase: phase_3
660      - path: alphavm/programs/credits/burn.rs
661        action: modify
662        purpose: "Add governor check to burn"
663        phase: phase_3
664  
665      # Phase 4 - Genesis and security
666      - path: alphavm/programs/gid/genesis.rs
667        action: create
668        purpose: "Genesis governor bootstrap"
669        phase: phase_4
670      - path: alphavm/programs/gid/metadata.rs
671        action: create
672        purpose: "Encrypted metadata handling"
673        phase: phase_4
674      - path: alphavm/genesis/config.rs
675        action: modify
676        purpose: "Genesis config for initial governors"
677        phase: phase_4
678      - path: audit/A004_gid_system_audit_package.md
679        action: create
680        purpose: "Security audit documentation"
681        phase: phase_4
682  
683    secondary_repos: []
684  
685  # === COMPLEXITY ASSESSMENT ===
686  complexity_assessment:
687    overall_complexity: medium
688    rationale: "Privileged registry is well-scoped, but governance integration and security-critical nature add complexity"
689  
690    risk_summary:
691      - risk_id: RISK-001
692        description: "Genesis bootstrap mechanism could create insecure initial state"
693        likelihood: low
694        impact: critical
695        mitigation: "Careful review of genesis config, multi-sig for initial governors"
696  
697      - risk_id: RISK-002
698        description: "Cross-program call between GID and credits could have edge cases"
699        likelihood: medium
700        impact: high
701        mitigation: "Extensive integration testing, formal verification of call paths"
702  
703      - risk_id: RISK-003
704        description: "Governance approval verification may be complex to implement correctly"
705        likelihood: medium
706        impact: high
707        mitigation: "Define clear governance interfaces, test all approval paths"
708  
709      - risk_id: RISK-004
710        description: "Removed governor status may not propagate correctly"
711        likelihood: low
712        impact: high
713        mitigation: "Synchronous status check on every privileged operation"
714  
715  # === DEPENDENCIES SUMMARY ===
716  dependencies_summary:
717    blocks: []
718    blocked_by: [A001]
719    parallel_candidates: [D001, D002, T001, T002]
720  
721  # === CHANGELOG ===
722  changelog:
723    - version: 1.1.0
724      date: 2026-01-07
725      type: revision
726      description: "Added parallel_workstreams section for testing, CI, and documentation"
727  
728    - version: 1.0.0
729      date: 2026-01-07
730      type: initial
731      description: "Initial implementation plan for A004 GID (Governor Identity) system"