feat(E1-10): persist device-local settings

[davidru85]

Summary

• Persist the single device-local settings row with locale-derived defaults, validated partial updates and deletion self-healing.
• Inject native Android/iOS locale providers and apply only the first persisted currency to each new Fuel Entry form.
• Add the one-shot AppGraph bootstrap, D-105 continuous agent handoffs, D-106 through D-109 ADRs and complete project status records.

Story

E1-10 - Settings Persistence - S

Ready Check

• Backlog story is explicit
• Acceptance criteria reviewed
• Dependencies checked
• Required decisions are not Proposed or Pending
• Normative sections reviewed
• Expected verification identified
• Human review gates identified before work

In-Progress Checkpoint

• Date: 2026-09-01
• Branch and base: story/E1-10-settings-persistence from merged PR docs(E1-12): register FuelEntryStateHolderTest SIGSEGV fix story for issue #42 #43 at df37ec7
• Current phase and latest commit: REFACTOR review corrections complete at dbb3239
• Push and pull-request status: the reviewed REFACTOR commit has replaced the earlier branch tip; this remains PR feat(E1-10): persist device-local settings #44
• Completed since the previous checkpoint: all nine second-review items, D-109 / ADR-0110, E1-13 registration, corrected handoff and project log
• Verification evidence and known failures: the expanded complete local command passed with 627 actionable tasks and 110 aligned decisions/ADRs; all ten post-amend required CI checks passed. The pre-review CI shared-tests attempt hit the known E1-12 / issue [Bug]: FuelEntryStateHolderTest segfaults on iosSimulatorArm64 when the graph closes while collectors are live #42 Kotlin/Native SIGSEGV, and its isolated retry passed
• Open decisions or blockers: no owner decision is pending; executable iOS locale-provider behavior remains the registered E1-13 gap; human review is required for gated paths
• Exact next step: owner/code-owner review; do not merge on agent judgement

Scope Completed

• Added fixed-row SQLDelight settings queries and typed access without a migration.
• Added SettingsRepository, UpdateSettingsCommand and a self-healing SQLDelight implementation.
• Added one shared locale-currency rule and native Android/Foundation adapters.
• Applied the first persisted currency only to new Fuel Entry forms, preserving edits and existing entries.
• Added a one-shot, best-effort AppGraph bootstrap with scope cancellation before database close.
• Made the cross-thread closure flag volatile and gated missing-row locale resolution before the write path.
• Added the Android application unit-test task to canonical local and CI verification.
• Formalized continuously updated agent handoffs under D-105.

Acceptance Evidence

• Graph and real SQLDelight tests prove first-launch and access-time default creation.
• Database tests prove the fixed row, metric units, analytics disabled, deletion and no outbox/Fuel Entry mutation.
• Resolver and executed Android provider tests prove supported two-decimal currency validation and EUR fallback on Android; E1-13 owns executable iOS provider behavior.
• Repository tests prove partial updates, typed invalid-currency errors, no-op rejection and deletion self-healing.
• Four Fuel Entry form tests prove first persisted value, explicit-edit precedence, later-settings isolation and existing-entry isolation.
• Immediate-close and closed-write-gate tests prove the creation gate and idempotent close ordering; they do not prove absence of a write in D-106's residual check-then-act window.

Out of Scope / Not Done

• Settings UI remains owned by E4-01.
• Firebase Analytics integration remains owned by E3-09.
• Sign-out and account deletion remain owned by E2-05 and E3-10.
• The general Kotlin/Native graph-close race remains owned by E1-12 / issue [Bug]: FuelEntryStateHolderTest segfaults on iosSimulatorArm64 when the graph closes while collectors are live #42 under D-89.
• Executable IosLocaleProvider Foundation behavior remains owned by E1-13 under D-109.

Files Changed

• Settings domain/data/database and tests under core/common, core/database and feature/session.
• Fuel form and AppGraph lifecycle behavior plus tests under feature/fuel and shared.
• Native locale composition under androidApp, composition/ios and wiring/firebase.
• Project status, D-105 through D-109, ADR-0106 through ADR-0110, templates, handoff and project log.

Decisions Made

• D-105: live versioned handoff checkpoints for replacement-agent continuation.
• D-106: repository self-healing plus a terminating best-effort AppGraph bootstrap.
• D-107: holder-owned first persisted currency only.
• D-108: native host adapters with an explicit production provider parameter.
• D-109: canonical Android application unit tests plus an explicit E1-13 owner for the D-75 iOS behavior gap.
• SettingsDatabaseAccess.deleteSettings() has no production caller yet and is intentionally staged for the destructive local-data flows owned by E2-05 / E3-10; this is the reviewed exception to the docs/SPECIFICATION.md §11 no-speculative-generality rule.
• Per owner instruction, RED, GREEN and REFACTOR were committed locally, followed by one push instead of the default push after every phase.
• SQLDelight query definitions and native/provider integration use the explicit TDD ordering exemptions in docs/SPECIFICATION.md §11; their behavior is covered by tests and builds.

Verification Run

• Relevant tests pass
• Lint passes (ktlint, detekt)
• Coverage thresholds hold
• Architecture checks pass
• Contract check passes
• Relevant builds pass (Android, iOS simulator, Shared framework from :composition:ios)
• Documentation updated if behaviour, decisions or models changed

Commands or checks run:

./gradlew :feature:fuel:testAndroidHostTest :feature:session:testAndroidHostTest :shared:testAndroidHostTest
./gradlew :androidApp:testDebugUnitTest :feature:session:testAndroidHostTest :shared:testAndroidHostTest :build-logic:convention:test --rerun-tasks
./gradlew :feature:fuel:ktlintCheck :feature:session:ktlintCheck :shared:ktlintCheck :feature:fuel:iosSimulatorArm64Test :feature:session:iosSimulatorArm64Test
./gradlew :shared:iosSimulatorArm64Test
./gradlew ktlintCheck detekt architectureCheck contractCheck :build-logic:convention:test koverVerify :androidApp:assembleDebug :androidApp:testDebugUnitTest testAndroidHostTest iosSimulatorArm64Test -x :integration:firebase-auth:iosSimulatorArm64Test -x :integration:firebase-firestore:iosSimulatorArm64Test -x :wiring:firebase:iosSimulatorArm64Test -x :composition:ios:iosSimulatorArm64Test

Contract Impact

• No contract changes
• Updated docs/CONTRACTS.md §:

Existing settings, database, presentation and provider contracts were implemented without changing public repository/use-case signatures or the Swift ABI.

Decision Board Impact

• No decision changes
• Updated docs/DECISION_BOARD.md (D-105 through D-109) and ADR-0106 through ADR-0110

Shared-Write Modules Touched

• None
• core/database — no concurrent story or open pull request owned it at intake

Project Log Entry

• Entry appended to docs/PROJECT_LOG.md

Human Review Gate

Gates are defined canonically in AGENTS.md.

• Not applicable
• E0-00 owner decision closure
• Phase 0 closure
• E0-07 walking skeleton
• E1-05 consumption calculation
• E2-06 local owner adoption
• E3-01 Firestore security rules
• E3-03 synchronization engine
• Gated path (docs/SPECIFICATION.md, docs/DECISION_BOARD.md, AGENTS.md, docs/adr/**, core/database/**)
• Gated topic

Risks or Follow-ups

• E1-12 / issue [Bug]: FuelEntryStateHolderTest segfaults on iosSimulatorArm64 when the graph closes while collectors are live #42 still owns the general Kotlin/Native test graph-close race; E1-10 does not attempt that broader fix.
• E1-13 owns executable IosLocaleProvider Foundation behavior; the current framework link and source contract are not behavioral evidence.
• This pull request MUST NOT be merged on agent judgement because it changes core/database/** and other gated documentation paths.