CORA integration — review flow

Sequence

Agent transitions — what a finding does

Every agent exit from IN_REVIEW is a finding. The outcome is the transition. There is no agent status PATCH.

From	To	Call
`IN_REVIEW`	`APPROVED_BY_CORA`	finding `outcome: APPROVE`
`IN_REVIEW`	`WAITING_ON_APPLICANT` / `REPLACEMENT_REQUESTED`	finding `outcome: REQUEST_REPLACEMENT` + `REPLACEMENT` reason code
`IN_REVIEW`	`CORRECTION_IN_PROGRESS`	finding `outcome: REQUEST_CORRECTION`, then `POST /applications/{applicationId}/corrections`
`IN_REVIEW`	`NEEDS_COMPLIANCE_REVIEW`	finding `outcome: ROUTE_TO_COMPLIANCE` + `ESCALATION` reason code (400 without)

Fortress-driven transitions — what CORA observes

Trigger	From → To	Event CORA receives
Rules create a slot	— → `WAITING_ON_APPLICANT` / `NOT_UPLOADED`	`requirement.added`
Upload, CORA on	`WAITING_ON_APPLICANT` → `IN_REVIEW`	`requirement.upload_received`
Upload, CORA off	`WAITING_ON_APPLICANT` → `NOT_YET_REVIEWED`	none
CORA comes back on / review closes	`NOT_YET_REVIEWED` → `IN_REVIEW`, one slot at a time	`requirement.upload_received` per slot (re-dispatch)
Current document deleted	any (incl. `APPROVED_BY_COMPLIANCE`) → `WAITING_ON_APPLICANT` / `NOT_UPLOADED`	`requirement.upload_removed`
Correction applied, rules ok	`CORRECTION_IN_PROGRESS` → `NOT_YET_REVIEWED`	`requirement.changed`
Correction applied, needs human	`CORRECTION_IN_PROGRESS` → `NEEDS_COMPLIANCE_REVIEW`	`requirement.needs_compliance_review`
Staff approves	any → `APPROVED_BY_COMPLIANCE`	`requirement.satisfied {approvedBy: COMPLIANCE, sessionId}`
Staff sends back	any → `WAITING_ON_APPLICANT` (any `waitingReason`)	`requirement.replacement_requested` or `requirement.reviewer_finding_submitted`
Staff cancels / rules recompute	any → `CANCELED`; new slots; `requirementVersion++`	`requirement.canceled` / `.added` / `.changed`

Edge cases (at-least-once, unordered delivery)

Situation	CORA action
Duplicate event	Dedupe on `eventId`. A repeated finding is rejected — re-read the slot
`upload_removed` mid-review	Cancel work, discard results. A late finding is rejected
`upload_removed` arrives before `upload_received`	Process by slot state, not event order; re-read the slot on conflict
Slot stuck `IN_REVIEW` (no finding posted)	Raise a `STUCK_OR_FAILED_WORKFLOW` alert (`POST .../agents/cora/alerts`); staff may transition the slot
Staff decided first (`requirement.satisfied {actorType: USER}`, your finding → 409)	Abandon the finding, stop outreach for that slot
`application.updated` / `requirement.changed` after a verdict	Re-read the application and the slot; re-review against the new `requirementVersion`
Household paused	Queue; resume on `compliance_review.closed`, only unresolved slots
Kill switch off / on	Stop safely; on re-enable Fortress re-dispatches `NOT_YET_REVIEWED` slots as `upload_received`

Cadence

Fortress stores the outreach policy per property (GET /properties/{propertyId}/agents/cora/cadencePolicy); CORA executes it. A SITE_TASK touchpoint marks where staff escalation would happen; creating site tasks through the API is not part of this version. One clock per household, started at application.activated, reset on any applicant reply or upload. Touchpoints are placed by offset {days?, hours?}; a touchpoint inside quietHours is deferred to quietHours.end. Treat the policy as data — never hard-code it.