Pretenancy Pipeline

The Pretenancy Pipeline gives agents a single view of all tenancies that are not yet active, organised into status buckets with inline action controls.

Pipeline Buckets

Bucket	Description
In Progress	Tenancies in pending status — being set up
Ready To Move In	Tenancies marked ready_to_move_in — awaiting confirmation
On Hold	Tenancies paused (on_hold) — can be resumed or progressed
Action Required	Tenancies with outstanding flags (e.g. overdue move-in)
Moving In (7 Days)	Lookahead: tenancies with a start date within the next 7 days
Moving In (30 Days)	Lookahead: tenancies with a start date within the next 30 days

The pipeline auto-refreshes every 30 seconds.

Status State Machine

Every status change is validated against the state machine before being applied. Invalid transitions are rejected.

pending
  ├─→ ready_to_move_in
  ├─→ on_hold
  └─→ fallen_through  (terminal)

ready_to_move_in
  ├─→ [confirmMoveIn] → active
  ├─→ on_hold
  └─→ fallen_through  (terminal)

on_hold
  ├─→ pending
  ├─→ ready_to_move_in
  └─→ fallen_through  (terminal)

fallen_through is a terminal state. Once set, all linked tenancy terms and any outstanding action-required flags are resolved automatically and the status cannot be changed.

Inline Action Buttons

Each tenancy row in the pipeline displays action buttons based on its current status.

In Progress (pending)

Button	Resulting Status	Notes
Mark Ready	ready_to_move_in	Signals all pre-tenancy checks are complete
Put On Hold	on_hold	Pauses progression; linked terms also go on hold
Fallen Through	fallen_through	Requires confirmation dialog; terminal

Ready To Move In

Button	Resulting Status	Notes
Confirm Move-In	active	Runs full move-in workflow (see below)
Put On Hold	on_hold	—
Fallen Through	fallen_through	Requires confirmation dialog; terminal

On Hold

Button	Resulting Status	Notes
Resume	pending	Returns to in-progress
Mark Ready	ready_to_move_in	Skips pending, goes straight to ready
Fallen Through	fallen_through	Requires confirmation dialog; terminal

Confirm Move-In Workflow

The Confirm Move-In action is the final step in the pretenancy pipeline. When triggered:

1. Tenancy status transitions to active.
2. All linked tenancy terms are activated with a movedInAt timestamp.
3. Any outstanding overdue_move_in action-required flags for the tenancy are resolved.
4. An audit trail entry is written to both auditLog and productAuditEvents.
5. The tenancy now appears in the Active Tenancies portfolio view and in the 30-day Moved In rolling window.

The Confirm Move-In button also appears directly on overdue_move_in action-required flag rows.

Action Required Flags

The action-required-scan Inngest cron job automatically creates overdue_move_in flags when a tenancy's start date passes without a confirmed move-in. Use the Confirm Move-In button on the flag row to resolve the flag and activate the tenancy in one step.

Destructive Actions & Confirmation

The Fallen Through button requires an explicit browser confirmation dialog before proceeding:

"Are you sure this tenancy has fallen through? This cannot be undone."

This guard is present regardless of the current status.

Feedback & Error Handling

After each action:

• A green banner is shown on success (e.g. "✓ Move-in confirmed — tenancy is now active").
• A red banner is shown on error, displaying the error message returned by the server.
• The pipeline data is automatically re-fetched after a successful mutation.
• Buttons are disabled while a mutation is in flight to prevent duplicate submissions.

API Reference

These endpoints are available under the pretenancy tRPC namespace.

pretenancy.updateStatus

Transitions a tenancy to a new status, enforcing the state machine.

trpc.pretenancy.updateStatus.mutate({
  tenancyId: string,
  newStatus: "pending" | "ready_to_move_in" | "on_hold" | "fallen_through",
});

• Mirrors the status change to all linked tenancy terms.
• Writes an entry to auditLog and productAuditEvents.
• Rejects invalid transitions with an error.

pretenancy.confirmMoveIn

Completes the move-in workflow for a tenancy.

trpc.pretenancy.confirmMoveIn.mutate({
  tenancyId: string,
});

• Transitions tenancy to active.
• Activates linked terms with movedInAt.
• Resolves overdue_move_in action-required flags.
• Writes a comprehensive audit trail.

pretenancy.getStateMachine

Returns the full allowed-transitions map.

const machine = await trpc.pretenancy.getStateMachine.query();
// { pending: ["ready_to_move_in", "on_hold", "fallen_through"], ... }

pretenancy.getAvailableActions

Returns allowed actions for a specific tenancy.

const actions = await trpc.pretenancy.getAvailableActions.query({
  tenancyId: string,
});

pretenancy.pipelineCounts

Lightweight counts for dashboard badges.

const counts = await trpc.pretenancy.pipelineCounts.query();
// { pending: 4, readyToMoveIn: 2, onHold: 1, actionRequired: 3 }