feat(lifecycle): implement deterministic lifecycle state machine for core records (#25)

[jotel-dev]

• Add deterministic state machine engine (DeterministicStateMachine, interfaces, and InvalidStateTransitionException)
• Implement state machines for Portfolio, Transaction, DeFiPosition, User, Invitation, and PaymentOperation
• Add guarded state transition endpoints and deriveStateModel for UI/API consistency
• Add sensitive action audit logging and lifecycle event emissions on critical transitions
• Refactor Portfolio, User, and Transaction entities and services to enforce transition rules
• Add 104 automated tests covering all valid transitions, terminal state invariants, and rejected transitions
• Add documentation in docs/LIFECYCLE_STATE_MACHINES.md

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

closes #25

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 not work as expected)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.

• Unit tests added/updated
• E2E tests added/updated
• Manual testing performed
• Tested in staging environment

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my 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
• 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
• Any dependent changes have been merged and published in downstream modules

Screenshots (if applicable)

If applicable, add screenshots to help explain your changes.

Additional Notes

Add any other information that's important for reviewers to understand this PR.

[drips-wave]

@jotel-dev 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

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @jotel-dev for your contribution!

• PR Title: feat(lifecycle): implement deterministic lifecycle state machine for core records (Trellis API: Implement deterministic lifecycle state machine for core records #25)
• Author: @jotel-dev
• Branch: #25-trellis-api-implement-deterministic-lifecycle-state-machine-for-core-records -> main
• Linked Issues: Closes Trellis API: Implement deterministic lifecycle state machine for core records #25
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.