Flow — Document lifecycle · Ingest branch

Summary

On every file drop, the storage trigger validates size/quota, branches free-tier docs to view_only, otherwise runs the parser and routes the document into one of the lifecycle sub-paths.

Audience

end-user

Entry

File drop on any Inbox surface via upload-modal or drag-drop into inbox-uploading.

Steps

#	Step	Surface	Notes
1	Upload starts (uploading)	inbox-uploading	In-browser progress; no Firestore doc yet
2	File lands in GCS	pillar-inbox	Storage trigger fires
3	Size check	review-document-failed	> 100 MB → rejected_oversized (terminal)
4	Quota check	review-document-failed	Cap exceeded → rejected_quota (terminal); see 2026-05-31-free-tier-storage-cap
5a	Free tier branch	review-document-view-only	No parse plan → view_only; parses on upgrade via document-lifecycle-upgrade-backfill
5b	Paid — parser runs	review-document	Hybrid parsing per 2026-05-31-hybrid-parsing-haiku-fallback
6a	Scanned PDF (is_scanned)	review-document	→ needs_ocr — see document-lifecycle-ocr
6b	Unknown form type	review-confirm-doc	→ needs_classification — see document-lifecycle-classification
6c	Transient parse error	review-document	→ parse_pending — see document-lifecycle-parse-pending
6d	Terminal parse error	review-document-failed	→ rejected_format (terminal)
7a	Owner no match	review-document-owner-mismatch	→ pending_owner_confirmation — see document-lifecycle-owner-mismatch
7b	Transfer candidate	review-document-transfer-pending	→ pending_family_transfer — see document-lifecycle-family-transfer
7c	Entity fuzzy match (< 0.85)	review-confirm-doc	→ pending_entity_confirmation — see document-lifecycle-fuzzy-entity-match
7d	Clean match	review-document	→ unreviewed — see document-lifecycle-standard-review

Exit

Document is in one of: view_only, needs_ocr, needs_classification, parse_pending, unreviewed, pending_owner_confirmation, pending_family_transfer, or pending_entity_confirmation. Terminal rejects exit immediately.

Escapes

Terminal states (no further actions possible — see the shared invariant for all Flow 12 paths):

State	What it means	User action
rejected_format	Not a parseable PDF/XLSX (wrong bytes, encrypted)	Re-upload a proper export
rejected_quota	Storage cap exceeded	Delete other docs or upgrade tier
rejected_oversized	File > 100 MB	Compress or re-export from source
rejected_duplicate	Identical fingerprint already in vault	No action needed
superseded	Newer version replaced this one	Read-only history entry

Confirm gate (enforced in confirmDocument callable, applies across every Flow 12 sub-path): only unreviewed, pending_owner_confirmation, and pending_entity_confirmation are confirmable. Every other status — including view_only, parse_pending, needs_ocr, needs_classification, all rejected_*, superseded, pending_family_transfer, pending_conflict_resolution — throws failed-precondition.

Identity matching (successor to owner-validation) lives in user-identity-entry + 2026-07-11-user-identity-entry-model (was: 2026-05-31-owner-validation — superseded); parser dispatch in inbox-document-types.

Note — Glossary of states a screen may carry

• empty — no data yet (first run / cleared)
• populated — happy path with real data
• locked — feature exists but paywalled (current AY only; past AYs never locked)
• processing — async in flight (parse, payment, OCR)
• failed — recoverable error with action prompt
• read-only — past-AY view, or post-engagement CA chat

Sources

• .context/wiki/flows/* § "Flow 12 — Document lifecycle state machine (all tiers)" · "A. Ingest branch"
• .context/wiki/flows/* § "Confirm gate" · "Terminal states" · "Exit state"
• .context/wiki/flows/* § "Glossary of states a screen may carry"