Workflow State Contract Repair

1. Repair decision

Decision: CROSS-LAYER WORKFLOW STATE DRIFT FOUND — SAFE LOCAL PATCH AVAILABLE; production records and workers remain unverified.

2. Scope and boundary

Reviewed: Prisma models, services, routes, BullMQ workers, permission helpers, React state mapping, tests, fixtures, docs, and runbook.

Not accessed: production databases, Redis, queues, customer records, external systems, or deployment configuration.

The repository contains onboarding, purchase-approval, and support-escalation workflows. The repair can unify mechanics without inventing who may approve, cancel, reopen, or complete them.

3. Workflow-state contract source register

4. Canonical repository contract

Exact transition graphs are OWNER DECISION REQUIRED where sources disagree.

Safe shared structure

• one typed state set per workflow;
• named transition commands instead of raw status writes;
• current-state, authority, required-data, and version guards;
• explicit terminal-state behavior;
• stable operation identity per transition;
• derived flags from canonical state where practical;
• side effects from the committed result;
• shared transition metadata for UI, API, workers, and bulk tools.

5. Drift findings

F1 — Competing state representations

Records persist status beside flags such as is_closed, approved, or completed.

Repair: make status the candidate source of truth and expose derived predicates. Keep legacy fields behind compatibility code until migration is separately approved.

F2 — Raw terminal-state writes

Admin routes assign terminal values without service guards.

Repair: route writes through commands such as approve, cancel, complete, or reopen. Reject unsupported source/target combinations.

F3 — UI/API disagreement

React and API code maintain independent action lists.

Repair: generate actions from shared transition metadata. Server authorization remains authoritative.

F4 — Stale worker transitions

Queued jobs can advance records after cancellation.

Repair: require expected state or workflow version. A delayed job against newer state returns stale_transition.

F5 — Duplicate side effects

Retries repeat notifications or downstream work.

Repair: use stable operation IDs and record the committed result. Replays return it without repeating the same logical effect.

F6 — Terminal-state regression

Bulk actions and callbacks can move terminal records backward.

Repair: define terminal behavior per workflow. If reopen policy is unclear, return policy_required.

F7 — Timestamp drift

Different layers set lifecycle timestamps independently.

Repair: derive or validate timestamps from committed transitions.

F8 — False completion

A worker result can be treated as completion after state changed.

Repair: apply completion only if current state and version still permit it.

6. Safe patch plan

No production rewrite, migration, policy invention, or deployment.

7. Deterministic test matrix

1. Supported transitions succeed only from approved source states.
2. Invalid jumps fail consistently across API and services.
3. Patched paths avoid raw terminal writes.
4. Derived flags match canonical state.
5. A stale BullMQ job cannot advance a canceled record.
6. Replaying one transition produces one logical side effect.
7. Concurrent approvals converge on one committed transition.
8. Terminal records cannot regress without an explicit transition.
9. Late completion cannot override a newer canceled state.
10. UI actions do not invent server transitions.
11. Lifecycle timestamps remain consistent.
12. Dashboard groups use canonical state classification.

8. Verification steps

Run repository-supported workflow tests, then typecheck, lint, and build.

Target transition-table, API/service parity, stale-worker, replay, concurrency, terminal-state, legacy-flag, and dashboard tests.

Search for raw status assignments, duplicated transition maps, stale booleans, jobs mutating without expected state/version, and side effects before commit.

9. Production boundary

Unknown issues may include contradictory legacy flags, impossible historical states, stale jobs, duplicate effects already sent, old app versions, and bulk-action histories.

These require separate reconciliation, migration, rollout, monitoring, and rollback.

10. Human approval request

Safe now: state types, transition commands, guards, replay protection, worker version checks, derived predicates, shared metadata, tests, and docs.

Decisions required: workflow-specific graphs, reopen policy, actor authority, prerequisites, legacy migration, historical cleanup, rollout, and rollback.

Status: PATCH READY FOR LOCAL REVIEW — PRODUCTION RECORDS, HISTORICAL INVALID STATES, QUEUED JOBS, AND DEPLOYED POLICY NOT VERIFIED

11. Suggested commit message

fix(workflows): centralize state transitions and replay guards