Requirements handling: a Stripe-style checklist projected from facts we already store

Two spike questions shaped the design. From Stripe Connect (spike, RENTAL-593): a requirement is a key, not data — the checklist names what's missing (external_account), it never holds the thing itself; and urgency is membership in buckets (currently_due, pending_verification), not a status enum — a key can legitimately sit in both at once. From Modern Treasury (spike, RENTAL-594): MT's status webhooks carry no requirement-keyed failure detail (RENTAL-594), only an entity-level verdict — which caps how granular our error model can usefully be, so we deliberately don't build a child error table that would never be populated.

Org-scoped checklist rows, one row per outstanding requirement key. Landed as migration 0004_warm_invaders.sql (commit 44b561c889ec).

No history on this table — it only ever says "what's outstanding right now." The audit trail of how we got here lives where it already lives: webhook_event.

The two booleans are bucket memberships. There's no status column and no state machine to keep valid; the four combinations mean:

The old evaluateOnboarding boolean check became a pure function deriveRequirements(facts) (commit f216d40afe1f, RENTAL-614). The facts are cross-module reads the treasury service already assembles; the output is the exact set of rows the table should hold.

// OnboardingFacts — everything the checklist is derived from, today
{ legalEntityStatus: LegalEntityStatus | null, hasExternalAccount: boolean }

recomputeOnboarding then reconciles the table to match exactly — upsert each desired row, delete rows whose key is no longer desired — and flips the gate: onboarding_completed = (desired rows = 0). Pending rows gate too: an org whose first verification is still in flight has not completed onboarding. The recompute is scoped to top-level platform orgs only (skips sub-accounts and the house org), consistent with the org-structure tenets — only platforms onboard for API access.

Adding a future requirement (e.g. an operating-agreement acceptance) is: persist the underlying fact wherever it belongs, add a key to the const list, extend OnboardingFacts and the derivation. No migration, no new endpoint, no gate change.

The projection is trigger-driven. Three kinds of writes, with a strict pecking order — only the full reconcile updates or deletes; everything else can merely add or soften:

One read endpoint (RENTAL-616): GET /api/v1/organizations/onboarding-requirements, ts-rest contract in packages/api-client. Stripe-style: requirement keys only, no PII. Session-allowed on purpose — a mid-onboarding platform needs to poll its checklist before it has an API key. Empty lists mean onboarding is complete.

// mid-resubmit after a suspension — key in both buckets, error retained
{
  "currentlyDue":         ["legal_entity.verification", "external_account"],
  "pendingVerification":  ["legal_entity.verification"],
  "errors": [{
    "requirement": "legal_entity.verification",
    "code":        "legal_entity_suspended",
    "reason":      "Legal entity verification was suspended"
  }]
}

The onboardingCompleted gate already rides along on /me and identity responses; this endpoint is the "why not" detail behind it.

This exact walk is automated as a hurl scenario (RENTAL-617, commit 4e9a0417aa34) against a live API + DB:

• Errors are entity-level only. MT gives us a verdict per entity, not per field (RENTAL-594). If MT ever ships requirement-keyed detail, the row-level error_code/error_reason generalize without schema change; a child error table stays unbuilt until something can populate it.
• Suspended self-serve platform can't self-recover yet. The gate flip kills the org's API key, and legal-entity PATCH isn't session-allowed — so a suspended platform is stuck without operator help. Surfaced by the hurl scenario; needs its own issue before self-serve onboarding matters (currently deprioritized in favor of Managed Brokkr flows).
• Vocabulary is intentionally small. Two keys today. The const list + facts + derivation is the extension seam; new keys are code changes, not migrations.
• Managed flow untouched. Sub-accounts and the house org are skipped by every write path; requirements are a platform-onboarding concept, matching the flat org-structure tenets.

generated for David · sugar-teach-visa investigation → RENTAL-613/614/616/617 · jb55 · 2026-07-09