Household groupings — the design

Proposed — pending review

The top-level choice is already written up at A household is one lead — read that first if you want the problem. This page is the design: what the household record is, where it sits, and how we get there without a big bang.

The model

A household is created at the first inquiry — a household of one. People attach to it with a role: primary, co-applicant, co-signer, or occupant. The household carries through inquiry, application, and approval.

One household is one deal: listed once, counted once, reminded once. When we discover two records are really one household, we link them — we never delete a person, so a co-signer stays screenable and reachable. Role comes from structural evidence the PMS gives us, never from reading a name.

Where it sits

Members attach by personId. Person already answers "who is this human" (ADR-0018/0020 — a role is a relationship that points at a Person, not a separate identity table). Household answers the one question Person doesn't: which humans are one deal.

So this is no new identity mechanism and no parallel person table — it is another relationship on the spine, the same shape as PersonRole. Each PMS adapter maps its own evidence into memberships: AppFolio's rental-application group id joined through the spine, Yardi's and RealPage's structural role fields where they exist.

Decided (Fede, 2026-08-04): Households are org-scoped, like PersonRole — a Person can cross orgs, but each household belongs to one organization. Same boundary ADR-0020 drew for roles.

The plan, in three stages

a. Group the lists (in flight now) Read-side only. One prospect card per application group, one PM reminder. Nothing new is stored.

b. The household record Household plus roles, sync writers that populate it, and one small backfill. Households are lazy — a lone inquiry is a household of one — so the backfill is a single idempotent pass over active prospects.

c. Move the workflow onto it Stage and reminders belong to the household rather than to whichever person happened to arrive first.

Stage (b) doesn't ship until the Willows test harness passes it. The harness is being built alongside this and covers the cases that have burned us: a joint couple with ordinary names, a co-signer whose label is typed wrong, two solo inquiries that turn out to be one household, and a person holding two roles at once.

Three things to pick

1. When does the headline Applications count switch to households?

With stage bRECOMMENDED The number then comes from a stored household, so every surface agrees.
With stage aTile is right sooner, but re-derived per surface until b lands.
Hold until cSafest, leaves Camellia's tile wrong for longer.

2. Two solo households turn out to be one. Who joins them?

Auto-merge on application-group evidenceRECOMMENDED The PMS told us they belong together; making a PM confirm it re-creates the duplicate we're fixing.
PM confirms every mergeNo wrong merges, but the tile stays wrong until someone clicks.

3. Do we ship the occupant role in v1?

YesRECOMMENDED An adult who lives there but doesn't sign is common, and without the role they land as a phantom applicant.
DeferThree roles is simpler, but we'd migrate rows later.