Coordinate the provider migration and backend/mobile routing releases

[stef-k]

Outcome

Coordinate the next backward-compatible Wayfarer backend patch and the later WayfarerMobile release through one backend-first release train.

The maintainer currently reports production as Wayfarer backend 1.9.4. The next backend target is 1.9.5. Provider implementation and Mobile implementation/cleanup are complete, but release preparation, deployment, observation, Mobile version preparation, and publication remain separate ordered gates.

This issue owns release composition, ordering, compatibility, backup/rollback readiness, provider privacy, recorded evidence, and explicit go/no-go decisions. It does not add implementation scope to the completed linked issues.

Current release composition

Wayfarer backend

Current Wayfarer main source composition base: 3a17a00b7b544ea589a5d142575cb4b8edead502.

It contains:

• PR Fix Geoapify credential verification #539 / Priority: fix live Geoapify capability verification and actionable failure results #537: fixed Geoapify verification with meaningful public probes, production response parsing, bounded reads, actionable outcomes, and truthful local admission accounting.
• PR Simplify personal provider authority and add native routing modes #540 / Consolidate provider settings and separate Geoapify from legacy routing configuration #538 step 1: replaced legacy administrator/global routing authority with personal capability-specific provider selection, explicit verification, and explicit provider-native modes.
• PR Clarify browser fallback evidence guidance #541: clarified proportional browser and fallback evidence guidance.
• PR Retire legacy routing authority #544 / Consolidate provider settings and separate Geoapify from legacy routing configuration #538 step 3: retired the obsolete administrator/global routing authority, templates, mappings, pages, services, and schema while preserving required compatibility and accepted route provenance.
• PR Fix deployment EF context selection #545 / Fix deploy.sh production EF context selection #535: supplies only the explicit production EF ApplicationDbContext correction where multiple contexts exist.

Version.props remains 1.9.4. Its Unreleased changelog section contains #535, #537, and #538. The final frozen backend SHA will be recorded only after the 1.9.5 release-preparation PR merges.

#535, #537, and #538 are complete and closed. #542 is deferred low-priority test maintenance and is not a release blocker. #543 is closed as not planned. Broader deployment lifecycle and managed-native release work remains future Python-owned #536 work and is not part of 1.9.5.

WayfarerMobile

Mobile implementation and cleanup are complete on main at 177a9841c90802ce1c5210a78953bdecd15848f6:

• PR Add Trip Editor area editing #265 delivered Consolidate provider settings and separate Geoapify from legacy routing configuration #538 step 2, explicit provider-native routing modes and current personal-provider authority consumption.
• PR [Implementation][Trip Editor]: Segment editing, order, and route map-work mode #266 delivered Consolidate provider settings and separate Geoapify from legacy routing configuration #538 step 2a, removing OSRM-era presentation, dead preferences, and legacy authority/mapping dependence from the updated client.

The published release and current project version remain 1.2.0. Mobile remains version 1.2.0 until the backend-first production smoke and observation gate passes. Do not prepare, version, build for publication, or publish the next Mobile release yet.

Provider and routing authority

• Personal, capability-specific authorization, verification, selection, and guarded admission are the routing/geocoding contact authority.
• Every new web or updated-Mobile directions request requires an explicit choice from the selected provider's closed provider-native mode catalog.
• Only the bounded released-Mobile compatibility adapter may translate an omitted mode using its exact reviewed built-in stable-key allow-list. Labels, categories, speeds, administrator mappings, and free-form Transport Profiles never infer provider mode.
• Mapbox Directions remains unsupported. Mapbox authority remains limited to separately authorized Permanent Geocoding.
• Geoapify is the storage-authorized hosted path for persistent geocoding and provider-neutral routed guidance, subject to attribution and the shared per-user guard.
• Nominatim remains only the bounded explicit-submit Trip Editor search fallback. It is not a Mobile routing provider.
• Mobile contacts routing providers only through authenticated Wayfarer and never receives provider credentials.
• Direct/manual routing stays provider-independent and network-free.

Required release order

1. Prepare Wayfarer 1.9.5 from the current source composition base through the repository's normal release helper and a narrow release-preparation PR.
2. Audit the release range, update version/release metadata and documentation as required, run proportional validation and exact-head CI, merge normally, and synchronize main.
3. Record the resulting final frozen backend SHA, version, release-preparation PR, exact-head CI evidence, migration boundary/manifest, and the identity and SHA-256 of the actual deployable artifact only after they exist.
4. Pause for explicit deployment authorization. Release preparation does not authorize production access, backup, migration, deployment, provider contact, rollback, installation, or publication.
5. After explicit authorization, prepare and verify the current PostgreSQL backup and rollback path together with the matching Data Protection key ring, durable uploads, hostname, authentication configuration, proxy routing, database ownership, and previous backend artifact.
6. Deploy the frozen 1.9.5 backend first and apply only the recorded authorized migrations from the recorded artifact/migration boundary.
7. Immediately smoke-test the currently released Mobile 1.2.0 against production.
8. On any released-Mobile smoke failure, roll back immediately. Do not begin observation and do not prepare or publish a new Mobile release.
9. If the smoke passes, observe backend and Mobile behavior for 1–2 days.
10. Only after observation passes and the maintainer records a separate Mobile go decision may the next Mobile version and release artifact be prepared, physically accepted, and published.

Keep the backend-to-Mobile interval as short as safely practical, but never skip the observation or physical-device gate merely to reduce elapsed time.

Frozen identity and artifact discipline

No 1.9.5 release-preparation PR, final frozen 1.9.5 SHA, 1.9.5 tag, 1.9.5 GitHub release, deployable artifact hash, release migration manifest, next-Mobile version, or next-Mobile artifact hash is recorded yet.

When each item actually exists, record it before it can authorize the corresponding action. An unrecorded or mismatching source SHA, version, artifact, checksum, migration payload, or release-relevant configuration identity must stop deployment, installation, or publication and return the coordinator to preparation/validation. Repackaging produces new bytes unless byte identity is independently proven; an earlier checksum cannot authorize different bytes.

Released-Mobile compatibility gate

The first runtime compatibility proof for backend 1.9.5 is the mandatory immediate production smoke with released Mobile 1.2.0:

• use an existing authenticated session or perform a fresh login;
• upload a Location;
• refresh Timeline;
• update and delete Timeline entries and verify synchronization;
• download a Trip;
• verify ordinary saved-geometry behavior and network-free Direct guidance.

The source, contract, integration, serialization, suite, and merged exact-head evidence support old-Mobile compatibility, but do not replace this runtime gate. A smoke failure requires immediate backend rollback and blocks observation and Mobile release preparation.

During the successful 1–2 day observation window, monitor startup, authentication, synchronization, migrations, provider operations, budgets, jobs, errors, and logs. Avoid unrelated production changes. A release-blocking observation stops the train and requires rollback or a correction through the normal reviewed workflow, followed by repetition of affected gates.

Compatibility and preservation requirements

The backend and released Mobile must preserve:

• authentication and session continuity;
• Location and Timeline upload, cursor/state progression, refresh, update, and deletion without loss, duplication, corruption, or reset;
• Trip download and ordinary/offline use;
• Trip, Place, Segment, waypoint, saved Segment geometry, accepted route provenance, and user-authored data;
• additive/tolerant DTO behavior for fields unknown to released Mobile;
• provider credentials when selections change and provider usage history when keys change;
• personal provider profiles, guards, admissions, retained authorized results, and attribution;
• network-free Direct/manual behavior;
• isolation of routing discovery, capability, authorization, stale-authority, or request failures from the global authenticated session, Timeline synchronization, and Trip download.

The updated Mobile must continue to prefer valid saved Segment geometry, then exact valid retained routes, then one explicit provider-native chooser, with Direct always available. It must not contact public OSRM, Geoapify, Mapbox, or another routing provider directly, invent Transport Profile authority, or silently fall back to a third-party provider.

Backup, migration, and rollback requirements

Before deployment:

• identify the exact frozen backend source, version, deployable artifact, artifact SHA-256, packaging command/runtime, ordered EF Core migration manifest, expected pre/post database boundaries, and pending-model-change result;
• identify whether migrations execute from that artifact or from a separately checksummed bundle;
• prepare and verify a current recovery set binding the PostgreSQL backup, complete matching Data Protection key ring, and durable uploads;
• preserve the exact previous backend artifact and tested restoration commands;
• confirm release-relevant non-secret configuration without recording secrets or hashes of secrets.

If deployment or the released-Mobile smoke fails, stop the service as required and restore PostgreSQL and its matching Data Protection key ring as one authority. Never restore one without the other when protected provider state may have changed. Preserve durable uploads and historical domain data. Provider contact can be stopped by deselection/revocation without deleting credentials or accepted data.

No production migration outside the recorded 1.9.5 manifest is authorized. #535 corrects only explicit EF context selection; it does not supply the broader lifecycle, artifact, adoption, backup, or managed rollback work owned by future #536.

Provider privacy and production smoke

Never record credentials, tokens, connection strings, Data Protection keys, private endpoints, raw personal queries, coordinates, coordinate-bearing provider URLs, raw provider responses, or hashes of secret values in this issue, logs, release evidence, or committed configuration.

After backend deployment, use only deliberate minimal maintainer-authorized production operations to verify:

• startup and the recorded migrations;
• released Mobile 1.2.0 compatibility smoke;
• tracking with no active geocoding provider;
• explicit Geoapify verification and selection for authorized accounts;
• one accepted attributed reverse-geocoding result;
• one explicit Trip Editor search and shared-credit accounting, including bounded fallback only where allowed;
• budget admission, exhaustion presentation, and no-contact behavior;
• one provider-neutral Geoapify route under explicit provider-native mode authority;
• no credential, raw search text, coordinate-bearing URL, response content, or protected authority leakage.

Automated tests must use controlled transports and never call billable/public providers.

Authorization boundary

Stop after backend 1.9.5 release preparation and evidence recording. Do not deploy, access production, create a production backup, run production migrations, contact providers, roll back, prepare the next Mobile version, build/publish its release artifact, install it for acceptance, tag it, or publish it without the corresponding explicit authorization.

This issue remains open as release/deployment authority until backend deployment, released-Mobile smoke, observation, separately authorized Mobile preparation/publication, and final integrity checks are complete.

Completion criteria

Close this issue only after:

1. backend 1.9.5 is prepared, exact-head CI-gated, published with its real recorded identities, explicitly authorized, backed up, deployed, migrated, smoke-tested, and observed successfully;
2. affected provider profiles are explicitly configured or deliberately left paused without inferred consent;
3. the next WayfarerMobile version is prepared only after the observation gate, installed over the existing application, and passes physical-device acceptance;
4. WayfarerMobile is published and verified against production;
5. documentation and release notes are live;
6. no unresolved release-blocking defect remains.