P2: Regenerate the mobile API client and validate native release

[tomqwu]

Current Priority Decision

The Church/Basketball business milestone is complete. Native release remains an optional platform track and is not required for the current web/API release work.

Execution lane: phase: platform-later. Status: deferred for native release.

Current Evidence

Deterministic client generation and maintained Flutter tests are documented. An iOS simulator flow and Android debug APK build have passed previously. Current host discovery shows an available iOS simulator, no Android emulator/system image and no physical device. This is not signed-device or store-release evidence.

Remaining

When the owner prioritizes native release and names the target platforms, refresh generation against the selected API revision, run maintained/generated tests, validate offline/retry/restart and core flows on the required simulators and physical devices, then prepare signing/store artifacts only with explicit authorization. Do not install global Android system images, use signing identities, submit to stores or claim physical-device acceptance without authorization and evidence.

All tests and code review remain local. GitHub Actions does not run tests, and Ollama is not a code-review provider.

---

Current Implementation Handoff

Prepared 2026-09-13 for a lower-cost builder at source 21a4a804aa57580451edded04736b1f51aef7e48.
No CI checks. All implementation validation and code review run locally.
Use the shared builder contract and this issue's work packages; no xhigh model or automatic model upgrade is required. This is a detailed recommendation, not a claim that a smaller model cannot make mistakes or that tests have passed.

Risk/review focus: Medium/high: generated client contracts and native release.
Start condition: DEFERRED FOR NATIVE RELEASE. Continue only when the owner prioritizes the native track and names targets; do not install global images or use signing/store accounts without authorization.

Source of Truth and Current State

• Makefile
• tests/contract/openapi.snapshot.json
• mobile/pubspec.yaml
• mobile/pubspec.lock
• mobile/api_client/
• mobile/lib/
• mobile/integration_test/
• mobile/scripts/run_integration_tests.sh
• mobile/SMOKE.md
• mobile/TESTFLIGHT.md
• mobile/ANDROID_RELEASE.md
• mobile/fastlane/Fastfile

make mobile-codegen pins the npm wrapper but still uses --skip-validate-spec and a hardcoded developer Flutter path. Validate actual generator/JDK/Flutter versions; do not repeat the historical claim that Java is unavailable on today's machine.

This handoff supersedes stale implementation statements in the background below. Preserve existing successful behavior and tests. Recheck the current branch before editing; the baseline is a source pointer, not permission to discard newer changes.

Dependencies and Ownership

• Current execution prerequisite: owner reactivates this deferred track after P1: Accept complete Church and Basketball day-to-day business flows #289. Original provider/platform dependencies are retained as future acceptance, not blockers for the current business flow.
• Coordinate, but do not wait for entire tickets to close merely to inspect/write isolated tests: P2: Validate production configuration after business-flow acceptance #258, P2: Build and validate the production artifact after business acceptance #265, P3: Defer paid billing and SMS product acceptance #270, P1: Reconcile every document and legacy spec with current source #277, P1: Make README, examples and public site match the product #278, P1: Repair local test entry points, coverage and isolation #281.
• The final commands below require P1: Repair local test entry points, coverage and isolation #281's safe local environment or an equivalently verified isolated setup. A missing dependency blocks only the slice that needs it; document that state.
• Shared source/ORM/migration changes are serialized per the master roadmap. Do not start concurrent edits to the same ownership area.

Recommended Decisions

1. Generate from a locally validated current OpenAPI snapshot. Pin both wrapper and actual generator version; remove hardcoded developer paths and resolve supported FLUTTER/DART/JAVA overrides.
2. Regenerate the complete client/docs/tests deterministically; never manually patch generated outputs to manufacture compatibility. Run generation twice and require the second run to produce no unexpected changes.
3. Keep widget/unit, emulator integration, native build, signing/upload and physical-device acceptance distinct. No visible device is not a passing test.
4. Preserve secure storage, refresh/revocation and deep-link recovery; validate backend auth/schema-only changes against native callers, not only files under mobile/.

Small Work Packages

Each item is one reviewable slice, not permission for one giant PR. Add the failing regression first; finish code, tests and affected docs for that slice together. Leave this issue open until all packages and original acceptance criteria are satisfied or explicitly revised by the owner.

• 191.1: Repair/preflight the generator toolchain in one narrow PR and validate the schema before generation.
• 191.2: Regenerate, review endpoint/model diffs including string SMS IDs and corrected auth contracts, then adapt maintained app code.
• 191.3: Run analysis/unit/widget/integration/native builds on explicitly named local targets; verify login/invite/reset/offline/retry and six-week member flows.
• 191.4: Update all native release/support docs and generated-doc link results; record artifact/device/server identities and request separate store authorization.

Required Regression Cases

These are specifications for tests to add/retain, not claimed execution results. Each new negative case must assert unchanged unauthorized state and zero forbidden side effects.

• T191-01: Second identical generation -> no drift; invalid schema or missing tool -> clear failure.
• T191-02: Expired/revoked session -> refresh/sign-in as designed, with no token logged or preserved after logout.
• T191-03: Invitation/reset deep link with valid/expired/malformed token -> usable correct screen or safe fallback; wrong tenant cannot be accessed.
• T191-04: Offline/retry and app restart preserve intended state without duplicate claims; simulator pass is not labeled physical-device pass.

Local Commands and Evidence

Existing targeted commands (paths checked against the audit source; run only after the stated safe preflight):

poetry run pytest tests/contract -q
make mobile-codegen
make test-mobile
./mobile/scripts/run_integration_tests.sh

Also run the shared formatting/lint/touched-type/unit/full-suite and local review protocol from #252 for the final pushed revision. Add new targeted tests to these commands when implemented. Run API and browser tiers in separate processes. Native, PostgreSQL, image, provider and operator drills require their explicit environment; an unavailable tool/target is blocked/not run, never a pass.

Schema and Compatibility

Generated API changes follow the canonical snapshot and reviewed server migrations. Native build numbers/store metadata are separate release changes, not automatic codegen churn.

Stop Conditions

Missing JDK/Flutter/device/signing credentials blocks only the affected slice. Do not auto-install global tools, use signing secrets or submit a store release without approval.

After two failed focused repair attempts without new diagnostic evidence, stop the affected package and post the exact failure, commands, suspected boundary and needed decision. Do not silently broaden scope, weaken tests or upgrade models. A fresh local reviewer checks: Inspect schema diff and generated determinism, maintained caller adaptations, secure storage/deep links and actual native artifact/device outcomes.

Completion Receipt

• Work-package and regression IDs above map to changed files and actual results.
• Commands, versions, dates, pass/fail/skip/not-run counts, logs/screenshots and tested head/base SHAs are linked.
• A separate local review records findings and resolution; self-review is labeled if used and is not misrepresented as independent review.
• Affected docs/README/playbooks/screenshots and dependency/roadmap status are reconciled, not left as unnamed follow-ups.
• If implementation is authorized through PR/merge, GitHub reports mergeable and the shared local-evidence requirements are met; reviewer agents never merge.
• No hosted CI check, status attestation, Ollama reviewer, live provider action, deployment, real-data purge or store submission was introduced by implication.

Copyable Builder Prompt

First read this issue's Current Priority Decision and #289. Run only its NOW slice.
If this issue is deferred, report that state instead of starting the older package list.
Implement the next ready work package in tomqwu/SignUpFlow issue #191.
Read its Current Implementation Handoff and #252 Builder Handoff Contract first.
Inspect current source and preserve newer/unrelated changes. Start with the
package's failing regression, then complete code, local tests, local review and
affected docs/assets together. Do not skip acceptance or invent passing evidence.
No CI checks or Ollama code review. Do not deploy, activate providers, purge real
data or submit to stores. Stop and report unmet prerequisites or policy decisions.
Record the package/test IDs and exact reviewed/tested source SHAs before claiming done.

---

Earlier Audit and Acceptance Context

Current policy (2026-09-13)

No CI checks. Everything is validated locally. This includes code review,
formatting, lint, type checks, migrations, all test tiers, security scans,
artifact checks and mobile validation. Do not add hosted jobs, required CI
statuses, synthetic success checks or an Ollama reviewer. GitHub is for source,
PRs, issues and publication, not validation.

Record commands, environment, results, limitations and reviewed head/base SHAs.
Builders merge only with completed local evidence and GitHub mergeability;
reviewer agents never merge. Real staging/provider/device acceptance remains
required where applicable, driven by authorized local operator tools.
Historical evidence and older comments do not override this policy.

Production readiness update (2026-09-09)

Parent roadmap: #252. Priority: P2, optional native-release track (Phase E); does not block the web/API pilot. Suggested owner: Mobile engineer. Original estimate (superseded; re-estimate remaining work): 3-5 engineering days plus device/signing access.

The May 19 comment already corrected the original Java-only blocker: that environment had Java but lacked Flutter/Dart. Tool availability must be rechecked on the implementation machine; neither absence is assumed for today's environment. The generated client remains documented as stale in mobile/README.md. Preserve generated output integrity and do not hand-edit client files to simulate codegen.

Plan and dependencies

1. After API authorization and contracts stabilize (P0: Close tenant data exposure in scheduling APIs and exports #254, P0: Prevent privileged signup and enforce organization membership #255, P3: Defer paid SMS; require safety before enablement #257, P1: Honor saved constraints and preserve assignment roles #263), verify supported Java/Flutter/Dart and generator versions, then run make mobile-codegen. If optional provider endpoints are included, coordinate with P3: Defer paid billing and SMS product acceptance #270.
2. Run the existing contract snapshot checks first; regenerate from the canonical schema and review only intentional output changes. Add a reproducibility/drift check so future API changes cannot silently strand the client.
3. Pin a compatible local Flutter version, use the lockfile, and require local drift validation for backend/schema changes as well as mobile changes. Record results in the PR (P1: Make local validation and review evidence reproducible #259); do not add a CI job.
4. Run flutter analyze --no-fatal-infos, flutter test, and native builds. Exercise real iOS/Android login, secure token storage, expired-token refresh, invitation/reset deep links, permission denial, logout, offline/retry and current volunteer/admin core journeys against the staging release (P2: Build and validate the production artifact after business acceptance #265).
5. Follow the existing mobile smoke/TestFlight documents after verifying they match the current API. Record device/OS/build/server SHA, artifacts and actual outcomes. Signing, store submission and live release are separate owner decisions.

Acceptance criteria

• Client code is reproducibly generated from the current schema; no hand-edited or unverified stubs.
• An API/schema-only change includes recorded local mobile compatibility verification.
• Analyze, unit/widget tests, Android/iOS builds and critical integration flows pass on documented supported toolchains.
• Secure storage/refresh/revocation and invitation/reset fallback links work on real device/emulator runs.
• The mobile support/release matrix names known limitations and links evidence; missing local/device evidence is not treated as a verified release.
• README and this issue reflect the actual remaining blocker, not the historical Java-only assumption.

Original issue context

Status: blocked, not faked (per the GUI-e2e honesty rule).

The marathon added new API endpoints in P2 — POST /api/v1/auth/change-password (P1.2), the billing router (P2.14), and the sms router /api/sms/* (P2.16). The generated Flutter API client at mobile/api_client/ predates these and is therefore stale.

Regenerating it is make mobile-codegen, which runs @openapitools/openapi-generator-cli — a Java tool. This environment has no Java runtime (java -version → "Unable to locate a Java Runtime"), so the client cannot be regenerated or verified here.

Decision: do not commit a hand-edited / partial / unverified client (that's exactly the "faked mobile work" failure mode). This is filed as the known gap.

To resolve (env with JDK 17):

make mobile-codegen        # regenerates mobile/api_client from tests/contract/openapi.snapshot.json
cd mobile && flutter analyze && flutter test

The OpenAPI snapshot is already current (refreshed in P2.14/P2.16), so codegen is a clean mechanical step once a JDK is available.

Tracked under the marathon (#145). P4.24 (Flutter CI lane) and P4.25 (honest unpark banner) proceed independently.

Whole-repository audit scope (2026-09-13)

Baseline: 21a4a804aa57580451edded04736b1f51aef7e48. This addendum assigns full-scope follow-through; it is not a new test pass or production sign-off. No CI checks; all review and validation runs locally.

Account for all 643 tracked mobile files, including 120 generated Markdown documents, generated Dart sources/tests, platform metadata/assets, two integration_test flows, fastlane, signing examples, prototypes and release docs. The link scan found 66 distinct generated-doc relative-target candidates; repair through generation/templates, never hand-edit generated output as proof. #277 owns documentation dispositions, #278 truthful README/site claims, #281 explicit local unit/widget versus integration/build command coverage. Run codegen and native artifact validation against the reviewed current schema after API contracts stabilize; review auth/deep links/storage/offline/UI behavior on named devices. Store submission, credentials and physical-device acceptance remain separate approvals; no native build or device run occurred in this planning audit.

Keep evidence and disposition synchronized with master roadmap #252 and documentation ledger #277. Close only after the remaining acceptance criteria have linked local results; a planning/audit note is not completion.

[tomqwu]

Status correction (keeping this tracking issue honest, per the P4.25 unpark rule):

The original blocker no longer applies. A fresh autopilot environment now ships a Java runtime:

$ java -version
openjdk version "21.0.10" 2026-01-20
OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04)

The Makefile's JAVA_BIN auto-detect (command -v java) resolves, so make mobile-codegen (@openapitools/openapi-generator-cli@2.20.2) is itself runnable here — the "Unable to locate a Java Runtime" condition in the issue body is stale.

The real remaining blocker is the verification half, not codegen. This environment has no Flutter/dart SDK:

$ flutter --version  -> command not found
$ dart --version     -> command not found

So the mandated post-codegen step — cd mobile && flutter analyze && flutter test — cannot run here. Per this issue's own decision and the repo honesty rule, regenerating and committing an unverified client is the "faked mobile work" failure mode, so the client was deliberately not regenerated/committed this run.

Updated resolution path (Java is already satisfied; only Flutter is needed):

make mobile-codegen                       # Java present — runs here
cd mobile && flutter analyze && flutter test   # needs a Flutter SDK

Any environment with a Flutter SDK can now close this in one mechanical pass; the OpenAPI snapshot is still current. This stays mobile-scoped and is not picked up autonomously without an explicit signal.

---

Generated by Claude Code

[tomqwu]

Partial implementation receipt: PR #293 merged as 73b5a99.

The Flutter signup caller now uses the atomic organization-bootstrap contract, the checked-in Dart API client was regenerated from the current OpenAPI schema, and make test-mobile passed 65 tests on head a0339ed. Native-device qualification and remaining mobile acceptance criteria are still outstanding, so this issue remains open.

[tomqwu]

SMS contract compatibility receipt from #257

PR #326 corrects four OpenAPI ID shapes from integer to string: verification request person_id, verification-code request person_id, broadcast recipient_ids, and SMS usage org_id. The corresponding generated Dart models, serializers, docs, and tests are synchronized.

No database migration is required; persistent SMS person/org columns and provider SIDs already use string/unique storage. Targeted Dart model tests passed 7/7 and targeted analysis reported no issues.

Generator limitation: the documented OpenAPI generator produced broad unrelated formatting drift and Flutter build_runner then hit the host Xcode license/tool broken-pipe boundary. That broad drift was discarded; only the three schema-affected generated models were updated. This is validated contract compatibility, not a claim that a full mobile build ran.

[tomqwu]

Local mobile/codegen completion receipt

PR #332 merged to main as a591b4133356ee398fa9555411a7a77b23192b8f from exact reviewed/tested head 3f4ab2084301dab38682dfca5b23f3d54ba9dcd6 over base 2c127e62eea189ce5a44a5de6d31de3ccc2d521e.

Completed locally:

• 191.1 / T191-01: pinned wrapper 2.20.2 and generator 7.14.0, discovered JDK/Flutter/Dart tools without a developer-specific path, validated the canonical OpenAPI snapshot, generated twice in isolation, and failed closed on tool/schema/output drift.
• 191.2: regenerated the complete Dart package from the canonical snapshot. The generated removal of obsolete OrganizationCreate, auth/validation changes, string SMS IDs, serializers, docs, and tests were reviewed; no generated file was hand-patched.
• 191.3 local target portion: maintained analysis and 65 tests passed; generated analysis exposed 48 nonfatal generator warnings and 692 generated tests passed; login plus invitation/reset routes passed on an iPhone 17 Pro iOS 26.4 simulator; an Android debug APK built.
• 191.4 local documentation portion: README, smoke, TestFlight, Android, testing, roadmap, agent guidance, generated docs, and documentation ledger now distinguish local/simulator/debug evidence from device/signing/store acceptance.
• Existing mobile tests cover refresh/revocation, concurrent refresh, logout token clearing, invitation expiry/reuse, reset expiry, retry/error states, and schedule/availability widgets. The exact native runner executes integration files sequentially so app lifecycle teardown cannot strand the next test.

Exact evidence:

• make test-all: 1,985 passed / 21 skipped / 0 failed/errors, including 73 Playwright; report test-artifacts/local-validation/20260915T164731.844906Z-21085-4c13ca4f/report.json has matching source SHA and tracked_tree_clean=true.
• make mobile-codegen-check: canonical schema valid; both generated trees identical; checked-in client matches.
• make test-mobile-generated: 692 passed; 48 visible nonfatal generated-code warnings.
• flutter analyze --no-fatal-infos: no warnings/errors; four pre-existing Riverpod deprecation infos.
• make test-mobile: 65 passed.
• mobile/scripts/run_integration_tests.sh: deep-link and login suites passed on simulator UUID 70CA2B69-483E-4E0E-AD65-884F9902AD33.
• Android debug APK built at mobile/build/app/outputs/flutter-apk/app-debug.apk.
• make test-docs: 188 manual / 138 generated documents passed current inventory/link validation.
• Black, Ruff, scoped mypy, diff/secret review passed. Whole-api mypy remains the known untouched legacy baseline of 806 errors.
• GitHub reported PR Make mobile client generation reproducible #332 MERGEABLE / CLEAN before builder squash merge. Local self-review was used and is not represented as independent review.

Keep #191 open for acceptance that cannot be supplied by this authorized local run:

• no Android emulator exists and no physical iOS/Android device is connected;
• signed iOS/Android artifacts, secure storage on physical hardware, offline/restart behavior on a real device, staging/live backend, TestFlight, Play, and store acceptance were not run;
• standalone multi-architecture iOS simulator build is affected by upstream Xcode 27 beta lipo -verify_arch rejects multiple architectures during iOS simulator build flutter/flutter#188461, while device-specific simulator integration builds pass;
• signing, account access, live environment use, and store submission require explicit owner authorization.

No CI test/review, Ollama code review, live provider action, deployment, paid activation, branch deletion, or store submission occurred.

[tomqwu]

Follow-up mobile compatibility receipt

Two later merged PRs preserve and extend the local mobile/codegen result recorded above:

• PR Add tenant-scoped solution ICS export #333 added the tenant-scoped solution ICS export, refreshed the OpenAPI snapshot, regenerated the Dart client/docs deterministically, passed make mobile-codegen-check, 65 maintained mobile tests, and 692 generated client tests with the already documented 48 nonfatal generator warnings.
• PR Correct stale API, environment, and mobile guidance #334 corrected mobile/SMOKE.md so invitation creation/resend, local mail capture, direct-token testing, and authorized external-provider evidence are no longer conflated.
• PR Correct stale API, environment, and mobile guidance #334 exact-head make test-all: 1,985 passed / 21 skipped / 0 failed, including 73 Playwright; report test-artifacts/local-validation/20260915T183125.899040Z-48293-4928b80a/report.json.
• Documentation validation remains 188 manual / 138 generated, and screenshot-manifest validation passes.

The issue correctly remains open for real Android-emulator/physical-device, signed artifact, staging backend, secure-storage/offline/restart, TestFlight/Play, and store acceptance. Those need explicit device, account, signing, environment, and release authorization. No store submission, deployment, provider call, hosted CI, or Ollama review occurred.

[tomqwu]

Current-main mobile compatibility refresh

The local mobile boundary was rerun after PR #337 against exact main cb77a9fd295880359055e8aecc96bbb9d868c19e.

• make mobile-codegen-check: OpenAPI valid; wrapper 2.20.2, generator 7.14.0, OpenJDK 17.0.20.1; two isolated generated trees were identical and matched the checked-in Dart client.
• make test-mobile: 65 passed.
• flutter analyze --no-fatal-infos: completed with the same four nonfatal Riverpod .stream deprecation infos and no warning/error failure.
• mobile/scripts/run_integration_tests.sh: deep-link and authenticated-login flows passed on iPhone 17 Pro iOS 26.4 simulator UUID 70CA2B69-483E-4E0E-AD65-884F9902AD33.
• Device inventory: that iOS simulator, macOS desktop, and Chrome only. No Android emulator, wireless device, or physical iOS/Android device was present.
• The SendGrid callback is excluded from OpenAPI, so it introduced no generated public-client surface or drift.

Keep #191 open. This run does not prove Android emulator behavior, physical-device secure storage/offline/restart, signed release artifacts, staging backend compatibility, TestFlight/Play, or store acceptance. No signing, account, deployment, provider, or store action was performed.