[ayomhide2-web]

PR: Extract a Shared Vault State Machine

Summary

Consolidates vault and milestone lifecycle rules into a single, framework-independent state-machine module shared by the deployed API and the TypeScript monolith. This prevents divergent transition logic and makes lifecycle invariants testable without HTTP or database dependencies.

Changes

• Add "shared/vaultMachine.mjs" with the shared "VAULT_TRANSITIONS" table and pure "validateMilestone" and "failVault" functions.
• Add "shared/vaultMachine.d.ts" to provide TypeScript declarations for the shared module.
• Refactor the deployed validation and failure handlers in "api/index.mjs" to use the shared state machine while preserving existing HTTP responses, status codes, messages, and activity entries.
• Update "src/services/vaultTransitions.ts" to import the shared transition table and preserve its existing exported API.
• Ensure lifecycle functions do not mutate their input objects and use injected timestamps for deterministic behavior.
• Preserve activity timestamp ordering, including the release-after-validation ordering requirement.
• Add property-based tests using "fast-check" to verify lifecycle invariants across randomized vaults and operation sequences.
• Add unit tests for error cases and HTTP snapshot tests to protect existing behavior.

Testing

• Verify terminal states are absorbing and completed vaults have all milestones completed.
• Confirm "failVault" never changes an already-completed milestone.
• Verify the combined count of release and redirect activities never exceeds one across an operation sequence.
• Test error cases for inactive vaults, missing milestones, and already-validated milestones.
• Confirm HTTP lifecycle snapshots remain unchanged after the refactor.
• Verify the monolith and shared module reference the same transition table.
• Run the existing Jest tests and "npm run build".
• Ensure CI passes without new lint or TypeScript errors.

Scope and Design

• Keep the shared module pure, small, and free of framework or database dependencies.
• Preserve existing lifecycle behavior without introducing new routes or changing HTTP contracts.
• Leave database locking, transaction changes, and deadline enforcement to separate issues.

Closes

Closes #1701

[drips-wave]

@ayomhide2-web 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