The onboarding chain gets a spine: its own model, and a delegation that cannot defeat it

apps/web/prisma/migrations/20260821090000_ose_initiated_onboarding_proposals/migration.sql

@@ -0,0 +1,93 @@
+-- CreateEnum
+CREATE TYPE "OnboardingProposalStatus" AS ENUM ('DRAFT', 'PENDING_DIRECTOR', 'APPROVED', 'REJECTED', 'WITHDRAWN', 'EXPIRED');
+
+-- CreateEnum
+CREATE TYPE "OnboardingSubjectKind" AS ENUM ('MEMBER', 'ADVISOR', 'OTHER');
+
+-- CreateEnum
+CREATE TYPE "OnboardingEventKind" AS ENUM ('CREATED', 'SUBMITTED', 'APPROVED', 'REJECTED', 'WITHDRAWN', 'EXPIRED');
+
+-- CreateTable
+CREATE TABLE "OnboardingProposal" (
+    "id" TEXT NOT NULL,
+    "institutionId" TEXT NOT NULL,
+    "subjectName" TEXT NOT NULL,
+    "subjectEmail" TEXT NOT NULL,
+    "subjectEmailNormalized" TEXT NOT NULL,
+    "subjectKind" "OnboardingSubjectKind" NOT NULL,
+    "subjectKindOther" TEXT,
+    "cohort" TEXT NOT NULL,
+    "organizationId" TEXT,
+    "submittedById" TEXT NOT NULL,
+    "status" "OnboardingProposalStatus" NOT NULL DEFAULT 'DRAFT',
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "submittedAt" TIMESTAMP(3),
+    "decidedAt" TIMESTAMP(3),
+    "decidedById" TEXT,
+    "decisionReason" TEXT,
+    "openSubjectKey" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "OnboardingProposal_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "OnboardingProposalEvent" (
+    "id" TEXT NOT NULL,
+    "proposalId" TEXT NOT NULL,
+    "institutionId" TEXT NOT NULL,
+    "kind" "OnboardingEventKind" NOT NULL,
+    "fromStatus" "OnboardingProposalStatus" NOT NULL,
+    "toStatus" "OnboardingProposalStatus" NOT NULL,
+    "actorId" TEXT,
+    "actorRole" TEXT,
+    "onBehalfOfId" TEXT,
+    "reason" TEXT,
+    "occurredAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "OnboardingProposalEvent_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "OnboardingProposal_institutionId_status_idx" ON "OnboardingProposal"("institutionId", "status");
+
+-- CreateIndex
+CREATE INDEX "OnboardingProposal_institutionId_expiresAt_idx" ON "OnboardingProposal"("institutionId", "expiresAt");
+
+-- CreateIndex
+CREATE INDEX "OnboardingProposal_submittedById_idx" ON "OnboardingProposal"("submittedById");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "OnboardingProposal_id_institutionId_key" ON "OnboardingProposal"("id", "institutionId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "OnboardingProposal_institutionId_openSubjectKey_key" ON "OnboardingProposal"("institutionId", "openSubjectKey");
+
+-- CreateIndex
+CREATE INDEX "OnboardingProposalEvent_proposalId_occurredAt_idx" ON "OnboardingProposalEvent"("proposalId", "occurredAt");
+
+-- CreateIndex
+CREATE INDEX "OnboardingProposalEvent_institutionId_occurredAt_idx" ON "OnboardingProposalEvent"("institutionId", "occurredAt");
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposal" ADD CONSTRAINT "OnboardingProposal_institutionId_fkey" FOREIGN KEY ("institutionId") REFERENCES "Institution"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposal" ADD CONSTRAINT "OnboardingProposal_organizationId_institutionId_fkey" FOREIGN KEY ("organizationId", "institutionId") REFERENCES "Organization"("id", "institutionId") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposal" ADD CONSTRAINT "OnboardingProposal_submittedById_fkey" FOREIGN KEY ("submittedById") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposal" ADD CONSTRAINT "OnboardingProposal_decidedById_fkey" FOREIGN KEY ("decidedById") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposalEvent" ADD CONSTRAINT "OnboardingProposalEvent_proposalId_institutionId_fkey" FOREIGN KEY ("proposalId", "institutionId") REFERENCES "OnboardingProposal"("id", "institutionId") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposalEvent" ADD CONSTRAINT "OnboardingProposalEvent_actorId_fkey" FOREIGN KEY ("actorId") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "OnboardingProposalEvent" ADD CONSTRAINT "OnboardingProposalEvent_onBehalfOfId_fkey" FOREIGN KEY ("onBehalfOfId") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+

apps/web/prisma/schema.prisma

@@ -83,6 +83,7 @@ model Institution {
   exceptions           Exception[]
   seatMeterEvents      SeatMeterEvent[]
   registrySeal         RestrictedRegistrySeal?
+  onboardingProposals  OnboardingProposal[]
 }
 
 enum InstitutionRole {
@@ -123,17 +124,21 @@ model User {
   sessions               Session[]
   institutionMembership  InstitutionMembership[]
   roleAssignments        RoleAssignment[]
-  roleTransfersFrom      RoleTransfer[]           @relation("RoleTransferFrom")
-  roleTransfersTo        RoleTransfer[]           @relation("RoleTransferTo")
-  roleTransfersInitiated RoleTransfer[]           @relation("RoleTransferInitiator")
-  delegationsGiven       ApprovalDelegation[]     @relation("DelegationFrom")
-  delegationsReceived    ApprovalDelegation[]     @relation("DelegationTo")
+  roleTransfersFrom      RoleTransfer[]            @relation("RoleTransferFrom")
+  roleTransfersTo        RoleTransfer[]            @relation("RoleTransferTo")
+  roleTransfersInitiated RoleTransfer[]            @relation("RoleTransferInitiator")
+  delegationsGiven       ApprovalDelegation[]      @relation("DelegationFrom")
+  delegationsReceived    ApprovalDelegation[]      @relation("DelegationTo")
   messagesSent           Message[]
   participants           Participant[]
   notifications          Notification[]
   notificationPrefs      NotificationPreference[]
   deliverableReminders   DeliverableReminder[]
-  resourcesAuthored      Resource[]               @relation("ResourceAuthor")
+  resourcesAuthored      Resource[]                @relation("ResourceAuthor")
+  onboardingProposed     OnboardingProposal[]      @relation("OnboardingProposedBy")
+  onboardingDecided      OnboardingProposal[]      @relation("OnboardingDecidedBy")
+  onboardingActed        OnboardingProposalEvent[] @relation("OnboardingEventActor")
+  onboardingActedFor     OnboardingProposalEvent[] @relation("OnboardingEventOnBehalfOf")
 }
 
 // ─── Organizations & Role Seats ───────────────────────────────────────────────
@@ -162,20 +167,21 @@ model Organization {
   createdAt     DateTime    @default(now())
   updatedAt     DateTime    @updatedAt
 
-  advisors        OrganizationAdvisor[]
-  roles           Role[]
-  approvals       ApprovalRequest[]
-  events          Event[]
-  conversations   Conversation[]
-  documents       Document[]
-  budgets         Budget[]
-  vendors         Vendor[]
-  memoryRecords   MemoryRecord[]
-  feedPosts       FeedPost[]
-  collabInterests CollabInterest[]
-  budgetLines     BudgetLine[]
-  ledgerEntries   LedgerEntry[]
-  exceptions      Exception[]
+  advisors            OrganizationAdvisor[]
+  roles               Role[]
+  approvals           ApprovalRequest[]
+  events              Event[]
+  conversations       Conversation[]
+  documents           Document[]
+  budgets             Budget[]
+  vendors             Vendor[]
+  memoryRecords       MemoryRecord[]
+  feedPosts           FeedPost[]
+  collabInterests     CollabInterest[]
+  budgetLines         BudgetLine[]
+  ledgerEntries       LedgerEntry[]
+  onboardingProposals OnboardingProposal[]
+  exceptions          Exception[]
 
   // The target of the composite foreign keys on Role, OrganizationAdvisor and
   // the club-scoped half of Exception.
@@ -1727,6 +1733,209 @@ model RestrictedRegistrySeal {
   institution Institution @relation(fields: [institutionId], references: [id], onDelete: Cascade)
 }
 
+// ─── OSE-initiated onboarding ─────────────────────────────────────────────────
+
+/// Where a proposal is. Mirrors `OnboardingStatus` in
+/// `src/lib/identity/onboarding-chain.ts` exactly; `onboarding-chain.test.ts`
+/// reads this file and fails if the two ever disagree, so the rules module
+/// cannot be reasoned about against a set of states the database does not have.
+enum OnboardingProposalStatus {
+  DRAFT
+  PENDING_DIRECTOR
+  APPROVED
+  REJECTED
+  WITHDRAWN
+  /// Nobody decided in time. Terminal, and reached by the clock rather than by
+  /// an actor — see `expiresAt` below.
+  EXPIRED
+}
+
+/// What the person is proposed AS. Not a role grant: it is the kind of access
+/// being asked for, which is what decides the registry cohort a decision writes.
+enum OnboardingSubjectKind {
+  MEMBER
+  ADVISOR
+  /// Anything else OSE admits — a graduate assistant, a staff observer. Requires
+  /// `subjectKindOther` to say what, so "other" never becomes the default that
+  /// means nothing.
+  OTHER
+}
+
+/// Every transition a proposal has been through, append-only.
+enum OnboardingEventKind {
+  CREATED
+  SUBMITTED
+  APPROVED
+  REJECTED
+  WITHDRAWN
+  EXPIRED
+}
+
+/// An OSE-initiated proposal to admit ONE PERSON to the institution.
+///
+/// ── Why this is its own model (ADR-0013) ────────────────────────────────────
+///
+/// `ApprovalRequest.organizationId` is a NON-NULL foreign key to `Organization`
+/// with `onDelete: Cascade`, and an onboarding proposal has no club. Relaxing
+/// that column to nullable would weaken the invariant for every club approval
+/// and every reimbursement on the same table — a nullable column cannot say
+/// "null only for onboarding" — and the cascade, which is right for a club
+/// approval, is meaningless for a proposal that has no club. ADR-0013 records
+/// the full argument and the two options it refuses.
+///
+/// ── Why the grain is a PERSON, not a seat ───────────────────────────────────
+///
+/// Measured from the tracked roster workbook (column D of the four club sheets):
+/// 64 students hold 106 occupied club/position pairs, and 40 of the 64 hold more
+/// than one — 38 hold two, 2 hold three. With 18 Simon-domain advisors that is
+/// the 82 people, on 82 distinct addresses, that `eligibility.ts` documents. A
+/// proposal is therefore one row per PERSON — the unit that admits somebody to
+/// the institution exactly once, no matter how many seats they go on to hold.
+/// Anything counted per seat over-counts people by 1.66x, and the access
+/// boundary this feeds (`RestrictedIdentity`) is itself keyed
+/// `(institutionId, emailNormalized)`, one row per address. The grains agree.
+///
+/// This comment said 145 pairs and 2.3x until the workbook was re-read. 145 is
+/// roughly every email cell in those sheets — 106 student cells plus 40 advisor
+/// cells — which counts an advisor's attachment to a seat as though it were a
+/// seat somebody holds. ADR-0013 records the correction.
+///
+/// What a decision then COSTS is a separate question with a separate answer;
+/// this model deliberately does not encode a billing unit, because a proposal
+/// that admits a person is not evidence about how seats are charged.
+model OnboardingProposal {
+  id            String      @id @default(cuid())
+  institutionId String
+  institution   Institution @relation(fields: [institutionId], references: [id], onDelete: Cascade)
+
+  /// Who is proposed. `subjectEmail` is kept as typed for display; every
+  /// comparison goes through `subjectEmailNormalized`, which is the same
+  /// normalisation `RestrictedIdentity.emailNormalized` uses so the two can be
+  /// matched without a second opinion about what an address is.
+  subjectName            String
+  subjectEmail           String
+  subjectEmailNormalized String
+  subjectKind            OnboardingSubjectKind
+  /// Required when `subjectKind` is OTHER. The database cannot express that
+  /// conditional, so `createProposal` refuses it and a test proves the refusal.
+  subjectKindOther       String?
+  /// The registry cohort a decision would write. Carried on the proposal so the
+  /// Director decides the same value that later reaches the boundary.
+  cohort                 String
+
+  /// The club this person is proposed into, if any. NULLABLE, and that is the
+  /// whole reason this model exists: an advisor may belong to no club, and an
+  /// institution-level member belongs to none by definition.
+  ///
+  /// The relation is composite — `(organizationId, institutionId)` — so a
+  /// proposal cannot name a club belonging to a different institution. Postgres
+  /// applies MATCH SIMPLE, so the constraint is enforced when organizationId is
+  /// present and simply absent when it is null, which is exactly the semantics
+  /// wanted here.
+  organizationId String?
+  /// `Restrict`, not `SetNull`: the composite key includes the non-null
+  /// `institutionId`, and SET NULL would have to null that column too. Clubs are
+  /// archived rather than deleted here, so this refuses a delete that would
+  /// silently rewrite what a Director was asked to decide.
+  organization   Organization? @relation(fields: [organizationId, institutionId], references: [id, institutionId], onDelete: Restrict)
+
+  submittedById String
+  submittedBy   User   @relation("OnboardingProposedBy", fields: [submittedById], references: [id])
+
+  status OnboardingProposalStatus @default(DRAFT)
+
+  /// The instant this proposal stops being decidable.
+  ///
+  /// STORED rather than computed from a constant, because it is a promise made
+  /// to a named person waiting for an answer: redeploying with a different
+  /// window must not move a deadline that has already been set. The clock is
+  /// authoritative — `effectiveProposalStatus` reads EXPIRED past this instant
+  /// whatever the column says — so an unrun sweep cannot leave a stale proposal
+  /// decidable. The sweep only makes the record catch up with the clock.
+  expiresAt DateTime
+
+  /// Set when the proposal enters PENDING_DIRECTOR, so "how long has this person
+  /// been waiting" is a column rather than a scan of the event log.
+  submittedAt DateTime?
+
+  /// The outcome, denormalised from the event log for lists and for the
+  /// downstream write. The log is the record; these are the current answer.
+  decidedAt      DateTime?
+  decidedById    String?
+  /// `Restrict`, following `AuditEvent`'s precedent: deleting a person must not
+  /// silently erase who decided an admission. The absence of a cascade is the
+  /// protection, and a tenant teardown removes these rows as a separate,
+  /// visible act.
+  decidedBy      User?     @relation("OnboardingDecidedBy", fields: [decidedById], references: [id], onDelete: Restrict)
+  decisionReason String?
+
+  /// `subjectEmailNormalized` while this proposal is OPEN, and NULL once it is
+  /// terminal.
+  ///
+  /// Postgres treats NULLs as distinct in a unique index, so this is a partial
+  /// unique constraint expressed in a column: one open proposal per person per
+  /// institution, and any number of settled ones. Prisma cannot declare a
+  /// partial index, and adding one as raw SQL would make the migration stop
+  /// reproducing this file — which CI checks. Two open proposals for the same
+  /// address is not a cosmetic duplicate: it is two Directors approving the
+  /// same admission twice.
+  openSubjectKey String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  events OnboardingProposalEvent[]
+
+  /// The target of the composite foreign key on OnboardingProposalEvent.
+  @@unique([id, institutionId])
+  @@unique([institutionId, openSubjectKey])
+  @@index([institutionId, status])
+  @@index([institutionId, expiresAt])
+  @@index([submittedById])
+}
+
+/// One transition of one proposal. Append-only: rows are written, never edited.
+///
+/// Separate from `AuditEvent` on purpose, and both are written. `AuditEvent` is
+/// the security log — who tried what, and whether it was allowed — and
+/// `audit.view` is minRole OSE_ADVISOR, so anything put in its metadata is
+/// readable by every advisor at the institution. A proposal's payload is a named
+/// person's address and cohort. That confidentiality inversion is why the
+/// subject never appears on an audit row; it lives here, behind the same
+/// permission as the proposal itself.
+model OnboardingProposalEvent {
+  id            String             @id @default(cuid())
+  proposalId    String
+  /// Denormalised from the proposal and held to it by the composite foreign key
+  /// below, so the tenant chokepoint can filter this table directly instead of
+  /// reaching its tenant through a join it cannot add. `ApprovalStep` is the
+  /// older shape and is still in UNENFORCEABLE for exactly this reason.
+  institutionId String
+  proposal      OnboardingProposal @relation(fields: [proposalId, institutionId], references: [id, institutionId], onDelete: Cascade)
+
+  kind       OnboardingEventKind
+  fromStatus OnboardingProposalStatus
+  toStatus   OnboardingProposalStatus
+
+  /// Null for EXPIRED, and only for EXPIRED: nobody acted, the clock did. Every
+  /// other transition names the person who caused it.
+  actorId      String?
+  actor        User?   @relation("OnboardingEventActor", fields: [actorId], references: [id], onDelete: Restrict)
+  /// The actor's institution role at the instant of the transition, and — when
+  /// authority was borrowed — whose it was. Recorded rather than looked up
+  /// later, because a role held today is not evidence about a decision taken in
+  /// March.
+  actorRole    String?
+  onBehalfOfId String?
+  onBehalfOf   User?   @relation("OnboardingEventOnBehalfOf", fields: [onBehalfOfId], references: [id], onDelete: Restrict)
+
+  reason     String?
+  occurredAt DateTime @default(now())
+
+  @@index([proposalId, occurredAt])
+  @@index([institutionId, occurredAt])
+}
+
 // ─── Inbound webhooks ────────────────────────────────────────────────────────
 
 /// What this deployment expects a provider to deliver, and where.
@@ -1899,4 +2108,4 @@ enum WebhookReceiptOutcome {
   NO_ACTION
   /// Accepted and recorded; no code path acts on it. `note` says which.
   NOT_PROCESSED
-}
+}