Closes #687

[mansur-codes]

Description

Implements idempotent and resumable deployment operations for StarForge. Deployment pipelines now persist checkpoints after each successful step, allowing interrupted deployments to safely resume from the last completed step without repeating already-succeeded work. Re-running a fully completed deployment is a safe no-op.

Closes #687

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Changes Made

• Add DeploymentCheckpointManager with atomic JSON persistence (temp-file + rename) to prevent corruption on interrupt
• Add session key derivation using SHA-256 hash of WASM content to detect stale checkpoints when the binary changes between runs
• Add corrupted/unparseable checkpoint recovery — warns and falls back to fresh run instead of crashing
• Add schema_version field to checkpoint files for forward compatibility and migration detection
• Add file locking mechanism (PID-based .lock files with 10-minute staleness detection) to prevent concurrent deployment runs
• Add --fresh / --force flags to starforge deployment-automate run to bypass existing checkpoints
• Add step-by-step resumability to deployment_automation.rs — each of the 5 pipeline steps checks the checkpoint before executing
• Add resumability to deploy_orchestrator.rs for multi-contract stack deployments
• Add docs/DEPLOYMENT_CHECKPOINTS.md — full user and developer guide covering architecture, CLI flags, security, and schema versioning
• Fix pre-existing formatting issues across codebase (cargo fmt)

Testing

How has this been tested?

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

Test Coverage

New test file: tests/deployment_checkpoint_resumability.rs — 9 tests covering:

• Happy path: test_primary_deployment_flow_creates_checkpoint — full run creates valid checkpoint; test_idempotent_reexecution — re-running a completed deployment returns immediately as no-op
• Edge cases: test_interrupted_deployment_resumes_from_checkpoint — steps 1 & 2 pre-populated, pipeline resumes at step 3 without re-running completed steps; test_wasm_content_change_triggers_staleness_reset — modified WASM binary invalidates existing checkpoint; test_orchestrate_resumability_and_idempotency — multi-contract stack skips already-deployed contracts
• Error handling: test_fast_fail_invalid_inputs_and_unsupported_network — invalid WASM path or unsupported network fails fast before touching checkpoint state; test_corrupted_checkpoint_recovery — invalid JSON in checkpoint file is discarded and treated as fresh run; test_schema_version_mismatch_resets — unknown schema version triggers fresh run with warning; test_concurrency_lock_prevents_duplicate_run — second process attempting same session is rejected with clear error

Code Quality Checklist

• My code follows the style guidelines of this project (cargo fmt)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings (cargo clippy -- -D warnings)
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• The CI checks pass (format, clippy, tests) — pending CI run

Breaking Changes

• This PR introduces breaking changes

Documentation

• README.md updated
• DEVELOPER_GUIDE.md updated (if applicable)
• API_REFERENCE.md updated (if applicable)
• New docs/DEPLOYMENT_CHECKPOINTS.md added covering architecture, CLI usage, security notes, and schema versioning

Additional Context

Checkpoint files are persisted under ~/.starforge/checkpoints/<session_key>.json. Sensitive data (private keys, seed phrases) is explicitly excluded from checkpoint state. Checkpoint directory is created with 0700 permissions and individual files with 0600 permissions on Unix systems.

The --fresh and --force flags are aliases — both force a clean run ignoring any existing checkpoint for the session.

[drips-wave]

@mansur-codes Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits