State machines & business rules
Legend: 🟢 Implemented · 🟡 Partial · 🔴 Not implemented
1. Interview lifecycle
1.1 States
| State | Spec meaning | Implementation |
|---|---|---|
scheduled | Snapshot frozen; credits reserved; invitation queued | 🟢 Enum + scheduleInterview |
in_progress | Live session; meter/recording active | 🟢 startInterview |
disconnected | Recovery window (≤3 min, inside original end) | 🟢 disconnectInterview |
completed | Normal terminal; settlement | 🟢 → SQS → settlement |
abandoned | Recovery/original end elapsed | 🔴 Enum only; no API path |
expired | Sweeper past expiresAt; release | 🔴 No expiry sweeper |
cancelled | Org cancel before start; zero charge | 🟢 + releaseCredits |
failed | Provider/bot fault | 🟢 → settleFailedInterview (0) |
deleted (soft) | deletedAt; filtered from queries | 🟢 Not a status value |
Settlement: orthogonal settledAt + ledger, not a ninth status.
1.2 State diagram
stateDiagram-v2
[*] --> scheduled: create + reserve
scheduled --> in_progress: preflight OK, live starts
scheduled --> cancelled: org/admin cancel
scheduled --> expired: expiresAt sweeper, no session
scheduled --> failed: pre-start fault (allowed by failInterview)
scheduled --> deleted: soft delete
in_progress --> disconnected: connection lost
in_progress --> completed: normal end / booked limit
in_progress --> failed: provider/bot fault
in_progress --> deleted: soft delete (blocked if in_progress)
disconnected --> in_progress: reconnect in window
disconnected --> abandoned: recovery/original end elapses
disconnected --> completed: end while disconnected (allowed)
disconnected --> failed: fault terminal
completed --> [*]: settledAt + ledger settle
abandoned --> [*]: settlement (consumed stand)
failed --> [*]: settledAt + release (0 charge typical)
expired --> [*]: release (0 charge)
cancelled --> [*]: release (0 charge)
note right of scheduled
Side effects: reserve ledger,
join token, invitation
end note
note right of completed
Side effects: settle U,
release unused, report.generate
end note1.3 Valid transitions
| From | To | Trigger (spec) | Side effects (spec) | Status |
|---|---|---|---|---|
| — | scheduled | Interview created | Snapshot; reserve; join token; invitation | 🟢 |
scheduled | in_progress | Preflight OK; live begins | Meter; consent; Daily room | 🟡 |
in_progress | disconnected | Connection lost | Meter pauses | 🟢 |
disconnected | in_progress | Reconnect in window | Context retained | 🟡 3-min / original-end not server-side |
disconnected | abandoned | Recovery / original end elapses | Terminal; consumed stand | 🔴 |
in_progress | completed | Normal end or limit | Transcript; settlement | 🟢 |
in_progress | failed | Provider fault | Remedy table | 🟡 |
scheduled | cancelled | Org cancel | release; zero | 🟢 |
scheduled | expired | Sweeper after expiresAt | release | 🔴 |
| any non-terminal | deleted | Soft delete | Hidden from queries | 🟢 |
| terminal | settlement | settledAt claim | Idempotent settle U, release | 🟢 |
| From | To | Code | Status |
|---|---|---|---|
disconnected | completed | completeInterview | 🟢 |
scheduled | failed | failInterview | 🟡 |
scheduled / expired | deleted | deleteInterview + release | 🟢 |
1.4 Invalid transitions to guard
| Guard | Status |
|---|---|
| Settle before terminal | 🟡 No status gate in settleCompletedInterview |
| Release after already settled | 🟢 Idempotent |
| Start expired/cancelled/deleted | 🟡 Partial checks |
| Second concurrent active session | 🟡 disconnected excluded from hasActiveInterview |
| Stale worker after newer session | 🔴 No generation guard |
2. Credit / commitment
Logical states → lots, org cache (available / reserved), append-only ledger.
| State (spec) | Implementation | Status |
|---|---|---|
| Uncommitted available | Lot remainingCredits + org available | 🟢 |
| Reserved | Lot reservedCredits; ledger reserve | 🟢 |
| Consumed | Ledger settle | 🟢 |
| Restored | — | 🔴 |
| Expired | expireLot; forfeit on release from expired lot | 🟡 No lot sweeper |
| Deficit / exposure | — | 🔴 |
| Transition | Status |
|---|---|
| Available → Reserved (schedule) | 🟢 |
| Reserved → Consumed + Released (settle) | 🟢 |
| Reserved → Released (cancel/fail/zero-U) | 🟢 |
| Reserved → Forfeited on release (lot expired) | 🟢 |
| Purchase → Available | 🟢 |
| Available → Expired (lot) | 🟡 expireLot only; scheduler 🔴 |
3. Report / session / recording
Session: same as interview status (🟢); no separate entity (🔴).
Report: not_started → processing → completed | failed (≤3 attempts).
| State | Status |
|---|---|
not_started / processing / completed / failed | 🟢 generateReport, MAX_ATTEMPTS = 3 |
Recording: pending → processing → completed | failed on interview.recording — 🟡 enum + bot updateRuntime; 25% restoration 🔴.
4. Proctoring (FR19)
| Dimension | Implementation |
|---|---|
Coverage complete | partial | unavailable | 🔴 proctoring Mixed only |
| Analysis / reviewer disposition | 🔴 |
| Never default 100% integrity | 🔴 |
proctoringCredibility snapshot | 🟡 partial |
5. User & organization
| Entity | States | Status |
|---|---|---|
| User | invited (7d TTL), active, disabled | 🟢 |
| Organization | active, suspended | 🟡 suspend API 🔴 |
| Position | draft → active → archived | 🟢 schedule requires active |
6. Credit arithmetic rules
| Rule | Status |
|---|---|
| 1 credit = 1 minute; reserve D minutes; charge U actual; 0 ≤ U ≤ reserved | 🟡 floor whole minutes; no segment aggregation (WAL07) |
| A = B − H (available vs commitments) | 🟡 cache + lots |
Atomicity / idempotency; FIFO lots by expiresAt | 🟢 |
| Protected commitments through lot expiry until settle | 🟡 |
| 30-day commitment cutoff | 🔴 |
| Release after source expiry → forfeit | 🟢 |
| Restored credits max(original expiry, +90d) | 🔴 |
| Purchase expiry 12 months | 🟢 |
Ledger adjustment writer | 🔴 |
7. Charge outcomes (remedy table)
| Outcome (spec) | Status |
|---|---|
| Normal early finish | 🟡 Floor minutes; release unused |
| Cancel / no-show / failed preflight → zero | 🟡 No-show/expired sweeper 🔴 |
| Candidate abandonment → consumed stand | 🟡 Abandon path 🔴 |
| Recoverable provider outage unbilled | 🔴 |
| Partial/unusable evidence restoration | 🔴 |
| Recording missing → 25% restore | 🔴 |
| Report delayed ≤24h | 🟡 Retries only |
| Duplicate charge reverse | 🔴 |
| Retakes consume credits | 🟢 |
8. Short-session & abuse
| Control | Status |
|---|---|
| <60s or <2 substantive → insufficient evidence | 🟡 report 🟢; billing floor 0 |
| 3 under-60s / hour / workspace → block 1h | 🔴 |
| Report attempts capped at 3 | 🟢 |
| Cost alerts $0.15 / $0.25 | 🔴 |
9. WAL01–WAL24
≥1,000 randomized sequences — not automated (unit tests on planners only). WAL19 cited §16, not in §15.1 table.
| ID | Scenario (abbrev.) | Status |
|---|---|---|
| WAL01 | Duplicate Stripe → grant once | 🟡 Code 🟢; concurrency test 🔴 |
| WAL02 | Failed/pending checkout | 🟡 |
| WAL03 | Race for last funds | 🟡 |
| WAL04 | Five 20-min holds block sixth | 🟡 |
| WAL05 | Unbooked expiry releases | 🟡 Sweeper 🔴 |
| WAL06 | Settle 12 of 20 | 🟢 Unit test |
| WAL07 | Fractional seconds aggregate once | 🔴 |
| WAL08 | No-show / preflight zero | 🟡 |
| WAL09 | Disconnect/reconnect no double bill | 🟡 |
| WAL10 | Abandonment + insufficient threshold | 🟡 / 🔴 |
| WAL11 | Crash retry idempotency | 🟡 |
| WAL12 | Report retry no second charge | 🟢 |
| WAL13 | Restoration remedies | 🔴 |
| WAL14 | Unknown cause → review | 🔴 |
| WAL15 | Reschedule swap capacity | 🔴 / 🟡 |
| WAL16 | Lot expiry + appointments | 🟡 Sweeper 🔴 |
| WAL17 | 30-day protection | 🔴 |
| WAL18 | Mixed-price packs | 🔴 |
| WAL19 | Chargeback / abuse | 🔴 |
| WAL20 | Reversal + webhook replay | 🔴 |
| WAL21 | 100-row batch | 🔴 |
| WAL22 | Demotion during export | 🟡 |
| WAL23 | Cost pause vs funded interviews | 🔴 |
| WAL24 | Stale callbacks | 🔴 |
Gaps: abandoned/expired sweeper; adjustment/restoration; 30-day cutoff; proctoring state machines; under-60s booking block; lot expiry consumer.