feat(#673): SetEndReason plumbing, CompletedSet persistence, firmware bounds

shared/build.gradle.kts

@@ -210,8 +210,8 @@ sqldelight {
     databases {
         create("VitruvianDatabase") {
             packageName.set("com.devil.phoenixproject.database")
-            // Version 43 = initial schema (1) + 42 migrations (1.sqm through 42.sqm).
-            version = 43
+            // Version 44 = initial schema (1) + 43 migrations (1.sqm through 43.sqm).
+            version = 44
         }
     }
 }

shared/src/androidHostTest/kotlin/com/devil/phoenixproject/data/local/SchemaParityTest.kt

@@ -638,10 +638,73 @@
         assertEquals(true, getTables(driver).contains("PendingProfileContextRecovery"))
     }
 
+    @Test
+    fun `migration 42 to 43 adds set_end_reason column and preserves existing rows with default`() {
+        val driver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
+        buildSchemaAtVersion(driver, 42)
+
+        // Create prerequisite rows: UserProfile, Routine, WorkoutSession
+        // Note: profile_id is added by manifest reconciliation, not by migration 42.
+        // Use columns available at schema v42 (pre-reconciliation).
+        driver.execute(null, "INSERT INTO UserProfile(id,name,colorIndex,createdAt,isActive) VALUES('u1','U1',0,1,1)", 0)
+        driver.execute(null, "INSERT INTO Routine(id,name,createdAt) VALUES('r1','R1',1)", 0)
+        driver.execute(null, "INSERT INTO RoutineExercise(id,routineId,exerciseName,exerciseMuscleGroup,orderIndex,weightPerCableKg) VALUES('re1','r1','Bench','Chest',0,40.0)", 0)
+        driver.execute(null, "INSERT INTO WorkoutSession(id,timestamp,mode,targetReps,weightPerCableKg) VALUES('s1',1,'OldSchool',10,40.0)", 0)
+
+        // Insert a CompletedSet BEFORE migration 43 (no set_end_reason column yet)
+        driver.execute(
+            null,
+            """
+            INSERT INTO CompletedSet (id, session_id, set_number, set_type, actual_reps, actual_weight_kg, is_pr, completed_at)
+            VALUES ('cs-pre-mig', 's1', 1, 'STANDARD', 8, 40.0, 0, 1000)
+            """.trimIndent(),
+            0,
+        )
+
+        // Migrate 42 → 43 with resilient fallback (matches production behavior)
+        try {
+            VitruvianDatabase.Schema.migrate(driver, 42, 43)
+        } catch (_: Exception) {
+            applyMigrationResilient(driver, 42)
+        }
+
+        assertEquals(true, columnExistsInDriver(driver, "CompletedSet", "set_end_reason"))
+
+        // Pre-existing row must have the default value
+        assertEquals("TARGET_REPS_REACHED", queryScalar(driver, "SELECT set_end_reason FROM CompletedSet WHERE id = 'cs-pre-mig'"))
+    }
+
+    @Test
+    fun `resilient migration 43 fallback adds set_end_reason when column already exists`() {
+        val driver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
+        buildSchemaAtVersion(driver, 42)
+
+        // Simulate schema drift: column already added by heal
+        driver.execute(null, "ALTER TABLE CompletedSet ADD COLUMN set_end_reason TEXT NOT NULL DEFAULT 'TARGET_REPS_REACHED'", 0)
+
+        driver.execute(null, "INSERT INTO UserProfile(id,name,colorIndex,createdAt,isActive) VALUES('u1','U1',0,1,1)", 0)
+        driver.execute(null, "INSERT INTO Routine(id,name,createdAt) VALUES('r1','R1',1)", 0)
+        driver.execute(null, "INSERT INTO RoutineExercise(id,routineId,exerciseName,exerciseMuscleGroup,orderIndex,weightPerCableKg) VALUES('re1','r1','Bench','Chest',0,40.0)", 0)
+        driver.execute(null, "INSERT INTO WorkoutSession(id,timestamp,mode,targetReps,weightPerCableKg) VALUES('s1',1,'OldSchool',10,40.0)", 0)
+        driver.execute(
+            null,
+            """
+            INSERT INTO CompletedSet (id, session_id, set_number, set_type, actual_reps, actual_weight_kg, is_pr, completed_at, set_end_reason)
+            VALUES ('cs-resilient', 's1', 1, 'STANDARD', 8, 40.0, 0, 1000, 'STALL_FAILURE')
+            """.trimIndent(),
+            0,
+        )
+
+        // Resilient fallback should succeed even though the column already exists
+        applyMigrationResilient(driver, 43)
+
+        assertEquals("STALL_FAILURE", queryScalar(driver, "SELECT set_end_reason FROM CompletedSet WHERE id = 'cs-resilient'"))
+    }
+
     // ==================== HELPERS ====================
 
     companion object {
-        private const val EXPECTED_SCHEMA_VERSION = 43L
+        private const val EXPECTED_SCHEMA_VERSION = 44L
         private val CANONICAL_UUID_REGEX = Regex("^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")
 
         /**

shared/src/androidHostTest/kotlin/com/devil/phoenixproject/data/repository/SqlDelightCompletedSetRepositoryTest.kt

@@ -3,6 +3,7 @@ package com.devil.phoenixproject.data.repository
 import com.devil.phoenixproject.database.VitruvianDatabase
 import com.devil.phoenixproject.domain.model.CompletedSet
 import com.devil.phoenixproject.domain.model.PlannedSet
+import com.devil.phoenixproject.domain.model.SetEndReason
 import com.devil.phoenixproject.domain.model.SetType
 import com.devil.phoenixproject.testutil.createTestDatabase
 import kotlin.test.assertEquals
@@ -71,6 +72,37 @@ class SqlDelightCompletedSetRepositoryTest {
         assertEquals(2, sets.size)
     }
 
+    @Test
+    fun `saveCompletedSet round-trips setEndReason STALL_FAILURE`() = runTest {
+        val completed = completedSet("cset-stall", "session-1", setNumber = 1, setEndReason = SetEndReason.STALL_FAILURE)
+        repository.saveCompletedSet(completed)
+
+        val loaded = repository.getCompletedSets("session-1").first { it.id == "cset-stall" }
+        assertEquals(SetEndReason.STALL_FAILURE, loaded.setEndReason)
+    }
+
+    @Test
+    fun `saveCompletedSet round-trips setEndReason TARGET_REPS_REACHED default`() = runTest {
+        val completed = completedSet("cset-default", "session-1", setNumber = 1)
+        repository.saveCompletedSet(completed)
+
+        val loaded = repository.getCompletedSets("session-1").first { it.id == "cset-default" }
+        assertEquals(SetEndReason.TARGET_REPS_REACHED, loaded.setEndReason)
+    }
+
+    @Test
+    fun `saveCompletedSet round-trips all SetEndReason values`() = runTest {
+        for ((index, reason) in SetEndReason.entries.withIndex()) {
+            repository.saveCompletedSet(completedSet("cset-$index", "session-1", setNumber = index + 1, setEndReason = reason))
+        }
+
+        val loaded = repository.getCompletedSets("session-1")
+        assertEquals(SetEndReason.entries.size, loaded.size)
+        for ((index, reason) in SetEndReason.entries.withIndex()) {
+            assertEquals(reason, loaded[index].setEndReason, "Mismatch at index $index")
+        }
+    }
+
     private fun plannedSet(
         id: String,
         routineExerciseId: String,
@@ -89,7 +121,7 @@ class SqlDelightCompletedSetRepositoryTest {
         restSeconds = restSeconds,
     )
 
-    private fun completedSet(id: String, sessionId: String, setNumber: Int) = CompletedSet(
+    private fun completedSet(id: String, sessionId: String, setNumber: Int, setEndReason: SetEndReason = SetEndReason.TARGET_REPS_REACHED) = CompletedSet(
         id = id,
         sessionId = sessionId,
         plannedSetId = null,
@@ -100,6 +132,7 @@ class SqlDelightCompletedSetRepositoryTest {
         loggedRpe = null,
         isPr = false,
         completedAt = 1000L + setNumber,
+        setEndReason = setEndReason,
     )
 
     private fun insertRoutine(id: String) {

shared/src/androidHostTest/kotlin/com/devil/phoenixproject/util/DataBackupManagerRoutineNameTest.kt

@@ -542,6 +542,7 @@ class DataBackupManagerRoutineNameTest {
             logged_rpe = null,
             is_pr = 0,
             completed_at = 1700000060000L,
+            set_end_reason = "TARGET_REPS_REACHED",
         )
 
         // Export just this session
@@ -650,6 +651,7 @@ class DataBackupManagerRoutineNameTest {
             logged_rpe = null,
             is_pr = 0,
             completed_at = 1_700_000_006_000L,
+            set_end_reason = "TARGET_REPS_REACHED",
         )
         database.vitruvianDatabaseQueries.insertCompletedSetIgnore(
             id = "cs-row",
@@ -662,6 +664,7 @@ class DataBackupManagerRoutineNameTest {
             logged_rpe = null,
             is_pr = 0,
             completed_at = 1_700_000_106_000L,
+            set_end_reason = "TARGET_REPS_REACHED",
         )
 
         val result = backupManager.exportRoutine(sharedRoutineSessionId)

shared/src/commonMain/kotlin/com/devil/phoenixproject/data/local/MigrationStatements.kt

@@ -1016,5 +1016,12 @@ WHERE gs.rowid = (
     SELECT id FROM UserProfile""",
     )
 
+    // Migration 43: Add set_end_reason to CompletedSet (Issue #673 PR 1)
+    // Records why a set ended for workout history analytics.
+    // Mirrors 43.sqm exactly.
+    43 -> listOf(
+        "ALTER TABLE CompletedSet ADD COLUMN set_end_reason TEXT NOT NULL DEFAULT 'TARGET_REPS_REACHED'",
+    )
+
     else -> emptyList()
 }

shared/src/commonMain/kotlin/com/devil/phoenixproject/data/local/SchemaManifest.kt

@@ -1141,7 +1141,7 @@ internal val manifestTables: List<SchemaTableOperation> = listOf(
         """.trimIndent(),
     ),
 
-    // CompletedSet -- migration 10, full shape (no later migrations add columns)
+    // CompletedSet -- migration 10, columns added by later migrations: set_end_reason (m43)
     SchemaTableOperation(
         table = "CompletedSet",
         createSql = """
@@ -1156,6 +1156,7 @@ internal val manifestTables: List<SchemaTableOperation> = listOf(
                 logged_rpe INTEGER,
                 is_pr INTEGER NOT NULL DEFAULT 0,
                 completed_at INTEGER NOT NULL,
+                set_end_reason TEXT NOT NULL DEFAULT 'TARGET_REPS_REACHED',
                 FOREIGN KEY (session_id) REFERENCES WorkoutSession(id) ON DELETE CASCADE,
                 FOREIGN KEY (planned_set_id) REFERENCES PlannedSet(id) ON DELETE SET NULL
             )
@@ -1437,6 +1438,10 @@ internal val manifestColumns: List<SchemaHealOperation> = listOf(
     // ── ExternalActivity (1 column, migration 31) ──────────────────────
     // Migration 31: provider tombstone handling
     SchemaHealOperation("ExternalActivity", "deletedAt", "ALTER TABLE ExternalActivity ADD COLUMN deletedAt INTEGER"),
+
+    // ── CompletedSet (1 column, migration 43) ──────────────────────────
+    // Migration 43: set-end reason for workout history analytics (Issue #673 PR 1)
+    SchemaHealOperation("CompletedSet", "set_end_reason", "ALTER TABLE CompletedSet ADD COLUMN set_end_reason TEXT NOT NULL DEFAULT 'TARGET_REPS_REACHED'"),
 )
 
 // ============================================================

shared/src/commonMain/kotlin/com/devil/phoenixproject/data/repository/SqlDelightCompletedSetRepository.kt

@@ -5,6 +5,7 @@ import app.cash.sqldelight.coroutines.mapToList
 import com.devil.phoenixproject.database.VitruvianDatabase
 import com.devil.phoenixproject.domain.model.CompletedSet
 import com.devil.phoenixproject.domain.model.PlannedSet
+import com.devil.phoenixproject.domain.model.SetEndReason
 import com.devil.phoenixproject.domain.model.SetType
 import com.devil.phoenixproject.domain.model.WorkoutSession
 import com.devil.phoenixproject.domain.model.generateUUID
@@ -54,6 +55,7 @@ class SqlDelightCompletedSetRepository(db: VitruvianDatabase) : CompletedSetRepo
         loggedRpe: Long?,
         isPr: Long,
         completedAt: Long,
+        setEndReason: String,
     ): CompletedSet = CompletedSet(
         id = id,
         sessionId = sessionId,
@@ -65,6 +67,8 @@ class SqlDelightCompletedSetRepository(db: VitruvianDatabase) : CompletedSetRepo
         loggedRpe = loggedRpe?.toInt(),
         isPr = isPr == 1L,
         completedAt = completedAt,
+        setEndReason = runCatching { SetEndReason.valueOf(setEndReason) }
+            .getOrElse { SetEndReason.TARGET_REPS_REACHED },
     )
 
     // ==================== Planned Sets ====================
@@ -178,6 +182,7 @@ class SqlDelightCompletedSetRepository(db: VitruvianDatabase) : CompletedSetRepo
                 logged_rpe = set.loggedRpe?.toLong(),
                 is_pr = if (set.isPr) 1L else 0L,
                 completed_at = set.completedAt,
+                set_end_reason = set.setEndReason.name,
             )
         }
     }
@@ -233,6 +238,7 @@ class SqlDelightCompletedSetRepository(db: VitruvianDatabase) : CompletedSetRepo
             logged_rpe = completedSet.loggedRpe?.toLong(),
             is_pr = if (completedSet.isPr) 1L else 0L,
             completed_at = completedSet.completedAt,
+            set_end_reason = completedSet.setEndReason.name,
         )
 
         completedSet
@@ -252,6 +258,7 @@ class SqlDelightCompletedSetRepository(db: VitruvianDatabase) : CompletedSetRepo
                     logged_rpe = set.loggedRpe?.toLong(),
                     is_pr = if (set.isPr) 1L else 0L,
                     completed_at = set.completedAt,
+                    set_end_reason = set.setEndReason.name,
                 )
             }
         }

shared/src/commonMain/kotlin/com/devil/phoenixproject/domain/model/TrainingCycleModels.kt

@@ -375,6 +375,25 @@ data class PlannedSet(
     }
 }
 
+/**
+ * Reason a set ended. Persisted on [CompletedSet] for workout history analytics.
+ * Threaded through [ActiveSessionEngine.handleSetCompletion] from every call site.
+ */
+enum class SetEndReason {
+    /** Rep target reached or WORKOUT_COMPLETE machine event */
+    TARGET_REPS_REACHED,
+    /** Stall detection auto-stop fired (velocity/deload threshold) */
+    STALL_FAILURE,
+    /** VBT auto-end: consecutive reps above velocity-loss threshold */
+    VBT_AUTO_END,
+    /** User manually stopped the set */
+    USER_STOPPED,
+    /** Cable released detected by machine */
+    CABLE_RELEASED,
+    /** Timed exercise countdown reached zero */
+    TIMER_EXPIRED,
+}
+
 /**
  * A completed set with actual performance data.
  * Records what the user actually did.
@@ -390,6 +409,7 @@ data class CompletedSet(
     val loggedRpe: Int?,
     val isPr: Boolean,
     val completedAt: Long,
+    val setEndReason: SetEndReason = SetEndReason.TARGET_REPS_REACHED,
 ) {
     /**
      * Calculate estimated 1RM using canonical hybrid formula (Brzycki ≤10 reps, Epley >10 reps).
@@ -412,6 +432,7 @@ data class CompletedSet(
             actualWeightKg: Float,
             loggedRpe: Int? = null,
             isPr: Boolean = false,
+            setEndReason: SetEndReason = SetEndReason.TARGET_REPS_REACHED,
         ) = CompletedSet(
             id = id,
             sessionId = sessionId,
@@ -423,6 +444,7 @@ data class CompletedSet(
             loggedRpe = loggedRpe,
             isPr = isPr,
             completedAt = currentTimeMillis(),
+            setEndReason = setEndReason,
         )
     }
 }