Use the reviewed authenticated bootstrap contract

Authenticated bootstrap is the transition from locally restored Driver session state to the main Driver App navigation. It coordinates loading, account, schedule, configuration, order-provider, permission, connectivity, and realtime state; it is not a single login or server-read result.

Use this contract when maintaining startup, provider order, the authenticated stack, or the main tabs. It describes source responsibilities only and does not confirm deployed behavior or runtime success.

Availability

The authenticated branch requires a locally restored signed-in session and a configured Driver App project. A configured schedule prerequisite can take priority over the main workspace. Local permission state can delay root readiness and later determines whether Map view or its permission substitute is mounted.

An account being visible in an operator product does not prove that its local session is present, valid, enabled, or authorized for a Driver App request.

Prerequisites

A supported Driver App build and project configuration.
A driver account obtained through the supported account workflow.
Saved session state that the client can rehydrate.
Completed local language and configuration readiness required by dependent providers.
An explicit strategy for schedule, permission, platform, connectivity, and provider failure states.
Separate authorization and error handling for every API request started after navigation is admitted.

Responsibility boundaries

Boundary	Responsibility during bootstrap	Required separation
Session provider	Read saved token, user, and device state; expose loading and signed-in state.	Local rehydration is not server authentication.
Language/configuration providers	Resolve the local language and current project configuration used by later providers.	Missing or default configuration is not a successful service response.
Root navigator	Keep loading visible until its local readiness inputs settle; select signed-out, schedule, or authenticated navigation.	Navigation admission is not data readiness.
Schedule gate	Compare the locally available driver schedule with the configured client validation rule.	Client gating is not a complete server schedule contract.
Authenticated stack	Mount the main tabs and registered detail routes after session loading clears.	Route registration does not authorize a detail action.
Main tabs	Start on Orders and expose Map view, Messages, and Profile when mounted; replace Map view locally when permission is absent.	A mounted tab does not prove a read, location, message, or profile effect.
Order/realtime providers	Start eligible reads, transport setup, and subscriptions from session, project, connectivity, and screen state.	Readiness, connection, join intent, receipt, and freshness are distinct.
API	Must independently authorize and validate each read or mutation; affected task contracts remain excluded when that boundary is not proven.	The client must not treat its stored session as an authorization decision.

The realtime provider can initialize transport after session loading based on project configuration even before the authenticated screen proves useful. The authenticated stack and other providers add subscriptions under their own conditions. Keep transport creation, authenticated membership, screen data, and user-visible completion as separate states.

Inputs and result

Input/state	Client transition	Observable result	Failure or partial-effect limit
Session loading	Restore saved session values.	Loading remains until local session work settles.	A storage error can produce incomplete state; no server verdict exists yet.
No admitted session	Select signed-out navigation.	A signed-out surface can become visible; this contract does not guarantee the clean first-launch tutorial transition.	Does not prove server logout or token revocation.
Admitted session plus pending startup state	Continue resolving notification, order-provider, schedule, and permission readiness.	Loading can remain visible.	Individual failures can settle differently; transition is not aggregate success.
Schedule validation blocks	Select schedule prerequisite instead of the authenticated shell.	Schedule-blocked surface appears.	Client time/schedule logic is not the complete API rule set.
Authenticated shell admitted	Mount authenticated stack, then the main tabs.	Orders is the initial tab; other tabs are available according to local state.	Tab visibility does not prove data availability.
Map tab without required local permission	Mount the permission-specific substitute.	Permission guidance appears in place of the map.	Request does not prove effective permission or location success.
Connectivity and session identity present	Eligible realtime/read providers can connect, subscribe, or request data.	Later loading, content, empty, or error state can change.	Connection and request intent are not acceptance, delivery, or freshness.
Profile tab navigation	The account area can refresh current user information.	Profile loading/content/error can change.	Refresh result must be handled separately from navigation.

Back behavior belongs to the active stack. Bootstrap must not use a back action to bypass signed-out, schedule, or permission prerequisites. Push or programmatic navigation must still target a registered route and pass its own task gates.

Security and privacy

Treat saved account and token state as sensitive and provisional.
Require independent server authorization and validation for every request; never use a mounted route, user identifier, transport connection, or local role as authorization proof. Keep affected message/read and other task contracts excluded until that boundary is proven.
Do not log tokens, session records, driver identity, room identifiers, orders, messages, contacts, coordinates, or provider identifiers.
Avoid running authenticated bootstrap against real services for documentation or smoke testing. Normal mounting can start reads, realtime, notification, and location-related work.
Clear or replace account-scoped state when ownership changes; do not let late reads or events from a prior session update the next one.

Limits and failure states

State	Meaning	Required handling
Session rehydrated locally	Saved values are available to providers.	Keep server authorization per request.
Root loading cleared	Local readiness admitted another branch.	Do not report API or provider success.
Authenticated tabs visible	Navigation mounted for the local session.	Let each tab expose loading, empty, unavailable, and error states.
Realtime transport exists	A transport object was created or connected.	Do not infer authenticated membership, event delivery, or data freshness.
Subscription requested	A provider asked to join task-specific realtime state.	Track disconnect, reconnect, cleanup, and stale-session ownership separately.
Read fails after tabs mount	Navigation and data readiness diverged.	Keep the failure within the owning task and avoid replaying mutations.
Session becomes absent or disabled	Local account state no longer admits authenticated work.	Return to the supported session/authentication flow; do not force navigation.
App backgrounds or foregrounds	Refresh, permission, location, or realtime work can run by lifecycle condition.	Prevent prior-session or late results from becoming current state.

Bootstrap does not guarantee ordering or atomicity across local storage, configuration, API reads, notification setup, realtime subscriptions, schedule checks, or lifecycle work. Treat each result independently and make stale or partial state visible without claiming completion.

Troubleshooting

Symptom	Inspect	Safe next step
Loading does not clear	Session, language, configuration, notification, order-provider, schedule, and local permission readiness	Capture only sanitized state names and timing; do not repeatedly relaunch against live services.
Signed-out entry appears for an expected account	Local session ownership and storage result	Use the authentication contract; do not inject navigation or a token manually.
Schedule prerequisite appears unexpectedly	Configured validation, device time, and available schedule state	Compare public inputs and escalate to the account/configuration owner.
Tabs appear but content does not	Navigation readiness versus the owning provider read	Diagnose loading, empty, unavailable, or error state without issuing a mutation.
Realtime state appears stale	Connectivity, transport, subscription lifecycle, session ownership, and screen read	Use the realtime contract and verify cleanup before reconnecting.
Map view shows permission guidance	Local permission result and platform state	Use the permissions contract; do not infer effective permission from declarations alone.

Re-review this contract whenever session storage or hydration, provider order, root readiness, schedule priority, authenticated routes, initial tab, permission substitution, realtime lifecycle, or account-scope cleanup changes.

Availability​

Prerequisites​

Responsibility boundaries​

Inputs and result​

Security and privacy​

Limits and failure states​

Troubleshooting​