Feature: Introduce Typed Status Enums and Transition Guards

[3m1n3nc3]

Description

Replace free-form status strings with enums and domain-owned transition guards.

File Location

learnault-api/prisma/schema.prisma, learnault-api/src/types/, learnault-api/src/domain/, and migrations

Design Reference

API Roadmap Phase 0: Introduce Typed Status Enums and Transition Guards.

Dependencies

• Status: Blocked
• Blocked by: Feature: Repair Clean Install and Prisma Generation; Feature: Define Backend Domain Module Boundaries
• Blocks: Feature: Add Transaction Outbox and Job Delivery Foundation; API Phase 1 session and wallet models

Tasks

• Inventory statuses for transactions, sync, webhooks, notifications, users, and jobs
• Define Prisma and TypeScript enums
• Implement legal transition functions
• Migrate known values and reject unknown legacy values
• Update DTOs, filters, fixtures, and OpenAPI schemas
• Add transition-table and migration tests

Acceptance Criteria

• Covered statuses reject arbitrary strings
• State changes use tested guards
• Unknown legacy values are reported
• Build and tests pass

Verification Evidence

• Attach transition matrix, migration dry-run, and transition tests

Difficulty

Advanced

[NoobFaris]

Hi Maintainer, I’d love to take this on. I’ve gone through the requirements and will make sure the implementation follows the spec with a clean, well-tested PR. Thanks!

[teethaking]

Hey maintainer,
I'll step in and resolve this block on Phase 1 development immediately. Leaving state transitions to free-form strings is a silent reliability killer—it inevitably leads to invalid database states, missing notifications, or bypassed business rules because a typo (like "processing" vs "processed") crept into a write handler.
Here is my direct implementation plan to lock down our status states and enforce robust domain-driven transition rules in learnault-api:

1. Database Schema & Type Safety

• Prisma Enum Defs: I will modify learnault-api/prisma/schema.prisma to declare explicit, database-enforced native enums for:
  • Transactions: TransactionStatus (PENDING, PROCESSING, SUCCESSFUL, FAILED, CANCELLED)
  • Sync / Jobs: JobStatus (QUEUED, RUNNING, COMPLETED, FAILED, STUCK)
  • Notifications / Webhooks: DeliveryStatus (QUEUED, DELIVERED, FAILED, RETRYING)
• Type Mirroring: I will export matching TypeScript namespaces and type guards from learnault-api/src/types/ to ensure full compile-time safety across our services and DTOs.

2. Domain-Owned Transition Guards
   I will build a centralized state-machine validator inside learnault-api/src/domain/ to protect our tables from invalid state transitions.
   Here is an example structure of the Transaction State Transition Matrix I will enforce:
   | Current State | Target State | Permitted? | Guard / Condition |
   |---|---|---|---|
   | PENDING | PROCESSING | Yes | Transition to lock resource |
   | PENDING | CANCELLED | Yes | Explicit user action |
   | PROCESSING | SUCCESSFUL | Yes | Requires on-chain/processor receipt |
   | PROCESSING | FAILED | Yes | Records terminal failure metadata |
   | SUCCESSFUL | Any | No | Terminal state; absolutely immutable |
   | FAILED | PENDING | No | Retry logic must spawn a new transaction |
   Any state change request will flow through a strict domain function like validateTransactionTransition(current, target), returning a structured result or throwing a domain-specific InvalidStateTransitionError.
3. Migration & Backward Compatibility

• SQL Migration: I will generate a clean Prisma migration that safely casts the old string columns to the new database enums.
• Sanitization Script: The migration script will include a safe fallback to capture and log any unrecognized legacy strings, mapping them to a safe default (e.g., FAILED or STUCK) instead of dropping records or failing the migration.
• API Boundary Update: I will update our Swagger schemas in learnault-api/src/config/swagger.ts so that OpenAPI models explicitly list the allowed enum parameters instead of generic string types.
  I will write a comprehensive unit test suite in learnault-api/src/domain/tests/stateTransitions.test.ts asserting every valid and invalid pathway on our transition matrix. Go ahead and assign this issue to me, and I'll drop a clean, type-safe PR!

[grantfox-oss]

🦊 GrantFox — @teethaking has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #65)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@teethaking's PR #104 was approved and merged by @3m1n3nc3.

🏆 @teethaking: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (414 total points). Track your full progress on GrantFox.

👏 Great work, @teethaking! Keep contributing to learnault.