feat: implement file provider stability loop

.github/workflows/xcode-build.yml

@@ -26,15 +26,36 @@ jobs:
             -destination 'platform=macOS' \
             CODE_SIGNING_ALLOWED=NO
 
-      - name: Run unit tests on macOS
+      - name: Run unit and UI tests on macOS
         run: |
           xcodebuild test \
             -project potassiumProvider.xcodeproj \
             -scheme potassiumProvider \
             -destination 'platform=macOS' \
+            -resultBundlePath "$RUNNER_TEMP/macos-tests.xcresult" \
             MACOSX_DEPLOYMENT_TARGET=26.4 \
             CODE_SIGNING_ALLOWED=NO
 
+      - name: Run Stability profile unit tests on macOS
+        if: ${{ !cancelled() }}
+        run: |
+          xcodebuild test \
+            -project potassiumProvider.xcodeproj \
+            -scheme potassiumProvider-Stability \
+            -destination 'platform=macOS' \
+            -resultBundlePath "$RUNNER_TEMP/macos-stability-tests.xcresult" \
+            MACOSX_DEPLOYMENT_TARGET=26.4 \
+            CODE_SIGNING_ALLOWED=NO
+
+      - name: Retain Mac test result bundles
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: macos-test-results
+          path: ${{ runner.temp }}/macos*-tests.xcresult
+          retention-days: 14
+          if-no-files-found: warn
+
   ios:
     name: iOS Simulator
     runs-on: macos-26
@@ -58,8 +79,18 @@ jobs:
             -scheme potassiumProvider \
             -destination 'platform=iOS Simulator,OS=26.5,name=iPhone 17' \
             -only-testing:potassiumProviderTests \
+            -resultBundlePath "$RUNNER_TEMP/ios-tests.xcresult" \
             CODE_SIGNING_ALLOWED=NO
 
+      - name: Retain iOS test result bundle
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: ios-test-results
+          path: ${{ runner.temp }}/ios-tests.xcresult
+          retention-days: 14
+          if-no-files-found: warn
+
   visionos:
     name: visionOS
     runs-on: macos-26
@@ -83,4 +114,14 @@ jobs:
             -scheme potassiumProvider \
             -destination 'platform=visionOS Simulator,OS=26.5,name=Apple Vision Pro' \
             -only-testing:potassiumProviderTests \
+            -resultBundlePath "$RUNNER_TEMP/visionos-tests.xcresult" \
             CODE_SIGNING_ALLOWED=NO
+
+      - name: Retain visionOS test result bundle
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: visionos-test-results
+          path: ${{ runner.temp }}/visionos-tests.xcresult
+          retention-days: 14
+          if-no-files-found: warn

AGENTS.md

@@ -13,7 +13,7 @@ File Provider experience.
   `potassiumProviderFileProvider`, `potassiumProviderActions`,
   `potassiumProviderTests`, and `potassiumProviderUITests`
 - Supported validation platforms: iOS Simulator, macOS, and visionOS
-- Dependencies: `SQLite.swift` and `potassiumChannel` package products
+- Dependencies: `InfomaniakConcurrency`, `SQLite.swift`, and `potassiumChannel` package products
   `PotassiumChannelCore`, `PotassiumKDrive`, and `PotassiumOAuth`
 - Tests: Swift Testing for unit tests, XCTest for UI tests
 
@@ -152,6 +152,15 @@ app.
 - Keep networking behavior testable with mocks, fixtures, or injectable
   clients. Live checks must be explicit, locally guarded, and kept out of the
   default test path.
+- Provision new Stability Lab roots below the server-created `Private` folder,
+  verifying its stable identity and drive-root parent; do not assume the drive
+  root accepts creates. Never use the `Private` folder itself as a disposable root.
+- The current account is an operator-authorized lab account. Stability may reuse
+  its existing OAuth Keychain login as well as manually entered tokens; never
+  extract a credential into a command, fixture, environment variable, or log.
+- Live Finder runs defer permanent deletion by default and continue later scenarios.
+  Use `--include-permanent-deletion` only when requested; retain exact-item
+  confirmation and never count deferred deletion as full-suite acceptance.
 - Prefer typed request/response flows from Potassium products over app-local
   ad hoc HTTP construction.
 
@@ -207,6 +216,9 @@ app.
 - Use Swift Testing (`import Testing`) for new unit tests unless the work is in
   existing XCTest UI test targets.
 - Use XCTest only for UI automation or when extending existing XCTest files.
+- Record the actual OS version/build and Xcode version with integration-test
+  evidence. Rerun native Finder integration after macOS upgrades before claiming
+  compatibility; an SDK or deployment target is not a tested runtime version.
 - Run the relevant `xcodebuild build` or `xcodebuild test` command before
   describing implementation work as complete, including Mac and visionOS
   destinations when changes affect runtime behavior. If validation cannot be

Config/potassiumProviderInfo.plist

@@ -20,6 +20,8 @@
 	<true/>
 	<key>LSApplicationCategoryType</key>
 	<string>public.app-category.productivity</string>
+	<key>NSAppleEventsUsageDescription</key>
+	<string>The opt-in Stability Lab uses Finder Automation only to exercise its verified disposable File Provider root.</string>
 	<key>CFBundleShortVersionString</key>
 	<string>$(MARKETING_VERSION)</string>
 	<key>CFBundleURLTypes</key>

Config/potassiumProviderStability.entitlements

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.net.weavee.potassiumProvider</string>
+	</array>
+	<key>com.apple.security.automation.apple-events</key>
+	<true/>
+	<key>com.apple.security.network.client</key>
+	<true/>
+	<key>keychain-access-groups</key>
+	<array>
+		<string>$(AppIdentifierPrefix)net.weavee.potassiumProvider</string>
+	</array>
+</dict>
+</plist>

PotassiumProviderCore/FileProviderBackgroundWork.swift

@@ -0,0 +1,56 @@
+import Foundation
+import Synchronization
+
+/// Owns work launched after a File Provider callback has been acknowledged.
+/// `invalidate()` is synchronous because the system's instance invalidation
+/// callback must cancel outstanding work before it returns. The mutex protects
+/// task registration only; operations and cancellation handlers run outside it.
+public final class FileProviderBackgroundWork: Sendable {
+    private struct State {
+        var invalidated = false
+        var tasks: [UUID: Task<Void, Never>] = [:]
+    }
+    private let state = Mutex(State())
+
+    public init() {}
+
+    /// Returns false once this instance has been invalidated. A new provider
+    /// instance must own a new scope even when it shares the same process.
+    @discardableResult
+    public func start(_ operation: @escaping @Sendable () async -> Void) -> Bool {
+        state.withLock { state in
+            guard !state.invalidated else { return false }
+            let identifier = UUID()
+            state.tasks[identifier] = Task {
+                // Registration holds the same mutex, so an immediately
+                // finishing task cannot remove itself before insertion.
+                guard self.canBegin(identifier) else { return }
+                defer { self.finished(identifier) }
+                await operation()
+            }
+            return true
+        }
+    }
+
+    public func invalidate() {
+        let tasks = state.withLock { state in
+            state.invalidated = true
+            let tasks = Array(state.tasks.values)
+            state.tasks.removeAll()
+            return tasks
+        }
+        // Task cancellation can synchronously invoke a handler. Never call
+        // it while holding the registration mutex.
+        for task in tasks { task.cancel() }
+    }
+
+    var registeredTaskCount: Int { state.withLock { $0.tasks.count } }
+
+    private func canBegin(_ identifier: UUID) -> Bool {
+        state.withLock { !$0.invalidated && $0.tasks[identifier] != nil && !Task.isCancelled }
+    }
+
+    private func finished(_ identifier: UUID) {
+        state.withLock { $0.tasks[identifier] = nil }
+    }
+}

PotassiumProviderCore/FileProviderOperationLifecycle.swift

@@ -6,15 +6,34 @@ public actor FileProviderOperationLifecycle {
     public nonisolated let progress: Progress
 
     private let cancellationCompletion: @Sendable () -> Void
+    private let diagnosticSpanTask: Task<ProviderDiagnosticSpan, Never>?
     private var task: Task<Void, Never>?
     private var isFinished = false
 
     public init(
         progress: Progress,
+        diagnosticSource: ProviderDiagnosticSource = .fileProviderExtension,
+        diagnosticOperation: ProviderDiagnosticOperation? = nil,
+        diagnosticFieldShape: [ProviderDiagnosticField] = [],
+        diagnosticItemIdentifier: String? = nil,
+        diagnosticRecorder: (any ProviderDiagnosticRecording)? = nil,
         cancellationCompletion: @escaping @Sendable () -> Void
     ) {
         self.progress = progress
         self.cancellationCompletion = cancellationCompletion
+        if let diagnosticOperation {
+            self.diagnosticSpanTask = Task {
+                await ProviderDiagnosticSpan.start(
+                    itemIdentifier: diagnosticItemIdentifier,
+                    source: diagnosticSource,
+                    operation: diagnosticOperation,
+                    fieldShape: diagnosticFieldShape,
+                    recorder: diagnosticRecorder
+                )
+            }
+        } else {
+            self.diagnosticSpanTask = nil
+        }
         progress.isCancellable = true
         progress.isPausable = false
         progress.cancellationHandler = { [weak self] in
@@ -34,24 +53,38 @@ public actor FileProviderOperationLifecycle {
 
     private func begin(
         _ operation: @escaping @Sendable (FileProviderOperationLifecycle) async -> Void
-    ) {
+    ) async {
         guard isFinished == false else { return }
         guard progress.isCancelled == false else {
-            cancel()
+            await cancel()
+            return
+        }
+        let diagnosticSpan = await diagnosticSpanTask?.value
+        guard isFinished == false else { return }
+        guard progress.isCancelled == false else {
+            await cancel()
             return
         }
         task = Task {
-            await operation(self)
+            if let diagnosticSpan {
+                await diagnosticSpan.withCorrelation {
+                    await operation(self)
+                }
+            } else {
+                await operation(self)
+            }
         }
     }
 
     @discardableResult
     public func finish(
         markProgressComplete: Bool,
+        diagnosticError: (any Error)? = nil,
+        diagnosticItemMetadataAlias: UUID? = nil,
         _ completion: @escaping @Sendable () -> Void
-    ) -> Bool {
+    ) async -> Bool {
         if progress.isCancelled {
-            cancel()
+            await cancel()
             return false
         }
 
@@ -62,11 +95,19 @@ public actor FileProviderOperationLifecycle {
         if markProgressComplete, progress.totalUnitCount > 0 {
             progress.completedUnitCount = progress.totalUnitCount
         }
+        if let diagnosticSpanTask {
+            let diagnosticSpan = await diagnosticSpanTask.value
+            if let diagnosticError {
+                await diagnosticSpan.fail(error: diagnosticError)
+            } else {
+                await diagnosticSpan.complete(statusClass: .success, itemMetadataAlias: diagnosticItemMetadataAlias)
+            }
+        }
         completion()
         return true
     }
 
-    public func cancel() {
+    public func cancel() async {
         guard isFinished == false else { return }
         isFinished = true
         let task = task
@@ -76,6 +117,10 @@ public actor FileProviderOperationLifecycle {
             progress.cancel()
         }
         task?.cancel()
+        if let diagnosticSpanTask {
+            let diagnosticSpan = await diagnosticSpanTask.value
+            await diagnosticSpan.cancel()
+        }
         cancellationCompletion()
     }
 }

PotassiumProviderCore/KDriveContextActions.swift

@@ -3,6 +3,7 @@ import Foundation
 public struct KDriveShareLinkConfiguration: Equatable, Sendable {
     public enum Access: String, CaseIterable, Equatable, Sendable {
         case `public`
+        case inherit
         case password
     }
 
@@ -45,6 +46,18 @@ public struct KDriveShareLinkConfiguration: Equatable, Sendable {
     public func isValid(preservingPasswordFor existingAccess: Access?) -> Bool {
         isValid || (access == .password && existingAccess == .password)
     }
+
+    /// Compare the settings kDrive reports after a write. Passwords are not
+    /// returned by the service, and expiration is transported in whole seconds.
+    /// A successful HTTP response alone does not prove that these values stuck.
+    public func hasSameReportedSettings(as other: Self) -> Bool {
+        access == other.access &&
+            validUntil.map { $0.timeIntervalSince1970.rounded(.towardZero) } ==
+                other.validUntil.map { $0.timeIntervalSince1970.rounded(.towardZero) } &&
+            allowsDownload == other.allowsDownload && allowsComments == other.allowsComments &&
+            allowsEditing == other.allowsEditing && allowsAccessRequests == other.allowsAccessRequests &&
+            showsFileInformation == other.showsFileInformation && showsStatistics == other.showsStatistics
+    }
 }
 
 public struct KDriveShareLinkSummary: Equatable, Sendable {
@@ -101,7 +114,7 @@ public struct KDriveFileVersionPage: Equatable, Sendable {
 
 public protocol KDriveContextActionProviding: Sendable {
     func setFavorite(driveID: Int, fileID: Int, isFavorite: Bool) async throws
-    func duplicateItem(driveID: Int, fileID: Int) async throws -> KDriveRemoteItem
+    func duplicateItem(driveID: Int, fileID: Int, name: String) async throws -> KDriveRemoteItem
     func trashedItem(driveID: Int, fileID: Int) async throws -> KDriveRemoteItem
     func existingFileIDs(driveID: Int, fileIDs: [Int]) async throws -> Set<Int>
     func restoreTrashedItem(driveID: Int, fileID: Int, destinationParentID: Int) async throws
@@ -131,6 +144,8 @@ public enum KDriveContextActionError: Error, Equatable, LocalizedError, Sendable
     case invalidShareLinkURL
     case passwordRequired
     case restoredItemUnavailable
+    case unsupportedShareLinkAccess
+    case shareLinkSettingsNotApplied
 
     public var errorDescription: String? {
         switch self {
@@ -140,6 +155,10 @@ public enum KDriveContextActionError: Error, Equatable, LocalizedError, Sendable
             return "Enter a password for the protected share link."
         case .restoredItemUnavailable:
             return "kDrive restored the version, but its metadata is not available yet."
+        case .unsupportedShareLinkAccess:
+            return "kDrive returned an unsupported share-link access policy."
+        case .shareLinkSettingsNotApplied:
+            return "kDrive did not apply all requested sharing settings. The current server settings are shown; review them before sharing the link."
         }
     }
 }
@@ -215,6 +234,21 @@ public struct KDriveContextActionExecution: Equatable, Sendable {
     }
 }
 
+public enum KDriveDuplicateNamePolicy {
+    /// Produces an explicit, human-readable destination name. The duplicate
+    /// endpoint's empty-body/server-selected naming behavior is not part of the
+    /// pinned public contract, so callers never rely on it.
+    public static func duplicateName(for sourceName: String) -> String {
+        let path = sourceName as NSString
+        let pathExtension = path.pathExtension
+        let baseName = path.deletingPathExtension
+        guard pathExtension.isEmpty == false, baseName.isEmpty == false else {
+            return "\(sourceName) copy"
+        }
+        return "\(baseName) copy.\(pathExtension)"
+    }
+}
+
 /// Coordinates action-specific remote calls and returns the exact provider
 /// containers that must be invalidated after the server mutation succeeds.
 public struct KDriveContextActionCoordinator: Sendable {
@@ -246,7 +280,13 @@ public struct KDriveContextActionCoordinator: Sendable {
             return try await setFavorite(false, fileID: fileID, action: action)
         case .duplicate:
             try Task.checkCancellation()
-            let duplicate = try await actions.duplicateItem(driveID: driveID, fileID: fileID)
+            let source = try await remote.item(driveID: driveID, fileID: fileID)
+            try Task.checkCancellation()
+            let duplicate = try await actions.duplicateItem(
+                driveID: driveID,
+                fileID: fileID,
+                name: KDriveDuplicateNamePolicy.duplicateName(for: source.name)
+            )
             let authoritativeDuplicate = try await remote.item(driveID: driveID, fileID: duplicate.id)
             return KDriveContextActionExecution(
                 action: action,