Pre-push review: cloudkit-mirroring

diff --git a/Asterism/Asterism.xcodeproj/project.pbxproj b/Asterism/Asterism.xcodeproj/project.pbxprojindex 6da4a77..b9472ec 100644--- a/Asterism/Asterism.xcodeproj/project.pbxproj+++ b/Asterism/Asterism.xcodeproj/project.pbxproj@@ -595,6 +595,7 @@ 				ASTERISM_APP_GROUP_IDENTIFIER = "group.$(ASTERISM_IDENTITY)"; 				ASTERISM_ICLOUD_CONTAINER_IDENTIFIER = "iCloud.$(ASTERISM_IDENTITY)"; 				ASTERISM_IDENTITY = me.nore.ig.Asterism.dev;+				ASTERISM_MIRRORING_ENABLED = YES; 				ASTERISM_XCENT_SUFFIX = ""; 				"ASTERISM_XCENT_SUFFIX[sdk=*simulator*]" = "-Simulated"; 				CLANG_ANALYZER_NONNULL = YES;@@ -662,6 +663,7 @@ 				ASTERISM_APP_GROUP_IDENTIFIER = "group.$(ASTERISM_IDENTITY)"; 				ASTERISM_ICLOUD_CONTAINER_IDENTIFIER = "iCloud.$(ASTERISM_IDENTITY)"; 				ASTERISM_IDENTITY = me.nore.ig.Asterism;+				ASTERISM_MIRRORING_ENABLED = YES; 				ASTERISM_XCENT_SUFFIX = ""; 				"ASTERISM_XCENT_SUFFIX[sdk=*simulator*]" = "-Simulated"; 				CLANG_ANALYZER_NONNULL = YES;

diff --git a/Asterism/Asterism/ContentView.swift b/Asterism/Asterism/ContentView.swiftindex fa2bf00..cd9a068 100644--- a/Asterism/Asterism/ContentView.swift+++ b/Asterism/Asterism/ContentView.swift@@ -1,4 +1,5 @@ import AsterismCore+import OSLog import SwiftUI  /// Two-tab root view driven by AppLibraryModel state.@@ -32,7 +33,7 @@ struct ContentView: View {         #if DEBUG || ASTERISM_PERFORMANCE_TESTING         switch UITestLaunchSupport.request() {         case .disabled:-            _model = State(initialValue: AppLibraryModel(appGroupIdentifier: Self.declaredAppGroupIdentifier()))+            _model = State(initialValue: Self.productionModel())         case .seeded(let configuration, let fixture):             _model = State(                 initialValue: AppLibraryModel(@@ -44,10 +45,20 @@ struct ContentView: View {             _model = State(initialValue: AppLibraryModel(startupFailureMessage: message))         }         #else-        _model = State(initialValue: AppLibraryModel(appGroupIdentifier: Self.declaredAppGroupIdentifier()))+        _model = State(initialValue: Self.productionModel())         #endif     } +    /// The model the app runs on, built from what this build's bundle declares.+    private static func productionModel() -> AppLibraryModel {+        let mirroring = declaredMirroring()+        return AppLibraryModel(+            appGroupIdentifier: declaredAppGroupIdentifier(),+            cloudKitContainerID: mirroring.containerID,+            mirroringDeclarationFailure: mirroring.failure+        )+    }+     /// The App Group this build was signed for, read from its own bundle.     ///     /// Traps rather than falling back (Req 2.3, Q2). The key is derived at build@@ -71,6 +82,39 @@ struct ContentView: View {         }     } +    /// What this build's bundle says about mirroring: the container to mirror+    /// into, or why it could not be resolved (Q51).+    ///+    /// Unlike the App Group, this does *not* trap. A container the app cannot+    /// resolve costs sync and nothing else, and Q44 puts every mirroring+    /// misconfiguration on that side of the line: degrade sync, never the+    /// library.+    ///+    /// **The failure travels separately from the nil.** Returning only nil made+    /// "this configuration has mirroring off" and "this configuration asked to+    /// mirror and the container id would not resolve" the same value, so+    /// Settings told the reader "iCloud sync is off in this build" about a build+    /// whose sync was broken — the one outcome Req 8.4 forbids, reporting a+    /// misconfiguration as anything other than a misconfiguration. The reason is+    /// carried through so the open can record the `.failed` attachment, which is+    /// the same path a `.private` construction failure takes (Q44).+    private static func declaredMirroring() -> (containerID: String?, failure: String?) {+        do {+            return (try LibraryConfiguration.declaredMirroringContainerIdentifier(in: .main), nil)+        } catch {+            let reason = String(describing: error)+            Logger(subsystem: "me.nore.ig.Asterism", category: "ContentView").error(+                """+                Mirroring is enabled for this configuration but \+                \(LibraryConfiguration.cloudKitContainerInfoPlistKey, privacy: .public) \+                could not be resolved, so the library runs local-only: \+                \(reason, privacy: .public)+                """+            )+            return (nil, reason)+        }+    }+     /// Test/Preview initializer — injects an explicit configuration.     init(configuration: LibraryConfiguration) {         _model = State(initialValue: AppLibraryModel(configuration: configuration))@@ -117,6 +161,7 @@ struct ContentView: View {                         presentation: model.recentPresentation,                         capabilities: model.capabilities,                         diagnosisRefreshFailed: model.diagnosisRefreshFailed,+                        sync: model.recentSyncPresentation,                         onSelect: { entryID in                             selectedRecentEntryID = entryID                         },@@ -124,7 +169,11 @@ struct ContentView: View {                             // Direct teaching sheet from inline action (Audit §6)                             showingTeachingForEntryID = entryID                         },-                        onShowDiagnostics: { showingDiagnostics = true }+                        onShowDiagnostics: { showingDiagnostics = true },+                        // Req 8.2's route out of the banner: the same Settings+                        // sheet the toolbar opens, where the condition and its+                        // remedy are spelled out.+                        onShowSyncSettings: { showingSettings = true }                     )                     .navigationTitle("Recent")                     .toolbar {@@ -207,7 +256,9 @@ struct ContentView: View {                                 pendingReteachHostname = hostname                                 showingSettings = false                             }-                        )+                        ),+                        syncModel: model.settingsSyncModel(),+                        interruptedImportNotice: model.interruptedImportNotice                     )                     .toolbar {                         ToolbarItem(placement: .confirmationAction) {

diff --git a/Asterism/Asterism/Info.plist b/Asterism/Asterism/Info.plistindex f4cc53c..ee11e4d 100644--- a/Asterism/Asterism/Info.plist+++ b/Asterism/Asterism/Info.plist@@ -6,6 +6,8 @@ 	<string>$(ASTERISM_APP_GROUP_IDENTIFIER)</string> 	<key>AsterismCloudKitContainerIdentifier</key> 	<string>$(ASTERISM_ICLOUD_CONTAINER_IDENTIFIER)</string>+	<key>AsterismCloudKitMirroringEnabled</key>+	<string>$(ASTERISM_MIRRORING_ENABLED)</string> 	<key>UIBackgroundModes</key> 	<array> 		<string>remote-notification</string>

diff --git a/Asterism/Asterism/ViewModels/AppLibraryModel.swift b/Asterism/Asterism/ViewModels/AppLibraryModel.swiftindex 353cac9..7cab16c 100644--- a/Asterism/Asterism/ViewModels/AppLibraryModel.swift+++ b/Asterism/Asterism/ViewModels/AppLibraryModel.swift@@ -31,11 +31,39 @@ public final class AppLibraryModel {     /// it beside the count it undermines.     public private(set) var diagnosisRefreshFailed = false +    /// What an interrupted import left behind, read once at the end of every+    /// bootstrap (Req 4.4).+    ///+    /// The repository writes the sidecar before its first save and removes it+    /// after its last, so its presence at open means an import stopped partway —+    /// a kill, a crash, a device that ran out of power. It is a *report*, not a+    /// resume token: the repair is the reader running the import again, which+    /// upsert makes idempotent (Decision 2), so nothing here tries to continue+    /// anything.+    ///+    /// Cleared when an import completes, because the repository has removed the+    /// file by then and a notice about a finished import is just wrong.+    public private(set) var interruptedImport: InterruptedImportReport?+     /// When an explicit configuration is injected (tests), resolution is skipped.     private let explicitConfiguration: LibraryConfiguration?     /// When bundle-declared resolution is used, this holds the declared App Group     /// identifier the embedding target read from its own bundle (Decision 1).     private let appGroupIdentifier: String?+    /// The CloudKit container this build mirrors into, or nil when its+    /// configuration has mirroring off — the same injection discipline as the+    /// App Group: the app reads its own bundle and hands the value in (Q51).+    private let cloudKitContainerID: String?+    /// Why the container identifier could not be read, when this build asked to+    /// mirror and its bundle would not say where (Q52, Req 8.4).+    ///+    /// Carried separately from `cloudKitContainerID` because a nil identifier+    /// alone cannot distinguish "mirroring is off in this configuration" from+    /// "mirroring is on and the declaration is broken", and the two must not+    /// read the same: the first is by design and the second is a+    /// misconfiguration Req 8.4 says to name. The library opens local-only+    /// either way — a setup mistake degrades sync, never the library (Q44).+    private let mirroringDeclarationFailure: String?     /// The locator used for App Group resolution (injectable for tests).     private let locator: any SharedContainerLocating @@ -55,12 +83,16 @@ public final class AppLibraryModel {     /// Group resolution fails.     public init(         appGroupIdentifier: String,+        cloudKitContainerID: String? = nil,+        mirroringDeclarationFailure: String? = nil,         locator: any SharedContainerLocating = SystemSharedContainerLocator(),         capabilities: AsterismCapabilities = .current     ) {         self.capabilities = capabilities         self.explicitConfiguration = nil         self.appGroupIdentifier = appGroupIdentifier+        self.cloudKitContainerID = cloudKitContainerID+        self.mirroringDeclarationFailure = mirroringDeclarationFailure         self.locator = locator         self.startupFailureMessage = nil         self.uiTestFixture = nil@@ -74,6 +106,8 @@ public final class AppLibraryModel {         self.capabilities = capabilities         self.explicitConfiguration = configuration         self.appGroupIdentifier = nil+        self.cloudKitContainerID = nil+        self.mirroringDeclarationFailure = nil         self.locator = SystemSharedContainerLocator()         self.startupFailureMessage = nil         self.uiTestFixture = nil@@ -88,6 +122,8 @@ public final class AppLibraryModel {         self.capabilities = capabilities         self.explicitConfiguration = configuration         self.appGroupIdentifier = nil+        self.cloudKitContainerID = nil+        self.mirroringDeclarationFailure = nil         self.locator = SystemSharedContainerLocator()         self.startupFailureMessage = nil         self.uiTestFixture = uiTestFixture@@ -104,11 +140,14 @@ public final class AppLibraryModel {     /// failure mode.     init(         readyRepository: any LibraryProviding,+        mirroringDeclarationFailure: String? = nil,         capabilities: AsterismCapabilities = .current     ) {         self.capabilities = capabilities         self.explicitConfiguration = nil         self.appGroupIdentifier = nil+        self.cloudKitContainerID = nil+        self.mirroringDeclarationFailure = mirroringDeclarationFailure         self.locator = SystemSharedContainerLocator()         self.startupFailureMessage = nil         self.uiTestFixture = nil@@ -124,14 +163,23 @@ public final class AppLibraryModel {         self.capabilities = capabilities         self.explicitConfiguration = nil         self.appGroupIdentifier = nil+        self.cloudKitContainerID = nil+        self.mirroringDeclarationFailure = nil         self.locator = SystemSharedContainerLocator()         self.startupFailureMessage = startupFailureMessage         self.uiTestFixture = nil     }      /// Attempts to open the library; transitions to ready or unavailable.+    ///+    /// Any repository this model already holds is shut down first (Q43). A+    /// second `openV4ForApp` while the previous one still retains its container+    /// is two live containers over one store — under mirroring, the in-process+    /// 134422 collision (Q24). `retry()` and the UI-test reseed path are the two+    /// ways here.     public func bootstrap() async {         state = .loading+        await teardownRepository()         if let startupFailureMessage {             state = .unavailable(message: startupFailureMessage)             Self.logger.error("Library bootstrap blocked by invalid launch configuration")@@ -148,7 +196,9 @@ public final class AppLibraryModel {                     return                 }                 configuration = try LibraryConfiguration.production(-                    appGroupIdentifier: appGroupIdentifier, locator: locator+                    appGroupIdentifier: appGroupIdentifier,+                    cloudKitContainerID: cloudKitContainerID,+                    locator: locator                 )             }             resolvedConfiguration = configuration@@ -169,6 +219,10 @@ public final class AppLibraryModel {                 try await seedUITestFixture(uiTestFixture, in: repo)                 self.uiTestFixture = nil                 if uiTestFixture.requiresReopenAfterSeeding {+                    // The reopen below is a second `openV4ForApp` over the same+                    // store, so the first repository lets go of its container+                    // before it runs (Q43).+                    await repo.shutdown()                     // Diagnoses are derived at open, and an incoherent fixture is                     // written *after* this repository opened on an empty store —                     // so its `diagnostics` describe a library that no longer@@ -183,8 +237,17 @@ public final class AppLibraryModel {             }             self.repository = repo             self.backupRepository = repo+            interruptedImport = await repo.interruptedImport()             await refreshAll()             state = .ready+            // Both of these belong *after* the open, and for the same reason:+            // the monitor observes a container that only exists once+            // certification has published the marker (Q35), and the launch+            // reconcile is charged to no budget the open has to meet (Q45,+            // Req 6.4).+            startSyncObservation(+                configuration: configuration, mirroring: await repo.mirroring)+            scheduleLaunchReconcile()             Self.logger.debug("Library bootstrap completed")         } catch {             state = .unavailable(message: String(describing: error))@@ -192,11 +255,30 @@ public final class AppLibraryModel {         }     } -    /// Retries the same bootstrap without changing paths.+    /// Retries the same bootstrap without changing paths. The open repository,+    /// if any, is released first — `bootstrap()` does that for every caller.     public func retry() async {         await bootstrap()     } +    /// Releases the open repository and forgets it, so nothing this model holds+    /// still claims the store when the next open runs (Q43).+    ///+    /// The monitor stops first: it observes notifications for a container that+    /// is about to go away, and its arrival callback reconciles through the+    /// repository this is releasing. The launch pass goes with it for the same+    /// reason — a pass still running against the old repository has nothing to+    /// say about the library the next open publishes.+    private func teardownRepository() async {+        stopSyncObservation()+        launchReconcileTask?.cancel()+        launchReconcileTask = nil+        guard let repository else { return }+        await repository.shutdown()+        self.repository = nil+        self.backupRepository = nil+    }+     /// Called when the app becomes active; re-derives the diagnoses and then     /// refreshes all snapshots (Req 1.5).     public func handleActivation() async {@@ -351,6 +433,174 @@ public final class AppLibraryModel {         return LibraryDiagnosticsModel(library: repo, onReteach: onReteach)     } +    // MARK: - Sync visibility (Req 8)++    /// The live monitor, or nil when this configuration cannot mirror.+    ///+    /// Constructed after `bootstrap()` and stopped in `teardownRepository()`.+    /// A build with no container identifier has nothing to observe: no mirroring+    /// container exists, so no sync event and no remote change can be posted for+    /// it, and a monitor would only register two observers to hear nothing.+    private(set) var syncMonitor: SyncMonitor?++    /// Where the sync surfaces read what the app last observed.+    ///+    /// Nil before the monitor exists and in every configuration that cannot+    /// mirror at all — both surfaces read the never-synced record rather than+    /// special-casing its absence.+    var syncStatusSource: (any SyncStatusReporting)? { syncMonitor }++    /// Q45's once-per-launch pass, scheduled after the open publishes Recent.+    private var launchReconcileTask: Task<Void, Never>?+    private var launchReconcileStarted = false+    /// Whether that pass has run to completion. Read by tests to pin the one+    /// thing its scheduling has to guarantee: the open does not wait for it.+    private(set) var launchReconcileCompleted = false++    /// Starts observing sync for a configuration that mirrors (Req 8.1–8.6).+    ///+    /// The monitor opens no container and holds no context — it reads+    /// notifications and writes its status file — so starting it here cannot+    /// violate the single-mirror rule whatever the open decided. A `.failed`+    /// attachment is recorded before it starts, since a misconfigured build+    /// degrades sync and leaves the library working, and that record is the only+    /// evidence anything is wrong (Req 8.4, Q44).+    func startSyncObservation(+        configuration: LibraryConfiguration,+        mirroring: MirroringAttachment+    ) {+        let attachment = declaredAttachment(configuration: configuration, opened: mirroring)+        guard attachment != .notRequested else { return }+        let monitor = SyncMonitor(+            storeURL: configuration.v4StoreURL,+            statusURL: configuration.syncStatusURL)+        monitor.onArrivals = { [weak self] in await self?.handleSyncArrivals() }+        monitor.record(attachment)+        monitor.start()+        syncMonitor = monitor+    }++    /// What the open did about mirroring, corrected for what it was never given+    /// a chance to try (Req 8.4).+    ///+    /// A build whose bundle declares mirroring on but whose container id would+    /// not resolve hands the open a nil identifier, so the open honestly reports+    /// `.notRequested` — it was not asked for anything. That is right about the+    /// open and wrong about the build, and the difference is the whole of Q52's+    /// residue: nil-because-off and nil-because-broken read identically, so+    /// Settings said "iCloud sync is off in this build" about a build whose sync+    /// was misconfigured. The declaration failure is the evidence the open never+    /// saw, so it is folded in here, onto the same `.failed` path a `.private`+    /// construction failure takes (Q44).+    private func declaredAttachment(+        configuration: LibraryConfiguration,+        opened: MirroringAttachment+    ) -> MirroringAttachment {+        guard configuration.cloudKitContainerID == nil,+              let reason = mirroringDeclarationFailure+        else { return opened }+        return .failed(containerID: "an iCloud container it could not name", reason: reason)+    }++    /// Stops the monitor and forgets it. Idempotent.+    private func stopSyncObservation() {+        syncMonitor?.stop()+        syncMonitor = nil+    }++    /// What one debounced batch of arrivals costs: the Site graph is made+    /// coherent, then everything on screen is re-derived from it (Req 1.7, 2.2,+    /// 8.6).+    ///+    /// Reconciliation runs first because Recent is built from the diagnoses, and+    /// it runs *through* the repository, which owns the mutual exclusion with+    /// import: an arrival mid-import sets the deferred flag and returns, and the+    /// import re-fires it when its flag drops (Q46). Nothing here may add a+    /// second gate.+    func handleSyncArrivals() async {+        guard let repo = repository else { return }+        do {+            _ = try await repo.reconcileAfterSync()+        } catch {+            // Reconciliation has no user-facing errors: a failed pass stopped at+            // a chunk boundary and the next trigger converges it. The refresh+            // below is not optional either way — records did arrive.+            Self.logger.error(+                "Reconciliation after arrivals failed: \(String(describing: error), privacy: .public)")+        }+        await refreshDiagnosesAndSnapshots()+    }++    /// Schedules the once-per-launch reconcile (Q45).+    ///+    /// A task rather than an await: the caller is the tail of `bootstrap()`, and+    /// the open's 2 s budget (Req 9.1) does not pay for merge work whose+    /// worst case is a 5,000-record re-pin. Nothing blocks on it (Req 6.4).+    private func scheduleLaunchReconcile() {+        launchReconcileStarted = false+        launchReconcileCompleted = false+        launchReconcileTask = Task { [weak self] in await self?.runLaunchReconcile() }+    }++    /// The launch pass itself. Runs at most once per open.+    func runLaunchReconcile() async {+        guard !launchReconcileStarted, let repo = repository else { return }+        launchReconcileStarted = true+        do {+            let outcome = try await repo.reconcileAfterSync()+            // An empty pass wrote nothing and the open published Recent moments+            // ago, so re-deriving over it would repeat the open's read for no+            // change. A pass that moved custody or re-pinned records changed+            // what the screen is built from, so it refreshes.+            if !outcome.isEmpty { await refreshDiagnosesAndSnapshots() }+        } catch {+            Self.logger.error(+                "Launch reconciliation failed: \(String(describing: error), privacy: .public)")+            // A failure can still have committed earlier chunks, so what is+            // published may describe a graph that no longer holds.+            await refreshDiagnosesAndSnapshots()+        }+        launchReconcileCompleted = true+    }++    /// Test seam: awaits the scheduled launch pass.+    func waitForLaunchReconcile() async {+        await launchReconcileTask?.value+    }++    /// Whether this build asked to mirror — the *declaration*, not the outcome.+    /// A `.private` construction that then failed records a `misconfigured`+    /// status, and the surfaces read that rather than second-guessing this flag+    /// (Q44).+    ///+    /// A build whose container id would not resolve counts as asking: it+    /// declared `ASTERISM_MIRRORING_ENABLED = YES` and got as far as its own+    /// Info.plist. Reading it as "not requested" is what let Settings report a+    /// misconfiguration as sync being off by design (Req 8.4).+    public var mirroringRequested: Bool {+        resolvedConfiguration?.cloudKitContainerID != nil || mirroringDeclarationFailure != nil+    }++    /// What Recent renders about sync: the banner (actionable only) and the+    /// first-sync empty state (Req 6.5, 8.2, 8.3).+    ///+    /// Computed rather than stored so a view reading it during `body` observes+    /// the monitor's own `status` and re-renders without a relaunch (Req 8.6).+    public var recentSyncPresentation: RecentSyncPresentation {+        RecentSyncPresentation(+            status: syncStatusSource?.status ?? .neverSynced,+            mirroringRequested: mirroringRequested)+    }++    /// Provides the Settings iCloud section's model (Req 8.1–8.5).+    public func settingsSyncModel() -> SettingsSyncModel? {+        guard let repo = repository else { return nil }+        return SettingsSyncModel(+            source: syncStatusSource,+            library: repo,+            mirroringRequested: mirroringRequested)+    }+     /// Provides a settings backup model backed by the current repository.     public func settingsBackupModel() -> SettingsBackupModel? {         guard let repo = backupRepository, let config = resolvedConfiguration else { return nil }@@ -363,20 +613,49 @@ public final class AppLibraryModel {         return SettingsBackupModel(exporter: exporter)     } -    /// Provides a settings backup import model for importing into a ready library.+    /// Provides a settings backup import model for restoring into a ready library.     public func settingsBackupImportModel() -> SettingsBackupImportModel? {-        guard let config = resolvedConfiguration else { return nil }+        guard let repo = repository else { return nil }         return SettingsBackupImportModel(-            configuration: config,-            capabilities: capabilities,-            onCompletion: { [weak self] in-                // Replacement uses a separate fresh container. Reopen the fixed-                // V4 store so every subsequent read observes the imported graph.-                await self?.bootstrap()-            }+            committer: LibraryImportCommitter(repository: repo),+            onCompletion: { [weak self] in await self?.handleImportCompletion() }         )     } +    /// What a completed import costs this model.+    ///+    /// A refresh, not a re-bootstrap (Q43). The import runs on the live+    /// container, so the imported graph is already the one every read observes;+    /// re-opening would construct a second mirrored container over one store,+    /// which is the in-process 134422 collision (Q24).+    ///+    /// The completed import also removed the sidecar, so the notice about+    /// whichever earlier import stopped partway goes with it: re-running the+    /// import is the repair, and this is the reader having run it (Req 4.4).+    private func handleImportCompletion() async {+        interruptedImport = nil+        await refreshDiagnosesAndSnapshots()+    }++    /// Req 4.4's sentence, or nil when no import stopped partway.+    ///+    /// Wording lives here rather than in the view, per the+    /// `LibraryDiagnosticsModel` precedent. Two things it must do: name the+    /// archive, because "an import" is not enough to act on when a reader keeps+    /// several backups; and say plainly that it did not finish, because the+    /// library is *openable* either way and nothing else on screen would tell+    /// them a restore is half-applied.+    ///+    /// No date, deliberately. The sidecar's start date is shown by nothing: it+    /// invites reading an old one as stale, and Req 4.4 reports the interruption+    /// however old because age does not make it untrue.+    public var interruptedImportNotice: String? {+        guard let interruptedImport else { return nil }+        return "An import of \(interruptedImport.archiveName) did not finish. "+            + "Part of it was applied. Import the same backup again to complete it — "+            + "restoring adds and updates, so running it twice is safe."+    }+     /// Seeds a composed store: an untaught actionable Entry (for teaching through     /// the composed surface) plus a composed-taught Site whose URL rule supplies     /// Work identity (for Work detail → Review URL identity → Recalculate).@@ -420,7 +699,7 @@ public final class AppLibraryModel {         _ fixture: UITestFixtureKind,         in repository: LibraryRepository     ) async throws {-        let counts = try await repository.debugCounts()+        let counts = try await repository.recordCounts()         guard counts == .zero else {             throw LibraryRepositoryError.invalidInput(                 operation: "preparing UI test fixture",

diff --git a/Asterism/Asterism/ViewModels/EntryDetailModel.swift b/Asterism/Asterism/ViewModels/EntryDetailModel.swiftindex ea45b88..529afe4 100644--- a/Asterism/Asterism/ViewModels/EntryDetailModel.swift+++ b/Asterism/Asterism/ViewModels/EntryDetailModel.swift@@ -15,10 +15,72 @@ public final class EntryDetailModel {         case error(message: String)     } +    /// Why there is no entry to show, when there is none.+    ///+    /// `state` says the load finished; it does not say what the reader is looking+    /// at. Three different things leave `entry` nil and only one of them is a+    /// deletion, so the screen needs the distinction — a quarantined site had the+    /// reader told their entry was removed while it sat in the store waiting for+    /// the reconciler (two-device runbook, 2026-07-30).+    ///+    /// The wording lives here rather than in the view, as it does for every other+    /// surface in this app.+    public enum Unavailability: Equatable, Sendable {+        /// The record is gone: the reader deleted it here, or another device did+        /// and the deletion arrived.+        case deleted+        /// The site's teaching state failed validation, so the detail refuses+        /// (Q39). Not damage the reader has to act on — the reconciler repairs+        /// this class on its own (Decision 7), which is what the message says.+        case siteRulesInvalid+        /// Anything else. The Entry row still exists, so no deletion is claimed.+        case unavailable(reason: String)++        public var title: String {+            switch self {+            case .deleted: "Entry deleted"+            case .siteRulesInvalid: "Site rules not valid"+            case .unavailable: "Entry unavailable"+            }+        }++        public var message: String {+            switch self {+            case .deleted:+                "This entry has been removed."+            case .siteRulesInvalid:+                // The first sentence is Recent's, word for word: one condition+                // must not read as two different things on two screens.+                """+                This site's saved rules are not valid. The app repairs this \+                automatically — this entry is still in your library.+                """+            case .unavailable(let reason):+                reason+            }+        }++        public var systemImage: String {+            switch self {+            case .deleted: "trash"+            case .siteRulesInvalid, .unavailable: "exclamationmark.triangle"+            }+        }++        public var accessibilityIdentifier: String {+            switch self {+            case .deleted: "entry-detail-deleted"+            case .siteRulesInvalid: "entry-detail-site-rules-invalid"+            case .unavailable: "entry-detail-unavailable"+            }+        }+    }+     public private(set) var state: State = .loading     public private(set) var entry: EntrySnapshot?     public private(set) var errorMessage: String?     public private(set) var teachingDetail: EntryTeachingDetail?+    public private(set) var unavailability: Unavailability = .deleted      // Draft fields     public var draftNote: String = ""@@ -55,11 +117,29 @@ public final class EntryDetailModel {             self.draftRating = snapshot.rating             state = .ready         } catch {+            unavailability = Self.unavailability(for: error)             state = .error(message: error.localizedDescription)             Self.logger.error("Entry detail load failed: \(String(describing: error), privacy: .public)")         }     } +    /// What a failed load means for the reader.+    ///+    /// Only `recordNotFound` for an Entry says the record is gone. A quarantine+    /// says the *site's* rules are the problem, and everything else says nothing+    /// about the record at all — in both cases the row is still there, so the+    /// screen must not claim a deletion.+    private static func unavailability(for error: Error) -> Unavailability {+        guard let repositoryError = error as? LibraryRepositoryError else {+            return .unavailable(reason: error.localizedDescription)+        }+        return switch repositoryError {+        case .recordNotFound(let type, _) where type == "Entry": .deleted+        case .quarantined: .siteRulesInvalid+        default: .unavailable(reason: repositoryError.description)+        }+    }+     /// Commits note/rating edit. Suppresses duplicate submissions.     public func update() async {         guard !isSubmitting else { return }@@ -92,6 +172,7 @@ public final class EntryDetailModel {             // Entry no longer exists; detail should dismiss             state = .ready             entry = nil+            unavailability = .deleted         } catch {             errorMessage = error.localizedDescription             state = .error(message: error.localizedDescription)

diff --git a/Asterism/Asterism/ViewModels/MaintenanceViewModels.swift b/Asterism/Asterism/ViewModels/MaintenanceViewModels.swiftindex c4da024..6af522f 100644--- a/Asterism/Asterism/ViewModels/MaintenanceViewModels.swift+++ b/Asterism/Asterism/ViewModels/MaintenanceViewModels.swift@@ -151,9 +151,9 @@ public final class LibraryDiagnosticsModel {         case .siteTuple:             "Asterism cannot use the rules saved for this site, so entries from it are left as captured."         case .duplicateSiteRows(_, let rowCount):-            "This site is stored more than once (\(rowCount) copies), so Asterism cannot tell which of its rules apply."+            "This site is stored more than once (\(rowCount) copies). Asterism uses one of them everywhere and moves the others' rules onto it."         case .siteMissing(_, let entryCount, let workCount):-            "\(pluralised(entryCount, "entry", "entries")) and \(pluralised(workCount, "work", "works")) name this site, but the library holds no site record for it."+            "\(Pluralisation.count(entryCount, "entry", "entries")) and \(Pluralisation.count(workCount, "work", "works")) name this site, but the library holds no site record for it."         case .duplicateIdentity(let type, _, _, let rowCount):             "\(rowCount) \(typeLabel(type)) records share one identifier, so Asterism cannot tell them apart."         }@@ -162,9 +162,9 @@ public final class LibraryDiagnosticsModel {     private static func recordCountText(_ diagnosis: LibraryDiagnosis) -> String {         switch diagnosis {         case .siteTuple, .duplicateSiteRows:-            pluralised(diagnosis.recordCount, "site record affected", "site records affected")+            Pluralisation.count(diagnosis.recordCount, "site record affected", "site records affected")         case .siteMissing, .duplicateIdentity:-            pluralised(diagnosis.recordCount, "record affected", "records affected")+            Pluralisation.count(diagnosis.recordCount, "record affected", "records affected")         }     } @@ -173,7 +173,12 @@ public final class LibraryDiagnosticsModel {         case .siteTuple:             "Re-teaching this site replaces those rules and clears this."         case .duplicateSiteRows:-            "Re-teaching cannot clear this: it would rewrite one copy and leave the other. Asterism does not merge duplicate sites yet."+            // Q36: informational. Asterism consolidates the copies itself and+            // teaching one still works — it writes to the copy every other screen+            // already resolves (Q39). The emptied copies are kept rather than+            // deleted (Decision 6), so this line stays visible afterwards and must+            // read as expected rather than as damage.+            "Nothing to do: Asterism sorts this out on its own, and teaching this site still works."         case .siteMissing:             // Q40: teaching refuses a hostname with no Site row, while capture and             // creating a Work both insert one — so the route exists, it is simply@@ -190,7 +195,7 @@ public final class LibraryDiagnosticsModel {         // because "12 records unresolved" reads as routine bookkeeping and this         // is not that.         if diagnostics.suggestsDamage { return "This looks like damage, not a routine artefact" }-        return pluralised(diagnostics.affectedRecordCount, "record unresolved", "records unresolved")+        return Pluralisation.count(diagnostics.affectedRecordCount, "record unresolved", "records unresolved")     }      private static func detail(_ diagnostics: LibraryDiagnostics) -> String {@@ -201,16 +206,12 @@ public final class LibraryDiagnosticsModel {             return """                 iCloud sync is off, so none of this can be a sync artefact. It points to a bug, \                 an interrupted migration, or a damaged library file. \-                \(pluralised(diagnostics.affectedRecordCount, "record is", "records are")) affected.+                \(Pluralisation.count(diagnostics.affectedRecordCount, "record is", "records are")) affected.                 """         }         return "Asterism opened your library and kept everything it could resolve. What it could not is listed below."     } -    private static func pluralised(_ count: Int, _ singular: String, _ plural: String) -> String {-        "\(count) \(count == 1 ? singular : plural)"-    }-     /// The reader-facing name for a de-duplicated record type. Deliberately not     /// the model type name: `URLRulePattern` is not a phrase anyone reading a     /// diagnosis should have to decode.

diff --git a/Asterism/Asterism/ViewModels/Pluralisation.swift b/Asterism/Asterism/ViewModels/Pluralisation.swiftnew file mode 100644index 0000000..f202dcb--- /dev/null+++ b/Asterism/Asterism/ViewModels/Pluralisation.swift@@ -0,0 +1,12 @@+import Foundation++/// `"1 record"` / `"2 records"`, once.+///+/// Two view models word counts for the reader — the diagnosis screen and the+/// Settings iCloud section — and each carried a byte-identical private copy of+/// this. It is one sentence-building rule, so it lives in one place.+enum Pluralisation {+    static func count(_ count: Int, _ singular: String, _ plural: String) -> String {+        "\(count) \(count == 1 ? singular : plural)"+    }+}

diff --git a/Asterism/Asterism/ViewModels/RecentSyncPresentation.swift b/Asterism/Asterism/ViewModels/RecentSyncPresentation.swiftnew file mode 100644index 0000000..a4dcac5--- /dev/null+++ b/Asterism/Asterism/ViewModels/RecentSyncPresentation.swift@@ -0,0 +1,61 @@+import AsterismCore+import Foundation++/// What Recent renders about sync: the banner, and whether an empty library is+/// still arriving (Req 6.5, 8.2, 8.3).+///+/// A pure function of the observed status, computed on every read by+/// `AppLibraryModel.recentSyncPresentation`, so Recent moves when the monitor+/// does without a relaunch (Req 8.6). The wording lives here rather than in the+/// view, per the `LibraryDiagnosticsModel` precedent — `RecentView` chooses+/// styling only.+public struct RecentSyncPresentation: Equatable, Sendable {+    /// The banner's sentence, or nil for no banner.+    ///+    /// **Actionable only** (Q11). Transient failures clear themselves, the+    /// self-healing ones are the mirror re-syncing, and a misconfiguration is+    /// developer-grade — none of them is something the reader can act on, and a+    /// persisted record turning routine noise into a standing alarm on the main+    /// screen is what Q42 refuses. All of them are still named in Settings.+    public let bannerMessage: String?++    /// Req 6.5: this device is mirroring, nothing has ever arrived, and the+    /// attachment did not fail — so an empty library is still filling rather+    /// than settled. Recent's empty branch says so instead of "No captures yet".+    public let isAwaitingFirstSync: Bool++    /// The state of a build that cannot mirror, and the default a view falls+    /// back to before the monitor exists.+    public static let inactive = RecentSyncPresentation(+        bannerMessage: nil, isAwaitingFirstSync: false)++    private init(bannerMessage: String?, isAwaitingFirstSync: Bool) {+        self.bannerMessage = bannerMessage+        self.isAwaitingFirstSync = isAwaitingFirstSync+    }++    public init(status: SyncStatusRecord, mirroringRequested: Bool) {+        // The status file outlives the mirroring flag — a library that mirrored+        // under one build opens under one that does not — so a build that is not+        // mirroring reports nothing rather than replaying a stale condition.+        guard mirroringRequested else {+            self = .inactive+            return+        }+        let failure = status.lastFailure+        bannerMessage = failure.flatMap(Self.bannerMessage)+        isAwaitingFirstSync =+            !status.hasEverImported && failure?.classification != .misconfigured+    }++    /// Short, because it shares a 44 pt row with the "Settings" affordance. The+    /// condition and the remedy in full are Settings' job (Req 8.2).+    private static func bannerMessage(_ record: SyncFailureRecord) -> String? {+        guard case .actionable(let condition) = record.classification else { return nil }+        switch condition {+        case .signedOut: return "You are signed out of iCloud"+        case .storageFull: return "Your iCloud storage is full"+        case .restricted: return "This iCloud account cannot sync"+        }+    }+}

diff --git a/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift b/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swiftindex 06c24a1..613e4e9 100644--- a/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift+++ b/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift@@ -51,73 +51,51 @@ public enum BackupDocumentError: Error, Equatable, Sendable, CustomStringConvert  // MARK: - Backup Import Committing Protocol -/// Test seam for the Core import commit operations.-/// Abstracts LibraryRepository static methods so tests can inject fakes.+/// Test seam for the Core import commit. One method, because there is one flow:+/// import adds what is missing and updates what is older, so filling an empty+/// library is the degenerate case of the same operation rather than a separate+/// one (Decision 2, Q37). public protocol BackupImportCommitting: Sendable {-    func confirmImportFillEmpty(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        capabilities: AsterismCapabilities-    ) async throws -> BackupImportCommitResult+    /// The library's current record counts, for the preview.+    func currentCounts() async throws -> LibraryRecordCounts -    func confirmImportReplace(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        expectedInventory: LibraryInventoryFingerprint,-        capabilities: AsterismCapabilities+    /// Applies the archive. Never deletes.+    func confirmImport(+        plan: BackupImportV4Plan, archiveName: String?     ) async throws -> BackupImportCommitResult--    func computeInventoryFingerprint(-        configuration: LibraryConfiguration-    ) async throws -> LibraryInventoryFingerprint } -/// Production implementation that calls through to LibraryRepository.+/// Production implementation, calling the live repository.+///+/// It holds the repository rather than a `LibraryConfiguration` because the+/// import now runs on the container the app already has open: a second container+/// over the same store is the in-process 134422 collision under mirroring (Q24). public struct LibraryImportCommitter: BackupImportCommitting, Sendable {-    public nonisolated init() {}+    private let repository: any LibraryProviding -    public func confirmImportFillEmpty(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        capabilities: AsterismCapabilities-    ) async throws -> BackupImportCommitResult {-        try await LibraryRepository.confirmImportFillEmpty(-            configuration,-            plan: plan,-            capabilities: capabilities-        )+    public nonisolated init(repository: any LibraryProviding) {+        self.repository = repository     } -    public func confirmImportReplace(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        expectedInventory: LibraryInventoryFingerprint,-        capabilities: AsterismCapabilities-    ) async throws -> BackupImportCommitResult {-        try await LibraryRepository.confirmImportReplace(-            configuration,-            plan: plan,-            expectedInventory: expectedInventory,-            capabilities: capabilities-        )+    public func currentCounts() async throws -> LibraryRecordCounts {+        try await repository.recordCounts()     } -    public func computeInventoryFingerprint(-        configuration: LibraryConfiguration-    ) async throws -> LibraryInventoryFingerprint {-        try await LibraryRepository.computeInventoryFingerprint(-            configuration: configuration-        )+    public func confirmImport(+        plan: BackupImportV4Plan, archiveName: String?+    ) async throws -> BackupImportCommitResult {+        try await repository.confirmImport(plan: plan, archiveName: archiveName)     } }  // MARK: - SettingsBackupImportModel -/// Drives the Settings backup import surface for nonempty libraries.-/// Supports both import into a ready-empty library and destructive replacement-/// of a nonempty library with preview and separate confirmation. (Req 1.11)+/// Drives the Settings backup import surface. ///-/// Only calls Core confirmation after picker/preview interaction.+/// **One flow.** The fill-empty/replace distinction is gone with the destructive+/// path that motivated it: import adds and updates and never deletes, so there is+/// nothing to warn about twice and no inventory to re-check. The preview says+/// what the archive holds and what the library holds; confirming applies it. @MainActor @Observable public final class SettingsBackupImportModel {     private static let logger = Logger(subsystem: "me.nore.ig.Asterism", category: "SettingsImport")@@ -131,13 +109,9 @@ public final class SettingsBackupImportModel {         case pickingDocument         /// Reading and decoding the selected backup.         case decodingBackup-        /// Import plan ready — for empty library, simple fill confirmation.-        case readyToFill(preview: FillPreview)-        /// Import plan ready — for nonempty library, destructive replacement preview.-        case readyToReplace(preview: ReplacePreview)-        /// Confirming destructive replacement (second confirmation step).-        case confirmingReplace(preview: ReplacePreview)-        /// Committing (fill or replace in progress).+        /// Import plan ready.+        case readyToImport(preview: Preview)+        /// Committing.         case committing         /// Import completed successfully.         case completed(LibraryRecordCounts)@@ -145,44 +119,31 @@ public final class SettingsBackupImportModel {         case failed(message: String)     } -    /// Preview for fill-empty import.-    public struct FillPreview: Equatable, Sendable {-        public let metadata: BackupImportMetadata-        public let importCounts: LibraryRecordCounts-    }--    /// Preview for destructive replacement.-    public struct ReplacePreview: Equatable, Sendable {+    public struct Preview: Equatable, Sendable {         public let metadata: BackupImportMetadata         public let importCounts: LibraryRecordCounts         public let currentCounts: LibraryRecordCounts-        public let inventory: LibraryInventoryFingerprint     }      public private(set) var state: State = .idle      // MARK: - Dependencies -    private let configuration: LibraryConfiguration-    private let capabilities: AsterismCapabilities     private let documentReader: any BackupDocumentReading     private let committer: any BackupImportCommitting     private let onCompletion: @Sendable () async -> Void      /// The plan retained between preview and confirmation.     private var currentPlan: BackupImportV4Plan?+    private var currentArchiveName: String?      // MARK: - Init      public init(-        configuration: LibraryConfiguration,-        capabilities: AsterismCapabilities = .current,         documentReader: any BackupDocumentReading = SecurityScopedDocumentReader(),-        committer: any BackupImportCommitting = LibraryImportCommitter(),+        committer: any BackupImportCommitting,         onCompletion: @escaping @Sendable () async -> Void     ) {-        self.configuration = configuration-        self.capabilities = capabilities         self.documentReader = documentReader         self.committer = committer         self.onCompletion = onCompletion@@ -203,7 +164,7 @@ public final class SettingsBackupImportModel {         currentPlan = nil     } -    /// Called when a file is selected. Reads, decodes, and determines fill vs replace mode.+    /// Reads, decodes, and presents the one preview.     public func handleDocumentSelection(_ url: URL) async {         Self.logger.debug("Settings import: document selected")         state = .decodingBackup@@ -212,29 +173,14 @@ public final class SettingsBackupImportModel {             let data = try documentReader.readData(from: url)             let plan = try BackupImporter.planV4(from: data)             currentPlan = plan--            // Determine if library is empty or nonempty-            let fingerprint = try await committer.computeInventoryFingerprint(-                configuration: configuration-            )--            if fingerprint.counts == .zero {-                // Empty library — simple fill-                Self.logger.debug("Settings import: empty library — fill mode")-                state = .readyToFill(preview: FillPreview(-                    metadata: plan.metadata,-                    importCounts: plan.counts-                ))-            } else {-                // Nonempty library — destructive replacement required (Req 1.11)-                Self.logger.debug("Settings import: nonempty library — replacement mode")-                state = .readyToReplace(preview: ReplacePreview(-                    metadata: plan.metadata,-                    importCounts: plan.counts,-                    currentCounts: fingerprint.counts,-                    inventory: fingerprint-                ))-            }+            currentArchiveName = url.lastPathComponent++            let counts = try await committer.currentCounts()+            state = .readyToImport(preview: Preview(+                metadata: plan.metadata,+                importCounts: plan.counts,+                currentCounts: counts+            ))         } catch let error as BackupDocumentError {             Self.logger.error("Settings import: document read failed: \(String(describing: error))")             state = .failed(message: error.description)@@ -247,101 +193,35 @@ public final class SettingsBackupImportModel {         }     } -    /// Confirms fill-empty import.-    public func confirmFillImport() async {+    /// Applies the archive.+    public func confirmImport() async {         guard let plan = currentPlan else {             state = .failed(message: "No import plan available.")             return         } -        Self.logger.debug("Settings import: confirming fill")+        Self.logger.debug("Settings import: confirming")         state = .committing          do {-            let result = try await committer.confirmImportFillEmpty(-                configuration,-                plan: plan,-                capabilities: capabilities-            )-+            let result = try await committer.confirmImport(+                plan: plan, archiveName: currentArchiveName)             switch result {             case .committed(let counts):-                Self.logger.debug("Settings import: fill committed")+                Self.logger.debug("Settings import: committed")                 state = .completed(counts)+                // A refresh, not a re-bootstrap: the import ran on the live+                // container, so there is no second graph to go and open — and+                // re-opening under mirroring constructs a second live mirrored+                // container over one store, which is 134422 (Q24, Q43).                 await onCompletion()-            case .stale(let reason):-                Self.logger.debug("Settings import: fill stale — \(reason)")-                state = .failed(message: "Library state changed: \(reason). Please try again.")             }         } catch {-            Self.logger.error("Settings import: fill commit failed: \(String(describing: error))")+            Self.logger.error("Settings import: commit failed: \(String(describing: error))")             state = .failed(message: "Import failed: \(error.localizedDescription)")         }     } -    /// Moves to the destructive replacement confirmation step (second confirm).-    public func proceedToReplaceConfirmation() {-        guard case .readyToReplace(let preview) = state else { return }-        Self.logger.debug("Settings import: proceeding to replacement confirmation")-        state = .confirmingReplace(preview: preview)-    }--    /// Confirms destructive replacement. Requires exact inventory match. (Req 1.22)-    public func confirmReplace() async {-        let inventory: LibraryInventoryFingerprint-        switch state {-        case .confirmingReplace(let preview):-            inventory = preview.inventory-        default:-            state = .failed(message: "Replace not in correct state.")-            return-        }--        guard let plan = currentPlan else {-            state = .failed(message: "No import plan available.")-            return-        }--        Self.logger.debug("Settings import: confirming destructive replacement")-        state = .committing--        do {-            let result = try await committer.confirmImportReplace(-                configuration,-                plan: plan,-                expectedInventory: inventory,-                capabilities: capabilities-            )--            switch result {-            case .committed(let counts):-                Self.logger.debug("Settings import: replacement committed")-                state = .completed(counts)-                await onCompletion()-            case .stale(let reason):-                // Inventory changed — refresh (Req 1.22)-                Self.logger.debug("Settings import: replacement stale — \(reason)")-                // Refresh the fingerprint and re-present-                do {-                    let freshFingerprint = try await committer.computeInventoryFingerprint(-                        configuration: configuration-                    )-                    state = .readyToReplace(preview: ReplacePreview(-                        metadata: plan.metadata,-                        importCounts: plan.counts,-                        currentCounts: freshFingerprint.counts,-                        inventory: freshFingerprint-                    ))-                } catch {-                    state = .failed(message: "Failed to refresh library state: \(error.localizedDescription)")-                }-            }-        } catch {-            Self.logger.error("Settings import: replace commit failed: \(String(describing: error))")-            state = .failed(message: "Replacement failed: \(error.localizedDescription)")-        }-    }-     /// Cancels and returns to idle.     public func cancel() {         Self.logger.debug("Settings import: cancelled")

diff --git a/Asterism/Asterism/ViewModels/SettingsSyncModel.swift b/Asterism/Asterism/ViewModels/SettingsSyncModel.swiftnew file mode 100644index 0000000..e3f94e8--- /dev/null+++ b/Asterism/Asterism/ViewModels/SettingsSyncModel.swift@@ -0,0 +1,278 @@+import AsterismCore+import Foundation++// MARK: - Status source++/// What a sync surface reads its state from.+///+/// `SyncMonitor` is the production conformance. The protocol exists because the+/// monitor's ingest seam is internal to AsterismCore, so nothing in the app —+/// including its tests — can drive a real monitor through a failure; and because+/// the app holds no monitor at all until it is constructed after bootstrap, at+/// which point every surface below has to keep working unchanged.+@MainActor+public protocol SyncStatusReporting: AnyObject {+    /// What the app last observed. Read live rather than snapshotted: the+    /// monitor is `@Observable`, so a view reading through this during `body`+    /// re-renders when the status changes (Req 8.6).+    var status: SyncStatusRecord { get }+}++extension SyncMonitor: SyncStatusReporting {}++// MARK: - Settings iCloud section++/// Backs the Settings "iCloud" section (Req 8.1–8.5).+///+/// The wording lives here rather than in the view, per the+/// `LibraryDiagnosticsModel` precedent, so the sentences are testable without+/// rendering anything. Three things are deliberate:+///+/// - **Every date is *last observed*.** Nothing is seen while the app is+///   suspended, so `observationNote` says as much beside the two lines; a+///   surface that implied a complete log would overstate what a status file+///   written on notification can know (Req 8.1).+/// - **Only `actionable` is banner-worthy** (Q11). Transient, self-healing,+///   misconfigured and terminal failures are named here in full and never reach+///   Recent — a persisted record must not turn routine noise into an alarm+///   (Q42).+/// - **The health line never says "healthy" while the library is degraded**+///   (Req 8.5). It is not "not healthy" either: the counts say what is wrong,+///   and the verdict is simply withheld.+@MainActor @Observable+public final class SettingsSyncModel {++    /// One recorded failure, rendered into reader-facing sentences.+    public struct FailureLine: Equatable, Sendable {+        /// What is wrong, in the reader's terms.+        public let condition: String+        /// What to do about it — an action for the actionable classes, and an+        /// explicit "nothing to do" for the ones the app or the mirror resolves.+        public let remedy: String+        /// The framework's own words. For the unclassified arm this is the only+        /// information there is, so it is surfaced rather than swallowed.+        public let detail: String+        /// When the app observed it.+        public let observed: String+        /// Whether Recent raises its banner for this (Req 8.2 vs 8.3, 8.4).+        public let isBannerWorthy: Bool+    }++    // MARK: - Dependencies++    private let source: (any SyncStatusReporting)?+    private let library: any LibraryProviding+    /// Whether this build asked to mirror at all. False for every host test, UI+    /// test root, and any configuration whose `ASTERISM_MIRRORING_ENABLED` is+    /// `NO` — in which case the section says so instead of reporting a library+    /// that "never synced" as though something were broken.+    public let mirroringRequested: Bool++    // MARK: - Loaded state (Req 8.5)++    public private(set) var quarantinedHostnameCount = 0+    public private(set) var duplicateIdentityRecordCount = 0++    /// Whether the counts below have ever been read.+    ///+    /// They start at zero, which is indistinguishable from a clean library, so+    /// before the first `load()` the health verdict would read "healthy" off+    /// nothing at all — on the first frame, and again on every frame until the+    /// task completes. Q15's objection is precisely to a green line above a+    /// degraded library, and "we have not looked yet" is a way of producing one.+    /// The verdict is therefore withheld rather than guessed, exactly as it is+    /// when the counts are nonzero.+    public private(set) var hasLoaded = false++    public init(+        source: (any SyncStatusReporting)?,+        library: any LibraryProviding,+        mirroringRequested: Bool+    ) {+        self.source = source+        self.library = library+        self.mirroringRequested = mirroringRequested+    }++    /// Reads the library's current diagnoses for the health gate.+    ///+    /// A read, not a re-derivation, exactly as `LibraryDiagnosticsModel.load()`+    /// is: `AppLibraryModel` re-derives on foreground and after every write it+    /// commits, so scanning again here would duplicate that work on a store the+    /// extension also writes.+    ///+    /// Re-runnable, and rerun by the view whenever the observed status changes+    /// (`SettingsView`'s `.task(id:)`). Settings can stay open across an arrival,+    /// and the counts are what Req 8.5 puts beside the sync lines — read once at+    /// presentation they would describe the library as it was when the sheet+    /// opened while the two lines above them moved.+    public func load() async {+        let diagnostics = await library.diagnostics+        quarantinedHostnameCount = diagnostics.quarantineMap().count+        duplicateIdentityRecordCount = diagnostics.diagnoses.reduce(into: 0) { total, diagnosis in+            if case .duplicateIdentity(_, _, _, let rowCount) = diagnosis { total += rowCount }+        }+        hasLoaded = true+    }++    // MARK: - Status++    /// The record as it stands now. Never cached: the surface has to move when+    /// the monitor does, without a relaunch (Req 8.6).+    public var status: SyncStatusRecord { source?.status ?? .neverSynced }++    // MARK: - The two lines (Req 8.1)++    public var lastExportLine: String {+        guard let date = status.lastExportCompleted else {+            return "Asterism has not seen a change of yours reach iCloud yet."+        }+        return "Last change seen reaching iCloud: \(Self.format(date))"+    }++    public var lastImportLine: String {+        guard let date = status.lastImportCompleted else {+            return "Asterism has not seen anything arrive from iCloud yet."+        }+        return "Last arrival seen from iCloud: \(Self.format(date))"+    }++    /// Why both lines are floors rather than a log.+    public var observationNote: String {+        "Asterism only sees sync while it is running, so these are the last times it looked, not the last times iCloud worked."+    }++    /// Req 6.5 in Settings (Q31): an empty library that has never imported is+    /// still arriving, not settled. Withheld when the attachment itself failed —+    /// nothing is on its way through a container the app could not open.+    public var firstSyncLine: String? {+        guard mirroringRequested, !status.hasEverImported, !isMisconfigured else { return nil }+        return "Nothing has arrived from iCloud on this device yet. If you use Asterism elsewhere, your library is still on its way."+    }++    // MARK: - The recorded failure (Req 8.2–8.4)++    public var failure: FailureLine? {+        status.lastFailure.map(Self.line)+    }++    /// Whether Recent raises its banner for the current state (Req 8.2).+    public var isBannerWorthy: Bool { status.lastFailure?.classification.isBannerWorthy ?? false }++    private var isMisconfigured: Bool { status.lastFailure?.classification == .misconfigured }++    // MARK: - Health (Req 8.5)++    /// Sync is healthy only when it is on, the library has been looked at,+    /// nothing failed, and it carries neither a quarantined hostname nor records+    /// sharing an identifier.+    public var isHealthy: Bool {+        mirroringRequested+            && hasLoaded+            && status.lastFailure == nil+            && quarantinedHostnameCount == 0+            && duplicateIdentityRecordCount == 0+    }++    /// The word "healthy" appears in exactly one branch, and that branch is+    /// `isHealthy`. Q15's objection is to a green line over a degraded library,+    /// and the fix is to withhold the verdict rather than to negate it.+    ///+    /// Derived from `isHealthy` rather than re-deriving the same four conditions+    /// in the same order: the two used to branch independently, so a condition+    /// added to one and not the other would have produced exactly the green line+    /// over a degraded library that both exist to prevent. The branches below run+    /// only when the verdict is already withheld, and say *which* of the four is+    /// the reason.+    public var healthLine: String {+        if isHealthy { return "iCloud sync looks healthy." }+        if !mirroringRequested {+            return "iCloud sync is off in this build of Asterism."+        }+        if quarantinedHostnameCount > 0 || duplicateIdentityRecordCount > 0 {+            return "Your library still holds records Asterism cannot resolve, so sync is not settled. Check Library lists them."+        }+        if status.lastFailure != nil {+            return "The last thing Asterism saw from iCloud was a problem, not a success."+        }+        return "Asterism is checking your library."+    }++    /// Req 8.5: the counts are visible beside the sync lines whatever they are.+    ///+    /// Until they have been read, they are not zero — they are unknown, and+    /// saying "0 sites quarantined" about a library nobody has looked at is the+    /// same overstatement the health line refuses.+    public var countsLine: String {+        guard hasLoaded else { return "Counting what the library holds…" }+        let sites = Pluralisation.count(quarantinedHostnameCount, "site", "sites")+        let records = Pluralisation.count(duplicateIdentityRecordCount, "record", "records")+        return "\(sites) quarantined · \(records) sharing an identifier"+    }++    // MARK: - Wording++    private static func line(_ record: SyncFailureRecord) -> FailureLine {+        FailureLine(+            condition: condition(record),+            remedy: remedy(record.classification),+            detail: record.message,+            observed: format(record.date),+            isBannerWorthy: record.classification.isBannerWorthy)+    }++    private static func condition(_ record: SyncFailureRecord) -> String {+        switch record.classification {+        case .actionable(.signedOut):+            "You are signed out of iCloud, so Asterism cannot sync this library."+        case .actionable(.storageFull):+            "Your iCloud storage is full, so your notes are no longer reaching iCloud."+        case .actionable(.restricted):+            "This iCloud account is restricted and is not allowed to sync Asterism's library."+        case .transient:+            "\(half(record.eventType)) did not finish: Asterism was offline, iCloud was busy, or the request was throttled."+        case .selfHealing:+            "iCloud asked Asterism to rebuild its copy of the library."+        case .misconfigured:+            "Asterism could not attach to iCloud, so this device is working from its own copy of the library."+        case .terminal:+            "\(half(record.eventType)) failed for a reason Asterism does not recognise."+        }+    }++    private static func remedy(_ classification: SyncFailureClassification) -> String {+        switch classification {+        case .actionable(.signedOut):+            "Sign in to iCloud in the Settings app. Asterism picks up where it left off."+        case .actionable(.storageFull):+            "Free up iCloud storage, or upgrade the plan, in the Settings app."+        case .actionable(.restricted):+            "Check the account's restrictions in the Settings app, or sign in with an account that allows iCloud Drive."+        case .transient:+            "Nothing to do. Asterism tries again on its own."+        case .selfHealing:+            "Nothing to do. Asterism re-syncs from scratch by itself, which can take a while for a large library."+        case .misconfigured:+            "Your library is safe and unchanged. This is a setup problem in the build rather than something to fix here."+        case .terminal:+            "Your library is unaffected. If notes stop appearing on your other devices, export a backup and reopen Asterism."+        }+    }++    /// Which half of mirroring an event was, in the reader's terms. This is what+    /// `SyncFailureRecord.eventType` is for: "the export failed" and "the import+    /// failed" are different facts and Q15 refuses to merge them.+    private static func half(_ eventType: SyncEventType) -> String {+        switch eventType {+        case .exportEvent: "Sending your latest changes to iCloud"+        case .importEvent: "Fetching changes from iCloud"+        case .setup: "Setting up iCloud sync"+        }+    }++    /// Shared by the tests so the assertions pin the value rather than a locale's+    /// rendering of it.+    public static func format(_ date: Date) -> String {+        date.formatted(date: .abbreviated, time: .shortened)+    }+}

diff --git a/Asterism/Asterism/Views/EntryDetailView.swift b/Asterism/Asterism/Views/EntryDetailView.swiftindex 612d043..07ac472 100644--- a/Asterism/Asterism/Views/EntryDetailView.swift+++ b/Asterism/Asterism/Views/EntryDetailView.swift@@ -25,12 +25,15 @@ struct EntryDetailView: View {                 if let entry = model.entry {                     entryContent(entry)                 } else {+                    // Which of these it is matters: a quarantined site leaves the+                    // Entry in the store, and the screen used to report every one+                    // of them as a deletion. The model owns the wording.                     ContentUnavailableView(-                        "Entry deleted",-                        systemImage: "trash",-                        description: Text("This entry has been removed.")+                        model.unavailability.title,+                        systemImage: model.unavailability.systemImage,+                        description: Text(model.unavailability.message)                     )-                    .accessibilityIdentifier("entry-detail-deleted")+                    .accessibilityIdentifier(model.unavailability.accessibilityIdentifier)                 }             }         }

diff --git a/Asterism/Asterism/Views/RecentView.swift b/Asterism/Asterism/Views/RecentView.swiftindex 42bb4d5..f001250 100644--- a/Asterism/Asterism/Views/RecentView.swift+++ b/Asterism/Asterism/Views/RecentView.swift@@ -13,10 +13,17 @@ struct RecentView: View {     /// `refreshAll` would have swallowed the reason. Shown so a stale count is     /// never presented as a current one.     let diagnosisRefreshFailed: Bool+    /// What sync looks like right now (Req 6.5, 8.2). Recomputed by+    /// `AppLibraryModel` on every read, so this view updates when the monitor's+    /// status changes without a relaunch (Req 8.6).+    let sync: RecentSyncPresentation     let onSelect: (UUID) -> Void     let onTeach: ((UUID) -> Void)?     /// Req 4.1's route to the screen listing the diagnoses.     let onShowDiagnostics: (() -> Void)?+    /// Req 8.2's route: the banner names the condition, Settings names the+    /// remedy, so the banner has to be able to get there.+    let onShowSyncSettings: (() -> Void)?      @State private var showingActionableOnly = false @@ -24,16 +31,20 @@ struct RecentView: View {         presentation: RecentPresentation,         capabilities: AsterismCapabilities = .current,         diagnosisRefreshFailed: Bool = false,+        sync: RecentSyncPresentation = .inactive,         onSelect: @escaping (UUID) -> Void,         onTeach: ((UUID) -> Void)? = nil,-        onShowDiagnostics: (() -> Void)? = nil+        onShowDiagnostics: (() -> Void)? = nil,+        onShowSyncSettings: (() -> Void)? = nil     ) {         self.presentation = presentation         self.capabilities = capabilities         self.diagnosisRefreshFailed = diagnosisRefreshFailed+        self.sync = sync         self.onSelect = onSelect         self.onTeach = onTeach         self.onShowDiagnostics = onShowDiagnostics+        self.onShowSyncSettings = onShowSyncSettings     }      /// Filtered groups respecting actionable-only toggle while preserving order.@@ -56,12 +67,7 @@ struct RecentView: View {             banners              if presentation.groups.isEmpty {-                ContentUnavailableView(-                    "No captures yet",-                    systemImage: "clock",-                    description: Text("Share a page to Asterism to begin.")-                )-                .accessibilityIdentifier("recent-empty")+                emptyBranch             } else {                 List {                     ForEach(displayGroups, id: \.day) { group in@@ -92,6 +98,30 @@ struct RecentView: View {         }     } +    /// Req 6.5: an empty library that has never received anything from iCloud is+    /// still filling, and presenting it as settled is what the requirement+    /// forbids. Once one import has completed the ordinary branch returns, for+    /// good — `hasEverImported` latches.+    @ViewBuilder+    private var emptyBranch: some View {+        if sync.isAwaitingFirstSync {+            ContentUnavailableView(+                "Arriving from iCloud",+                systemImage: "icloud.and.arrow.down",+                description: Text(+                    "Nothing has reached this device from iCloud yet. If your library is on another device, it is still on its way.")+            )+            .accessibilityIdentifier("recent-empty-first-sync")+        } else {+            ContentUnavailableView(+                "No captures yet",+                systemImage: "clock",+                description: Text("Share a page to Asterism to begin.")+            )+            .accessibilityIdentifier("recent-empty")+        }+    }+     /// The actionable banner ranks first when both apply: its action is the     /// routine one, and the diagnosis banner reports something the reader is not     /// expected to be doing every day (Q15).@@ -100,6 +130,12 @@ struct RecentView: View {         if capabilities.supportsSegmentTeaching && presentation.actionableCount > 0 {             actionableBanner         }+        // Between the two: less routine than teaching, and unlike the diagnosis+        // banner it reports something outside the library — notes not reaching+        // the reader's other devices — that only they can fix (Req 8.2).+        if let message = sync.bannerMessage, onShowSyncSettings != nil {+            syncBanner(message)+        }         // Req 4.4: the indication disappears with the last diagnosis, because the         // count it is built from is re-derived, never latched.         if presentation.diagnosisCount > 0, onShowDiagnostics != nil {@@ -110,71 +146,93 @@ struct RecentView: View {         }     } -    private var actionableBanner: some View {-        Button {-            if showingActionableOnly {-                showingActionableOnly = false-            } else {-                showingActionableOnly = true-            }-        } label: {+    /// The one banner language, built once (Req 4.1, 8.2).+    ///+    /// Three banners had a copy of it each, and they had already drifted: one+    /// spelled its hit target as a literal `44` where the others read+    /// `AsterismLayout.minHitTarget`. Rendered output and accessibility+    /// identifiers are unchanged — the UI tests key on both.+    ///+    /// `trailing` is nil for a banner with no call-to-action word, which is what+    /// the actionable banner is until it is filtering.+    private func bannerButton(+        icon: String,+        text: String,+        trailing: String?,+        identifier: String,+        accessibilityLabel: String,+        action: @escaping () -> Void+    ) -> some View {+        Button(action: action) {             HStack(spacing: 6) {-                Image(systemName: showingActionableOnly ? "line.3.horizontal.decrease.circle.fill" : "star.fill")+                Image(systemName: icon)                     .font(.caption)                     .foregroundStyle(AsterismColors.amberDark)                     .accessibilityHidden(true)-                Text(showingActionableOnly-                    ? "Showing \(presentation.actionableCount) actionable"-                    : "\(presentation.actionableCount) entries need teaching")+                Text(text)                     .font(.caption)                     .foregroundStyle(AsterismColors.amberDark)                 Spacer()-                if showingActionableOnly {-                    Text("Show All")+                if let trailing {+                    Text(trailing)                         .font(.caption.bold())                         .foregroundStyle(AsterismColors.amberDark)                 }             }             .padding(.horizontal)-            .frame(minHeight: 44)+            .frame(minHeight: AsterismLayout.minHitTarget)             .background(AsterismColors.amberDark.opacity(0.1))         }         .buttonStyle(.plain)         .accessibilityElement(children: .combine)-        .accessibilityIdentifier("actionable-banner")-        .accessibilityLabel(showingActionableOnly-            ? "Showing \(presentation.actionableCount) actionable entries. Tap to show all."-            : "\(presentation.actionableCount) entries need teaching. Tap to filter.")+        .accessibilityIdentifier(identifier)+        .accessibilityLabel(accessibilityLabel)+    }++    private var actionableBanner: some View {+        bannerButton(+            icon: showingActionableOnly+                ? "line.3.horizontal.decrease.circle.fill" : "star.fill",+            text: showingActionableOnly+                ? "Showing \(presentation.actionableCount) actionable"+                : "\(presentation.actionableCount) entries need teaching",+            trailing: showingActionableOnly ? "Show All" : nil,+            identifier: "actionable-banner",+            accessibilityLabel: showingActionableOnly+                ? "Showing \(presentation.actionableCount) actionable entries. Tap to show all."+                : "\(presentation.actionableCount) entries need teaching. Tap to filter."+        ) {+            showingActionableOnly.toggle()+        }     }      /// Req 4.1: the count of affected records, and the route to the screen that-    /// lists them. Same 44 pt Button treatment as `actionableBanner` — this is a-    /// second instance of one banner language, not a second language.+    /// lists them.     private var diagnosisBanner: some View {-        Button {+        bannerButton(+            icon: "exclamationmark.triangle.fill",+            text: diagnosisBannerText,+            trailing: "Review",+            identifier: "diagnosis-banner",+            accessibilityLabel: "\(diagnosisBannerText). Tap to review."+        ) {             onShowDiagnostics?()-        } label: {-            HStack(spacing: 6) {-                Image(systemName: "exclamationmark.triangle.fill")-                    .font(.caption)-                    .foregroundStyle(AsterismColors.amberDark)-                    .accessibilityHidden(true)-                Text(diagnosisBannerText)-                    .font(.caption)-                    .foregroundStyle(AsterismColors.amberDark)-                Spacer()-                Text("Review")-                    .font(.caption.bold())-                    .foregroundStyle(AsterismColors.amberDark)-            }-            .padding(.horizontal)-            .frame(minHeight: AsterismLayout.minHitTarget)-            .background(AsterismColors.amberDark.opacity(0.1))         }-        .buttonStyle(.plain)-        .accessibilityElement(children: .combine)-        .accessibilityIdentifier("diagnosis-banner")-        .accessibilityLabel("\(diagnosisBannerText). Tap to review.")+    }++    /// Req 8.2: the reader must find out from the app, not from a note missing on+    /// their other device. The route is Settings, which is where the condition and+    /// its remedy are spelled out.+    private func syncBanner(_ message: String) -> some View {+        bannerButton(+            icon: "exclamationmark.icloud.fill",+            text: message,+            trailing: "Settings",+            identifier: "sync-banner",+            accessibilityLabel: "\(message). Tap to open Settings."+        ) {+            onShowSyncSettings?()+        }     }      private var diagnosisBannerText: String {

diff --git a/Asterism/Asterism/Views/SettingsBackupImportView.swift b/Asterism/Asterism/Views/SettingsBackupImportView.swiftindex d4d0396..92aa3cf 100644--- a/Asterism/Asterism/Views/SettingsBackupImportView.swift+++ b/Asterism/Asterism/Views/SettingsBackupImportView.swift@@ -4,8 +4,8 @@ import UniformTypeIdentifiers  // MARK: - Settings Backup Import View -/// Settings surface for importing a backup into a ready V3 library.-/// Supports fill-empty (for ready-empty) and destructive replacement (for nonempty).+/// Settings surface for restoring a backup into a ready library. One flow: the+/// archive adds what is missing and updates what is older, and deletes nothing. struct SettingsBackupImportView: View {     @State private var model: SettingsBackupImportModel     @State private var showingDocumentPicker = false@@ -23,12 +23,8 @@ struct SettingsBackupImportView: View {                 idleView  // Picker shown as sheet             case .decodingBackup:                 decodingView-            case .readyToFill(let preview):-                fillPreviewView(preview)-            case .readyToReplace(let preview):-                replacePreviewView(preview)-            case .confirmingReplace(let preview):-                replaceConfirmationView(preview)+            case .readyToImport(let preview):+                previewView(preview)             case .committing:                 committingView             case .completed(let counts):@@ -74,111 +70,39 @@ struct SettingsBackupImportView: View {         .accessibilityIdentifier("settings-import-decoding")     } -    // MARK: - Fill Preview+    // MARK: - Preview -    private func fillPreviewView(_ preview: SettingsBackupImportModel.FillPreview) -> some View {+    /// One preview, one button. Import adds and updates and never deletes, so+    /// there is no destructive step to warn about and no second confirmation.+    private func previewView(_ preview: SettingsBackupImportModel.Preview) -> some View {         VStack(spacing: 16) {             VStack(alignment: .leading, spacing: 8) {-                Text("Import \(preview.importCounts.entries) entries, \(preview.importCounts.works) works?")+                Text("Restore \(preview.importCounts.entries) entries, \(preview.importCounts.works) works?")                     .font(.headline)                 Text("Exported \(preview.metadata.exportedAt.formatted(date: .abbreviated, time: .shortened))")                     .font(.caption)                     .foregroundStyle(.secondary)-            }--            HStack(spacing: 12) {-                Button("Import") {-                    Task { await model.confirmFillImport() }-                }-                .buttonStyle(.borderedProminent)-                .frame(minWidth: AsterismLayout.minHitTarget, minHeight: AsterismLayout.minHitTarget)-                .accessibilityIdentifier("settings-confirm-fill-button")--                Button("Cancel") { model.cancel() }-                    .frame(minHeight: AsterismLayout.minHitTarget)-                    .accessibilityIdentifier("settings-cancel-fill-button")-            }-        }-        .accessibilityIdentifier("settings-import-fill-preview")-    }--    // MARK: - Replace Preview--    private func replacePreviewView(_ preview: SettingsBackupImportModel.ReplacePreview) -> some View {-        VStack(spacing: 16) {-            // Warning banner (Req 1.11)-            HStack {-                Image(systemName: "exclamationmark.triangle")-                    .foregroundStyle(.orange)-                Text("Replace Library from Backup")-                    .font(.headline)-            }-            .accessibilityElement(children: .combine)-            .accessibilityLabel("Warning: Replace Library from Backup")--            VStack(alignment: .leading, spacing: 8) {-                Text("Current library: \(preview.currentCounts.entries) entries, \(preview.currentCounts.works) works")-                    .font(.subheadline)-                Text("Import: \(preview.importCounts.entries) entries, \(preview.importCounts.works) works")-                    .font(.subheadline)-                Text("Every current V3 record will be discarded. No merge occurs.")+                Text("Your library currently holds \(preview.currentCounts.entries) entries and \(preview.currentCounts.works) works. Anything this backup does not describe is left alone.")                     .font(.caption)-                    .foregroundStyle(.red)+                    .foregroundStyle(.secondary)             }             .accessibilityElement(children: .combine)-            .accessibilityLabel("Current library has \(preview.currentCounts.entries) entries and \(preview.currentCounts.works) works. Import has \(preview.importCounts.entries) entries and \(preview.importCounts.works) works. Every current record will be discarded.")--            HStack(spacing: 12) {-                Button("Replace Library…") {-                    model.proceedToReplaceConfirmation()-                }-                .buttonStyle(.borderedProminent)-                .tint(.red)-                .frame(minWidth: AsterismLayout.minHitTarget, minHeight: AsterismLayout.minHitTarget)-                .accessibilityIdentifier("settings-replace-proceed-button")--                Button("Cancel") { model.cancel() }-                    .frame(minHeight: AsterismLayout.minHitTarget)-                    .accessibilityIdentifier("settings-replace-cancel-button")-            }-        }-        .accessibilityIdentifier("settings-import-replace-preview")-    }--    // MARK: - Replace Confirmation (second step)--    private func replaceConfirmationView(_ preview: SettingsBackupImportModel.ReplacePreview) -> some View {-        VStack(spacing: 20) {-            Image(systemName: "exclamationmark.triangle.fill")-                .font(.system(size: 36))-                .foregroundStyle(.red)-                .accessibilityHidden(true)--            Text("Replace entire library?")-                .font(.headline)--            Text("This will permanently discard all \(preview.currentCounts.entries) current entries and \(preview.currentCounts.works) current works and replace them with the imported backup.")-                .font(.subheadline)-                .foregroundStyle(.secondary)-                .multilineTextAlignment(.center)-                .padding(.horizontal)+            .accessibilityLabel("This backup holds \(preview.importCounts.entries) entries and \(preview.importCounts.works) works. Your library currently holds \(preview.currentCounts.entries) entries and \(preview.currentCounts.works) works. Nothing will be deleted.")              HStack(spacing: 12) {-                Button("Replace") {-                    Task { await model.confirmReplace() }+                Button("Import") {+                    Task { await model.confirmImport() }                 }                 .buttonStyle(.borderedProminent)-                .tint(.red)                 .frame(minWidth: AsterismLayout.minHitTarget, minHeight: AsterismLayout.minHitTarget)-                .accessibilityIdentifier("settings-confirm-replace-button")-                .accessibilityLabel("Confirm destructive replacement of entire library")+                .accessibilityIdentifier("settings-confirm-import-button")                  Button("Cancel") { model.cancel() }                     .frame(minHeight: AsterismLayout.minHitTarget)-                    .accessibilityIdentifier("settings-replace-final-cancel-button")+                    .accessibilityIdentifier("settings-cancel-import-button")             }         }-        .accessibilityIdentifier("settings-import-replace-confirmation")+        .accessibilityIdentifier("settings-import-preview")     }      // MARK: - Committing@@ -201,7 +125,7 @@ struct SettingsBackupImportView: View {                     .foregroundStyle(.green)                 Text("Import complete")             }-            Text("\(counts.entries) entries, \(counts.works) works imported.")+            Text("Your library now holds \(counts.entries) entries and \(counts.works) works.")                 .font(.caption)                 .foregroundStyle(.secondary) 

diff --git a/Asterism/Asterism/Views/SettingsView.swift b/Asterism/Asterism/Views/SettingsView.swiftindex 55e66e8..e986aaa 100644--- a/Asterism/Asterism/Views/SettingsView.swift+++ b/Asterism/Asterism/Views/SettingsView.swift@@ -10,20 +10,46 @@ struct SettingsView: View {     /// diagnoses in its own `task`, so holding the model from here does not pin     /// it to the moment Settings opened.     private let diagnosticsModel: LibraryDiagnosticsModel?+    /// Req 8.1–8.5's surface, `@State`-owned like `importModel` and unlike the+    /// diagnostics model.+    ///+    /// It has to be owned, because it holds loaded state: `hasLoaded` and the two+    /// counts. The sheet's content closure builds a model on every re-render of+    /// the presenting view, and holding it as a plain `let` meant each of those+    /// replaced a loaded model with an unloaded one — while `.task(id:)` below+    /// saw an unchanged status and did not re-run. The counts and the health line+    /// then sat on their "checking…" placeholders for as long as Settings stayed+    /// open. `@State` keeps the first instance, so the load survives the renders.+    @State private var syncModel: SettingsSyncModel?+    /// Req 4.4's report, already worded by `AppLibraryModel`. A plain string+    /// rather than a model: there is nothing to load, nothing to act on here,+    /// and the one action it names — import the backup again — is the section+    /// it sits beside.+    private let interruptedImportNotice: String?      init(         model: SettingsBackupModel,         importModel: SettingsBackupImportModel? = nil,-        diagnosticsModel: LibraryDiagnosticsModel? = nil+        diagnosticsModel: LibraryDiagnosticsModel? = nil,+        syncModel: SettingsSyncModel? = nil,+        interruptedImportNotice: String? = nil     ) {         _model = State(initialValue: model)         _importModel = State(initialValue: importModel)+        _syncModel = State(initialValue: syncModel)         self.diagnosticsModel = diagnosticsModel+        self.interruptedImportNotice = interruptedImportNotice     }      var body: some View {         List {+            // Above Data: sync is the state the reader is most likely to be+            // checking, and the Data actions below read differently once it is+            // known whether anything is reaching iCloud at all.+            syncSection+             Section {+                interruptedImportRow                 backupRow                 diagnosticsRow             } header: {@@ -40,6 +66,18 @@ struct SettingsView: View {         }         .navigationTitle("Settings")         .accessibilityIdentifier("settings-view")+        // Attached to the List, not to the iCloud `Section`. With `.task` and an+        // accessibility identifier on the Section itself, none of its rows+        // appeared in the accessibility tree at all — the UI test could not find+        // a single one. Modifiers on a top-level Section are not worth the risk;+        // the section's own rows carry the identifiers.+        // Keyed on the observed status, not a bare `.task`. Settings can stay+        // open across an arrival, and the counts Req 8.5 puts beside the sync+        // lines would otherwise describe the library as it was when the sheet+        // opened while the lines above them moved (Req 8.6). Every trigger that+        // updates the status — an import event, an export event, a recorded+        // failure — re-reads the counts with it.+        .task(id: syncModel?.status) { await syncModel?.load() }         .sheet(isPresented: $showingShareSheet, onDismiss: handleShareDismiss) {             if let url = model.exportedFileURL {                 ShareSheet(fileURL: url)@@ -53,6 +91,99 @@ struct SettingsView: View {         }     } +    // MARK: - iCloud Section (Req 8.1–8.5)++    /// Every sentence here comes from the model (the `LibraryDiagnosticsModel`+    /// precedent): this view chooses rows and styling, never wording.+    @ViewBuilder+    private var syncSection: some View {+        if let syncModel {+            Section {+                Text(syncModel.lastExportLine)+                    .font(.callout)+                    .accessibilityIdentifier("settings-sync-export-line")+                Text(syncModel.lastImportLine)+                    .font(.callout)+                    .accessibilityIdentifier("settings-sync-import-line")+                Text(syncModel.observationNote)+                    .font(.caption)+                    .foregroundStyle(.secondary)+                    .accessibilityIdentifier("settings-sync-observation-note")++                if let firstSync = syncModel.firstSyncLine {+                    Text(firstSync)+                        .font(.caption)+                        .foregroundStyle(.secondary)+                        .accessibilityIdentifier("settings-sync-first-sync-line")+                }++                if let failure = syncModel.failure {+                    syncFailureRow(failure)+                }++                VStack(alignment: .leading, spacing: 4) {+                    Text(syncModel.healthLine)+                        .font(.callout)+                        .accessibilityIdentifier("settings-sync-health-line")+                    // Req 8.5: the counts are beside the sync lines whether or+                    // not they are zero, so "healthy" is never the only thing+                    // the reader has to go on.+                    Text(syncModel.countsLine)+                        .font(.caption)+                        .foregroundStyle(.secondary)+                        .accessibilityIdentifier("settings-sync-counts-line")+                }+            } header: {+                Text("iCloud")+            }+        }+    }++    private func syncFailureRow(_ failure: SettingsSyncModel.FailureLine) -> some View {+        VStack(alignment: .leading, spacing: 6) {+            HStack(alignment: .firstTextBaseline, spacing: 6) {+                Image(systemName: failure.isBannerWorthy+                    ? "exclamationmark.triangle.fill" : "exclamationmark.circle")+                    .font(.caption)+                    .foregroundStyle(failure.isBannerWorthy ? AsterismColors.amberDark : .secondary)+                    .accessibilityHidden(true)+                Text(failure.condition)+                    .font(.callout)+                    .accessibilityIdentifier("settings-sync-condition")+            }+            Text(failure.remedy)+                .font(.caption)+                .foregroundStyle(.secondary)+                .accessibilityIdentifier("settings-sync-remedy")+            Text("\(failure.observed) — \(failure.detail)")+                .font(.caption2)+                .foregroundStyle(.tertiary)+                .accessibilityIdentifier("settings-sync-detail")+        }+        .accessibilityElement(children: .combine)+    }++    // MARK: - Interrupted import (Req 4.4)++    /// Above the backup and Check Library rows, and in the section whose Import+    /// control is the repair. Shown however old the sidecar is — an import that+    /// stopped partway did not become complete by being ignored for a month.+    @ViewBuilder+    private var interruptedImportRow: some View {+        if let interruptedImportNotice {+            HStack(alignment: .firstTextBaseline, spacing: 6) {+                Image(systemName: "exclamationmark.circle")+                    .font(.caption)+                    .foregroundStyle(AsterismColors.amberDark)+                    .accessibilityHidden(true)+                Text(interruptedImportNotice)+                    .font(.callout)+            }+            .accessibilityElement(children: .combine)+            .accessibilityIdentifier("settings-interrupted-import-notice")+        }+    }+     // MARK: - Library Check Row (Req 4.2)      /// Reachable whether or not anything is diagnosed: the reader should be able

diff --git a/Asterism/AsterismTests/AppLibraryModelTests.swift b/Asterism/AsterismTests/AppLibraryModelTests.swiftindex 444f673..40f1a55 100644--- a/Asterism/AsterismTests/AppLibraryModelTests.swift+++ b/Asterism/AsterismTests/AppLibraryModelTests.swift@@ -41,6 +41,76 @@ struct AppLibraryModelTests {         try? FileManager.default.removeItem(at: root)     } +    // MARK: - Req 4.4: an import that stopped partway is reported++    @Test("A sidecar left by an interrupted import is read at bootstrap and named to the reader")+    @MainActor func interruptedImportIsReportedAtBootstrap() async throws {+        let root = FileManager.default.temporaryDirectory+            .appending(path: "asterism-interrupted-\(UUID())")+        let config = LibraryConfiguration(rootDirectory: root)+        defer { try? FileManager.default.removeItem(at: root) }+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)+        // What the repository writes before an import's first save and removes+        // after its last. Dated a month back on purpose: Req 4.4 reports the+        // interruption however old, because age does not make it untrue.+        let report = InterruptedImportReport(+            archiveName: "Asterism-backup-v4-2026-06-01.json",+            startedAt: Date(timeIntervalSince1970: 1_780_000_000))+        try JSONEncoder().encode(report).write(to: config.importSidecarURL)++        let model = AppLibraryModel(configuration: config)+        await model.bootstrap()++        #expect(model.state == .ready, "the library still opens; the import is a report")+        #expect(model.interruptedImport == report)+        let notice = try #require(model.interruptedImportNotice)+        // Both halves are required: which archive, and that it did not finish.+        #expect(notice.contains("Asterism-backup-v4-2026-06-01.json"))+        #expect(notice.localizedCaseInsensitiveContains("did not finish"))+    }++    @Test("A library with no interrupted import says nothing")+    @MainActor func noSidecarNoNotice() async {+        let root = FileManager.default.temporaryDirectory+            .appending(path: "asterism-nointerrupt-\(UUID())")+        defer { try? FileManager.default.removeItem(at: root) }+        let model = AppLibraryModel(configuration: LibraryConfiguration(rootDirectory: root))++        await model.bootstrap()++        #expect(model.interruptedImport == nil)+        #expect(model.interruptedImportNotice == nil)+    }++    @Test("Completing an import clears the notice the earlier interruption left")+    @MainActor func completedImportClearsTheNotice() async throws {+        let root = FileManager.default.temporaryDirectory+            .appending(path: "asterism-interrupted-clear-\(UUID())")+        let config = LibraryConfiguration(rootDirectory: root)+        defer { try? FileManager.default.removeItem(at: root) }+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)+        try JSONEncoder().encode(+            InterruptedImportReport(archiveName: "an earlier backup", startedAt: .distantPast)+        ).write(to: config.importSidecarURL)++        let model = AppLibraryModel(configuration: config)+        await model.bootstrap()+        #expect(model.interruptedImportNotice != nil)++        // Re-running the import is the repair, and it goes through the real+        // committer: the repository removes the sidecar as it completes, so a+        // notice left standing afterwards would describe a file that is gone.+        let archive = root.appending(path: "restore.json")+        try SettingsBackupImportModelTests.minimalV4BackupData.write(to: archive)+        let importModel = try #require(model.settingsBackupImportModel())+        await importModel.handleDocumentSelection(archive)+        await importModel.confirmImport()++        #expect(model.interruptedImport == nil)+        #expect(model.interruptedImportNotice == nil)+        #expect(!FileManager.default.fileExists(atPath: config.importSidecarURL.path))+    }+     @Test("Transitions to ready with valid temporary directory")     @MainActor func bootstrapSuccess() async {         let tmp = FileManager.default.temporaryDirectory.appending(path: "asterism-test-\(UUID())")@@ -240,6 +310,274 @@ struct AppLibraryModelDiagnosisRefreshTests {     } } +// MARK: - Sync arrivals, the launch reconcile, and the monitor's lifecycle++/// The arrival wiring (Req 1.7, 2.2, 8.6) and the once-per-launch reconcile+/// (Q45), driven through the injected-repository seam.+///+/// Nothing here mirrors: a `LibraryConfiguration` carrying a container id is+/// enough to make the model build a monitor, and the monitor opens no container+/// — it reads notifications and writes a JSON file. The `.private` construction+/// that a host cannot perform stays inside `openV4ForApp`, which these tests+/// reach only through the ordinary non-mirroring bootstrap.+@Suite("AppLibraryModel sync arrivals")+@MainActor+struct AppLibraryModelSyncArrivalTests {++    /// A fictional container id. It is not a composed identifier of either+    /// configuration, so the identity lint's literal sweep has nothing to find.+    private static let fixtureContainerID = "iCloud.example.fixture"++    /// The call sequence one arrival must produce: reconcile first, then the+    /// existing diagnosis-before-snapshots refresh.+    private static let arrivalSequence =+        ["reconcileAfterSync", "refreshDiagnostics", "recentPresentation", "works"]++    private static func mirroringConfiguration() -> LibraryConfiguration {+        LibraryConfiguration(+            rootDirectory: FileManager.default.temporaryDirectory+                .appending(path: "asterism-sync-\(UUID())"),+            cloudKitContainerID: fixtureContainerID)+    }++    // MARK: - Arrivals++    @Test("An arrival reconciles the Site graph and then re-derives what is displayed (Req 1.7, 2.2, 8.6)")+    func arrivalReconcilesThenRefreshes() async {+        let mock = MockLibraryProvider()+        let model = AppLibraryModel(readyRepository: mock)++        await model.handleSyncArrivals()++        #expect(mock.reconcileAfterSyncCallCount == 1)+        // Order, not merely occurrence: a refresh taken before reconciliation+        // would publish the pre-merge graph and Req 2.2's resolved reference+        // would keep being reported until the next foreground.+        #expect(mock.callLog == Self.arrivalSequence)+    }++    @Test("A failed reconciliation still re-derives what is displayed (Req 2.2)")+    func arrivalRefreshesEvenWhenReconciliationThrows() async {+        let mock = MockLibraryProvider()+        mock.reconcileAfterSyncResult = .failure(+            MockLibraryProvider.MockError.simulatedFailure("reconcile failed"))+        let model = AppLibraryModel(readyRepository: mock)++        await model.handleSyncArrivals()++        // Reconciliation has no user-facing errors: a failed pass leaves work at+        // a chunk boundary and the next trigger converges it. What must not+        // happen is losing the refresh — records did arrive, whatever the+        // reconciler made of them.+        #expect(mock.callLog == Self.arrivalSequence)+    }++    @Test("The monitor's arrival callback is wired to that handler")+    func monitorArrivalCallbackReachesTheHandler() async throws {+        let mock = MockLibraryProvider()+        let model = AppLibraryModel(readyRepository: mock)+        let configuration = Self.mirroringConfiguration()+        defer { try? FileManager.default.removeItem(at: configuration.rootDirectory) }++        model.startSyncObservation(configuration: configuration, mirroring: .attached(+            containerID: Self.fixtureContainerID))++        let monitor = try #require(model.syncMonitor)+        #expect(model.syncStatusSource != nil)+        // Driving the monitor's own callback, not the handler directly: the+        // wiring is the thing under test.+        await monitor.onArrivals?()+        #expect(mock.callLog == Self.arrivalSequence)+    }++    @Test("A configuration that cannot mirror builds no monitor")+    func noMonitorWithoutAContainer() {+        let model = AppLibraryModel(readyRepository: MockLibraryProvider())++        model.startSyncObservation(+            configuration: LibraryConfiguration(+                rootDirectory: FileManager.default.temporaryDirectory+                    .appending(path: "asterism-sync-\(UUID())")),+            mirroring: .notRequested)++        #expect(model.syncMonitor == nil)+        #expect(model.syncStatusSource == nil)+    }++    @Test("A failed attachment is recorded as misconfigured (Req 8.4, Q44)")+    func failedAttachmentIsRecorded() async throws {+        let model = AppLibraryModel(readyRepository: MockLibraryProvider())+        let configuration = Self.mirroringConfiguration()+        try FileManager.default.createDirectory(+            at: configuration.rootDirectory, withIntermediateDirectories: true)+        defer { try? FileManager.default.removeItem(at: configuration.rootDirectory) }++        model.startSyncObservation(configuration: configuration, mirroring: .failed(+            containerID: Self.fixtureContainerID, reason: "missing entitlement"))++        let monitor = try #require(model.syncMonitor)+        #expect(monitor.status.lastFailure?.classification == .misconfigured)+        // The library itself opened, so the app is ready and only sync degraded.+        #expect(model.state == .ready)+    }++    /// Req 8.4, refining Q52. A build with `ASTERISM_MIRRORING_ENABLED = YES`+    /// whose container id will not resolve hands the open a nil identifier, so+    /// the open reports `.notRequested` — honest about the open, wrong about the+    /// build. Read alone that is indistinguishable from mirroring being off by+    /// design, and Settings said exactly that about a broken build.+    @Test("A mirroring build whose container id will not resolve reads as misconfigured, not as off")+    func unresolvedContainerDeclarationReadsAsMisconfigured() async throws {+        let model = AppLibraryModel(+            readyRepository: MockLibraryProvider(),+            mirroringDeclarationFailure:+                "AsterismCloudKitContainerIdentifier is missing from the bundle's Info.plist")+        // No container id: the declaration failed before one could be resolved,+        // which is exactly the configuration `bootstrap` would build.+        let configuration = LibraryConfiguration(+            rootDirectory: FileManager.default.temporaryDirectory+                .appending(path: "asterism-sync-\(UUID())"))+        try FileManager.default.createDirectory(+            at: configuration.rootDirectory, withIntermediateDirectories: true)+        defer { try? FileManager.default.removeItem(at: configuration.rootDirectory) }++        model.startSyncObservation(configuration: configuration, mirroring: .notRequested)++        let monitor = try #require(model.syncMonitor, "a broken declaration must still be observed")+        #expect(monitor.status.lastFailure?.classification == .misconfigured)+        #expect(+            monitor.status.lastFailure?.message.contains("Info.plist") == true,+            "the recorded reason must name what could not be read")+        // The library opened and only sync degraded (Q44).+        #expect(model.state == .ready)++        // And Settings stops calling it off-by-design.+        #expect(model.mirroringRequested)+        let settings = try #require(model.settingsSyncModel())+        #expect(!settings.healthLine.localizedCaseInsensitiveContains("off in this build"))+        #expect(settings.failure?.condition.isEmpty == false)+    }++    @Test("A build that simply has mirroring off still builds no monitor")+    func mirroringOffStillBuildsNoMonitor() {+        // The other half of the same distinction: no container and no failure is+        // a configuration that never asked, and it must stay silent.+        let model = AppLibraryModel(readyRepository: MockLibraryProvider())++        model.startSyncObservation(+            configuration: LibraryConfiguration(+                rootDirectory: FileManager.default.temporaryDirectory+                    .appending(path: "asterism-sync-\(UUID())")),+            mirroring: .notRequested)++        #expect(model.syncMonitor == nil)+        #expect(!model.mirroringRequested)+    }++    @Test("Teardown stops the monitor and forgets it")+    func teardownStopsTheMonitor() async {+        let mock = MockLibraryProvider()+        let model = AppLibraryModel(readyRepository: mock)+        let configuration = Self.mirroringConfiguration()+        defer { try? FileManager.default.removeItem(at: configuration.rootDirectory) }+        model.startSyncObservation(configuration: configuration, mirroring: .attached(+            containerID: Self.fixtureContainerID))+        #expect(model.syncMonitor != nil)++        // A re-bootstrap tears the previous repository down first (Q43). The+        // monitor observes a container that is about to be released, so it has+        // to go with it — this model has no identifier to resolve, so the+        // bootstrap goes no further than the teardown.+        await model.bootstrap()++        #expect(model.syncMonitor == nil)+        #expect(model.syncStatusSource == nil)+    }++    // MARK: - The launch reconcile (Q45)++    @Test("The launch reconcile runs once per launch and skips the refresh when it changed nothing")+    func launchReconcileRunsOnceAndSkipsAnEmptyPass() async {+        let mock = MockLibraryProvider()+        let model = AppLibraryModel(readyRepository: mock)++        await model.runLaunchReconcile()+        await model.runLaunchReconcile()++        #expect(mock.reconcileAfterSyncCallCount == 1)+        // The open published Recent moments before; re-reading it for a pass+        // that wrote nothing would repeat the open's work for no change.+        #expect(mock.callLog == ["reconcileAfterSync"])+        #expect(model.launchReconcileCompleted)+    }++    @Test("A launch reconcile that consolidated something re-derives what is displayed")+    func launchReconcileRefreshesAfterRealWork() async {+        let mock = MockLibraryProvider()+        var outcome = SiteReconciliationOutcome()+        outcome.consolidatedHostnames = ["example.test"]+        outcome.repinnedRecords = 3+        mock.reconcileAfterSyncResult = .success(outcome)+        let model = AppLibraryModel(readyRepository: mock)++        await model.runLaunchReconcile()++        #expect(mock.callLog == Self.arrivalSequence)+    }++    @Test("The launch reconcile fires after the open publishes Recent, never inside it (Q45, Req 6.4)")+    func launchReconcileFollowsTheOpen() async {+        let root = FileManager.default.temporaryDirectory+            .appending(path: "asterism-launch-reconcile-\(UUID())")+        let model = AppLibraryModel(configuration: LibraryConfiguration(rootDirectory: root))+        defer { try? FileManager.default.removeItem(at: root) }++        await model.bootstrap()++        // Ready, with Recent published, and the reconcile has not run: the open+        // does not pay for it, and nothing waits on it (Req 6.4). The pass+        // cannot have completed here — its first step is a call into the+        // repository actor, which suspends.+        #expect(model.state == .ready)+        #expect(!model.launchReconcileCompleted)++        await model.waitForLaunchReconcile()++        #expect(model.launchReconcileCompleted)+        #expect(model.state == .ready)+    }++    // MARK: - Import exclusion (Q46)++    @Test("An arrival during an import is forwarded for the repository to defer (Q46)")+    func arrivalDuringImportIsForwardedNotDropped() async throws {+        let mock = MockLibraryProvider()+        mock.confirmImportResult = .success(.committed(.zero))+        let model = AppLibraryModel(readyRepository: mock)+        // The arrival lands between the import's chunk saves — the window the+        // repository's bulk-operation flag exists for. The deferral and its+        // re-fire are the repository's (`BackupImportTransactionTests`); what is+        // asserted here is that the model neither gates nor drops the trigger,+        // and does not block the import on it.+        mock.onConfirmImport = { [model] in await model.handleSyncArrivals() }++        _ = try await mock.confirmImport(+            plan: BackupImportV4Plan(+                metadata: BackupImportMetadata(+                    formatVersion: 4, schemaVersion: 4, appBuild: "test",+                    exportedAt: .now, capabilityGate: "m4", entryCount: 0, workCount: 0),+                payload: BackupV4Payload(+                    entries: [], works: [], sites: [], titlePatterns: [], urlRules: []),+                counts: .zero),+            archiveName: "arrivals.json")++        #expect(mock.reconcileAfterSyncCallCount == 1)+        #expect(mock.confirmImportCallCount == 1)+        #expect(mock.callLog.contains("confirmImport"))+        #expect(mock.callLog.contains("reconcileAfterSync"))+    }+}+ // MARK: - Test helpers  private struct FailingLocator: SharedContainerLocating {

diff --git a/Asterism/AsterismTests/AsterismTests.swift b/Asterism/AsterismTests/AsterismTests.swiftindex 0c952d0..80cd3df 100644--- a/Asterism/AsterismTests/AsterismTests.swift+++ b/Asterism/AsterismTests/AsterismTests.swift@@ -30,8 +30,7 @@ struct AsterismTests {         #expect(appGroup.hasPrefix("group."))         #expect(appGroup.hasSuffix(".dev"), "The hosted app is the Development configuration") -        let container = Bundle.main.object(forInfoDictionaryKey: "AsterismCloudKitContainerIdentifier") as? String-        let resolvedContainer = try #require(container, "AsterismCloudKitContainerIdentifier is missing")+        let resolvedContainer = try LibraryConfiguration.declaredCloudKitContainerIdentifier(in: .main)         #expect(!resolvedContainer.isEmpty)         #expect(!resolvedContainer.contains("$("), "The build setting was not expanded")         #expect(resolvedContainer.hasPrefix("iCloud."))@@ -41,4 +40,27 @@ struct AsterismTests {         // container — the failure this spec exists to prevent — breaks this.         #expect(resolvedContainer.dropFirst("iCloud.".count) == appGroup.dropFirst("group.".count))     }++    /// The mirroring gate, end to end through a real build (Q51).+    ///+    /// The flag is a declared per-configuration build setting like the+    /// identifiers, so the same thing can go wrong with it: an unexpanded+    /// reference reaching the product, or a key that never made it into the+    /// merged Info.plist. Read by shape rather than by value, and asserted+    /// *on* since task 26 flipped Development: unit tests only ever run under+    /// Development (Personal has no testability), so the hosted value is that+    /// configuration's. Personal stays NO until task 27; `verify-identity`+    /// lints both declarations.+    @Test("The hosted app's bundle declares the mirroring gate, on for Development")+    func bundleDeclaresMirroringGate() throws {+        let raw = Bundle.main.object(forInfoDictionaryKey: LibraryConfiguration.mirroringEnabledInfoPlistKey)+        let declared = try #require(raw as? String, "\(LibraryConfiguration.mirroringEnabledInfoPlistKey) is missing")+        #expect(!declared.contains("$("), "The build setting was not expanded")+        #expect(declared == "YES", "Task 26 enabled mirroring for the Development configuration")++        #expect(LibraryConfiguration.declaredMirroringEnabled(in: .main) == true)+        // The gate is on, so the container identifier the app would inject must+        // resolve — an unresolvable identifier here is the misconfigured state.+        #expect(try LibraryConfiguration.declaredMirroringContainerIdentifier(in: .main) != nil)+    } }

diff --git a/Asterism/AsterismTests/EntryDetailModelTests.swift b/Asterism/AsterismTests/EntryDetailModelTests.swiftindex 263f043..f5b9179 100644--- a/Asterism/AsterismTests/EntryDetailModelTests.swift+++ b/Asterism/AsterismTests/EntryDetailModelTests.swift@@ -142,6 +142,71 @@ struct EntryDetailModelTests {         #expect(model.errorMessage != nil)     } +    // MARK: - Why there is no entry to show++    /// The runbook's click-through, and the reason this is a bug rather than a+    /// wording preference: the stale diagnosis raised Recent's banner, the reader+    /// tapped the row it labelled, and the detail screen told them the entry had+    /// been removed. The entry was there the whole time; its site's rules were+    /// the thing that was not valid, and the app repairs that on its own.+    @Test("A quarantined site is reported as invalid rules, not as a deleted entry")+    @MainActor func quarantinedSiteIsNotReportedAsDeleted() async {+        let (model, mock, _) = makeSUT()+        mock.entryTeachingDetailResult = .failure(+            LibraryRepositoryError.quarantined(+                hostname: "jeconais.fanficauthors.net",+                reason: "Taught Site must retain exactly one active title pattern"))++        await model.load()++        #expect(model.entry == nil)+        #expect(model.unavailability == .siteRulesInvalid)+        // The same sentence Recent uses for the same cause, so one condition does+        // not read as two different things on two screens.+        #expect(model.unavailability.message.contains("This site's saved rules are not valid"))+        #expect(model.unavailability.message.lowercased().contains("automatic"))+        #expect(model.unavailability.title != "Entry deleted")+    }++    @Test("An entry that no longer exists still reports as deleted")+    @MainActor func missingEntryIsReportedAsDeleted() async {+        let (model, mock, _) = makeSUT()+        mock.entryTeachingDetailResult = .failure(+            LibraryRepositoryError.recordNotFound(type: "Entry", id: UUID()))++        await model.load()++        #expect(model.entry == nil)+        #expect(model.unavailability == .deleted)+        #expect(model.unavailability.title == "Entry deleted")+    }++    /// Every other failure leaves the Entry row in the store, so "removed" is a+    /// claim the app cannot make. The reason is carried through instead.+    @Test("A load that failed for any other reason does not claim a deletion")+    @MainActor func otherFailuresDoNotClaimDeletion() async {+        let (model, mock, _) = makeSUT()+        mock.entryTeachingDetailResult = .failure(+            LibraryRepositoryError.libraryBusy(operation: "building entry teaching detail"))++        await model.load()++        #expect(model.entry == nil)+        #expect(model.unavailability != .deleted)+        #expect(model.unavailability.title != "Entry deleted")+    }++    @Test("A delete the reader asked for still reports as deleted")+    @MainActor func deleteReportsAsDeleted() async {+        let (model, _, _) = makeSUT()+        await model.load()++        await model.delete()++        #expect(model.entry == nil)+        #expect(model.unavailability == .deleted)+    }+     @Test("Duplicate submission is suppressed")     @MainActor func duplicateSubmissionSuppressed() async {         let (model, mock, _) = makeSUT()

diff --git a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swiftindex b6d52da..e0c7fc6 100644--- a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift+++ b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift@@ -187,6 +187,53 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable {         try refreshDiagnosticsResult.get()     } +    var debugCountsResult: Result<LibraryRecordCounts, Error> = .success(.zero)++    func debugCounts() async throws -> LibraryRecordCounts {+        callLog.append("debugCounts")+        return try debugCountsResult.get()+    }++    var confirmImportCallCount = 0+    var lastConfirmImportArchiveName: String?+    var confirmImportResult: Result<BackupImportCommitResult, Error> = .failure(+        MockError.notConfigured)+    /// Runs *inside* the import, so a test can make something else happen while+    /// it is in flight — Q46's window, where a sync arrival must be forwarded+    /// for the repository to defer rather than dropped or awaited.+    var onConfirmImport: (@Sendable () async -> Void)?++    @discardableResult+    func confirmImport(+        plan: BackupImportV4Plan, archiveName: String?+    ) async throws -> BackupImportCommitResult {+        confirmImportCallCount += 1+        lastConfirmImportArchiveName = archiveName+        callLog.append("confirmImport")+        await onConfirmImport?()+        return try confirmImportResult.get()+    }++    var interruptedImportReport: InterruptedImportReport?+    var interruptedImportCallCount = 0++    func interruptedImport() async -> InterruptedImportReport? {+        interruptedImportCallCount += 1+        callLog.append("interruptedImport")+        return interruptedImportReport+    }++    var reconcileAfterSyncCallCount = 0+    var reconcileAfterSyncResult: Result<SiteReconciliationOutcome, Error> = .success(+        SiteReconciliationOutcome())++    @discardableResult+    func reconcileAfterSync() async throws -> SiteReconciliationOutcome {+        reconcileAfterSyncCallCount += 1+        callLog.append("reconcileAfterSync")+        return try reconcileAfterSyncResult.get()+    }+     func projectInitialTeaching(hostname: String, patternDefinition: PatternDefinition) async throws -> TeachingContract {         projectInitialTeachingCallCount += 1         return try projectInitialTeachingResult.get()

diff --git a/Asterism/AsterismTests/IntegrationSafetyNetTests.swift b/Asterism/AsterismTests/IntegrationSafetyNetTests.swiftindex 4d69586..7941f44 100644--- a/Asterism/AsterismTests/IntegrationSafetyNetTests.swift+++ b/Asterism/AsterismTests/IntegrationSafetyNetTests.swift@@ -311,10 +311,8 @@ struct IntegrationSafetyNetTests {         let (targetOpenResult, _) = try await LibraryRepository.openV4ForApp(targetConfig)         #expect(targetOpenResult == .ready(.zero)) -        let fillResult = try await LibraryRepository.confirmImportFillEmpty(-            targetConfig,-            plan: plan-        )+        let (_, targetRepo) = try await LibraryRepository.openV4ForApp(targetConfig)+        let fillResult = try await targetRepo.confirmImport(plan: plan)         guard case .committed(let counts) = fillResult else {             Issue.record("Expected committed fill, got \(fillResult)")             return@@ -331,69 +329,56 @@ struct IntegrationSafetyNetTests {         #expect(observed.workID == work.id)     } -    @Test("Destructive backup replace preserves import data and discards current graph")-    func backupV3DestructiveReplace() async throws {+    /// Decision 2, end to end. Restoring into a populated library used to discard+    /// every current record; under mirroring each of those deletions exports and+    /// destroys the same records on every other device. So the assertion is+    /// inverted: what the archive does not describe survives.+    @Test("Restoring into a populated library adds the archive without discarding anything")+    func backupImportAddsWithoutDiscarding() async throws {         let fixture = try IntegrationFixture()         defer { fixture.cleanup() }         let config = fixture.developmentConfiguration -        // Create a populated library with existing data         let repo = try await openV3AppRepository(config)         let existing = try await repo.capture(             CaptureDraft(-                captureTitle: "Existing chapter to discard",+                captureTitle: "Existing chapter to keep",                 captureTitleSource: .manual,-                rawURLString: "https://discard.test/old"+                rawURLString: "https://keep.test/old"             )         ) -        // Build a different import from the personal configuration+        // A different library's archive.         let sourceConfig = fixture.personalConfiguration         let sourceRepo = try await openV3AppRepository(sourceConfig)         let imported = try await sourceRepo.capture(             CaptureDraft(-                captureTitle: "Replacement chapter",+                captureTitle: "Restored chapter",                 captureTitleSource: .manual,-                rawURLString: "https://replace.test/new",-                note: "Replacement note"+                rawURLString: "https://restore.test/new",+                note: "Restored note"             )         )-        let stagingDir = fixture.baseDirectory.appending(path: "replace-stage")+        let stagingDir = fixture.baseDirectory.appending(path: "restore-stage")         let exporter = BackupV4Exporter(repository: sourceRepo, stagingDirectory: stagingDir)         let exportResult = try await exporter.export(-            metadata: BackupV4Metadata(appBuild: "replace-test", exportedAt: Date())+            metadata: BackupV4Metadata(appBuild: "restore-test", exportedAt: Date())         )         defer { exporter.cleanup(exportResult) }-        let backupData = try Data(contentsOf: exportResult.fileURL)-        let plan = try BackupImporter.planV4(from: backupData)+        let plan = try BackupImporter.planV4(from: try Data(contentsOf: exportResult.fileURL)) -        // Get current inventory fingerprint for stale check-        let fingerprint = try await LibraryRepository.computeInventoryFingerprint(-            configuration: config-        )--        // Perform destructive replace-        let replaceResult = try await LibraryRepository.confirmImportReplace(-            config,-            plan: plan,-            expectedInventory: fingerprint-        )-        guard case .committed(let counts) = replaceResult else {-            Issue.record("Expected committed replace, got \(replaceResult)")+        let result = try await repo.confirmImport(plan: plan)+        guard case .committed(let counts) = result else {+            Issue.record("Expected committed, got \(result)")             return         }-        #expect(counts.entries == 1)+        #expect(counts.entries == 2) -        // Old data is gone, new data present-        let freshRepo = try await openV3AppRepository(config)-        do {-            _ = try await freshRepo.entry(id: existing.id)-            Issue.record("Old entry should be gone after replace")-        } catch {-            // Expected: record not found-        }-        let observedNew = try await freshRepo.entry(id: imported.id)-        #expect(observedNew.note == "Replacement note")+        // Req 4.2: both records are there afterwards.+        let observedExisting = try await repo.entry(id: existing.id)+        #expect(observedExisting.captureTitle == "Existing chapter to keep")+        let observedNew = try await repo.entry(id: imported.id)+        #expect(observedNew.note == "Restored note")     }      // MARK: - URL Teaching cross-target (Reqs 2.1–2.13, 3.1–3.7)

diff --git a/Asterism/AsterismTests/LibraryDiagnosticsModelTests.swift b/Asterism/AsterismTests/LibraryDiagnosticsModelTests.swiftindex cd20e75..69f401f 100644--- a/Asterism/AsterismTests/LibraryDiagnosticsModelTests.swift+++ b/Asterism/AsterismTests/LibraryDiagnosticsModelTests.swift@@ -75,8 +75,8 @@ struct LibraryDiagnosticsModelTests {         #expect(!row.resolution.localizedCaseInsensitiveContains("cannot"))     } -    @Test("A duplicateSiteRows row states plainly that re-teaching cannot clear it")-    func duplicateSiteRowsStatesReteachCannotClear() async throws {+    @Test("A duplicateSiteRows row reads as informational, with nothing for the reader to do")+    func duplicateSiteRowsReadsAsInformational() async throws {         let (model, _) = Self.model(             Self.diagnostics(tolerated: [.duplicateSiteRows(hostname: "dup.test", rowCount: 2)]))         await model.load()@@ -85,11 +85,16 @@ struct LibraryDiagnosticsModelTests {         #expect(row.site == "dup.test")         #expect(row.recordCount == 2)         #expect(row.recordCountText.contains("2"))-        // Req 3.4: no route, and the reason is said rather than implied by silence.+        // Q36: the app consolidates these itself, so this row carries no route and+        // must not be worded as damage. The emptied copies are kept rather than+        // deleted (Decision 6), so the row stays visible after the repair and+        // "cannot" would read as a standing failure.         #expect(row.reteachHostname == nil)-        #expect(row.resolution.localizedCaseInsensitiveContains("re-teach"))-        #expect(row.resolution.localizedCaseInsensitiveContains("cannot"))-        // The problem must name what is unresolvable, not just that something is.+        #expect(!row.resolution.localizedCaseInsensitiveContains("cannot"))+        #expect(row.resolution.localizedCaseInsensitiveContains("nothing to do"))+        // Teaching the site still works, and the row says so (Q39).+        #expect(row.resolution.localizedCaseInsensitiveContains("teaching"))+        // The problem still names the state.         #expect(row.problem.localizedCaseInsensitiveContains("more than once")             || row.problem.contains("2"))     }

diff --git a/Asterism/AsterismTests/RecentSyncPresentationTests.swift b/Asterism/AsterismTests/RecentSyncPresentationTests.swiftnew file mode 100644index 0000000..7f12da7--- /dev/null+++ b/Asterism/AsterismTests/RecentSyncPresentationTests.swift@@ -0,0 +1,149 @@+import AsterismCore+import Foundation+import Testing+@testable import Asterism++/// Tests for what Recent renders about sync (task 22, Req 6.5, 8.2, 8.3, 8.6).+///+/// Recent shows two things and they are independent: a banner for the failures+/// the reader can do something about, and — while the library is empty and+/// nothing has ever arrived — an "arriving from iCloud" empty state instead of a+/// settled one. Both are derived here rather than in the view, so the decisions+/// are testable without rendering; `RecentView` only chooses styling.+///+/// The line that matters most is the banner's: **actionable only**. A persisted+/// status record turning `.serverRecordChanged` or an entitlement mistake into a+/// standing alarm on the reader's main screen is exactly what Q11 and Q42 refuse.+@Suite("RecentSyncPresentation")+struct RecentSyncPresentationTests {++    // MARK: - Fixtures++    private static func status(+        _ classification: SyncFailureClassification?,+        eventType: SyncEventType = .exportEvent,+        hasEverImported: Bool = false+    ) -> SyncStatusRecord {+        SyncStatusRecord(+            lastImportCompleted: hasEverImported ? Date() : nil,+            hasEverImported: hasEverImported,+            lastFailure: classification.map {+                SyncFailureRecord(+                    classification: $0,+                    eventType: eventType,+                    date: Date(timeIntervalSince1970: 1_700_000_000),+                    message: "the underlying error's own words")+            })+    }++    private static func presentation(+        _ classification: SyncFailureClassification?,+        hasEverImported: Bool = false,+        mirroringRequested: Bool = true+    ) -> RecentSyncPresentation {+        RecentSyncPresentation(+            status: status(classification, hasEverImported: hasEverImported),+            mirroringRequested: mirroringRequested)+    }++    // MARK: - Banner visibility (Req 8.2, 8.3)++    @Test("Every actionable condition raises the banner and says which one it is")+    func actionableConditionsRaiseTheBanner() throws {+        var messages: Set<String> = []+        for condition: SyncActionableCondition in [.signedOut, .storageFull, .restricted] {+            let presentation = Self.presentation(.actionable(condition))+            let message = try #require(+                presentation.bannerMessage, "\(condition) is banner-worthy")+            #expect(!message.isEmpty)+            messages.insert(message)+        }+        // Three conditions, three remedies, three sentences: a shared one would+        // send the reader to Settings without saying what for.+        #expect(messages.count == 3)+    }++    @Test("No failure at all raises nothing")+    func noFailureRaisesNothing() {+        #expect(Self.presentation(nil).bannerMessage == nil)+    }++    @Test("Transient, self-healing, misconfigured and terminal failures stay off the banner")+    func nonActionableClassesStayOffTheBanner() {+        for classification: SyncFailureClassification in [+            .transient, .selfHealing, .misconfigured, .terminal,+        ] {+            #expect(+                Self.presentation(classification).bannerMessage == nil,+                "\(classification) must not reach Recent")+        }+    }++    @Test("A build that does not mirror raises no banner, whatever an old status file says")+    func nonMirroringBuildRaisesNothing() {+        // The status file outlives the flag: a library that mirrored under one+        // build can be opened by one that does not, and the stale failure is not+        // a live condition to alarm about.+        let presentation = Self.presentation(+            .actionable(.signedOut), mirroringRequested: false)+        #expect(presentation.bannerMessage == nil)+        #expect(!presentation.isAwaitingFirstSync)+    }++    // MARK: - First-sync empty state (Req 6.5)++    @Test("A mirroring device that has never imported is still arriving")+    func neverImportedDeviceIsStillArriving() {+        #expect(Self.presentation(nil).isAwaitingFirstSync)+    }++    @Test("One completed import settles the library for good")+    func oneImportSettlesTheLibrary() {+        // `hasEverImported` latches, so an empty library that has imported once+        // is genuinely empty rather than still filling.+        #expect(!Self.presentation(nil, hasEverImported: true).isAwaitingFirstSync)+    }++    @Test("A failed attachment is not presented as a library on its way")+    func misconfiguredAttachmentIsNotArriving() {+        // Nothing is arriving through a container the app could not open (Q44),+        // so promising the reader that it is would be a lie the app can detect.+        #expect(!Self.presentation(.misconfigured).isAwaitingFirstSync)+    }++    @Test("A transient failure during the first sync does not settle the library")+    func transientFailureLeavesTheDeviceArriving() {+        let presentation = Self.presentation(.transient)+        #expect(presentation.isAwaitingFirstSync)+        #expect(presentation.bannerMessage == nil)+    }++    // MARK: - The two are independent (banners render above the empty branch)++    @Test("An actionable failure while the library is still arriving produces both")+    func bannerAndFirstSyncStateCoexist() throws {+        let presentation = Self.presentation(.actionable(.signedOut))+        // RecentView renders the banner region above the empty branch, so the+        // one state where a reader most needs to be told about a sign-out — a+        // new device with nothing on it — is not the state that hides it.+        #expect(try #require(presentation.bannerMessage).localizedCaseInsensitiveContains("signed out"))+        #expect(presentation.isAwaitingFirstSync)+    }++    // MARK: - Liveness (Req 8.6)++    @Test("The presentation is derived from the status, so a changed status changes it")+    func presentationFollowsTheStatus() {+        let arriving = Self.presentation(nil)+        let signedOut = Self.presentation(.actionable(.signedOut))+        let settled = Self.presentation(nil, hasEverImported: true)++        // A pure function of the record: `AppLibraryModel` recomputes it on every+        // read, and the monitor's status is observable, so Recent moves without+        // a relaunch.+        #expect(arriving != signedOut)+        #expect(arriving != settled)+        #expect(RecentSyncPresentation.inactive.bannerMessage == nil)+        #expect(!RecentSyncPresentation.inactive.isAwaitingFirstSync)+    }+}

diff --git a/Asterism/AsterismTests/SettingsImportTests.swift b/Asterism/AsterismTests/SettingsImportTests.swiftindex a2e43d0..89fc980 100644--- a/Asterism/AsterismTests/SettingsImportTests.swift+++ b/Asterism/AsterismTests/SettingsImportTests.swift@@ -20,45 +20,28 @@ final class MockBackupDocumentReader: BackupDocumentReading, @unchecked Sendable // MARK: - Mock Import Committer  final class MockBackupImportCommitter: BackupImportCommitting, @unchecked Sendable {-    var confirmFillEmptyCallCount = 0-    var confirmReplaceCallCount = 0-    var computeFingerprintCallCount = 0--    var lastFillPlan: BackupImportV4Plan?-    var lastReplacePlan: BackupImportV4Plan?-    var lastReplaceInventory: LibraryInventoryFingerprint?--    var confirmFillEmptyResult: Result<BackupImportCommitResult, Error> = .failure(MockSetupError.notConfigured)-    var confirmReplaceResult: Result<BackupImportCommitResult, Error> = .failure(MockSetupError.notConfigured)-    var computeFingerprintResult: Result<LibraryInventoryFingerprint, Error> = .failure(MockSetupError.notConfigured)--    func confirmImportFillEmpty(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        capabilities: AsterismCapabilities-    ) async throws -> BackupImportCommitResult {-        confirmFillEmptyCallCount += 1-        lastFillPlan = plan-        return try confirmFillEmptyResult.get()-    }+    var confirmImportCallCount = 0+    var currentCountsCallCount = 0 -    func confirmImportReplace(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        expectedInventory: LibraryInventoryFingerprint,-        capabilities: AsterismCapabilities-    ) async throws -> BackupImportCommitResult {-        confirmReplaceCallCount += 1-        lastReplacePlan = plan-        lastReplaceInventory = expectedInventory-        return try confirmReplaceResult.get()+    var lastPlan: BackupImportV4Plan?+    var lastArchiveName: String?++    var confirmImportResult: Result<BackupImportCommitResult, Error> = .failure(+        MockSetupError.notConfigured)+    var currentCountsResult: Result<LibraryRecordCounts, Error> = .success(.zero)++    func currentCounts() async throws -> LibraryRecordCounts {+        currentCountsCallCount += 1+        return try currentCountsResult.get()     } -    func computeInventoryFingerprint(-        configuration: LibraryConfiguration-    ) async throws -> LibraryInventoryFingerprint {-        computeFingerprintCallCount += 1-        return try computeFingerprintResult.get()+    func confirmImport(+        plan: BackupImportV4Plan, archiveName: String?+    ) async throws -> BackupImportCommitResult {+        confirmImportCallCount += 1+        lastPlan = plan+        lastArchiveName = archiveName+        return try confirmImportResult.get()     } } @@ -74,36 +57,55 @@ enum MockSetupError: Error, LocalizedError {     } } -// MARK: - Minimal valid backup data for planning tests--/// Creates minimal valid V3 backup JSON data that passes BackupImporter.plan().-private func makeMinimalV3BackupData(-    entries: Int = 1,-    works: Int = 1-) -> Data {-    // We need real valid data that BackupImporter.plan can process.-    // For now, use a stub approach: the committer mock is what matters for model tests.-    // The actual parsing is tested at the Core layer. Here we test the model state machine.-    Data()-}- // MARK: - SettingsBackupImportModel Tests  @Suite("SettingsBackupImportModel") struct SettingsBackupImportModelTests { -    private func makeConfiguration() -> LibraryConfiguration {-        LibraryConfiguration(-            rootDirectory: URL(filePath: "/tmp/test-settings-import-\(UUID())")-        )-    }+    /// A real 4/4 document, because the model plans the bytes it is handed —+    /// stubbing the planner would leave the preview untested.+    static let minimalV4BackupData: Data = {+        let hostname = "settings-import.example"+        let rawURL = "https://\(hostname)/read?chapter=1"+        let noProvenance = try! FieldProvenance(kind: .none)+        let payload = BackupV4Payload(+            entries: [+                BackupV4Entry(+                    id: UUID(), captureTitle: "Chapter 1", captureTitleSource: .host,+                    rawURL: rawURL, canonicalURL: nil, hostname: hostname,+                    entryIdentityKey: rawURL, identityKeyVersion: 1,+                    conservativeIdentityKey: rawURL, identityBasis: .conservative,+                    identityURLRuleID: nil, identityURLRuleVersion: nil,+                    identityNameTitleRuleID: nil, identityNameTitleRuleVersion: nil,+                    urlWorkIdentity: nil, urlWorkRuleID: nil, urlWorkRuleVersion: nil,+                    chapterSequence: nil, chapterSequenceRuleID: nil,+                    chapterSequenceRuleVersion: nil, chapterTitle: nil,+                    chapterTitleProvenance: noProvenance, note: "", rating: nil,+                    firstCapturedAt: Date(timeIntervalSince1970: 1_800_000_000),+                    lastSharedAt: Date(timeIntervalSince1970: 1_800_000_000),+                    modifiedAt: Date(timeIntervalSince1970: 1_800_000_000),+                    workID: nil, workAssignmentProvenance: noProvenance,+                    workURLRuleID: nil, workURLRuleVersion: nil, workURLAssignmentKind: nil,+                    workPatternID: nil, workPatternVersion: nil, intentionallyUnattached: false)+            ],+            works: [],+            sites: [+                BackupV4Site(+                    hostname: hostname, displayName: hostname, mode: .untaught,+                    patternIDs: [], urlRuleIDs: [], junkSuffixRule: nil)+            ],+            titlePatterns: [], urlRules: [])+        return try! BackupV4Codec.encode(+            payload: payload,+            metadata: BackupV4Metadata(+                appBuild: "test", exportedAt: Date(timeIntervalSince1970: 1_800_000_000)))+    }()      // MARK: - Initial State      @Test("Starts in idle state")     @MainActor func initialState() {         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: MockBackupDocumentReader(),             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -116,7 +118,6 @@ struct SettingsBackupImportModelTests {     @Test("Begin import transitions to pickingDocument")     @MainActor func beginImport() {         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: MockBackupDocumentReader(),             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -129,7 +130,6 @@ struct SettingsBackupImportModelTests {     @MainActor func pickerCancellation() {         let committer = MockBackupImportCommitter()         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: MockBackupDocumentReader(),             committer: committer,             onCompletion: {}@@ -138,8 +138,7 @@ struct SettingsBackupImportModelTests {         model.handlePickerCancellation()          #expect(model.state == .idle)-        #expect(committer.confirmFillEmptyCallCount == 0)-        #expect(committer.confirmReplaceCallCount == 0)+        #expect(committer.confirmImportCallCount == 0)     }      // MARK: - Document Selection: Validation Errors@@ -150,7 +149,6 @@ struct SettingsBackupImportModelTests {         reader.readDataResult = .failure(BackupDocumentError.securityScopeAccessDenied(url: URL(filePath: "/f")))          let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: reader,             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -171,7 +169,6 @@ struct SettingsBackupImportModelTests {         reader.readDataResult = .success(Data("garbage".utf8))          let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: reader,             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -186,39 +183,48 @@ struct SettingsBackupImportModelTests {         }     } -    // MARK: - Destructive Replacement Flow--    @Test("Proceed to replace confirmation transitions correctly")-    @MainActor func proceedToReplaceConfirmation() {-        let _ = SettingsBackupImportModel.ReplacePreview(-            metadata: BackupImportMetadata(-                formatVersion: 3, schemaVersion: 3, appBuild: "1",-                exportedAt: Date(), capabilityGate: "m3", entryCount: 5, workCount: 2-            ),-            importCounts: LibraryRecordCounts(entries: 5, works: 2, sites: 1, titlePatterns: 0),-            currentCounts: LibraryRecordCounts(entries: 10, works: 3, sites: 2, titlePatterns: 1),-            inventory: LibraryInventoryFingerprint(-                counts: LibraryRecordCounts(entries: 10, works: 3, sites: 2, titlePatterns: 1),-                entitySignature: "test-sig"-            )-        )--        let committer = MockBackupImportCommitter()-        let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),-            documentReader: MockBackupDocumentReader(),-            committer: committer,-            onCompletion: {}-        )--        // Manually set state to readyToReplace for unit testing the state machine-        // In production this happens after handleDocumentSelection-        // We test the state machine transitions here-        // Note: We can't directly set state, so we test the flow through the committer--        // Test cancel from idle-        model.cancel()-        #expect(model.state == .idle)+    // MARK: - The single flow (Q37)++    /// The fill-empty/replace distinction is gone with the destructive path that+    /// motivated it. There is one preview and one confirm, whatever the library+    /// already holds — filling an empty library is the degenerate upsert.+    @Test("A nonempty library gets the same preview and the same confirm as an empty one")+    @MainActor func oneFlowWhateverTheLibraryHolds() async {+        for current in [LibraryRecordCounts.zero,+                        LibraryRecordCounts(entries: 10, works: 3, sites: 2, titlePatterns: 1)] {+            let reader = MockBackupDocumentReader()+            reader.readDataResult = .success(Self.minimalV4BackupData)+            let committer = MockBackupImportCommitter()+            committer.currentCountsResult = .success(current)+            committer.confirmImportResult = .success(+                .committed(LibraryRecordCounts(entries: 1, works: 0, sites: 1, titlePatterns: 0)))+            var completed = false+            let model = SettingsBackupImportModel(+                documentReader: reader, committer: committer,+                onCompletion: { completed = true })++            model.beginImport()+            await model.handleDocumentSelection(URL(filePath: "/tmp/my-backup.json"))++            guard case .readyToImport(let preview) = model.state else {+                Issue.record("Expected readyToImport, got \(model.state)")+                return+            }+            #expect(preview.currentCounts == current)++            await model.confirmImport()++            #expect(committer.confirmImportCallCount == 1)+            // The archive's own file name reaches the sidecar, so an interrupted+            // import can name what it was applying (Req 4.4).+            #expect(committer.lastArchiveName == "my-backup.json")+            guard case .completed = model.state else {+                Issue.record("Expected completed, got \(model.state)")+                return+            }+            // Completion refreshes; it does not re-bootstrap (Q43).+            #expect(completed)+        }     }      // MARK: - Cancel and Retry@@ -226,7 +232,6 @@ struct SettingsBackupImportModelTests {     @Test("Cancel returns to idle")     @MainActor func cancelReturnsToIdle() {         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: MockBackupDocumentReader(),             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -242,7 +247,6 @@ struct SettingsBackupImportModelTests {         reader.readDataResult = .failure(BackupDocumentError.emptyFile(url: URL(filePath: "/f")))          let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: reader,             committer: MockBackupImportCommitter(),             onCompletion: {}@@ -267,7 +271,6 @@ struct SettingsBackupImportModelTests {          let committer = MockBackupImportCommitter()         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: reader,             committer: committer,             onCompletion: {}@@ -275,8 +278,7 @@ struct SettingsBackupImportModelTests {         model.beginImport()         await model.handleDocumentSelection(URL(filePath: "/f")) -        #expect(committer.confirmFillEmptyCallCount == 0)-        #expect(committer.confirmReplaceCallCount == 0)+        #expect(committer.confirmImportCallCount == 0)     }      @Test("No Core commit calls made when planning fails")@@ -286,7 +288,6 @@ struct SettingsBackupImportModelTests {          let committer = MockBackupImportCommitter()         let model = SettingsBackupImportModel(-            configuration: makeConfiguration(),             documentReader: reader,             committer: committer,             onCompletion: {}@@ -294,8 +295,7 @@ struct SettingsBackupImportModelTests {         model.beginImport()         await model.handleDocumentSelection(URL(filePath: "/f")) -        #expect(committer.confirmFillEmptyCallCount == 0)-        #expect(committer.confirmReplaceCallCount == 0)+        #expect(committer.confirmImportCallCount == 0)     }      // MARK: - Accessibility

diff --git a/Asterism/AsterismTests/SettingsSyncModelTests.swift b/Asterism/AsterismTests/SettingsSyncModelTests.swiftnew file mode 100644index 0000000..cef579d--- /dev/null+++ b/Asterism/AsterismTests/SettingsSyncModelTests.swift@@ -0,0 +1,333 @@+import AsterismCore+import Foundation+import Testing+@testable import Asterism++/// Tests for the Settings iCloud section's view model (task 20, Req 8.1–8.5).+///+/// The model is where the wording lives, per the `LibraryDiagnosticsModel`+/// precedent, so these tests are the only place the reader-facing sentences are+/// pinned. Four properties matter more than the exact phrasing:+///+/// - **Every date is *last observed*.** Events raised while the app was+///   suspended are never seen, so the lines are a floor on sync activity and the+///   surface has to say so rather than implying a log (Req 8.1).+/// - **Only the actionable class is banner-worthy** (Req 8.2, 8.3, Q11).+///   Transient, self-healing, misconfigured and terminal failures are named here+///   and stay off Recent's banner.+/// - **The health line refuses "healthy" while the library is degraded**+///   (Req 8.5), and the counts are visible either way.+/// - **The lines follow the source** rather than a snapshot taken at+///   construction, which is what makes Req 8.6 hold without a relaunch.+@Suite("SettingsSyncModel")+@MainActor+struct SettingsSyncModelTests {++    // MARK: - Fixtures++    /// A settable stand-in for `SyncMonitor`, which cannot be driven from the app+    /// test bundle: its ingest seam is internal to AsterismCore.+    private final class StubSyncStatusSource: SyncStatusReporting {+        var status: SyncStatusRecord+        init(_ status: SyncStatusRecord = .neverSynced) { self.status = status }+    }++    private static func model(+        status: SyncStatusRecord = .neverSynced,+        mirroringRequested: Bool = true,+        diagnostics: LibraryDiagnostics = .empty+    ) -> (SettingsSyncModel, StubSyncStatusSource, MockLibraryProvider) {+        let source = StubSyncStatusSource(status)+        let library = MockLibraryProvider()+        library.diagnostics = diagnostics+        let model = SettingsSyncModel(+            source: source, library: library, mirroringRequested: mirroringRequested)+        return (model, source, library)+    }++    private static func failing(+        _ classification: SyncFailureClassification,+        eventType: SyncEventType = .exportEvent,+        message: String = "the underlying error's own words"+    ) -> SyncStatusRecord {+        SyncStatusRecord(+            lastExportCompleted: nil,+            lastImportCompleted: nil,+            hasEverImported: false,+            lastFailure: SyncFailureRecord(+                classification: classification,+                eventType: eventType,+                date: Date(timeIntervalSince1970: 1_700_000_000),+                message: message))+    }++    private static func quarantined(_ hostname: String = "quarantined.test") -> LibraryDiagnostics {+        LibraryDiagnostics.union(+            tupleDiagnoses: [+                hostname: .invalidStateTuple(+                    type: "Site", id: hostname, reason: "taught with no active pattern")+            ],+            toleratedStates: [])+    }++    private static func duplicateIdentities(rowCount: Int = 2) -> LibraryDiagnostics {+        LibraryDiagnostics.union(+            tupleDiagnoses: [:],+            toleratedStates: [+                .duplicateIdentity(+                    type: "Entry", id: UUID(), hostname: "dup.test", rowCount: rowCount)+            ])+    }++    // MARK: - Last export / last import (Req 8.1)++    @Test("A library that has never synced says so, separately for each direction")+    func neverSyncedStatesBothDirections() {+        let (model, _, _) = Self.model()++        #expect(model.lastExportLine.localizedCaseInsensitiveContains("not"))+        #expect(model.lastImportLine.localizedCaseInsensitiveContains("not"))+        // Req 8.1 wants the two directions reported separately, so the same+        // sentence for both would be the failure, not the pass.+        #expect(model.lastExportLine != model.lastImportLine)+    }++    @Test("Observed dates are reported per direction and framed as last observed")+    func observedDatesAreReportedPerDirection() {+        let exported = Date(timeIntervalSince1970: 1_700_000_000)+        let imported = Date(timeIntervalSince1970: 1_700_003_600)+        let (model, _, _) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: exported,+                lastImportCompleted: imported,+                hasEverImported: true))++        #expect(model.lastExportLine.contains(SettingsSyncModel.format(exported)))+        #expect(model.lastImportLine.contains(SettingsSyncModel.format(imported)))+        // The surface must not read as a sync log: nothing is observed while the+        // app is suspended, and the note is the only place that is said.+        #expect(!model.observationNote.isEmpty)+        #expect(model.observationNote.localizedCaseInsensitiveContains("running"))+    }++    @Test("A never-imported mirroring build says the library may still be arriving (Req 6.5)")+    func firstSyncLineShownWhileNothingHasArrived() {+        let (model, _, _) = Self.model()+        #expect(model.firstSyncLine != nil)++        let (imported, _, _) = Self.model(+            status: SyncStatusRecord(lastImportCompleted: Date(), hasEverImported: true))+        #expect(imported.firstSyncLine == nil)+    }++    @Test("A build that does not mirror claims nothing about arriving records")+    func firstSyncLineAbsentWithoutMirroring() {+        let (model, _, _) = Self.model(mirroringRequested: false)+        #expect(model.firstSyncLine == nil)+        #expect(!model.isHealthy)+        #expect(model.healthLine.localizedCaseInsensitiveContains("off"))+    }++    @Test("A failed attachment is not presented as a library still arriving")+    func firstSyncLineAbsentWhenMisconfigured() {+        let (model, _, _) = Self.model(+            status: Self.failing(.misconfigured, eventType: .setup))+        #expect(model.firstSyncLine == nil)+    }++    // MARK: - Failure wording per class (Req 8.2–8.4)++    @Test("No recorded failure means no condition to report")+    func noFailureReportsNoCondition() {+        let (model, _, _) = Self.model()+        #expect(model.failure == nil)+        #expect(!model.isBannerWorthy)+    }++    @Test("Each actionable condition is named, carries a remedy, and is banner-worthy")+    func actionableConditionsNameThemselvesAndAreBannerWorthy() throws {+        // Looped rather than `@Test(arguments:)`: xcodebuild's+        // `-only-testing:<bundle>/<suite>` selection does not run parameterized+        // cases, so a table here would pass by never executing.+        for (condition, expectedWord) in [+            (SyncActionableCondition.signedOut, "signed out"),+            (.storageFull, "storage"),+            (.restricted, "restricted"),+        ] {+            let (model, _, _) = Self.model(status: Self.failing(.actionable(condition)))+            let failure = try #require(model.failure, "\(condition) records a failure line")++            #expect(failure.condition.localizedCaseInsensitiveContains(expectedWord))+            #expect(!failure.remedy.isEmpty)+            // Req 8.2: Settings names the condition *and* what to do about it.+            #expect(failure.remedy.localizedCaseInsensitiveContains("settings"))+            #expect(failure.isBannerWorthy)+            #expect(model.isBannerWorthy)+        }+    }++    @Test("Every non-actionable class is recorded, named, and kept off the banner")+    func nonActionableClassesAreNamedButNeverBannered() throws {+        for classification: SyncFailureClassification in [+            .transient, .selfHealing, .misconfigured, .terminal,+        ] {+            let (model, _, _) = Self.model(status: Self.failing(classification))+            let failure = try #require(model.failure, "\(classification) records a failure line")++            // Req 8.3, 8.4: recorded and named rather than reported as success…+            #expect(!failure.condition.isEmpty)+            #expect(!failure.remedy.isEmpty)+            #expect(!model.isHealthy)+            // …and never raised to Recent (Q11, Q42).+            #expect(!failure.isBannerWorthy)+            #expect(!model.isBannerWorthy)+        }+    }++    @Test("A transient failure names the half that failed and says no action is needed")+    func transientFailureNamesTheHalfAndAsksForNothing() throws {+        let (exporting, _, _) = Self.model(+            status: Self.failing(.transient, eventType: .exportEvent))+        let (importing, _, _) = Self.model(+            status: Self.failing(.transient, eventType: .importEvent))++        let sending = try #require(exporting.failure)+        let receiving = try #require(importing.failure)+        // `SyncFailureRecord.eventType` exists so a failure can say which half it+        // was; a shared sentence for both would waste it.+        #expect(sending.condition != receiving.condition)+        #expect(sending.remedy.localizedCaseInsensitiveContains("nothing"))+    }++    @Test("The recorded message and the observation date travel with the failure")+    func failureCarriesItsMessageAndDate() throws {+        let (model, _, _) = Self.model(+            status: Self.failing(.terminal, message: "CKError 4711: unknown"))+        let failure = try #require(model.failure)++        // For the unclassified arm the framework's own words are the only+        // information there is, so they are surfaced rather than swallowed.+        #expect(failure.detail == "CKError 4711: unknown")+        #expect(failure.observed == SettingsSyncModel.format(Date(timeIntervalSince1970: 1_700_000_000)))+    }++    // MARK: - Health gating with counts (Req 8.5)++    @Test("A clean, mirroring, failure-free library is the only healthy state")+    func cleanLibraryReadsHealthy() async {+        let (model, _, _) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: Date(), lastImportCompleted: Date(), hasEverImported: true))+        await model.load()++        #expect(model.isHealthy)+        #expect(model.healthLine.localizedCaseInsensitiveContains("healthy"))+        #expect(model.quarantinedHostnameCount == 0)+        #expect(model.duplicateIdentityRecordCount == 0)+        #expect(model.countsLine.contains("0"))+    }++    @Test("A quarantined hostname refuses the healthy reading and shows its count")+    func quarantinedHostnameRefusesHealthy() async {+        let (model, _, library) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: Date(), lastImportCompleted: Date(), hasEverImported: true),+            diagnostics: Self.quarantined())+        await model.load()++        #expect(library.diagnosticsReadCount == 1)+        #expect(model.quarantinedHostnameCount == 1)+        #expect(!model.isHealthy)+        // The word itself must not appear: "not healthy" still reads as a verdict+        // the reader has to parse, and Req 8.5 is about not making the claim.+        #expect(!model.healthLine.localizedCaseInsensitiveContains("healthy"))+        #expect(model.countsLine.contains("1"))+    }++    @Test("Records sharing an application UUID refuse the healthy reading and show their count")+    func duplicateIdentitiesRefuseHealthy() async {+        let (model, _, _) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: Date(), lastImportCompleted: Date(), hasEverImported: true),+            diagnostics: Self.duplicateIdentities(rowCount: 3))+        await model.load()++        #expect(model.duplicateIdentityRecordCount == 3)+        #expect(!model.isHealthy)+        #expect(!model.healthLine.localizedCaseInsensitiveContains("healthy"))+        #expect(model.countsLine.contains("3"))+    }++    @Test("A recorded failure alone is enough to refuse the healthy reading")+    func recordedFailureRefusesHealthy() async {+        let (model, _, _) = Self.model(status: Self.failing(.transient))+        await model.load()++        #expect(model.quarantinedHostnameCount == 0)+        #expect(!model.isHealthy)+        #expect(!model.healthLine.localizedCaseInsensitiveContains("healthy"))+    }++    @Test("Before the counts have been read, the verdict is withheld rather than assumed")+    func healthIsWithheldUntilTheCountsAreRead() async {+        let (model, _, _) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: Date(), lastImportCompleted: Date(), hasEverImported: true))++        // The counts start at zero, which is what a clean library also looks+        // like — so "healthy" here would be read off nothing, on the first frame+        // and every frame until the loading task completes.+        #expect(!model.hasLoaded)+        #expect(!model.isHealthy)+        #expect(!model.healthLine.localizedCaseInsensitiveContains("healthy"))+        #expect(!model.countsLine.contains("0 sites"))++        await model.load()++        #expect(model.hasLoaded)+        #expect(model.isHealthy)+    }++    @Test("Reloading picks up a library that changed while Settings stayed open")+    func reloadingFollowsTheLibrary() async {+        let (model, _, library) = Self.model(+            status: SyncStatusRecord(+                lastExportCompleted: Date(), lastImportCompleted: Date(), hasEverImported: true))+        await model.load()+        #expect(model.isHealthy)++        // An arrival quarantines a hostname while the sheet is up. The view+        // re-runs `load()` on the status change; the model has to answer with+        // the library as it now stands rather than as it was at presentation.+        library.diagnostics = Self.quarantined()+        await model.load()++        #expect(model.quarantinedHostnameCount == 1)+        #expect(!model.isHealthy)+        #expect(model.countsLine.contains("1"))+    }++    // MARK: - Liveness (Req 8.6)++    @Test("The lines follow the status source rather than a snapshot taken at construction")+    func linesFollowTheSourceWithoutRebuilding() throws {+        let (model, source, _) = Self.model()+        #expect(model.failure == nil)+        #expect(model.lastExportLine.localizedCaseInsensitiveContains("not"))++        let exported = Date(timeIntervalSince1970: 1_700_000_000)+        source.status = SyncStatusRecord(+            lastExportCompleted: exported,+            hasEverImported: true,+            lastFailure: SyncFailureRecord(+                classification: .actionable(.signedOut),+                eventType: .exportEvent,+                date: exported,+                message: "not authenticated"))++        // Same model instance: nothing was reconstructed and no reload was run.+        #expect(model.lastExportLine.contains(SettingsSyncModel.format(exported)))+        #expect(try #require(model.failure).isBannerWorthy)+        #expect(model.firstSyncLine == nil)+    }+}

diff --git a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swiftindex ad6973e..3c0ad3a 100644--- a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift+++ b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift@@ -89,6 +89,46 @@ final class AccessibilityJourneyUITests: XCTestCase {         XCTAssertTrue(app.collectionViews["settings-view"].exists)     } +    /// Req 8.1–8.5's surface, reached the way the reader reaches it.+    ///+    /// A UI-test root cannot mirror — it opens an explicit `LibraryConfiguration`+    /// whose `cloudKitContainerID` is nil, so the open lands in+    /// `MirroringAttachment.notRequested` (cloudkit-mirroring Q57). This pins the+    /// section that state renders: both directions reported separately, and a+    /// health line that does not claim health for a library that is not syncing+    /// at all.+    ///+    /// The failure and banner states are still not reachable from here, and no+    /// longer for the reason this comment used to give — task 19 landed, and the+    /// app does construct a live `SyncMonitor`. The blocker is that with no+    /// container attached, no CloudKit event is ever posted, so the monitor has+    /// nothing to report and Recent's sync banner and first-sync empty state+    /// never render. Reaching them would need a UI-test-only status-file seed or+    /// an event-injection seam; the gap and that trade-off are recorded as+    /// cloudkit-mirroring Q56, and the logic itself is pinned by+    /// `AppLibraryModelTests` and the `SettingsSyncModel` suites.+    @MainActor+    func testSettingsSyncSectionIsReachableAndReportsBothDirections() {+        launchSeeded()++        let settingsButton = app.buttons["settings-button"]+        XCTAssertTrue(settingsButton.waitForExistence(timeout: 30))+        settingsButton.tap()++        let exportLine = app.staticTexts["settings-sync-export-line"]+        XCTAssertTrue(exportLine.waitForExistence(timeout: 10), "The iCloud section should be present")+        let importLine = app.staticTexts["settings-sync-import-line"]+        XCTAssertTrue(importLine.exists, "Req 8.1 reports the two directions separately")+        XCTAssertNotEqual(exportLine.label, importLine.label)++        let healthLine = app.staticTexts["settings-sync-health-line"]+        XCTAssertTrue(healthLine.exists)+        XCTAssertFalse(+            healthLine.label.localizedCaseInsensitiveContains("healthy"),+            "A build that cannot mirror must not report sync as healthy")+        XCTAssertTrue(app.staticTexts["settings-sync-counts-line"].exists, "Req 8.5 shows the counts")+    }+     @MainActor     func testDarkReduceTransparencyLargestDynamicTypeKeepsPrimaryJourneysReachable() {         launchSeeded(

diff --git a/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift b/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swiftindex f3badc1..0f4fb7b 100644--- a/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift+++ b/Asterism/AsterismUITests/LibraryDiagnosticsUITests.swift@@ -124,34 +124,39 @@ final class LibraryDiagnosticsUITests: XCTestCase {          tapDiagnosisBanner()         require(app.staticTexts["dup.test"], "The duplicated site is named")-        // Req 3.4: the reader is told plainly, not sent to an action that is refused.+        // Q36: the app consolidates duplicate rows itself, so the row is+        // informational. It must not read as a standing failure — the emptied+        // copies are kept rather than deleted, so this line never goes away.         let resolution = require(             app.staticTexts["diagnostics-row-resolution-0"], "The row states its resolution")-        XCTAssertTrue(resolution.label.localizedCaseInsensitiveContains("cannot"),-                      "Duplicate Site rows say re-teaching cannot clear them")+        XCTAssertTrue(resolution.label.localizedCaseInsensitiveContains("nothing to do"),+                      "Duplicate Site rows read as expected, not as damage")+        XCTAssertFalse(resolution.label.localizedCaseInsensitiveContains("cannot"),+                       "The row no longer says re-teaching cannot clear it")         XCTAssertFalse(app.buttons["diagnostics-reteach-0"].exists,-                       "No route is offered where re-teaching would be refused")+                       "There is nothing for the reader to do from this screen")     } -    // MARK: - Attention-marked rows (Req 2.2, Q38, Q49)+    // MARK: - Attention-marked rows (Req 2.2, Q36, Q39) -    func testDuplicatedHostnameRowIsMarkedAndOffersNoTeachPill() {+    func testDuplicatedHostnameRowIsMarkedAndKeepsItsTeachPill() {         launch("duplicateSiteRows")         require(app.collectionViews["recent-list"], "Recent renders in the duplicated state", timeout: 60)          require(app.staticTexts["entry-attention"],-                "A row whose action was withdrawn says what is unresolved")+                "The row says its hostname is stored more than once") -        // Scoped to the marked row on purpose: the fixture also carries a healthy-        // untaught Site, whose row *should* still offer Teach. An unscoped-        // assertion would pass only by breaking the rest of Recent.+        // Q39: the pill is offered again. Teaching commits to the row+        // `SiteResolutionOrder` selects — the row this one already renders its+        // mode from — so the action leads where the disclosure points. Withdrawing+        // it made Decision 6's coexisting rows permanently unteachable.         let markedRow = app.cells.containing(.staticText, identifier: "entry-attention").firstMatch-        require(markedRow, "The unresolved row is still listed")-        XCTAssertFalse(markedRow.buttons["teach-pill"].exists,-                       "Teaching is refused on a duplicated hostname, so no pill is offered")-        XCTAssertEqual(app.buttons.matching(identifier: "teach-pill").count, 1,-                       "Only the healthy site's row keeps its Teach pill")-        require(app.buttons["diagnosis-banner"], "The diagnosis screen is the route instead")+        require(markedRow, "The marked row is still listed")+        XCTAssertTrue(markedRow.buttons["teach-pill"].exists,+                      "A duplicated hostname is teachable, through its winning row")+        XCTAssertEqual(app.buttons.matching(identifier: "teach-pill").count, 2,+                       "Both the marked row and the healthy site's row offer Teach")+        require(app.buttons["diagnosis-banner"], "The state is still reported")     }      // MARK: - Every tolerated state opens (Req 1.1)

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7bdc730..39a0299 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -30,6 +30,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).   comes from whichever rule supplies it. Existing taught Sites carry over   without re-teaching. +### Added++- **iCloud sync is on.** The library now mirrors to CloudKit in both configurations (Development and Personal, each to its own container), verified by a two-device runbook whose results live in `specs/cloudkit-mirroring/runbook-log.md` — including concurrent-teach conflict repair on arrival and a 5,000-record import converging across devices with store-level diff evidence. The share extension still captures locally and never mirrors; captures sync when the app is next opened (T-2052 tracks narrowing that gap).+- The CloudKit mirroring implementation (M4b, tasks 1–25 of `specs/cloudkit-mirroring/`). The library-coherence half works with mirroring off and improves the app today: duplicate Site rows for one hostname now consolidate additively in the background (rows are never deleted; rule versions renumber deterministically and citations follow), teaching a duplicated hostname commits to the deterministically chosen winner row instead of being refused, backup export produces a file for quarantined, unresolved, and duplicate-row libraries alike (three named refusals remain: duplicate application UUIDs, an unrepresentable raw value naming the record, and references still arriving), and import is a modification-guarded chunked upsert onto the live library — no re-bootstrap, an interruption leaves a legal library that reports the unfinished archive by name in Settings. The sync half is plumbed and dormant: a two-phase store open that only attaches a mirrored container after first-launch certification, a sync monitor classifying failures into five classes with a persisted status file, an iCloud section in Settings whose health line refuses "healthy" while quarantined or duplicate-UUID counts are nonzero, a Recent banner for the one actionable failure class, and an "Arriving from iCloud" empty state for a first sync. The shared bulk chunk constant is now measured rather than provisional (stays 500 — chunking buys interruption boundaries, not speed; bands in `specs/cloudkit-mirroring/implementation.md`), and the identity lint now covers the mirroring flag so the eventual flip is one linted pbxproj value per configuration.+- CloudKit mirroring specification (`specs/cloudkit-mirroring/`, M4b): requirements, design, decision log, and task plan for enabling app-only mirroring on per-configuration containers. The design settled on additive-only Site reconciliation (rows consolidate, never delete), deterministic rule-version renumbering with citation rewrites, export that projects sync states instead of refusing them (three named refusals remain), and a modification-guarded chunked upsert import. No code changes in this commit.+ ### Changed  - Each build configuration now declares its identity once — `ASTERISM_IDENTITY` in the Xcode project — and derives both the App Group and the CloudKit container identifier from it. Entitlements and each product's Info.plist carry references to the derived settings instead of repeating literals, and the resolved values are unchanged: Development keeps its `.dev` pair, Personal keeps the bare pair. The `LibraryEnvironment` enum and its `#if DEBUG` selection are deleted; the app and the share extension read the identifier from their own bundle at launch (the app stops with a diagnostic naming the missing key, the extension fails through its existing library-unavailable message), and the AsterismCore package takes identifiers as explicit input with no bundle reading. Divergence now fails loudly twice over: `make verify-identity` (a new `test-core` prerequisite) checks the declarations without building anything, and an in-build phase on both targets verifies the processed entitlements against values recomputed from the token — in both configurations, including Personal, which never runs unit tests. Every check was demonstrated to fire on a deliberate break before landing. `AsterismMigrationTool` and `make migrate-m1-to-m2` now take an explicit root (`MIGRATION_ROOT`) instead of an `--environment` flag.

diff --git a/CLAUDE.md b/CLAUDE.mdindex 0b0ba03..ec59767 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -44,6 +44,7 @@ invocations where a target exists. - `make test-quick` — unit-test bundle only (simulator) - `make test` / `make test-ui` — full suites (simulator) - `make test-performance-m4` — M4 Core budgets, host only, no device, safe to run. **Takes ~30 minutes** since the V4→V5 migration measurement joined it: each sample is ~17 s of migration plus a ~13 s reset that has to be committed and reopened to be a pre-pass graph at all (Q58 of `specs/relational-references`).+- `make test-performance-chunks` — host-only calibration sweep of the shared bulk chunk constant (import commits and the reconciler re-pin). No device, safe to run, but gated on `ASTERISM_RUN_CHUNK_SWEEP=1` and **~20 minutes per run**, so it is deliberately *not* part of `make test-performance-m4`. It asserts nothing — a calibration is reported, not budgeted. Re-run it when the bulk write paths change (Q53 and the task 25 section of `specs/cloudkit-mirroring/implementation.md`). - `make test-performance`, `make test-performance-m4-recent` — **physical device, see above**  The `-m4` and `-m4-recent` targets are easy to confuse and only one of them is safe: `test-performance-m4` is a `swift test` run of the `AsterismCore` package on the host, while `test-performance-m4-recent` builds the `Personal` configuration and installs it over the real app on a phone.@@ -59,10 +60,17 @@ without building anything — see `specs/configuration-identity/`.  ### Configurations are not interchangeable -| Configuration | Scheme | Bundle ID | App Group | Optimization |-|---|---|---|---|---|-| `Development` | `Asterism Development` | `me.nore.ig.Asterism.dev` | `group.me.nore.ig.Asterism.dev` | `-Onone`, `ENABLE_TESTABILITY=YES` |-| `Personal` | `Asterism Personal` | `me.nore.ig.Asterism` | `group.me.nore.ig.Asterism` | `-O`, `wholemodule` |+| Configuration | Scheme | Bundle ID | App Group | CloudKit container | Optimization |+|---|---|---|---|---|---|+| `Development` | `Asterism Development` | `me.nore.ig.Asterism.dev` | `group.me.nore.ig.Asterism.dev` | `iCloud.me.nore.ig.Asterism.dev` | `-Onone`, `ENABLE_TESTABILITY=YES` |+| `Personal` | `Asterism Personal` | `me.nore.ig.Asterism` | `group.me.nore.ig.Asterism` | `iCloud.me.nore.ig.Asterism` | `-O`, `wholemodule` |++**Both configurations mirror to CloudKit** since tasks 26/27 of+`specs/cloudkit-mirroring/`. A `Development` install is therefore **no longer+device-local**: any device signed into the same iCloud account that has it+installed shares the dev library, so installing it on a second phone merges+that phone's dev data in. `Personal` syncs the real library. Both containers+are in CloudKit's development environment.  These install as **separate apps with separate data**, both named "Asterism" on the home screen (`PRODUCT_NAME` is shared). Performance measurement must use

diff --git a/Makefile b/Makefileindex a8e270a..a81b14e 100644--- a/Makefile+++ b/Makefile@@ -44,6 +44,7 @@ help: 	@echo "    test-performance - Run opt-in M2 scale measurements on a physical iPhone" 	@echo "    test-performance-m4 - Run opt-in M4 composed-teaching scale budgets (AsterismCore)" 	@echo "    test-performance-m4-recent - Run the M4 Recent publish baseline on a physical iPhone"+	@echo "    test-performance-chunks - Sweep the bulk chunk constant (AsterismCore, host only)" 	@echo "    test-only   - Run TEST, e.g. make test-only TEST=AsterismTests/MyTests/testName" 	@echo "    install     - Build and install on a connected physical device" 	@echo "    run         - Build, install, and launch on a connected physical device"@@ -307,6 +308,36 @@ test-performance-m4: 			|| exit $$?; \ 	done +# The Q32 calibration sweep behind LibraryRepository.bulkOperationBatchSize:+# import commit chunks and reconciler re-pin chunks over the 5,000-Entry fixture+# at several candidate sizes. Host only, no device, sync quiesced by+# construction (no measured store carries a container id).+#+# Deliberately NOT part of test-performance-m4, which is already ~30 minutes.+# This is a calibration to re-run when the bulk write paths change, not a budget+# to assert on every pass -- it asserts no budget at all, it reports.+#+# Budget your time: ~20 minutes per run. Every re-pin sample pays a ~40 s divert+# of its own before anything is timed, and there is no shortcut that does not+# turn the measurement into one of an already-converged graph.+#+# Same release/ASTERISM_PERFORMANCE_TESTING reasoning as the target above, and+# RUNS=<n> likewise, so the bands recorded in+# specs/cloudkit-mirroring/implementation.md span runs rather than one sample set.+.PHONY: test-performance-chunks+test-performance-chunks:+	$(PIPEFAIL) for run in $$(seq 1 $(RUNS)); do \+		echo "== Chunk calibration run $$run of $(RUNS)"; \+		ASTERISM_RUN_CHUNK_SWEEP=1 \+		ASTERISM_PERFORMANCE_LOG="$(PERFORMANCE_LOG)" swift test \+			--package-path Packages/AsterismCore \+			--no-parallel \+			-c release \+			-Xswiftc -DASTERISM_PERFORMANCE_TESTING \+			--filter 'M4BulkChunkPerformanceTests' \+			|| exit $$?; \+	done+ .PHONY: test test: 	$(PIPEFAIL) xcodebuild test \

diff --git a/Packages/AsterismCore/Sources/AsterismCore/AsterismCapabilities.swift b/Packages/AsterismCore/Sources/AsterismCore/AsterismCapabilities.swiftindex 113c06a..4c3482a 100644--- a/Packages/AsterismCore/Sources/AsterismCore/AsterismCapabilities.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/AsterismCapabilities.swift@@ -40,12 +40,34 @@ public struct AsterismCapabilities: Codable, Equatable, Sendable {         case .m2_2, .m2_3, .m3, .m4: true         }     }-    public var supportsPhraseTeaching: Bool { gate == .m2_3 || gate == .m3 || gate == .m4 }-    public var supportsURLIdentity: Bool { gate == .m3 || gate == .m4 }+    // Q10 of `specs/cloudkit-mirroring`: these three were `gate == .m3 || gate ==+    // .m4` equality chains, which is why a proposed `.m5` gate would have turned+    // all three *off* with nothing failing to compile. Exhaustive switches make+    // the next gate a compile error at every one of them, which is the whole+    // point of adding one.+    public var supportsPhraseTeaching: Bool {+        switch gate {+        case .m2_0, .m2_1, .m2_2: false+        case .m2_3, .m3, .m4: true+        }+    }++    public var supportsURLIdentity: Bool {+        switch gate {+        case .m2_0, .m2_1, .m2_2, .m2_3: false+        case .m3, .m4: true+        }+    }+     /// The M4 composed forms: whole-title and chapter-less title rules, title     /// affix trims, and sequence-only URL rules (Req 2.2). Only `.m4` accepts     /// them, so every pre-M4 gate keeps its frozen validation.-    public var supportsComposedForms: Bool { gate == .m4 }+    public var supportsComposedForms: Bool {+        switch gate {+        case .m2_0, .m2_1, .m2_2, .m2_3, .m3: false+        case .m4: true+        }+    }      public func allows(patternForm: PatternForm) -> Bool {         switch patternForm {

diff --git a/Packages/AsterismCore/Sources/AsterismCore/BackupImporter.swift b/Packages/AsterismCore/Sources/AsterismCore/BackupImporter.swiftindex d93d811..4257cce 100644--- a/Packages/AsterismCore/Sources/AsterismCore/BackupImporter.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/BackupImporter.swift@@ -65,29 +65,18 @@ public struct BackupImportMetadata: Sendable, Equatable {     } } -/// An opaque fingerprint of the current library inventory at the time of preview.-/// Used to detect stale replacement confirmation.-public struct LibraryInventoryFingerprint: Sendable, Equatable {-    /// The record counts at preview time.-    public let counts: LibraryRecordCounts-    /// A snapshot of all entity UUIDs for deep equality comparison.-    public let entitySignature: String--    public init(counts: LibraryRecordCounts, entitySignature: String) {-        self.counts = counts-        self.entitySignature = entitySignature-    }-}- // MARK: - Import Commit Result  /// The result of an import commit operation.+///+/// There is no `.stale` case any more (Req 4.5). It existed for the inventory+/// fingerprint the confirm step compared against the preview's, which on any+/// device receiving sync traffic could never match — records arriving while the+/// reader confirms are simply more rows for the upsert to match. public enum BackupImportCommitResult: Sendable, Equatable {-    /// Import committed successfully. The library is now ready.+    /// Import committed. The counts are the library's afterwards, not the+    /// archive's: an upsert adds to what is already there.     case committed(LibraryRecordCounts)-    /// The expected state/inventory changed; zero writes performed.-    /// The caller should refresh and re-confirm.-    case stale(reason: String) }  // MARK: - Importer Errors

diff --git a/Packages/AsterismCore/Sources/AsterismCore/BackupV4Exporter.swift b/Packages/AsterismCore/Sources/AsterismCore/BackupV4Exporter.swiftindex 770ca9d..995cc0a 100644--- a/Packages/AsterismCore/Sources/AsterismCore/BackupV4Exporter.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/BackupV4Exporter.swift@@ -12,35 +12,42 @@ public protocol BackupV4SnapshotProviding: Sendable { // MARK: - V4 Export Errors  public enum BackupV4ExportError: Error, Equatable, Sendable, CustomStringConvertible {-    /// One or more Sites failed validation at load and are quarantined; export-    /// is refused because an illegal Site cannot be encoded into a valid 4/4-    /// payload and silently skipping it would be data loss (Req 9.4). Each Site-    /// is named and the repair is composed re-teaching.-    case libraryQuarantined(sites: [String])-    /// Q17. The two tolerated states that do **not** quarantine — an Entry or-    /// Work whose Site row is absent, and records sharing an application UUID —-    /// walk past the gate above, encode successfully, and then fail inside-    /// export's own self-validating decode as-    /// `encodingFailed(reason: "decode-validation failed: …")`: a codec error-    /// for a library-shape problem. This refusal is checked before any of that-    /// work and says how many records are unresolved.+    /// Req 3.3. Two records of one type share an application UUID. The archive+    /// keys records by UUID and cannot hold both, and silently dropping one is+    /// data loss inside a backup. The repair is M4c's Entry/Work collapse.+    case duplicateRecordIdentity(type: String, id: String)++    /// Req 3.6. A record holds a stored value the 4/4 wire format cannot+    /// represent — typically an enum raw value a newer app version wrote and+    /// synced down. Omitting the record is silent data loss; representing the+    /// value is a format change (Decision 4). So the record and the value are+    /// named and the export refuses.+    case unrepresentableValue(record: String, field: String, value: String)++    /// Req 3.7. A record cites a rule no row in the library holds, or a rule+    /// whose owning Site is absent and which no citing record locates. The+    /// import gates rightly refuse an archive whose citations do not resolve+    /// (relational-references Decision 3), so export must not produce one.     ///-    /// There is no repair in phase 1. Making a 4/4 archive able to represent-    /// these states is a format change and belongs with the mirroring hazards-    /// that determine what it must represent (Decision 3).-    case libraryUnresolved(recordCount: Int)+    /// Transient by nature: the missing row is en route.+    case referencesStillArriving(detail: String)+     case snapshotFailed(reason: String)     case encodingFailed(reason: String)     case stagingFailed(reason: String)      public var description: String {         switch self {-        case .libraryQuarantined(let sites):-            "Backup export refused: re-teach these quarantined Sites before exporting: \(sites.joined(separator: ", "))"-        case .libraryUnresolved(let recordCount):-            "Backup export refused: this library cannot be exported yet because \(recordCount) "-                + "records are unresolved — records whose site is missing, or sharing an identity "-                + "with another record"+        case .duplicateRecordIdentity(let type, let id):+            "Backup export refused: two \(type) records share the identifier \(id), "+                + "and a backup cannot hold both"+        case .unrepresentableValue(let record, let field, let value):+            "Backup export refused: \(record) holds \(field) '\(value)', which this "+                + "backup format cannot represent — it was probably written by a newer "+                + "version of Asterism"+        case .referencesStillArriving(let detail):+            "Backup export refused: records are still arriving from iCloud (\(detail)). "+                + "Try again once syncing has settled"         case .snapshotFailed(let reason): "Backup V4 snapshot failed: \(reason)"         case .encodingFailed(let reason): "Backup V4 encoding failed: \(reason)"         case .stagingFailed(let reason): "Backup V4 staging failed: \(reason)"@@ -51,42 +58,321 @@ public enum BackupV4ExportError: Error, Equatable, Sendable, CustomStringConvert // MARK: - LibraryRepository V4 Snapshot  extension LibraryRepository: BackupV4SnapshotProviding {-    /// Provides a coherent V4 backup payload under a shared lock. Refuses while-    /// any Site is quarantined, naming each offending Site (Req 9.4).+    /// Provides a coherent V4 backup payload under a shared lock.+    ///+    /// **The quarantine and unresolved gates are gone** (Req 3.1). They refused a+    /// file at exactly the moment one is most wanted: an ordinary sync quarantines+    /// a hostname or leaves 2,995 of 3,000 records holding an unresolved Site+    /// reference (Q25), and the backup tool then declined. What made removing them+    /// possible is `SiteUnionProjection` — duplicate rows project to one wire Site,+    /// rowless hostnames to a synthesised untaught one, and nil-site rules attach+    /// through their citers — so the snapshot is total over the ordinary sync+    /// states rather than merely permitted to try.+    ///+    /// Three refusals remain, each named: duplicate application UUIDs (3.3), a+    /// stored value the format cannot represent (3.6), and citations that do not+    /// resolve (3.7).+    ///+    /// Export never writes. The projection is computed read-side precisely so a+    /// backup cannot mutate the library on the way out (Q38); the archive it+    /// produces is nonetheless the shape reconciliation settles on, which is what+    /// makes Req 3.5's round-trip hold.     public func backupV4Snapshot() async throws -> BackupV4Payload {-        if !quarantined.isEmpty {-            throw BackupV4ExportError.libraryQuarantined(sites: quarantined.keys.sorted())+        let outcome: Result<BackupV4Payload, BackupV4ExportError> =+            try await withLockedBackupContext { context in+                do { return .success(try Self.projectV4Payload(context: context)) }+                catch let error as BackupV4ExportError { return .failure(error) }+            }+        return try outcome.get()+    }++    /// The whole snapshot, from a context. Static and pure so the projection can+    /// be exercised without an actor.+    internal static func projectV4Payload(context: ModelContext) throws -> BackupV4Payload {+        let entries = try context.fetch(FetchDescriptor<Entry>())+            .sorted { $0.id.uuidString < $1.id.uuidString }+        let works = try context.fetch(FetchDescriptor<Work>())+            .sorted { $0.id.uuidString < $1.id.uuidString }+        let sites = try context.fetch(FetchDescriptor<Site>())+        let patterns = try context.fetch(FetchDescriptor<TitlePattern>())+        let urlRules = try context.fetch(FetchDescriptor<URLRulePattern>())++        // Req 3.3 first: a duplicate UUID makes every later map ambiguous.+        try requireUniqueIdentities(+            entries: entries, works: works, patterns: patterns, urlRules: urlRules)+        // Req 3.6 second: naming the record and the value is only possible before+        // the mappers coerce or throw over it.+        try requireRepresentableValues(+            entries: entries, works: works, sites: sites,+            patterns: patterns, urlRules: urlRules)++        // Rules whose Site has not arrived are attached through a citing record's+        // hostname (Q41). One that nothing cites cannot be placed at all.+        let citers = citerHostnames(entries: entries, works: works)+        var additionalPatterns: [String: [TitlePattern]] = [:]+        for pattern in patterns where pattern.site == nil {+            guard let hostname = citers[pattern.id] else {+                throw BackupV4ExportError.referencesStillArriving(+                    detail: "title rule \(pattern.id) has no site and no entry naming one")+            }+            additionalPatterns[hostname, default: []].append(pattern)         }-        // Q17. The other two tolerated states do not quarantine, so nothing above-        // catches them and export would otherwise discover the problem inside its-        // own decode-validation, as a codec error. Refused here by name, before-        // the snapshot, the mappers, and the encode. Phase 1 pre-check only: the-        // archive format and the reference validator are phase 2's (Decision 3).-        let unresolved = diagnostics.unresolvedRecordCount-        if unresolved > 0 {-            throw BackupV4ExportError.libraryUnresolved(recordCount: unresolved)+        var additionalURLRules: [String: [URLRulePattern]] = [:]+        for rule in urlRules where rule.site == nil {+            guard let hostname = citers[rule.id] else {+                throw BackupV4ExportError.referencesStillArriving(+                    detail: "URL rule \(rule.id) has no site and no record naming one")+            }+            additionalURLRules[hostname, default: []].append(rule)         }-        return try await withLockedBackupContext { context in-            let entries = try context.fetch(FetchDescriptor<Entry>())-            let works = try context.fetch(FetchDescriptor<Work>())-            let sites = try context.fetch(FetchDescriptor<Site>())-            let patterns = try context.fetch(FetchDescriptor<TitlePattern>())-            let urlRules = try context.fetch(FetchDescriptor<URLRulePattern>())--            return BackupV4Payload(-                entries: try entries.map { try Self.mapV4EntryRecord($0) },-                works: try works.map { try Self.mapV4WorkRecord($0) },-                sites: try sites.map { try Self.mapV4SiteRecord($0) },-                titlePatterns: try patterns.map { try Self.mapV4TitlePatternRecord($0) },-                urlRules: try urlRules.map { try Self.mapV4URLRuleRecord($0) }-            )++        // Q40, read-side: an Entry or Work naming a hostname with no row gets a+        // synthesised untaught wire Site, which is what capture would have+        // materialised and what the codec's every-Entry-has-a-Site invariant asks+        // for. The store gains nothing.+        let rowHostnames = Set(sites.map(\.hostname))+        let danglingHostnames = Set(entries.map(\.hostname))+            .union(works.map(\.siteHostname))+            .subtracting(rowHostnames)++        let projected = SiteUnionProjection.project(+            rows: sites, danglingHostnames: danglingHostnames,+            additionalPatterns: additionalPatterns, additionalURLRules: additionalURLRules)+        try requireProjectedTuplesRepresentable(projected)++        var wireSites: [BackupV4Site] = []+        var wirePatterns: [BackupV4TitlePattern] = []+        var wireRules: [BackupV4URLRule] = []+        var rewrites: [UUID: Int] = [:]+        for site in projected {+            rewrites.merge(site.versionRewrites) { lhs, _ in lhs }+            wireSites.append(mapV4SiteRecord(site))+            for projectedPattern in site.patterns {+                wirePatterns.append(+                    try mapV4TitlePatternRecord(projectedPattern, hostname: site.hostname))+            }+            for projectedRule in site.urlRules {+                wireRules.append(mapV4URLRuleRecord(projectedRule, hostname: site.hostname))+            }         }++        let payload = BackupV4Payload(+            entries: try entries.map { try mapV4EntryRecord($0, rewrites: rewrites) },+            works: try works.map { try mapV4WorkRecord($0, rewrites: rewrites) },+            sites: wireSites.sorted { $0.hostname < $1.hostname },+            titlePatterns: wirePatterns.sorted { $0.id.uuidString < $1.id.uuidString },+            urlRules: wireRules.sorted { $0.id.uuidString < $1.id.uuidString }+        )+        // Req 3.7: the archive's own reference validator refuses a citation that+        // does not resolve, and the import gates refuse such a file. Discovering+        // that inside export's verify-decode would surface a library-shape problem+        // as a codec error, so it is named here instead.+        try requireCitationsResolve(payload)+        return payload+    }++    // MARK: - The three named refusals++    /// Req 3.3.+    private static func requireUniqueIdentities(+        entries: [Entry], works: [Work], patterns: [TitlePattern], urlRules: [URLRulePattern]+    ) throws {+        try requireUnique(entries.map(\.id), type: "Entry")+        try requireUnique(works.map(\.id), type: "Work")+        try requireUnique(patterns.map(\.id), type: "TitlePattern")+        try requireUnique(urlRules.map(\.id), type: "URLRulePattern")+    }++    private static func requireUnique(_ ids: [UUID], type: String) throws {+        var seen: Set<UUID> = []+        // Sorted so the refusal names the same record on every run over the same+        // store; fetch order is not defined.+        for id in ids.sorted(by: { $0.uuidString < $1.uuidString }) where !seen.insert(id).inserted {+            throw BackupV4ExportError.duplicateRecordIdentity(type: type, id: id.uuidString)+        }+    }++    /// Req 3.6. Every stored raw value the 4/4 mappers read, checked before they+    /// read it — several of them coerce (`?? .conservative`, `?? .manual`) rather+    /// than throw, and a coerced value is silent data loss in a backup.+    private static func requireRepresentableValues(+        entries: [Entry], works: [Work], sites: [Site],+        patterns: [TitlePattern], urlRules: [URLRulePattern]+    ) throws {+        for entry in entries {+            let record = "Entry \(entry.id)"+            try require(CaptureTitleSource(rawValue: entry.captureTitleSourceRaw),+                record, "capture title source", entry.captureTitleSourceRaw)+            try require(EntryIdentityBasis(rawValue: entry.identityBasisRaw),+                record, "identity basis", entry.identityBasisRaw)+            try require(FieldProvenanceKind(rawValue: entry.chapterTitleProvenanceRaw),+                record, "chapter provenance", entry.chapterTitleProvenanceRaw)+            try require(FieldProvenanceKind(rawValue: entry.workAssignmentProvenanceRaw),+                record, "work assignment provenance", entry.workAssignmentProvenanceRaw)+            if let raw = entry.ratingRaw {+                try require(Rating(rawValue: raw), record, "rating", raw)+            }+            if let raw = entry.workURLAssignmentKindRaw {+                try require(URLWorkAssignmentKind(rawValue: raw), record, "work URL assignment", raw)+            }+        }+        for work in works {+            let record = "Work \(work.id)"+            try require(WorkType(rawValue: work.typeRaw), record, "type", work.typeRaw)+            try require(TitleProvenance(rawValue: work.titleProvenanceRaw),+                record, "title provenance", work.titleProvenanceRaw)+            try require(WorkURLIdentityState(rawValue: work.urlIdentityStateRaw),+                record, "URL identity state", work.urlIdentityStateRaw)+        }+        for site in sites {+            try require(SiteMode(rawValue: site.modeRaw), "Site \(site.hostname)", "mode", site.modeRaw)+        }+        for pattern in patterns {+            let record = "Title rule \(pattern.id)"+            try require(PatternForm(rawValue: pattern.formRaw), record, "form", pattern.formRaw)+            do { _ = try pattern.definition }+            catch {+                throw BackupV4ExportError.unrepresentableValue(+                    record: record, field: "definition", value: pattern.formRaw)+            }+        }+        for rule in urlRules {+            try require(rule.origin, "URL rule \(rule.id)", "origin", rule.originRaw)+        }+    }++    private static func require<Value>(+        _ value: Value?, _ record: String, _ field: String, _ raw: String+    ) throws {+        guard value == nil else { return }+        throw BackupV4ExportError.unrepresentableValue(record: record, field: field, value: raw)+    }++    /// Req 3.7's third face: a hostname whose *projected* tuple the 4/4 format+    /// has no case for.+    ///+    /// The archive's closed tuple table (`BackupV4ReferenceValidator`) wants a+    /// `.taught` Site to hold exactly one active title rule, an `.untaught` one+    /// to hold nothing but imported V2 URL history, and an `.articles` one to+    /// hold neither an active title rule nor a current URL rule.+    /// `SiteUnionProjection.mode` deliberately *preserves* a row that satisfies+    /// none of those rather than inventing a mode for it — archiving a taught+    /// site as untaught or as articles would put a different library in the file+    /// than the one in the store.+    ///+    /// Every producer of the state is an arrival gap. A re-teach demotes the old+    /// title rule and inserts its replacement in one local save; the receiving+    /// device applies that as several transactions (45 for 3,000 records, Q25),+    /// so a window in which the row is `.taught` holding one *inactive* rule is+    /// ordinary rather than exotic. Reconciliation cannot repair it — no rule the+    /// library holds is the missing one.+    ///+    /// So it refuses here, by name and as transient. Discovered later it is the+    /// verify-decode gate throwing `encodingFailed`, which tells the reader their+    /// backup failed to encode when what actually happened is that sync has not+    /// settled (Req 3.1: produce a file, or refuse in a way that names the+    /// state).+    private static func requireProjectedTuplesRepresentable(+        _ projected: [SiteUnionProjection.ProjectedSite]+    ) throws {+        for site in projected {+            let activePatterns = site.patterns.count(where: \.isActive)+            let currentRules = site.urlRules.count(where: \.isCurrent)+            switch site.mode {+            case .taught:+                guard activePatterns != 1 else { continue }+                throw BackupV4ExportError.referencesStillArriving(+                    detail: "site \(site.hostname) is taught, and the one active title rule "+                        + "that state needs is not in the library")+            case .untaught:+                let historyOnly = site.urlRules.allSatisfy {+                    $0.rule.origin == .importedV2 && !$0.isCurrent+                }+                guard !site.patterns.isEmpty || currentRules > 0 || !historyOnly else { continue }+                throw BackupV4ExportError.referencesStillArriving(+                    detail: "site \(site.hostname) is untaught while still holding rules, "+                        + "so the teaching that owns them has not arrived")+            case .articles:+                guard activePatterns > 0 || currentRules > 0 else { continue }+                throw BackupV4ExportError.referencesStillArriving(+                    detail: "site \(site.hostname) reads as articles while still holding an "+                        + "active rule, so the change that cleared them has not arrived")+            }+        }+    }++    /// Req 3.7's second half: a citation whose rule no row holds. The union+    /// renumbering means a rule present in the store always resolves, so what is+    /// left here is a citation of a rule that is genuinely absent.+    private static func requireCitationsResolve(_ payload: BackupV4Payload) throws {+        let patternIDs = Set(payload.titlePatterns.map(\.id))+        let ruleIDs = Set(payload.urlRules.map(\.id))++        for entry in payload.entries {+            let record = "entry \(entry.id)"+            for citation in Entry.ruleCitations {+                guard let id = entry[keyPath: citation.wireID] else { continue }+                let held = switch citation.target {+                case .urlRule: ruleIDs.contains(id)+                case .titlePattern: patternIDs.contains(id)+                }+                guard !held else { continue }+                throw missingCitation(record, citation.label)+            }+        }+        for work in payload.works {+            guard let id = work.urlIdentityRuleID, !ruleIDs.contains(id) else { continue }+            throw missingCitation("work \(work.id)", "its identity rule")+        }+    }++    private static func missingCitation(+        _ record: String, _ field: String+    ) -> BackupV4ExportError {+        .referencesStillArriving(+            detail: "\(record) names \(field), which the library does not hold")+    }++    /// The hostname each rule id is cited from, for placing a rule whose own Site+    /// has not arrived (Q41). Records are visited in id order, so a rule cited from+    /// two hostnames — which nothing legitimately produces — still lands the same+    /// way on every run.+    private static func citerHostnames(entries: [Entry], works: [Work]) -> [UUID: String] {+        var map: [UUID: String] = [:]+        func note(_ id: UUID?, _ hostname: String) {+            guard let id, map[id] == nil else { return }+            map[id] = hostname+        }+        for entry in entries {+            for citation in Entry.ruleCitations {+                note(entry[keyPath: citation.id], entry.hostname)+            }+        }+        for work in works { note(work.urlIdentityRuleID, work.siteHostname) }+        return map     }      // MARK: - V4 Record Mappers -    internal static func mapV4EntryRecord(_ entry: Entry) throws -> BackupV4Entry {+    /// `rewrites` carries the union's rule-id → version map, so a citation of a+    /// rule the projection renumbered is archived at the version the archive+    /// actually holds (Decision 7). Without it the verify-decode would reject+    /// every duplicated hostname's entries.+    ///+    /// The seven `version(…)` calls below are the one place `Entry.ruleCitations`+    /// does not drive: `BackupV4Entry` is a `let`-only struct built by one+    /// memberwise initializer, so its citation fields are named arguments rather+    /// than assignable key paths. Reaching them through the table would mean+    /// building the record and then rewriting it, which is more moving parts than+    /// the enumeration it would remove.+    internal static func mapV4EntryRecord(+        _ entry: Entry, rewrites: [UUID: Int] = [:]+    ) throws -> BackupV4Entry {         let snap = try snapshot(entry)+        func version(_ id: UUID?, _ stored: Int?) -> Int? {+            guard let id else { return stored }+            return rewrites[id] ?? stored+        }         return BackupV4Entry(             id: snap.id,             captureTitle: snap.captureTitle,@@ -99,34 +385,38 @@ extension LibraryRepository: BackupV4SnapshotProviding {             conservativeIdentityKey: entry.conservativeIdentityKey,             identityBasis: EntryIdentityBasis(rawValue: entry.identityBasisRaw) ?? .conservative,             identityURLRuleID: entry.identityURLRuleID,-            identityURLRuleVersion: entry.identityURLRuleVersion,+            identityURLRuleVersion: version(entry.identityURLRuleID, entry.identityURLRuleVersion),             identityNameTitleRuleID: entry.identityNameTitleRuleID,-            identityNameTitleRuleVersion: entry.identityNameTitleRuleVersion,+            identityNameTitleRuleVersion: version(+                entry.identityNameTitleRuleID, entry.identityNameTitleRuleVersion),             urlWorkIdentity: entry.urlWorkIdentity,             urlWorkRuleID: entry.urlWorkRuleID,-            urlWorkRuleVersion: entry.urlWorkRuleVersion,+            urlWorkRuleVersion: version(entry.urlWorkRuleID, entry.urlWorkRuleVersion),             chapterSequence: entry.chapterSequence,             chapterSequenceRuleID: entry.chapterSequenceRuleID,-            chapterSequenceRuleVersion: entry.chapterSequenceRuleVersion,+            chapterSequenceRuleVersion: version(+                entry.chapterSequenceRuleID, entry.chapterSequenceRuleVersion),             chapterTitle: snap.chapterTitle,-            chapterTitleProvenance: snap.chapterTitleProvenance,+            chapterTitleProvenance: try rewritten(snap.chapterTitleProvenance, rewrites),             note: snap.note,             rating: snap.rating,             firstCapturedAt: snap.firstCapturedAt,             lastSharedAt: snap.lastSharedAt,             modifiedAt: snap.modifiedAt,             workID: snap.workID,-            workAssignmentProvenance: snap.workAssignmentProvenance,+            workAssignmentProvenance: try rewritten(snap.workAssignmentProvenance, rewrites),             workURLRuleID: entry.workURLRuleID,-            workURLRuleVersion: entry.workURLRuleVersion,+            workURLRuleVersion: version(entry.workURLRuleID, entry.workURLRuleVersion),             workURLAssignmentKind: entry.workURLAssignmentKind,             workPatternID: entry.workPatternID,-            workPatternVersion: entry.workPatternVersion,+            workPatternVersion: version(entry.workPatternID, entry.workPatternVersion),             intentionallyUnattached: snap.intentionallyUnattached         )     } -    internal static func mapV4WorkRecord(_ work: Work) throws -> BackupV4Work {+    internal static func mapV4WorkRecord(+        _ work: Work, rewrites: [UUID: Int] = [:]+    ) throws -> BackupV4Work {         guard let type = WorkType(rawValue: work.typeRaw) else {             throw LibraryRepositoryError.corruptLibrary(operation: "mapping Work for V4 backup", reason: "invalid type")         }@@ -143,7 +433,8 @@ extension LibraryRepository: BackupV4SnapshotProviding {             urlIdentity: work.urlIdentity,             urlIdentityState: work.urlIdentityState,             urlIdentityRuleID: work.urlIdentityRuleID,-            urlIdentityRuleVersion: work.urlIdentityRuleVersion,+            urlIdentityRuleVersion: work.urlIdentityRuleID+                .flatMap { rewrites[$0] } ?? work.urlIdentityRuleVersion,             workURL: work.workURLString,             genericNotes: work.genericNotes,             type: type,@@ -155,69 +446,76 @@ extension LibraryRepository: BackupV4SnapshotProviding {         )     } -    internal static func mapV4SiteRecord(_ site: Site) throws -> BackupV4Site {-        guard SiteMode(rawValue: site.modeRaw) != nil else {-            throw LibraryRepositoryError.corruptLibrary(operation: "mapping Site for V4 backup", reason: "invalid mode")-        }-        let patternIDs = site.patternValues.map(\.id)-            .sorted { $0.uuidString.lowercased() < $1.uuidString.lowercased() }-        let urlRuleIDs = site.urlRuleValues.map(\.id)-            .sorted { $0.uuidString.lowercased() < $1.uuidString.lowercased() }-        return BackupV4Site(-            hostname: site.hostname,-            displayName: site.displayName,-            mode: site.mode,-            patternIDs: patternIDs,-            urlRuleIDs: urlRuleIDs,-            junkSuffixRule: site.junkSuffixRule+    /// The wire Site for a hostname: exactly one, whatever the store holds+    /// (Q38). Its membership lists come from the union, so a hostname carrying+    /// two rows archives every rule both held.+    internal static func mapV4SiteRecord(+        _ projected: SiteUnionProjection.ProjectedSite+    ) -> BackupV4Site {+        BackupV4Site(+            hostname: projected.hostname,+            displayName: projected.displayName,+            mode: projected.mode,+            patternIDs: projected.patterns.map(\.pattern.id)+                .sorted { $0.uuidString.lowercased() < $1.uuidString.lowercased() },+            urlRuleIDs: projected.urlRules.map(\.rule.id)+                .sorted { $0.uuidString.lowercased() < $1.uuidString.lowercased() },+            junkSuffixRule: projected.junkSuffixRule         )     } -    internal static func mapV4TitlePatternRecord(_ pattern: TitlePattern) throws -> BackupV4TitlePattern {-        guard let hostname = pattern.site?.hostname, !hostname.isEmpty else {-            throw LibraryRepositoryError.corruptLibrary(-                operation: "mapping TitlePattern for V4 backup", reason: "pattern has no Site")-        }-        return BackupV4TitlePattern(-            id: pattern.id,-            version: pattern.version,-            isActive: pattern.isActive,-            createdAt: pattern.createdAt,-            definition: try pattern.definition,-            trimPrefix: pattern.trimPrefix,-            trimSuffix: pattern.trimSuffix,+    internal static func mapV4TitlePatternRecord(+        _ projected: SiteUnionProjection.ProjectedTitlePattern, hostname: String+    ) throws -> BackupV4TitlePattern {+        BackupV4TitlePattern(+            id: projected.pattern.id,+            version: projected.version,+            isActive: projected.isActive,+            createdAt: projected.pattern.createdAt,+            definition: try projected.pattern.definition,+            trimPrefix: projected.pattern.trimPrefix,+            trimSuffix: projected.pattern.trimSuffix,             siteHostname: hostname         )     } -    internal static func mapV4URLRuleRecord(_ rule: URLRulePattern) throws -> BackupV4URLRule {-        guard let origin = rule.origin else {-            throw LibraryRepositoryError.corruptLibrary(-                operation: "mapping URLRulePattern for V4 backup", reason: "rule has unknown origin")-        }-        guard let hostname = rule.site?.hostname, !hostname.isEmpty else {-            throw LibraryRepositoryError.corruptLibrary(-                operation: "mapping URLRulePattern for V4 backup", reason: "rule has no Site")-        }-        return BackupV4URLRule(-            id: rule.id,-            version: rule.version,-            isCurrent: rule.isCurrent,-            createdAt: rule.createdAt,-            origin: origin,-            definition: rule.definition,+    internal static func mapV4URLRuleRecord(+        _ projected: SiteUnionProjection.ProjectedURLRule, hostname: String+    ) -> BackupV4URLRule {+        BackupV4URLRule(+            id: projected.rule.id,+            version: projected.version,+            isCurrent: projected.isCurrent,+            createdAt: projected.rule.createdAt,+            // `requireRepresentableValues` already refused an unknown origin, so+            // the fallback here is unreachable rather than a coercion.+            origin: projected.rule.origin ?? .readerTaught,+            definition: projected.rule.definition,             siteHostname: hostname         )     }++    /// A `FieldProvenance` whose cited pattern version follows the union.+    private static func rewritten(+        _ provenance: FieldProvenance, _ rewrites: [UUID: Int]+    ) throws -> FieldProvenance {+        guard let id = provenance.patternID, let version = rewrites[id],+              version != provenance.patternVersion else { return provenance }+        return try FieldProvenance(kind: provenance.kind, patternID: id, patternVersion: version)+    } }  // MARK: - V4 Exporter  /// Orchestrates coherent V4 snapshot → validated Backup V4 encoding → staging. ///-/// Export is V4-only (Req 5.2): it decode-validates its own bytes before-/// sharing, so a produced file is always a valid strict Backup V4 document, and-/// it refuses while any Site is quarantined via the snapshot provider (Req 9.4).+/// Export is V4-only (Req 3.2): it decode-validates its own bytes before sharing,+/// so a produced file is always a valid strict Backup V4 document (Req 3.4).+///+/// That gate should now pass whenever none of the three named refusals fires+/// (3.3, 3.6, 3.7) — the snapshot projection makes the payload total over the+/// ordinary sync states. A decode failure beyond them is a bug, and the+/// round-trip tests treat it as one. public final class BackupV4Exporter: Sendable {     private let repository: any BackupV4SnapshotProviding     private let stagingDirectory: URL

diff --git a/Packages/AsterismCore/Sources/AsterismCore/EntryRuleCitations.swift b/Packages/AsterismCore/Sources/AsterismCore/EntryRuleCitations.swiftnew file mode 100644index 0000000..533cb9f--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/EntryRuleCitations.swift@@ -0,0 +1,73 @@+import Foundation++// MARK: - The seven rule citations an Entry carries++extension Entry {++    /// One `(rule id, rule version)` pair an Entry can carry, described once.+    ///+    /// Four passes used to hand-enumerate the same seven pairs — the reconciler's+    /// citation rewrite, the exporter's citer-hostname collection, its+    /// citations-resolve refusal, and the wire mapper. Adding a rule kind meant+    /// finding all four, and a pass that missed one lost the citation silently:+    /// nothing type-checks a list of field names against a sibling list.+    /// `@unchecked Sendable`, and it has to be: a `KeyPath` is `Sendable` only+    /// when its `Root` is, and `Entry` is a `@Model` class that is deliberately+    /// not. What this holds is four immutable key paths, a case and a literal —+    /// no `Entry` instance and nothing mutable — so the table itself crosses+    /// isolation safely even though a value of its root type would not.+    struct RuleCitation: @unchecked Sendable {+        /// Which table the cited id lives in, and therefore what a resolution+        /// failure means.+        enum Target: Sendable {+            case urlRule+            case titlePattern+        }++        /// The Entry's stored citation, on the live model.+        let id: ReferenceWritableKeyPath<Entry, UUID?>+        let version: ReferenceWritableKeyPath<Entry, Int?>+        /// The same citation on the 4/4 wire record, so the archive's own+        /// refusal reads the same seven pairs the store does.+        let wireID: KeyPath<BackupV4Entry, UUID?>+        let target: Target+        /// How a refusal names this citation to the reader.+        let label: String+    }++    /// The seven pairs, in the order every pass visits them.+    ///+    /// The order is load-bearing in one place — `citerHostnames` keeps the first+    /// hostname it sees for a rule id — so it is fixed here rather than left to+    /// each caller.+    static let ruleCitations: [RuleCitation] = [+        RuleCitation(+            id: \.identityURLRuleID, version: \.identityURLRuleVersion,+            wireID: \.identityURLRuleID, target: .urlRule,+            label: "its identity rule"),+        RuleCitation(+            id: \.identityNameTitleRuleID, version: \.identityNameTitleRuleVersion,+            wireID: \.identityNameTitleRuleID, target: .titlePattern,+            label: "its naming title rule"),+        RuleCitation(+            id: \.urlWorkRuleID, version: \.urlWorkRuleVersion,+            wireID: \.urlWorkRuleID, target: .urlRule,+            label: "its work-extraction rule"),+        RuleCitation(+            id: \.chapterSequenceRuleID, version: \.chapterSequenceRuleVersion,+            wireID: \.chapterSequenceRuleID, target: .urlRule,+            label: "its sequence rule"),+        RuleCitation(+            id: \.chapterPatternID, version: \.chapterPatternVersion,+            wireID: \.chapterTitleProvenance.patternID, target: .titlePattern,+            label: "its chapter rule"),+        RuleCitation(+            id: \.workPatternID, version: \.workPatternVersion,+            wireID: \.workPatternID, target: .titlePattern,+            label: "its work rule"),+        RuleCitation(+            id: \.workURLRuleID, version: \.workURLRuleVersion,+            wireID: \.workURLRuleID, target: .urlRule,+            label: "its work URL rule"),+    ]+}

diff --git a/Packages/AsterismCore/Sources/AsterismCore/IdentityResolution.swift b/Packages/AsterismCore/Sources/AsterismCore/IdentityResolution.swiftindex ac359e0..7a838e5 100644--- a/Packages/AsterismCore/Sources/AsterismCore/IdentityResolution.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/IdentityResolution.swift@@ -81,6 +81,20 @@ public enum SiteResolutionOrder {     /// (no pattern, rule 5) cycle under it, which is undefined behaviour in     /// `sorted(by:)`.     private static func precedes(_ lhs: SiteOrderKey, _ rhs: SiteOrderKey) -> Bool {+        if let ordered = syncedContentOrder(lhs, rhs) { return ordered }+        return IdentityTiebreak.precedes(lhs.identifier, rhs.identifier)+    }++    /// Steps 1–4 alone — the ones that read *synced* content — or nil when they+    /// all tie and only step 5 is left.+    ///+    /// Split out because Decision 5 turns on exactly this distinction: a merge+    /// may move rule custody only where synced content picks the winner, since+    /// the step-5 tiebreak is a `PersistentIdentifier` and two devices assign+    /// different ones to the same logical rows. Selecting a *presentation*+    /// winner on it is fine and necessary; writing against it makes each device+    /// pin the hostname to the row the other did not.+    private static func syncedContentOrder(_ lhs: SiteOrderKey, _ rhs: SiteOrderKey) -> Bool? {         // Reading `patterns` faults one relationship; `urlRules` is left alone         // unless step 1 ties, and neither is read twice for the same row.         let lhsPatterns = lhs.patterns@@ -94,8 +108,22 @@ public enum SiteResolutionOrder {         if let ordered = orderedAbsentLast(lhsPatterns.lowestID, rhsPatterns.lowestID) {             return ordered         }-        if let ordered = orderedAbsentLast(lhsRules.lowestID, rhsRules.lowestID) { return ordered }-        return IdentityTiebreak.precedes(lhs.identifier, rhs.identifier)+        return orderedAbsentLast(lhsRules.lowestID, rhsRules.lowestID)+    }++    /// Whether the synced-content steps separate these two rows at all+    /// (Decision 5).+    ///+    /// The reconciler asks this before moving anything: two rows owning nothing,+    /// or owning rules that share their UUIDs (the `.duplicateIdentity`+    /// tolerated state), tie all the way to step 5, and a custody move decided+    /// there is a move each device makes in the opposite direction — they re-pin+    /// against each other for as long as neither gains distinguishing content.+    /// Export is unaffected: a snapshot still needs exactly one wire Site per+    /// hostname, and picking it by tiebreak is harmless because export writes+    /// nothing back.+    internal static func distinguishedBySyncedContent(_ lhs: Site, _ rhs: Site) -> Bool {+        syncedContentOrder(SiteOrderKey(lhs), SiteOrderKey(rhs)) != nil     }      /// `nil` means "these two are equal at this step, continue"; absence is

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryConfiguration.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryConfiguration.swiftindex 3a89d9a..d3b038c 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryConfiguration.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryConfiguration.swift@@ -24,10 +24,34 @@ public struct LibraryConfiguration: Sendable, Equatable {         storeURL.deletingLastPathComponent().appending(path: migrationSidecarFilename)     } +    // MARK: - Mirroring artefacts (Q34)++    /// Persisted sync status, JSON, beside the readiness marker. The project+    /// keeps cross-launch state in files rather than `UserDefaults`, and these+    /// two follow that pattern.+    public static let syncStatusFilename = "AsterismSync.status"++    /// Req 4.4. Written before an import's first save and removed after its last,+    /// so an import that stops partway is reportable however long ago it stopped.+    public static let importSidecarFilename = "AsterismImport.inProgress"+     public let rootDirectory: URL -    public init(rootDirectory: URL) {+    /// The CloudKit container this process mirrors into, or nil when mirroring+    /// is impossible.+    ///+    /// Injected, never composed here (configuration-identity Decision 2, Q51):+    /// the app reads the value its own bundle declares and hands it in, so the+    /// package holds no identifier literal for the lint to find. nil is the+    /// default and the only value every non-app caller can produce — host+    /// tests, UI-test temporary roots, the migration helpers and the share+    /// extension all open with mirroring off because none of them has a bundle+    /// carrying the key.+    public let cloudKitContainerID: String?++    public init(rootDirectory: URL, cloudKitContainerID: String? = nil) {         self.rootDirectory = rootDirectory+        self.cloudKitContainerID = cloudKitContainerID     }      public var storeURL: URL {@@ -70,6 +94,19 @@ public struct LibraryConfiguration: Sendable, Equatable {     public var migrationSidecarURL: URL {         Self.migrationSidecarURL(forStoreAt: v4StoreURL)     }++    // MARK: - Mirroring paths++    /// Where `SyncMonitor` persists what it last observed (Q34).+    public var syncStatusURL: URL {+        rootDirectory.appending(path: Self.syncStatusFilename)+    }++    /// Written before an import's first save and removed after its last, so an+    /// interrupted import is reportable however long afterwards (Req 4.4).+    public var importSidecarURL: URL {+        rootDirectory.appending(path: Self.importSidecarFilename)+    } }  // MARK: - Declared identity@@ -82,30 +119,116 @@ public struct LibraryConfiguration: Sendable, Equatable { /// The bundle (or its info dictionary) is an explicit parameter: the package /// reads no ambient `Bundle.main` and sniffs no environment, so host tests /// exercise exactly the production code path with fixture dictionaries (Q11,-/// Decision 1). There is no reader for the CloudKit container identifier — the-/// build carries the value, and the mirroring work adds consumption when it-/// needs it.+/// Decision 1). public extension LibraryConfiguration {     /// The Info.plist key each product's bundle carries.     static let appGroupInfoPlistKey = "AsterismAppGroupIdentifier" +    /// The app's CloudKit container identifier, derived from the same+    /// `ASTERISM_IDENTITY` token as the App Group. Only the app carries it —+    /// the extension never mirrors (Req 5.1).+    static let cloudKitContainerInfoPlistKey = "AsterismCloudKitContainerIdentifier"++    /// The per-configuration mirroring gate, surfaced from the project-level+    /// `ASTERISM_MIRRORING_ENABLED` build setting (Q51).+    static let mirroringEnabledInfoPlistKey = "AsterismCloudKitMirroringEnabled"+     /// Resolves the declared App Group identifier, or throws naming the key.     ///     /// Never falls back to a default (Req 2.3): a missing, empty, non-string, or     /// unexpanded value can only mean a build defect, and guessing an identifier     /// would point the process at the wrong library.     static func declaredAppGroupIdentifier(fromInfoDictionary dictionary: [String: Any]?) throws -> String {+        try declaredIdentifier(+            forKey: appGroupInfoPlistKey,+            operation: "resolving the declared App Group identifier",+            fromInfoDictionary: dictionary+        )+    }++    /// Resolves the declared App Group identifier from a bundle's Info.plist.+    /// An extension's `Bundle.main` is its `.appex`, so each product resolves its+    /// own derived value (Req 2.1).+    static func declaredAppGroupIdentifier(in bundle: Bundle) throws -> String {+        try declaredAppGroupIdentifier(fromInfoDictionary: bundle.infoDictionary)+    }++    /// Resolves the declared CloudKit container identifier, or throws naming the+    /// key — the same contract as the App Group reader, for the same reason: a+    /// guessed container identifier would mirror one configuration's library+    /// into the other's container (Req 7.1, 7.2).+    ///+    /// Read only when the mirroring flag says yes; a build with mirroring off+    /// never asks, so a missing key there is not an error.+    static func declaredCloudKitContainerIdentifier(fromInfoDictionary dictionary: [String: Any]?) throws -> String {+        try declaredIdentifier(+            forKey: cloudKitContainerInfoPlistKey,+            operation: "resolving the declared CloudKit container identifier",+            fromInfoDictionary: dictionary+        )+    }++    static func declaredCloudKitContainerIdentifier(in bundle: Bundle) throws -> String {+        try declaredCloudKitContainerIdentifier(fromInfoDictionary: bundle.infoDictionary)+    }++    /// Whether this build's bundle declares mirroring enabled.+    ///+    /// Deliberately unlike the identifier readers: it answers rather than+    /// throws. Absent, empty, unexpanded, or unrecognised all read as *off*,+    /// because "off" is the state every process that cannot mirror is already+    /// in — host tests, UI-test roots, the migration helpers and the share+    /// extension carry no such key at all — and because a mistake here must+    /// degrade sync, never the library (Q44). Only an explicitly affirmative+    /// declaration turns mirroring on.+    ///+    /// `INFOPLIST_EXPAND_BUILD_SETTINGS` substitutes the build setting as text,+    /// so `ASTERISM_MIRRORING_ENABLED = YES` arrives as the string `"YES"`; a+    /// hand-written `<true/>` is accepted too.+    static func declaredMirroringEnabled(fromInfoDictionary dictionary: [String: Any]?) -> Bool {+        guard let value = dictionary?[mirroringEnabledInfoPlistKey] else { return false }+        if let flag = value as? Bool { return flag }+        guard let text = value as? String else { return false }+        switch text.trimmingCharacters(in: .whitespaces).lowercased() {+        case "yes", "true", "1": return true+        default: return false+        }+    }++    static func declaredMirroringEnabled(in bundle: Bundle) -> Bool {+        declaredMirroringEnabled(fromInfoDictionary: bundle.infoDictionary)+    }++    /// The container identifier this build should mirror into, or nil when its+    /// configuration has mirroring off — the value `cloudKitContainerID` takes.+    ///+    /// The flag is read first so a mirroring-off build never reaches the+    /// throwing reader: the two declarations are independent, and only a build+    /// that has asked to mirror is failed by a missing container id.+    static func declaredMirroringContainerIdentifier(+        fromInfoDictionary dictionary: [String: Any]?+    ) throws -> String? {+        guard declaredMirroringEnabled(fromInfoDictionary: dictionary) else { return nil }+        return try declaredCloudKitContainerIdentifier(fromInfoDictionary: dictionary)+    }++    static func declaredMirroringContainerIdentifier(in bundle: Bundle) throws -> String? {+        try declaredMirroringContainerIdentifier(fromInfoDictionary: bundle.infoDictionary)+    }++    private static func declaredIdentifier(+        forKey key: String,+        operation: String,+        fromInfoDictionary dictionary: [String: Any]?+    ) throws -> String {         func unavailable(_ reason: String) -> LibraryRepositoryError {-            .libraryUnavailable(-                operation: "resolving the declared App Group identifier",-                reason: "\(appGroupInfoPlistKey) \(reason)"-            )+            .libraryUnavailable(operation: operation, reason: "\(key) \(reason)")         }          guard let dictionary else {             throw unavailable("could not be read: the bundle has no info dictionary")         }-        guard let value = dictionary[appGroupInfoPlistKey] else {+        guard let value = dictionary[key] else {             throw unavailable("is missing from the bundle's Info.plist")         }         guard let identifier = value as? String else {@@ -121,11 +244,4 @@ public extension LibraryConfiguration {         }         return identifier     }--    /// Resolves the declared App Group identifier from a bundle's Info.plist.-    /// An extension's `Bundle.main` is its `.appex`, so each product resolves its-    /// own derived value (Req 2.1).-    static func declaredAppGroupIdentifier(in bundle: Bundle) throws -> String {-        try declaredAppGroupIdentifier(fromInfoDictionary: bundle.infoDictionary)-    } }

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryDiagnostics.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryDiagnostics.swiftindex acf8b2d..ef2fb6a 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryDiagnostics.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryDiagnostics.swift@@ -180,28 +180,27 @@ public struct LibraryDiagnostics: Equatable, Sendable {         return result     } -    /// Q12. `.siteTuple` and `.duplicateSiteRows` quarantine their hostname;-    /// `.siteMissing` does not, because no Site row exists to quarantine and an-    /// untaught hostname is a state every path already handles; and-    /// `.duplicateIdentity` does not, because a duplicate application UUID is-    /// not a property of a hostname's teaching state.+    /// **Quarantine is `.siteTuple` alone** (Q36, Req 2.3).+    ///+    /// A quarantine disables rule application on capture and gates every path+    /// that assumes a legal current state, so it belongs to record-local damage+    /// — an unrecognised enum raw value, a blank required value — which no+    /// arriving record and no pass can repair.+    ///+    /// `.duplicateSiteRows` used to quarantine and no longer does: the app now+    /// repairs it on its own (`SiteReconciler`), and a state the app repairs is+    /// not a state to disable capture parsing over. Teaching a duplicated+    /// hostname targets the deterministic winner instead of being refused (Q39),+    /// and the Check Library row for it becomes informational.     ///-    /// A hostname can carry both quarantining diagnoses. The map holds one-    /// reason per hostname and `.siteTuple` sorts first, so the tuple reason-    /// wins — it is the one the reader can act on by re-teaching.+    /// `.siteMissing` never quarantined — there is no Site row to quarantine and+    /// an untaught hostname is a state every path already handles — and+    /// `.duplicateIdentity` never did, because a duplicate application UUID is+    /// not a property of a hostname's teaching state.     public func quarantineMap() -> [String: V4ValidationError] {         var map: [String: V4ValidationError] = [:]-        for diagnosis in diagnoses {-            switch diagnosis {-            case .siteTuple(let hostname, let reason):-                if map[hostname] == nil { map[hostname] = reason }-            case .duplicateSiteRows(let hostname, _):-                // The reason `uniqueSites` throws today, so the payload a-                // quarantine consumer sees is unchanged by the demotion.-                if map[hostname] == nil { map[hostname] = .duplicate(type: "Site", id: hostname) }-            case .siteMissing, .duplicateIdentity:-                continue-            }+        for case .siteTuple(let hostname, let reason) in diagnoses where map[hostname] == nil {+            map[hostname] = reason         }         return map     }@@ -234,22 +233,6 @@ public struct LibraryDiagnostics: Equatable, Sendable {             suggestsDamage: shapeSuggestsDamage(combined, shape: shape))     } -    /// The records a 4/4 archive cannot represent coherently: the two tolerated-    /// states that do not quarantine (Q17). Counted the same distinct way as-    /// `affectedRecordCount`, so a record in both states counts once.-    ///-    /// Backup export's pre-check reads this. The quarantining states are already-    /// refused by the gate that predates this milestone, and `.siteTuple` in-    /// particular is repairable by re-teaching, so it is not counted here.-    public var unresolvedRecordCount: Int {-        Self.distinctRecordCount(diagnoses.filter {-            switch $0 {-            case .siteMissing, .duplicateIdentity: true-            case .siteTuple, .duplicateSiteRows: false-            }-        })-    }-     /// Rewrites one hostname's tuple diagnosis, leaving every other diagnosis     /// alone. Used after a teaching commit, which re-validates the whole graph     /// and so knows the current answer for the hostname it wrote — without it

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swiftindex 3088f17..d9950c8 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift@@ -34,6 +34,48 @@ public protocol LibraryProviding: Sendable {     /// in either process (Req 1.6).     func refreshDiagnostics() async throws +    /// Makes the Site graph coherent after records arrive from sync (Req 1.7).+    ///+    /// On the protocol for the same reason `refreshDiagnostics()` is: the app is+    /// the caller, it holds `any LibraryProviding`, and the remote-change+    /// debounce runs this immediately before the refresh.+    @discardableResult+    func reconcileAfterSync() async throws -> SiteReconciliationOutcome++    // MARK: - Backup import++    /// The library's current record counts, for the import preview.+    ///+    /// `debugCounts()` is the name this had while nothing but a test read it, and+    /// it survives as the requirement so the test doubles written against it keep+    /// conforming unchanged. Production reads `recordCounts()`.+    func debugCounts() async throws -> LibraryRecordCounts++    /// The library's current record counts. What every production caller uses.+    func recordCounts() async throws -> LibraryRecordCounts++    /// Applies an archive: adds what is missing, updates what is older, deletes+    /// nothing (Decision 2).+    ///+    /// On the protocol because the confirm surface runs on the live repository+    /// the app already holds — the static commit paths it replaces each opened a+    /// second container over the same store (Q37).+    @discardableResult+    func confirmImport(+        plan: BackupImportV4Plan, archiveName: String?+    ) async throws -> BackupImportCommitResult++    /// What an interrupted import left behind, or nil (Req 4.4).+    ///+    /// On the protocol because the sidecar is written for a *reader* to be told+    /// about, and the app is the only thing with a surface to tell them on. The+    /// repository writes it before the first save and removes it after the last;+    /// without a caller here it was a file nothing ever read.+    ///+    /// Reported however old: a sidecar from a month ago still means that import+    /// did not finish, and time does not make that untrue.+    func interruptedImport() async -> InterruptedImportReport?+     // MARK: - Curation (non-teaching writes)     func updateEntry(id: UUID, note: String, rating: Rating?) async throws     func deleteEntry(id: UUID) async throws@@ -120,6 +162,23 @@ public protocol LibraryProviding: Sendable {      /// Commit an approved Merge contract.     func commitMerge(_ contract: WorkMergeContract) async throws -> WorkMergeCommitOutcome++    // MARK: - Teardown++    /// Releases whatever this provider holds open, so a re-open is the only+    /// live claim on the store (Q43).+    ///+    /// On the protocol because `AppLibraryModel` holds `any LibraryProviding`+    /// and is the caller: it awaits this before every re-`bootstrap()`. Default+    /// no-op — a test double holds nothing to release.+    func shutdown() async+}++public extension LibraryProviding {+    func shutdown() async {}++    /// A conformer that only implements the old name still answers the new one.+    func recordCounts() async throws -> LibraryRecordCounts { try await debugCounts() } }  extension LibraryRepository: LibraryProviding {}

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImport.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImport.swiftindex a4f0068..15b65e1 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImport.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImport.swift@@ -1,304 +1,107 @@ import Foundation-import OSLog import SwiftData -// MARK: - LibraryRepository Backup Import Extension (V4 commit path)--/// The runtime import-commit path is V4 (Decision 2, task 25): every accepted-/// source version is mapped to a prospective `BackupImportV4Plan` outside the-/// actor, and these methods materialize it into the fixed-path V4 store under the-/// exclusive lease and validate with `V4LibraryValidator`. Both commit into an-/// already-ready library: the bootstrap publishes the readiness marker when it-/// creates the store, so import is a Settings action, never a first-run one. The-/// frozen V2/V3 codecs and the V2→V3 / V3→V4 mappers are import-only and-/// untouched; only the live commit path switched to V4.+// MARK: - Backup import: the materialisation half++/// The runtime import-commit path is `confirmImport` on the actor+/// (`LibraryRepository+ConfirmImport.swift`). What is left here is+/// `materializeV4Payload`, which builds a whole payload into a *fresh, empty*+/// context — used by the import-plan gate, which validates a prospective graph in+/// an in-memory store before the reader is asked to confirm anything.+///+/// The two static commit paths this file used to hold are gone (Q37):+///+/// - `confirmImportFillEmpty` and `confirmImportReplace` both opened a second+///   `ModelContainer` over the live store. Beside a mirroring container that is+///   the in-process 134422 collision (Q24), and their writes would have reached+///   the mirror only through history replay.+/// - `confirmImportReplace` deleted every entity first. Under mirroring each of+///   those deletions exports and destroys the same records on every other device,+///   including everything captured since the archive was taken (Decision 2).+/// - `computeInventoryFingerprint` hashed the full entity id set at preview and+///   re-compared it at commit, so on any device receiving sync traffic the+///   confirm step could never succeed (Req 4.5). extension LibraryRepository {-    private static let importLogger = Logger(subsystem: "me.nore.ig.Asterism", category: "BackupImport")--    // MARK: - Confirm Import (Fill Empty)--    /// Commits a V4 import plan into a ready but empty V4 library.-    public static func confirmImportFillEmpty(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        capabilities: AsterismCapabilities = .m4,-        clock: any RepositoryClock = SystemRepositoryClock(),-        saveStrategy: any RepositorySaveStrategy = ModelContextSaveStrategy()-    ) async throws -> BackupImportCommitResult {-        Self.importLogger.debug("Confirming import fill-empty")--        guard capabilities.gate == .m4 else {-            throw LibraryRepositoryError.invalidInput(-                operation: "confirming import fill",-                reason: "V4 library transitions require the m4 capability gate, got \(capabilities.gate.rawValue)"-            )-        }--        let fileManager = FileManager.default--        let lease = try await CrossProcessLibraryLock.acquire(-            mode: .exclusive,-            at: configuration.lockURL,-            timeout: .seconds(5)-        )-        defer { withExtendedLifetime(lease) {} }--        let markerExists = fileManager.fileExists(atPath: configuration.v4MarkerURL.path)-        let storeExists = fileManager.fileExists(atPath: configuration.v4StoreURL.path)--        Self.importLogger.debug("Fill import: store=\(storeExists) marker=\(markerExists)")--        guard storeExists, markerExists else {-            return .stale(reason: "expected ready empty store, but state changed")-        }--        let container: ModelContainer-        do {-            container = try openV4Container(at: configuration.v4StoreURL)-        } catch {-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "opening V4 store for import",-                reason: String(describing: error)-            )-        }--        let context = ModelContext(container)-        let currentCounts = try v3Counts(context: context)-        guard currentCounts == .zero else {-            Self.importLogger.debug("Fill import: store not empty — stale")-            return .stale(reason: "library is not empty; cannot fill")-        }--        // Imported pattern forms must be usable at the running capability gate.-        for pattern in plan.payload.titlePatterns {-            do { try capabilities.validate(patternDefinition: pattern.definition) }-            catch {-                throw LibraryRepositoryError.invalidInput(-                    operation: "validating imported pattern forms",-                    reason: String(describing: error)-                )-            }-        }--        let freshContext = ModelContext(container)-        do {-            try materializeV4Payload(plan.payload, into: freshContext)-        } catch {-            Self.importLogger.error("Fill import: materialization failed: \(String(describing: error))")-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "materializing import plan",-                reason: String(describing: error)-            )-        }--        // Strict: an imported library must be wholly legal, so the three states-        // the open paths tolerate from this milestone on still fail here-        // (Decision 3).-        let diagnoses = try validateV4StoreStrictly(context: freshContext)-        guard diagnoses.isEmpty else {-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "validating materialized import",-                reason: "imported library is not wholly legal: \(diagnoses.sorted { $0.key < $1.key }.first!.value)"-            )-        }--        let materializedCounts = try v3Counts(context: freshContext)-        guard materializedCounts == plan.counts else {-            throw BackupImportError.planMismatch(-                reason: "materialized counts \(materializedCounts) != plan counts \(plan.counts)"-            )-        }--        do {-            try saveStrategy.save(freshContext)-        } catch {-            Self.importLogger.error("Fill import: save failed: \(String(describing: error))")-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "saving import",-                reason: String(describing: error)-            )-        }--        // Readiness is already published — the guard above required the marker,-        // and the bootstrap publishes it when it creates the store.-        try? fileManager.removeItem(at: configuration.v3MarkerURL)--        Self.importLogger.debug("Fill import: committed \(materializedCounts.entries) entries")-        return .committed(materializedCounts)-    }--    // MARK: - Confirm Import (Destructive Replace)--    /// Commits a destructive replacement of the entire V4 library.-    public static func confirmImportReplace(-        _ configuration: LibraryConfiguration,-        plan: BackupImportV4Plan,-        expectedInventory: LibraryInventoryFingerprint,-        capabilities: AsterismCapabilities = .m4,-        clock: any RepositoryClock = SystemRepositoryClock(),-        saveStrategy: any RepositorySaveStrategy = ModelContextSaveStrategy()-    ) async throws -> BackupImportCommitResult {-        Self.importLogger.debug("Confirming destructive replacement import")--        guard capabilities.gate == .m4 else {-            throw LibraryRepositoryError.invalidInput(-                operation: "confirming import replacement",-                reason: "V4 library transitions require the m4 capability gate, got \(capabilities.gate.rawValue)"-            )-        }--        let fileManager = FileManager.default--        let lease = try await CrossProcessLibraryLock.acquire(-            mode: .exclusive,-            at: configuration.lockURL,-            timeout: .seconds(5)-        )-        defer { withExtendedLifetime(lease) {} }--        let markerExists = fileManager.fileExists(atPath: configuration.v4MarkerURL.path)-        let storeExists = fileManager.fileExists(atPath: configuration.v4StoreURL.path)--        Self.importLogger.debug("Replace import: store=\(storeExists) marker=\(markerExists)")--        guard storeExists, markerExists else {-            return .stale(reason: "expected ready store for replacement, but state changed")-        }--        try validateMarkerContentForApp(at: configuration.v4MarkerURL)--        let container: ModelContainer-        do {-            container = try openV4Container(at: configuration.v4StoreURL)-        } catch {-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "opening V4 store for replacement",-                reason: String(describing: error)+    /// Materializes a complete `BackupV4Payload` into a context. Does NOT save —+    /// the caller validates and saves. The V4 backup omits the M3 interpretation+    /// and site-level trim columns, so those live-store columns are left nil.+    ///+    /// Assumes an empty context: it inserts unconditionally. The live path is the+    /// upsert, which matches first.+    static func materializeV4Payload(+        _ payload: BackupV4Payload,+        into context: ModelContext+    ) throws {+        var sitesByHostname: [String: Site] = [:]+        for record in payload.sites {+            let site = Site(hostname: record.hostname, displayName: record.displayName)+            site.modeRaw = record.mode.rawValue+            site.junkSuffixRule = record.junkSuffixRule+            context.insert(site)+            sitesByHostname[record.hostname] = site+        }++        for record in payload.titlePatterns {+            let pattern = try TitlePattern(+                id: record.id,+                version: record.version,+                isActive: record.isActive,+                createdAt: record.createdAt,+                definition: record.definition,+                site: sitesByHostname[record.siteHostname]             )-        }--        let context = ModelContext(container)-        let currentFingerprint = try computeInventoryFingerprint(context: context)-        guard currentFingerprint == expectedInventory else {-            Self.importLogger.debug("Replace import: inventory changed — stale")-            return .stale(reason: "library inventory changed since preview; refresh required")-        }--        for pattern in plan.payload.titlePatterns {-            do { try capabilities.validate(patternDefinition: pattern.definition) }-            catch {-                throw LibraryRepositoryError.invalidInput(-                    operation: "validating imported pattern forms",-                    reason: String(describing: error)-                )-            }-        }--        let freshContext = ModelContext(container)-        do {-            try deleteAllEntities(in: freshContext)-            try materializeV4Payload(plan.payload, into: freshContext)-        } catch {-            Self.importLogger.error("Replace import: materialization failed: \(String(describing: error))")-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "materializing replacement import",-                reason: String(describing: error)+            pattern.trimPrefix = record.trimPrefix+            pattern.trimSuffix = record.trimSuffix+            context.insert(pattern)+        }++        for record in payload.urlRules {+            let rule = try URLRulePattern(+                id: record.id,+                version: record.version,+                isCurrent: record.isCurrent,+                createdAt: record.createdAt,+                origin: record.origin,+                definition: record.definition,+                site: sitesByHostname[record.siteHostname]             )+            context.insert(rule)         } -        // Strict, for the same reason as the fill-empty gate above.-        let diagnoses = try validateV4StoreStrictly(context: freshContext)-        guard diagnoses.isEmpty else {-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "validating replacement import",-                reason: "imported library is not wholly legal: \(diagnoses.sorted { $0.key < $1.key }.first!.value)"+        var worksByID: [UUID: Work] = [:]+        for record in payload.works {+            let work = Work(+                id: record.id,+                displayTitle: record.displayTitle,+                siteHostname: record.siteHostname,+                timestamp: record.createdAt             )-        }--        let materializedCounts = try v3Counts(context: freshContext)-        guard materializedCounts == plan.counts else {-            throw BackupImportError.planMismatch(-                reason: "replacement counts \(materializedCounts) != plan counts \(plan.counts)"-            )-        }--        do {-            try saveStrategy.save(freshContext)-        } catch {-            Self.importLogger.error("Replace import: save failed: \(String(describing: error))")-            throw LibraryRepositoryError.libraryUnavailable(-                operation: "saving replacement import",-                reason: String(describing: error)+            context.insert(work)+            // The same applier the upsert uses, so an inserted record and an+            // updated one cannot drift apart.+            apply(record, to: work)+            // Req 2.5: an archive references its Site by hostname, so the+            // relationship is derived from exactly that — the same map the rules+            // above are wired from.+            work.site = sitesByHostname[record.siteHostname]+            worksByID[record.id] = work+        }++        for record in payload.entries {+            let entry = Entry(+                id: record.id,+                captureTitle: record.captureTitle,+                captureTitleSource: record.captureTitleSource,+                rawURLString: record.rawURL,+                canonicalURLString: record.canonicalURL,+                hostname: record.hostname,+                entryIdentityKey: record.entryIdentityKey,+                timestamp: record.firstCapturedAt             )+            context.insert(entry)+            apply(record, to: entry)+            entry.site = sitesByHostname[record.hostname]+            entry.work = record.workID.flatMap { worksByID[$0] }         }--        Self.importLogger.debug("Replace import: committed \(materializedCounts.entries) entries")-        return .committed(materializedCounts)-    }--    // MARK: - Inventory Fingerprint--    /// Computes a fingerprint of the current library inventory for stale detection.-    public static func computeInventoryFingerprint(-        configuration: LibraryConfiguration-    ) async throws -> LibraryInventoryFingerprint {-        let container = try openV4Container(at: configuration.v4StoreURL)-        let context = ModelContext(container)-        return try computeInventoryFingerprint(context: context)     }--    // MARK: - Private Helpers--    private static func computeInventoryFingerprint(-        context: ModelContext-    ) throws -> LibraryInventoryFingerprint {-        let counts = try v3Counts(context: context)--        var ids: [String] = []-        for entry in try context.fetch(FetchDescriptor<Entry>()) {-            ids.append("e:\(entry.id.uuidString.lowercased())")-        }-        for work in try context.fetch(FetchDescriptor<Work>()) {-            ids.append("w:\(work.id.uuidString.lowercased())")-        }-        for site in try context.fetch(FetchDescriptor<Site>()) {-            ids.append("s:\(site.hostname)")-        }-        for pattern in try context.fetch(FetchDescriptor<TitlePattern>()) {-            ids.append("p:\(pattern.id.uuidString.lowercased())")-        }-        for rule in try context.fetch(FetchDescriptor<URLRulePattern>()) {-            ids.append("r:\(rule.id.uuidString.lowercased())")-        }-        ids.sort()-        let signature = ids.joined(separator: "|")--        return LibraryInventoryFingerprint(counts: counts, entitySignature: signature)-    }--    /// Deletes all entities in the context for destructive replacement.-    private static func deleteAllEntities(in context: ModelContext) throws {-        for entry in try context.fetch(FetchDescriptor<Entry>()) {-            context.delete(entry)-        }-        for work in try context.fetch(FetchDescriptor<Work>()) {-            context.delete(work)-        }-        for pattern in try context.fetch(FetchDescriptor<TitlePattern>()) {-            context.delete(pattern)-        }-        for rule in try context.fetch(FetchDescriptor<URLRulePattern>()) {-            context.delete(rule)-        }-        for site in try context.fetch(FetchDescriptor<Site>()) {-            context.delete(site)-        }-    }-}--// MARK: - LibraryProviding Extension--extension LibraryProviding {-    // Default implementations are provided on the protocol extension-    // so existing conformers don't need to add them immediately. }

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImportV4.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImportV4.swiftindex 8563c11..f365c0d 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImportV4.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+BackupImportV4.swift@@ -36,125 +36,4 @@ extension LibraryRepository {         }         return try v3Counts(context: context)     }--    /// Materializes a complete `BackupV4Payload` into a ModelContext. Does NOT-    /// save — the caller validates and saves. The V4 backup omits the M3-    /// interpretation and site-level trim columns, so those live-store columns-    /// are left nil.-    static func materializeV4Payload(-        _ payload: BackupV4Payload,-        into context: ModelContext-    ) throws {-        var sitesByHostname: [String: Site] = [:]-        for record in payload.sites {-            let site = Site(hostname: record.hostname, displayName: record.displayName)-            site.modeRaw = record.mode.rawValue-            site.junkSuffixRule = record.junkSuffixRule-            context.insert(site)-            sitesByHostname[record.hostname] = site-        }--        for record in payload.titlePatterns {-            let site = sitesByHostname[record.siteHostname]-            let pattern = try TitlePattern(-                id: record.id,-                version: record.version,-                isActive: record.isActive,-                createdAt: record.createdAt,-                definition: record.definition,-                site: site-            )-            pattern.trimPrefix = record.trimPrefix-            pattern.trimSuffix = record.trimSuffix-            context.insert(pattern)-        }--        for record in payload.urlRules {-            let site = sitesByHostname[record.siteHostname]-            let rule = try URLRulePattern(-                id: record.id,-                version: record.version,-                isCurrent: record.isCurrent,-                createdAt: record.createdAt,-                origin: record.origin,-                definition: record.definition,-                site: site-            )-            context.insert(rule)-        }--        var worksByID: [UUID: Work] = [:]-        for record in payload.works {-            let work = Work(-                id: record.id,-                displayTitle: record.displayTitle,-                siteHostname: record.siteHostname,-                timestamp: record.createdAt-            )-            work.lastParsedTitle = record.lastParsedTitle-            work.urlIdentity = record.urlIdentity-            work.urlIdentityStateRaw = record.urlIdentityState.rawValue-            work.urlIdentityRuleID = record.urlIdentityRuleID-            work.urlIdentityRuleVersion = record.urlIdentityRuleVersion-            work.workURLString = record.workURL-            work.genericNotes = record.genericNotes-            work.typeRaw = record.type.rawValue-            work.genreTags = record.genreTags-            work.titleProvenanceRaw = record.titleProvenance.rawValue-            work.modifiedAt = record.modifiedAt-            context.insert(work)-            // Req 2.5: an archive references its Site by hostname, so the-            // relationship is derived from exactly that — the same map the-            // rules above are wired from. Nothing republishes the readiness-            // marker after an import, so the relationship pass never runs over-            // what this writes; if it were left nil here it would stay nil-            // forever (Decision 2).-            work.site = sitesByHostname[record.siteHostname]-            worksByID[record.id] = work-        }--        for record in payload.entries {-            let entry = Entry(-                id: record.id,-                captureTitle: record.captureTitle,-                captureTitleSource: record.captureTitleSource,-                rawURLString: record.rawURL,-                canonicalURLString: record.canonicalURL,-                hostname: record.hostname,-                entryIdentityKey: record.entryIdentityKey,-                timestamp: record.firstCapturedAt,-                note: record.note,-                rating: record.rating,-                work: record.workID.flatMap { worksByID[$0] }-            )-            entry.identityKeyVersion = record.identityKeyVersion-            entry.conservativeIdentityKey = record.conservativeIdentityKey-            entry.identityBasisRaw = record.identityBasis.rawValue-            entry.identityURLRuleID = record.identityURLRuleID-            entry.identityURLRuleVersion = record.identityURLRuleVersion-            entry.identityNameTitleRuleID = record.identityNameTitleRuleID-            entry.identityNameTitleRuleVersion = record.identityNameTitleRuleVersion-            entry.urlWorkIdentity = record.urlWorkIdentity-            entry.urlWorkRuleID = record.urlWorkRuleID-            entry.urlWorkRuleVersion = record.urlWorkRuleVersion-            entry.chapterSequence = record.chapterSequence-            entry.chapterSequenceRuleID = record.chapterSequenceRuleID-            entry.chapterSequenceRuleVersion = record.chapterSequenceRuleVersion-            entry.chapterTitle = record.chapterTitle-            entry.chapterTitleProvenanceRaw = record.chapterTitleProvenance.kind.rawValue-            entry.chapterPatternID = record.chapterTitleProvenance.patternID-            entry.chapterPatternVersion = record.chapterTitleProvenance.patternVersion-            entry.lastSharedAt = record.lastSharedAt-            entry.modifiedAt = record.modifiedAt-            entry.workAssignmentProvenanceRaw = record.workAssignmentProvenance.kind.rawValue-            entry.workPatternID = record.workPatternID ?? record.workAssignmentProvenance.patternID-            entry.workPatternVersion = record.workPatternVersion ?? record.workAssignmentProvenance.patternVersion-            entry.workURLRuleID = record.workURLRuleID-            entry.workURLRuleVersion = record.workURLRuleVersion-            entry.workURLAssignmentKindRaw = record.workURLAssignmentKind?.rawValue-            entry.intentionallyUnattached = record.intentionallyUnattached-            context.insert(entry)-            entry.site = sitesByHostname[record.hostname]-        }-    } }

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ComposedTeaching.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ComposedTeaching.swiftindex e92f079..f85a37c 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ComposedTeaching.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ComposedTeaching.swift@@ -72,9 +72,6 @@ extension LibraryRepository {         return try await withLockedContext(mode: .exclusive, operation: "committing composed teaching") { context in             let hostname = contract.basis.hostname -            // 0. Req 3.4: a hostname with more than one Site row cannot be-            // repaired by teaching, so refuse before projecting anything.-            try self.requireNoDuplicateSiteRows(hostname: hostname)             // What this hostname was already diagnosed with, read before any             // mutation. Step 7 rolls back only when the commit *changes* it.             let priorDiagnosis = self.quarantineReason(hostname: hostname)@@ -234,11 +231,6 @@ extension LibraryRepository {     /// current rules on purpose (Q20). Pure read, no write.     public func previewRecalculation(hostname: String) async throws -> ComposedTeachingContract {         try await withLockedContext(mode: .shared, operation: "projecting recalculation") { context in-            // Only a second Site row refuses here (Req 3.4). This used to refuse-            // for any quarantine, which included the illegal-tuple diagnosis the-            // reader is recalculating in order to clear — the dead end Req 3-            // exists to remove.-            try self.requireNoDuplicateSiteRows(hostname: hostname)             let basis = try self.buildComposedTeachingBasis(hostname: hostname, context: context)             guard let title = basis.currentTitleRule else {                 throw LibraryRepositoryError.invalidInput(@@ -261,7 +253,6 @@ extension LibraryRepository {     ) async throws -> ComposedRecalculationOutcome {         try await withLockedContext(mode: .exclusive, operation: "committing recalculation") { context in             let hostname = contract.basis.hostname-            try self.requireNoDuplicateSiteRows(hostname: hostname)             let priorDiagnosis = self.quarantineReason(hostname: hostname)              let currentBasis: ComposedTeachingBasis@@ -398,14 +389,9 @@ extension LibraryRepository {     // MARK: - Basis builder      func buildComposedTeachingBasis(hostname: String, context: ModelContext) throws -> ComposedTeachingBasis {-        // Req 3.4, Q43: refuse at the preview, not only at the commit. Without-        // this the reader can compose a whole teaching preview on a duplicated-        // hostname and be told only on confirmation that it cannot be-        // committed — work invited and then discarded. Both commits and-        // `previewRecalculation` call `requireNoDuplicateSiteRows` themselves-        // before reaching here, so the refusal they raise is unchanged; this-        // covers `projectComposedTeaching`, which does not.-        try requireNoDuplicateSiteRows(hostname: hostname)+        // Q39: the basis is built from the row `SiteResolutionOrder` selects, and+        // the commit writes to that same row. Refusing a duplicated hostname here+        // is what made Decision 6's coexisting rows permanently unteachable.         let sites = try Self.fetchSites(hostname: hostname, context: context)         guard let site = sites.first else {             throw LibraryRepositoryError.invalidInput(

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ConfirmImport.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ConfirmImport.swiftnew file mode 100644index 0000000..7df5797--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ConfirmImport.swift@@ -0,0 +1,339 @@+import Foundation+import OSLog+import SwiftData++/// What an interrupted import left behind (Req 4.4).+///+/// A **report, not a resume token**. The repair is the reader re-running the+/// import, which the upsert makes idempotent and convergent; there is nothing to+/// resume from and nothing that could be trusted if there were.+public struct InterruptedImportReport: Codable, Sendable, Equatable {+    public var archiveName: String+    public var startedAt: Date++    public init(archiveName: String, startedAt: Date) {+        self.archiveName = archiveName+        self.startedAt = startedAt+    }+}++// MARK: - The single import commit path++extension LibraryRepository {+    private static let confirmLogger = Logger(+        subsystem: "me.nore.ig.Asterism", category: "ConfirmImport")++    /// Applies an archive to the live library: **adds what is missing and updates+    /// what is older, and deletes nothing** (Decision 2, Req 4.1, 4.2).+    ///+    /// This one method replaces `confirmImportFillEmpty` and+    /// `confirmImportReplace`. Both were destructive-or-empty and both opened a+    /// *second* `ModelContainer` over the store, which beside a mirroring+    /// container is the in-process 134422 collision (Q24) and whose writes would+    /// have reached the mirror only through history replay. Upsert also makes the+    /// fill/replace distinction meaningless: filling an empty library is the+    /// degenerate upsert (Q37).+    ///+    /// Commit order is (1) Sites and rules, (2) Works in chunks, (3) Entries in+    /// chunks, each wired before its save, so a committed Entry's Site and Work+    /// always precede it and every boundary is a library the app can open+    /// (Req 4.3, 4.4).+    ///+    /// There is no staleness gate (Req 4.5). `computeInventoryFingerprint` hashed+    /// the full entity id set at preview and re-compared at commit, which on any+    /// device receiving sync traffic could never succeed. Records arriving while+    /// the reader confirms are simply more rows for the upsert to match.+    @discardableResult+    public func confirmImport(+        plan: BackupImportV4Plan, archiveName: String? = nil+    ) async throws -> BackupImportCommitResult {+        guard capabilities.gate == .m4 else {+            throw LibraryRepositoryError.invalidInput(+                operation: "confirming import",+                reason: "V4 library transitions require the m4 capability gate, "+                    + "got \(capabilities.gate.rawValue)")+        }+        // Imported rule forms must be usable at the running gate (Req 4.7's+        // sibling): refuse before anything is written.+        for pattern in plan.payload.titlePatterns {+            do { try capabilities.validate(patternDefinition: pattern.definition) }+            catch {+                throw LibraryRepositoryError.invalidInput(+                    operation: "validating imported pattern forms",+                    reason: String(describing: error))+            }+        }++        // Q46: import and reconciliation mutually exclude. A reconcile trigger+        // during this defers and re-fires when the flag drops.+        bulkOperationInProgress = true+        defer { bulkOperationInProgress = false }++        writeImportSidecar(+            InterruptedImportReport(+                archiveName: archiveName ?? Self.defaultArchiveName(plan.metadata),+                startedAt: clock.now()))++        let counts = try await withLockedContext(+            mode: .exclusive, operation: "committing a backup import"+        ) { context in+            try Self.upsert(+                plan.payload, context: context,+                batchSize: Self.bulkOperationBatchSize, saveStrategy: saveStrategy)+        }++        clearImportSidecar()++        // Post-import validation is **tolerant**, replacing the strict pass both+        // static paths ran. The target may legitimately carry states the archive+        // did not cause — a hostname still awaiting its Site row, a record that+        // arrived twice — and refusing over those would make a restore impossible+        // on exactly the devices that need one. Per-write strictness+        // (`validateEntryTuple`) is untouched.+        let refreshed = try await withLockedContext(+            mode: .shared, operation: "validating the imported library"+        ) { context in+            try Self.validateV4Store(context: context)+        }+        diagnostics = refreshed+        setQuarantine(refreshed.quarantineMap())++        // Q46's second half: a reconcile trigger that arrived mid-import deferred+        // rather than interleaving with the chunk saves. It re-fires here, now+        // that the flag has dropped and the diagnoses describe the imported graph.+        await refireDeferredReconcile()++        Self.confirmLogger.debug("Import committed: \(counts.entries) entries")+        return .committed(counts)+    }++    /// The report an interrupted import left, or nil. Read at open or from+    /// Settings, **however old** — a sidecar from a month ago still means that+    /// import did not finish, and time does not make that untrue.+    public func interruptedImport() -> InterruptedImportReport? {+        Self.readImportSidecar(at: configuration.importSidecarURL)+    }++    internal func writeImportSidecar(_ report: InterruptedImportReport) {+        guard let data = try? JSONEncoder().encode(report) else { return }+        try? FileManager.default.createDirectory(+            at: configuration.rootDirectory, withIntermediateDirectories: true)+        try? data.write(to: configuration.importSidecarURL, options: .atomic)+    }++    internal func clearImportSidecar() {+        try? FileManager.default.removeItem(at: configuration.importSidecarURL)+    }++    /// A corrupt or unreadable sidecar is still evidence that an import started,+    /// so it reports rather than vanishing — with what it can say.+    internal static func readImportSidecar(at url: URL) -> InterruptedImportReport? {+        guard let data = try? Data(contentsOf: url) else { return nil }+        if let report = try? JSONDecoder().decode(InterruptedImportReport.self, from: data) {+            return report+        }+        return InterruptedImportReport(archiveName: "an unnamed backup", startedAt: .distantPast)+    }++    private static func defaultArchiveName(_ metadata: BackupImportMetadata) -> String {+        let formatter = DateFormatter()+        formatter.dateStyle = .medium+        formatter.timeStyle = .short+        return "the backup from \(formatter.string(from: metadata.exportedAt))"+    }++    // MARK: - The upsert++    /// Adds and updates; never deletes. Returns the library's counts afterwards —+    /// not the plan's, which under upsert describe the archive rather than the+    /// result.+    internal static func upsert(+        _ payload: BackupV4Payload,+        context: ModelContext,+        batchSize: Int,+        saveStrategy: any RepositorySaveStrategy+    ) throws -> LibraryRecordCounts {+        // (1) Sites and rules, one save.+        //+        // A Site matches by hostname, and under coexisting duplicate rows it+        // matches the row `SiteResolutionOrder` selects — the same row capture and+        // teaching write to, so an import cannot pin records to a row nothing else+        // uses.+        //+        // Grouped rather than reduced to winners, because the rule merge at the+        // end needs every row a hostname holds and would otherwise re-fetch them+        // one predicate at a time.+        var rowsByHostname = Dictionary(+            grouping: try context.fetch(FetchDescriptor<Site>()), by: \.hostname)+        var sitesByHostname = rowsByHostname.compactMapValues {+            SiteResolutionOrder.sorted($0).first+        }+        for record in payload.sites {+            if let existing = sitesByHostname[record.hostname] {+                // Teaching state follows the union below, not the archive's+                // wholesale claim; only an unnamed row takes a name.+                if existing.displayName.isEmpty { existing.displayName = record.displayName }+                if existing.junkSuffixRule == nil { existing.junkSuffixRule = record.junkSuffixRule }+                continue+            }+            let site = Site(hostname: record.hostname, displayName: record.displayName)+            site.modeRaw = record.mode.rawValue+            site.junkSuffixRule = record.junkSuffixRule+            context.insert(site)+            sitesByHostname[record.hostname] = site+            rowsByHostname[record.hostname, default: []].append(site)+        }++        // Rules are immutable revisions keyed by UUID (Decision 8): a rule the+        // library already holds is never overwritten, and one it lacks is+        // inserted. Their versions may collide with the ones already there —+        // both histories start at v1 — which the union below is what repairs.+        var patternIDs = Set(try context.fetch(FetchDescriptor<TitlePattern>()).map(\.id))+        for record in payload.titlePatterns where patternIDs.insert(record.id).inserted {+            let pattern = try TitlePattern(+                id: record.id, version: record.version, isActive: record.isActive,+                createdAt: record.createdAt, definition: record.definition,+                site: sitesByHostname[record.siteHostname])+            pattern.trimPrefix = record.trimPrefix+            pattern.trimSuffix = record.trimSuffix+            context.insert(pattern)+        }+        var ruleIDs = Set(try context.fetch(FetchDescriptor<URLRulePattern>()).map(\.id))+        for record in payload.urlRules where ruleIDs.insert(record.id).inserted {+            let rule = try URLRulePattern(+                id: record.id, version: record.version, isCurrent: record.isCurrent,+                createdAt: record.createdAt, origin: record.origin,+                definition: record.definition, site: sitesByHostname[record.siteHostname])+            context.insert(rule)+        }+        try saveStrategy.save(context)++        // (2) Works, in chunks.+        var worksByID = worksByID(try context.fetch(FetchDescriptor<Work>())).byID+        for chunk in chunks(of: payload.works, size: batchSize) {+            for record in chunk {+                if let existing = worksByID[record.id] {+                    // Decision 8: an older archive must not regress a newer edit.+                    // Under mirroring that regression would reach every device,+                    // which is the shape of loss this spec exists to prevent.+                    guard record.modifiedAt >= existing.modifiedAt else { continue }+                    apply(record, to: existing)+                    existing.site = sitesByHostname[record.siteHostname]+                } else {+                    let work = Work(+                        id: record.id, displayTitle: record.displayTitle,+                        siteHostname: record.siteHostname, timestamp: record.createdAt)+                    context.insert(work)+                    apply(record, to: work)+                    work.site = sitesByHostname[record.siteHostname]+                    worksByID[record.id] = work+                }+            }+            try saveStrategy.save(context)+        }++        // (3) Entries, in chunks. Their Site and Work are already committed, so+        // every boundary here is a legal library too.+        var entriesByID = entriesByID(try context.fetch(FetchDescriptor<Entry>())).byID+        for chunk in chunks(of: payload.entries, size: batchSize) {+            for record in chunk {+                let entry: Entry+                if let existing = entriesByID[record.id] {+                    guard record.modifiedAt >= existing.modifiedAt else { continue }+                    entry = existing+                } else {+                    entry = Entry(+                        id: record.id, captureTitle: record.captureTitle,+                        captureTitleSource: record.captureTitleSource,+                        rawURLString: record.rawURL, canonicalURLString: record.canonicalURL,+                        hostname: record.hostname, entryIdentityKey: record.entryIdentityKey,+                        timestamp: record.firstCapturedAt)+                    context.insert(entry)+                    entriesByID[record.id] = entry+                }+                apply(record, to: entry)+                entry.site = sitesByHostname[record.hostname]+                entry.work = record.workID.flatMap { worksByID[$0] }+            }+            try saveStrategy.save(context)+        }++        // (4) The rule merge. Archive rules joining existing ones collide on+        // version and can leave two active title rules on one row, so the union+        // renumbers deterministically and rewrites every citing record's+        // `(id, version)` pair — the imported records and the ones already there+        // alike (Decision 7). Reusing the reconciler is what keeps the imported+        // shape and the reconciled shape the same shape.+        //+        // Every hostname the archive touched, named once: the reconciler unions+        // its two lists, so handing it the same array twice said nothing the one+        // list does not. Its rows come from the grouping step (1) already built.+        _ = try SiteReconciler.run(+            duplicateHostnames: payload.sites.map(\.hostname),+            rowsByHostname: rowsByHostname,+            batchSize: batchSize, context: context, saveStrategy: saveStrategy)++        return try v3Counts(context: context)+    }++    // MARK: - Record application++    /// The mutable half of a `BackupV4Work`, shared by the upsert and by+    /// `materializeV4Payload` so an inserted record and an updated one cannot+    /// drift apart. Identity, hostname, and `createdAt` are set at construction.+    internal static func apply(_ record: BackupV4Work, to work: Work) {+        work.displayTitle = record.displayTitle+        work.lastParsedTitle = record.lastParsedTitle+        work.siteHostname = record.siteHostname+        work.urlIdentity = record.urlIdentity+        work.urlIdentityStateRaw = record.urlIdentityState.rawValue+        work.urlIdentityRuleID = record.urlIdentityRuleID+        work.urlIdentityRuleVersion = record.urlIdentityRuleVersion+        work.workURLString = record.workURL+        work.genericNotes = record.genericNotes+        work.typeRaw = record.type.rawValue+        work.genreTags = record.genreTags+        work.titleProvenanceRaw = record.titleProvenance.rawValue+        work.createdAt = record.createdAt+        work.modifiedAt = record.modifiedAt+    }++    internal static func apply(_ record: BackupV4Entry, to entry: Entry) {+        entry.captureTitle = record.captureTitle+        entry.captureTitleSourceRaw = record.captureTitleSource.rawValue+        entry.rawURLString = record.rawURL+        entry.canonicalURLString = record.canonicalURL+        entry.hostname = record.hostname+        entry.entryIdentityKey = record.entryIdentityKey+        entry.identityKeyVersion = record.identityKeyVersion+        entry.conservativeIdentityKey = record.conservativeIdentityKey+        entry.identityBasisRaw = record.identityBasis.rawValue+        entry.identityURLRuleID = record.identityURLRuleID+        entry.identityURLRuleVersion = record.identityURLRuleVersion+        entry.identityNameTitleRuleID = record.identityNameTitleRuleID+        entry.identityNameTitleRuleVersion = record.identityNameTitleRuleVersion+        entry.urlWorkIdentity = record.urlWorkIdentity+        entry.urlWorkRuleID = record.urlWorkRuleID+        entry.urlWorkRuleVersion = record.urlWorkRuleVersion+        entry.chapterSequence = record.chapterSequence+        entry.chapterSequenceRuleID = record.chapterSequenceRuleID+        entry.chapterSequenceRuleVersion = record.chapterSequenceRuleVersion+        entry.chapterTitle = record.chapterTitle+        entry.chapterTitleProvenanceRaw = record.chapterTitleProvenance.kind.rawValue+        entry.chapterPatternID = record.chapterTitleProvenance.patternID+        entry.chapterPatternVersion = record.chapterTitleProvenance.patternVersion+        entry.note = record.note+        entry.ratingRaw = record.rating?.rawValue+        entry.firstCapturedAt = record.firstCapturedAt+        entry.lastSharedAt = record.lastSharedAt+        entry.modifiedAt = record.modifiedAt+        entry.workAssignmentProvenanceRaw = record.workAssignmentProvenance.kind.rawValue+        entry.workPatternID = record.workPatternID ?? record.workAssignmentProvenance.patternID+        entry.workPatternVersion =+            record.workPatternVersion ?? record.workAssignmentProvenance.patternVersion+        entry.workURLRuleID = record.workURLRuleID+        entry.workURLRuleVersion = record.workURLRuleVersion+        entry.workURLAssignmentKindRaw = record.workURLAssignmentKind?.rawValue+        entry.intentionallyUnattached = record.intentionallyUnattached+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Contracts.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Contracts.swiftindex 6fd9f6a..b0e5a76 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Contracts.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Contracts.swift@@ -11,11 +11,11 @@ extension LibraryRepository {     /// Validates closed Site/pattern state: no duplicate Sites (handled by fetchSites),     /// valid mode, mode-consistent patterns, positive site-unique versions, valid definitions.     func buildTeachingBasis(hostname: String, context: ModelContext) throws -> TeachingBasis {-        // Req 3.4: more than one Site row for this hostname is not something a-        // teaching commit can repair. Every caller of this builder — the two-        // teaching projections, `commitTeaching`, and both articles paths —-        // refuses through this one check.-        try requireNoDuplicateSiteRows(hostname: hostname)+        // Q39: a duplicated hostname resolves to the row `SiteResolutionOrder`+        // selects, exactly as capture already does. This used to refuse+        // outright, which made Decision 6's coexisting rows permanently+        // unteachable — closing the one escape hatch ("until teaching+        // distinguishes them") that decision relies on.         let sites = try Self.fetchSites(hostname: hostname, context: context)         guard let site = sites.first else {             throw LibraryRepositoryError.invalidInput(

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+EntryDetail.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+EntryDetail.swiftindex 98d03c4..b0ef8d5 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+EntryDetail.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+EntryDetail.swift@@ -34,9 +34,9 @@ extension LibraryRepository {             let siteMode: SiteMode             if let site {                 guard let mode = SiteMode(rawValue: site.modeRaw) else {-                    throw LibraryRepositoryError.corruptLibrary(-                        operation: "entry teaching detail",-                        reason: "Site '\(hostname)' has invalid mode raw value '\(site.modeRaw)'"+                    throw LibraryRepositoryError.quarantined(+                        hostname: hostname,+                        reason: "Site mode raw value '\(site.modeRaw)' is not one this app defines"                     )                 }                 siteMode = mode@@ -55,22 +55,32 @@ extension LibraryRepository {             let allPatterns = site?.patternValues ?? []             let activePatterns = allPatterns.filter(\.isActive)             let isWorkOnly = site?.isWorkOnlyTitleRule ?? false+            // **Typed as a quarantine, not as corruption** (Q39). Every arm here+            // is the hostname's teaching state failing the closed tuple table —+            // the class `.siteTuple` reports, the class re-teaching clears, and+            // since Decision 7 the class the reconciler repairs on its own for the+            // shape two concurrent teaches produce. The screen refuses either way;+            // what the type buys is a caller that can say *why*. `corruptLibrary`+            // is indistinguishable from a record the app cannot map, and+            // `EntryDetailView` read every one of them as "this entry has been+            // removed" — told the reader their entry was gone while it sat in the+            // store waiting for the next reconciliation pass.             switch siteMode {             case .untaught where !allPatterns.isEmpty:-                throw LibraryRepositoryError.corruptLibrary(-                    operation: "entry teaching detail",+                throw LibraryRepositoryError.quarantined(+                    hostname: hostname,                     reason: "Untaught Site retains title patterns"                 )             case .taught where activePatterns.count != 1:                 // A taught Site always retains exactly one active title pattern                 // (Decision 5) — whole-title, chapter-less, or ordinary.-                throw LibraryRepositoryError.corruptLibrary(-                    operation: "entry teaching detail",+                throw LibraryRepositoryError.quarantined(+                    hostname: hostname,                     reason: "Taught Site must retain exactly one active title pattern"                 )             case .articles where !activePatterns.isEmpty:-                throw LibraryRepositoryError.corruptLibrary(-                    operation: "entry teaching detail",+                throw LibraryRepositoryError.quarantined(+                    hostname: hostname,                     reason: "Articles Site cannot have an active title pattern"                 )             default:@@ -131,22 +141,13 @@ extension LibraryRepository {             // exists for hostname"`; teaching deliberately does not create the row             // (Q40), and capture does.             //-            // A duplicated hostname is refused with `.quarantined` (Q47): a-            // teaching commit rewrites one row's tuple and says nothing about the-            // second, so it cannot clear the diagnosis. `fetchSites` names a-            // winner, so `site` is non-nil and the actions would otherwise be-            // offered — this is the same defect the nil-Site case had. The screen-            // still renders everything it resolved; the route is the diagnostics-            // surface (Req 4.1).-            //-            // The test is the diagnosis list, not the quarantine map: `.siteTuple`-            // quarantines as well (Q12) and must keep its actions, being the one-            // class re-teaching clears (Req 3.1, Q41). It is also not `sites.count`-            // — reading what `requireNoDuplicateSiteRows` reads is what keeps the-            // action offered here and the commit that accepts it in step.-            let isDuplicatedHostname = Self.duplicatedHostnames(in: self.diagnostics)-                .contains(hostname)-            let availableActions = site == nil || isDuplicatedHostname+            // A duplicated hostname keeps its actions (Q39). It used to be refused+            // outright, on the reasoning that a teaching commit rewrites one row+            // and says nothing about the second — which was true while nothing+            // reconciled the rows. `SiteReconciler` does, and teaching commits to+            // the row `SiteResolutionOrder` selects, so the action offered here is+            // the action the commit performs.+            let availableActions = site == nil                 ? []                 : Self.computeAvailableActions(siteMode: siteMode, isWorkOnly: isWorkOnly) 

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RecentPresentation.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RecentPresentation.swiftindex 54c22e6..43df2ef 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RecentPresentation.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RecentPresentation.swift@@ -59,10 +59,10 @@ extension LibraryRepository {             let sortedEntries = entries.sorted {                 Self.recentEntryOrder($0.snapshot, $1.snapshot)             }-            // Req 3.4, read from the same list `requireNoDuplicateSiteRows` reads-            // rather than from the fetched rows, so the rows that offer an action-            // and the commit that accepts one cannot disagree about which-            // hostnames are duplicated. Deliberately **not** the quarantine map:+            // Req 3.4, read from the derived diagnoses rather than from the rows+            // fetched above, so the rows that offer an action and the commit that+            // accepts one cannot disagree about which hostnames are duplicated —+            // both read one derivation. Deliberately **not** the quarantine map:             // `.siteTuple` quarantines too and must keep its Teach action, since             // it is the one class re-teaching clears (Q13, Q41).             let duplicatedHostnames = Self.duplicatedHostnames(in: self.diagnostics)@@ -85,15 +85,17 @@ extension LibraryRepository {                 // cause is only known once the citation has been replayed below.                 // These rank first because they also explain why the row carries                 // no mode and therefore no action.-                // Duplication outranks an illegal tuple, inverting Q24's order for-                // the quarantine payload: there the tuple reason wins because it is-                // the actionable one, but on a duplicated hostname re-teaching is-                // refused, so naming the tuple would promise a repair that is not-                // available.+                // An illegal tuple outranks duplication again (Q36, Q39). The+                // inversion this carried was justified by re-teaching being+                // refused on a duplicated hostname — so naming the tuple would+                // promise an unavailable repair. Teaching now targets the+                // deterministic winner, so the tuple reason is the actionable one+                // and leads; duplication is informational, and the app repairs it+                // on its own.                 let siteAttention: RecentRowAttention? =                     if site == nil { .siteMissing }-                    else if isDuplicatedHostname { .siteDuplicated }                     else if mode == nil { .siteRulesInvalid }+                    else if isDuplicatedHostname { .siteDuplicated }                     else if missingWork { .workMissing }                     else { nil } @@ -103,17 +105,12 @@ extension LibraryRepository {                 // Site row — the dead-end action Req 3.4 exists to prevent. Nothing                 // downstream can recover from that, so the row offers nothing.                 //-                // **A duplicated hostname yields `.none` too**, for the same-                // reason one step later: `fetchSites` names a winner, so the mode-                // resolves and the row would otherwise offer Teach or Re-teach —-                // routing into `buildComposedTeachingBasis`, which refuses a-                // duplicated hostname with `.quarantined` (Req 3.4, Q47). It is-                // also not actionable: `actionableCount` labels a banner promising-                // entries that need teaching and filters to exactly those rows, so-                // counting a row whose teaching is refused would point the reader-                // at work they cannot do. Same shape as Q38 for a nil mode.-                let actionable = !isDuplicatedHostname-                    && (mode.map { Self.isRecentEntryActionable(entry, siteMode: $0) } ?? false)+                // **A duplicated hostname keeps its action** (Q39). It used to+                // yield `.none` because the commit refused; the commit now writes+                // to the winner `fetchSites` already resolves the mode from, so+                // the pill leads somewhere and the row counts toward the banner+                // it belongs in.+                let actionable = mode.map { Self.isRecentEntryActionable(entry, siteMode: $0) } ?? false                 let actionType: RecentRowActionType                 let displayCaptureTitle: String                 let replay: CitationReplay

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+URLIdentity.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+URLIdentity.swiftindex 36697ce..6db258f 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+URLIdentity.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+URLIdentity.swift@@ -41,12 +41,10 @@ extension LibraryRepository {     hostname: String,     context: ModelContext   ) throws -> URLSiteEvidenceBasis {-    // Req 3.4: with more than one Site row the evidence would be assembled from-    // whichever row won `SiteResolutionOrder`, and the review screen's only-    // onward action is to re-teach — which cannot clear that state. Refuse-    // rather than show a projection derived from one arbitrary half of the-    // hostname's rules.-    try requireNoDuplicateSiteRows(hostname: hostname)+    // Q39: the evidence is assembled from the row `SiteResolutionOrder` selects+    // — the same row teaching now commits to, so the review screen and the+    // commit describe one row rather than disagreeing about which half of a+    // duplicated hostname governs.     let sites = try Self.fetchSites(hostname: hostname, context: context)     guard let site = sites.first else {       return try URLSiteEvidenceBasis(

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+V4Bootstrap.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+V4Bootstrap.swiftindex c66dcae..c7b9d18 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+V4Bootstrap.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+V4Bootstrap.swift@@ -31,13 +31,32 @@ public extension LibraryRepository {     }      /// App startup: evaluates fixed-path V4 state under one exclusive lease,-    /// migrates in place when required, and certifies readiness. Implements the-    /// design's bootstrap state table. Returns an open, ready library or throws.+    /// migrates in place when required, certifies readiness, and only then+    /// constructs the container the repository keeps. Implements the design's+    /// bootstrap state table. Returns an open, ready library or throws.+    ///+    /// The open is two-phase (Q35). Every certification phase — store creation,+    /// migration, sidecar resume, the V5 relationship pass, validation, marker+    /// publication — runs on a container opened `.none`, exactly as before, and+    /// that container is released when `certifyV4ForApp` returns. Only then is+    /// the long-lived container constructed, mirrored when a container+    /// identifier was injected. Two consequences the design leans on:+    ///+    /// * Mirroring cannot write into the store before it is marked ready+    ///   (Req 6.1), on any path including mark-at-birth, because no mirroring+    ///   container exists until the marker does. That closes the Q22 window+    ///   without timing arguments.+    /// * The two containers are never live together (Q24's in-process 134422).+    ///+    /// The second construction costs one `ModelContainer.init` per launch, under+    /// 1% of the open path, and it runs on every configuration rather than only+    /// mirroring ones so the sequence under test is the sequence that ships.     static func openV4ForApp(         _ configuration: LibraryConfiguration,         capabilities: AsterismCapabilities = .current,         clock: any RepositoryClock = SystemRepositoryClock(),-        saveStrategy: any RepositorySaveStrategy = ModelContextSaveStrategy()+        saveStrategy: any RepositorySaveStrategy = ModelContextSaveStrategy(),+        mirroring hooks: MirroringOpenHooks = .production     ) async throws -> (result: V4OpeningResult, repository: LibraryRepository) {         let fileManager = FileManager.default         do {@@ -53,6 +72,34 @@ public extension LibraryRepository {             mode: .exclusive, at: configuration.lockURL, timeout: bootstrapLockTimeout)         defer { withExtendedLifetime(lease) {} } +        let certification = try certifyV4ForApp(+            configuration, capabilities: capabilities, clock: clock,+            saveStrategy: saveStrategy, hooks: hooks)+        // The certification container died with that call's frame. Nothing here+        // holds a reference to it, which is what makes the construction below+        // the only live container over this store.+        let (container, attachment) = try openLiveV4Container(configuration, hooks: hooks)+        return (certification.result, makeRepository(+            configuration, container, capabilities, clock, saveStrategy,+            quarantined: certification.quarantined, diagnostics: certification.diagnostics,+            mirroring: attachment))+    }++    /// Certification: everything that decides whether the library is openable+    /// and publishes the readiness marker, on a `.none` container that does not+    /// outlive the call.+    ///+    /// Returns no container by construction — that is the point, not an+    /// oversight. Handing one back would put the hazard (a lingering ARC+    /// reference to a second container over the store) into the caller's frame.+    internal static func certifyV4ForApp(+        _ configuration: LibraryConfiguration,+        capabilities: AsterismCapabilities,+        clock: any RepositoryClock,+        saveStrategy: any RepositorySaveStrategy,+        hooks: MirroringOpenHooks+    ) throws -> V4Certification {+        let fileManager = FileManager.default         let storeExists = fileManager.fileExists(atPath: configuration.v4StoreURL.path)         let v4Marker = fileManager.fileExists(atPath: configuration.v4MarkerURL.path)         let v3Marker = fileManager.fileExists(atPath: configuration.v3MarkerURL.path)@@ -109,9 +156,8 @@ public extension LibraryRepository {                 configuration, context: context, saveStrategy: saveStrategy,                 runPass: needsRelationshipPass)             let counts = try v3Counts(context: context)-            return (.ready(counts), makeRepository(-                configuration, container, capabilities, clock, saveStrategy,-                quarantined: diagnostics.quarantineMap(), diagnostics: diagnostics))+            hooks.certificationContainerObserver?(container)+            return V4Certification(result: .ready(counts), diagnostics: diagnostics)         }          // No V4 marker: resume or run migration, or classify the store.@@ -132,7 +178,8 @@ public extension LibraryRepository {             // rewrite it, or the completion pass would duplicate patterns.             return try certifyMigration(                 configuration, sidecar: sidecar,-                capabilities: capabilities, clock: clock, saveStrategy: saveStrategy)+                capabilities: capabilities, clock: clock, saveStrategy: saveStrategy,+                hooks: hooks)         }          // Create the store when it is missing, so the unmarked-store case below@@ -153,7 +200,8 @@ public extension LibraryRepository {             let sidecar = try writeFreshSidecar(configuration)             return try certifyMigration(                 configuration, sidecar: sidecar,-                capabilities: capabilities, clock: clock, saveStrategy: saveStrategy)+                capabilities: capabilities, clock: clock, saveStrategy: saveStrategy,+                hooks: hooks)         } else {             container = try openV4Container(at: configuration.v4StoreURL)         }@@ -200,8 +248,8 @@ public extension LibraryRepository {             // populated stores.             try publishV5Readiness(at: configuration.v4MarkerURL)             v4Logger.debug("Marked an empty unmarked V4 store as ready")-            return (.ready(.zero), makeRepository(-                configuration, container, capabilities, clock, saveStrategy))+            hooks.certificationContainerObserver?(container)+            return V4Certification(result: .ready(.zero), diagnostics: .empty)         }         throw LibraryRepositoryError.libraryUnavailable(             operation: "opening current V4 library",@@ -253,20 +301,39 @@ public extension LibraryRepository { extension LibraryRepository {     static let v4Logger = Logger(subsystem: "me.nore.ig.Asterism", category: "V4Bootstrap") +    /// What certification established, without the container it established it+    /// on. The absent container is the design's Q35 property in the type: a+    /// caller cannot accidentally keep the certification container alive+    /// alongside the mirrored one (Q24's in-process 134422).+    struct V4Certification {+        var result: V4OpeningResult+        var diagnostics: LibraryDiagnostics+        var quarantined: [String: V4ValidationError] { diagnostics.quarantineMap() }+    }+     /// Opens the fixed-path store with the live V5 schema and the `[V3, V4, V5]`     /// lightweight migration plan (adds the M4-additive columns for real pre-M4     /// stores, then the M4a relationships; a V3-recorded store traverses both     /// stages in one open — Q22).+    ///+    /// Mirroring defaults to off, and every certification-phase caller takes the+    /// default: the store is opened `.none` for creation, migration, the+    /// relationship pass and validation, and only the app's post-certification+    /// open passes `.private` (Q35). The share extension never passes it at all+    /// (Req 5.1).     // `public` so the app target can open a V4 store for the isolated UI-test     // bootstrap of the composed teaching surface (Req 7.3); production opens via     // `openV4ForApp` (task 25's runtime switch).-    public static func openV4Container(at storeURL: URL) throws -> ModelContainer {+    public static func openV4Container(+        at storeURL: URL,+        mirroring cloudKitDatabase: ModelConfiguration.CloudKitDatabase = .none+    ) throws -> ModelContainer {         let schema = Schema(versionedSchema: AsterismSchemaV5.self)         let storeConfiguration = ModelConfiguration(             "AsterismV3", // same on-disk store name as V3 (Q13)             schema: schema,             url: storeURL,-            cloudKitDatabase: .none+            cloudKitDatabase: cloudKitDatabase         )         return try ModelContainer(             for: schema,@@ -325,8 +392,9 @@ extension LibraryRepository {         sidecar: MigrationSidecar,         capabilities: AsterismCapabilities,         clock: any RepositoryClock,-        saveStrategy: any RepositorySaveStrategy-    ) throws -> (result: V4OpeningResult, repository: LibraryRepository) {+        saveStrategy: any RepositorySaveStrategy,+        hooks: MirroringOpenHooks = .production+    ) throws -> V4Certification {         let container: ModelContainer         do {             container = try openV4Container(at: configuration.v4StoreURL)@@ -354,9 +422,37 @@ extension LibraryRepository {          let counts = try v3Counts(context: context)         v4Logger.debug("V4 migration certified with \(counts.sites, privacy: .public) Sites")-        return (.ready(counts), makeRepository(-            configuration, container, capabilities, clock, saveStrategy,-            quarantined: diagnostics.quarantineMap(), diagnostics: diagnostics))+        hooks.certificationContainerObserver?(container)+        return V4Certification(result: .ready(counts), diagnostics: diagnostics)+    }++    /// Constructs the container the repository keeps, after certification.+    ///+    /// Mirrored when a container identifier was injected, and `.none`+    /// otherwise — a configuration that names no container cannot mirror+    /// (Req 7.1), which is every host test, UI-test root and migration helper.+    ///+    /// A `.private` construction failure falls back to `.none` and is recorded+    /// rather than thrown (Q44): a bad container identifier or a missing+    /// entitlement must degrade sync, never the library. The recorded+    /// attachment is what Settings names as misconfigured (Req 8.4).+    static func openLiveV4Container(+        _ configuration: LibraryConfiguration,+        hooks: MirroringOpenHooks+    ) throws -> (container: ModelContainer, attachment: MirroringAttachment) {+        guard let containerID = configuration.cloudKitContainerID else {+            return (try openV4Container(at: configuration.v4StoreURL), .notRequested)+        }+        do {+            let mirrored = try hooks.makeMirroredContainer(configuration.v4StoreURL, containerID)+            v4Logger.debug("Attached CloudKit mirroring to the certified store")+            return (mirrored, .attached(containerID: containerID))+        } catch {+            let reason = String(describing: error)+            v4Logger.error("Mirrored container construction failed, running local-only: \(reason, privacy: .public)")+            return (try openV4Container(at: configuration.v4StoreURL),+                    .failed(containerID: containerID, reason: reason))+        }     }      /// The certification tail both V4 open paths share, in the order Q36 pins:@@ -506,11 +602,12 @@ extension LibraryRepository {         _ clock: any RepositoryClock,         _ saveStrategy: any RepositorySaveStrategy,         quarantined: [String: V4ValidationError] = [:],-        diagnostics: LibraryDiagnostics = .empty+        diagnostics: LibraryDiagnostics = .empty,+        mirroring: MirroringAttachment = .notRequested     ) -> LibraryRepository {         LibraryRepository(             configuration: configuration, container: container,             capabilities: capabilities, clock: clock, saveStrategy: saveStrategy,-            quarantined: quarantined, diagnostics: diagnostics)+            quarantined: quarantined, diagnostics: diagnostics, mirroring: mirroring)     } }

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swiftindex 1852346..cbbfe15 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift@@ -36,8 +36,12 @@ public extension LibraryConfiguration {     /// The identifier is explicit input (Decision 1): the embedding target reads     /// its own bundle's derived value and hands it in, so the package holds no     /// identifier literals of its own (Req 2.2).+    ///+    /// `cloudKitContainerID` is injected on the same terms and defaults to nil:+    /// a caller that does not name a container cannot mirror (Q51).     static func production(         appGroupIdentifier: String,+        cloudKitContainerID: String? = nil,         locator: any SharedContainerLocating = SystemSharedContainerLocator()     ) throws -> LibraryConfiguration {         guard let root = locator.containerURL(forAppGroup: appGroupIdentifier) else {@@ -46,7 +50,7 @@ public extension LibraryConfiguration {                 reason: "the configured shared container is unavailable"             )         }-        return LibraryConfiguration(rootDirectory: root)+        return LibraryConfiguration(rootDirectory: root, cloudKitContainerID: cloudKitContainerID)     } } @@ -55,8 +59,12 @@ public actor LibraryRepository {     internal static let interactiveLockTimeout: Duration = .seconds(2)     internal static let bootstrapLockTimeout: Duration = .seconds(5) -    private let configuration: LibraryConfiguration-    private let container: ModelContainer+    internal let configuration: LibraryConfiguration+    /// Optional so `shutdown()` can release it (Q43). There is no `close()` on+    /// a `ModelContainer`, so dropping the last reference is the only teardown+    /// there is — and under mirroring a re-open that left this one alive would+    /// be the in-process 134422 collision (Q24).+    private var container: ModelContainer?     internal let capabilities: AsterismCapabilities     internal let clock: any RepositoryClock     internal let saveStrategy: any RepositorySaveStrategy@@ -76,7 +84,7 @@ public actor LibraryRepository {     /// Re-derived by `refreshDiagnostics()` on foreground and after a write the     /// app commits (Req 1.5), and by nothing on the capture path in either     /// process (Req 1.6).-    public private(set) var diagnostics: LibraryDiagnostics = .empty+    public internal(set) var diagnostics: LibraryDiagnostics = .empty      /// Re-derives the three tolerated states from the store as it stands and     /// republishes `quarantined` from the merged map (Req 1.5).@@ -88,9 +96,18 @@ public actor LibraryRepository {     /// `setQuarantine`, which assigns wholesale. A refresh that republished the     /// scan alone would silently un-quarantine every tuple-diagnosed hostname,     /// putting an illegal Site's rules back onto capture-    /// (`+ReparseCapture.swift:284`, `:396`) and un-gating backup export-    /// (`BackupV4Exporter.swift:41`). Decision 7 predicts exactly this failure;-    /// `RefreshUnionInvariantTests` is the regression.+    /// (`+ReparseCapture.swift:284`, `:396`). Backup export used to be the second+    /// consumer; its quarantine gate is gone (Req 3.1) and a quarantined library+    /// now exports, so capture is the one that makes this load-bearing.+    /// Decision 7 predicts exactly this failure; `RefreshUnionInvariantTests` is+    /// the regression.+    ///+    /// The carry-forward is a *cache* of the last full validation, so the two+    /// passes that can repair a hostname without one invalidate it themselves:+    /// a teaching commit through `recordPostCommitDiagnosis`, and a reconcile+    /// pass through the re-validation in `reconcileAfterSync`. Both re-validate+    /// before they clear; neither drops an entry for having written to the+    /// hostname.     ///     /// App only. The extension runs the full validator once at open and nothing     /// after it: it has no foreground and no surface that reports diagnoses@@ -112,6 +129,289 @@ public actor LibraryRepository {         setQuarantine(merged.quarantineMap())     } +    /// The chunk size every bulk pass commits in — the reconciler's re-pin and+    /// import's Work/Entry chunks (Q32, Q45).+    ///+    /// One constant, because the two passes write the same shape: a+    /// `Site`-relationship assignment across many records, whose cost is+    /// inverse-array maintenance and superlinear in the array's length (~n^1.65,+    /// Q27 — 5,000 links in one save measured 17 s).+    ///+    /// **Measured, no longer provisional** (task 25, Q53;+    /// `specs/cloudkit-mirroring/implementation.md`). Swept from 250 to 5,000+    /// over the 5,000-Entry fixture, host, release:+    ///+    /// - the reconciler's re-pin does not depend on this number *at all* —+    ///   39.4–40.8 s at 500, 41.0–43.8 s at 2,500, 39.7–40.8 s at one save for+    ///   the whole hostname, three overlapping bands. The work is the+    ///   inverse-array maintenance, and splitting it into saves neither adds to+    ///   it nor takes from it.+    /// - import pays ~20 ms per commit boundary and nothing else: ~2.98 s at 500+    ///   (12 saves) against a 2.71 s one-save floor.+    ///+    /// So chunking buys interruption boundaries (Req 4.4), not speed, and the+    /// size is chosen for boundary granularity rather than throughput. 500 costs+    /// ~0.27 s of a 3 s import and nothing measurable of a consolidation, and+    /// leaves ten Entry boundaries where one save leaves none. Raising it to+    /// 1,000 would buy back ~0.13 s — not a reason to halve the number of legal+    /// states an interrupted import can stop in.+    internal static let bulkOperationBatchSize = 500++    /// Splits a bulk pass's records into `bulkOperationBatchSize`-sized commit+    /// units. One helper for both passes, beside the size they share: the+    /// reconciler's re-pin and import's Work/Entry chunks had a byte-identical+    /// copy each.+    ///+    /// A non-positive size means "one chunk", so a caller that passes 0 commits+    /// once rather than looping forever.+    internal static func chunks<Element>(+        of values: [Element], size: Int+    ) -> [ArraySlice<Element>] {+        guard !values.isEmpty else { return [] }+        guard size > 0 else { return [values[...]] }+        return stride(from: 0, to: values.count, by: size).map {+            values[$0..<min($0 + size, values.count)]+        }+    }++    /// Q46: import and reconciliation mutually exclude.+    ///+    /// Both run on the live container as actor methods with await points between+    /// chunk saves, so an arrival mid-import could otherwise reconcile rows the+    /// next chunk is about to wire against. A reconcile trigger during an import+    /// defers and re-fires when the import releases the flag.+    internal var bulkOperationInProgress = false+    internal var reconcileDeferred = false++    /// Makes the Site graph coherent after records arrive (Req 1.1–1.8).+    ///+    /// Runs on the remote-change debounce and once per launch *after* the first+    /// Recent publication — never inside the open path, whose 2 s budget+    /// (Req 9.1) does not pay for it, and never on the capture path (Req 9.2).+    ///+    /// Silent by construction (Req 1.2): it returns what it did and asks nothing.+    /// Diagnoses are the caller's to refresh — `AppLibraryModel` follows this+    /// with the scan/union/refresh it already runs on foreground.+    ///+    /// **The duplicate set is derived here, not read from `diagnostics`.** The+    /// cached diagnoses describe the store as of the last refresh, and every+    /// arrival caller reconciles *before* it refreshes — necessarily so, since+    /// Recent is built from the diagnoses and the refresh has to see the merged+    /// graph. Deriving the work list from the cache therefore made each pass+    /// operate on the previous batch's hostnames: the rows an arrival had just+    /// minted were invisible until something else refreshed, so the last batch+    /// of a hydration never converged before the next launch (Req 1.7). One+    /// derivation inside the same locked context fixes it for every caller.+    ///+    /// It is **not** `LibraryToleranceScan.scan`. That pass walks five tables to+    /// answer five questions, of which this one consumed exactly one —+    /// `.duplicateSiteRows` — so every arrival charged the whole library for a+    /// question about its Site rows. The scan stays where its other four answers+    /// are wanted (`refreshDiagnostics`, which every arrival caller runs next).+    ///+    /// **The version collisions are queried here too, not read from the cache+    /// alone.** The cache is the last full validation's answer, and every arrival+    /// caller reconciles before it refreshes — so a same-row collision that just+    /// synced in was invisible to the pass that was supposed to repair it. That is+    /// the state the two-device runbook reproduced: both devices taught the same+    /// already-synced row concurrently, CloudKit unioned two version-1 active+    /// patterns onto it, the arrival debounce fired and found nothing in+    /// `tupleDiagnoses`, and the row stayed broken until the next launch ran a+    /// full validation (Req 1.7).+    ///+    /// The query is not folded into `LibraryToleranceScan`: that pass reads+    /// identity columns and deliberately never faults `TitlePattern.site`, which+    /// grouping rules by their owning row requires. Its affordability is what+    /// pays for running it on every foreground, and this pass runs on neither+    /// the foreground nor the capture path, so the cost belongs here instead.+    /// The cached tuple set is still unioned in: it carries the tuple damage no+    /// column comparison can see.+    ///+    /// A repaired hostname is **re-validated before this returns**, so its stale+    /// tuple diagnosis stops being carried forward (Req 2.2). Without it the+    /// refresh that follows every arrival unioned the repaired hostname's old+    /// diagnosis straight back in, and Check Library reported an unresolved+    /// record against a library the pass had just made coherent — until the next+    /// relaunch ran the validation that would have said so.+    @discardableResult+    public func reconcileAfterSync() async throws -> SiteReconciliationOutcome {+        guard !bulkOperationInProgress else {+            reconcileDeferred = true+            return SiteReconciliationOutcome()+        }+        let cachedTuples = diagnostics.tupleDiagnoses++        bulkOperationInProgress = true+        defer { bulkOperationInProgress = false }+        let pass = try await withLockedContext(+            mode: .exclusive, operation: "reconciling Site rows after sync"+        ) { context in+            let work = try Self.reconcileWorkLists(context: context)+            let colliding = Set(cachedTuples.keys).union(work.colliding)++            var pass = ReconcilePass()+            pass.outcome = try SiteReconciler.run(+                duplicateHostnames: work.duplicates,+                collidingHostnames: colliding.sorted(),+                batchSize: Self.bulkOperationBatchSize,+                context: context,+                saveStrategy: saveStrategy)++            // Only the hostnames this pass wrote to *and* that arrived carrying a+            // diagnosis: a hostname with nothing to shed costs nothing, and every+            // other hostname's diagnosis is left to the carry-forward exactly as+            // the union invariant requires. The answer is a fresh full+            // validation — the same one a teaching commit runs — so a hostname+            // whose damage the pass could not repair stays diagnosed rather than+            // being cleared for having been touched.+            let repaired = pass.outcome.consolidatedHostnames.filter { cachedTuples[$0] != nil }+            if !repaired.isEmpty {+                // Only the repaired hostnames — usually one or two. The answer is+                // the same per-Site arm a whole-graph validation runs, over a+                // graph narrowed to them, so a hostname whose damage the pass+                // could not repair still stays diagnosed; what it no longer does+                // is replay every rule on every Entry in the library to say so.+                let revalidated = try V4LibraryValidator.validate(+                    hostnames: repaired, context: context)+                for hostname in repaired {+                    if let reason = revalidated[hostname] {+                        pass.stillDiagnosed[hostname] = reason+                    } else {+                        pass.cleared.append(hostname)+                    }+                }+            }+            return pass+        }++        for hostname in pass.cleared { recordPostCommitDiagnosis(nil, hostname: hostname) }+        for (hostname, reason) in pass.stillDiagnosed {+            recordPostCommitDiagnosis(reason, hostname: hostname)+        }+        let outcome = pass.outcome++        // Q46's second half, which only `confirmImport` used to honour. A+        // reconcile trigger that arrived while this pass held the flag deferred+        // rather than interleaving with its chunk saves, and nothing re-fired it+        // — so an arrival landing mid-pass was dropped until the next trigger.+        //+        // One re-fire, not a loop. The re-fired pass scans the store as it now+        // stands, so it already covers everything that arrived during this one;+        // a deferral latched *during* the re-fire is a third batch, and the+        // arrival debounce, the foreground refresh and the launch pass are all+        // still ahead of it. Re-firing until quiet would be correct too — passes+        // are idempotent and a no-op pass is cheap — but it makes the recursion+        // depend on arrival timing for no property this does not already have.+        await refireDeferredReconcile()+        return outcome+    }++    /// Runs the pass a trigger deferred while `bulkOperationInProgress` was held,+    /// if there was one (Q46's second half).+    ///+    /// Both holders of the flag end this way — this pass and `confirmImport` —+    /// and the release has to happen *here* rather than through the `defer` on+    /// the way out: a deferred pass that found the flag still set would defer+    /// itself, forever.+    internal func refireDeferredReconcile() async {+        guard reconcileDeferred else { return }+        reconcileDeferred = false+        bulkOperationInProgress = false+        _ = try? await reconcileAfterSync()+    }++    /// What one pass produced: what the reconciler wrote, and the re-validated+    /// answer for each repaired hostname that arrived carrying a diagnosis.+    /// Crosses out of the locked context, so every member is `Sendable`.+    private struct ReconcilePass: Sendable {+        var outcome = SiteReconciliationOutcome()+        /// Repaired, and validating now — the diagnosis is dropped.+        var cleared: [String] = []+        /// Repaired something, but still failing — the diagnosis is republished+        /// from this pass's answer rather than the stale one.+        var stillDiagnosed: [String: V4ValidationError] = [:]+    }++    /// The two hostname lists one reconciliation pass works from, in **one+    /// enumeration per table** — Sites, title rules, URL rules — and nothing else.+    ///+    /// - `duplicates`: hostnames holding more than one Site row, the class+    ///   `.duplicateSiteRows` reports. Derived from `Site.hostname` alone, which+    ///   is the only column the answer depends on.+    /// - `colliding`: hostnames whose rules carry the damage Decision 7 renumbers+    ///   away — a version used twice, a non-positive version, two rules marked+    ///   where one may be, or a current URL rule that does not hold the greatest+    ///   version. The same conditions `SiteUnionProjection.assignVersions`+    ///   renumbers for, so a hostname this names either converges on the pass+    ///   that follows or is one the projection declines to touch (untaught twins,+    ///   rules sharing a UUID) — in which case the pass costs one projection and+    ///   writes nothing, which is already true of every duplicated hostname.+    ///+    /// Rules are grouped by their owning row's hostname, which faults+    /// `TitlePattern.site` once per rule. A library holds one rule per teaching+    /// revision per hostname — orders of magnitude below its Entry count — and+    /// this runs on neither the capture path (Req 9.2) nor the foreground scan.+    private static func reconcileWorkLists(+        context: ModelContext+    ) throws -> (duplicates: [String], colliding: Set<String>) {+        // Round-trips against peak memory, matching `LibraryToleranceScan`.+        let batchSize = 1_000+        var siteRows: [String: Int] = [:]+        var patterns: [String: RuleTally] = [:]+        var rules: [String: RuleTally] = [:]++        try context.enumerate(FetchDescriptor<Site>(), batchSize: batchSize) { site in+            siteRows[site.hostname, default: 0] += 1+        }+        try context.enumerate(FetchDescriptor<TitlePattern>(), batchSize: batchSize) { pattern in+            guard let hostname = pattern.site?.hostname else { return }+            patterns[hostname, default: RuleTally()]+                .record(version: pattern.version, marked: pattern.isActive)+        }+        try context.enumerate(FetchDescriptor<URLRulePattern>(), batchSize: batchSize) { rule in+            guard let hostname = rule.site?.hostname else { return }+            rules[hostname, default: RuleTally()]+                .record(version: rule.version, marked: rule.isCurrent)+        }++        var colliding: Set<String> = []+        for (hostname, tally) in patterns where tally.collides { colliding.insert(hostname) }+        // The greatest-version invariant is the URL rules' alone: a title rule's+        // active revision is not required to be the newest.+        for (hostname, tally) in rules where tally.collides || tally.markedIsNotGreatest {+            colliding.insert(hostname)+        }+        // `Dictionary` iteration is per-process seeded; the reconciler sorts the+        // union it is handed, but the list it reports having worked from should+        // not depend on the seed either.+        return (siteRows.filter { $0.value > 1 }.keys.sorted(), colliding)+    }++    /// One hostname's rules of one type, counted without holding the rows.+    private struct RuleTally {+        private var count = 0+        private var versions: Set<Int> = []+        private var markedCount = 0+        private var greatest = Int.min+        private var markedVersion: Int?++        mutating func record(version: Int, marked: Bool) {+            count += 1+            versions.insert(version)+            greatest = max(greatest, version)+            if marked {+                markedCount += 1+                markedVersion = version+            }+        }++        var collides: Bool {+            versions.count != count || versions.contains { $0 <= 0 } || markedCount > 1+        }++        var markedIsNotGreatest: Bool { markedCount == 1 && markedVersion != greatest }+    }+     /// The quarantine reason for a Site, or nil when it validates.     func quarantineReason(hostname: String) -> V4ValidationError? { quarantined[hostname] } @@ -144,54 +444,13 @@ public actor LibraryRepository {         // the set stale here would let the next refresh re-quarantine a hostname         // this commit just repaired — Req 3.1 undone one foreground later, by         // the very mechanism that exists to keep diagnoses fresh.-        diagnostics = diagnostics.recordingTupleDiagnosis(-            Self.carriedTupleReason(diagnosis, hostname: hostname), hostname: hostname)+        diagnostics = diagnostics.recordingTupleDiagnosis(diagnosis, hostname: hostname)     } -    /// The part of a post-commit quarantine reason that belongs in the carried-    /// tuple set. `quarantineMap()` collapses `.duplicateSiteRows` into-    /// `.duplicate(type: "Site")` (Q24), which is not a tuple diagnosis and which-    /// the scan re-derives on its own — carrying it forward would publish a-    /// phantom `.siteTuple` row on every refresh thereafter.-    private static func carriedTupleReason(-        _ diagnosis: V4ValidationError?, hostname: String-    ) -> V4ValidationError? {-        guard let diagnosis else { return nil }-        if case .duplicate(let type, let id) = diagnosis, type == "Site", id == hostname {-            return nil-        }-        return diagnosis-    }--    /// Req 3.4. Refuses when the hostname carries more than one Site row.-    ///-    /// A teaching commit rewrites one row's tuple and says nothing about the-    /// second, so it cannot clear a `.duplicateSiteRows` diagnosis — reconciling-    /// the rows is phase 3. Every path that rewrites a Site's teaching state-    /// therefore refuses up front rather than sending the reader to an action-    /// that cannot succeed.-    ///-    /// Two things about the shape of this check are deliberate.-    ///-    /// It reads `diagnostics`, not `quarantined`. The quarantine map holds one-    /// reason per hostname and `.siteTuple` wins when a hostname carries both-    /// (Q24), so a hostname that is duplicated *and* tuple-invalid would be-    /// invisible in the projection.-    ///-    /// And it is narrow on purpose. `.siteTuple` quarantines but must **not**-    /// refuse here: it is precisely the class re-teaching exists to clear-    /// (Req 3.1). `.siteMissing` and `.duplicateIdentity` do not quarantine at-    /// all (Q12). Widening this to "any quarantine" would restore the dead end-    /// Req 3 removes.-    func requireNoDuplicateSiteRows(hostname: String) throws {-        for case .duplicateSiteRows(let host, let rowCount) in diagnostics.diagnoses-        where host == hostname {-            throw LibraryRepositoryError.quarantined(-                hostname: hostname,-                reason: "\(rowCount) Site rows exist for this hostname; "-                    + "re-teaching cannot clear that")-        }-    }+    /// What this open did about CloudKit mirroring (Req 8.4, Q44). `.failed` is+    /// the only evidence that a misconfigured build is running local-only, since+    /// the library itself works either way.+    public private(set) var mirroring: MirroringAttachment      internal init(         configuration: LibraryConfiguration,@@ -200,7 +459,8 @@ public actor LibraryRepository {         clock: any RepositoryClock,         saveStrategy: any RepositorySaveStrategy,         quarantined: [String: V4ValidationError] = [:],-        diagnostics: LibraryDiagnostics = .empty+        diagnostics: LibraryDiagnostics = .empty,+        mirroring: MirroringAttachment = .notRequested     ) {         self.configuration = configuration         self.container = container@@ -209,6 +469,44 @@ public actor LibraryRepository {         self.saveStrategy = saveStrategy         self.quarantined = quarantined         self.diagnostics = diagnostics+        self.mirroring = mirroring+    }++    /// Releases the container so the next open constructs the only live one for+    /// this store (Q43).+    ///+    /// Awaited by `AppLibraryModel` before any re-`bootstrap()` — `retry()` and+    /// the UI-test reseed path. Without it a re-open runs while the previous+    /// repository still retains its container, which under mirroring is the+    /// in-process 134422 collision (Q24). Idempotent; every operation afterwards+    /// fails with a reason that says the library was shut down, rather than+    /// touching a store this process no longer claims.+    ///+    /// Declared `async` deliberately, though it awaits nothing. `LibraryProviding`+    /// requires `shutdown() async` and carries a no-op default for test doubles;+    /// a sync member here would lose overload resolution to that default in an+    /// async context, and the teardown would silently do nothing — which is how+    /// this comment came to be written.+    public func shutdown() async {+        guard container != nil else { return }+        container = nil+        Self.logger.debug("Repository shut down; container released")+    }++    /// The live container, or a failure naming the shutdown.+    private func liveContainer(_ operation: String) throws -> ModelContainer {+        guard let container else {+            throw LibraryRepositoryError.libraryUnavailable(+                operation: operation,+                reason: "the repository has been shut down; re-open the library before using it")+        }+        return container+    }++    /// Identity of the container this repository holds. Test seam: it is how a+    /// test tells the mirrored container from the certification one (Q35).+    internal func containerIdentity() -> ObjectIdentifier? {+        container.map(ObjectIdentifier.init)     }      /// Source-compatible app-owned open. New runtime call sites should use the@@ -732,7 +1030,13 @@ public actor LibraryRepository {         entry.modifiedAt = timestamp     } -    public func debugCounts() async throws -> LibraryRecordCounts {+    /// The library's record counts.+    ///+    /// Named `debugCounts` while nothing but a test read it. The import preview+    /// now puts these numbers in front of the reader — "your library holds N+    /// entries" beside what the archive holds — so the name had to stop calling+    /// them debug output.+    public func recordCounts() async throws -> LibraryRecordCounts {         try await withLockedContext(mode: .shared, operation: "reading coherent library counts") { context in             try LibraryRecordCounts(                 entries: context.fetchCount(FetchDescriptor<Entry>()),@@ -744,6 +1048,12 @@ public actor LibraryRepository {         }     } +    /// The former name of `recordCounts()`, kept because the package's suites+    /// call it by the hundred and renaming them is not what this change is about.+    public func debugCounts() async throws -> LibraryRecordCounts {+        try await recordCounts()+    }+     // MARK: - Backup Support      internal func withLockedBackupContext<Value: Sendable>(@@ -850,7 +1160,7 @@ public actor LibraryRepository {             timeout: Self.interactiveLockTimeout         )         defer { withExtendedLifetime(lease) {} }-        let context = ModelContext(container)+        let context = ModelContext(try liveContainer(operation))         do { return try body(context) }         catch let error as LibraryRepositoryError { throw error }         catch {

diff --git a/Packages/AsterismCore/Sources/AsterismCore/MirroringOpen.swift b/Packages/AsterismCore/Sources/AsterismCore/MirroringOpen.swiftnew file mode 100644index 0000000..dac3968--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/MirroringOpen.swift@@ -0,0 +1,71 @@+import Foundation+import SwiftData++/// What the app's open did about CloudKit mirroring.+///+/// Recorded on the repository so the sync surface can name a misconfiguration+/// rather than report success (Req 8.4, Q44): a bad container identifier or a+/// missing entitlement degrades sync and leaves the library working, so the+/// only evidence that anything is wrong is this value.+public enum MirroringAttachment: Equatable, Sendable {+    /// No container identifier was injected — the configuration cannot mirror.+    /// Every host test, UI-test root, migration helper and extension open is+    /// this case, and so is an app build with `ASTERISM_MIRRORING_ENABLED = NO`.+    case notRequested+    /// The long-lived container was constructed with `.private(containerID)`.+    case attached(containerID: String)+    /// `.private` construction threw; the library opened on `.none` instead and+    /// runs local-only (Q44).+    case failed(containerID: String, reason: String)++    public var isMirroring: Bool {+        if case .attached = self { return true }+        return false+    }+}++/// The two seams the mirrored open needs to be testable on a host with no+/// iCloud entitlement.+///+/// Production passes `.production`, whose factory is the real+/// `.private(containerID)` construction. A test passes its own to observe *when*+/// the mirrored container is constructed relative to the readiness marker+/// (Req 6.1) and to make construction fail on demand (Q44) — neither of which a+/// host can otherwise reach, because `.private` construction always fails there.+public struct MirroringOpenHooks: Sendable {+    /// Constructs the app's long-lived mirrored container over the marked store.+    public var makeMirroredContainer: @Sendable (_ storeURL: URL, _ containerID: String) throws -> ModelContainer++    /// Handed the certification container immediately before the bootstrap lets+    /// go of it. Test seam only: the design requires that release to be+    /// deterministic (there is no `close()`, and two live containers over one+    /// store in one process is the 134422 collision — Q24, Q35), and a test that+    /// holds this weakly is the only way to prove it happened.+    ///+    /// Internal, unlike its sibling: nothing outside the package sets it, and the+    /// suites that do reach it through `@testable import`. A public seam would+    /// invite an embedder to hold the container this exists to prove is released.+    internal var certificationContainerObserver: (@Sendable (ModelContainer) -> Void)?++    public init(+        makeMirroredContainer: @escaping @Sendable (URL, String) throws -> ModelContainer = { storeURL, containerID in+            try LibraryRepository.openV4Container(at: storeURL, mirroring: .private(containerID))+        }+    ) {+        self.makeMirroredContainer = makeMirroredContainer+    }++    /// The in-package initializer, the only one that can wire the certification+    /// observer.+    internal init(+        makeMirroredContainer: @escaping @Sendable (URL, String) throws -> ModelContainer = { storeURL, containerID in+            try LibraryRepository.openV4Container(at: storeURL, mirroring: .private(containerID))+        },+        certificationContainerObserver: (@Sendable (ModelContainer) -> Void)?+    ) {+        self.makeMirroredContainer = makeMirroredContainer+        self.certificationContainerObserver = certificationContainerObserver+    }++    public static let production = MirroringOpenHooks()+}

diff --git a/Packages/AsterismCore/Sources/AsterismCore/SiteReconciler.swift b/Packages/AsterismCore/Sources/AsterismCore/SiteReconciler.swiftnew file mode 100644index 0000000..fd46bb2--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/SiteReconciler.swift@@ -0,0 +1,341 @@+import Foundation+import SwiftData++/// What one reconciliation pass did. Public because `LibraryProviding` vends the+/// pass and the app's models take the protocol, not the actor.+///+/// (The design wrote this as `SiteReconciler.Outcome`; the reconciler itself is+/// internal, so the outcome is lifted to file scope rather than making the whole+/// enum public to carry it.)+public struct SiteReconciliationOutcome: Equatable, Sendable {+    /// Hostnames whose teaching moved onto one row this pass — and, since+    /// Decision 7, hostnames whose single row the union repaired in place, which+    /// is the same question asked of the same write.+    ///+    /// Read as "what this pass repaired": `reconcileAfterSync` re-validates each+    /// of these before it returns, so a hostname the pass fixed stops carrying+    /// the diagnosis the last full validation left on it (Req 2.2).+    public var consolidatedHostnames: [String] = []+    /// Records whose `site` relationship was pointed at the survivor.+    public var repinnedRecords = 0+    /// Rule rows whose owner or version the union rewrote.+    public var renumberedRules = 0+    /// Records whose nil relationship was healed against a surviving row+    /// (Req 1.8) outside a consolidation.+    public var healedRecords = 0++    public init() {}++    public var isEmpty: Bool {+        consolidatedHostnames.isEmpty && repinnedRecords == 0+            && renumberedRules == 0 && healedRecords == 0+    }+}++/// Makes the Site graph coherent after records arrive from sync (Req 1.1–1.8).+///+/// **Additive-only: no row is ever deleted, and none is ever created**+/// (Decision 6, Q40). A merge *moves*: the losers' rules re-parent to the+/// survivor, records re-pin, and the stripped loser stays as an untaught row+/// holding nothing the reader, capture, or the archive can observe. That is not+/// tidiness deferred — CloudKit applies one local save as many remote+/// transactions (45 for 3,000 records, Q25), so a deletion races its own+/// re-parent on the receiving device and `Site.patterns`'s `.cascade` destroys+/// the union. With no deletions the worst outcome of a divergent merge is rule+/// custody sitting on the "wrong" row until both devices see the same content,+/// at which point the deterministic order moves it identically on both.+///+/// Everything it decides comes from `SiteUnionProjection`, which export and+/// import also read, so the reconciled shape and the archived shape are the same+/// shape by construction (Q38, Req 3.5).+///+/// Contracts: idempotent (`run ∘ run = run`), deterministic given synced content+/// (Req 1.5), silent (Req 1.2), never on the capture path (Req 9.2), and never+/// promoted by elapsed time (Req 2.4 — nothing here reads a clock).+enum SiteReconciler {++    /// One pass.+    ///+    /// The two hostname lists are **unioned**, so a caller holding one list of+    /// hostnames-to-reconcile passes it once and leaves the other empty.+    /// `duplicateHostnames` are the ones holding more than one Site row;+    /// `collidingHostnames` are the ones whose rules may carry the same-row+    /// version collision two concurrent teaches produce (Decision 7), which no+    /// row count can see — `LibraryRepository.reconcileAfterSync` composes that+    /// list from its own rule tallies and the `.siteTuple` set.+    ///+    /// `rowsByHostname` is every Site row a hostname holds, when the caller+    /// already has them. Import does: its upsert fetched and grouped the whole+    /// Site table two steps earlier, and letting this re-derive the same grouping+    /// costs one predicate fetch per archived hostname. Nil means "fetch them",+    /// which is what an arrival-triggered pass wants — its rows changed under it.+    /// A hostname absent from a supplied map holds no rows and is skipped.+    ///+    /// Records are found by hostname predicate and by `site == nil`, **never by+    /// traversing `Site.entries`**: that inverse is internal precisely because+    /// walking it faults every Entry for a hostname (relational-references Q17),+    /// and `SiteInverseReachTests` pins that it stays unreached.+    static func run(+        duplicateHostnames: [String],+        collidingHostnames: [String] = [],+        rowsByHostname: [String: [Site]]? = nil,+        batchSize: Int,+        context: ModelContext,+        saveStrategy: any RepositorySaveStrategy+    ) throws -> SiteReconciliationOutcome {+        var outcome = SiteReconciliationOutcome()++        // Sorted, so two runs over the same store do the same work in the same+        // order — `Set` iteration is per-process seeded.+        for hostname in Set(duplicateHostnames).union(collidingHostnames).sorted() {+            let rows: [Site]+            if let rowsByHostname {+                rows = rowsByHostname[hostname] ?? []+            } else {+                rows = try LibraryRepository.fetchSites(hostname: hostname, context: context)+            }+            let projection = SiteUnionProjection.project(hostname: hostname, rows: rows)+            guard projection.consolidates, let survivor = projection.survivor else { continue }++            // The rule union and every demotion land in one save: a receiving+            // device must never see a rule re-parented without the version that+            // travels with it. Nothing is saved where nothing was dirtied —+            // that is what makes `run ∘ run = run`, and a converged hostname+            // still reaches here on every pass, because additive-only leaves the+            // stripped rows in place and `.duplicateSiteRows` standing.+            let union = applyUnion(projection, survivor: survivor)+            outcome.renumberedRules += union.rules+            if union.changed { try saveStrategy.save(context) }++            let repin = try repin(+                hostname: hostname, survivor: survivor,+                rewrites: projection.versionRewrites, batchSize: batchSize,+                context: context, saveStrategy: saveStrategy)+            outcome.repinnedRecords += repin.repinned+            if union.changed || repin.changed { outcome.consolidatedHostnames.append(hostname) }+        }++        outcome.healedRecords = try heal(+            batchSize: batchSize, context: context, saveStrategy: saveStrategy)+        return outcome+    }++    // MARK: - Rule custody (Req 1.1, 1.3, Decision 7)++    /// Re-parents the union's rules to the survivor, applies the renumbering and+    /// the demotions, and leaves every stripped row legal.+    ///+    /// Each write is guarded by a comparison, so a second run over a reconciled+    /// graph dirties nothing — which is also the convergence mechanism when a+    /// late relationship heal disturbs a prior pass.+    private static func applyUnion(+        _ projection: SiteUnionProjection.ProjectedSite, survivor: Site+    ) -> (rules: Int, changed: Bool) {+        var rewritten = 0+        var changed = false++        for projected in projection.patterns {+            let pattern = projected.pattern+            var touched = false+            if pattern.site !== survivor {+                pattern.site = survivor+                touched = true+            }+            if pattern.version != projected.version {+                pattern.version = projected.version+                touched = true+            }+            if pattern.isActive != projected.isActive {+                pattern.isActive = projected.isActive+                touched = true+            }+            if touched {+                rewritten += 1+                changed = true+            }+        }++        for projected in projection.urlRules {+            let rule = projected.rule+            var touched = false+            if rule.site !== survivor {+                rule.site = survivor+                touched = true+            }+            if rule.version != projected.version {+                rule.version = projected.version+                touched = true+            }+            if rule.isCurrent != projected.isCurrent {+                rule.isCurrent = projected.isCurrent+                touched = true+            }+            if touched {+                rewritten += 1+                changed = true+            }+        }++        if survivor.mode != projection.mode {+            survivor.mode = projection.mode+            changed = true+        }+        if survivor.junkSuffixRule == nil, let junk = projection.junkSuffixRule {+            survivor.junkSuffixRule = junk+            changed = true+        }++        // A stripped row holds no rules at all afterwards, and `.taught` with no+        // active title rule is an illegal tuple. Leaving it would have the+        // reconciler manufacture exactly the quarantine it exists to prevent.+        // `.articles` and `.untaught` are both legal empty, so they stay.+        for row in projection.strippedRows where row.mode == .taught {+            row.mode = .untaught+            changed = true+        }++        return (rewritten, changed)+    }++    // MARK: - Re-pin and citation rewrite (Req 1.4, 1.8)++    /// Points a hostname's records at the survivor and rewrites their rule+    /// citations, in chunks.+    ///+    /// Chunking is not a nicety: re-pinning a 5,000-record hostname in one save+    /// is the 17 s shape Q27 measured, because the cost is inverse-array+    /// maintenance and it is superlinear. Every chunk boundary is a legal+    /// library, and idempotence makes an interruption safe — the next trigger+    /// converges it.+    private static func repin(+        hostname: String,+        survivor: Site,+        rewrites: [UUID: Int],+        batchSize: Int,+        context: ModelContext,+        saveStrategy: any RepositorySaveStrategy+    ) throws -> (repinned: Int, changed: Bool) {+        var repinned = 0+        var changed = false++        let entries = try context.fetch(+            FetchDescriptor<Entry>(predicate: #Predicate { $0.hostname == hostname }))+        for chunk in chunks(of: entries, size: batchSize) {+            var dirty = false+            for entry in chunk {+                if entry.site !== survivor {+                    entry.site = survivor+                    repinned += 1+                    dirty = true+                }+                if rewriteCitations(of: entry, rewrites) { dirty = true }+            }+            if dirty {+                changed = true+                try saveStrategy.save(context)+            }+        }++        let works = try context.fetch(+            FetchDescriptor<Work>(predicate: #Predicate { $0.siteHostname == hostname }))+        for chunk in chunks(of: works, size: batchSize) {+            var dirty = false+            for work in chunk {+                if work.site !== survivor {+                    work.site = survivor+                    repinned += 1+                    dirty = true+                }+                if rewriteCitations(of: work, rewrites) { dirty = true }+            }+            if dirty {+                changed = true+                try saveStrategy.save(context)+            }+        }++        return (repinned, changed)+    }++    /// Req 1.8's defensive heal: a record whose relationship is nil while a row+    /// for its hostname exists is pointed at the row the deterministic order+    /// selects.+    ///+    /// Under additive-only reconciliation no merge produces this state — its one+    /// known producer, CloudKit `.nullify` against a deleted loser row, went away+    /// with the deletions (Decision 6). It stays as the heal for whatever else+    /// does. A hostname with *no* row is left alone: the row is en route, and+    /// writing against its absence is what would mint duplicates during every+    /// hydration (Q40).+    private static func heal(+        batchSize: Int, context: ModelContext, saveStrategy: any RepositorySaveStrategy+    ) throws -> Int {+        let entries = try context.fetch(+            FetchDescriptor<Entry>(predicate: #Predicate { $0.site == nil }))+        let works = try context.fetch(+            FetchDescriptor<Work>(predicate: #Predicate { $0.site == nil }))+        guard !entries.isEmpty || !works.isEmpty else { return 0 }++        var winners: [String: Site] = [:]+        for hostname in Set(entries.map(\.hostname)).union(works.map(\.siteHostname)) {+            winners[hostname] = try LibraryRepository.fetchSites(+                hostname: hostname, context: context).first+        }++        var healed = 0+        for chunk in chunks(of: entries, size: batchSize) {+            var dirty = false+            for entry in chunk {+                guard let winner = winners[entry.hostname] else { continue }+                entry.site = winner+                healed += 1+                dirty = true+            }+            if dirty { try saveStrategy.save(context) }+        }+        for chunk in chunks(of: works, size: batchSize) {+            var dirty = false+            for work in chunk {+                guard let winner = winners[work.siteHostname] else { continue }+                work.site = winner+                healed += 1+                dirty = true+            }+            if dirty { try saveStrategy.save(context) }+        }+        return healed+    }++    /// Rewrites an Entry's seven `(rule id, version)` citations through the+    /// union's map. Rule UUIDs are unique, so the new version is a lookup and+    /// provenance replay keeps resolving across the merge (Req 1.4).+    ///+    /// The seven pairs come from `Entry.ruleCitations`, so a citation added to+    /// the model is rewritten here without this method being touched.+    private static func rewriteCitations(of entry: Entry, _ rewrites: [UUID: Int]) -> Bool {+        guard !rewrites.isEmpty else { return false }+        var changed = false+        for citation in Entry.ruleCitations {+            guard let id = entry[keyPath: citation.id], let replacement = rewrites[id],+                  entry[keyPath: citation.version] != replacement else { continue }+            entry[keyPath: citation.version] = replacement+            changed = true+        }+        return changed+    }++    private static func rewriteCitations(of work: Work, _ rewrites: [UUID: Int]) -> Bool {+        guard !rewrites.isEmpty else { return false }+        return rewrite(work.urlIdentityRuleID, &work.urlIdentityRuleVersion, rewrites)+    }++    private static func rewrite(_ id: UUID?, _ version: inout Int?, _ rewrites: [UUID: Int]) -> Bool {+        guard let id, let replacement = rewrites[id], version != replacement else { return false }+        version = replacement+        return true+    }++    private static func chunks<Element>(of values: [Element], size: Int) -> [ArraySlice<Element>] {+        LibraryRepository.chunks(of: values, size: size)+    }+}