Stakeholder Application State Machine

Purpose

This specification defines deterministic, auditable stakeholder onboarding using a DB-backed state machine. It separates onboarding application lifecycle from RBAC/system roles and introduces an outbox table for Kafka-ready publishing in later phases.

States

• DRAFT
• SUBMITTED
• UNDER_REVIEW
• REQUIRES_INFO
• APPROVED
• VERIFIED
• REJECTED
• EXPIRED
• SUSPENDED

Deterministic Transitions

Owner transitions

• DRAFT -> SUBMITTED
• REQUIRES_INFO -> SUBMITTED

Reviewer transitions (Phase R1 enablement)

• SUBMITTED -> UNDER_REVIEW
• UNDER_REVIEW -> REQUIRES_INFO
• UNDER_REVIEW -> APPROVED
• UNDER_REVIEW -> REJECTED
• APPROVED -> VERIFIED
• APPROVED -> EXPIRED (time/policy-driven)
• VERIFIED -> EXPIRED (time/policy-driven)
• ANY -> SUSPENDED (administrative)

Unknown transitions are rejected.

Audit Model

All state mutations append immutable records into:

• stakeholder_application_events

Each event stores:

• actor account id
• event type
• from/to state
• payload JSON
• timestamp

Outbox Pattern (Kafka-ready)

Each successful mutation also appends:

• stakeholder_outbox_events

Current phase does not publish. Future publisher will read published_at IS NULL rows and mark published atomically.

Data Surfaces

• stakeholder_applications: current aggregate state
• stakeholder_application_events: immutable event log
• stakeholder_outbox_events: integration outbox

Phase Scope

R0

• DB-backed state machine
• Owner self-service (draft, submit, list, events)
• Immutable audit + outbox writes

R1

• Reviewer actions enabled at gateway/service
• Reviewer authorization policy gates activated

R2

• Automated expiration/suspension governance workflows
• Outbox producer enabled (Kafka/event bus)