09 Consequence System

09. Consequence Engine & Accountability State Machine

Architectural specification for the commitment state machine and consequence resolution engine.

---

🔄 Consequence State Machine Diagram

stateDiagram-v2
    [*] --> Active: Task Sealed with Commitment
    Active --> Completed: Proof Verified / Marked Complete (Before Deadline)
    Active --> Breached: Deadline Expired (deadline_at < NOW())
    Breached --> Activated: Sweeper Cron Activates Consequence
    Active --> Waived: Waiver Approved (Grace Period)
    Activated --> Resolved: Consequence Reflection / Penalty Fulfilled
    Completed --> [*]
    Resolved --> [*]
    Waived --> [*]

Loading

---

📜 State Definitions & Invariants

1. Active: The commitment is live. The user has until deadline_at to complete the task or submit proof of work.
2. Completed: The task was successfully completed before deadline expiration. Streak multipliers increment.
3. Breached: The deadline expired without completion. Evaluated server-side by /api/cron/sweep-deadlines.
4. Activated: The consequence payload is unmasked and activated (is_activated = true). Notifications are dispatched.
5. Waived: A grace period waiver request (commitment_waivers) was approved with valid justification.
6. Resolved: The activated consequence penalty has been fulfilled by the user.

---

🎁 Consequence Types & Payloads

Consequence Type	Payload Structure	Execution Details
written_reflection	{ prompt: string, minWords: number }	Mandates a structured post-mortem reflection before unlocking new task creation.
public_declaration	{ message: string, channel: string }	Dispatches an automated breach announcement to linked notification channels.
emergency_task	{ title: string, durationMinutes: number }	Injects an immediate high-priority recovery task into the user's daily planner.
financial_pledge	{ pledgeCents: number, charityId: string }	Records a financial penalty transaction logged against the user's discipline ledger.

---

⏱️ Sweeper Cron Integration (/api/cron/sweep-deadlines)

• Automated 1-minute cron job scans PostgreSQL for expired commitments:

  SELECT * FROM commitments 
  WHERE status = 'active' 
    AND deadline_at < NOW();

• Expired commitments transition status to breached, set tasks.status = 'missed', and execute consequences.is_activated = true.
• Dispatcher pushes deadline breach alerts to user notification channels.