Flow — Document lifecycle · Free-tier upgrade backfill

Summary

After a free-tier user pays for an unlock, backfillFreeUploads runs on every view_only document and routes it through the parser the same way a fresh upload would.

Audience

end-user (just upgraded)

Entry

verifyUnlockPayment succeeds (post step 3a of current-ay-paid-unlock); client loops backfillFreeUploads over every view_only doc.

Steps

#	Step	Surface	Notes
1	Document state pre-upgrade	review-document-view-only	view_only — see freemium-per-ay
2	backfillFreeUploads invoked	pillar-inbox	Per-doc parse via 2026-05-31-hybrid-parsing-haiku-fallback
3a	Scanned	review-document	→ needs_ocr — see document-lifecycle-ocr
3b	Unknown form type	review-confirm-doc	→ needs_classification — see document-lifecycle-classification
3c	Transient parse error	review-document	→ parse_pending — see document-lifecycle-parse-pending
3d	Terminal parse error	review-document-failed	→ rejected_format (terminal)
3e	Parsed OK	review-document	→ unreviewed — see document-lifecycle-standard-review

Exit

Every view_only doc has moved to a downstream lifecycle state. The Inbox UI swaps the "Parses on upgrade" chip for the new state.

Escapes

• Confirm gate: view_only docs are NEVER confirmable; the Confirm button must be hidden / disabled until backfill has run and the doc has moved to unreviewed. See the shared confirm-gate rule in document-lifecycle-ingest.
• Terminal rejected_format: doc surfaces in review-document-failed; user re-uploads a proper export. See the shared terminal-states table in document-lifecycle-ingest.
• Backfill partial failure: client retries the callable in a loop; idempotent per doc.

Sources

• .context/wiki/flows/* § "Flow 12 — Document lifecycle state machine" · "B. Free-tier upgrade backfill"