feat: add Folder Autopilot module slice

.prettierignore

@@ -6,6 +6,9 @@ docs/
 **/README.md
 pnpm-lock.yaml
 packages/contracts/generated/
+# Published schema bytes are compatibility-versioned and must not be rewritten
+# by a formatting-only change.
+packages/contracts/schemas/v1/recipe-assignment.schema.json
 packages/design-tokens/brand/derivatives.json
 services/engine/test/fixtures/fake-uv-prefix
 infrastructure/local/.env.example

apps/android/app/src/androidTest/java/com/databreeze/android/MainActivityTest.kt

@@ -36,4 +36,19 @@ class MainActivityTest {
         composeRule.onNodeWithTag("capture-screen").assertIsDisplayed()
         composeRule.onNodeWithText(savedText).assertIsDisplayed()
     }
+
+    @Test
+    fun folder_autopilot_keeps_actions_content_free_and_reversible() {
+        composeRule.onNodeWithTag("autopilot-button").performClick()
+        composeRule.onNodeWithTag("autopilot-screen").assertIsDisplayed()
+
+        composeRule.onNodeWithTag("autopilot-pause-button").performClick()
+        composeRule.onNodeWithTag("autopilot-assignment-state").assertIsDisplayed()
+
+        composeRule.onNodeWithTag("autopilot-approve-button").performClick()
+        composeRule.onNodeWithTag("autopilot-approval-state").assertIsDisplayed()
+
+        composeRule.onNodeWithTag("autopilot-undo-button").performClick()
+        composeRule.onNodeWithTag("autopilot-undo-state").assertIsDisplayed()
+    }
 }

apps/android/app/src/main/java/com/databreeze/android/MainActivity.kt

@@ -16,8 +16,10 @@ import androidx.compose.material3.TopAppBar
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.testTag
 import androidx.compose.ui.res.stringResource
@@ -30,11 +32,24 @@ import com.databreeze.android.storage.InMemoryLocalStore
 import com.databreeze.android.storage.LocalStorePort
 import com.databreeze.android.storage.SyncQueueEntity
 import com.databreeze.android.sync.SyncScheduler
+import com.databreeze.android.folderautopilot.FolderAutopilotApprovalDecision
+import com.databreeze.android.folderautopilot.FolderAutopilotAssignmentState
+import com.databreeze.android.folderautopilot.FolderAutopilotAssignmentSummary
+import com.databreeze.android.folderautopilot.FolderAutopilotExceptionSummary
+import com.databreeze.android.folderautopilot.FolderAutopilotMobileState
+import com.databreeze.android.folderautopilot.FolderAutopilotOfflineActionQueue
+import com.databreeze.android.folderautopilot.FolderAutopilotOutcome
+import com.databreeze.android.folderautopilot.FolderAutopilotOutcomeSummary
+import com.databreeze.android.folderautopilot.FolderAutopilotApprovalSummary
+import com.databreeze.android.folderautopilot.FolderAutopilotUndoState
+import com.databreeze.android.folderautopilot.FolderAutopilotWatcherState
+import com.databreeze.android.folderautopilot.FolderAutopilotScreen
 import kotlinx.coroutines.launch
 
 private object AppRoutes {
     const val HOME = "home"
     const val CAPTURE = "capture"
+    const val AUTOPILOT = "autopilot"
 }
 
 private val localScope = AccountWorkspaceScope("local-account", "local-workspace")
@@ -63,6 +78,11 @@ fun DataBreezeApp(
     syncScheduler: SyncScheduler? = null,
 ) {
     val navController = rememberNavController()
+    var autopilotState by remember { mutableStateOf(sampleFolderAutopilotState()) }
+    val autopilotActions = remember(localStore, scope, syncScheduler) {
+        FolderAutopilotOfflineActionQueue(localStore, scope, syncScheduler)
+    }
+    val autopilotActionScope = rememberCoroutineScope()
     DataBreezeTheme {
         Scaffold(
             topBar = { TopAppBar(title = { Text(stringResource(R.string.app_name)) }) },
@@ -73,7 +93,10 @@ fun DataBreezeApp(
                 modifier = Modifier.padding(padding),
             ) {
                 composable(AppRoutes.HOME) {
-                    HomeScreen(onCapture = { navController.navigate(AppRoutes.CAPTURE) })
+                    HomeScreen(
+                        onCapture = { navController.navigate(AppRoutes.CAPTURE) },
+                        onAutopilot = { navController.navigate(AppRoutes.AUTOPILOT) },
+                    )
                 }
                 composable(AppRoutes.CAPTURE) {
                     CaptureScreen(
@@ -83,13 +106,66 @@ fun DataBreezeApp(
                         onBack = { navController.popBackStack() },
                     )
                 }
+                composable(AppRoutes.AUTOPILOT) {
+                    FolderAutopilotScreen(
+                        state = autopilotState,
+                        onPause = {
+                            autopilotActionScope.launch {
+                                val current = autopilotState
+                                autopilotActions.enqueuePause(current.assignment)
+                                autopilotState = current.pauseAssignment()
+                            }
+                        },
+                        onApprove = {
+                            autopilotActionScope.launch {
+                                val current = autopilotState
+                                val nowEpochMs = System.currentTimeMillis()
+                                autopilotActions.enqueueApproval(
+                                    current.approval,
+                                    FolderAutopilotApprovalDecision.APPROVED,
+                                    current.approval.planHash,
+                                    nowEpochMs,
+                                )
+                                autopilotState = current.decideApproval(
+                                    FolderAutopilotApprovalDecision.APPROVED,
+                                    current.approval.planHash,
+                                    nowEpochMs,
+                                )
+                            }
+                        },
+                        onReject = {
+                            autopilotActionScope.launch {
+                                val current = autopilotState
+                                val nowEpochMs = System.currentTimeMillis()
+                                autopilotActions.enqueueApproval(
+                                    current.approval,
+                                    FolderAutopilotApprovalDecision.REJECTED,
+                                    current.approval.planHash,
+                                    nowEpochMs,
+                                )
+                                autopilotState = current.decideApproval(
+                                    FolderAutopilotApprovalDecision.REJECTED,
+                                    current.approval.planHash,
+                                    nowEpochMs,
+                                )
+                            }
+                        },
+                        onUndo = {
+                            autopilotActionScope.launch {
+                                val current = autopilotState
+                                autopilotActions.enqueueUndo(current.recentOutcome)
+                                autopilotState = current.requestUndo()
+                            }
+                        },
+                    )
+                }
             }
         }
     }
 }
 
 @Composable
-private fun HomeScreen(onCapture: () -> Unit) {
+private fun HomeScreen(onCapture: () -> Unit, onAutopilot: () -> Unit) {
     Column(
         modifier = Modifier
             .fillMaxSize()
@@ -102,9 +178,44 @@ private fun HomeScreen(onCapture: () -> Unit) {
         Button(onClick = onCapture, modifier = Modifier.testTag("capture-button")) {
             Text(stringResource(R.string.capture_action))
         }
+        Button(onClick = onAutopilot, modifier = Modifier.testTag("autopilot-button")) {
+            Text(stringResource(R.string.autopilot_title))
+        }
     }
 }
 
+private fun sampleFolderAutopilotState() = FolderAutopilotMobileState(
+    assignment = FolderAutopilotAssignmentSummary(
+        assignmentId = "assignment-1",
+        displayName = "Invoice intake",
+        state = FolderAutopilotAssignmentState.ACTIVE,
+        revision = 3,
+        watcherState = FolderAutopilotWatcherState.HEALTHY,
+    ),
+    approval = FolderAutopilotApprovalSummary(
+        approvalId = "approval-1",
+        previewId = "preview-1",
+        planHash = "a".repeat(64),
+        affectedCount = 2,
+        blockedCount = 1,
+        decision = FolderAutopilotApprovalDecision.PENDING,
+        expiresAt = "2026-08-05T00:00:00Z",
+    ),
+    recentOutcome = FolderAutopilotOutcomeSummary(
+        executionId = "execution-1",
+        outcome = FolderAutopilotOutcome.UNDO_AVAILABLE,
+        affectedCount = 2,
+        undoState = FolderAutopilotUndoState.AVAILABLE,
+    ),
+    exceptions = listOf(
+        FolderAutopilotExceptionSummary(
+            exceptionId = "exception-1",
+            severity = "WARNING",
+            reasonCode = "DESTINATION_COLLISION",
+        ),
+    ),
+)
+
 @Composable
 private fun CaptureScreen(
     localStore: LocalStorePort,

apps/android/app/src/main/java/com/databreeze/android/folderautopilot/FolderAutopilotModels.kt

@@ -0,0 +1,158 @@
+package com.databreeze.android.folderautopilot
+
+import java.time.Instant
+
+private val OPAQUE_IDENTIFIER = Regex("^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+private val SAFE_TEXT = Regex("^[^\\u0000-\\u001f\\u007f]{1,128}$")
+private val PLAN_HASH = Regex("^[0-9a-f]{64}$")
+private val REASON_CODE = Regex("^[A-Z][A-Z0-9_.-]{1,63}$")
+
+enum class FolderAutopilotAssignmentState { ACTIVE, PAUSED, RETIRED, INVALID }
+
+enum class FolderAutopilotWatcherState { HEALTHY, PAUSED, OVERFLOWED, OFFLINE }
+
+enum class FolderAutopilotApprovalDecision { PENDING, APPROVED, REJECTED, EXPIRED }
+
+enum class FolderAutopilotOutcome {
+    QUEUED,
+    WAITING_FOR_APPROVAL,
+    RUNNING,
+    HANDLED,
+    EXCEPTION,
+    UNDO_AVAILABLE,
+    UNDO_EXPIRED,
+}
+
+enum class FolderAutopilotUndoState { AVAILABLE, REQUESTED, COMPLETED, CONFLICT, EXPIRED, NOT_ELIGIBLE }
+
+data class FolderAutopilotAssignmentSummary(
+    val assignmentId: String,
+    val displayName: String,
+    val state: FolderAutopilotAssignmentState,
+    val revision: Long,
+    val watcherState: FolderAutopilotWatcherState,
+) {
+    init {
+        requireOpaqueIdentifier(assignmentId)
+        requireSafeText(displayName)
+        require(revision > 0) { "revision must be positive" }
+    }
+
+    fun pause(): FolderAutopilotAssignmentSummary {
+        check(state == FolderAutopilotAssignmentState.ACTIVE) { "assignment is not active" }
+        return copy(state = FolderAutopilotAssignmentState.PAUSED, revision = revision + 1)
+    }
+}
+
+data class FolderAutopilotApprovalSummary(
+    val approvalId: String,
+    val previewId: String,
+    val planHash: String,
+    val affectedCount: Int,
+    val blockedCount: Int,
+    val decision: FolderAutopilotApprovalDecision,
+    val expiresAt: String,
+) {
+    init {
+        requireOpaqueIdentifier(approvalId)
+        requireOpaqueIdentifier(previewId)
+        requirePlanHash(planHash)
+        require(affectedCount >= 0) { "affectedCount must not be negative" }
+        require(blockedCount >= 0) { "blockedCount must not be negative" }
+        require(expiresAt.isNotBlank()) { "expiresAt must be present" }
+        requireNotNull(parseExpiryEpochMs(expiresAt)) { "expiresAt must be an ISO-8601 timestamp" }
+    }
+
+    fun isExpired(nowEpochMs: Long = System.currentTimeMillis()): Boolean =
+        nowEpochMs >= requireNotNull(parseExpiryEpochMs(expiresAt))
+
+    fun decide(
+        next: FolderAutopilotApprovalDecision,
+        expectedPlanHash: String,
+        nowEpochMs: Long = System.currentTimeMillis(),
+    ): FolderAutopilotApprovalSummary {
+        require(next == FolderAutopilotApprovalDecision.APPROVED || next == FolderAutopilotApprovalDecision.REJECTED) {
+            "only an approval or rejection can be submitted"
+        }
+        requirePlanHash(expectedPlanHash)
+        check(decision == FolderAutopilotApprovalDecision.PENDING) { "approval is no longer pending" }
+        check(!isExpired(nowEpochMs)) { "approval has expired" }
+        require(planHash == expectedPlanHash) { "approval plan hash changed" }
+        return copy(decision = next)
+    }
+}
+
+data class FolderAutopilotOutcomeSummary(
+    val executionId: String,
+    val outcome: FolderAutopilotOutcome,
+    val affectedCount: Int,
+    val undoState: FolderAutopilotUndoState,
+) {
+    init {
+        requireOpaqueIdentifier(executionId)
+        require(affectedCount >= 0) { "affectedCount must not be negative" }
+    }
+
+    fun requestUndo(): FolderAutopilotOutcomeSummary {
+        check(undoState == FolderAutopilotUndoState.AVAILABLE) { "undo is not available" }
+        return copy(undoState = FolderAutopilotUndoState.REQUESTED)
+    }
+}
+
+data class FolderAutopilotExceptionSummary(
+    val exceptionId: String,
+    val severity: String,
+    val reasonCode: String,
+) {
+    init {
+        requireOpaqueIdentifier(exceptionId)
+        require(severity in setOf("INFO", "WARNING", "ERROR")) { "unsupported severity" }
+        requireReasonCode(reasonCode)
+    }
+}
+
+data class FolderAutopilotMobileState(
+    val assignment: FolderAutopilotAssignmentSummary,
+    val approval: FolderAutopilotApprovalSummary,
+    val recentOutcome: FolderAutopilotOutcomeSummary,
+    val exceptions: List<FolderAutopilotExceptionSummary>,
+) {
+    init {
+        require(exceptions.size <= 50) { "too many exception summaries" }
+        require(exceptions.none { it.reasonCode.contains("PATH", ignoreCase = true) }) {
+            "path-bearing exception details are not allowed"
+        }
+    }
+
+    fun pauseAssignment(): FolderAutopilotMobileState = copy(assignment = assignment.pause())
+
+    fun decideApproval(
+        decision: FolderAutopilotApprovalDecision,
+        expectedPlanHash: String,
+        nowEpochMs: Long = System.currentTimeMillis(),
+    ): FolderAutopilotMobileState = copy(
+        approval = approval.decide(decision, expectedPlanHash, nowEpochMs),
+    )
+
+    fun requestUndo(): FolderAutopilotMobileState = copy(recentOutcome = recentOutcome.requestUndo())
+}
+
+private fun requireOpaqueIdentifier(value: String) {
+    require(OPAQUE_IDENTIFIER.matches(value)) { "identifier must be opaque and path-free" }
+}
+
+private fun requireSafeText(value: String) {
+    require(SAFE_TEXT.matches(value) && value.trim() == value) { "text is not safe" }
+}
+
+private fun requirePlanHash(value: String) {
+    require(PLAN_HASH.matches(value)) { "plan hash must be a lowercase SHA-256 value" }
+}
+
+private fun requireReasonCode(value: String) {
+    require(REASON_CODE.matches(value)) { "reason code is not safe" }
+}
+
+private fun parseExpiryEpochMs(value: String): Long? = runCatching {
+    Instant.parse(value).toEpochMilli()
+}.getOrNull()