Pre-push review: T-2156/rule-suggestion

diff --git a/Asterism/Asterism.xcodeproj/project.pbxproj b/Asterism/Asterism.xcodeproj/project.pbxprojindex 4a0a532..7ef2f6e 100644--- a/Asterism/Asterism.xcodeproj/project.pbxproj+++ b/Asterism/Asterism.xcodeproj/project.pbxproj@@ -15,6 +15,8 @@ 		A10000000000000000000019 /* ConstellationKit in Frameworks */ = {isa = PBXBuildFile; productRef = A1000000000000000000001C /* ConstellationKit */; }; 		A1000000000000000000001A /* ConstellationKit in Frameworks */ = {isa = PBXBuildFile; productRef = A1000000000000000000001D /* ConstellationKit */; }; 		A1000000000000000000001E /* AsterismCore in Frameworks */ = {isa = PBXBuildFile; productRef = A1000000000000000000001F /* AsterismCore */; };+		A10000000000000000000020 /* AsterismIntelligence in Frameworks */ = {isa = PBXBuildFile; productRef = A10000000000000000000022 /* AsterismIntelligence */; };+		A10000000000000000000021 /* AsterismIntelligence in Frameworks */ = {isa = PBXBuildFile; productRef = A10000000000000000000023 /* AsterismIntelligence */; }; /* End PBXBuildFile section */  /* Begin PBXContainerItemProxy section */@@ -124,6 +126,7 @@ 			files = ( 				A10000000000000000000001 /* AsterismCore in Frameworks */, 				A10000000000000000000018 /* ConstellationKit in Frameworks */,+				A10000000000000000000020 /* AsterismIntelligence in Frameworks */, 			); 			runOnlyForDeploymentPostprocessing = 0; 		};@@ -133,6 +136,7 @@ 			files = ( 				A10000000000000000000014 /* AsterismCore in Frameworks */, 				A1000000000000000000001A /* ConstellationKit in Frameworks */,+				A10000000000000000000021 /* AsterismIntelligence in Frameworks */, 			); 			runOnlyForDeploymentPostprocessing = 0; 		};@@ -218,6 +222,7 @@ 			name = Asterism; 			packageProductDependencies = ( 				A10000000000000000000011 /* AsterismCore */,+				A10000000000000000000022 /* AsterismIntelligence */, 				A1000000000000000000001B /* ConstellationKit */, 			); 			productName = Asterism;@@ -243,6 +248,7 @@ 			name = AsterismTests; 			packageProductDependencies = ( 				A10000000000000000000013 /* AsterismCore */,+				A10000000000000000000023 /* AsterismIntelligence */, 				A1000000000000000000001D /* ConstellationKit */, 			); 			productName = AsterismTests;@@ -922,6 +928,16 @@ 			package = A10000000000000000000010 /* XCLocalSwiftPackageReference "../Packages/AsterismCore" */; 			productName = AsterismCore; 		};+		A10000000000000000000022 /* AsterismIntelligence */ = {+			isa = XCSwiftPackageProductDependency;+			package = A10000000000000000000010 /* XCLocalSwiftPackageReference "../Packages/AsterismCore" */;+			productName = AsterismIntelligence;+		};+		A10000000000000000000023 /* AsterismIntelligence */ = {+			isa = XCSwiftPackageProductDependency;+			package = A10000000000000000000010 /* XCLocalSwiftPackageReference "../Packages/AsterismCore" */;+			productName = AsterismIntelligence;+		}; /* End XCSwiftPackageProductDependency section */ 	}; 	rootObject = D4A9C78C30091593004199A5 /* Project object */;

diff --git a/Asterism/Asterism/ContentView.swift b/Asterism/Asterism/ContentView.swiftindex 2f2a5f5..69c95cc 100644--- a/Asterism/Asterism/ContentView.swift+++ b/Asterism/Asterism/ContentView.swift@@ -202,6 +202,16 @@ struct ContentView: View {         .onReceive(NotificationCenter.default.publisher(for: UIApplication.didBecomeActiveNotification)) { _ in             Task { await model.handleActivation() }         }+        // `rule-suggestion` Req 5.3: the background sweep stops with the+        // foreground. On-open and on-request work is the reader's and continues.+        .onReceive(NotificationCenter.default.publisher(for: UIApplication.willResignActiveNotification)) { _ in+            model.suggestions?.resignActive()+        }+        // Req 5.6: held suggestions are cheap to recompute and are the first+        // thing to go under memory pressure.+        .onReceive(NotificationCenter.default.publisher(for: UIApplication.didReceiveMemoryWarningNotification)) { _ in+            model.suggestions?.memoryWarning()+        }     }      private var readyContent: some View {

diff --git a/Asterism/Asterism/RuleSuggestion/RuleSuggester.swift b/Asterism/Asterism/RuleSuggestion/RuleSuggester.swiftnew file mode 100644index 0000000..5d97be8--- /dev/null+++ b/Asterism/Asterism/RuleSuggestion/RuleSuggester.swift@@ -0,0 +1,420 @@+import AsterismCore+import AsterismIntelligence+import Foundation++/// One suggestion attempt for one hostname. The seam the coordinator holds, so+/// its tests need no model and no library.+protocol RuleSuggesting: Sendable {+    /// Steps 1–7 of the design's attempt pipeline.+    ///+    /// Throws `AttemptTimeout` when the work outlived its bound, and+    /// `CancellationError` when the system cancelled it. Everything else — an+    /// unreadable basis, a model failure, a proposal nothing survives — is a+    /// settled attempt with `nil`, because Req 4.2 forbids any of it reaching+    /// the reader.+    func attempt(hostname: String) async throws -> (suggestion: RuleSuggestion?, modelPhase: Duration)+}++/// The attempt pipeline: read the basis, ask the model, locate what it copied,+/// assemble the rules, verify them against the whole hostname.+///+/// An actor, and deliberately not the main one: the model call and up to four+/// projections must never run on the main actor (Req 5.1). It owns no state+/// beyond its two dependencies — the ledger, the budget and the in-flight+/// `Task` all live in the coordinator.+actor RuleSuggester: RuleSuggesting {+    private let library: any LibraryProviding+    private let model: any RuleSuggestionModelClient+    /// Injected so the timeout path is testable in milliseconds rather than in+    /// the ten seconds Req 5.10 sets.+    private let timeout: Duration++    /// Production's initializer: Req 5.10's bound and nothing else to choose.+    ///+    /// **Main-actor isolated, and cannot be made otherwise here.** Under this+    /// target's `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` *every*+    /// initializer below is `@MainActor` — delegating or not, and whether or+    /// not the bound is a default argument (measured: a nonisolated call site+    /// warns "call to main actor-isolated initializer … in a synchronous+    /// nonisolated context" for the three-argument initializer just as much as+    /// for this one). `nonisolated` cannot buy the way out: the compiler+    /// rejects it on an actor's synchronous initializer outright, as+    /// "'nonisolated' on an actor's synchronous initializer is invalid".+    ///+    /// That costs nothing: the suggester is constructed at the app's wiring+    /// point, which is main-actor anyway, and every *use* of it — `attempt` —+    /// is on the actor. Only construction is pinned.+    init(library: any LibraryProviding, model: any RuleSuggestionModelClient) {+        self.init(library: library, model: model,+                  timeout: RuleSuggestionBounds.attemptTimeout)+    }++    /// The timeout is injected here so its path is testable in milliseconds+    /// rather than in the ten seconds Req 5.10 sets.+    init(+        library: any LibraryProviding,+        model: any RuleSuggestionModelClient,+        timeout: Duration+    ) {+        self.library = library+        self.model = model+        self.timeout = timeout+    }++    /// The projection that reads the basis: the same whole-title, no-URL request+    /// `ComposedTeachingViewModel.load()` opens with, so the suggester sees the+    /// hostname exactly as the editor will.+    private nonisolated static let basisRequest = ComposedTeachingRequest(+        titleDefinition: .wholeTitle, trimPrefix: nil, trimSuffix: nil,+        urlDefinition: nil, acknowledgeUnsettled: false, permitsArticlesConversion: false)++    func attempt(+        hostname: String+    ) async throws -> (suggestion: RuleSuggestion?, modelPhase: Duration) {+        // Step 1. An articles-mode Site makes this throw, and so does an+        // unreadable library; both settle the attempt with nothing to show.+        let basis: ComposedTeachingBasis+        do {+            basis = try await library+                .projectComposedTeaching(hostname: hostname, request: Self.basisRequest).basis+        } catch {+            if error is CancellationError { throw error }+            RuleSuggestionLog.failure(+                "\(hostname): basis projection failed — \(RuleSuggestionLog.describe(error))")+            return (nil, .zero)+        }++        // Step 2.+        guard let corpus = SuggestionCorpus.make(from: basis.entries, hostname: hostname) else {+            RuleSuggestionLog.note("\(hostname): empty corpus — the basis holds no captures")+            return (nil, .zero)+        }+        RuleSuggestionLog.note("\(hostname): corpus of \(corpus.examples.count) captures")++        // Steps 3–6 under the timeout, measured from the model request.+        let started = ContinuousClock.now+        let outcome = try await withThrowingTaskGroup(of: PipelineOutcome.self) { group in+            group.addTask {+                .settled(try await self.run(corpus: corpus, basis: basis, hostname: hostname))+            }+            group.addTask {+                try await Task.sleep(for: self.timeout)+                return .timedOut+            }+            guard let first = try await group.next() else { throw CancellationError() }+            // Whichever lost is cancelled here and awaited on scope exit, so a+            // timeout is thrown only once the work has actually stopped.+            group.cancelAll()+            return first+        }++        switch outcome {+        case .settled(let suggestion):+            return (suggestion, started.duration(to: .now))+        case .timedOut:+            throw AttemptTimeout(modelPhase: started.duration(to: .now))+        }+    }++    private nonisolated enum PipelineOutcome: Sendable {+        case settled(RuleSuggestion?)+        case timedOut+    }++    // MARK: - Steps 3–6++    private func run(+        corpus: SuggestionCorpus, basis: ComposedTeachingBasis, hostname: String+    ) async throws -> RuleSuggestion? {+        // Step 3.+        guard let proposal = try await propose(corpus) else { return nil }++        // Step 4.+        let anchor = corpus.anchor+        let titleWork = ProposalLocator.locate(proposal.workName, in: anchor.title)+        if titleWork == nil {+            RuleSuggestionLog.note(+                "\(hostname): workName not located exactly once in the anchor title",+                content: "workName=\"\(proposal.workName)\" title=\"\(anchor.title)\"")+        }+        // The optional field dies with the required one on its own side: a+        // chapter span with no Work span authors nothing (Req 3.1, Q49).+        var titleChapter: Range<Int>?+        if let titleWork {+            titleChapter = ProposalLocator.locate(proposal.chapterText, in: anchor.title)+            if titleChapter == nil, !proposal.chapterText.isEmpty {+                RuleSuggestionLog.note(+                    "\(hostname): chapterText not located exactly once in the anchor title",+                    content: "chapterText=\"\(proposal.chapterText)\" title=\"\(anchor.title)\"")+            }+            if let chapter = titleChapter, chapter.overlaps(titleWork) {+                RuleSuggestionLog.note(+                    "\(hostname): chapterText span overlaps the workName span; chapter dropped")+                titleChapter = nil+            }+        }++        let components = try? RawURLRuleParser.parse(ExactScalarString(anchor.rawURL))+        var urlIdentity: LocatedURLSpan?+        var urlSequence: LocatedURLSpan?+        if let components {+            urlIdentity = Self.locate(proposal.urlWorkIdentity, in: components)+            if urlIdentity == nil {+                RuleSuggestionLog.note(+                    "\(hostname): urlWorkIdentity not located in exactly one URL component",+                    content: "urlWorkIdentity=\"\(proposal.urlWorkIdentity)\" url=\"\(anchor.rawURL)\"")+            }+            if urlIdentity != nil {+                urlSequence = Self.locate(proposal.urlSequenceText, in: components)+                if urlSequence == nil, !proposal.urlSequenceText.isEmpty {+                    RuleSuggestionLog.note(+                        "\(hostname): urlSequenceText not located in exactly one URL component",+                        content: "urlSequenceText=\"\(proposal.urlSequenceText)\" url=\"\(anchor.rawURL)\"")+                }+            }+            if let identity = urlIdentity, let sequence = urlSequence,+               identity.selection == sequence.selection, identity.range.overlaps(sequence.range) {+                RuleSuggestionLog.note(+                    "\(hostname): urlSequenceText span overlaps urlWorkIdentity's; sequence dropped")+                urlSequence = nil+            }+        } else {+            RuleSuggestionLog.note(+                "\(hostname): the anchor URL did not parse; no URL side",+                content: "url=\"\(anchor.rawURL)\"")+        }++        // Short-circuit (Q44): with neither a chapter nor a sequence the+        // projection sets `requiresUnsettledAcknowledgment`, which Req 3.4+        // rejects — so the up-to-three projections would all fail.+        guard titleChapter != nil || urlSequence != nil else {+            RuleSuggestionLog.note(+                "\(hostname): no chapter span and no sequence span; chapters would be unsettled")+            return nil+        }++        // Step 5.+        let title = titleWork.flatMap {+            RuleSuggestionAssembler.titleRule(+                anchorTitle: anchor.title, workSpan: $0, chapterSpan: titleChapter)+        }+        let url = components.flatMap { parsed in+            urlIdentity.flatMap { identity in+                RuleSuggestionAssembler.urlRule(+                    components: parsed, identity: (identity.selection, identity.range),+                    sequence: urlSequence.map { ($0.selection, $0.range) })+            }+        }+        if titleWork != nil, title == nil {+            RuleSuggestionLog.note(+                "\(hostname): the editor would author no title rule from those spans")+        }+        if urlIdentity != nil, url == nil {+            RuleSuggestionLog.note(+                "\(hostname): the editor would author no URL rule from those selections")+        }++        // A title rule equal to the untaught default is worth nothing on its+        // own — it would badge the state the editor already opens in — so it+        // survives only alongside a URL side.+        let soloTitle = title.flatMap { Self.isUntaughtDefault($0) ? nil : $0 }+        guard url != nil || soloTitle != nil else {+            RuleSuggestionLog.note(+                "\(hostname): nothing to offer — no URL rule, and the title rule is the untaught default")+            return nil+        }++        // Step 6, in the design's order. The first passing set wins.+        if let title, let url,+           try await verifies(+            hostname: hostname, candidateSet: .titleAndURL, basis: basis,+            request: Self.request(title: title, url: url)) {+            RuleSuggestionLog.note("\(hostname): verified \(CandidateSet.titleAndURL.rawValue)")+            return RuleSuggestion(hostname: hostname, title: title, url: url)+        }+        if let soloTitle,+           try await verifies(+            hostname: hostname, candidateSet: .titleOnly, basis: basis,+            request: Self.request(title: soloTitle, url: basis.currentURLRule?.definition)) {+            RuleSuggestionLog.note("\(hostname): verified \(CandidateSet.titleOnly.rawValue)")+            return RuleSuggestion(hostname: hostname, title: soloTitle, url: nil)+        }+        if let url,+           try await verifies(+            hostname: hostname, candidateSet: .urlOnly, basis: basis,+            request: Self.request(title: Self.storedTitle(basis), url: url)) {+            RuleSuggestionLog.note("\(hostname): verified \(CandidateSet.urlOnly.rawValue)")+            return RuleSuggestion(hostname: hostname, title: nil, url: url)+        }+        RuleSuggestionLog.note("\(hostname): no candidate set verified")+        return nil+    }++    /// Step 3: the model, halving the corpus on an overflow rather than giving+    /// up on the hostname (Req 3.7). `halved()` returns nil at the anchor-alone+    /// floor, which is what ends the loop (Q53).+    private func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal? {+        var current: SuggestionCorpus? = corpus+        while let attempted = current {+            do {+                RuleSuggestionLog.note(+                    "\(attempted.hostname): model call, \(attempted.examples.count) captures")+                let proposal = try await model.propose(attempted)+                RuleSuggestionLog.note(+                    "\(attempted.hostname): model proposed", content: Self.describe(proposal))+                return proposal+            } catch {+                if error is CancellationError { throw error }+                guard model.isContextWindowOverflow(error) else {+                    RuleSuggestionLog.failure(+                        "\(attempted.hostname): model call failed — \(model.describe(error))")+                    return nil+                }+                RuleSuggestionLog.note(+                    "\(attempted.hostname): context window overflow at \(attempted.examples.count) captures; halving")+                current = attempted.halved()+            }+        }+        RuleSuggestionLog.note("\(corpus.hostname): corpus cannot shrink further; no proposal")+        return nil+    }++    private nonisolated static func describe(_ proposal: RuleProposal) -> String {+        """+        workName="\(proposal.workName)" chapterText="\(proposal.chapterText)" \+        urlWorkIdentity="\(proposal.urlWorkIdentity)" urlSequenceText="\(proposal.urlSequenceText)"+        """+    }++    /// The three sets Req 3.4 tries, in order. The raw values are what the log+    /// carries, which is the only reason they are strings.+    private nonisolated enum CandidateSet: String, Sendable {+        case titleAndURL = "title+url"+        case titleOnly = "title-only"+        case urlOnly = "url-only"+    }++    /// Step 6 for one candidate set: the whole-hostname projection the editor's+    /// preview uses, read for the three things Req 3.4 names.+    private func verifies(+        hostname: String, candidateSet: CandidateSet, basis: ComposedTeachingBasis,+        request: ComposedTeachingRequest+    ) async throws -> Bool {+        // The timeout wrapper's check point between projections.+        try Task.checkCancellation()+        let outcome: ComposedTeachingOutcome+        do {+            outcome = try await library+                .projectComposedTeaching(hostname: hostname, request: request).outcome+        } catch {+            if error is CancellationError { throw error }+            RuleSuggestionLog.failure(+                "\(hostname): \(candidateSet.rawValue) projection failed — \(RuleSuggestionLog.describe(error))")+            return false+        }+        guard !outcome.requiresUnsettledAcknowledgment else {+            RuleSuggestionLog.note(+                "\(hostname): \(candidateSet.rawValue) rejected — chapters left unsettled")+            return false+        }+        for entry in outcome.entries {+            guard entry.titleFailure == nil, entry.urlFailure == nil,+                  let workName = entry.workName, !workName.isEmpty else {+                RuleSuggestionLog.note(+                    "\(hostname): \(candidateSet.rawValue) rejected — \(Self.failure(of: entry))",+                    content: "title=\"\(Self.captureTitle(of: entry, in: basis))\"")+                return false+            }+        }+        return true+    }++    /// Why one projected entry disqualified a candidate set. Req 3.4 names the+    /// three, and the first one that holds is the one reported.+    private nonisolated static func failure(of entry: ComposedEntryProjection) -> String {+        if let titleFailure = entry.titleFailure {+            return "titleFailure \(String(describing: titleFailure))"+        }+        if let urlFailure = entry.urlFailure {+            return "urlFailure \(String(describing: urlFailure))"+        }+        return "empty workName"+    }++    /// The projection carries no capture title, so the failing entry is named+    /// by looking its id back up in the basis it was projected from.+    private nonisolated static func captureTitle(+        of entry: ComposedEntryProjection, in basis: ComposedTeachingBasis+    ) -> String {+        basis.entries.first { $0.id == entry.entryID }?.captureTitle ?? "<entry not in basis>"+    }++    // MARK: - Helpers++    /// One URL field, located in exactly one component of the anchor URL.+    private nonisolated struct LocatedURLSpan: Sendable {+        let selection: ComposedTeachingPresentation.URLComponentSelection+        /// Component-relative, never a span over the raw URL.+        let range: Range<Int>+    }++    /// Every path component's text and every query value, searched for one+    /// field. Accepted only on exactly one occurrence across all of them: a+    /// slug that repeats has no single span, and text the model copied out of+    /// the host or the scheme is found in none (Req 3.1).+    private nonisolated static func locate(+        _ text: String, in components: RawURLLexicalComponents+    ) -> LocatedURLSpan? {+        guard !text.isEmpty else { return nil }+        var candidates: [(ComposedTeachingPresentation.URLComponentSelection, String)] = []+        for (index, component) in components.pathComponents.enumerated() {+            candidates.append((.path(index), component.value))+        }+        for (index, item) in components.queryItems.enumerated() {+            candidates.append((.query(index), item.value.value))+        }++        var found: LocatedURLSpan?+        for (selection, source) in candidates {+            switch ProposalLocator.place(text, in: source) {+            case .absent:+                continue+            case .unique(let range):+                // A second component that also holds it once is as ambiguous as+                // two occurrences in one, and is not resolved in either's favour.+                guard found == nil else { return nil }+                found = LocatedURLSpan(selection: selection, range: range)+            case .ambiguous:+                // Ambiguous within one component; the whole field is dropped+                // rather than resolved in favour of another component.+                return nil+            }+        }+        return found+    }++    private nonisolated static func request(+        title: TitleRuleSuggestion, url: URLRuleDefinition?+    ) -> ComposedTeachingRequest {+        ComposedTeachingRequest(+            titleDefinition: title.definition, trimPrefix: title.trimPrefix,+            trimSuffix: title.trimSuffix, urlDefinition: url,+            acknowledgeUnsettled: false, permitsArticlesConversion: false)+    }++    /// Req 3.4 / Q48: a single-side set fills the other slot with what the Site+    /// already holds, because that is the state the reader would save.+    private nonisolated static func storedTitle(_ basis: ComposedTeachingBasis) -> TitleRuleSuggestion {+        guard let stored = basis.currentTitleRule else {+            return TitleRuleSuggestion(definition: .wholeTitle)+        }+        return TitleRuleSuggestion(+            definition: stored.definition,+            trimPrefix: stored.trimPrefix, trimSuffix: stored.trimSuffix)+    }++    private nonisolated static func isUntaughtDefault(_ title: TitleRuleSuggestion) -> Bool {+        guard case .wholeTitle = title.definition else { return false }+        return (title.trimPrefix ?? "").isEmpty && (title.trimSuffix ?? "").isEmpty+    }+}

diff --git a/Asterism/Asterism/RuleSuggestion/RuleSuggestionAssembler.swift b/Asterism/Asterism/RuleSuggestion/RuleSuggestionAssembler.swiftnew file mode 100644index 0000000..3adc0ed--- /dev/null+++ b/Asterism/Asterism/RuleSuggestion/RuleSuggestionAssembler.swift@@ -0,0 +1,94 @@+import AsterismCore+import AsterismIntelligence+import Foundation++/// Step 5 of the attempt pipeline: turn located spans into the rules the editor+/// would have authored from the same selection.+///+/// Nothing here derives a rule of its own. The title path drives+/// `ComposedTeachingPresentation`'s chip inference and the URL path drives a+/// headless `URLEditorState`, because a suggestion that took a different route+/// could produce a rule the editor cannot depict — which is exactly what+/// Req 3.5 forbids (Q36). A refusal on either path is `nil`, not an error: the+/// spans came from a model, and "the editor would not author that" is an+/// ordinary answer.+///+/// `nonisolated`, and pure: this runs on the `RuleSuggester` actor, off the+/// main actor (Req 5.1).+nonisolated enum RuleSuggestionAssembler {++    /// The title rule a Work span and an optional chapter span author on the+    /// anchor capture's title, or nil when they author none.+    ///+    /// The default whole-title rule *is* returned here; whether it is worth+    /// showing on its own is the suggester's call (design step 5).+    static func titleRule(+        anchorTitle: String, workSpan: Range<Int>, chapterSpan: Range<Int>?+    ) -> TitleRuleSuggestion? {+        let count = anchorTitle.count+        guard !workSpan.isEmpty, workSpan.lowerBound >= 0, workSpan.upperBound <= count else {+            return nil+        }+        if let chapterSpan {+            guard !chapterSpan.isEmpty, chapterSpan.lowerBound >= 0,+                  chapterSpan.upperBound <= count, !chapterSpan.overlaps(workSpan)+            else { return nil }+        }++        let segments = ComposedTeachingPresentation.titleSegments(in: anchorTitle)+        let selection = ComposedTeachingPresentation.titleSelection(+            in: anchorTitle, workSpan: workSpan, chapterSpan: chapterSpan)+        let chips = ComposedTeachingPresentation.titleChips(+            segments: segments, subdividing: selection.subdivided)+        guard chips.count == selection.roles.count, selection.roles.contains(.work),+              let inferred = ComposedTeachingPresentation.inferredTitleRule(+                title: anchorTitle, segments: segments, chips: chips, roles: selection.roles)+        else { return nil }+        // A chapter span the chip row could not express drops silently out of+        // `titleSelection`; a rule that names no chapter when one was proposed+        // is still a legal rule, and Req 3.4's projection is what decides+        // whether it is worth showing.+        return TitleRuleSuggestion(+            definition: inferred.definition,+            trimPrefix: inferred.trimPrefix, trimSuffix: inferred.trimSuffix)+    }++    /// The URL rule an identity selection and an optional sequence selection+    /// author on the anchor capture's URL, or nil when they author none.+    ///+    /// The spans are component-relative and are used **only** for a+    /// within-component split: a slot that takes a whole component takes it+    /// whole, exactly as a chip tap does.+    static func urlRule(+        components: RawURLLexicalComponents,+        identity: (ComposedTeachingPresentation.URLComponentSelection, Range<Int>),+        sequence: (ComposedTeachingPresentation.URLComponentSelection, Range<Int>)?+    ) -> URLRuleDefinition? {+        var state = ComposedTeachingPresentation.URLEditorState()+        state.activeSlot = .work+        state.select(identity.0)++        if let sequence {+            if sequence.0 == identity.0 {+                // One component carrying both fields is the combined form, and+                // the split is the only way to say where the boundary falls.+                guard identity.1.upperBound <= sequence.1.lowerBound+                        || sequence.1.upperBound <= identity.1.lowerBound+                else { return nil }+                state.setSplit(+                    URLTwoFieldSelection(work: identity.1, sequence: sequence.1))+            } else {+                state.activeSlot = .sequence+                state.select(sequence.0)+                state.activeSlot = .work+            }+        }++        // Only a finished rule is a suggestion. `.pending` (a half-chosen+        // anchoring), `.unauthorable` (a component nothing can single out) and+        // `.cleared` (including a split the deriver refused) all mean the+        // editor authored nothing.+        guard case .valid(let definition) = state.rule(in: components).status else { return nil }+        return definition+    }+}

diff --git a/Asterism/Asterism/RuleSuggestion/RuleSuggestionCoordinator.swift b/Asterism/Asterism/RuleSuggestion/RuleSuggestionCoordinator.swiftnew file mode 100644index 0000000..fad4a13--- /dev/null+++ b/Asterism/Asterism/RuleSuggestion/RuleSuggestionCoordinator.swift@@ -0,0 +1,402 @@+import AsterismCore+import AsterismIntelligence+import Foundation+import UIKit++/// The device conditions Req 5.3 gates the sweep on, plus the clock the+/// coordinator measures a cancelled attempt with.+///+/// A protocol rather than direct `ProcessInfo` reads: Low Power Mode, the+/// thermal state and the app's active state cannot be set from a test, and the+/// gates are most of what the coordinator does.+@MainActor+protocol SuggestionEnvironment {+    var isActive: Bool { get }+    var isLowPowerModeEnabled: Bool { get }+    var thermalState: ProcessInfo.ThermalState { get }+    var now: ContinuousClock.Instant { get }+}++/// The production environment.+@MainActor+struct SystemSuggestionEnvironment: SuggestionEnvironment {+    /// Explicit and `nonisolated` so the coordinator can name it as a default+    /// argument: a default-argument generator is nonisolated, and the implicit+    /// memberwise initializer of a main-actor type is not.+    nonisolated init() {}++    var isActive: Bool { UIApplication.shared.applicationState == .active }+    var isLowPowerModeEnabled: Bool { ProcessInfo.processInfo.isLowPowerModeEnabled }+    var thermalState: ProcessInfo.ThermalState { ProcessInfo.processInfo.thermalState }+    var now: ContinuousClock.Instant { .now }+}++/// Owns everything a suggestion needs that is not the attempt itself: the+/// ledger, the in-flight `Task`, the callers waiting on it, and the library+/// read that produces a hostname's fingerprint.+///+/// `@MainActor` because the view model reads `held`/`isDismissed`+/// synchronously; the attempt runs in a `RuleSuggester` actor, so no model work+/// touches this actor (Q40, Req 5.1).+@MainActor @Observable+final class RuleSuggestionCoordinator {+    /// Req 4.1/6.1: nothing is attempted and the Suggest action is hidden while+    /// the model is away. Re-read on every activation, because `.modelNotReady`+    /// is transient (Q41).+    private(set) var isModelAvailable: Bool++    private let library: any LibraryProviding+    private let model: any RuleSuggestionModelClient+    private let suggester: any RuleSuggesting+    private let environment: any SuggestionEnvironment++    private var ledger = RuleSuggestionLedger()+    /// The attempt is the coordinator's, never the caller's: cancelling whoever+    /// asked must not cancel the work (design, coordinator section).+    private var attemptTask: Task<Void, Never>?+    /// When the current attempt started, so a cancellation — which returns no+    /// `modelPhase` of its own — can still be charged to the budget (Req 5.2).+    private var attemptStartedAt: ContinuousClock.Instant?+    /// Everyone awaiting the in-flight attempt: the caller that started it and+    /// anyone who attached (Q16).+    private var waiters: [CheckedContinuation<RuleSuggestion?, Never>] = []+    /// The sweep currently running, so the next activation can queue behind it+    /// rather than race it. See `activationSweep()`.+    private var sweepTask: Task<Void, Never>?++    init(+        library: any LibraryProviding,+        model: any RuleSuggestionModelClient,+        suggester: any RuleSuggesting,+        environment: any SuggestionEnvironment = SystemSuggestionEnvironment()+    ) {+        self.library = library+        self.model = model+        self.suggester = suggester+        self.environment = environment+        self.isModelAvailable = model.availability().isAvailable+    }++    // MARK: - Reads++    func held(for hostname: String) -> RuleSuggestion? { ledger.held(for: hostname) }++    func isDismissed(hostname: String, side: Side) -> Bool {+        ledger.isDismissed(hostname: hostname, side: side)+    }++    /// Whether an attempt for this hostname has settled this run. Read by the+    /// editor to decide whether an on-open computation is even possible+    /// (Req 5.7), and by the tests.+    func isAttempted(_ hostname: String) -> Bool { ledger.isAttempted(hostname) }++    /// What the run has spent so far (Req 5.2).+    var budgetSpent: Duration { ledger.budgetSpent }++    // MARK: - Dismissal (Reqs 2.7, 2.8, 6.5)++    func dismiss(hostname: String, side: Side) {+        ledger.dismiss(hostname: hostname, side: side)+    }++    func clearDismissal(hostname: String, side: Side) {+        ledger.clearDismissal(hostname: hostname, side: side)+    }++    // MARK: - Activation (Req 5.1)++    /// One sweep per activation: re-read availability, then attempt up to+    /// `backgroundSweepDepth` auto-eligible hostnames, most recent capture+    /// first. Never awaited inline by the caller — the app's activation must+    /// not wait on it.+    ///+    /// Activations queue rather than collide. `resignActive()` stops a sweep+    /// but cannot end it — the coroutine runs until the attempt it is awaiting+    /// returns — so an app that comes straight back finds the previous sweep+    /// still in the loop. Waiting for it and then beginning a fresh one is what+    /// gives every activation the sweep Req 5.1 promises it.+    func activationSweep() async {+        let previous = sweepTask+        let task = Task { [weak self] in+            await previous?.value+            await self?.runSweep()+        }+        sweepTask = task+        await task.value+        if sweepTask == task { sweepTask = nil }+    }++    /// One sweep, from the ledger's point of view. Its generation is the token+    /// the loop asks about and the only one that may end it: a sweep stopped+    /// mid-flight must not switch off the sweep that replaced it.+    private func runSweep() async {+        guard let generation = ledger.beginSweep() else { return }+        defer { ledger.endSweep(generation: generation) }++        let availability = model.availability()+        isModelAvailable = availability.isAvailable+        if case .unavailable(let reason) = availability {+            RuleSuggestionLog.note("sweep skipped — model unavailable: \(reason)")+            return+        }++        // Asked before the read, not after: with the budget spent every+        // candidate would be refused anyway (Q31), and the read is 2N SwiftData+        // fetches to be told so.+        guard !ledger.budgetExhausted else {+            RuleSuggestionLog.note(+                "sweep skipped — run budget spent (\(RuleSuggestionLog.milliseconds(ledger.budgetSpent)) ms)")+            return+        }++        let candidates: [RuleSuggestionCandidate]+        do {+            candidates = try await library.ruleSuggestionCandidates(hostnames: nil)+        } catch {+            // A library that is not ready yet skips this activation in silence+            // (Req 4.2); the next one tries again.+            RuleSuggestionLog.failure(+                "sweep skipped — candidate read failed: \(RuleSuggestionLog.describe(error))")+            return+        }++        let eligible = candidates+            .filter {+                Self.isAutoEligible($0) && !ledger.isAttempted($0.hostname)+                    // Req 2.8: the reader rejected both sides, and `invalidate`+                    // keeps that rejection — so a corpus change must not spend+                    // a sweep slot and up to 10 s of budget re-offering it.+                    && !ledger.isFullyDismissed($0.hostname)+            }+            .sorted(by: Self.byRecency)+            .prefix(RuleSuggestionBounds.backgroundSweepDepth)+        RuleSuggestionLog.note(+            "sweep: \(eligible.count) of \(candidates.count) hostnames eligible")++        for candidate in eligible {+            // A pre-emption or a resign-active ends *this* sweep; the next+            // activation restarts it.+            guard ledger.isSweeping(generation: generation) else { return }+            _ = await suggestion(for: candidate.hostname, origin: .background, candidate: candidate)+        }+    }++    /// Req 5.5's single invalidation hook, called after every library refresh.+    /// The comparison itself is the ledger's (Q57); this only performs the read.+    func reconcile() async {+        let tracked = ledger.trackedHostnames+        guard !tracked.isEmpty else { return }+        let rows: [RuleSuggestionCandidate]+        do {+            rows = try await library.ruleSuggestionCandidates(hostnames: tracked)+        } catch {+            return+        }+        var fingerprints: [String: CorpusFingerprint] = [:]+        for row in rows { fingerprints[row.hostname] = Self.fingerprint(row) }++        let invalidated = ledger.reconcile(against: fingerprints)+        if let inFlight = ledger.inFlight, invalidated.contains(inFlight.hostname) {+            // The record is already voided, so whatever the attempt returns is+            // discarded; cancelling only stops it sooner.+            attemptTask?.cancel()+        }+    }++    /// Req 5.3: the sweep stops with the foreground, and so does its attempt.+    /// On-open and on-request work is the reader's and continues.+    func resignActive() {+        if ledger.resignActive() != nil { attemptTask?.cancel() }+    }++    /// Req 5.6.+    func memoryWarning() {+        if ledger.memoryWarning() != nil { attemptTask?.cancel() }+    }++    // MARK: - Delivery++    /// The single delivery channel for on-open and on-request (and the sweep's+    /// own starts). Nil means the attempt settled with nothing, or the ledger+    /// refused to start one.+    func suggestion(for hostname: String, origin: Origin) async -> RuleSuggestion? {+        await suggestion(for: hostname, origin: origin, candidate: nil)+    }++    private func suggestion(+        for hostname: String, origin: Origin, candidate: RuleSuggestionCandidate?+    ) async -> RuleSuggestion? {+        // Req 6.6: a held result is the answer, with no model call.+        if let held = ledger.held(for: hostname) { return held }+        guard isModelAvailable else {+            RuleSuggestionLog.note("\(hostname): \(origin.rawValue) refused — model unavailable")+            return nil+        }+        // Ask the ledger before paying for a candidate row: an editor open on a+        // hostname already attempted, dismissed on both sides, or standing+        // behind the reader's own request is refused on state already in hand,+        // and the read it would otherwise make is 2N fetches per open.+        if origin == .open, let reason = ledger.openRefusal(hostname: hostname) {+            RuleSuggestionLog.note("\(hostname): open refused — \(reason)")+            return nil+        }++        // The fingerprint an attempt is recorded against has to come from the+        // library, so a start needs a candidate row. The sweep has one already.+        var row = candidate+        if row == nil {+            row = try? await library.ruleSuggestionCandidates(hostnames: [hostname]).first+        }+        guard let row else {+            RuleSuggestionLog.note(+                "\(hostname): \(origin.rawValue) refused — the library returned no candidate row")+            return nil+        }+        let fingerprint = Self.fingerprint(row)++        while true {+            // Re-read each time round: `cancelInFlight()` below awaits another+            // attempt's termination, and a settlement during that suspension+            // may have held a suggestion for this hostname (Req 6.6).+            if let held = ledger.held(for: hostname) { return held }+            switch ledger.start(+                hostname: hostname, origin: origin, fingerprint: fingerprint,+                environment: currentEnvironment+            ) {+            case .refuse(let reason):+                RuleSuggestionLog.note("\(hostname): \(origin.rawValue) refused — \(reason)")+                return nil+            case .attach:+                RuleSuggestionLog.note(+                    "\(hostname): \(origin.rawValue) attached to the attempt already in flight")+                return await awaitAttempt()+            case .preempt(let preempted):+                // Q54's two-step protocol: the ledger will not swap the record+                // itself, so the running attempt is cancelled and awaited — it+                // settles itself on the way out — and only then asked again.+                RuleSuggestionLog.note(+                    "\(hostname): \(origin.rawValue) pre-empts the attempt for \(preempted)")+                await cancelInFlight()+            case .start:+                RuleSuggestionLog.note("\(hostname): attempt start (\(origin.rawValue))")+                beginAttempt(hostname: hostname)+                return await awaitAttempt()+            }+        }+    }++    // MARK: - The attempt Task++    private func beginAttempt(hostname: String) {+        attemptStartedAt = environment.now+        attemptTask = Task { [weak self] in+            guard let self else { return }+            do {+                let result = try await self.suggester.attempt(hostname: hostname)+                self.settle(+                    hostname: hostname,+                    settlement: result.suggestion.map { .suggestion($0) } ?? .noSuggestion,+                    modelPhase: result.modelPhase)+            } catch let timeout as AttemptTimeout {+                // Attempted, and charged what it spent (Q45, Req 5.4).+                self.settle(hostname: hostname, settlement: .timedOut,+                            modelPhase: timeout.modelPhase)+            } catch {+                // The app's own cancellation: unattempted, still charged (Q28).+                self.settle(hostname: hostname, settlement: .cancelled,+                            modelPhase: self.elapsedSinceStart())+            }+        }+    }++    /// Only ever reached from the attempt's own `Task`, which is the only thing+    /// that can end an attempt — so clearing the handles here cannot strand a+    /// newer one: a new attempt starts only after this one has terminated.+    private func settle(+        hostname: String, settlement: AttemptSettlement, modelPhase: Duration+    ) {+        RuleSuggestionLog.note(+            "\(hostname): settled \(Self.describe(settlement)) after \(RuleSuggestionLog.milliseconds(modelPhase)) ms")+        ledger.settle(hostname: hostname, settlement, modelPhase: modelPhase)+        attemptTask = nil+        attemptStartedAt = nil++        let result = ledger.held(for: hostname)+        let resuming = waiters+        waiters = []+        for continuation in resuming { continuation.resume(returning: result) }+    }++    private func awaitAttempt() async -> RuleSuggestion? {+        // Deliberately not cancellation-aware: the caller may go away, the+        // attempt may not.+        await withCheckedContinuation { continuation in+            waiters.append(continuation)+        }+    }++    /// Req 5.11: the next attempt may not start until this one has stopped.+    private func cancelInFlight() async {+        guard let task = attemptTask else { return }+        task.cancel()+        await task.value+    }++    private func elapsedSinceStart() -> Duration {+        guard let attemptStartedAt else { return .zero }+        return attemptStartedAt.duration(to: environment.now)+    }++    private var currentEnvironment: RuleSuggestionEnvironment {+        RuleSuggestionEnvironment(+            isActive: environment.isActive,+            isLowPowerMode: environment.isLowPowerModeEnabled,+            thermalState: environment.thermalState)+    }++    // MARK: - Candidate rows++    /// The definition in the requirements: not articles, at least one capture,+    /// and a rule missing on one side.+    private static func isAutoEligible(_ candidate: RuleSuggestionCandidate) -> Bool {+        candidate.siteMode != .articles && candidate.entryCount > 0+            && (candidate.titleRuleVersion == nil || candidate.urlRuleVersion == nil)+    }++    /// Most recent capture first; a hostname with no captures is never eligible,+    /// so the nil arm only has to be total. Hostname breaks ties so a sweep is+    /// reproducible.+    private static func byRecency(+        _ left: RuleSuggestionCandidate, _ right: RuleSuggestionCandidate+    ) -> Bool {+        switch (left.latestCaptureAt, right.latestCaptureAt) {+        case (let l?, let r?) where l != r: return l > r+        case (nil, _?): return false+        case (_?, nil): return true+        default: return left.hostname < right.hostname+        }+    }++    /// How the attempt ended, for the log: which sides a suggestion carried,+    /// or which of the three endings that hold nothing this was.+    private static func describe(_ settlement: AttemptSettlement) -> String {+        switch settlement {+        case .suggestion(let suggestion):+            let sides = [+                suggestion.title == nil ? nil : "title", suggestion.url == nil ? nil : "url",+            ].compactMap { $0 }+            return sides.isEmpty ? "a suggestion with no sides" : "suggestion (\(sides.joined(separator: "+")))"+        case .noSuggestion: return "no suggestion"+        case .timedOut: return "timed out"+        case .cancelled: return "cancelled"+        }+    }++    private static func fingerprint(_ candidate: RuleSuggestionCandidate) -> CorpusFingerprint {+        CorpusFingerprint(+            siteMode: candidate.siteMode, entryCount: candidate.entryCount,+            latestCaptureAt: candidate.latestCaptureAt,+            titleRuleVersion: candidate.titleRuleVersion,+            urlRuleVersion: candidate.urlRuleVersion)+    }+}

diff --git a/Asterism/Asterism/RuleSuggestion/RuleSuggestionLog.swift b/Asterism/Asterism/RuleSuggestion/RuleSuggestionLog.swiftnew file mode 100644index 0000000..b9577e8--- /dev/null+++ b/Asterism/Asterism/RuleSuggestion/RuleSuggestionLog.swift@@ -0,0 +1,79 @@+import AsterismIntelligence+import Foundation+import OSLog++/// The rule-suggestion pipeline's diagnostic log.+///+/// Every failure in this pipeline settles the attempt with `nil` and tells the+/// reader nothing (Req 4.2), so a hostname that produces no suggestion is+/// otherwise indistinguishable from one the model was never asked about. These+/// lines are the only place the reason survives.+///+/// Follow one run in Console.app with+/// `subsystem:me.nore.ig.Asterism category:RuleSuggestion`, or after the fact+/// with+/// `log show --predicate 'subsystem == "me.nore.ig.Asterism" AND category == "RuleSuggestion"' --last 10m`.+///+/// `nonisolated` because the suggester runs on its own actor, off the main one+/// (Req 5.1), and every static under this target's default isolation would+/// otherwise be main-actor bound.+nonisolated enum RuleSuggestionLog {+    static let logger = Logger(subsystem: "me.nore.ig.Asterism", category: "RuleSuggestion")++    /// `reason` — hostname, step, origin, error type, count, duration — is+    /// always readable. `content` — capture titles, URLs, the text the model+    /// copied out of them — is readable only in a debug build; a release build+    /// leaves it to the logging system to redact.+    ///+    /// The `#if` has to wrap the whole call rather than a constant: `privacy:`+    /// accepts nothing but a literal member of `OSLogPrivacy` — not a variable,+    /// and not a static of our own ("argument must be a static method or+    /// property of 'OSLogPrivacy'").+    ///+    /// Both arguments are autoclosures and neither is evaluated until the level+    /// is known to be enabled. Every call site here interpolates — a proposal's+    /// four fields, a capture title looked back up in the basis, an error+    /// stringified — and `Logger`'s own laziness cannot help with that, because+    /// the interpolation happens at the call site, before the message is ever+    /// handed over.+    static func note(+        _ reason: @autoclosure () -> String,+        content: @autoclosure () -> String? = nil,+        level: OSLogType = .default+    ) {+        guard logger.isEnabled(type: level) else { return }+        // Both are bound to locals first: `OSLogMessage`'s interpolation is an+        // *escaping* autoclosure, and a non-escaping parameter cannot be+        // captured by one.+        let reason = reason()+        guard let content = content() else {+            logger.log(level: level, "\(reason, privacy: .public)")+            return+        }+        #if DEBUG+        logger.log(level: level, "\(reason, privacy: .public) | \(content, privacy: .public)")+        #else+        logger.log(level: level, "\(reason, privacy: .public) | \(content, privacy: .private)")+        #endif+    }++    /// A step that failed with an error rather than an answer.+    static func failure(+        _ reason: @autoclosure () -> String, content: @autoclosure () -> String? = nil+    ) {+        note(reason(), content: content(), level: .error)+    }++    /// The one spelling of a failure this pipeline's logs use, shared with the+    /// package so a model client's default `describe(_:)` reads the same.+    static func describe(_ error: any Error) -> String {+        SuggestionFailure.describe(error)+    }++    /// Durations read better in the log as a plain millisecond count than as+    /// `Duration`'s "0.123 seconds".+    static func milliseconds(_ duration: Duration) -> Int64 {+        let components = duration.components+        return components.seconds * 1000 + components.attoseconds / 1_000_000_000_000_000+    }+}

diff --git a/Asterism/Asterism/UITestLaunchSupport.swift b/Asterism/Asterism/UITestLaunchSupport.swiftindex 47c278b..f859624 100644--- a/Asterism/Asterism/UITestLaunchSupport.swift+++ b/Asterism/Asterism/UITestLaunchSupport.swift@@ -1,4 +1,5 @@ import AsterismCore+import AsterismIntelligence import Foundation  /// Injectable process-environment boundary used by the debug UI-test launcher.@@ -93,6 +94,41 @@ enum UITestLaunchSupport {     /// second table.     static let seededToleratedPrefix = "seeded-tolerated-" +    /// `rule-suggestion`: which scripted model client this launch runs with.+    /// Absent means the on-device model, which is what production always uses.+    static let suggestionKey = "ASTERISM_UI_TEST_SUGGESTION"+    /// A proposal that verifies on the `seeded-composed` fixture's untaught+    /// capture — `TtH - Story - Real Title` at+    /// `https://composed.test/Story-28614-94/slug.htm`. The last title segment+    /// names the Work and the first is the chapter; the URL's first path+    /// component identifies the Work.+    static let cannedSuggestionProposal = RuleProposal(+        workName: "Real Title", chapterText: "TtH",+        urlWorkIdentity: "Story-28614-94", urlSequenceText: "")++    /// The model client this launch's suggestions run against, or nil when the+    /// launch asked for nothing (every production launch, and every UI test but+    /// the two `rule-suggestion` scenarios).+    ///+    /// Gated because `StubRuleSuggestionModelClient` is: the scripted client is+    /// a test double and carries the package's fixture gate, so a shipping+    /// build has neither it nor this.+    #if DEBUG || ASTERISM_PERFORMANCE_TESTING+    static func suggestionClient(+        environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment()+    ) -> (any RuleSuggestionModelClient)? {+        switch environmentProvider.environment[suggestionKey] {+        case "canned":+            return StubRuleSuggestionModelClient(proposal: cannedSuggestionProposal)+        case "unavailable":+            return StubRuleSuggestionModelClient(+                availability: .unavailable(reason: "UI test"))+        default:+            return nil+        }+    }+    #endif+     static func request(         environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment(),         temporaryDirectory: URL = FileManager.default.temporaryDirectory

diff --git a/Asterism/Asterism/ViewModels/AppLibraryModel.swift b/Asterism/Asterism/ViewModels/AppLibraryModel.swiftindex ad1bb83..3da6b15 100644--- a/Asterism/Asterism/ViewModels/AppLibraryModel.swift+++ b/Asterism/Asterism/ViewModels/AppLibraryModel.swift@@ -1,4 +1,5 @@ import AsterismCore+import AsterismIntelligence import Foundation import OSLog @@ -131,6 +132,11 @@ public final class AppLibraryModel {     /// Cleared after seeding so a later in-process bootstrap cannot seed twice.     private var uiTestFixture: UITestFixtureKind? +    /// The run's rule suggestions (`rule-suggestion`). Built at bootstrap over+    /// the repository that opened, so it is nil until the library is ready and+    /// in the test seams that publish a repository without one.+    private(set) var suggestions: RuleSuggestionCoordinator?+     /// Production initializer: resolves the configuration from the App Group     /// identifier its bundle declares. Fails closed (→ unavailable) when App     /// Group resolution fails.@@ -291,6 +297,10 @@ public final class AppLibraryModel {             }             self.repository = repo             self.backupRepository = repo+            // `rule-suggestion`: the run's suggestion state, built over the+            // repository that just opened. Nothing is attempted until an+            // activation sweeps or an editor opens.+            self.suggestions = Self.makeSuggestionCoordinator(library: repo)             interruptedImport = await repo.interruptedImport()             // Before `refreshAll()`, so a capture this pass commits is in the             // first snapshots rather than waiting for the next activation, and@@ -380,6 +390,25 @@ public final class AppLibraryModel {         // the larger budget — nothing is waiting on it but the refresh (Q40).         await drainPendingCaptures(budget: PendingCaptureBounds.drainPassTimeBudget)         await refreshDiagnosesAndSnapshots()+        // `rule-suggestion` Req 5.1: never awaited inline — the activation must+        // not wait on model work, and the sweep may outlive this call.+        if let suggestions {+            Task { await suggestions.activationSweep() }+        }+    }++    /// The model client the run's suggestions are computed with. A UI test may+    /// substitute a scripted one; production always asks the on-device model.+    private static func makeSuggestionCoordinator(+        library: any LibraryProviding+    ) -> RuleSuggestionCoordinator {+        var client: any RuleSuggestionModelClient = FoundationRuleSuggestionModelClient()+        #if DEBUG || ASTERISM_PERFORMANCE_TESTING+        if let scripted = UITestLaunchSupport.suggestionClient() { client = scripted }+        #endif+        return RuleSuggestionCoordinator(+            library: library, model: client,+            suggester: RuleSuggester(library: library, model: client))     }      // MARK: - Preserved captures (pending-capture-queue)@@ -571,6 +600,9 @@ public final class AppLibraryModel {     private func refreshDiagnosesAndSnapshots() async {         await refreshDiagnoses()         await refreshAll()+        // `rule-suggestion` Req 5.5's single invalidation hook: every library+        // mutation the app performs funnels through here (Q43).+        await suggestions?.reconcile()         dropSettledConflicts()     } @@ -769,7 +801,8 @@ public final class AppLibraryModel {             entryContext: context,             onMutation: { [weak self] in                 await self?.refreshDiagnosesAndSnapshots()-            }+            },+            suggestions: suggestions         )     } @@ -806,7 +839,8 @@ public final class AppLibraryModel {             permitsArticlesConversion: permitsArticlesConversion,             onMutation: { [weak self] in                 await self?.refreshDiagnosesAndSnapshots()-            }+            },+            suggestions: suggestions         )     } 

diff --git a/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift b/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swiftindex fc80a1e..71fd06b 100644--- a/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift+++ b/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift@@ -1,4 +1,5 @@ import AsterismCore+import AsterismIntelligence import Foundation import OSLog @@ -65,6 +66,30 @@ public final class ComposedTeachingViewModel {         case urlFocused     } +    /// Why a suggestion is being applied. The automatic path (editor open, late+    /// arrival) only touches sides the reader has neither taught nor changed nor+    /// dismissed; the reader's own request applies to any side (Reqs 1.1, 6.2).+    public enum SuggestionApplication: Equatable, Sendable {+        case automatic+        case request+    }++    /// One side's editor state as it stood before a suggestion was applied, so+    /// the clear action can put it back exactly (Req 2.3, Q42).+    private struct TitleSuggestionSnapshot {+        var subdividedSegments: Set<Int>+        var chips: [ComposedTeachingPresentation.TitleChip]+        var roles: [SegmentRole]+        var edited: Bool+        var storedNotice: String?+    }++    private struct URLSuggestionSnapshot {+        var definition: URLRuleDefinition?+        var status: ComposedTeachingPresentation.URLRuleStatus+        var disclosure: DisclosureState+    }+     // MARK: - Published state      public private(set) var state: State = .loading@@ -125,6 +150,36 @@ public final class ComposedTeachingViewModel {     // Acknowledgment (Req 2.1, Q3)     public private(set) var acknowledgedUnsettled: Bool = false +    // Rule suggestion (rule-suggestion Reqs 1, 2, 6)+    /// Whether a suggested rule is applied and unedited on that side — the+    /// marker's only condition (Req 2.1).+    ///+    /// Derived rather than tracked: the applied payload below is the marker's+    /// only evidence, and the two were only ever written together.+    public var titleSuggestionApplied: Bool { appliedTitleSuggestion != nil }+    public var urlSuggestionApplied: Bool { appliedURLSuggestion != nil }+    /// True while any computation for this hostname is being awaited, on open or+    /// on request (Req 6.3).+    public private(set) var suggestionBusy = false+    /// A suggestion exists for this hostname that the automatic path did not+    /// apply — late, touched, or dismissed (Reqs 5.9, Q68).+    ///+    /// Read from the state rather than latched. The coordinator holds the+    /// suggestion before it resumes anyone waiting on the attempt, so every+    /// side of it is knowable here: what is offered, what took, and what the+    /// reader has since rejected. A flag set on delivery and cleared on request+    /// could say none of that after a `clearSuggestedSide`.+    public var suggestionReady: Bool {+        guard let suggestions, let held = suggestions.held(for: hostname) else { return false }+        return Side.allCases.contains { side in+            Self.offers(held, side) && !isSuggestionApplied(side)+                && !suggestions.isDismissed(hostname: hostname, side: side)+        }+    }+    /// Req 6.4's message, and the only thing about suggestions the reader is+    /// ever told.+    public private(set) var suggestionUnavailableNotice: String?+     // MARK: - Dependencies      private let entry: EntrySnapshot@@ -138,6 +193,9 @@ public final class ComposedTeachingViewModel {     /// from converting one by accident.     private let permitsArticlesConversion: Bool     private let onMutation: (@Sendable () async -> Void)?+    /// The run's suggestion state. Nil wherever suggestions are not wired —+    /// previews, and every test that does not exercise them.+    private let suggestions: RuleSuggestionCoordinator?      private var contract: ComposedTeachingContract?     private var previewTask: Task<Void, Never>?@@ -154,6 +212,30 @@ public final class ComposedTeachingViewModel {     /// so a reader who collapses it again is not fought by the same trigger.     private var didAutoExpandForChapter = false +    /// When the editor became interactive, which is what Req 5.8's auto-apply+    /// window is measured from.+    private var appearedAt: ContinuousClock.Instant?+    /// The URL side's "changed": any outcome the URL editor dispatched after+    /// load (the title side uses `titleEdited`). Reqs 5.8, 5.9.+    private var urlTouched = false+    /// Req 5.8's window.+    ///+    /// **Test seam.** Production never assigns this: `RuleSuggestionBounds` is+    /// the one home for the bound (Q11/Q22). It is settable so the late-arrival+    /// path can be driven with a zero window instead of waiting out the real two+    /// seconds.+    var suggestionAutoApplyWindow: Duration = RuleSuggestionBounds.autoApplyWindow+    private var titleSuggestionSnapshot: TitleSuggestionSnapshot?+    private var urlSuggestionSnapshot: URLSuggestionSnapshot?+    /// What is currently applied per side, so an incoming edit can be compared+    /// against it and a commit can tell "saved the suggestion" from "saved+    /// something else" (Reqs 2.6, 2.7).+    private var appliedTitleSuggestion: TitleRuleSuggestion?+    private var appliedURLSuggestion: URLRuleDefinition?+    /// The on-open delivery. Cancelled with the editor; the attempt behind it is+    /// the coordinator's and continues (Req 5.7).+    private var suggestionTask: Task<Void, Never>?+     /// Articles mode is a one-way Site transition, not a composed title rule, so     /// it keeps its own contract and commits through `commitArticles` rather than     /// `commitComposedTeaching` (which requires an active title rule).@@ -174,9 +256,11 @@ public final class ComposedTeachingViewModel {     public var isSubdivided: Bool { !subdividedSegments.isEmpty }      /// The rule the surface would commit right now: the Site's retained rule-    /// until the reader edits the title, then the rule inferred from the chips.+    /// until the reader edits the title — or a suggestion is applied over it,+    /// which Req 6.2 says the commit must store rather than the retained rule+    /// (Q33) — then the rule inferred from the chips.     public var effectiveTitleRule: ComposedTeachingPresentation.InferredTitleRule? {-        if !titleEdited, let retained = retainedTitleRule {+        if !titleEdited, !titleSuggestionApplied, let retained = retainedTitleRule {             return ComposedTeachingPresentation.InferredTitleRule(                 definition: retained.definition,                 trimPrefix: retained.trimPrefix, trimSuffix: retained.trimSuffix)@@ -570,13 +654,18 @@ public final class ComposedTeachingViewModel {      // MARK: - Init -    public init(+    /// Internal, unlike the other view models' initializers: `suggestions` names+    /// an app-internal type, and nothing outside this module constructs the+    /// model — the unit tests reach it through `@testable`. Making it `public`+    /// would only force `RuleSuggestionCoordinator` public with it.+    init(         entry: EntrySnapshot,         library: any LibraryProviding,         capabilities: AsterismCapabilities = .m4,         entryContext: EntryContext = .titleFocused,         permitsArticlesConversion: Bool = false,-        onMutation: (@Sendable () async -> Void)? = nil+        onMutation: (@Sendable () async -> Void)? = nil,+        suggestions: RuleSuggestionCoordinator? = nil     ) {         self.entry = entry         self.library = library@@ -584,6 +673,7 @@ public final class ComposedTeachingViewModel {         self.entryContext = entryContext         self.permitsArticlesConversion = permitsArticlesConversion         self.onMutation = onMutation+        self.suggestions = suggestions     }      // MARK: - Lifecycle@@ -619,8 +709,12 @@ public final class ComposedTeachingViewModel {             contract = nil             previewOutcome = nil             state = .ready+            // The editor is interactive from here, which is what Req 5.8's+            // auto-apply window is measured from.+            appearedAt = .now             syncChapterRemedyDisclosure()             await generatePreviewIfValid()+            await seedSuggestionIfAvailable()         } catch {             errorMessage = "Unable to load teaching basis. \(error.localizedDescription)"             state = .error@@ -809,6 +903,14 @@ public final class ComposedTeachingViewModel {     /// invalidate, then re-sync the chapter-remedy disclosure, then preview. The     /// preview itself declines to run on an unsettled status.     public func updateURLRule(_ outcome: ComposedTeachingPresentation.URLRuleOutcome) {+        // Q47: this is the URL side's edit detection. `beginGesture` cannot be:+        // it is private and runs on the re-seed the suggestion itself triggers,+        // which would dismiss the suggestion the instant it applied. An outcome+        // equal to what is applied is the editor echoing its own seed.+        if urlSuggestionApplied, !isAppliedURLSuggestion(outcome.definition) {+            retireSuggestion(.url, restoringSnapshot: false)+        }+        urlTouched = true         urlRuleStatus = outcome.status         urlRuleDefinition = outcome.definition         invalidatePreview()@@ -833,6 +935,291 @@ public final class ComposedTeachingViewModel {                 status: definition.map { .valid($0) } ?? .cleared))     } +    // MARK: - Rule suggestion (rule-suggestion Reqs 1, 2, 5.7–5.9, 6)++    /// Req 6.4's wording, in the same register as the editor's other notices.+    public static let noSuggestionNotice = "No suggestion available for this site."++    /// Req 6.1: the action exists only while the model is there and the Site is+    /// something a rule can be taught for.+    public var offersSuggestAction: Bool {+        suggestions?.isModelAvailable == true && frozenBasis?.siteMode != .articles+    }++    /// Req 6: ask for a suggestion now. A held one is applied without a model+    /// call; anything else waits on the coordinator's attempt.+    public func requestSuggestion() async {+        guard let suggestions, offersSuggestAction, !suggestionBusy else { return }+        suggestionUnavailableNotice = nil+        suggestionBusy = true+        let result = await suggestions.suggestion(for: hostname, origin: .request)+        // The editor may have been dismissed while the attempt ran: `cancel()`+        // is the only thing that sets `.cancelled`, and applying here would+        // overwrite it with a fresh preview for a surface that is gone.+        guard state != .cancelled else { return }+        suggestionBusy = false+        guard let result, !result.isEmpty else {+            suggestionUnavailableNotice = Self.noSuggestionNotice+            return+        }+        // A suggestion this capture cannot depict leaves both sides unchanged+        // (Req 1.4 on request), which the reader must not read as "applied".+        if await applySuggestion(result, origin: .request).isEmpty {+            suggestionUnavailableNotice = Self.noSuggestionNotice+        }+    }++    /// Req 2.3: return one side to the state it had before the suggestion —+    /// its untaught initial state, or the retained rule on a taught side (Q42).+    public func clearSuggestedSide(_ side: Side) {+        guard isSuggestionApplied(side) else { return }+        retireSuggestion(side, restoringSnapshot: true)+        invalidatePreview()+        syncChapterRemedyDisclosure()+        Task { await generatePreviewIfValid() }+    }++    /// Applies whichever sides the origin allows, and returns the ones that took.+    @discardableResult+    public func applySuggestion(+        _ suggestion: RuleSuggestion, origin: SuggestionApplication+    ) async -> Set<Side> {+        var applied: Set<Side> = []+        if let title = suggestion.title, accepts(.title, origin: origin),+           applyTitleSuggestion(title) {+            applied.insert(.title)+        }+        if let url = suggestion.url, accepts(.url, origin: origin), applyURLSuggestion(url) {+            applied.insert(.url)+        }+        guard !applied.isEmpty else { return applied }+        if origin == .request {+            // Req 6.5: applying to a dismissed side clears its dismissal.+            for side in applied { suggestions?.clearDismissal(hostname: hostname, side: side) }+            suggestionUnavailableNotice = nil+        }+        // Req 1.5: the preview shows the projected result for the whole+        // hostname exactly as it does for a hand-authored selection.+        invalidatePreview()+        syncChapterRemedyDisclosure()+        await generatePreviewIfValid()+        return applied+    }++    /// Req 1: apply what is held, or — on an auto-eligible hostname nothing has+    /// been attempted for — start the computation this open needs (Req 5.7).+    private func seedSuggestionIfAvailable() async {+        guard let suggestions, suggestions.isModelAvailable else { return }+        if let held = suggestions.held(for: hostname) {+            await applySuggestion(held, origin: .automatic)+            // Req 5.7 keys on "no held suggestion for **any of its untaught+            // sides**": a hold that only covers a side this hostname has already+            // been taught leaves the untaught side with nothing, so the open+            // still asks for a computation. The coordinator refuses it while the+            // hold's own attempt still counts as this run's attempt, which is+            // every case today; the check is here so the requirement holds+            // wherever a hold outlives its attempt.+            if coversAnUntaughtSide(held) { return }+        }+        guard isAutoEligibleForSuggestion, !suggestions.isAttempted(hostname) else { return }+        suggestionBusy = true+        let host = hostname+        suggestionTask = Task { [weak self] in+            let result = await suggestions.suggestion(for: host, origin: .open)+            guard let self, !Task.isCancelled else { return }+            // Req 6.3: the action stays busy until the delivery has finished+            // applying, so the reader cannot tap Suggest into a half-applied+            // side. `cancel()` clears the flag on the path that returns early.+            defer { self.suggestionBusy = false }+            guard let result, !result.isEmpty else { return }+            await self.deliverOnOpenSuggestion(result)+        }+    }++    /// Whether a held suggestion offers anything for a side this hostname has no+    /// stored rule for — Req 5.7's "held suggestion for any of its untaught+    /// sides".+    private func coversAnUntaughtSide(_ suggestion: RuleSuggestion) -> Bool {+        guard let basis = frozenBasis else { return true }+        if suggestion.title != nil, basis.currentTitleRule == nil { return true }+        if suggestion.url != nil, basis.currentURLRule == nil { return true }+        return false+    }++    /// Reqs 5.8/5.9: within the window the untouched sides are applied; past it+    /// the result is held and only the on-request action says so — which+    /// `suggestionReady` reads off the hold, so there is nothing to record here.+    private func deliverOnOpenSuggestion(_ suggestion: RuleSuggestion) async {+        let inWindow = appearedAt+            .map { $0.duration(to: .now) <= suggestionAutoApplyWindow } ?? false+        guard inWindow else { return }+        await applySuggestion(suggestion, origin: .automatic)+    }++    /// The requirements' auto-eligibility, asked of the basis this editor froze:+    /// not articles, and a rule missing on one side.+    private var isAutoEligibleForSuggestion: Bool {+        guard let basis = frozenBasis else { return false }+        return basis.siteMode != .articles+            && (basis.currentTitleRule == nil || basis.currentURLRule == nil)+    }++    /// Whether one side may take a suggestion from this origin. The automatic+    /// path stays off taught, touched and dismissed sides (Reqs 1.1, 2.8, 5.8);+    /// the reader's request applies to any of them (Req 6.2).+    private func accepts(_ side: Side, origin: SuggestionApplication) -> Bool {+        guard origin == .automatic else { return true }+        if suggestions?.isDismissed(hostname: hostname, side: side) == true { return false }+        switch side {+        case .title: return retainedTitleRule == nil && !titleEdited+        case .url: return frozenBasis?.currentURLRule == nil && !urlTouched+        }+    }++    /// Seeds the title side through the same path a stored rule takes, then+    /// checks Req 3.5: what the chips now author must be the rule that was+    /// verified. Anything else puts the side back as it was and counts as no+    /// suggestion — the cannot-depict outcome of Req 1.4.+    ///+    /// The rollback is to the state the side was in **when this call started**,+    /// not to the pre-suggestion snapshot: on a re-apply over an already applied+    /// suggestion (a second Suggest after the hostname's hold was invalidated+    /// and recomputed) that state is the applied suggestion, and Req 6.2 /+    /// Req 1.4-on-request say a side with no valid suggestion is *left+    /// unchanged*. Restoring the pre-suggestion baseline there would silently+    /// undo a suggestion the reader had accepted, marker and all.+    private func applyTitleSuggestion(_ suggestion: TitleRuleSuggestion) -> Bool {+        let before = TitleSuggestionSnapshot(+            subdividedSegments: subdividedSegments, chips: titleChips, roles: titleRoles,+            edited: titleEdited, storedNotice: storedTitleRuleNotice)+        seedTitleEditor(+            definition: suggestion.definition,+            trimPrefix: suggestion.trimPrefix, trimSuffix: suggestion.trimSuffix)+        guard let authored = selectedTitleRule,+              RuleDefinitionComparator.semanticallyEqual(+                authored.definition, suggestion.definition),+              RuleDefinitionComparator.trimsEqual(authored.trimPrefix, suggestion.trimPrefix),+              RuleDefinitionComparator.trimsEqual(authored.trimSuffix, suggestion.trimSuffix)+        else {+            // Nothing else is touched: the applied flag, the applied suggestion+            // and the pre-suggestion snapshot all survive a failed re-apply.+            restoreTitle(before)+            return false+        }+        // The snapshot is the *pre-suggestion* baseline the clear action returns+        // to, so only the not-applied → applied transition establishes it.+        if !titleSuggestionApplied { titleSuggestionSnapshot = before }+        // Q34: a suggestion is not a stored rule, so seeding it must never raise+        // the stored-rule notice — Req 1.4 says an undepictable side is silent.+        storedTitleRuleNotice = nil+        appliedTitleSuggestion = suggestion+        return true+    }++    /// The URL side's cannot-depict check, run headlessly on the opened entry's+    /// components before anything is published: the same seed-then-read the+    /// editor performs, so a rule it could not reproduce never reaches it.+    private func applyURLSuggestion(_ definition: URLRuleDefinition) -> Bool {+        guard canDepictURLRule(definition) else { return false }+        if !urlSuggestionApplied {+            urlSuggestionSnapshot = URLSuggestionSnapshot(+                definition: urlRuleDefinition, status: urlRuleStatus, disclosure: disclosureState)+        }+        urlRuleStatus = .valid(definition)+        urlRuleDefinition = definition+        // The suggested rule is what the reader has to review, so the section+        // that shows it opens.+        disclosureState = .expanded+        appliedURLSuggestion = definition+        return true+    }++    private func canDepictURLRule(_ definition: URLRuleDefinition) -> Bool {+        guard let components = try? RawURLRuleParser.parse(ExactScalarString(exampleRawURL))+        else { return false }+        var state = ComposedTeachingPresentation.URLEditorState()+        state.seed(from: definition, in: components)+        guard case .valid(let authored) = state.rule(in: components).status else { return false }+        return RuleDefinitionComparator.semanticallyEqual(authored, definition)+    }++    private func isAppliedURLSuggestion(_ definition: URLRuleDefinition?) -> Bool {+        guard let definition, let applied = appliedURLSuggestion else { return false }+        return RuleDefinitionComparator.semanticallyEqual(definition, applied)+    }++    /// Retires one side's suggestion: the marker goes with the applied payload,+    /// the pre-suggestion snapshot is spent, and the side is dismissed for the+    /// rest of the run (Reqs 2.3, 2.7, 2.8).+    ///+    /// The three paths that reach it differ in one thing only. The clear action+    /// puts the editor back as it was; a direct edit on either side has already+    /// replaced that state with the reader's own, and restoring the snapshot+    /// there would undo the very edit that retired the suggestion.+    private func retireSuggestion(_ side: Side, restoringSnapshot: Bool) {+        switch side {+        case .title:+            if restoringSnapshot, let snapshot = titleSuggestionSnapshot { restoreTitle(snapshot) }+            titleSuggestionSnapshot = nil+            appliedTitleSuggestion = nil+        case .url:+            if restoringSnapshot { restoreURLSnapshot() }+            urlSuggestionSnapshot = nil+            appliedURLSuggestion = nil+        }+        suggestions?.dismiss(hostname: hostname, side: side)+    }++    /// Whether a suggestion is currently applied to one side.+    private func isSuggestionApplied(_ side: Side) -> Bool {+        switch side {+        case .title: titleSuggestionApplied+        case .url: urlSuggestionApplied+        }+    }++    /// Whether a suggestion carries anything for one side.+    private static func offers(_ suggestion: RuleSuggestion, _ side: Side) -> Bool {+        switch side {+        case .title: suggestion.title != nil+        case .url: suggestion.url != nil+        }+    }++    private func restoreTitle(_ snapshot: TitleSuggestionSnapshot) {+        subdividedSegments = snapshot.subdividedSegments+        titleChips = snapshot.chips+        titleRoles = snapshot.roles+        titleEdited = snapshot.edited+        storedTitleRuleNotice = snapshot.storedNotice+    }++    private func restoreURLSnapshot() {+        guard let snapshot = urlSuggestionSnapshot else { return }+        urlRuleDefinition = snapshot.definition+        urlRuleStatus = snapshot.status+        disclosureState = snapshot.disclosure+    }++    /// Req 2.7: a side whose suggestion is held or applied, saved as something+    /// else, is dismissed for the rest of the run.+    private func dismissDivergentlySavedSides() {+        guard let suggestions, let request = contract?.request else { return }+        let held = suggestions.held(for: hostname)+        if let title = appliedTitleSuggestion ?? held?.title {+            let same = RuleDefinitionComparator.semanticallyEqual(+                request.titleDefinition, title.definition)+                && RuleDefinitionComparator.trimsEqual(request.trimPrefix, title.trimPrefix)+                && RuleDefinitionComparator.trimsEqual(request.trimSuffix, title.trimSuffix)+            if !same { suggestions.dismiss(hostname: hostname, side: .title) }+        }+        if let url = appliedURLSuggestion ?? held?.url {+            let same = request.urlDefinition+                .map { RuleDefinitionComparator.semanticallyEqual($0, url) } ?? false+            if !same { suggestions.dismiss(hostname: hostname, side: .url) }+        }+    }+     // MARK: - Acknowledgment (Req 2.1, Q3)      /// Records the per-commit unsettled-chapters acknowledgment and commits. The@@ -878,6 +1265,11 @@ public final class ComposedTeachingViewModel {     public func cancel() {         previewTask?.cancel()         previewTask = nil+        // The delivery is cancelled, never the attempt: it is the coordinator's+        // and its result is still worth holding (Req 5.7).+        suggestionTask?.cancel()+        suggestionTask = nil+        suggestionBusy = false         state = .cancelled     } @@ -1043,6 +1435,10 @@ public final class ComposedTeachingViewModel {     private func handleCommitOutcome(_ outcome: ComposedTeachingCommitOutcome) {         switch outcome {         case .committed:+            // Req 2.7's third trigger, read before the contract is let go: a+            // saved rule that is not the suggestion is the reader choosing+            // against it. An equal save is Req 2.6 and dismisses nothing.+            dismissDivergentlySavedSides()             committedOutcome = previewOutcome             requiresReconfirmation = false             state = .committed@@ -1129,6 +1525,11 @@ public final class ComposedTeachingViewModel {     // MARK: - Selection helpers      private func commitTitleEdit() {+        // Req 2.7: a direct edit retires the marker and dismisses the side for+        // the rest of the run.+        if titleSuggestionApplied {+            retireSuggestion(.title, restoringSnapshot: false)+        }         titleEdited = true         titleSelectionNotice = nil         // The stored rule stops being the one in effect the moment the reader@@ -1174,18 +1575,34 @@ public final class ComposedTeachingViewModel {     /// case `retainedTitleRule` keeps the commit faithful until the reader     /// actually edits the title.     private func seedTitleEditor(from rule: ComposedTitleRuleBasis) {-        switch rule.definition {+        seedTitleEditor(+            definition: rule.definition, trimPrefix: rule.trimPrefix, trimSuffix: rule.trimSuffix)+    }++    /// The seeding itself, taking only the three fields it reads.+    ///+    /// A suggested title rule is seeded through exactly this path (Q14): what+    /// the reader sees for a suggestion and for a stored rule must come from+    /// one implementation, cannot-depict fallback included, or Req 1.4's "the+    /// same cannot-depict fallback a stored rule has" is two behaviours.+    func seedTitleEditor(+        definition: PatternDefinition, trimPrefix: String?, trimSuffix: String?+    ) {+        switch definition {         case .wholeTitle:-            let span = keptSpan(forTrimPrefix: rule.trimPrefix, trimSuffix: rule.trimSuffix)+            let span = keptSpan(forTrimPrefix: trimPrefix, trimSuffix: trimSuffix)             applySelection(workSpan: span, chapterSpan: nil)         case .segment(let work, let ignored):             applySegmentSelection(-                rule: rule, work: work, ignored: ignored, chapterFromRemainder: true)+                definition: definition, trimPrefix: trimPrefix, trimSuffix: trimSuffix,+                work: work, ignored: ignored, chapterFromRemainder: true)         case .chapterlessSegment(let work, let ignored):             applySegmentSelection(-                rule: rule, work: work, ignored: ignored, chapterFromRemainder: false)+                definition: definition, trimPrefix: trimPrefix, trimSuffix: trimSuffix,+                work: work, ignored: ignored, chapterFromRemainder: false)         case .phrase, .chapterlessPhrase:-            if let spans = phraseSpans(for: rule) {+            if let spans = phraseSpans(+                definition: definition, trimPrefix: trimPrefix, trimSuffix: trimSuffix) {                 applySelection(workSpan: spans.work, chapterSpan: spans.chapter)             }         }@@ -1203,12 +1620,14 @@ public final class ComposedTeachingViewModel {     }      private func applySegmentSelection(-        rule: ComposedTitleRuleBasis, work: SegmentRangeSpec, ignored: [SegmentPositionSpec],+        definition: PatternDefinition, trimPrefix: String?, trimSuffix: String?,+        work: SegmentRangeSpec, ignored: [SegmentPositionSpec],         chapterFromRemainder: Bool     ) {-        guard rule.trimPrefix == nil, rule.trimSuffix == nil else {+        guard trimPrefix == nil, trimSuffix == nil else {             applyTrimmedSegmentSelection(-                rule: rule, work: work, ignored: ignored, chapterFromRemainder: chapterFromRemainder)+                definition: definition, trimPrefix: trimPrefix, trimSuffix: trimSuffix,+                work: work, ignored: ignored, chapterFromRemainder: chapterFromRemainder)             return         }         guard let restored = Self.roles(@@ -1225,11 +1644,12 @@ public final class ComposedTeachingViewModel {     /// whole-title selection and says the stored rule is the one in effect,     /// rather than presenting a different rule as if it were the stored one.     private func applyTrimmedSegmentSelection(-        rule: ComposedTitleRuleBasis, work: SegmentRangeSpec, ignored: [SegmentPositionSpec],+        definition: PatternDefinition, trimPrefix: String?, trimSuffix: String?,+        work: SegmentRangeSpec, ignored: [SegmentPositionSpec],         chapterFromRemainder: Bool     ) {         guard let selection = trimmedSegmentSelection(-                rule: rule, work: work, ignored: ignored,+                trimPrefix: trimPrefix, trimSuffix: trimSuffix, work: work, ignored: ignored,                 chapterFromRemainder: chapterFromRemainder),               let inferred = ComposedTeachingPresentation.inferredTitleRule(                 title: exampleTitle, segments: titleSegments,@@ -1238,9 +1658,9 @@ public final class ComposedTeachingViewModel {               // canonically-equal but byte-distinct definition is the same rule.               // This is the seeding half of the projection's own faithfulness               // check (`ComposedTeachingProjection.titleVersionProjection`).-              RuleDefinitionComparator.semanticallyEqual(inferred.definition, rule.definition),-              RuleDefinitionComparator.trimsEqual(inferred.trimPrefix, rule.trimPrefix),-              RuleDefinitionComparator.trimsEqual(inferred.trimSuffix, rule.trimSuffix)+              RuleDefinitionComparator.semanticallyEqual(inferred.definition, definition),+              RuleDefinitionComparator.trimsEqual(inferred.trimPrefix, trimPrefix),+              RuleDefinitionComparator.trimsEqual(inferred.trimSuffix, trimSuffix)         else {             storedTitleRuleNotice = ComposedTeachingPresentation.storedTitleRuleNotice             return@@ -1256,24 +1676,25 @@ public final class ComposedTeachingViewModel {     /// stored anchors inverted against the **post-trim** segment count. Nil     /// where any of those cannot be expressed.     private func trimmedSegmentSelection(-        rule: ComposedTitleRuleBasis, work: SegmentRangeSpec, ignored: [SegmentPositionSpec],+        trimPrefix: String?, trimSuffix: String?,+        work: SegmentRangeSpec, ignored: [SegmentPositionSpec],         chapterFromRemainder: Bool     ) -> (subdivided: Set<Int>, chips: [ComposedTeachingPresentation.TitleChip], roles: [SegmentRole])? {         guard let first = titleSegments.first, let last = titleSegments.last,               let kept = TitleTrimApplicator.keptCharacterRange(-                prefix: rule.trimPrefix, suffix: rule.trimSuffix, in: exampleTitle)+                prefix: trimPrefix, suffix: trimSuffix, in: exampleTitle)         else { return nil }         let lastIndex = titleSegments.count - 1          var subdivided: Set<Int> = []-        if rule.trimPrefix != nil {+        if trimPrefix != nil {             guard kept.lowerBound < first.range.upperBound,                   partBoundaries(ofSegment: 0).starts.contains(kept.lowerBound) else { return nil }             subdivided.insert(0)         } else if kept.lowerBound != first.range.lowerBound {             return nil         }-        if rule.trimSuffix != nil {+        if trimSuffix != nil {             guard kept.upperBound > last.range.lowerBound,                   partBoundaries(ofSegment: lastIndex).ends.contains(kept.upperBound) else { return nil }             subdivided.insert(lastIndex)@@ -1284,7 +1705,7 @@ public final class ComposedTeachingViewModel {         // The stored anchors index the trimmed title's segments (Req 3.4), so         // the inversion runs against that count and maps back positionally.         let trimmed = TitleTrimApplicator.apply(-            prefix: rule.trimPrefix, suffix: rule.trimSuffix, to: exampleTitle)+            prefix: trimPrefix, suffix: trimSuffix, to: exampleTitle)         let trimmedSegments = ComposedTeachingPresentation.titleSegments(in: trimmed)         guard trimmedSegments.count == titleSegments.count,               let segmentRoles = Self.roles(@@ -1322,13 +1743,15 @@ public final class ComposedTeachingViewModel {     /// rule still parses it. `.phrase` is `prefix + FIELD + separator + FIELD +     /// suffix`, so the parsed field lengths locate both spans exactly; a title the     /// rule no longer parses leaves the selection at its default.-    private func phraseSpans(for rule: ComposedTitleRuleBasis) -> (work: Range<Int>, chapter: Range<Int>)? {-        guard case .phrase(let prefix, _, let suffix, let order) = rule.definition,+    private func phraseSpans(+        definition: PatternDefinition, trimPrefix: String?, trimSuffix: String?+    ) -> (work: Range<Int>, chapter: Range<Int>)? {+        guard case .phrase(let prefix, _, let suffix, let order) = definition,               case .success(let parsed) = TitleRuleApplicator.apply(-                definition: rule.definition, trimPrefix: rule.trimPrefix,-                trimSuffix: rule.trimSuffix, to: entry.captureTitle),+                definition: definition, trimPrefix: trimPrefix,+                trimSuffix: trimSuffix, to: entry.captureTitle),               let chapterTitle = parsed.chapterTitle,-              rule.trimPrefix == nil, rule.trimSuffix == nil else { return nil }+              trimPrefix == nil, trimSuffix == nil else { return nil }          let characters = Array(entry.captureTitle)         let count = characters.count

diff --git a/Asterism/Asterism/Views/ComposedTeachingPresentation.swift b/Asterism/Asterism/Views/ComposedTeachingPresentation.swiftindex ff98579..4f9e5b6 100644--- a/Asterism/Asterism/Views/ComposedTeachingPresentation.swift+++ b/Asterism/Asterism/Views/ComposedTeachingPresentation.swift@@ -211,7 +211,8 @@ public enum ComposedTeachingPresentation {      /// Character ranges of the maximal alphanumeric runs in a component — the     /// tappable tokens of the split editor. Everything between is separator text.-    public static func tokenRanges(in componentText: String) -> [Range<Int>] {+    /// `nonisolated`: reached from the nonisolated `titleChips`, and pure.+    public nonisolated static func tokenRanges(in componentText: String) -> [Range<Int>] {         var ranges: [Range<Int>] = []         var runStart: Int?         for (offset, character) in componentText.enumerated() {@@ -289,7 +290,10 @@ public enum ComposedTeachingPresentation {     // MARK: - Two-granularity title chip selection (Req 3.3, 8.3, 8.6)      /// A delimiter-split segment of the example title with its character range.-    public struct TitleSegment: Equatable, Sendable {+    /// `nonisolated`: the app target defaults to main-actor isolation, and the+    /// synthesized `==` has to be usable off the main actor — `RuleSuggestionAssembler`+    /// compares these values on the suggester actor.+    public nonisolated struct TitleSegment: Equatable, Sendable {         public let text: String         public let range: Range<Int>     }@@ -297,7 +301,8 @@ public enum ComposedTeachingPresentation {     /// One tappable title chip: a whole delimiter-split **segment** by default,     /// or one **part** (maximal alphanumeric run) of a segment the reader has     /// subdivided in place.-    public struct TitleChip: Equatable, Sendable {+    /// `nonisolated` for the same reason as `TitleSegment`.+    public nonisolated struct TitleChip: Equatable, Sendable {         public let text: String         /// Character range within the example title.         public let range: Range<Int>@@ -310,7 +315,8 @@ public enum ComposedTeachingPresentation {      /// The title rule a chip selection authors. The form is inferred from the     /// selection and never chosen by the reader (Req 8.6).-    public struct InferredTitleRule: Equatable, Sendable {+    /// `nonisolated` for the same reason as `TitleSegment`.+    public nonisolated struct InferredTitleRule: Equatable, Sendable {         public let definition: PatternDefinition         public let trimPrefix: String?         public let trimSuffix: String?@@ -357,7 +363,8 @@ public enum ComposedTeachingPresentation {     /// The chip row for a set of subdivided segment indices. Subdividing happens     /// in place: the subdivided segment's chip is replaced by its part chips in     /// the same row (Req 8.3 — no sheet, no second screen).-    public static func titleChips(segments: [TitleSegment], subdividing: Set<Int>) -> [TitleChip] {+    /// `nonisolated`: reached from the nonisolated `titleSelection`, and pure.+    public nonisolated static func titleChips(segments: [TitleSegment], subdividing: Set<Int>) -> [TitleChip] {         var chips: [TitleChip] = []         for (index, segment) in segments.enumerated() {             let parts = tokenRanges(in: segment.text)@@ -403,7 +410,8 @@ public enum ComposedTeachingPresentation {     /// table, widened by Reqs 3.1–3.5). Returns nil for a selection that cannot     /// author a legal rule; the caller uses that to make such selections     /// unreachable rather than reporting a validation error afterwards.-    public static func inferredTitleRule(+    /// `nonisolated`: called off the main actor by `RuleSuggestionAssembler`, and pure.+    public nonisolated static func inferredTitleRule(         title: String, segments: [TitleSegment], chips: [TitleChip], roles: [SegmentRole]     ) -> InferredTitleRule? {         inferenceOutcome(title: title, segments: segments, chips: chips, roles: roles).rule@@ -514,7 +522,8 @@ public enum ComposedTeachingPresentation {     /// The chip selection that reproduces a Work span and an optional chapter     /// span — used to re-seed the selector from the rule a Site already holds.     /// Segments a span cuts through are subdivided so the boundary is expressible.-    public static func titleSelection(+    /// `nonisolated`: called off the main actor by `RuleSuggestionAssembler`, and pure.+    public nonisolated static func titleSelection(         in title: String, workSpan: Range<Int>, chapterSpan: Range<Int>?     ) -> (subdivided: Set<Int>, roles: [SegmentRole]) {         let segments = titleSegments(in: title)@@ -709,7 +718,8 @@ public enum ComposedTeachingPresentation {     }      /// Whether a span's boundary falls strictly inside a segment.-    private static func splits(_ segment: Range<Int>, by span: Range<Int>) -> Bool {+    /// `nonisolated`: called from the nonisolated `titleSelection`, and pure.+    private nonisolated static func splits(_ segment: Range<Int>, by span: Range<Int>) -> Bool {         (span.lowerBound > segment.lowerBound && span.lowerBound < segment.upperBound)             || (span.upperBound > segment.lowerBound && span.upperBound < segment.upperBound)     }

diff --git a/Asterism/Asterism/Views/ComposedTeachingView.swift b/Asterism/Asterism/Views/ComposedTeachingView.swiftindex d7681e7..15033c6 100644--- a/Asterism/Asterism/Views/ComposedTeachingView.swift+++ b/Asterism/Asterism/Views/ComposedTeachingView.swift@@ -1,4 +1,5 @@ import AsterismCore+import AsterismIntelligence import ConstellationKit import SwiftUI @@ -88,6 +89,10 @@ struct ComposedTeachingView: View {         if model.articlesRequested {             articlesConfirmation         } else {+            // rule-suggestion Req 6.1: the on-request action is the first+            // actionable thing on the screen, above the selection it fills in —+            // beside the commit control it went unnoticed.+            suggestRow             titleChipSelector             urlDisclosure             if let outcome = model.previewOutcome {@@ -154,6 +159,14 @@ struct ComposedTeachingView: View {                     .accessibilityIdentifier("composed-title-stored-rule-notice")             } +            if model.titleSuggestionApplied {+                suggestionMarker(+                    voiceOverLabel: "Suggested title rule",+                    identifier: "composed-title-suggested",+                    clearIdentifier: "composed-title-suggested-clear",+                    clear: { model.clearSuggestedSide(.title) })+            }+             if let caption = model.titleTrimCaption {                 // Req 3.7 (Q24): the trims the effective rule carries, named                 // where the reader can check them against the example title.@@ -190,6 +203,110 @@ struct ComposedTeachingView: View {         .frame(maxWidth: .infinity, alignment: .leading)     } +    // MARK: - Rule suggestion (rule-suggestion Reqs 2.1, 2.3, 6.1, 6.3, 6.4)++    /// One side's "this was suggested" marker with its clear action, in the same+    /// amber caption register as the editor's other notices.+    ///+    /// The row keeps its children (`.contain`), or the clear button is+    /// unqueryable from XCUITest and unreachable from VoiceOver+    /// (`docs/agent-notes/composed-teaching-ui.md`). The marker's own identifier+    /// goes on the **label**, not on the row: inside the URL disclosure, a+    /// container element one level under the `DisclosureGroup` is merged with+    /// the group's element and takes its `composed-url-disclosure` identifier,+    /// so a row-level identifier there is silently lost. Leaves keep theirs.+    private func suggestionMarker(+        voiceOverLabel: String, identifier: String, clearIdentifier: String,+        clear: @escaping () -> Void+    ) -> some View {+        HStack(spacing: 8) {+            suggestionMarkerLabel(voiceOverLabel: voiceOverLabel, identifier: identifier)+            Spacer(minLength: 0)+            Button("Clear", action: clear)+                .font(.footnote)+                .frame(minHeight: AsterismLayout.minHitTarget)+                .accessibilityIdentifier(clearIdentifier)+                .accessibilityLabel("Clear \(voiceOverLabel.lowercased())")+        }+        .frame(maxWidth: .infinity, alignment: .leading)+        .accessibilityElement(children: .contain)+    }++    /// The marker itself: one combined element, so the symbol and the caption+    /// read as a single VoiceOver stop and one identifier addresses it.+    private func suggestionMarkerLabel(+        voiceOverLabel: String, identifier: String+    ) -> some View {+        Label("Suggested — review before saving", systemImage: "sparkles")+            .font(.caption)+            .foregroundStyle(AsterismColors.amberText)+            .accessibilityElement(children: .combine)+            .accessibilityLabel(voiceOverLabel)+            .accessibilityIdentifier(identifier)+    }++    /// Req 6.1: shown only while the on-device model is there and the Site is+    /// one a rule can be taught for. It heads the editor, so it is the first+    /// actionable control the reader meets — a full-width secondary button, kept+    /// visually distinct from the one gradient control the commit wears.+    ///+    /// Busy disables the button and shows a `ProgressView` inside the capsule+    /// (Req 6.3); a suggestion that arrived too late to be applied says so under+    /// it with the same `sparkles` the marker uses (Req 5.9), and Req 6.4's+    /// notice sits under it too, where the tap happened.+    ///+    /// The spinner is an **overlay**, not part of the button's label: a+    /// `Button` merges its label into one element, which would swallow the+    /// `composed-suggest-busy` identifier+    /// (`docs/agent-notes/composed-teaching-ui.md`).+    @ViewBuilder+    private var suggestRow: some View {+        if model.offersSuggestAction {+            VStack(alignment: .leading, spacing: 8) {+                Button {+                    Task { await model.requestSuggestion() }+                } label: {+                    Label("Suggest rule", systemImage: "sparkles")+                        .frame(maxWidth: .infinity, minHeight: AsterismLayout.minHitTarget)+                }+                .buttonStyle(.constellationSecondary)+                .disabled(model.suggestionBusy)+                .accessibilityIdentifier("composed-suggest")+                .overlay(alignment: .trailing) {+                    if model.suggestionBusy {+                        ProgressView()+                            .controlSize(.small)+                            .padding(.trailing, 18)+                            .accessibilityIdentifier("composed-suggest-busy")+                            .accessibilityLabel("Working on a suggestion")+                    }+                }++                if model.suggestionReady {+                    Label("A suggestion is ready", systemImage: "sparkles")+                        .font(.caption)+                        .foregroundStyle(AsterismColors.amberText)+                        .accessibilityElement(children: .combine)+                        .accessibilityLabel("A suggestion is ready")+                        .accessibilityIdentifier("composed-suggest-ready")+                }++                if let notice = model.suggestionUnavailableNotice {+                    // rule-suggestion Req 6.4: the one thing about suggestions+                    // the reader is ever told, in the same amber caption+                    // register as the editor's other notices.+                    Label(notice, systemImage: "exclamationmark.circle")+                        .font(.caption)+                        .foregroundStyle(AsterismColors.amberText)+                        .accessibilityIdentifier("composed-suggest-unavailable")+                }+            }+            .frame(maxWidth: .infinity, alignment: .leading)+            .accessibilityElement(children: .contain)+            .accessibilityIdentifier("composed-suggest-row")+        }+    }+     // MARK: - Articles affordance (Req 8.7)      /// Articles is a one-way Site transition, not a title rule form, so it sits@@ -265,6 +382,13 @@ struct ComposedTeachingView: View {                 set: { model.setURLDisclosureExpanded($0) })         ) {             VStack(alignment: .leading, spacing: 12) {+                if model.urlSuggestionApplied {+                    suggestionMarker(+                        voiceOverLabel: "Suggested URL rule",+                        identifier: "composed-url-suggested",+                        clearIdentifier: "composed-url-suggested-clear",+                        clear: { model.clearSuggestedSide(.url) })+                }                 // The editor owns the single clear affordance                 // ("composed-url-clear"); a second one here would clear the                 // definition without resetting the editor's own selections.@@ -308,6 +432,20 @@ struct ComposedTeachingView: View {                     Text(ComposedTeachingPresentation.disclosureBenefit)                         .font(.caption).foregroundStyle(.secondary)                 }+                if model.urlSuggestionApplied, !model.urlDisclosureExpanded {+                    // Req 2.1: the marker is visible for as long as the+                    // suggestion is applied, and while the section is closed+                    // this row is all there is of the URL side. Gated on the+                    // same condition that hides the section's own marker, so+                    // exactly one carries the identifier at any moment.+                    //+                    // The clear action stays inside the section: a button in a+                    // DisclosureGroup's label competes with the header's own tap+                    // target, and Req 2.3 asks for one action, not two.+                    suggestionMarkerLabel(+                        voiceOverLabel: "Suggested URL rule",+                        identifier: "composed-url-suggested")+                }             }         }         .accessibilityIdentifier("composed-url-disclosure")

diff --git a/Asterism/Asterism/Views/ComposedURLEditorState.swift b/Asterism/Asterism/Views/ComposedURLEditorState.swiftindex 3618cef..971ab9f 100644--- a/Asterism/Asterism/Views/ComposedURLEditorState.swift+++ b/Asterism/Asterism/Views/ComposedURLEditorState.swift@@ -507,6 +507,19 @@ extension ComposedTeachingPresentation {             split = ComposedTeachingPresentation.defaultSplitSelection(for: componentText)         } +        /// Set the within-component split outright, without going through the+        /// reader's token gestures (Q36).+        ///+        /// `RuleSuggestionAssembler` has two character spans in one component+        /// and no gestures to make; `beginSplit` + repeated `toggleSplitToken`+        /// cannot express an arbitrary pair. The split itself is all that is+        /// set: `rule(in:)` treats a live split as superseding anything+        /// retained and re-derives the template from it, exactly as it does+        /// after a token tap.+        mutating func setSplit(_ selection: URLTwoFieldSelection) {+            split = selection+        }+         /// A token tap inside the split editor.         public mutating func toggleSplitToken(at index: Int, tokens: [Range<Int>]) {             guard let current = split else { return }

diff --git a/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift b/Asterism/AsterismTests/ComposedTeachingViewModelTests.swiftindex 6ba5f53..502b7d2 100644--- a/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift+++ b/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift@@ -1,4 +1,5 @@ import AsterismCore+import AsterismIntelligence import Foundation import Testing @testable import Asterism@@ -17,9 +18,11 @@ struct ComposedTeachingViewModelTests {      private static func makeEntry(         title: String = "TtH - Story - Real Title",-        hostname: String = ComposedTeachingViewModelTests.hostname+        hostname: String = ComposedTeachingViewModelTests.hostname,+        rawURLString: String? = nil     ) -> EntrySnapshot {-        TestFixtures.makeEntry(captureTitle: title, hostname: hostname)+        TestFixtures.makeEntry(+            captureTitle: title, hostname: hostname, rawURLString: rawURLString)     }      private static func makeOutcome(requiresAck: Bool = false) -> ComposedTeachingOutcome {@@ -67,7 +70,8 @@ struct ComposedTeachingViewModelTests {         commitOutcome: ComposedTeachingCommitOutcome = .committed(             titleRuleID: UUID(), titleRuleVersion: 1, urlRuleID: nil, urlRuleVersion: nil),         entryContext: ComposedTeachingViewModel.EntryContext = .titleFocused,-        entry: EntrySnapshot? = nil+        entry: EntrySnapshot? = nil,+        suggestions: RuleSuggestionCoordinator? = nil     ) -> (ComposedTeachingViewModel, MockLibraryProvider) {         let mock = MockLibraryProvider()         let c = contract ?? Self.makeContract()@@ -77,7 +81,7 @@ struct ComposedTeachingViewModelTests {         mock.commitArticlesResult = .success(.committed)         let vm = ComposedTeachingViewModel(             entry: entry ?? Self.makeEntry(), library: mock, capabilities: .m4,-            entryContext: entryContext, onMutation: {})+            entryContext: entryContext, onMutation: {}, suggestions: suggestions)         return (vm, mock)     } @@ -1016,4 +1020,494 @@ struct ComposedTeachingViewModelTests {         #expect(request.titleDefinition == expected)         #expect(request.titleDefinition != definition)     }++    // MARK: - Rule suggestion (Reqs 1, 2, 3.5, 5.7–5.9, 6)++    /// The suggested title rule for `TtH - Story - Real Title`: the last segment+    /// names the Work, the rest is the chapter. Seeding it re-derives exactly+    /// this definition, which is what Req 3.5 demands of a suggestion.+    private static func suggestedTitle(+        trimPrefix: String? = nil+    ) throws -> TitleRuleSuggestion {+        TitleRuleSuggestion(+            definition: .segment(+                work: try SegmentRangeSpec(origin: .end, offset: 0, length: 1), ignored: []),+            trimPrefix: trimPrefix)+    }++    /// A URL rule the editor can depict on the fixture URL below: a query item+    /// carries its own name, so seeding it needs no anchoring.+    nonisolated private static let suggestedURL = URLRuleDefinition.sequence(+        locator: .query(name: ExactScalarString("chapter")))++    /// The capture the suggestion tests open the editor from — three title+    /// segments and a query-bearing URL.+    private static func suggestionEntry() -> EntrySnapshot {+        makeEntry(+            title: "TtH - Story - Real Title",+            rawURLString: "https://example.com/read?id=42&chapter=7")+    }++    private static func suggestion(+        title: TitleRuleSuggestion? = nil, url: URLRuleDefinition? = nil+    ) -> RuleSuggestion {+        RuleSuggestion(hostname: hostname, title: title, url: url)+    }++    /// A coordinator over the stubbed attempt seam. `held` is delivered through+    /// a settled background attempt, which is the only way the ledger holds a+    /// suggestion; `delivers` is left for the editor's own on-open attempt.+    private func makeCoordinator(+        held: RuleSuggestion? = nil,+        delivers: RuleSuggestion? = nil,+        availability: ModelAvailability = .available+    ) async -> (RuleSuggestionCoordinator, RuleSuggestionCoordinatorTests.StubSuggester) {+        let mock = MockLibraryProvider()+        mock.ruleSuggestionCandidatesResult = .success([+            RuleSuggestionCandidate(+                hostname: Self.hostname, siteMode: .untaught, titleRuleVersion: nil,+                urlRuleVersion: nil, entryCount: 3,+                latestCaptureAt: Date(timeIntervalSince1970: 1)),+        ])+        let suggester = RuleSuggestionCoordinatorTests.StubSuggester()+        let coordinator = RuleSuggestionCoordinator(+            library: mock,+            model: StubRuleSuggestionModelClient(availability: availability),+            suggester: suggester,+            environment: RuleSuggestionCoordinatorTests.StubEnvironment())+        if let held {+            suggester.suggestions[Self.hostname] = held+            _ = await coordinator.suggestion(for: Self.hostname, origin: .background)+            suggester.suggestions[Self.hostname] = nil+        }+        suggester.suggestions[Self.hostname] = delivers+        return (coordinator, suggester)+    }++    /// Spins the main actor until the condition holds. The on-open delivery is a+    /// child task, so there is something to wait for but nothing to sleep on.+    private func yieldUntil(_ condition: () -> Bool) async {+        var spins = 0+        while !condition(), spins < 200 {+            await Task.yield()+            spins += 1+        }+    }++    @Test("A held suggestion seeds both untaught sides and marks them")+    func heldSuggestionSeedsUntaughtSides() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(vm.titleSuggestionApplied)+        #expect(vm.urlSuggestionApplied)+        #expect(vm.titleRoles == [.chapter, .chapter, .work])+        #expect(vm.urlRuleDefinition == Self.suggestedURL)+        #expect(vm.effectiveTitleRule?.definition == held.title?.definition)+        // Req 2.5: nothing was written because a suggestion was applied.+        #expect(vm.state != .committed)+    }++    @Test("The retained rule wins on a taught side; the untaught side still seeds")+    func retainedRuleWinsOnTaughtSide() async throws {+        let retained = PatternDefinition.wholeTitle+        let contract = Self.makeContract(+            currentTitleRule: Self.titleRuleBasis(definition: retained))+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(+            contract: contract, entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.effectiveTitleRule?.definition == retained)+        #expect(vm.urlSuggestionApplied)+    }++    @Test("A dismissed side is not prefilled by the automatic path (Req 2.8)")+    func dismissedSideIsNotPrefilled() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        coordinator.dismiss(hostname: Self.hostname, side: .title)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.urlSuggestionApplied)+    }++    @Test("Editing the title clears its marker and dismisses that side (Req 2.7)")+    func titleEditDismissesTheTitleSide() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        #expect(vm.titleSuggestionApplied)++        vm.cycleTitleRole(at: 0)++        #expect(!vm.titleSuggestionApplied)+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .title))+        #expect(!coordinator.isDismissed(hostname: Self.hostname, side: .url))+    }++    @Test("A differing URL outcome clears its marker and dismisses that side (Q47)")+    func urlEditDismissesTheURLSide() async throws {+        let held = Self.suggestion(url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        #expect(vm.urlSuggestionApplied)++        vm.setURLRuleDefinition(.sequence(locator: .query(name: ExactScalarString("id"))))++        #expect(!vm.urlSuggestionApplied)+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .url))+    }++    @Test("The URL editor re-publishing the same rule is not an edit")+    func equalURLOutcomeDoesNotDismiss() async throws {+        let held = Self.suggestion(url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()++        vm.setURLRuleDefinition(Self.suggestedURL)++        #expect(vm.urlSuggestionApplied)+        #expect(!coordinator.isDismissed(hostname: Self.hostname, side: .url))+    }++    @Test("Clearing a suggested side restores the untaught initial state and dismisses it")+    func clearRestoresUntaughtState() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()++        vm.clearSuggestedSide(.title)+        vm.clearSuggestedSide(.url)++        #expect(!vm.titleSuggestionApplied)+        #expect(!vm.urlSuggestionApplied)+        // The untaught initial state: whole title, no URL selection.+        #expect(vm.titleRoles == [.work, .work, .work])+        #expect(vm.urlRuleDefinition == nil)+        #expect(vm.urlRuleStatus == .cleared)+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .title))+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .url))+    }++    @Test("Clearing a suggested side on a taught site restores the retained rule (Q42)")+    func clearRestoresRetainedRule() async throws {+        let retained = PatternDefinition.wholeTitle+        let contract = Self.makeContract(+            currentTitleRule: Self.titleRuleBasis(definition: retained))+        let (coordinator, _) = await makeCoordinator(+            held: Self.suggestion(title: try Self.suggestedTitle()))+        let (vm, _) = makeSUT(+            contract: contract, entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        // Only the request path reaches a taught side.+        await vm.requestSuggestion()+        #expect(vm.titleSuggestionApplied)++        vm.clearSuggestedSide(.title)++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.effectiveTitleRule?.definition == retained)+    }++    @Test("The pre-suggestion snapshot is taken once, so a re-apply keeps the original baseline")+    func snapshotIsTakenOnce() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        #expect(vm.titleRoles == [.chapter, .chapter, .work])++        // A second application of the same held suggestion must not snapshot the+        // suggested selection as if it were the pre-suggestion state.+        await vm.requestSuggestion()+        vm.clearSuggestedSide(.title)++        #expect(vm.titleRoles == [.work, .work, .work])+    }++    @Test("effectiveTitleRule follows the suggestion once it is applied on a taught side (Q33)")+    func effectiveRuleFollowsSuggestionOnTaughtSide() async throws {+        let retained = PatternDefinition.wholeTitle+        let contract = Self.makeContract(+            currentTitleRule: Self.titleRuleBasis(definition: retained))+        let suggested = try Self.suggestedTitle()+        let (coordinator, _) = await makeCoordinator(held: Self.suggestion(title: suggested))+        let (vm, mock) = makeSUT(+            contract: contract, entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()++        await vm.requestSuggestion()+        try await Task.sleep(for: .milliseconds(30))++        #expect(vm.effectiveTitleRule?.definition == suggested.definition)+        let request = try #require(mock.lastProjectComposedRequest)+        #expect(request.titleDefinition == suggested.definition)+    }++    @Test("A rule the opened capture cannot depict restores the snapshot and raises no notice")+    func cannotDepictRestoresTheSnapshot() async throws {+        // The trim is absent from this title, so seeding falls back to the+        // default selection and would ordinarily raise the stored-rule notice.+        let undepictable = try Self.suggestedTitle(trimPrefix: "Read ")+        let (coordinator, _) = await makeCoordinator(+            held: Self.suggestion(title: undepictable, url: Self.suggestedURL))+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.storedTitleRuleNotice == nil)+        #expect(vm.titleRoles == [.work, .work, .work])+        // Req 1.3: the other side is unaffected.+        #expect(vm.urlSuggestionApplied)+    }++    @Test("A re-apply that cannot be depicted leaves the applied side exactly as it was")+    func undepictableReapplyLeavesTheAppliedSideUnchanged() async throws {+        let applied = try Self.suggestedTitle()+        let (coordinator, _) = await makeCoordinator(held: Self.suggestion(title: applied))+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        #expect(vm.titleSuggestionApplied)+        #expect(vm.titleRoles == [.chapter, .chapter, .work])++        // A second suggestion for the same side — the hostname's hold was+        // recomputed after a save — whose trim is absent from this title, so it+        // cannot be depicted. Req 6.2 / Req 1.4 on request: left unchanged.+        let undepictable = Self.suggestion(title: try Self.suggestedTitle(trimPrefix: "Read "))+        let took = await vm.applySuggestion(undepictable, origin: .request)++        #expect(took.isEmpty)+        #expect(vm.titleSuggestionApplied)+        #expect(vm.titleRoles == [.chapter, .chapter, .work])+        #expect(vm.effectiveTitleRule?.definition == applied.definition)+        #expect(vm.storedTitleRuleNotice == nil)+        // The pre-suggestion baseline survived the failed re-apply, so the clear+        // action still returns the side to the untaught initial state (Req 2.3).+        vm.clearSuggestedSide(.title)+        #expect(vm.titleRoles == [.work, .work, .work])+    }++    /// Req 5.7's "no held suggestion for **any of its untaught sides**": a hold+    /// that only covers the taught side fills nothing, so the open falls through+    /// to the on-open request rather than returning satisfied. The coordinator+    /// then refuses it — the hold's own attempt is this run's attempt for the+    /// hostname — which is why the URL side stays untaught here.+    @Test("A hold covering only a taught side leaves the untaught side untouched (Req 5.7)")+    func holdOverATaughtSideLeavesTheUntaughtSideAlone() async throws {+        let contract = Self.makeContract(+            currentTitleRule: Self.titleRuleBasis(definition: .wholeTitle))+        let (coordinator, suggester) = await makeCoordinator(+            held: Self.suggestion(title: try Self.suggestedTitle()))+        let (vm, _) = makeSUT(+            contract: contract, entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(!vm.titleSuggestionApplied)+        #expect(!vm.urlSuggestionApplied)+        #expect(vm.urlRuleDefinition == nil)+        // Req 5.9: the hold exists but nothing took it, so the action says ready.+        #expect(vm.suggestionReady)+        #expect(suggester.calls == [Self.hostname])+    }++    @Test("Applying and then clearing leaves the ready indicator reading the hold (Q68)")+    func clearingASideRetiresItFromTheReadyIndicator() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()+        // Both sides took, so there is nothing left for the action to offer.+        #expect(vm.titleSuggestionApplied)+        #expect(vm.urlSuggestionApplied)+        #expect(!vm.suggestionReady)++        // The hold still carries a title side after the clear, but the reader+        // has just rejected it — the action must not advertise it as ready.+        vm.clearSuggestedSide(.title)+        #expect(!vm.titleSuggestionApplied)+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .title))+        #expect(!vm.suggestionReady)++        vm.clearSuggestedSide(.url)+        #expect(!vm.suggestionReady)+    }++    @Test("A side rejected earlier in the run does not light the ready indicator")+    func dismissedSideIsNotReady() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(held: held)+        // The reader rejected the title side in an earlier editor session; the+        // dismissal outlives the editor (Q18).+        coordinator.dismiss(hostname: Self.hostname, side: .title)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.urlSuggestionApplied)+        // The unapplied title side is unapplied because the reader said so, so+        // Req 5.9's indicator stays dark rather than nagging with it.+        #expect(!vm.suggestionReady)+    }++    @Test("A cancel while a request is in flight leaves the editor cancelled")+    func cancelDuringARequestIsNotOverwritten() async throws {+        let (coordinator, suggester) = await makeCoordinator()+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        // The editor's own on-open attempt settles with nothing first.+        await yieldUntil { !vm.suggestionBusy }++        suggester.isGated = true+        suggester.suggestions[Self.hostname] = Self.suggestion(title: try Self.suggestedTitle())+        let request = Task { await vm.requestSuggestion() }+        await yieldUntil { vm.suggestionBusy }+        vm.cancel()+        suggester.openGate()+        await request.value++        #expect(vm.state == .cancelled)+        #expect(!vm.titleSuggestionApplied)+    }++    @Test("A result arriving within the auto-apply window seeds untouched sides only")+    func lateResultWithinWindowAppliesUntouchedSides() async throws {+        let delivered = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)+        let (coordinator, _) = await makeCoordinator(delivers: delivered)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()+        // Touch the URL side before the result lands.+        vm.setURLRuleDefinition(.sequence(locator: .query(name: ExactScalarString("id"))))+        await yieldUntil { vm.titleSuggestionApplied }++        #expect(vm.titleSuggestionApplied)+        #expect(!vm.urlSuggestionApplied)+        #expect(vm.suggestionReady)+    }++    @Test("A result arriving after the window is held and only marks the action ready (Req 5.9)")+    func lateResultOutsideWindowIsNotApplied() async throws {+        let delivered = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(delivers: delivered)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        vm.suggestionAutoApplyWindow = .zero++        await vm.load()+        await yieldUntil { vm.suggestionReady }++        #expect(!vm.titleSuggestionApplied)+        #expect(vm.suggestionReady)+        #expect(vm.titleRoles == [.work, .work, .work])+    }++    @Test("The request applies a held suggestion to a dismissed side and clears the dismissal")+    func requestAppliesToDismissedSide() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        coordinator.dismiss(hostname: Self.hostname, side: .title)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        #expect(!vm.titleSuggestionApplied)++        await vm.requestSuggestion()++        #expect(vm.titleSuggestionApplied)+        #expect(!coordinator.isDismissed(hostname: Self.hostname, side: .title))+        #expect(!vm.suggestionBusy)+        #expect(vm.suggestionUnavailableNotice == nil)+    }++    @Test("A request that settles with nothing says so and changes neither side (Req 6.4)")+    func requestWithoutSuggestionShowsTheNotice() async throws {+        let (coordinator, _) = await makeCoordinator()+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        // The editor's own on-open attempt has to settle before the action is+        // triggerable at all (Req 6.3).+        await yieldUntil { !vm.suggestionBusy }++        await vm.requestSuggestion()++        #expect(vm.suggestionUnavailableNotice != nil)+        #expect(!vm.titleSuggestionApplied)+        #expect(!vm.urlSuggestionApplied)+        #expect(!vm.suggestionBusy)+    }++    @Test("Applying a suggestion regenerates the preview for the whole hostname (Req 1.5)")+    func applyingRegeneratesThePreview() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, mock) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)++        await vm.load()+        try await Task.sleep(for: .milliseconds(30))++        let request = try #require(mock.lastProjectComposedRequest)+        #expect(request.titleDefinition == held.title?.definition)+        #expect(vm.state == .previewReady)+    }++    @Test("The Suggest action is offered only while the model is available and the Site is not articles")+    func suggestActionVisibility() async throws {+        let (available, _) = await makeCoordinator()+        let (shown, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: available)+        await shown.load()+        #expect(shown.offersSuggestAction)++        let (away, _) = await makeCoordinator(availability: .unavailable(reason: "test"))+        let (hidden, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: away)+        await hidden.load()+        #expect(!hidden.offersSuggestAction)++        let (none, _) = makeSUT(entry: Self.suggestionEntry())+        await none.load()+        #expect(!none.offersSuggestAction)+    }++    @Test("Saving a rule that differs from the suggestion dismisses that side (Req 2.7)")+    func divergentCommitDismisses() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        // Edit away from the suggestion, then save what the reader authored.+        vm.cycleTitleRole(at: 0)+        try await Task.sleep(for: .milliseconds(30))+        await vm.confirm()++        #expect(vm.state == .committed)+        #expect(coordinator.isDismissed(hostname: Self.hostname, side: .title))+    }++    @Test("Saving the suggestion itself dismisses nothing (Req 2.6)")+    func identicalCommitDoesNotDismiss() async throws {+        let held = Self.suggestion(title: try Self.suggestedTitle())+        let (coordinator, _) = await makeCoordinator(held: held)+        let (vm, _) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator)+        await vm.load()+        try await Task.sleep(for: .milliseconds(30))+        await vm.confirm()++        #expect(vm.state == .committed)+        #expect(!coordinator.isDismissed(hostname: Self.hostname, side: .title))+    } }

diff --git a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swiftindex 55abafe..6a3b23c 100644--- a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift+++ b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift@@ -182,6 +182,24 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable {         return try sitesResult.get()     } +    // MARK: - Rule suggestion candidates++    var ruleSuggestionCandidatesCallCount = 0+    var ruleSuggestionCandidatesResult: Result<[RuleSuggestionCandidate], Error> = .success([])+    /// What the last call asked for: nil is the sweep's whole-store read, a set+    /// is `reconcile`'s tracked hostnames. Doubly optional so a test can tell+    /// "asked for everything" from "was never called".+    var lastRuleSuggestionCandidateHostnames: Set<String>??++    func ruleSuggestionCandidates(hostnames: Set<String>?) async throws -> [RuleSuggestionCandidate] {+        ruleSuggestionCandidatesCallCount += 1+        callLog.append("ruleSuggestionCandidates")+        lastRuleSuggestionCandidateHostnames = hostnames+        let rows = try ruleSuggestionCandidatesResult.get()+        guard let hostnames else { return rows }+        return rows.filter { hostnames.contains($0.hostname) }+    }+     // MARK: - Work types      var workTypesCallCount = 0@@ -479,8 +497,32 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable {     // MARK: - Composed teaching and recalculation stubs      var projectComposedTeachingResult: Result<ComposedTeachingContract, Error> = .failure(MockError.notConfigured)-    var projectComposedTeachingCallCount = 0-    var lastProjectComposedRequest: ComposedTeachingRequest?+    /// The projection's three records — the count, the last request and the+    /// whole log — all under one lock, unlike the rest of this class: the+    /// composed generation tests deliberately overlap two projections, and+    /// unsynchronised writes from two threads tear (an array append reallocates+    /// under itself, and a count loses an increment).+    var projectComposedTeachingCallCount: Int {+        composedRequestLock.withLock { storedComposedTeachingCallCount }+    }+    var lastProjectComposedRequest: ComposedTeachingRequest? {+        composedRequestLock.withLock { storedLastComposedRequest }+    }+    /// Every request the projection was given, in order. One suggestion attempt+    /// makes a basis call and up to three verification calls, and which sets it+    /// tried is only visible here (design steps 1 and 6).+    var projectComposedRequests: [ComposedTeachingRequest] {+        composedRequestLock.withLock { storedComposedRequests }+    }+    private let composedRequestLock = NSLock()+    private var storedComposedRequests: [ComposedTeachingRequest] = []+    private var storedComposedTeachingCallCount = 0+    private var storedLastComposedRequest: ComposedTeachingRequest?+    /// Answers per request rather than with one preset contract, for the same+    /// reason: a test of the verification ladder has to pass one candidate set+    /// and fail another. Takes precedence over `projectComposedTeachingResult`.+    var projectComposedTeachingHandler:+        (@Sendable (String, ComposedTeachingRequest) throws -> ComposedTeachingContract)?      var commitComposedTeachingResult: Result<ComposedTeachingCommitOutcome, Error> = .failure(MockError.notConfigured)     var commitComposedTeachingCallCount = 0@@ -500,12 +542,16 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable {     var composedProjectionDelay: Duration?      func projectComposedTeaching(hostname: String, request: ComposedTeachingRequest) async throws -> ComposedTeachingContract {-        projectComposedTeachingCallCount += 1-        lastProjectComposedRequest = request+        composedRequestLock.withLock {+            storedComposedTeachingCallCount += 1+            storedLastComposedRequest = request+            storedComposedRequests.append(request)+        }         if let delay = composedProjectionDelay { try await Task.sleep(for: delay) }         // Mirror the real repository: the returned contract carries the request         // that produced it, so acknowledgment state round-trips into the commit.-        let base = try projectComposedTeachingResult.get()+        let base = try projectComposedTeachingHandler.map { try $0(hostname, request) }+            ?? projectComposedTeachingResult.get()         return ComposedTeachingContract(basis: base.basis, request: request, outcome: base.outcome)     } 

diff --git a/Asterism/AsterismTests/RuleSuggesterTests.swift b/Asterism/AsterismTests/RuleSuggesterTests.swiftnew file mode 100644index 0000000..866c988--- /dev/null+++ b/Asterism/AsterismTests/RuleSuggesterTests.swift@@ -0,0 +1,390 @@+import AsterismCore+import AsterismIntelligence+import Foundation+import Testing+@testable import Asterism++/// Tests for `RuleSuggester.attempt(hostname:)` — the whole attempt pipeline+/// against a mock library and the scripted model stub. No model is involved,+/// and none of these run on the main actor: the suggester is an actor precisely+/// so the model call and the projections stay off it (Req 5.1).+@Suite("RuleSuggester")+struct RuleSuggesterTests {++    // MARK: - Fixtures++    private static let hostname = "example.com"++    /// Chapter `index` of the one story on the hostname. A higher index is+    /// newer, so the highest is the anchor.+    private static func basisEntry(_ index: Int) -> ComposedEntryBasis {+        ComposedEntryBasis(+            id: UUID(), captureTitle: "Some Story - Chapter \(index)",+            rawURLString: "https://example.com/series/some-story/chapter-\(index)",+            hostname: hostname, firstCapturedAt: Date(timeIntervalSince1970: TimeInterval(index)),+            chapterTitle: nil, chapterTitleProvenance: .none, workID: nil,+            workAssignmentProvenance: .none, intentionallyUnattached: false)+    }++    private static func basis(+        entries: Int = 3,+        currentTitleRule: ComposedTitleRuleBasis? = nil,+        currentURLRule: ComposedURLRuleBasis? = nil+    ) -> ComposedTeachingBasis {+        ComposedTeachingBasis(+            siteMode: currentTitleRule == nil ? .untaught : .taught, hostname: hostname,+            entries: (1...max(entries, 1)).map(basisEntry), works: [],+            currentTitleRule: currentTitleRule, currentURLRule: currentURLRule)+    }++    private static func outcome(+        entryCount: Int = 3, titleFailure: PatternApplicationError? = nil,+        urlFailure: URLRuleApplicationError? = nil, workName: String? = "Some Story",+        requiresAck: Bool = false+    ) -> ComposedTeachingOutcome {+        let entries = (0..<entryCount).map { _ in+            ComposedEntryProjection(+                entryID: UUID(), previousWorkID: nil, previousChapterTitle: nil,+                workName: workName, workNameSource: .parsed,+                projectedChapterTitle: nil, projectedChapterSequence: nil,+                projectedIdentityBasis: .conservative, projectedKeyVersion: 1,+                projectedIdentityKey: "key", assignment: .noChange, projectedWorkID: nil,+                chapterSettled: true, actionableAfter: false,+                titleFailure: titleFailure, urlFailure: urlFailure)+        }+        return ComposedTeachingOutcome(+            titleVersion: .available(1), urlVersion: nil, entries: entries, works: [],+            issues: [], prospectiveWorks: [], requiresUnsettledAcknowledgment: requiresAck)+    }++    private static func contract(+        basis: ComposedTeachingBasis, outcome: ComposedTeachingOutcome+    ) -> ComposedTeachingContract {+        ComposedTeachingContract(+            basis: basis, request: ComposedTeachingRequest(titleDefinition: .wholeTitle),+            outcome: outcome)+    }++    /// The basis read, told apart from the verification calls by its content:+    /// the whole-title, no-URL request the editor's `load()` also makes.+    private static func isBasisRequest(_ request: ComposedTeachingRequest) -> Bool {+        request.urlDefinition == nil && request.titleDefinition == .wholeTitle+            && request.trimPrefix == nil && request.trimSuffix == nil+    }++    /// The proposal for the three-chapter fixture: both sides present,+    /// everything copied verbatim from the anchor.+    private static let goodProposal = RuleProposal(+        workName: "Some Story", chapterText: "Chapter 3",+        urlWorkIdentity: "some-story", urlSequenceText: "chapter-3")++    private func makeSUT(+        basis: ComposedTeachingBasis? = nil,+        basisFailure: (any Error & Sendable)? = nil,+        proposal: RuleProposal? = goodProposal,+        error: (any Error & Sendable)? = nil,+        results: [StubRuleSuggestionModelClient.ScriptedResult] = [],+        delay: Duration? = nil,+        timeout: Duration = .seconds(30),+        verification: (@Sendable (ComposedTeachingRequest) -> ComposedTeachingOutcome)? = nil+    ) -> (RuleSuggester, MockLibraryProvider, StubRuleSuggestionModelClient) {+        let mock = MockLibraryProvider()+        let resolved = basis ?? Self.basis()+        let verify = verification ?? { _ in Self.outcome() }+        mock.projectComposedTeachingHandler = { _, request in+            if let basisFailure, Self.isBasisRequest(request) { throw basisFailure }+            return Self.contract(+                basis: resolved,+                outcome: Self.isBasisRequest(request) ? Self.outcome() : verify(request))+        }+        let stub = StubRuleSuggestionModelClient(+            proposal: proposal, error: error, delay: delay, results: results)+        return (RuleSuggester(library: mock, model: stub, timeout: timeout), mock, stub)+    }++    // MARK: - The happy path++    @Test("Both sides verify together and are offered together")+    func happyPathBothSides() async throws {+        let (suggester, mock, stub) = makeSUT()+        let result = try await suggester.attempt(hostname: Self.hostname)+        let suggestion = try #require(result.suggestion)++        #expect(suggestion.hostname == Self.hostname)+        guard case .segment = try #require(suggestion.title).definition else {+            Issue.record("expected a segment title rule")+            return+        }+        guard case .workAndSequence = try #require(suggestion.url) else {+            Issue.record("expected a two-slot URL rule")+            return+        }+        // One basis read plus one verification: the pair passed first time.+        #expect(mock.projectComposedRequests.count == 2)+        #expect(stub.recorder.callCount == 1)+        #expect(result.modelPhase > .zero)+    }++    @Test("The model is shown the newest capture as the anchor and older ones as context")+    func corpusIsAnchoredOnTheNewestCapture() async throws {+        let (suggester, _, stub) = makeSUT()+        _ = try await suggester.attempt(hostname: Self.hostname)+        let corpus = try #require(stub.recorder.recordedCorpora.first)+        #expect(corpus.anchor.title == "Some Story - Chapter 3")+        #expect(corpus.context.map(\.title) == [+            "Some Story - Chapter 2", "Some Story - Chapter 1",+        ])+    }++    // MARK: - The verification ladder (Req 3.4, Q27, Q48)++    @Test("A pair that fails together is reduced to the title side beside the stored URL rule")+    func pairFailureFallsBackToTitleOnly() async throws {+        let stored = URLRuleDefinition.sequence(locator: .query(name: ExactScalarString("ch")))+        let taughtBasis = Self.basis(+            currentURLRule: ComposedURLRuleBasis(+                id: UUID(), version: 1, origin: .readerTaught, definition: stored))+        let (suggester, mock, _) = makeSUT(basis: taughtBasis) { request in+            // Only the pair carries both candidates; the single-side sets carry+            // one candidate and one stored rule.+            guard case .workAndSequence = request.urlDefinition,+                  case .segment = request.titleDefinition else { return Self.outcome() }+            return Self.outcome(titleFailure: .blankResult(field: "work"))+        }++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)+        #expect(suggestion.title != nil)+        #expect(suggestion.url == nil)+        // Basis, the failed pair, then the title alone beside the stored rule.+        #expect(mock.projectComposedRequests.count == 3)+        #expect(mock.projectComposedRequests[2].urlDefinition == stored)+    }++    @Test("A URL-only suggestion is projected with the Site's stored title rule")+    func urlOnlyUsesTheStoredTitleRule() async throws {+        let storedDefinition = PatternDefinition.chapterlessSegment(+            work: try SegmentRangeSpec(origin: .start, offset: 0, length: 1), ignored: [])+        let taughtBasis = Self.basis(+            currentTitleRule: ComposedTitleRuleBasis(+                id: UUID(), version: 1, definition: storedDefinition,+                trimPrefix: nil, trimSuffix: nil))+        // The Work name is not in the anchor title, so there is no title side.+        let proposal = RuleProposal(+            workName: "Absent From The Title", chapterText: "Chapter 3",+            urlWorkIdentity: "some-story", urlSequenceText: "chapter-3")+        let (suggester, mock, _) = makeSUT(basis: taughtBasis, proposal: proposal)++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)+        #expect(suggestion.title == nil)+        #expect(suggestion.url != nil)+        #expect(mock.projectComposedRequests.count == 2)+        #expect(mock.projectComposedRequests[1].titleDefinition == storedDefinition)+    }++    @Test("A URL-only suggestion on an untaught Site is projected with the whole-title default")+    func urlOnlyUsesWholeTitleWhenUntaught() async throws {+        let proposal = RuleProposal(+            workName: "Absent From The Title", chapterText: "Chapter 3",+            urlWorkIdentity: "some-story", urlSequenceText: "chapter-3")+        let (suggester, mock, _) = makeSUT(proposal: proposal)++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)+        #expect(suggestion.url != nil)+        #expect(mock.projectComposedRequests[1].titleDefinition == .wholeTitle)+    }++    @Test("A title rule equal to the untaught default is never projected on its own")+    func defaultTitleAloneIsNotOffered() async throws {+        // The chapter text sits inside the Work text, so the optional span is+        // dropped (Req 3.1) and the title side collapses to the whole-title+        // default — which may ride along in the pair but must never be a set of+        // its own.+        let proposal = RuleProposal(+            workName: "Some Story - Chapter 3", chapterText: "Chapter 3",+            urlWorkIdentity: "some-story", urlSequenceText: "chapter-3")+        let (suggester, mock, _) = makeSUT(proposal: proposal) { _ in+            Self.outcome(titleFailure: .blankResult(field: "work"))+        }++        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+        // Basis, the pair, the URL alone. A fourth call would be the title-only+        // set, which carries nothing but the default and is skipped.+        #expect(mock.projectComposedRequests.count == 3)+        #expect(mock.projectComposedRequests.dropFirst().allSatisfy { $0.urlDefinition != nil })+    }++    @Test("An entry the title rule fails on fails the whole set")+    func titleFailureFailsTheSet() async throws {+        let (suggester, _, _) = makeSUT { _ in+            Self.outcome(titleFailure: .blankResult(field: "work"))+        }+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+    }++    @Test("An entry the URL rule fails on fails the whole set")+    func urlFailureFailsTheSet() async throws {+        let (suggester, _, _) = makeSUT { _ in+            Self.outcome(urlFailure: .ambiguousSeparator(count: 0))+        }+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+    }++    @Test("An entry with no Work name fails the whole set")+    func missingWorkNameFailsTheSet() async throws {+        let (suggester, _, _) = makeSUT { _ in Self.outcome(workName: nil) }+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+    }++    @Test("A set that would require the unsettled-chapters acknowledgment fails")+    func unsettledAcknowledgmentFailsTheSet() async throws {+        let (suggester, _, _) = makeSUT { _ in Self.outcome(requiresAck: true) }+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+    }++    // MARK: - Locating and the short-circuit (Reqs 3.1, Q44)++    @Test("Neither a chapter nor a URL sequence settles the attempt before any verification")+    func noChapterAndNoSequenceShortCircuits() async throws {+        let proposal = RuleProposal(+            workName: "Some Story", chapterText: "",+            urlWorkIdentity: "some-story", urlSequenceText: "")+        let (suggester, mock, stub) = makeSUT(proposal: proposal)++        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+        // The model ran; nothing was projected beyond the basis read.+        #expect(stub.recorder.callCount == 1)+        #expect(mock.projectComposedRequests.count == 1)+    }++    @Test("Chapter text sitting inside the Work text costs the chapter, not the suggestion")+    func chapterInsideTheWorkNameDropsOnlyTheChapter() async throws {+        // Q49: an optional span overlapping its required one is dropped, rather+        // than failing the whole proposal. The URL sequence is what keeps the+        // chapters settled once the title has none.+        let proposal = RuleProposal(+            workName: "Some Story - Chapter 3", chapterText: "Chapter 3",+            urlWorkIdentity: "some-story", urlSequenceText: "chapter-3")+        let (suggester, mock, _) = makeSUT(proposal: proposal)++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)++        #expect(suggestion.url != nil)+        // The title rule that survives names no chapter, so the projected pair+        // carries a rule over the whole title rather than a two-role selection.+        let paired = try #require(mock.projectComposedRequests.dropFirst().first)+        #expect(paired.titleDefinition == .wholeTitle)+        // Basis and the pair: the ladder never had to fall back.+        #expect(mock.projectComposedRequests.count == 2)+    }++    @Test("URL sequence text sitting inside the identity costs the sequence, not the URL side")+    func sequenceInsideTheIdentityDropsOnlyTheSequence() async throws {+        // "chapter" occurs once, inside the "chapter-3" the model also named as+        // the identity — one component, two overlapping spans.+        let proposal = RuleProposal(+            workName: "Some Story", chapterText: "Chapter 3",+            urlWorkIdentity: "chapter-3", urlSequenceText: "chapter")+        let (suggester, _, _) = makeSUT(proposal: proposal)++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)+        let url = try #require(suggestion.url)++        #expect(url.suppliesIdentity)+        // The sequence span went; the identity stands on its own, and the title+        // side is what settles the chapters.+        #expect(!url.suppliesSequence)+        #expect(suggestion.title != nil)+    }++    @Test("Text the model copied out of the host is located in no component")+    func identityInTheHostYieldsNoURLSide() async throws {+        let proposal = RuleProposal(+            workName: "Some Story", chapterText: "Chapter 3",+            urlWorkIdentity: "example.com", urlSequenceText: "chapter-3")+        let (suggester, mock, _) = makeSUT(proposal: proposal)++        let suggestion = try #require(try await suggester.attempt(hostname: Self.hostname).suggestion)+        #expect(suggestion.url == nil)+        #expect(suggestion.title != nil)+        #expect(mock.projectComposedRequests[1].urlDefinition == nil)+    }++    // MARK: - Model failures (Reqs 3.7, 4.2)++    @Test("A context-window overflow halves the corpus and retries within the attempt")+    func contextWindowOverflowHalvesAndRetries() async throws {+        // Five captures, so the anchor is chapter 5 and the proposal quotes it.+        let anchored = RuleProposal(+            workName: "Some Story", chapterText: "Chapter 5",+            urlWorkIdentity: "some-story", urlSequenceText: "chapter-5")+        let (suggester, _, stub) = makeSUT(+            basis: Self.basis(entries: 5), proposal: nil,+            results: [+                .failure(StubRuleSuggestionModelClientError.contextWindowOverflow),+                .success(anchored),+            ])++        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion != nil)+        #expect(stub.recorder.callCount == 2)+        // Five captures cap at the anchor plus four context entries; the retry+        // drops half of them, oldest first.+        #expect(stub.recorder.recordedCorpora.map(\.context.count) == [4, 2])+    }++    @Test("Any other model failure settles the attempt with nothing")+    func otherModelErrorYieldsNothing() async throws {+        let (suggester, mock, _) = makeSUT(+            proposal: nil, error: StubRuleSuggestionModelClientError.noCannedProposal)+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+        #expect(mock.projectComposedRequests.count == 1)+    }++    @Test("A basis read that throws — an articles Site — settles the attempt with nothing")+    func articlesBasisThrowYieldsNothing() async throws {+        let (suggester, _, stub) = makeSUT(+            basisFailure: ComposedTeachingProjectionError.invalidTitleDefinition(+                reason: "articles"))++        let result = try await suggester.attempt(hostname: Self.hostname)+        #expect(result.suggestion == nil)+        #expect(result.modelPhase == .zero)+        #expect(stub.recorder.callCount == 0)+    }++    @Test("A hostname with no captures settles the attempt with nothing")+    func noCapturesYieldsNothing() async throws {+        let empty = ComposedTeachingBasis(+            siteMode: .untaught, hostname: Self.hostname, entries: [], works: [],+            currentTitleRule: nil, currentURLRule: nil)+        let (suggester, _, stub) = makeSUT(basis: empty)+        #expect(try await suggester.attempt(hostname: Self.hostname).suggestion == nil)+        #expect(stub.recorder.callCount == 0)+    }++    // MARK: - Timeout and cancellation (Reqs 5.4, 5.10, Q45)++    @Test("An attempt that outlives its bound throws AttemptTimeout carrying what it spent")+    func timeoutThrowsAttemptTimeout() async throws {+        let (suggester, _, _) = makeSUT(delay: .seconds(30), timeout: .milliseconds(50))+        do {+            _ = try await suggester.attempt(hostname: Self.hostname)+            Issue.record("expected the attempt to time out")+        } catch let timeout as AttemptTimeout {+            #expect(timeout.modelPhase >= .milliseconds(50))+        }+    }++    @Test("A system cancellation propagates rather than settling as no suggestion")+    func cancellationPropagates() async throws {+        let (suggester, _, stub) = makeSUT(delay: .seconds(30))+        let task = Task { try await suggester.attempt(hostname: Self.hostname) }+        while stub.recorder.callCount == 0 { await Task.yield() }+        task.cancel()+        do {+            _ = try await task.value+            Issue.record("expected the attempt to be cancelled")+        } catch is CancellationError {+            // The system's own cancellation, distinct from a timeout (Q45).+        }+    }+}

diff --git a/Asterism/AsterismTests/RuleSuggestionAssemblerTests.swift b/Asterism/AsterismTests/RuleSuggestionAssemblerTests.swiftnew file mode 100644index 0000000..d5cc143--- /dev/null+++ b/Asterism/AsterismTests/RuleSuggestionAssemblerTests.swift@@ -0,0 +1,217 @@+import AsterismCore+import AsterismIntelligence+import Foundation+import Testing+@testable import Asterism++/// Tests for `RuleSuggestionAssembler` — design step 5, the span→rule seam.+///+/// The suite is deliberately **not** `@MainActor`: the assembler runs on the+/// `RuleSuggester` actor, and the editor helpers it drives are only usable+/// there because task 7 made them `nonisolated`. A main-actor suite would pass+/// while the suggester still failed to compile.+@Suite("RuleSuggestionAssembler")+struct RuleSuggestionAssemblerTests {++    // MARK: - Helpers++    private static func components(_ rawURL: String) throws -> RawURLLexicalComponents {+        try RawURLRuleParser.parse(ExactScalarString(rawURL))+    }++    /// The character range of `text` in `source`, as the locator would produce.+    private static func span(_ text: String, in source: String) throws -> Range<Int> {+        try #require(ProposalLocator.locate(text, in: source))+    }++    // MARK: - Title assembly++    @Test("The whole title marked as the Work yields the whole-title rule with no trims")+    func wholeTitleWork() throws {+        let title = "Some Story"+        let rule = try #require(RuleSuggestionAssembler.titleRule(+            anchorTitle: title, workSpan: Self.span("Some Story", in: title), chapterSpan: nil))+        #expect(rule.definition == .wholeTitle)+        #expect(rule.trimPrefix == nil)+        #expect(rule.trimSuffix == nil)+    }++    @Test("Work and chapter on whole segments yield the segment form")+    func workAndChapterSegments() throws {+        let title = "Some Story - Chapter 3"+        let rule = try #require(RuleSuggestionAssembler.titleRule(+            anchorTitle: title,+            workSpan: Self.span("Some Story", in: title),+            chapterSpan: Self.span("Chapter 3", in: title)))+        guard case .segment = rule.definition else {+            Issue.record("expected a segment form, got \(rule.definition)")+            return+        }+    }++    @Test("A chapter segment before the work segment still yields the segment form")+    func chapterBeforeWork() throws {+        let title = "Chapter 3 - Some Story"+        let rule = try #require(RuleSuggestionAssembler.titleRule(+            anchorTitle: title,+            workSpan: Self.span("Some Story", in: title),+            chapterSpan: Self.span("Chapter 3", in: title)))+        guard case .segment = rule.definition else {+            Issue.record("expected a segment form, got \(rule.definition)")+            return+        }+    }++    @Test("Sub-segment spans yield a phrase rule")+    func subSegmentPhrase() throws {+        let title = "Prologue of Story #12"+        let rule = try #require(RuleSuggestionAssembler.titleRule(+            anchorTitle: title,+            workSpan: Self.span("Story", in: title),+            chapterSpan: Self.span("12", in: title)))+        guard case .phrase = rule.definition else {+            Issue.record("expected a phrase form, got \(rule.definition)")+            return+        }+    }++    @Test("A selection whose separator is whitespace-only is unauthorable and yields nothing")+    func whitespaceSeparatorIsUnauthorable() throws {+        // Parts are maximal alphanumeric runs, so the separator between "Story"+        // and "12" is a bare space — which `PhrasePatternDeriver` refuses. The+        // chip cycle keeps this selection unreachable for a reader; a model+        // proposal can still land on it, so the assembler has to refuse it too.+        let title = "Some Story 12"+        #expect(RuleSuggestionAssembler.titleRule(+            anchorTitle: title,+            workSpan: try Self.span("Some Story", in: title),+            chapterSpan: try Self.span("12", in: title)) == nil)+    }++    @Test("An out-of-bounds work span yields nothing")+    func outOfBoundsTitleSpan() {+        #expect(RuleSuggestionAssembler.titleRule(+            anchorTitle: "Some Story", workSpan: 50..<60, chapterSpan: nil) == nil)+    }++    // MARK: - URL assembly++    @Test("An identity in one path component yields a Work-identity rule")+    func identityInOnePathComponent() throws {+        let raw = "https://example.com/series/some-story/chapter-3"+        let parsed = try Self.components(raw)+        let definition = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<10), sequence: nil))+        guard case .work(let locator) = definition else {+            Issue.record("expected a Work-identity rule, got \(definition)")+            return+        }+        #expect(locator == .pathBracketed(+            left: .literal(ExactScalarString("series")), right: .unanchored))+    }++    @Test("Identity and sequence in different components yield a two-slot rule")+    func identityAndSequenceInDifferentComponents() throws {+        let raw = "https://example.com/series/some-story/chapter-3"+        let parsed = try Self.components(raw)+        let definition = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<10), sequence: (.path(2), 8..<9)))+        guard case .workAndSequence(let work, let sequence) = definition else {+            Issue.record("expected a two-slot rule, got \(definition)")+            return+        }+        #expect(work.locator == .pathBracketed(+            left: .literal(ExactScalarString("series")), right: .unanchored))+        #expect(sequence.locator == .pathBracketed(left: .unanchored, right: .end))+    }++    @Test("An identity span in its own component is widened to the whole component")+    func identitySpanIsWidenedWhenTheSequenceIsElsewhere() throws {+        // The spans are component-relative and only ever describe a *split*.+        // With the sequence in another component there is nothing to split, so+        // the identity slot takes its component whole — exactly as a chip tap+        // does — and the partial span is discarded rather than narrowing the+        // rule to something the editor could not have authored.+        let raw = "https://example.com/series/some-story/chapter-3"+        let parsed = try Self.components(raw)+        let partial = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<4), sequence: (.path(2), 8..<9)))+        let whole = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<10), sequence: (.path(2), 8..<9)))++        #expect(partial == whole)+    }++    @Test("A sequence span before the identity span yields the sequence-first order")+    func sequenceBeforeIdentityInOneComponent() throws {+        // The model is not asked for an order and Req 3.1 does not impose one+        // (Q49); the deriver reads the order off the two spans.+        let raw = "https://example.com/series/3-somestory"+        let parsed = try Self.components(raw)+        let definition = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 2..<11), sequence: (.path(1), 0..<1)))+        guard case .combined(_, let template) = definition else {+            Issue.record("expected a combined rule, got \(definition)")+            return+        }+        #expect(template.order == .sequenceThenWork)+        #expect(template.separator.value == "-")+    }++    @Test("Identity and sequence in the same component yield a combined template")+    func identityAndSequenceInOneComponent() throws {+        let raw = "https://example.com/series/somestory-3"+        let parsed = try Self.components(raw)+        let definition = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<9), sequence: (.path(1), 10..<11)))+        guard case .combined(let locator, let template) = definition else {+            Issue.record("expected a combined rule, got \(definition)")+            return+        }+        #expect(locator == .pathBracketed(+            left: .literal(ExactScalarString("series")), right: .end))+        // The split's separator, not a guess: the deriver read it off the+        // component between the two spans.+        #expect(template.separator.value == "-")+    }++    @Test("A sequence span overlapping the identity span in one component is dropped")+    func overlappingSplitFallsBackToTheWholeComponent() throws {+        // The suggester drops an overlapping optional span before it reaches+        // here; this pins what the assembler does if one arrives anyway — the+        // deriver refuses, and a refused split is no rule rather than a wrong+        // one.+        let raw = "https://example.com/series/somestory-3"+        let parsed = try Self.components(raw)+        #expect(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(1), 0..<11), sequence: (.path(1), 0..<11)) == nil)+    }++    @Test("A selection that is not a component of this URL yields nothing")+    func selectionOutsideTheURL() throws {+        // Text the model copied out of the *host* is located in no path+        // component and no query value, so the suggester forms no selection for+        // it at all. An index past the path is the same shape, and is what the+        // assembler must refuse.+        let parsed = try Self.components("https://example.com/series/some-story")+        #expect(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(9), 0..<4), sequence: nil) == nil)+    }++    @Test("A component no anchoring can single out yields nothing")+    func unauthorableComponent() throws {+        // Both neighbours are blank, so the only offered pair is+        // unanchored/unanchored — which the representation always refuses.+        let parsed = try Self.components("https://example.com/a//x//b")+        #expect(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.path(2), 0..<1), sequence: nil) == nil)+    }++    @Test("A query value carries the identity as a query locator")+    func identityInAQueryValue() throws {+        let parsed = try Self.components("https://example.com/read.php?story=somestory&ch=3")+        let definition = try #require(RuleSuggestionAssembler.urlRule(+            components: parsed, identity: (.query(0), 0..<9), sequence: nil))+        #expect(definition == .work(locator: .query(name: ExactScalarString("story"))))+    }+}

diff --git a/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swift b/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swiftnew file mode 100644index 0000000..20e9ccb--- /dev/null+++ b/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swift@@ -0,0 +1,677 @@+import AsterismCore+import AsterismIntelligence+import Foundation+import Testing+@testable import Asterism++/// Tests for `RuleSuggestionCoordinator`: the sweep, invalidation, delivery and+/// the gates, with the attempt itself stubbed out. The ledger's own transitions+/// are covered host-side in `RuleSuggestionLedgerTests`; what is pinned here is+/// what the coordinator does *around* them — the `Task`, the clock, the library+/// read, and the callers waiting on a result.+@Suite("RuleSuggestionCoordinator")+@MainActor+struct RuleSuggestionCoordinatorTests {++    // MARK: - Doubles++    /// The attempt seam. Records what it was asked and how many attempts were+    /// running at once, so "at most one computation at a time" (Req 5.11) is an+    /// assertion rather than an inference.+    final class StubSuggester: RuleSuggesting, @unchecked Sendable {+        private let lock = NSLock()+        private var _calls: [String] = []+        private var _concurrent = 0+        private var _peakConcurrent = 0+        private var _isGated = false+        private var _gateWaiters: [CheckedContinuation<Void, Never>] = []+        private var _arrivalWaiters: [(count: Int, waiter: CheckedContinuation<Void, Never>)] = []++        /// Answers per hostname; a hostname with no entry settles with nothing.+        nonisolated(unsafe) var suggestions: [String: RuleSuggestion] = [:]+        nonisolated(unsafe) var delay: Duration?+        nonisolated(unsafe) var modelPhase: Duration = .milliseconds(100)+        nonisolated(unsafe) var failure: (any Error)?++        var calls: [String] { lock.withLock { _calls } }+        var peakConcurrent: Int { lock.withLock { _peakConcurrent } }++        /// Holds every attempt at a gate the test opens by hand, so a test can+        /// keep an attempt in flight without sleeping for it.+        var isGated: Bool {+            get { lock.withLock { _isGated } }+            set { lock.withLock { _isGated = newValue } }+        }++        /// Releases the gate and lets later attempts through it.+        func openGate() {+            let waiting = lock.withLock { () -> [CheckedContinuation<Void, Never>] in+                _isGated = false+                defer { _gateWaiters = [] }+                return _gateWaiters+            }+            for waiter in waiting { waiter.resume() }+        }++        /// Suspends until `count` attempts have started. The deterministic+        /// alternative to a sleep: the caller knows the attempt is in flight+        /// because the attempt said so.+        func waitForAttempts(_ count: Int) async {+            await withCheckedContinuation { continuation in+                let alreadyThere = lock.withLock { () -> Bool in+                    guard _calls.count < count else { return true }+                    _arrivalWaiters.append((count, continuation))+                    return false+                }+                if alreadyThere { continuation.resume() }+            }+        }++        func attempt(+            hostname: String+        ) async throws -> (suggestion: RuleSuggestion?, modelPhase: Duration) {+            let arrived = lock.withLock { () -> [CheckedContinuation<Void, Never>] in+                _calls.append(hostname)+                _concurrent += 1+                _peakConcurrent = max(_peakConcurrent, _concurrent)+                let ready = _arrivalWaiters.filter { $0.count <= _calls.count }+                _arrivalWaiters.removeAll { $0.count <= _calls.count }+                return ready.map(\.waiter)+            }+            for waiter in arrived { waiter.resume() }+            defer { lock.withLock { _concurrent -= 1 } }++            if isGated {+                await withCheckedContinuation { continuation in+                    let open = lock.withLock { () -> Bool in+                        guard _isGated else { return true }+                        _gateWaiters.append(continuation)+                        return false+                    }+                    if open { continuation.resume() }+                }+                // Deliberately checked only *after* the gate opens: a real+                // attempt does not stop the instant it is cancelled either, and+                // the gap between the two is where several of these tests live.+                try Task.checkCancellation()+            }+            if let delay { try await Task.sleep(for: delay) }+            if let failure { throw failure }+            return (suggestions[hostname], modelPhase)+        }+    }++    /// A model client whose availability can change between activations, which+    /// is the whole point of re-reading it (Q41). The stub in the package is a+    /// value type, so a copy the coordinator holds could never change.+    final class MutableAvailabilityClient: RuleSuggestionModelClient, @unchecked Sendable {+        nonisolated(unsafe) var availabilityResult: ModelAvailability++        init(_ availability: ModelAvailability) { self.availabilityResult = availability }++        func availability() -> ModelAvailability { availabilityResult }++        /// Never reached: the coordinator's tests stub the suggester, which is+        /// the only thing that talks to a model.+        func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal {+            throw StubRuleSuggestionModelClientError.noCannedProposal+        }+    }++    @MainActor+    final class StubEnvironment: SuggestionEnvironment {+        var isActive = true+        var isLowPowerModeEnabled = false+        var thermalState: ProcessInfo.ThermalState = .nominal+        /// A hand-advanced clock: the coordinator reads it when an attempt+        /// starts and again when a cancellation settles, and nothing else.+        var elapsed: Duration = .zero+        private let base = ContinuousClock.now+        var now: ContinuousClock.Instant { base.advanced(by: elapsed) }+    }++    // MARK: - Fixtures++    private static func candidate(+        _ hostname: String, capturedAt: TimeInterval = 0, mode: SiteMode = .untaught,+        titleRuleVersion: Int? = nil, urlRuleVersion: Int? = nil, entryCount: Int = 3+    ) -> RuleSuggestionCandidate {+        RuleSuggestionCandidate(+            hostname: hostname, siteMode: mode, titleRuleVersion: titleRuleVersion,+            urlRuleVersion: urlRuleVersion, entryCount: entryCount,+            latestCaptureAt: Date(timeIntervalSince1970: capturedAt))+    }++    private static func suggestion(_ hostname: String) -> RuleSuggestion {+        RuleSuggestion(+            hostname: hostname, title: TitleRuleSuggestion(definition: .wholeTitle), url: nil)+    }++    private func makeSUT(+        candidates: [RuleSuggestionCandidate] = [],+        availability: ModelAvailability = .available+    ) -> (RuleSuggestionCoordinator, MockLibraryProvider, StubSuggester, StubEnvironment,+          MutableAvailabilityClient) {+        let mock = MockLibraryProvider()+        mock.ruleSuggestionCandidatesResult = .success(candidates)+        let suggester = StubSuggester()+        let environment = StubEnvironment()+        let client = MutableAvailabilityClient(availability)+        let coordinator = RuleSuggestionCoordinator(+            library: mock, model: client, suggester: suggester, environment: environment)+        return (coordinator, mock, suggester, environment, client)+    }++    /// Spins the main actor until `condition` holds, or until the bound is+    /// reached. No wall-clock sleep is involved: it costs nothing when the+    /// condition is already true, and a coordinator that never gets there fails+    /// the assertion that follows rather than hanging the suite.+    private func yieldUntil(_ condition: () -> Bool) async {+        var spins = 0+        while !condition(), spins < 100 {+            await Task.yield()+            spins += 1+        }+    }++    // MARK: - The activation sweep (Req 5.1)++    @Test("The sweep attempts the three most recent auto-eligible hostnames, newest first")+    func sweepRespectsDepthOrderAndEligibility() async {+        let candidates = [+            Self.candidate("old.test", capturedAt: 10),+            Self.candidate("newest.test", capturedAt: 50),+            Self.candidate("middle.test", capturedAt: 30),+            Self.candidate("second.test", capturedAt: 40),+            // Not auto-eligible: articles mode, no captures, both rules stored.+            Self.candidate("articles.test", capturedAt: 60, mode: .articles),+            Self.candidate("empty.test", capturedAt: 70, entryCount: 0),+            Self.candidate(+                "taught.test", capturedAt: 80, mode: .taught,+                titleRuleVersion: 1, urlRuleVersion: 1),+        ]+        let (coordinator, _, suggester, _, _) = makeSUT(candidates: candidates)++        await coordinator.activationSweep()++        #expect(suggester.calls == ["newest.test", "second.test", "middle.test"])+    }++    @Test("A hostname attempted this run is not swept again")+    func sweepSkipsAttemptedHostnames() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test", capturedAt: 10)])++        await coordinator.activationSweep()+        await coordinator.activationSweep()++        #expect(suggester.calls == ["a.test"])+    }++    @Test("Two sweeps overlapping run as one")+    func sweepIsSingleInstance() async {+        let candidates = (1...3).map { Self.candidate("h\($0).test", capturedAt: TimeInterval($0)) }+        let (coordinator, _, suggester, _, _) = makeSUT(candidates: candidates)+        suggester.delay = .milliseconds(20)++        async let first: Void = coordinator.activationSweep()+        async let second: Void = coordinator.activationSweep()+        _ = await (first, second)++        #expect(suggester.calls.count == 3)+        #expect(suggester.peakConcurrent == 1)+    }++    @Test("A sweep stopped mid-attempt does not swallow the next activation's sweep")+    func stoppedSweepDoesNotSwallowTheNextActivation() async {+        let candidates = (1...3).map {+            Self.candidate("h\($0).test", capturedAt: TimeInterval(10 * $0))+        }+        let (coordinator, mock, suggester, _, _) = makeSUT(candidates: candidates)+        suggester.isGated = true++        async let stopped: Void = coordinator.activationSweep()+        await suggester.waitForAttempts(1)+        // Backgrounded: the sweep is stopped, but the attempt it is awaiting+        // does not notice its cancellation until the gate opens.+        coordinator.resignActive()+        // ... and straight back to the foreground, which is the ordinary shape+        // of a share-then-return.+        async let reactivated: Void = coordinator.activationSweep()+        await yieldUntil { mock.ruleSuggestionCandidatesCallCount > 1 }+        suggester.openGate()+        _ = await (stopped, reactivated)++        // The stopped sweep attempted one hostname and was cancelled out of it,+        // leaving it attemptable; the second activation then swept the full+        // depth, rather than running under the first sweep, refusing every+        // candidate and being switched off by it.+        #expect(suggester.calls == ["h3.test", "h3.test", "h2.test", "h1.test"])+        #expect(suggester.peakConcurrent == 1)+    }++    @Test("Resigning active stops the sweep where it stands")+    func resignActiveStopsTheSweepAtTheNextCandidate() async {+        let candidates = (1...3).map {+            Self.candidate("h\($0).test", capturedAt: TimeInterval(10 * $0))+        }+        let (coordinator, _, suggester, _, _) = makeSUT(candidates: candidates)+        suggester.isGated = true++        async let sweep: Void = coordinator.activationSweep()+        await suggester.waitForAttempts(1)+        coordinator.resignActive()+        suggester.openGate()+        await sweep++        // Candidate 2 is never reached: the sweep stops with the foreground+        // (Req 5.3), and the attempt it was awaiting stays unattempted (Q28).+        #expect(suggester.calls == ["h3.test"])+        #expect(coordinator.isAttempted("h3.test") == false)+    }++    @Test("A hostname the reader rejected on both sides is never swept again")+    func sweepSkipsFullyDismissedHostnames() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test", capturedAt: 10)])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        await coordinator.activationSweep()+        #expect(suggester.calls == ["a.test"])++        coordinator.dismiss(hostname: "a.test", side: .title)+        coordinator.dismiss(hostname: "a.test", side: .url)++        // A capture lands. Invalidation drops the hold and reopens the hostname+        // by design, but it keeps the rejection (Q18) — so the sweep must pass+        // it over rather than spend a slot and up to 10 s of budget on a+        // suggestion the reader has already turned down twice.+        mock.ruleSuggestionCandidatesResult = .success(+            [Self.candidate("a.test", capturedAt: 10, entryCount: 4)])+        await coordinator.reconcile()+        #expect(coordinator.isAttempted("a.test") == false)++        await coordinator.activationSweep()+        #expect(suggester.calls == ["a.test"])+    }++    @Test("A spent budget stops the sweep before it reads the library")+    func exhaustedBudgetSkipsTheCandidateRead() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.modelPhase = RuleSuggestionBounds.runTimeBudget+        await coordinator.activationSweep()+        let reads = mock.ruleSuggestionCandidatesCallCount++        await coordinator.activationSweep()++        // Every candidate would be refused for the budget anyway (Q31), and the+        // read that would establish that is 2N SwiftData fetches per activation.+        #expect(mock.ruleSuggestionCandidatesCallCount == reads)+        #expect(suggester.calls == ["a.test"])+    }++    @Test("The sweep starts nothing in Low Power Mode or a serious thermal state")+    func sweepGates() async {+        let (lowPower, _, lowPowerSuggester, lowPowerEnvironment, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        lowPowerEnvironment.isLowPowerModeEnabled = true+        await lowPower.activationSweep()+        #expect(lowPowerSuggester.calls.isEmpty)++        let (hot, _, hotSuggester, hotEnvironment, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        hotEnvironment.thermalState = .serious+        await hot.activationSweep()+        #expect(hotSuggester.calls.isEmpty)+    }++    @Test("Model availability is re-read on every activation")+    func modelAvailabilityIsReReadOnSweep() async {+        let (coordinator, _, suggester, _, client) = makeSUT(+            candidates: [Self.candidate("a.test")],+            availability: .unavailable(reason: "downloading"))+        #expect(coordinator.isModelAvailable == false)++        await coordinator.activationSweep()+        #expect(suggester.calls.isEmpty)++        client.availabilityResult = .available+        await coordinator.activationSweep()+        #expect(coordinator.isModelAvailable)+        #expect(suggester.calls == ["a.test"])+    }++    // MARK: - Invalidation (Req 5.5, Q57)++    @Test("Reconcile asks only about the hostnames the ledger tracks")+    func reconcileAsksAboutTrackedHostnamesOnly() async {+        let (coordinator, mock, _, _, _) = makeSUT(+            candidates: [+                Self.candidate("a.test", capturedAt: 20), Self.candidate("b.test", capturedAt: 10),+            ])+        await coordinator.activationSweep()++        await coordinator.reconcile()+        #expect(mock.lastRuleSuggestionCandidateHostnames == Set(["a.test", "b.test"]))+    }++    @Test("Reconcile does not read the library when nothing is tracked")+    func reconcileIsFreeWhenNothingIsTracked() async {+        let (coordinator, mock, _, _, _) = makeSUT()+        await coordinator.reconcile()+        #expect(mock.ruleSuggestionCandidatesCallCount == 0)+    }++    @Test("A changed candidate row drops the held suggestion and makes the hostname attemptable")+    func reconcileInvalidatesOnFingerprintMismatch() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test", capturedAt: 10)])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        await coordinator.activationSweep()+        #expect(coordinator.held(for: "a.test") != nil)++        // One more capture on the hostname.+        mock.ruleSuggestionCandidatesResult = .success(+            [Self.candidate("a.test", capturedAt: 10, entryCount: 4)])+        await coordinator.reconcile()++        #expect(coordinator.held(for: "a.test") == nil)+        #expect(coordinator.isAttempted("a.test") == false)+        await coordinator.activationSweep()+        #expect(suggester.calls == ["a.test", "a.test"])+    }++    @Test("A memory warning drops held suggestions and reopens their hostnames")+    func memoryWarningClearsTheRun() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        await coordinator.activationSweep()++        coordinator.memoryWarning()++        #expect(coordinator.held(for: "a.test") == nil)+        #expect(coordinator.isAttempted("a.test") == false)+    }++    @Test("A memory warning cancels the attempt in flight and throws its result away")+    func memoryWarningCancelsTheAttemptInFlight() async {+        let (coordinator, _, suggester, environment, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.isGated = true++        async let requested = coordinator.suggestion(for: "a.test", origin: .request)+        await suggester.waitForAttempts(1)+        environment.elapsed = .milliseconds(120)+        coordinator.memoryWarning()+        suggester.openGate()++        // The attempt was computed against state the warning has just dropped,+        // so nothing it returns is held and the hostname stays attemptable+        // (Req 5.6, Q50) — but it is charged for what it ran (Req 5.2).+        #expect(await requested == nil)+        #expect(coordinator.held(for: "a.test") == nil)+        #expect(coordinator.isAttempted("a.test") == false)+        #expect(coordinator.budgetSpent == .milliseconds(120))+    }++    @Test("Reconcile voids the attempt in flight, so its result is discarded")+    func reconcileDiscardsTheInFlightResult() async {+        let (coordinator, mock, suggester, environment, _) = makeSUT(+            candidates: [Self.candidate("a.test", capturedAt: 10)])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.isGated = true++        async let requested = coordinator.suggestion(for: "a.test", origin: .request)+        await suggester.waitForAttempts(1)+        // A capture lands on the hostname while the attempt is running: what it+        // is computing is already about a corpus that no longer exists.+        mock.ruleSuggestionCandidatesResult = .success(+            [Self.candidate("a.test", capturedAt: 10, entryCount: 4)])+        await coordinator.reconcile()+        environment.elapsed = .milliseconds(80)+        suggester.openGate()++        #expect(await requested == nil)+        #expect(coordinator.held(for: "a.test") == nil)+        #expect(coordinator.isAttempted("a.test") == false)+        #expect(coordinator.budgetSpent == .milliseconds(80))+    }++    // MARK: - Delivery (Reqs 5.7, 6.6)++    @Test("A held suggestion is returned without a model call")+    func heldIsReturnedWithoutACall() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        await coordinator.activationSweep()++        let delivered = await coordinator.suggestion(for: "a.test", origin: .open)+        #expect(delivered == Self.suggestion("a.test"))+        #expect(suggester.calls == ["a.test"])+    }++    @Test("An editor open on an already-attempted hostname starts nothing")+    func openIsRefusedWhenAttempted() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        await coordinator.activationSweep()+        #expect(coordinator.isAttempted("a.test"))++        #expect(await coordinator.suggestion(for: "a.test", origin: .open) == nil)+        #expect(suggester.calls == ["a.test"])+    }++    @Test("An open on an already-attempted hostname is refused without reading the library")+    func openRefusedWithoutALibraryRead() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        await coordinator.activationSweep()+        #expect(coordinator.isAttempted("a.test"))+        let reads = mock.ruleSuggestionCandidatesCallCount++        #expect(await coordinator.suggestion(for: "a.test", origin: .open) == nil)++        // Every editor open on such a hostname would otherwise pay the+        // candidate read — a count and a fetch per hostname — only to be told+        // what the ledger already knew.+        #expect(mock.ruleSuggestionCandidatesCallCount == reads)+        #expect(suggester.calls == ["a.test"])+    }++    @Test("An open behind the reader's own request for another hostname is refused for free")+    func openRefusedBehindARequest() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(candidates: [+            Self.candidate("a.test", capturedAt: 20), Self.candidate("b.test", capturedAt: 10),+        ])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.isGated = true++        async let requested = coordinator.suggestion(for: "a.test", origin: .request)+        await suggester.waitForAttempts(1)+        let reads = mock.ruleSuggestionCandidatesCallCount++        // Q55: an open never pre-empts a request, so there is nothing for it to+        // do here — and no library read is needed to establish that.+        #expect(await coordinator.suggestion(for: "b.test", origin: .open) == nil)+        #expect(mock.ruleSuggestionCandidatesCallCount == reads)++        suggester.openGate()+        #expect(await requested == Self.suggestion("a.test"))+        #expect(suggester.calls == ["a.test"])+    }++    @Test("The reader's request starts an attempt even on an attempted hostname")+    func requestStartsWhenAttempted() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        await coordinator.activationSweep()++        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        let delivered = await coordinator.suggestion(for: "a.test", origin: .request)+        #expect(delivered == Self.suggestion("a.test"))+        #expect(suggester.calls == ["a.test", "a.test"])+    }++    @Test("An open on the hostname already being computed attaches to it")+    func openAttachesToAnInFlightAttempt() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.delay = .milliseconds(30)++        async let sweep: Void = coordinator.activationSweep()+        // The editor opens only once the sweep's attempt is in flight, which+        // the attempt itself reports rather than a sleep guessing at it.+        await suggester.waitForAttempts(1)+        async let opened = coordinator.suggestion(for: "a.test", origin: .open)++        await sweep+        #expect(await opened == Self.suggestion("a.test"))+        #expect(suggester.calls == ["a.test"])+    }++    @Test("A request pre-empts another hostname's attempt and waits for it to stop")+    func requestPreemptsAnotherHostname() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test"), Self.candidate("b.test")])+        mock.ruleSuggestionCandidatesResult = .success([+            Self.candidate("a.test", capturedAt: 20), Self.candidate("b.test", capturedAt: 10),+        ])+        suggester.suggestions = ["b.test": Self.suggestion("b.test")]+        suggester.delay = .milliseconds(50)++        async let sweep: Void = coordinator.activationSweep()+        await suggester.waitForAttempts(1)+        let delivered = await coordinator.suggestion(for: "b.test", origin: .request)+        await sweep++        #expect(delivered == Self.suggestion("b.test"))+        // The pre-empted hostname is left attemptable (Q28) and the two+        // attempts never overlapped (Req 5.11).+        #expect(coordinator.isAttempted("a.test") == false)+        #expect(suggester.peakConcurrent == 1)+    }++    @Test("Cancelling the caller does not cancel the attempt")+    func callerCancellationDoesNotCancelTheAttempt() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.delay = .milliseconds(30)++        let caller = Task { await coordinator.suggestion(for: "a.test", origin: .request) }+        await suggester.waitForAttempts(1)+        caller.cancel()+        _ = await caller.value++        // The attempt is the coordinator's, not the caller's: it finishes and+        // its result is held for the next open.+        while coordinator.held(for: "a.test") == nil { await Task.yield() }+        #expect(coordinator.held(for: "a.test") == Self.suggestion("a.test"))+    }++    // MARK: - Resign-active and the budget (Reqs 5.2, 5.3, 5.4)++    @Test("Resigning active cancels a background attempt and leaves it unattempted")+    func resignActiveCancelsBackgroundOnly() async {+        let (coordinator, _, suggester, environment, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.delay = .milliseconds(50)++        async let sweep: Void = coordinator.activationSweep()+        await suggester.waitForAttempts(1)+        environment.elapsed = .milliseconds(250)+        coordinator.resignActive()+        await sweep++        #expect(coordinator.isAttempted("a.test") == false)+        #expect(coordinator.held(for: "a.test") == nil)+        // A cancelled attempt still spends what it ran for (Req 5.2); the+        // suggester returned nothing, so the clock is the only measure.+        #expect(coordinator.budgetSpent == .milliseconds(250))+    }++    @Test("Resigning active leaves a reader-initiated attempt running")+    func resignActiveLeavesRequestsAlone() async {+        let (coordinator, mock, suggester, _, _) = makeSUT()+        mock.ruleSuggestionCandidatesResult = .success([Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        suggester.delay = .milliseconds(30)++        async let requested = coordinator.suggestion(for: "a.test", origin: .request)+        await suggester.waitForAttempts(1)+        coordinator.resignActive()++        #expect(await requested == Self.suggestion("a.test"))+        #expect(coordinator.isAttempted("a.test"))+    }++    @Test("The budget is charged what the attempt reported spending")+    func budgetIsChargedFromModelPhase() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test", capturedAt: 20),+                         Self.candidate("b.test", capturedAt: 10)])+        suggester.modelPhase = .milliseconds(400)++        await coordinator.activationSweep()+        #expect(coordinator.budgetSpent == .milliseconds(800))+    }++    @Test("A timed-out attempt is attempted, and charged what the timeout reported")+    func timeoutIsAttemptedAndCharged() async {+        let (coordinator, _, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.failure = AttemptTimeout(modelPhase: .milliseconds(900))++        await coordinator.activationSweep()++        #expect(coordinator.isAttempted("a.test"))+        #expect(coordinator.held(for: "a.test") == nil)+        #expect(coordinator.budgetSpent == .milliseconds(900))+    }++    @Test("An exhausted budget stops the sweep but not the reader's request")+    func exhaustedBudgetStopsBackgroundOnly() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.modelPhase = RuleSuggestionBounds.runTimeBudget+        await coordinator.activationSweep()+        #expect(suggester.calls == ["a.test"])++        mock.ruleSuggestionCandidatesResult = .success([+            Self.candidate("a.test", capturedAt: 5), Self.candidate("b.test", capturedAt: 10),+        ])+        await coordinator.activationSweep()+        #expect(suggester.calls == ["a.test"])++        suggester.suggestions = ["b.test": Self.suggestion("b.test")]+        #expect(await coordinator.suggestion(for: "b.test", origin: .request) != nil)+        #expect(suggester.calls == ["a.test", "b.test"])+    }++    // MARK: - Dismissal passthrough (Reqs 2.7, 2.8, 6.5)++    @Test("Dismissal is per side and survives invalidation")+    func dismissalIsPerSideAndSurvivesInvalidation() async {+        let (coordinator, mock, suggester, _, _) = makeSUT(+            candidates: [Self.candidate("a.test")])+        suggester.suggestions = ["a.test": Self.suggestion("a.test")]+        await coordinator.activationSweep()++        coordinator.dismiss(hostname: "a.test", side: .title)+        #expect(coordinator.isDismissed(hostname: "a.test", side: .title))+        #expect(coordinator.isDismissed(hostname: "a.test", side: .url) == false)++        mock.ruleSuggestionCandidatesResult = .success(+            [Self.candidate("a.test", entryCount: 9)])+        await coordinator.reconcile()+        #expect(coordinator.isDismissed(hostname: "a.test", side: .title))++        coordinator.clearDismissal(hostname: "a.test", side: .title)+        #expect(coordinator.isDismissed(hostname: "a.test", side: .title) == false)+    }+}

diff --git a/Asterism/AsterismTests/RuleSuggestionLogTests.swift b/Asterism/AsterismTests/RuleSuggestionLogTests.swiftnew file mode 100644index 0000000..3a5737f--- /dev/null+++ b/Asterism/AsterismTests/RuleSuggestionLogTests.swift@@ -0,0 +1,38 @@+import AsterismIntelligence+import Foundation+import Testing+@testable import Asterism++/// The suggestion log's two pure helpers. Everything else in it writes to+/// `OSLog`, which a test cannot read back.+@Suite("RuleSuggestionLog")+struct RuleSuggestionLogTests {++    @Test("A whole number of milliseconds survives the round trip",+          arguments: [0, 1, 250, 999, 1_000, 1_234, 10_000, 60_000] as [Int64])+    func millisecondsRoundTrip(_ milliseconds: Int64) {+        #expect(RuleSuggestionLog.milliseconds(.milliseconds(milliseconds)) == milliseconds)+    }++    @Test("Sub-millisecond remainders truncate rather than round")+    func millisecondsTruncates() {+        #expect(RuleSuggestionLog.milliseconds(.microseconds(1_500)) == 1)+        #expect(RuleSuggestionLog.milliseconds(.microseconds(999)) == 0)+        // The bounds this feature is written in: the attempt timeout and the+        // run budget both read as their plain millisecond counts.+        #expect(RuleSuggestionLog.milliseconds(RuleSuggestionBounds.attemptTimeout) == 10_000)+        #expect(RuleSuggestionLog.milliseconds(RuleSuggestionBounds.runTimeBudget) == 60_000)+    }++    @Test("A failure is described by its type and its value")+    func failureDescription() {+        let error = StubRuleSuggestionModelClientError.contextWindowOverflow+        let described = RuleSuggestionLog.describe(error)++        #expect(described.contains("StubRuleSuggestionModelClientError"))+        #expect(described.contains("contextWindowOverflow"))+        // One spelling, shared with the package so a model client's default+        // `describe(_:)` and this read the same.+        #expect(described == SuggestionFailure.describe(error))+    }+}

diff --git a/Asterism/AsterismTests/UITestLaunchSupportTests.swift b/Asterism/AsterismTests/UITestLaunchSupportTests.swiftindex ee6e1dd..5f89a40 100644--- a/Asterism/AsterismTests/UITestLaunchSupportTests.swift+++ b/Asterism/AsterismTests/UITestLaunchSupportTests.swift@@ -2,6 +2,7 @@ import Foundation import Testing @testable import Asterism import AsterismCore+import AsterismIntelligence  @MainActor @Suite("UI test launch validation")@@ -205,6 +206,33 @@ struct UITestLaunchSupportTests {         }         #expect(!message.isEmpty)     }++    // MARK: - The scripted suggestion client (rule-suggestion)++    @Test("The launch environment picks the scripted model client, or none at all")+    func suggestionClientMapping() {+        let canned = UITestLaunchSupport.suggestionClient(+            environmentProvider: StubProcessEnvironment(+                values: [UITestLaunchSupport.suggestionKey: "canned"]))+        #expect(canned?.availability() == .available)+        #expect((canned as? StubRuleSuggestionModelClient)?.proposal+            == UITestLaunchSupport.cannedSuggestionProposal)++        let unavailable = UITestLaunchSupport.suggestionClient(+            environmentProvider: StubProcessEnvironment(+                values: [UITestLaunchSupport.suggestionKey: "unavailable"]))+        #expect(unavailable?.availability().isAvailable == false)++        // Every production launch, and every UI test that asked for nothing:+        // the on-device client stands, and no stub is substituted for it.+        let unasked = UITestLaunchSupport.suggestionClient(+            environmentProvider: StubProcessEnvironment(values: [:]))+        let unrecognised = UITestLaunchSupport.suggestionClient(+            environmentProvider: StubProcessEnvironment(+                values: [UITestLaunchSupport.suggestionKey: "nonsense"]))+        #expect(unasked == nil)+        #expect(unrecognised == nil)+    } }  private struct StubProcessEnvironment: ProcessEnvironmentProviding {

diff --git a/Asterism/AsterismUITests/ComposedSurfaceUITests.swift b/Asterism/AsterismUITests/ComposedSurfaceUITests.swiftindex d56b82c..3a29795 100644--- a/Asterism/AsterismUITests/ComposedSurfaceUITests.swift+++ b/Asterism/AsterismUITests/ComposedSurfaceUITests.swift@@ -82,6 +82,24 @@ final class ComposedSurfaceUITests: XCTestCase {         XCTFail(message, file: file, line: line)     } +    /// Scrolls the surface until the element is in the tree. A lazy Form does not+    /// instantiate rows below the fold, so "does not exist" and "has not been+    /// scrolled to" look alike; this asks the second question first. The message+    /// is an autoclosure so a diagnosis can be taken at the moment of failure.+    @discardableResult+    private func scrollUntilExists(+        _ element: XCUIElement, _ message: @autoclosure () -> String,+        file: StaticString = #filePath, line: UInt = #line+    ) -> Bool {+        if element.waitForExistence(timeout: 5) { return true }+        for _ in 0..<8 {+            app.swipeUp()+            if element.waitForExistence(timeout: 2) { return true }+        }+        XCTFail(message(), file: file, line: line)+        return false+    }+     /// The URL details are expanded when the editor's own controls are on screen.     private func requireURLEditorExpanded(         _ message: String, file: StaticString = #filePath, line: UInt = #line@@ -362,6 +380,86 @@ final class ComposedSurfaceUITests: XCTestCase {                     "Committing Articles leaves the composed surface")     } +    // MARK: - Rule suggestion (rule-suggestion Reqs 1.1, 2.1, 2.2, 4.1, 6.1)++    /// Relaunches the same seeded scenario with a scripted model client. `setUp`+    /// has already launched it without one, which is what every other test here+    /// wants — a suggestion must be asked for explicitly.+    private func relaunch(withSuggestion mode: String) {+        terminateAndWaitForExit(app)+        app.launchEnvironment["ASTERISM_UI_TEST_SCENARIO"] = "seeded-composed"+        app.launchEnvironment["ASTERISM_UI_TEST_RUN_ID"] = UUID().uuidString+        app.launchEnvironment["ASTERISM_UI_TEST_SUGGESTION"] = mode+        app.launch()+    }++    /// A verified suggestion is applied when the editor opens, wears its marker,+    /// and gives way to the reader's first edit.+    func testCannedSuggestionSeedsTheEditorAndYieldsToAnEdit() {+        relaunch(withSuggestion: "canned")+        openComposedSurfaceViaPill()++        require(any("composed-title-suggested"),+                "A held suggestion opens the title editor already filled and marked",+                timeout: 20)+        require(app.buttons["composed-suggest"],+                "The on-request action is offered while the model is available")++        // Req 2.2: changing the selection retires the marker and leaves an+        // ordinary hand-authored selection behind. Done before the URL+        // assertions below, which scroll away from the chip row.+        app.buttons["composed-title-chip-0"].tap()+        requireGone(any("composed-title-suggested"),+                    "Editing a suggested side removes its marker")+        require(app.buttons["composed-teaching-confirm"],+                "The editor keeps the controls a hand-authored selection has")++        // Req 2.1: the URL side is marked in its own right — the canned proposal+        // identifies the Work in the first path component — and the marker is+        // not hidden by the disclosure the reader closes over it.+        scrollUntilExists(+            any("composed-url-suggested"),+            """+            The suggested URL rule should carry its own marker \+            (disclosure: \(self.any("composed-url-disclosure").exists), \+            editor: \(self.app.buttons["composed-url-path-chip-0"].exists), \+            summary: \(self.any("composed-url-collapsed-summary").exists), \+            clear: \(self.app.buttons["composed-url-clear"].exists))+            """)+        toggleURLDisclosure()+        requireGone(app.buttons["composed-url-path-chip-0"], "Collapsing hides the URL editor")+        scrollUntilExists(+            any("composed-url-suggested"),+            "The URL marker should stay visible while the URL details are collapsed")+    }++    /// Req 4.1: with no model, the surface is exactly what it is today.+    func testModelUnavailableLeavesTheSurfaceUnchanged() {+        relaunch(withSuggestion: "unavailable")+        openComposedSurfaceViaPill()++        XCTAssertFalse(+            any("composed-title-suggested").waitForExistence(timeout: 8),+            "No title suggestion is applied while the model reports itself away")++        // The URL marker has two homes — inside the details and on the collapsed+        // header — so the absence is checked with each of them on screen rather+        // than against a section that is not in the tree at all. The default+        // whole-title selection sources no chapter, so the details open by+        // themselves first.+        requireURLEditorExpanded("The URL details open as the chapter remedy")+        XCTAssertFalse(any("composed-url-suggested").exists,+                       "No URL marker inside the open URL details")+        toggleURLDisclosure()+        requireGone(app.buttons["composed-url-path-chip-0"], "Collapsing hides the URL editor")+        require(any("composed-url-disclosure"), "The collapsed URL header stays on screen")+        XCTAssertFalse(any("composed-url-suggested").exists,+                       "No URL marker on the collapsed URL header either")++        XCTAssertFalse(app.buttons["composed-suggest"].exists,+                       "The on-request action is not offered at all")+    }+     // MARK: - Work detail → Review URL identity → Recalculate (Req 7.1, 7.2)      func testWorkDetailReviewAndRecalculate() {

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0808aea..5334801 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).  ## [Unreleased] +### Added++- **Suggested rules in the composed teaching editor (rule-suggestion,+  T-2156).** On devices where Apple Intelligence is available, the app proposes+  a title rule and a URL rule for an untaught hostname from its captures, using+  the on-device model. Suggestions are computed in the background after the app+  comes to the foreground (bounded depth and time budget, never in Low Power+  Mode or under thermal pressure) and verified against every capture on the+  hostname before they are shown. Opening the editor on such a hostname+  pre-fills the untaught side with the suggestion under a "Suggested" marker;+  a **Suggest** action asks for one on demand; clearing restores the editor+  exactly as it was; a suggestion arriving after you have started editing a+  side leaves that side alone; a side you save differently is not suggested+  again. Nothing is written until you save. Where the model is unavailable, or+  no suggestion verifies, the editor is unchanged and Suggest reports that no+  suggestion is available. The share extension is untouched.+  Internally this adds the `AsterismIntelligence` package product (the first+  `FoundationModels` use in the tree; linked by the app only), a+  `ruleSuggestionCandidates(hostnames:)` read on `LibraryProviding`, and+  diagnostic logging under `subsystem:me.nore.ig.Asterism+  category:RuleSuggestion`. No schema, migration or archive change.+ ### Upgrading  - **Your library migrates to schema V5 the first time you open the app after

diff --git a/CLAUDE.md b/CLAUDE.mdindex c205135..3ed7403 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -40,7 +40,7 @@ overwrites state. A restore is irreversible; a container download is not. Use the `Makefile` for everything. Do not hand-roll `xcodebuild` or `swift test` invocations where a target exists. -- `make test-core` — AsterismCore package tests (host, fast, safe)+- `make test-core` — AsterismCore package tests (host, fast, safe). Since `rule-suggestion` the package has a second product, `AsterismIntelligence` (linked by the app and `AsterismTests` only — never the share extension), and its tests include **one live Apple Intelligence call** that degrades to a `withKnownIssue` when the host has no model available. - `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. **~20 minutes** (1,213 s measured 2026-08-09, including a 165 s release build): 62% of it is the worst-case single-hostname consolidation in `M4ScalePerformanceTests` (5 samples, each paying its own ~40 s divert before a ~40 s measurement) and the Req 10.1 settling pass (10 samples, each re-seeding 1,350 duplicate rows plus an untimed observation pass). The V4→V5 migration measurement is **gone** — `retire-migration-chain` deleted the pass it timed along with the suite. **The target exits 0**, with four accepted breaches reported as `withKnownIssue` known issues rather than failures (Req 10.1's settling pass, Req 5.5's three diagnosis re-derivations); `RUNS=3` therefore completes all three runs. See `specs/retire-migration-chain/verification-run.md` for the numbers and `docs/agent-notes/testing.md` for recording a band.@@ -79,6 +79,14 @@ shipped app. Unit tests must use `Development` — `Personal` has no testability and the `Asterism Personal` scheme deliberately excludes the unit-test bundle for that reason. +### Rule-suggestion diagnostics++The suggestion pipeline logs every attempt, refusal, drop point and settle+(with the model phase in ms) under `subsystem:me.nore.ig.Asterism+category:RuleSuggestion`. Reader content (titles, URLs, proposal text) is+readable in `Development` builds only; reasons and numbers are always readable.+Filter on that in Console.app with the phone selected.+ ## Performance measurement  Measure in release. `swift test` defaults to debug, and the fixtures are guarded

diff --git a/Packages/AsterismCore/Package.swift b/Packages/AsterismCore/Package.swiftindex 759048a..db3153a 100644--- a/Packages/AsterismCore/Package.swift+++ b/Packages/AsterismCore/Package.swift@@ -10,11 +10,21 @@ let package = Package(     ],     products: [         .library(name: "AsterismCore", targets: ["AsterismCore"]),+        .library(name: "AsterismIntelligence", targets: ["AsterismIntelligence"]),         .library(name: "ConstellationKit", targets: ["ConstellationKit"]),         .executable(name: "AsterismStoreTestHelper", targets: ["AsterismStoreTestHelper"]),     ],     targets: [         .target(name: "AsterismCore"),+        // On-device model work: the availability gate, the model client and the+        // pure state around a rule suggestion. It imports `FoundationModels`,+        // which is exactly why it is a separate product: the share extension+        // links `AsterismCore` and must never link the model framework+        // (Req 4.4, rule-suggestion Decision 2).+        .target(+            name: "AsterismIntelligence",+            dependencies: ["AsterismCore"]+        ),         // The Constellation design language: tokens and SwiftUI components.         // Deliberately independent of AsterismCore — Core stays SwiftUI-free,         // and the share extension can import this without importing the store@@ -29,6 +39,10 @@ let package = Package(             dependencies: ["AsterismCore"],             resources: [.copy("Fixtures")]         ),+        .testTarget(+            name: "AsterismIntelligenceTests",+            dependencies: ["AsterismIntelligence"]+        ),         .testTarget(             name: "ConstellationKitTests",             dependencies: ["ConstellationKit"]

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swiftindex 9c59b20..ee9a295 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryProviding.swift@@ -19,6 +19,12 @@ public protocol LibraryProviding: Sendable {     /// appearing twice (Q24) — row-level duplication is Library Check's subject.     func sites() async throws -> [SiteSnapshot] +    /// One row per hostname for the rule-suggestion sweep and its invalidation+    /// pass (Reqs 1.6, 5.1, 5.5, Q37): Site mode, live rule versions, capture+    /// count and newest capture. `nil` reads every hostname; a set reads only+    /// those.+    func ruleSuggestionCandidates(hostnames: Set<String>?) async throws -> [RuleSuggestionCandidate]+     /// The configured work-type list for the settings screen and the editor's     /// picker: active entries, plus the removed ones works still use (Reqs 1.1,     /// 1.7). One row per identity — duplicate rows are folded, merged entries

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RuleSuggestion.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RuleSuggestion.swiftnew file mode 100644index 0000000..00d50a5--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+RuleSuggestion.swift@@ -0,0 +1,117 @@+import Foundation+import SwiftData++// The rule-suggestion candidate read (Reqs 1.6, 5.1, 5.5, Q37).+//+// One row per hostname carrying exactly what the suggestion coordinator needs+// and nothing that would make it expensive: the sweep picks auto-eligible+// hostnames from it (not in articles mode, at least one capture, a rule+// missing on one side) and orders them by most recent capture, and+// `reconcile` compares the same fields to the fingerprint it recorded when an+// attempt started. Neither `sites()` nor `RecentPresentation` can serve: the+// first carries no URL-rule presence or capture recency, the second is capped+// and would miss older untaught sites.++extension LibraryRepository {++    /// Candidate rows for the rule-suggestion sweep and its invalidation pass.+    ///+    /// `hostnames == nil` is the sweep's read: every hostname in the store.+    /// A set is `reconcile`'s read: only the hostnames the ledger tracks. An+    /// empty set answers immediately, without taking the lock — the ledger+    /// tracks nothing for most of a run.+    ///+    /// Rows come back sorted by hostname, so a caller comparing two reads+    /// compares them in a stable order; recency ordering is the sweep's own+    /// business.+    public func ruleSuggestionCandidates(+        hostnames: Set<String>?+    ) async throws -> [RuleSuggestionCandidate] {+        if let hostnames, hostnames.isEmpty { return [] }+        return try await withLockedContext(+            mode: .shared, operation: "reading rule suggestion candidates"+        ) { context in+            let rows: [Site]+            if let hostnames {+                let wanted = Array(hostnames)+                rows = try context.fetch(+                    FetchDescriptor<Site>(predicate: #Predicate { wanted.contains($0.hostname) }))+            } else {+                rows = try context.fetch(FetchDescriptor<Site>())+            }+            // The same winner rule every whole-store pass uses: a duplicated+            // hostname is Library Check's subject, not this read's, and a+            // suggestion is about the row a teach would write to.+            return try SiteResolutionOrder.winnersByHostname(rows)+                .values+                .compactMap { site -> RuleSuggestionCandidate? in+                    // A mode outside the closed set has no honest row here, the+                    // same judgement `sites()` makes. Coercing it to `.untaught`+                    // would make it auto-eligible and propose fiction rules for+                    // a state nothing here understands (Q15). Its absence reads+                    // as a mismatch to `reconcile`, which is the safe direction.+                    guard let mode = SiteMode(rawValue: site.modeRaw) else { return nil }+                    return try Self.ruleSuggestionCandidate(+                        site, mode: mode, context: context)+                }+                .sorted { $0.hostname < $1.hostname }+        }+    }++    /// One hostname's row. `Site.entries` is never traversed — faulting every+    /// Entry for a hostname is what that relationship stays internal to prevent+    /// (Q17) — so the two capture facts come from two scoped Entry reads:+    /// a count, and the newest row alone. SwiftData has no aggregate max.+    private static func ruleSuggestionCandidate(+        _ site: Site, mode: SiteMode, context: ModelContext+    ) throws -> RuleSuggestionCandidate {+        let hostname = site.hostname+        let entryCount = try context.fetchCount(+            FetchDescriptor<Entry>(predicate: #Predicate { $0.hostname == hostname }))+        var newest = FetchDescriptor<Entry>(+            predicate: #Predicate { $0.hostname == hostname },+            sortBy: [SortDescriptor(\.firstCapturedAt, order: .reverse)])+        newest.fetchLimit = 1+        return RuleSuggestionCandidate(+            hostname: hostname,+            siteMode: mode,+            titleRuleVersion: site.activePattern?.version,+            urlRuleVersion: site.urlRuleValues.first(where: \.isCurrent)?.version,+            entryCount: entryCount,+            latestCaptureAt: try context.fetch(newest).first?.firstCapturedAt)+    }+}++/// What the rule-suggestion sweep sees of one hostname (Reqs 1.6, 5.1, 5.5).+///+/// Deliberately five facts and no rule content: eligibility and invalidation+/// are the only questions it answers, and the attempt itself re-reads the+/// hostname through `projectComposedTeaching`.+public struct RuleSuggestionCandidate: Equatable, Sendable {+    public let hostname: String+    public let siteMode: SiteMode+    /// Version of the Site's active title pattern; nil where it has none.+    public let titleRuleVersion: Int?+    /// Version of the Site's current URL rule; nil where it has none.+    public let urlRuleVersion: Int?+    public let entryCount: Int+    /// The newest capture's `firstCapturedAt`; nil where the hostname has no+    /// captures.+    public let latestCaptureAt: Date?++    public init(+        hostname: String,+        siteMode: SiteMode,+        titleRuleVersion: Int?,+        urlRuleVersion: Int?,+        entryCount: Int,+        latestCaptureAt: Date?+    ) {+        self.hostname = hostname+        self.siteMode = siteMode+        self.titleRuleVersion = titleRuleVersion+        self.urlRuleVersion = urlRuleVersion+        self.entryCount = entryCount+        self.latestCaptureAt = latestCaptureAt+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/FoundationRuleSuggestionModelClient.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/FoundationRuleSuggestionModelClient.swiftnew file mode 100644index 0000000..dd44a24--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/FoundationRuleSuggestionModelClient.swift@@ -0,0 +1,168 @@+import Foundation+import FoundationModels++/// The on-device model, behind the suggester's seam. Everything it does runs on+/// this device: no capture title or URL leaves it (Req 4.3).+///+/// One `LanguageModelSession` per call. There is no conversation to keep — each+/// hostname is an independent question — and a fresh session keeps the token+/// window to the instructions plus one corpus.+public struct FoundationRuleSuggestionModelClient: RuleSuggestionModelClient {+    public init() {}++    // MARK: - Availability (Req 4.1, Q41)++    public func availability() -> ModelAvailability {+        Self.availability(from: SystemLanguageModel.default.availability)+    }++    /// The reason is kept for logging only: Req 4.1 forbids telling the reader+    /// anything about the model being absent.+    static func availability(from availability: SystemLanguageModel.Availability) -> ModelAvailability {+        switch availability {+        case .available:+            .available+        case .unavailable(let reason):+            switch reason {+            case .deviceNotEligible: .unavailable(reason: "deviceNotEligible")+            case .appleIntelligenceNotEnabled: .unavailable(reason: "appleIntelligenceNotEnabled")+            case .modelNotReady: .unavailable(reason: "modelNotReady")+            @unknown default: .unavailable(reason: "unknown")+            }+        }+    }++    // MARK: - The call++    public func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal {+        let session = LanguageModelSession(instructions: Self.instructions)+        // `Response<Content>` is not Sendable, so only its content leaves here.+        let response = try await session.respond(to: Self.prompt(for: corpus),+                                                 generating: RuleProposal.self,+                                                 options: Self.generationOptions)+        return response.content+    }++    /// Greedy sampling: the same corpus must yield the same proposal, or a+    /// suggestion the reader dismissed could come back different next launch+    /// (Q24).+    static let generationOptions = GenerationOptions(sampling: .greedy)++    /// Whether an error is the model saying the input was too long. The+    /// suggester answers it by halving the corpus and retrying, which is why+    /// the case has to survive as a type rather than a message (Req 3.7).+    ///+    /// It is the client's job rather than the suggester's so that nothing above+    /// this seam has to import `FoundationModels`.+    public func isContextWindowOverflow(_ error: any Error) -> Bool {+        guard let generation = error as? LanguageModelSession.GenerationError else { return false }+        if case .exceededContextWindowSize = generation { return true }+        return false+    }++    /// The failure as the log should carry it. `GenerationError`'s cases are+    /// the difference between "the model refused this corpus" and "Apple+    /// Intelligence is not there", and the case name is the only part of that+    /// which reads at a glance — so it is named here, where the framework is+    /// imported, rather than left to `String(describing:)` above the seam.+    public func describe(_ error: any Error) -> String {+        guard let generation = error as? LanguageModelSession.GenerationError else {+            return SuggestionFailure.describe(error)+        }+        return "GenerationError.\(Self.caseName(of: generation)): \(String(describing: generation))"+    }++    static func caseName(of error: LanguageModelSession.GenerationError) -> String {+        switch error {+        case .exceededContextWindowSize: "exceededContextWindowSize"+        case .assetsUnavailable: "assetsUnavailable"+        case .guardrailViolation: "guardrailViolation"+        case .unsupportedGuide: "unsupportedGuide"+        case .unsupportedLanguageOrLocale: "unsupportedLanguageOrLocale"+        case .decodingFailure: "decodingFailure"+        case .rateLimited: "rateLimited"+        case .concurrentRequests: "concurrentRequests"+        case .refusal: "refusal"+        @unknown default: "unknown"+        }+    }++    // MARK: - Prompting++    /// Fixed instructions: the task, the verbatim-copying rule that makes+    /// `ProposalLocator` able to find the answers, and three worked examples —+    /// the third an opaque address whose chapter lives only in the title+    /// (Decision 1).+    static let instructions = """+    You are given the titles and web addresses of pages captured from one \+    website. Each page is one chapter or part of a longer story that is \+    published in instalments.++    Answer about the FIRST title and the FIRST address only, with four pieces \+    of text:+    - workName: the part of the first title that names the story.+    - chapterText: the part of the first title that identifies the chapter or \+    part, or empty if the title has none. It is often nothing more than a \+    number or a decimal such as 12, 1.00 or 4.3, frequently at the very start \+    of the title.+    - urlWorkIdentity: the part of the first address that identifies the story.+    - urlSequenceText: the part of the first address that identifies the \+    chapter or its number, or empty if the address has none.++    Copy text exactly as it appears, character for character. Do not translate \+    it, reword it, reorder it, correct its spelling, or change its punctuation, \+    spacing or capitalisation. If a value does not appear in the first title or \+    the first address, answer with empty text.++    workName and chapterText come only from the first title; urlWorkIdentity \+    and urlSequenceText come only from the first address. Judge the title and \+    the address separately: an address that is just a bare number or code names \+    neither the story nor its chapter, so both address answers are empty — but \+    the title still gets its own workName and chapterText. The website's own \+    domain name is never urlWorkIdentity. Site names, verbs \+    such as "Read", and separators are not part of the story's name.++    The later examples are there only to show which parts change from chapter \+    to chapter. Never answer with text taken from them.++    Example A+    1. title: Sylver Seeker - Chapter 12: The Long Road+       url: https://example.net/novel/sylver-seeker/chapter-12+    2. title: Sylver Seeker - Chapter 11: Ashes+       url: https://example.net/novel/sylver-seeker/chapter-11+    Answer: workName "Sylver Seeker", chapterText "Chapter 12: The Long Road", \+    urlWorkIdentity "sylver-seeker", urlSequenceText "12".++    Example B+    1. title: Deep Blue Sky+       url: https://stories.example.com/read?story=deep-blue-sky&part=4+    2. title: Deep Blue Sky+       url: https://stories.example.com/read?story=deep-blue-sky&part=3+    Answer: workName "Deep Blue Sky", chapterText "", urlWorkIdentity \+    "deep-blue-sky", urlSequenceText "4".++    Example C+    1. title: Read Episode 7 - Moonlit Harbour | Pagelight+       url: https://pagelight.example/en/chapters/58210034+    2. title: Read Episode 6 - Moonlit Harbour | Pagelight+       url: https://pagelight.example/en/chapters/58209871+    Answer: workName "Moonlit Harbour", chapterText "Episode 7", \+    urlWorkIdentity "", urlSequenceText "".+    """++    /// The corpus as the model sees it: numbered examples, anchor first, so+    /// "the first title" in the instructions is unambiguous.+    static func prompt(for corpus: SuggestionCorpus) -> String {+        let examples = corpus.examples.enumerated().map { index, example in+            """+            \(index + 1). title: \(example.title)+               url: \(example.rawURL)+            """+        }+        return """+        Pages captured from \(corpus.hostname):++        \(examples.joined(separator: "\n"))+        """+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/ProposalLocator.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/ProposalLocator.swiftnew file mode 100644index 0000000..27604e2--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/ProposalLocator.swift@@ -0,0 +1,54 @@+import Foundation++/// Turns a substring the model claimed to have copied into a span over the text+/// it was copied from (Decision 1).+///+/// Constrained decoding guarantees the *shape* of a `RuleProposal`, not that a+/// value occurs in the input, so every field is re-found here. A field is+/// accepted only when it occurs exactly once: a repeated substring — a chapter+/// number that also appears in the work name — has no single span, and guessing+/// one would put a span the reader never sanctioned into a rule (Req 3.1).+public enum ProposalLocator {+    /// Where a field sits in one piece of text. `absent` and `ambiguous` are+    /// both "no span", but a caller searching several candidate texts has to+    /// tell them apart: absent in this one means keep looking, ambiguous means+    /// the field is unusable whatever the others say.+    public enum Placement: Sendable, Equatable {+        case unique(Range<Int>)+        case absent+        case ambiguous+    }++    /// Where `text` occurs in `source`. Empty text is `absent` in every source:+    /// "no chapter" is spelled as an empty field (Q39), never as a span.+    ///+    /// Offsets count `Character`s so they line up with+    /// `ComposedTeachingPresentation.TitleSegment.range`, which the assembler+    /// feeds them to. Comparison is `Character` equality, so a precomposed+    /// needle matches a decomposed source, and a multi-scalar emoji counts as+    /// one position.+    public static func place(_ text: String, in source: String) -> Placement {+        let needle = Array(text)+        guard !needle.isEmpty else { return .absent }+        let haystack = Array(source)+        guard needle.count <= haystack.count else { return .absent }++        var match: Range<Int>?+        // Overlapping occurrences count separately: "aa" in "aaa" is ambiguous.+        for start in 0 ... (haystack.count - needle.count) {+            guard haystack[start ..< start + needle.count].elementsEqual(needle) else { continue }+            if match != nil { return .ambiguous }+            match = start ..< start + needle.count+        }+        guard let match else { return .absent }+        return .unique(match)+    }++    /// The character range of `text` in `source`, or nil when `text` is empty,+    /// absent, or occurs more than once — the answer a caller with one text to+    /// search wants.+    public static func locate(_ text: String, in source: String) -> Range<Int>? {+        guard case .unique(let range) = place(text, in: source) else { return nil }+        return range+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/RuleProposal.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleProposal.swiftnew file mode 100644index 0000000..061929b--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleProposal.swift@@ -0,0 +1,178 @@+import Foundation+import FoundationModels+import Synchronization++/// What the model returns: the *text* of each field, copied out of the anchor+/// capture, never an offset.+///+/// Constrained decoding guarantees the shape but not that a value is a+/// substring, so `ProposalLocator` re-finds each one in the anchor and drops+/// anything it cannot place uniquely (Decision 1). Empty means "none" — an+/// optional field would cost schema room inside the 4,096-token window for+/// nothing (Q39).+///+/// The declaration order is deliberate: work before chapter, title before URL.+@Generable+public struct RuleProposal: Sendable, Equatable {+    @Guide(description: "Exact text from the first title that names the work, copied verbatim")+    public var workName: String++    @Guide(description: "Exact text from the first title that identifies the chapter or part, verbatim, or empty if none")+    public var chapterText: String++    @Guide(description: "Exact text from the first URL that identifies the work, verbatim")+    public var urlWorkIdentity: String++    @Guide(description: "Exact text from the first URL that identifies the chapter or sequence, verbatim, or empty if none")+    public var urlSequenceText: String++    public init(workName: String = "", chapterText: String = "",+                urlWorkIdentity: String = "", urlSequenceText: String = "") {+        self.workName = workName+        self.chapterText = chapterText+        self.urlWorkIdentity = urlWorkIdentity+        self.urlSequenceText = urlSequenceText+    }+}++/// The seam between the suggester and the on-device model. Everything above it+/// is testable on the host without Apple Intelligence being present.+public protocol RuleSuggestionModelClient: Sendable {+    /// Re-read on every activation: `.modelNotReady` is transient (Q41).+    func availability() -> ModelAvailability+    func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal++    /// Whether an error is this client saying the input was too long. The+    /// suggester answers it by halving the corpus and retrying (Req 3.7), and+    /// asks the client because only the client knows what its own failures look+    /// like — the suggester must never have to name a concrete client or import+    /// `FoundationModels` to find out.+    func isContextWindowOverflow(_ error: any Error) -> Bool++    /// A loggable account of a failure from this client, for the same reason:+    /// naming the *case* of a framework error takes the framework's own types,+    /// and only the client has them.+    func describe(_ error: any Error) -> String+}++extension RuleSuggestionModelClient {+    /// A client whose model has no context limit worth retrying against never+    /// overflows.+    public func isContextWindowOverflow(_ error: any Error) -> Bool { false }++    /// The type and the value: as much as a client that knows nothing special+    /// about its own errors can say.+    public func describe(_ error: any Error) -> String {+        SuggestionFailure.describe(error)+    }+}++// The stub is a test double, and the same gate the package's other fixtures+// carry (`M4PerformanceFixture`) keeps it out of a shipping build: a release+// binary has no business carrying a scripted model client that answers+// `propose` with whatever it was handed.+#if DEBUG || ASTERISM_PERFORMANCE_TESTING++/// A model client that returns what it was told to, for tests and for the UI+/// test launch environment.+///+/// Two ways to script it. The single canned `proposal`/`error` answers every+/// call the same way; `results`, when non-empty, is consumed one entry per call+/// with the last entry repeating, which is what a halve-then-succeed sequence+/// needs. Either way `recorder` keeps every corpus `propose` was given, so a+/// test can assert on both the count and the shrinking context.+public struct StubRuleSuggestionModelClient: RuleSuggestionModelClient {+    /// One scripted answer. The failure is constrained to `Sendable` so the+    /// script can cross isolation domains with the stub.+    public typealias ScriptedResult = Result<RuleProposal, any Error & Sendable>++    /// The stub's only mutable state. It lives behind a lock in a reference+    /// type so that copies of the (value-typed, `Sendable`) stub share one log+    /// and one position in the script.+    public final class Recorder: Sendable {+        private struct State {+            var corpora: [SuggestionCorpus] = []+            var nextResult = 0+        }++        private let state = Mutex(State())++        public init() {}++        /// Every corpus `propose` was called with, in order.+        public var recordedCorpora: [SuggestionCorpus] { state.withLock { $0.corpora } }+        public var callCount: Int { state.withLock { $0.corpora.count } }++        public func reset() { state.withLock { $0 = State() } }++        /// Logs the call and returns which scripted result it should get,+        /// clamped so the last entry repeats. Nil when the script is empty.+        fileprivate func record(_ corpus: SuggestionCorpus, scriptLength: Int) -> Int? {+            state.withLock { state in+                state.corpora.append(corpus)+                defer { state.nextResult += 1 }+                guard scriptLength > 0 else { return nil }+                return min(state.nextResult, scriptLength - 1)+            }+        }+    }++    public var availabilityResult: ModelAvailability+    public var proposal: RuleProposal?+    public var error: (any Error & Sendable)?+    /// Sleep before answering, so a test can exercise timeout and cancellation.+    public var delay: Duration?+    /// Answers consumed in order, the last one repeating. Takes precedence over+    /// `proposal` and `error` when non-empty.+    public var results: [ScriptedResult]+    public let recorder: Recorder++    public init(availability: ModelAvailability = .available,+                proposal: RuleProposal? = nil,+                error: (any Error & Sendable)? = nil,+                delay: Duration? = nil,+                results: [ScriptedResult] = [],+                recorder: Recorder = Recorder()) {+        self.availabilityResult = availability+        self.proposal = proposal+        self.error = error+        self.delay = delay+        self.results = results+        self.recorder = recorder+    }++    public func availability() -> ModelAvailability { availabilityResult }++    public func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal {+        // Recorded before the delay: a call that is cancelled or times out still+        // happened, and a test asserting "no model call" must see it.+        let scripted = recorder.record(corpus, scriptLength: results.count)+        if let delay {+            try await Task.sleep(for: delay)+        }+        if let scripted {+            return try results[scripted].get()+        }+        if let error {+            throw error+        }+        guard let proposal else {+            throw StubRuleSuggestionModelClientError.noCannedProposal+        }+        return proposal+    }++    public func isContextWindowOverflow(_ error: any Error) -> Bool {+        (error as? StubRuleSuggestionModelClientError) == .contextWindowOverflow+    }+}++public enum StubRuleSuggestionModelClientError: Error, Sendable, Equatable {+    /// The stub was asked for a proposal it was never given.+    case noCannedProposal+    /// The stub's stand-in for the model refusing an over-long input, so a test+    /// can drive Req 3.7's halve-and-retry without `FoundationModels`.+    case contextWindowOverflow+}++#endif

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionBounds.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionBounds.swiftnew file mode 100644index 0000000..69b3692--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionBounds.swift@@ -0,0 +1,31 @@+import Foundation++/// Every tunable this feature has, in one place, so the latency spike can+/// revise them without hunting through call sites (Q11, Q17, Q22, Q24).+///+/// All five values are provisional until `RuleSuggester.attempt(hostname:)` has+/// been measured on the `Personal` build; see `specs/rule-suggestion/prerequisites.md`.+public enum RuleSuggestionBounds {+    /// How many auto-eligible hostnames one activation sweep attempts (Q17).+    /// Positions 1–3 carry nearly all the value: the hostname the reader opens+    /// is almost always the one whose capture just landed.+    public static let backgroundSweepDepth = 3++    /// The cumulative wall-clock model time one app run may spend (Q17, Q31).+    /// Exhaustion stops the background sweep only — on-open and on-request+    /// attempts are reader-initiated and still start.+    public static let runTimeBudget: Duration = .seconds(60)++    /// How long one hostname's attempt may run, measured from the model request+    /// being issued (Q11). A stuck model call cannot pin resources for longer.+    public static let attemptTimeout: Duration = .seconds(10)++    /// How long after the editor appears a late result may still be applied+    /// (Q22). Past it the result is held and surfaced through the on-request+    /// action instead of mutating a selection the reader is already reading.+    public static let autoApplyWindow: Duration = .seconds(2)++    /// How many of a hostname's captures the model is shown, newest first+    /// (Q24). The newest is the anchor; the rest are context.+    public static let captureSampleCount = 5+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionLedger.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionLedger.swiftnew file mode 100644index 0000000..484918a--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionLedger.swift@@ -0,0 +1,377 @@+import Foundation++/// The device conditions the sweep is gated on (Req 5.3) and whether the app is+/// active. They are passed in rather than read here so the ledger stays a pure+/// value type the host tests can drive.+public struct RuleSuggestionEnvironment: Sendable, Equatable {+    public var isActive: Bool+    public var isLowPowerMode: Bool+    public var thermalState: ProcessInfo.ThermalState++    public init(isActive: Bool = true, isLowPowerMode: Bool = false,+                thermalState: ProcessInfo.ThermalState = .nominal) {+        self.isActive = isActive+        self.isLowPowerMode = isLowPowerMode+        self.thermalState = thermalState+    }++    /// Req 5.3's gate: serious or critical stops the sweep, fair does not.+    var isThermallyConstrained: Bool {+        thermalState.rawValue >= ProcessInfo.ThermalState.serious.rawValue+    }+}++/// Why the ledger refused to start an attempt. Carried out of `start` rather+/// than re-derived by the caller: the state that decided it can have moved on+/// by the time the caller asks, and a log line that names a different reason+/// than the one applied is worse than no log line.+public enum RefusalReason: Sendable, Equatable, CustomStringConvertible {+    /// Attempted this run already (Req 5.7).+    case attempted+    /// The reader rejected both sides for this hostname (Reqs 2.8, 6.5).+    case bothSidesDismissed+    /// Another hostname's attempt holds the floor and this origin cannot+    /// pre-empt it (Req 5.11, Q55).+    case inFlight(hostname: String)+    /// The run's cumulative model-time budget is spent (Req 5.2, Q31).+    case budgetExhausted+    case notActive+    case lowPower+    case thermallyConstrained++    public var description: String {+        switch self {+        case .attempted: "already attempted this run"+        case .bothSidesDismissed: "both sides dismissed"+        case .inFlight(let hostname): "attempt in flight for \(hostname)"+        case .budgetExhausted: "run budget spent"+        case .notActive: "app not active"+        case .lowPower: "low power mode"+        case .thermallyConstrained: "thermally constrained"+        }+    }+}++/// What the caller must do about a requested attempt.+public enum AttemptStart: Sendable, Equatable {+    /// Run the attempt: the ledger has recorded it as in flight.+    case start+    /// An attempt for this hostname is already running; await its result.+    case attach+    /// Do nothing, for the reason the ledger actually applied.+    case refuse(RefusalReason)+    /// Cancel the running attempt for this hostname, settle it, then ask again.+    /// The ledger deliberately does not swap the in-flight record itself: the+    /// new attempt may not start until the cancelled one has terminated+    /// (Req 5.11).+    case preempt(hostname: String)++    /// The reason, for a caller that only wants to log it.+    public var refusalReason: RefusalReason? {+        guard case .refuse(let reason) = self else { return nil }+        return reason+    }+}++/// How an attempt ended. The distinction that matters is whether the hostname+/// counts as attempted: a timeout does, a cancellation the app itself caused+/// does not (Q28, Q45). Every ending charges the budget (Req 5.2).+public enum AttemptSettlement: Sendable, Equatable {+    case suggestion(RuleSuggestion)+    /// Settled with nothing to show: no valid suggestion, or the model failed.+    case noSuggestion+    case timedOut+    case cancelled+}++/// Every piece of per-run state this feature keeps, and the rules for moving+/// between its states. Pure and value-typed: the coordinator owns the `Task`s,+/// the clock and the library, the ledger owns only the bookkeeping.+///+/// Nothing here is ever written to disk — an app run is the whole lifetime.+public struct RuleSuggestionLedger: Sendable, Equatable {+    public struct InFlight: Sendable, Equatable {+        public let hostname: String+        public let origin: Origin+        /// Set when the corpus this attempt was computed against went away+        /// under it (`invalidate`, `reconcile`, memory warning). The attempt is+        /// still running — the coordinator owns the `Task` — but whatever it+        /// returns is about a corpus that no longer exists, so `settle` throws+        /// the result away instead of holding it (Reqs 5.5, 5.6).+        public private(set) var voided = false++        public init(hostname: String, origin: Origin, voided: Bool = false) {+            self.hostname = hostname+            self.origin = origin+            self.voided = voided+        }++        fileprivate mutating func void() { voided = true }+    }++    public private(set) var held: [String: RuleSuggestion] = [:]+    public private(set) var attempted: Set<String> = []+    public private(set) var dismissed: [String: Set<Side>] = [:]+    public private(set) var inFlight: InFlight?+    public private(set) var budgetSpent: Duration = .zero+    public private(set) var fingerprints: [String: CorpusFingerprint] = [:]++    /// The sweep that may still start attempts, if any. `resignActive` and+    /// pre-emption clear it: this is the sweep's **stop signal**.+    public private(set) var permittedSweep: Int?+    /// The sweep coroutine that has begun and not yet ended. This is the+    /// **single-instance guard**, and it is deliberately not the same thing as+    /// the stop signal: a stopped sweep is still running until it notices, and+    /// starting a second one under it would put two sweeps in the same loop.+    public private(set) var runningSweep: Int?+    private var sweepGenerations = 0++    public init() {}++    // MARK: - Reads++    public func held(for hostname: String) -> RuleSuggestion? { held[hostname] }++    public func isAttempted(_ hostname: String) -> Bool { attempted.contains(hostname) }++    public func isDismissed(hostname: String, side: Side) -> Bool {+        dismissed[hostname]?.contains(side) ?? false+    }++    /// Exhaustion stops the background sweep only (Q31).+    public var budgetExhausted: Bool { budgetSpent >= RuleSuggestionBounds.runTimeBudget }++    /// Whether an `.open` start is already decided against, on state the ledger+    /// holds. `start` applies it, and the coordinator asks *before* the library+    /// read that a start would otherwise need: an editor opening on a hostname+    /// nothing can be done for must not pay for a candidate row to be told so.+    public func refusesOpen(hostname: String) -> Bool {+        openRefusal(hostname: hostname) != nil+    }++    /// The same decision with the reason attached, for the coordinator's log.+    public func openRefusal(hostname: String) -> RefusalReason? {+        // A start for the hostname already running attaches instead (Q16).+        if let inFlight, inFlight.hostname == hostname, !inFlight.voided { return nil }+        // Attempted this run: no second automatic attempt (Req 5.7).+        if attempted.contains(hostname) { return .attempted }+        // An open never pre-empts the reader's own request, so behind one there+        // is nothing left for it to do (Q55).+        if let inFlight, inFlight.origin == .request {+            return .inFlight(hostname: inFlight.hostname)+        }+        // Both sides rejected this run: the automatic path would apply neither+        // (Req 2.8), so the attempt would be a model call spent on nothing.+        return isFullyDismissed(hostname) ? .bothSidesDismissed : nil+    }++    /// Whether the reader has rejected everything an attempt could offer this+    /// hostname. Such a hostname is worth no model call on any automatic path:+    /// `invalidate` keeps dismissals by design (Q18), so a corpus change must+    /// not put it back in front of the sweep.+    public func isFullyDismissed(_ hostname: String) -> Bool {+        Side.allCases.allSatisfy { isDismissed(hostname: hostname, side: $0) }+    }++    /// The hostnames `reconcile` has to ask the library about.+    public var trackedHostnames: Set<String> {+        var tracked = Set(held.keys)+        tracked.formUnion(attempted)+        if let inFlight { tracked.insert(inFlight.hostname) }+        return tracked+    }++    // MARK: - Sweep++    /// Whether the sweep may still start attempts. Read for its own sake; a+    /// sweep asks `isSweeping(generation:)` about *itself*, because a sweep+    /// still running after its stop signal must not be revived by a later one.+    public var sweepActive: Bool { permittedSweep != nil }++    /// The token for this sweep, or nil when a sweep coroutine is still+    /// running: one activation sweep at a time (Req 5.1).+    ///+    /// The token exists because the two things `sweepActive` used to mean have+    /// to be told apart. A sweep that `resignActive` stopped keeps running+    /// until its awaited attempt returns; without a generation, its `endSweep`+    /// would switch off whichever sweep had started in the meantime, and that+    /// sweep would abort having attempted nothing.+    @discardableResult+    public mutating func beginSweep() -> Int? {+        guard runningSweep == nil else { return nil }+        sweepGenerations += 1+        runningSweep = sweepGenerations+        permittedSweep = sweepGenerations+        return sweepGenerations+    }++    /// Whether *this* sweep may still start attempts (Req 5.3).+    public func isSweeping(generation: Int) -> Bool { permittedSweep == generation }++    /// Ends the sweep the token identifies. A token from a sweep that has+    /// already ended is stale and ends nothing.+    public mutating func endSweep(generation: Int) {+        guard runningSweep == generation else { return }+        runningSweep = nil+        if permittedSweep == generation { permittedSweep = nil }+    }++    /// The stop signal on its own: the running coroutine is left alone, and+    /// only it can end the sweep.+    private mutating func stopSweep() { permittedSweep = nil }++    // MARK: - Attempts++    /// The fingerprint is required: it is what `reconcile` compares the next+    /// candidate row against, and a missing one would read as "nothing known"+    /// and invalidate the hostname on the very next reconcile.+    public mutating func start(hostname: String, origin: Origin,+                               fingerprint: CorpusFingerprint,+                               environment: RuleSuggestionEnvironment) -> AttemptStart {+        // Whatever asked for it, the work is already being done (Q16) — unless+        // it has been voided, in which case its answer is already worthless and+        // attaching would hand the caller nothing.+        if let inFlight, inFlight.hostname == hostname, !inFlight.voided { return .attach }++        switch origin {+        case .background:+            // In the order the sweep would hit them, each carrying the reason+            // the caller logs.+            if attempted.contains(hostname) { return .refuse(.attempted) }+            // Req 2.8 for the automatic path: a hostname the reader rejected on+            // both sides is worth neither a sweep slot nor the budget, and a+            // corpus change must not hand it one back (Q18).+            if isFullyDismissed(hostname) { return .refuse(.bothSidesDismissed) }+            if budgetExhausted { return .refuse(.budgetExhausted) }+            if let inFlight { return .refuse(.inFlight(hostname: inFlight.hostname)) }+            if !environment.isActive { return .refuse(.notActive) }+            if environment.isLowPowerMode { return .refuse(.lowPower) }+            if environment.isThermallyConstrained { return .refuse(.thermallyConstrained) }++        case .open:+            // Everything an open can be refused for without the library: a+            // hostname attempted this run, both sides rejected, or the reader's+            // own request holding the floor (Reqs 5.7, 2.8, Q55).+            if let reason = openRefusal(hostname: hostname) { return .refuse(reason) }+            if let inFlight {+                // The reader's hostname must not wait behind an unrelated job+                // (Q23); a request outranks an open, and `refusesOpen` has+                // already turned that case away.+                stopSweep()+                return .preempt(hostname: inFlight.hostname)+            }++        case .request:+            // Req 6.6: regardless of prior attempts, and ahead of anything else.+            if let inFlight {+                stopSweep()+                return .preempt(hostname: inFlight.hostname)+            }+        }++        inFlight = InFlight(hostname: hostname, origin: origin)+        fingerprints[hostname] = fingerprint+        return .start+    }++    public mutating func settle(hostname: String, _ settlement: AttemptSettlement,+                                modelPhase: Duration) {+        // Every attempt spends what it spent, including the pre-empted ones+        // (Req 5.2).+        budgetSpent += modelPhase+        let wasVoided = inFlight?.hostname == hostname && inFlight?.voided == true+        if inFlight?.hostname == hostname { inFlight = nil }++        // A voided attempt was computed against a corpus that has since+        // changed, so its answer is discarded whatever it says, and the+        // hostname stays attemptable — exactly a `.cancelled` ending+        // (Reqs 5.4, 5.5, 5.6).+        guard !wasVoided else { return }++        switch settlement {+        case .suggestion(let suggestion):+            // A suggestion always belongs to the hostname it was asked about.+            // A mismatch means the coordinator crossed two attempts, and+            // holding it anyway would file one site's rule under another and+            // offer it to the reader; that is worth a crash, not a silent+            // wrong answer.+            precondition(suggestion.hostname == hostname,+                         "settled \(suggestion.hostname) against \(hostname)")+            attempted.insert(hostname)+            // Only a settled attempt with at least one side is held; an empty+            // suggestion is a settled attempt with nothing to show.+            if !suggestion.isEmpty { held[hostname] = suggestion }+        case .noSuggestion, .timedOut:+            attempted.insert(hostname)+        case .cancelled:+            // The app's own pre-emption must not burn a sweep slot (Q28).+            break+        }+    }++    // MARK: - Dismissal++    public mutating func dismiss(hostname: String, side: Side) {+        dismissed[hostname, default: []].insert(side)+    }++    public mutating func clearDismissal(hostname: String, side: Side) {+        dismissed[hostname]?.remove(side)+        if dismissed[hostname]?.isEmpty == true { dismissed[hostname] = nil }+    }++    // MARK: - Invalidation++    /// Drops everything computed for a hostname, but never the reader's+    /// rejection of a side (Req 2.8, Q18).+    ///+    /// Returns whether an attempt for that hostname is in flight and must be+    /// cancelled by the caller. That attempt is voided here and now, so a+    /// result that lands before the cancellation takes effect cannot re-hold a+    /// rule derived from the corpus that just changed (Req 5.5).+    @discardableResult+    public mutating func invalidate(hostname: String) -> Bool {+        held[hostname] = nil+        attempted.remove(hostname)+        fingerprints[hostname] = nil+        guard inFlight?.hostname == hostname else { return false }+        inFlight?.void()+        return true+    }++    /// Compares fresh candidate rows to what each tracked hostname was computed+    /// against and invalidates the ones that moved. A tracked hostname absent+    /// from `candidates` has lost its Site and is invalidated too.+    ///+    /// Returns the invalidated hostnames; a returned hostname that is in flight+    /// still has to be cancelled by the caller.+    @discardableResult+    public mutating func reconcile(against candidates: [String: CorpusFingerprint]) -> Set<String> {+        var invalidated: Set<String> = []+        for hostname in trackedHostnames where candidates[hostname] != fingerprints[hostname] {+            invalidate(hostname: hostname)+            invalidated.insert(hostname)+        }+        return invalidated+    }++    /// Req 5.6: the run's cheap state goes, dismissals stay. Returns the+    /// in-flight hostname the caller must cancel, if any. That attempt is+    /// voided too — its fingerprint has just been dropped, so its result can no+    /// longer be reconciled against anything.+    public mutating func memoryWarning() -> String? {+        held.removeAll()+        attempted.removeAll()+        fingerprints.removeAll()+        inFlight?.void()+        return inFlight?.hostname+    }++    /// Req 5.3: the sweep stops, and its attempt with it. On-open and+    /// on-request work is the reader's and continues.+    public mutating func resignActive() -> String? {+        stopSweep()+        guard let inFlight, inFlight.origin == .background else { return nil }+        return inFlight.hostname+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionTypes.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionTypes.swiftnew file mode 100644index 0000000..e49902c--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/RuleSuggestionTypes.swift@@ -0,0 +1,131 @@+import AsterismCore+import Foundation++/// Which half of a composed teaching rule a suggestion, marker or dismissal+/// applies to. The two sides are offered, applied and rejected independently+/// (Req 1.3, Q7).+public enum Side: String, Sendable, Hashable, CaseIterable {+    case title+    case url+}++/// Why an attempt was started. It decides what the attempt may pre-empt, what+/// gates it is subject to, and whether a prior attempt for the hostname blocks+/// it (Reqs 5.1, 5.7, 6.6).+public enum Origin: String, Sendable, Hashable, CaseIterable {+    /// The activation sweep.+    case background+    /// The composed teaching editor opening on a hostname with nothing held.+    case open+    /// The reader using the Suggest action.+    case request+}++/// How this feature spells a failure in its logs, in one place.+///+/// Every failure here settles the attempt with `nil` and tells the reader+/// nothing (Req 4.2), so the log line is the only record — and the type is+/// most of what makes it readable, because `String(describing:)` alone reduces+/// a framework error to an opaque case name.+public enum SuggestionFailure {+    public static func describe(_ error: any Error) -> String {+        "\(type(of: error)): \(String(describing: error))"+    }+}++/// Thrown by the attempt wrapper when `RuleSuggestionBounds.attemptTimeout`+/// elapses. Distinct from `CancellationError` on purpose: a timeout marks the+/// hostname attempted, a system cancellation does not (Q45, Q28).+public struct AttemptTimeout: Error, Sendable, Equatable {+    /// What the abandoned attempt spent, measured from the model request. The+    /// budget is charged for it (Req 5.2) and only the attempt itself was+    /// holding a clock, so the timeout carries the number out rather than+    /// leaving the coordinator to assume the bound was reached exactly.+    ///+    /// No default: a timeout charges the budget, and a construction that+    /// silently charged nothing would be a leak the compiler could have caught.+    public var modelPhase: Duration++    public init(modelPhase: Duration) {+        self.modelPhase = modelPhase+    }+}++/// Whether the on-device model can be asked for a proposal. The reason is+/// carried for logging only — Req 4.1 forbids showing it to the reader.+public enum ModelAvailability: Sendable, Equatable {+    case available+    case unavailable(reason: String)++    public var isAvailable: Bool {+        switch self {+        case .available: true+        case .unavailable: false+        }+    }+}++/// One capture as the model sees it: the exact title and the exact raw URL.+public struct SuggestionExample: Sendable, Equatable {+    public var title: String+    public var rawURL: String++    public init(title: String, rawURL: String) {+        self.title = title+        self.rawURL = rawURL+    }+}++/// A verified title rule, in the shape the editor seeds a stored rule from.+public struct TitleRuleSuggestion: Sendable, Equatable {+    public var definition: PatternDefinition+    public var trimPrefix: String?+    public var trimSuffix: String?++    public init(definition: PatternDefinition, trimPrefix: String? = nil, trimSuffix: String? = nil) {+        self.definition = definition+        self.trimPrefix = trimPrefix+        self.trimSuffix = trimSuffix+    }+}++/// The held artefact: a *rule* per side, not the spans it was derived from.+///+/// A background computation cannot know which capture the reader will open the+/// editor from, and spans only mean something against one capture — so what is+/// held has to be seedable onto any of them (Q14).+public struct RuleSuggestion: Sendable, Equatable {+    public var hostname: String+    public var title: TitleRuleSuggestion?+    public var url: URLRuleDefinition?++    public init(hostname: String, title: TitleRuleSuggestion? = nil, url: URLRuleDefinition? = nil) {+        self.hostname = hostname+        self.title = title+        self.url = url+    }++    /// Whether either side survived verification. A suggestion with neither is+    /// never held.+    public var isEmpty: Bool { title == nil && url == nil }+}++/// What a held suggestion was computed against. `reconcile` compares a fresh+/// candidate row to this and invalidates the hostname on any difference, which+/// is how Req 5.5 covers captures, Site mode and stored rules with one check.+public struct CorpusFingerprint: Sendable, Equatable {+    public var siteMode: SiteMode+    public var entryCount: Int+    public var latestCaptureAt: Date?+    public var titleRuleVersion: Int?+    public var urlRuleVersion: Int?++    public init(siteMode: SiteMode, entryCount: Int, latestCaptureAt: Date?,+                titleRuleVersion: Int? = nil, urlRuleVersion: Int? = nil) {+        self.siteMode = siteMode+        self.entryCount = entryCount+        self.latestCaptureAt = latestCaptureAt+        self.titleRuleVersion = titleRuleVersion+        self.urlRuleVersion = urlRuleVersion+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismIntelligence/SuggestionCorpus.swift b/Packages/AsterismCore/Sources/AsterismIntelligence/SuggestionCorpus.swiftnew file mode 100644index 0000000..ff3d2ec--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismIntelligence/SuggestionCorpus.swift@@ -0,0 +1,62 @@+import AsterismCore+import Foundation++/// The bounded, deterministically chosen set of a hostname's captures the model+/// is shown (Req 3.7, Q24).+///+/// The **anchor** is the newest capture and the only one the model answers+/// about; the context entries exist to show which parts of a title and a URL+/// change between chapters.+public struct SuggestionCorpus: Sendable, Equatable {+    public var hostname: String+    public var anchor: SuggestionExample+    /// At most `RuleSuggestionBounds.captureSampleCount - 1` entries, newest+    /// first.+    public var context: [SuggestionExample]++    public init(hostname: String, anchor: SuggestionExample, context: [SuggestionExample] = []) {+        self.hostname = hostname+        self.anchor = anchor+        self.context = context+    }++    /// Every example the model is shown, anchor first.+    public var examples: [SuggestionExample] { [anchor] + context }++    /// The hostname's captures, newest first, capped at+    /// `RuleSuggestionBounds.captureSampleCount`.+    ///+    /// Selection is deterministic — captures sharing a timestamp are ordered by+    /// id — so the same corpus yields the same suggestion twice (Q24). Nil when+    /// the hostname has no captures.+    public static func make(from entries: [ComposedEntryBasis], hostname: String) -> SuggestionCorpus? {+        let ordered = entries.sorted { left, right in+            if left.firstCapturedAt != right.firstCapturedAt {+                return left.firstCapturedAt > right.firstCapturedAt+            }+            return left.id.uuidString < right.id.uuidString+        }+        guard let anchor = ordered.first else { return nil }++        let context = ordered.dropFirst().prefix(RuleSuggestionBounds.captureSampleCount - 1)+        return SuggestionCorpus(hostname: hostname,+                                anchor: example(anchor),+                                context: context.map(example))+    }++    /// The same corpus with half the context, oldest dropped first.+    ///+    /// This is the response to `exceededContextWindowSize`: Req 3.7 shrinks the+    /// input rather than skipping the hostname. Nil once only the anchor is+    /// left — that is the floor, and there is nothing further to try.+    public func halved() -> SuggestionCorpus? {+        guard !context.isEmpty else { return nil }+        return SuggestionCorpus(hostname: hostname,+                                anchor: anchor,+                                context: Array(context.prefix(context.count / 2)))+    }++    private static func example(_ entry: ComposedEntryBasis) -> SuggestionExample {+        SuggestionExample(title: entry.captureTitle, rawURL: entry.rawURLString)+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swiftindex 69533f5..cb05af2 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift@@ -474,9 +474,9 @@ struct ComposedRepoFixture {      func freshContext() -> ModelContext { ModelContext(container) } -    func seed(_ mutate: (ModelContext) -> Void) throws {+    func seed(_ mutate: (ModelContext) throws -> Void) throws {         let context = ModelContext(container)-        mutate(context)+        try mutate(context)         try context.save()     } 

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/RuleSuggestionCandidatesTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/RuleSuggestionCandidatesTests.swiftnew file mode 100644index 0000000..f611184--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/RuleSuggestionCandidatesTests.swift@@ -0,0 +1,259 @@+import Foundation+import SwiftData+import Testing++@testable import AsterismCore++/// The rule-suggestion candidate read (Reqs 1.6, 5.1, 5.5): one row per+/// hostname describing what the sweep needs to pick a hostname and what+/// `reconcile` needs to notice a change.+@Suite("Rule suggestion candidates", .serialized)+struct RuleSuggestionCandidatesTests {++    // MARK: - Seeding helpers++    @discardableResult+    private func insertSite(+        _ context: ModelContext, hostname: String, mode: SiteMode+    ) -> Site {+        let site = Site(hostname: hostname)+        site.mode = mode+        context.insert(site)+        return site+    }++    private func insertEntry(+        _ context: ModelContext, hostname: String, capturedAt: Date, suffix: String+    ) {+        let url = "https://\(hostname)/read/\(suffix)"+        let entry = Entry(+            id: UUID(), captureTitle: "Chapter \(suffix)", captureTitleSource: .host,+            rawURLString: url, hostname: hostname, entryIdentityKey: url,+            timestamp: capturedAt)+        entry.conservativeIdentityKey = url+        entry.identityKeyVersion = 1+        entry.identityBasis = .conservative+        context.insert(entry)+    }++    private func insertTitlePattern(+        _ context: ModelContext, site: Site, version: Int, isActive: Bool+    ) throws {+        let pattern = try TitlePattern(+            version: version, isActive: isActive,+            createdAt: Date(timeIntervalSince1970: 1_000), definition: .wholeTitle, site: site)+        context.insert(pattern)+    }++    private func insertURLRule(+        _ context: ModelContext, site: Site, version: Int, isCurrent: Bool+    ) throws {+        let rule = try URLRulePattern(+            version: version, isCurrent: isCurrent,+            createdAt: Date(timeIntervalSince1970: 1_000), origin: .readerTaught,+            definition: .sequence(locator: .query(name: ExactScalarString("chapter"))),+            site: site)+        context.insert(rule)+    }++    private func candidate(+        _ rows: [RuleSuggestionCandidate], _ hostname: String+    ) throws -> RuleSuggestionCandidate {+        try #require(rows.first { $0.hostname == hostname })+    }++    // MARK: - Selection++    @Test("A nil hostname set returns every hostname, sorted")+    func nilHostnamesReturnsEveryWinner() async throws {+        let fixture = try ComposedRepoFixture()+        // Seeded backwards: the rows come out of a dictionary of winners, so+        // only an explicit sort can put them back in hostname order.+        try fixture.seed { context in+            insertSite(context, hostname: "c.example", mode: .articles)+            insertSite(context, hostname: "b.example", mode: .untaught)+            insertSite(context, hostname: "a.example", mode: .untaught)+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)++        #expect(rows.map(\.hostname) == ["a.example", "b.example", "c.example"])+    }++    @Test("A hostname subset returns only those hostnames")+    func subsetReturnsOnlyRequestedHostnames() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            insertSite(context, hostname: "c.example", mode: .untaught)+            insertSite(context, hostname: "b.example", mode: .untaught)+            insertSite(context, hostname: "a.example", mode: .untaught)+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(+            hostnames: ["c.example", "a.example", "never.example"])++        #expect(rows.map(\.hostname) == ["a.example", "c.example"])+    }++    @Test("An empty hostname set returns no rows")+    func emptySubsetReturnsNothing() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            insertSite(context, hostname: "a.example", mode: .untaught)+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: [])++        #expect(rows.isEmpty)+    }++    // MARK: - Fields++    @Test("Each row carries its Site's mode")+    func siteModeIsReported() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            insertSite(context, hostname: "untaught.example", mode: .untaught)+            let taught = insertSite(context, hostname: "taught.example", mode: .taught)+            try insertTitlePattern(context, site: taught, version: 1, isActive: true)+            insertSite(context, hostname: "articles.example", mode: .articles)+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)++        #expect(try candidate(rows, "untaught.example").siteMode == .untaught)+        #expect(try candidate(rows, "taught.example").siteMode == .taught)+        #expect(try candidate(rows, "articles.example").siteMode == .articles)+    }++    @Test("Rule versions come from the active title pattern and the current URL rule")+    func ruleVersionsComeFromTheLiveRules() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            let taught = insertSite(context, hostname: "taught.example", mode: .taught)+            // Superseded records must not be read: only the active/current ones.+            try insertTitlePattern(context, site: taught, version: 1, isActive: false)+            try insertTitlePattern(context, site: taught, version: 4, isActive: true)+            try insertURLRule(context, site: taught, version: 1, isCurrent: false)+            try insertURLRule(context, site: taught, version: 2, isCurrent: true)++            // A title rule and no URL rule at all.+            let titleOnly = insertSite(context, hostname: "title.example", mode: .taught)+            try insertTitlePattern(context, site: titleOnly, version: 7, isActive: true)++            insertSite(context, hostname: "untaught.example", mode: .untaught)+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)++        let taught = try candidate(rows, "taught.example")+        #expect(taught.titleRuleVersion == 4)+        #expect(taught.urlRuleVersion == 2)++        let titleOnly = try candidate(rows, "title.example")+        #expect(titleOnly.titleRuleVersion == 7)+        #expect(titleOnly.urlRuleVersion == nil)++        let untaught = try candidate(rows, "untaught.example")+        #expect(untaught.titleRuleVersion == nil)+        #expect(untaught.urlRuleVersion == nil)+    }++    @Test("Entry count and latest capture describe the hostname's captures")+    func entryCountAndLatestCapture() async throws {+        let fixture = try ComposedRepoFixture()+        let newest = Date(timeIntervalSince1970: 1_800_000_300)+        try fixture.seed { context in+            insertSite(context, hostname: "a.example", mode: .untaught)+            insertSite(context, hostname: "b.example", mode: .untaught)+            insertEntry(+                context, hostname: "a.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_100), suffix: "1")+            insertEntry(context, hostname: "a.example", capturedAt: newest, suffix: "2")+            insertEntry(+                context, hostname: "a.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_200), suffix: "3")+            insertEntry(+                context, hostname: "b.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_900), suffix: "1")+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(+            hostnames: ["a.example"])++        let row = try candidate(rows, "a.example")+        #expect(row.entryCount == 3)+        #expect(row.latestCaptureAt == newest)+    }++    @Test("A Site with no captures reports zero entries and no latest capture")+    func siteWithoutEntries() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            insertSite(context, hostname: "empty.example", mode: .untaught)+            insertSite(context, hostname: "other.example", mode: .untaught)+            insertEntry(+                context, hostname: "other.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_100), suffix: "1")+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)++        let row = try candidate(rows, "empty.example")+        #expect(row.entryCount == 0)+        #expect(row.latestCaptureAt == nil)+    }++    // MARK: - Fail-closed++    @Test("A Site whose mode raw is outside the closed set has no row at all")+    func unknownSiteModeRawIsOmitted() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            let stranger = insertSite(context, hostname: "stranger.example", mode: .untaught)+            // A raw value no writer produces: coercing it to `.untaught` would+            // make the hostname auto-eligible and propose rules for a state+            // nothing here understands, so the row is dropped instead (Q15).+            stranger.modeRaw = "teleported"+            insertSite(context, hostname: "known.example", mode: .untaught)+            insertEntry(+                context, hostname: "stranger.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_100), suffix: "1")+        }++        let all = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)+        #expect(all.map(\.hostname) == ["known.example"])++        // Named directly, it is still absent — which is what makes `reconcile`+        // read the hostname as changed rather than unchanged.+        let named = try await fixture.repository.ruleSuggestionCandidates(+            hostnames: ["stranger.example", "known.example"])+        #expect(named.map(\.hostname) == ["known.example"])+    }++    // MARK: - Duplicate Site rows++    @Test("Two Site rows for one hostname yield the resolution winner, once")+    func duplicateSiteRowsResolveToTheWinner() async throws {+        let fixture = try ComposedRepoFixture()+        try fixture.seed { context in+            // Step 1 of `SiteResolutionOrder`: the row with an active title+            // pattern wins over the untaught duplicate.+            insertSite(context, hostname: "dup.example", mode: .untaught)+            let taught = insertSite(context, hostname: "dup.example", mode: .taught)+            try insertTitlePattern(context, site: taught, version: 5, isActive: true)+            insertEntry(+                context, hostname: "dup.example",+                capturedAt: Date(timeIntervalSince1970: 1_800_000_100), suffix: "1")+        }++        let rows = try await fixture.repository.ruleSuggestionCandidates(hostnames: nil)++        #expect(rows.count == 1)+        let row = try candidate(rows, "dup.example")+        #expect(row.siteMode == .taught)+        #expect(row.titleRuleVersion == 5)+        // The count is per hostname, so a duplicate row does not double it.+        #expect(row.entryCount == 1)+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismIntelligenceTests/FoundationRuleSuggestionModelClientTests.swift b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/FoundationRuleSuggestionModelClientTests.swiftnew file mode 100644index 0000000..0ea511c--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/FoundationRuleSuggestionModelClientTests.swift@@ -0,0 +1,147 @@+import Foundation+import FoundationModels+import Testing++@testable import AsterismIntelligence++@Suite("FoundationRuleSuggestionModelClient")+struct FoundationRuleSuggestionModelClientTests {+    static let corpus = SuggestionCorpus(+        hostname: "example.net",+        anchor: SuggestionExample(title: "Sylver Seeker - Chapter 12: The Long Road",+                                  rawURL: "https://example.net/novel/sylver-seeker/chapter-12"),+        context: [+            SuggestionExample(title: "Sylver Seeker - Chapter 11: Ashes",+                              rawURL: "https://example.net/novel/sylver-seeker/chapter-11"),+        ])++    // MARK: - Availability mapping (Req 4.1)++    @Test("Availability maps to the feature's own gate, reason included for logging")+    func availabilityMapping() {+        #expect(FoundationRuleSuggestionModelClient.availability(from: .available) == .available)++        for reason: SystemLanguageModel.Availability.UnavailableReason in+            [.deviceNotEligible, .appleIntelligenceNotEnabled, .modelNotReady] {+            let mapped = FoundationRuleSuggestionModelClient.availability(from: .unavailable(reason))+            #expect(!mapped.isAvailable)+            if case .unavailable(let text) = mapped {+                #expect(!text.isEmpty)+            }+        }++        #expect(FoundationRuleSuggestionModelClient.availability(from: .unavailable(.modelNotReady))+            != FoundationRuleSuggestionModelClient.availability(from: .unavailable(.deviceNotEligible)))+    }++    // MARK: - Instructions (Decision 1)++    @Test("The instructions demand verbatim copying and carry three worked examples")+    func instructions() {+        let instructions = FoundationRuleSuggestionModelClient.instructions++        #expect(instructions.contains("exactly as it appears"))+        #expect(instructions.contains("Example A"))+        #expect(instructions.contains("Example B"))+        // Example C is the opaque-address case: chapter in the title, nothing in the URL.+        #expect(instructions.contains("Example C"))+        #expect(!instructions.contains("Example D"))+        #expect(instructions.contains("domain name is never urlWorkIdentity"))+        // A bare number or decimal is a chapter (1.00 - The Wandering Inn).+        #expect(instructions.contains("1.00"))+        // Every field of the proposal is named, in the order it is declared.+        let fields = ["workName", "chapterText", "urlWorkIdentity", "urlSequenceText"]+        var searchStart = instructions.startIndex+        for field in fields {+            let found = instructions.range(of: field, range: searchStart ..< instructions.endIndex)+            #expect(found != nil, "\(field) missing or out of order in the instructions")+            searchStart = found?.upperBound ?? searchStart+        }+        // Empty means "none" (Q39), and the model is told so.+        #expect(instructions.contains("empty"))+    }++    // MARK: - Prompt (Req 3.7)++    @Test("The prompt numbers the examples with the anchor first")+    func promptNumbersAnchorFirst() {+        let prompt = FoundationRuleSuggestionModelClient.prompt(for: Self.corpus)++        #expect(prompt.contains("1. title: Sylver Seeker - Chapter 12: The Long Road"))+        #expect(prompt.contains("   url: https://example.net/novel/sylver-seeker/chapter-12"))+        #expect(prompt.contains("2. title: Sylver Seeker - Chapter 11: Ashes"))+        if let anchorPosition = prompt.range(of: "Chapter 12")?.lowerBound,+           let contextPosition = prompt.range(of: "Chapter 11")?.lowerBound {+            #expect(anchorPosition < contextPosition)+        } else {+            Issue.record("both examples must appear in the prompt")+        }+        #expect(prompt.contains("example.net"))+    }++    @Test("A one-capture corpus produces a single numbered example")+    func promptWithOnlyTheAnchor() {+        let corpus = SuggestionCorpus(hostname: "example.net", anchor: Self.corpus.anchor)++        let prompt = FoundationRuleSuggestionModelClient.prompt(for: corpus)++        #expect(prompt.contains("1. title: "))+        #expect(!prompt.contains("2. title: "))+    }++    // MARK: - Generation options (Decision 1: reproducible for a given corpus)++    @Test("Sampling is greedy so the same corpus yields the same proposal")+    func greedyOptions() {+        #expect(FoundationRuleSuggestionModelClient.generationOptions+            == GenerationOptions(sampling: .greedy))+    }++    // MARK: - Context overflow (Req 3.7)++    @Test("A context-window overflow is recognisable by type, so the corpus can be halved")+    func contextOverflowIsTyped() {+        let client = FoundationRuleSuggestionModelClient()+        let overflow = LanguageModelSession.GenerationError+            .exceededContextWindowSize(.init(debugDescription: "too long"))+        let other = LanguageModelSession.GenerationError+            .guardrailViolation(.init(debugDescription: "nope"))++        #expect(client.isContextWindowOverflow(overflow))+        #expect(!client.isContextWindowOverflow(other))+        #expect(!client.isContextWindowOverflow(CancellationError()))+        #expect(!client.isContextWindowOverflow(AttemptTimeout(modelPhase: .zero)))+    }++    @Test("The overflow question is answerable through the protocol, without naming the client")+    func contextOverflowIsAskedThroughTheSeam() {+        // What the suggester will hold: an existential with no idea which+        // client it is or that `FoundationModels` exists.+        let client: any RuleSuggestionModelClient = FoundationRuleSuggestionModelClient()+        let overflow = LanguageModelSession.GenerationError+            .exceededContextWindowSize(.init(debugDescription: "too long"))++        #expect(client.isContextWindowOverflow(overflow))+        #expect(!client.isContextWindowOverflow(AttemptTimeout(modelPhase: .zero)))+    }++    // MARK: - One live call++    @Test("A live model call returns a decodable RuleProposal for a two-example corpus")+    func liveCall() async throws {+        let client = FoundationRuleSuggestionModelClient()+        try await withKnownIssue("The on-device model is unavailable on this host") {+            try #require(SystemLanguageModel.default.isAvailable)+            #expect(client.availability() == .available)++            let proposal = try await client.propose(Self.corpus)++            // What the model actually picks is its business — Req 3 validates+            // it downstream. What this asserts is that the call round-trips+            // into the structure at all.+            #expect(!proposal.workName.isEmpty)+        } when: {+            !SystemLanguageModel.default.isAvailable+        }+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismIntelligenceTests/ProposalLocatorTests.swift b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/ProposalLocatorTests.swiftnew file mode 100644index 0000000..28372ac--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/ProposalLocatorTests.swift@@ -0,0 +1,199 @@+import Foundation+import Testing++@testable import AsterismIntelligence++@Suite("ProposalLocator")+struct ProposalLocatorTests {+    // MARK: - The four outcomes (Req 3.1, Decision 1)++    @Test("A unique occurrence yields its character range")+    func uniqueOccurrence() {+        let source = "Sylver Seeker - Chapter 12"+        #expect(ProposalLocator.locate("Sylver Seeker", in: source) == 0 ..< 13)+        #expect(ProposalLocator.locate("Chapter 12", in: source) == 16 ..< 26)+        #expect(ProposalLocator.locate(source, in: source) == 0 ..< source.count)+    }++    @Test("Text that does not appear yields nil")+    func absent() {+        #expect(ProposalLocator.locate("Chapter 13", in: "Sylver Seeker - Chapter 12") == nil)+        // The locator is exact by design: case and whitespace drift are misses.+        #expect(ProposalLocator.locate("sylver seeker", in: "Sylver Seeker - Chapter 12") == nil)+        #expect(ProposalLocator.locate("Sylver  Seeker", in: "Sylver Seeker - Chapter 12") == nil)+    }++    @Test("Text that appears twice is ambiguous and yields nil")+    func duplicate() {+        #expect(ProposalLocator.locate("12", in: "Chapter 12 of 12") == nil)+        // Overlapping repeats count as two occurrences: neither span is the one.+        #expect(ProposalLocator.locate("aa", in: "aaa") == nil)+    }++    @Test("Empty text never locates, in any source")+    func empty() {+        #expect(ProposalLocator.locate("", in: "Sylver Seeker") == nil)+        #expect(ProposalLocator.locate("", in: "") == nil)+        #expect(ProposalLocator.locate("anything", in: "") == nil)+    }++    // MARK: - The placement entry point (Req 3.1)++    @Test("Placement tells absence and ambiguity apart, which locate() collapses")+    func placementSeparatesAbsentFromAmbiguous() {+        let source = "Chapter 12 of 12"+        #expect(ProposalLocator.place("Chapter", in: source) == .unique(0 ..< 7))+        #expect(ProposalLocator.place("13", in: source) == .absent)+        #expect(ProposalLocator.place("12", in: source) == .ambiguous)+        // Both non-unique outcomes are the same nil to a caller with one source.+        #expect(ProposalLocator.locate("13", in: source) == nil)+        #expect(ProposalLocator.locate("12", in: source) == nil)+    }++    @Test("Text longer than the source, and empty text, are absent rather than ambiguous")+    func placementEdges() {+        #expect(ProposalLocator.place("Sylver Seeker", in: "Sylver") == .absent)+        #expect(ProposalLocator.place("", in: "Sylver Seeker") == .absent)+        #expect(ProposalLocator.place("", in: "") == .absent)+        #expect(ProposalLocator.place("anything", in: "") == .absent)+    }++    @Test("Overlapping repeats are ambiguous, not two placements")+    func placementOverlappingRepeats() {+        #expect(ProposalLocator.place("aa", in: "aaa") == .ambiguous)+    }++    @Test("locate() is place() with the non-unique outcomes collapsed",+          arguments: ProposalLocatorPropertyCase.all)+    func locateAgreesWithPlace(_ testCase: ProposalLocatorPropertyCase) {+        switch ProposalLocator.place(testCase.slice, in: testCase.source) {+        case .unique(let range):+            #expect(ProposalLocator.locate(testCase.slice, in: testCase.source) == range)+        case .absent, .ambiguous:+            #expect(ProposalLocator.locate(testCase.slice, in: testCase.source) == nil)+        }+    }++    // MARK: - Offsets are over Characters, matching TitleSegment.range++    @Test("Offsets count Characters, not scalars or UTF-8 bytes")+    func combiningMarksCountAsOneCharacter() {+        // "é" as e + U+0301: one Character, two scalars, three UTF-8 bytes.+        let source = "Cafe\u{0301} Chapter 3"+        #expect(source.count == 14)+        #expect(ProposalLocator.locate("Chapter 3", in: source) == 5 ..< 14)+        #expect(ProposalLocator.locate("Cafe\u{0301}", in: source) == 0 ..< 4)+    }++    @Test("A precomposed needle matches a decomposed source, as Character equality does")+    func canonicalEquivalence() {+        let source = "Cafe\u{0301} Chapter 3"+        #expect(ProposalLocator.locate("Caf\u{00E9}", in: source) == 0 ..< 4)+    }++    @Test("Emoji built from several scalars are single Characters")+    func emojiSequence() {+        let source = "Family 👩‍👩‍👧 Chapter 2"+        #expect(ProposalLocator.locate("👩‍👩‍👧", in: source) == 7 ..< 8)+        #expect(ProposalLocator.locate("Chapter 2", in: source) == 9 ..< 18)+    }++    @Test("CJK titles locate by Character offset")+    func cjk() {+        let source = "転生したらスライムだった件 第12話"+        #expect(ProposalLocator.locate("転生したらスライムだった件", in: source) == 0 ..< 13)+        #expect(ProposalLocator.locate("第12話", in: source) == 14 ..< 18)+        #expect(ProposalLocator.locate("スライム", in: source) == 5 ..< 9)+    }++    @Test("A CJK substring repeated in the source is ambiguous")+    func cjkDuplicate() {+        #expect(ProposalLocator.locate("第", in: "第1話 第2話") == nil)+    }++    // MARK: - Property: random slices round-trip++    @Test("A random slice of a random source locates iff it occurs exactly once",+          arguments: ProposalLocatorPropertyCase.all)+    func randomSliceRoundTrip(_ testCase: ProposalLocatorPropertyCase) {+        let occurrences = testCase.expectedOccurrences+        let located = ProposalLocator.locate(testCase.slice, in: testCase.source)++        if testCase.slice.isEmpty {+            #expect(located == nil)+        } else if occurrences.count == 1 {+            #expect(located == occurrences[0])+            // The located range really does cut the slice back out.+            if let located {+                #expect(String(Array(testCase.source)[located]) == testCase.slice)+            }+        } else {+            #expect(located == nil)+        }+    }+}++/// One generated `(source, slice)` pair, with the expected occurrences computed+/// by an independent implementation (Foundation literal search) so the property+/// test is not the locator agreeing with itself.+struct ProposalLocatorPropertyCase: Sendable, CustomTestStringConvertible {+    let source: String+    let slice: String++    var testDescription: String { "\(source.debugDescription) ⊃ \(slice.debugDescription)" }++    /// Every character-offset range at which `slice` occurs in `source`,+    /// overlapping occurrences included.+    var expectedOccurrences: [Range<Int>] {+        guard !slice.isEmpty else { return [] }+        var found: [Range<Int>] = []+        var searchStart = source.startIndex+        while searchStart < source.endIndex,+              let hit = source.range(of: slice, options: [.literal],+                                     range: searchStart ..< source.endIndex) {+            found.append(source.distance(from: source.startIndex, to: hit.lowerBound)+                ..< source.distance(from: source.startIndex, to: hit.upperBound))+            searchStart = source.index(after: hit.lowerBound)+        }+        return found+    }++    /// Deterministic so a failure is reproducible. The alphabet is deliberately+    /// single-scalar (`.literal` search and Character comparison then agree);+    /// combining marks and grapheme clusters are covered by the cases above.+    static let all: [ProposalLocatorPropertyCase] = {+        let alphabet = Array("aabc 日本-1")+        var rng = SplitMix64(seed: 0x5EED_1234_5EED_1234)+        var cases: [ProposalLocatorPropertyCase] = []+        for _ in 0 ..< 300 {+            let length = Int(rng.next(upperBound: 10)) + 1+            let source = String((0 ..< length).map { _ in alphabet[Int(rng.next(upperBound: UInt64(alphabet.count)))] })+            let characters = Array(source)+            let start = Int(rng.next(upperBound: UInt64(characters.count)))+            let end = start + Int(rng.next(upperBound: UInt64(characters.count - start + 1)))+            cases.append(ProposalLocatorPropertyCase(source: source,+                                                     slice: String(characters[start ..< end])))+        }+        return cases+    }()+}++/// A tiny seeded generator: the property cases must be identical on every run.+struct SplitMix64 {+    private var state: UInt64++    init(seed: UInt64) { state = seed }++    mutating func next() -> UInt64 {+        state &+= 0x9E37_79B9_7F4A_7C15+        var z = state+        z = (z ^ (z >> 30)) &* 0xBF58_476D_1CE4_E5B9+        z = (z ^ (z >> 27)) &* 0x94D0_49BB_1331_11EB+        return z ^ (z >> 31)+    }++    mutating func next(upperBound: UInt64) -> UInt64 {+        precondition(upperBound > 0)+        return next() % upperBound+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismIntelligenceTests/RuleSuggestionLedgerTests.swift b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/RuleSuggestionLedgerTests.swiftnew file mode 100644index 0000000..bc4cb66--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/RuleSuggestionLedgerTests.swift@@ -0,0 +1,743 @@+import AsterismCore+import Foundation+import Testing++@testable import AsterismIntelligence++@Suite("RuleSuggestionLedger")+struct RuleSuggestionLedgerTests {+    // MARK: - Fixtures++    static let foreground = RuleSuggestionEnvironment(isActive: true, isLowPowerMode: false,+                                                      thermalState: .nominal)++    static func suggestion(_ hostname: String) -> RuleSuggestion {+        RuleSuggestion(hostname: hostname,+                       title: TitleRuleSuggestion(definition: .wholeTitle),+                       url: nil)+    }++    static func fingerprint(entryCount: Int = 3, titleRuleVersion: Int? = nil) -> CorpusFingerprint {+        CorpusFingerprint(siteMode: .untaught, entryCount: entryCount,+                          latestCaptureAt: Date(timeIntervalSince1970: 1_700_000_000),+                          titleRuleVersion: titleRuleVersion, urlRuleVersion: nil)+    }++    /// A ledger mid-sweep with one attempt running for `hostname`.+    static func running(_ hostname: String, origin: Origin = .background) -> RuleSuggestionLedger {+        var ledger = RuleSuggestionLedger()+        ledger.beginSweep()+        let outcome = ledger.start(hostname: hostname, origin: origin,+                                   fingerprint: fingerprint(), environment: foreground)+        #expect(outcome == .start)+        return ledger+    }++    /// A ledger that has settled one attempt for `hostname`.+    static func settled(_ hostname: String, _ settlement: AttemptSettlement,+                        modelPhase: Duration = .seconds(1)) -> RuleSuggestionLedger {+        var ledger = running(hostname)+        ledger.settle(hostname: hostname, settlement, modelPhase: modelPhase)+        return ledger+    }++    // MARK: - Single flight (Req 5.11)++    @Test("Only one attempt runs at a time")+    func singleFlight() {+        var ledger = Self.running("a.example")++        #expect(ledger.inFlight == RuleSuggestionLedger.InFlight(hostname: "a.example",+                                                                 origin: .background))+        let outcome = ledger.start(hostname: "b.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .refuse(.inFlight(hostname: "a.example")))+        #expect(ledger.inFlight?.hostname == "a.example")+    }++    @Test("A start for the hostname already in flight attaches, whatever its origin",+          arguments: Origin.allCases)+    func attachesToTheSameHostname(origin: Origin) {+        var ledger = Self.running("a.example")++        let outcome = ledger.start(hostname: "a.example", origin: origin,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .attach)+        #expect(ledger.inFlight?.origin == .background)+    }++    @Test("An attempted hostname still in flight (re-requested) attaches rather than refusing")+    func attachesEvenWhenAttempted() {+        var ledger = Self.settled("a.example", .noSuggestion)+        _ = ledger.start(hostname: "a.example", origin: .request,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)++        let outcome = ledger.start(hostname: "a.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(ledger.isAttempted("a.example"))+        #expect(outcome == .attach)+    }++    // MARK: - Origins (Reqs 5.1, 5.7, 6.6)++    @Test("An on-open attempt is refused for a hostname already attempted this run")+    func openRefusedWhenAttempted() {+        var ledger = Self.settled("a.example", .noSuggestion)++        let outcome = ledger.start(hostname: "a.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .refuse(.attempted))+        #expect(ledger.inFlight == nil)+    }++    @Test("An on-request attempt starts for a hostname already attempted this run")+    func requestStartsWhenAttempted() {+        var ledger = Self.settled("a.example", .noSuggestion)++        let outcome = ledger.start(hostname: "a.example", origin: .request,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .start)+        #expect(ledger.inFlight?.origin == .request)+    }++    @Test("An on-open attempt is refused when the reader has rejected both sides")+    func openRefusedWhenBothSidesDismissed() {+        var ledger = RuleSuggestionLedger()+        ledger.dismiss(hostname: "a.example", side: .title)++        // One side left: the attempt is still worth making for it.+        #expect(!ledger.refusesOpen(hostname: "a.example"))+        #expect(ledger.start(hostname: "a.example", origin: .open,+                             fingerprint: Self.fingerprint(),+                             environment: Self.foreground) == .start)++        var both = RuleSuggestionLedger()+        both.dismiss(hostname: "a.example", side: .title)+        both.dismiss(hostname: "a.example", side: .url)++        #expect(both.refusesOpen(hostname: "a.example"))+        #expect(both.start(hostname: "a.example", origin: .open,+                           fingerprint: Self.fingerprint(),+                           environment: Self.foreground) == .refuse(.bothSidesDismissed))+        // The reader can still ask for one (Req 6.5).+        #expect(both.start(hostname: "a.example", origin: .request,+                           fingerprint: Self.fingerprint(),+                           environment: Self.foreground) == .start)+    }++    @Test("A background attempt is refused when the reader has rejected both sides")+    func backgroundRefusedWhenBothSidesDismissed() {+        var ledger = RuleSuggestionLedger()+        ledger.dismiss(hostname: "a.example", side: .title)++        // One side left is still worth the sweep's slot.+        #expect(!ledger.isFullyDismissed("a.example"))+        #expect(ledger.start(hostname: "a.example", origin: .background,+                             fingerprint: Self.fingerprint(),+                             environment: Self.foreground) == .start)++        var both = RuleSuggestionLedger()+        both.dismiss(hostname: "a.example", side: .title)+        both.dismiss(hostname: "a.example", side: .url)++        #expect(both.isFullyDismissed("a.example"))+        #expect(both.start(hostname: "a.example", origin: .background,+                           fingerprint: Self.fingerprint(),+                           environment: Self.foreground) == .refuse(.bothSidesDismissed))+    }++    @Test("Invalidation keeps the rejection, so the sweep still passes the hostname over")+    func invalidationDoesNotReviveAFullyDismissedHostname() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))+        ledger.dismiss(hostname: "a.example", side: .title)+        ledger.dismiss(hostname: "a.example", side: .url)++        // A capture lands: the hold and the attempt go, the rejection stays+        // (Q18) — and with it the refusal, so the corpus change cannot cost a+        // second model call on a hostname the reader has already turned down.+        ledger.invalidate(hostname: "a.example")++        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.isFullyDismissed("a.example"))+        #expect(ledger.start(hostname: "a.example", origin: .background,+                             fingerprint: Self.fingerprint(entryCount: 4),+                             environment: Self.foreground) == .refuse(.bothSidesDismissed))+    }++    @Test("The free refusal agrees with what a start would do")+    func refusesOpenMatchesStart() {+        // Attempted, and behind a request for another hostname: both are+        // answerable without a library read, which is why the coordinator asks.+        #expect(Self.settled("a.example", .noSuggestion).refusesOpen(hostname: "a.example"))+        #expect(Self.running("a.example", origin: .request).refusesOpen(hostname: "b.example"))+        // Behind a background attempt an open pre-empts, so it is not refused;+        // nor is a start for the hostname already running, which attaches.+        #expect(!Self.running("a.example", origin: .background).refusesOpen(hostname: "b.example"))+        #expect(!Self.running("a.example", origin: .request).refusesOpen(hostname: "a.example"))+    }++    @Test("A background attempt is refused for a hostname already attempted this run")+    func backgroundRefusedWhenAttempted() {+        var ledger = Self.settled("a.example", .noSuggestion)++        let outcome = ledger.start(hostname: "a.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .refuse(.attempted))+    }++    // MARK: - Pre-emption (Q23, Req 6.6)++    @Test("An editor open pre-empts a background attempt for another hostname")+    func openPreemptsBackground() {+        var ledger = Self.running("a.example", origin: .background)++        let outcome = ledger.start(hostname: "b.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .preempt(hostname: "a.example"))+        // The ledger does not start the new attempt itself: the coordinator+        // cancels the running task, settles it, and asks again.+        #expect(ledger.inFlight?.hostname == "a.example")+    }++    @Test("An editor open pre-empts an earlier on-open attempt for another hostname")+    func openPreemptsOpen() {+        var ledger = Self.running("a.example", origin: .open)++        let outcome = ledger.start(hostname: "b.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .preempt(hostname: "a.example"))+    }++    @Test("An editor open does not pre-empt a request")+    func openDoesNotPreemptRequest() {+        var ledger = Self.running("a.example", origin: .request)++        let outcome = ledger.start(hostname: "b.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .refuse(.inFlight(hostname: "a.example")))+        #expect(ledger.inFlight?.hostname == "a.example")+    }++    @Test("A request pre-empts an attempt of any origin for another hostname",+          arguments: Origin.allCases)+    func requestPreemptsAnything(origin: Origin) {+        var ledger = Self.running("a.example", origin: origin)++        let outcome = ledger.start(hostname: "b.example", origin: .request,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .preempt(hostname: "a.example"))+    }++    @Test("Pre-emption ends the sweep for this activation", arguments: [Origin.open, .request])+    func preemptionEndsTheSweep(origin: Origin) {+        var ledger = Self.running("a.example", origin: .background)+        #expect(ledger.sweepActive)++        _ = ledger.start(hostname: "b.example", origin: origin,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)++        #expect(!ledger.sweepActive)+    }++    @Test("An ordinary start leaves the sweep running")+    func plainStartKeepsTheSweep() {+        var ledger = RuleSuggestionLedger()+        ledger.beginSweep()++        _ = ledger.start(hostname: "a.example", origin: .background,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)++        #expect(ledger.sweepActive)+    }++    @Test("A sweep cannot be begun twice")+    func sweepIsSingleInstance() throws {+        var ledger = RuleSuggestionLedger()++        let begun = ledger.beginSweep()+        let first = try #require(begun)+        let second = ledger.beginSweep()+        ledger.endSweep(generation: first)+        let third = ledger.beginSweep()++        #expect(second == nil)+        #expect(third != nil)+        #expect(third != first)+    }++    @Test("A stopped sweep is still running, and only it can end itself")+    func stopSignalIsNotTheSingleInstanceGuard() throws {+        var ledger = RuleSuggestionLedger()+        let begun = ledger.beginSweep()+        let stopped = try #require(begun)++        _ = ledger.resignActive()++        // Stopped: it starts nothing more. Still running: the coroutine has not+        // returned, so a second sweep may not begin under it.+        #expect(!ledger.isSweeping(generation: stopped))+        #expect(ledger.beginSweep() == nil)++        ledger.endSweep(generation: stopped)+        let begunAgain = ledger.beginSweep()+        let fresh = try #require(begunAgain)+        #expect(ledger.isSweeping(generation: fresh))+    }++    @Test("A token from a sweep that has already ended ends nothing")+    func staleEndSweepIsANoOp() throws {+        var ledger = RuleSuggestionLedger()+        let begun = ledger.beginSweep()+        let first = try #require(begun)+        ledger.endSweep(generation: first)+        let begunAgain = ledger.beginSweep()+        let second = try #require(begunAgain)++        ledger.endSweep(generation: first)++        #expect(ledger.isSweeping(generation: second))+        #expect(ledger.beginSweep() == nil)+    }++    // MARK: - Background gates (Reqs 5.2, 5.3)++    @Test("The background sweep is refused once the run budget is spent")+    func backgroundRefusedOnBudget() {+        var ledger = Self.settled("a.example", .noSuggestion,+                                  modelPhase: RuleSuggestionBounds.runTimeBudget)++        let outcome = ledger.start(hostname: "b.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(ledger.budgetExhausted)+        #expect(outcome == .refuse(.budgetExhausted))+    }++    @Test("Budget exhaustion does not stop reader-initiated attempts (Q31)",+          arguments: [Origin.open, .request])+    func budgetBlocksBackgroundOnly(origin: Origin) {+        var ledger = Self.settled("a.example", .noSuggestion,+                                  modelPhase: RuleSuggestionBounds.runTimeBudget)++        let outcome = ledger.start(hostname: "b.example", origin: origin,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .start)+    }++    @Test("The background sweep is refused in Low Power Mode, on heat, and when inactive",+          arguments: zip(+              [+                  RuleSuggestionEnvironment(isActive: true, isLowPowerMode: true, thermalState: .nominal),+                  RuleSuggestionEnvironment(isActive: true, isLowPowerMode: false, thermalState: .serious),+                  RuleSuggestionEnvironment(isActive: true, isLowPowerMode: false, thermalState: .critical),+                  RuleSuggestionEnvironment(isActive: false, isLowPowerMode: false, thermalState: .nominal),+              ],+              [RefusalReason.lowPower, .thermallyConstrained, .thermallyConstrained, .notActive]))+    func backgroundGates(environment: RuleSuggestionEnvironment, reason: RefusalReason) {+        var ledger = RuleSuggestionLedger()++        let outcome = ledger.start(hostname: "a.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: environment)++        #expect(outcome == .refuse(reason))+        #expect(ledger.inFlight == nil)+    }++    @Test("A fair thermal state does not stop the sweep")+    func fairThermalIsFine() {+        var ledger = RuleSuggestionLedger()+        let environment = RuleSuggestionEnvironment(isActive: true, isLowPowerMode: false,+                                                    thermalState: .fair)++        let outcome = ledger.start(hostname: "a.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: environment)++        #expect(outcome == .start)+    }++    @Test("Reader-initiated attempts ignore the Low Power and thermal gates (Req 5.3)",+          arguments: [Origin.open, .request])+    func gatesDoNotApplyToReaderAttempts(origin: Origin) {+        var ledger = RuleSuggestionLedger()+        let environment = RuleSuggestionEnvironment(isActive: false, isLowPowerMode: true,+                                                    thermalState: .critical)++        let outcome = ledger.start(hostname: "a.example", origin: origin,+                                   fingerprint: Self.fingerprint(), environment: environment)++        #expect(outcome == .start)+    }++    // MARK: - Settlement (Reqs 5.2, 5.4, 5.10, Q28)++    @Test("A settled attempt holds its suggestion, marks the hostname attempted, and charges")+    func successSettles() {+        let ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")),+                                  modelPhase: .seconds(4))++        #expect(ledger.held(for: "a.example") == Self.suggestion("a.example"))+        #expect(ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == .seconds(4))+        #expect(ledger.inFlight == nil)+    }++    @Test("An attempt that produced nothing still marks the hostname attempted")+    func noSuggestionSettles() {+        let ledger = Self.settled("a.example", .noSuggestion, modelPhase: .seconds(2))++        #expect(ledger.held(for: "a.example") == nil)+        #expect(ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == .seconds(2))+    }++    @Test("A timeout marks the hostname attempted and charges the budget")+    func timeoutSettles() {+        let ledger = Self.settled("a.example", .timedOut,+                                  modelPhase: RuleSuggestionBounds.attemptTimeout)++        #expect(ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == RuleSuggestionBounds.attemptTimeout)+        #expect(ledger.inFlight == nil)+    }++    @Test("A system cancellation charges the budget but leaves the hostname attemptable")+    func cancellationSettles() {+        var ledger = Self.settled("a.example", .cancelled, modelPhase: .seconds(3))+        let restart = ledger.start(hostname: "a.example", origin: .background,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == .seconds(3))+        #expect(restart == .start)+    }++    @Test("A settled attempt with no sides is not held, but the hostname is attempted")+    func emptySuggestionIsNotHeld() {+        let ledger = Self.settled("a.example",+                                  .suggestion(RuleSuggestion(hostname: "a.example")),+                                  modelPhase: .seconds(2))++        #expect(ledger.held(for: "a.example") == nil)+        #expect(ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == .seconds(2))+        #expect(ledger.inFlight == nil)+    }++    @Test("Settling a hostname that is not the one in flight leaves the in-flight record alone")+    func staleSettleIsIgnored() {+        var ledger = Self.running("a.example")++        ledger.settle(hostname: "b.example", .cancelled, modelPhase: .seconds(1))++        #expect(ledger.inFlight?.hostname == "a.example")+        #expect(ledger.budgetSpent == .seconds(1))+    }++    // MARK: - Dismissal (Reqs 2.7, 2.8, 6.5)++    @Test("Dismissal is per side and per hostname")+    func dismissalIsPerSide() {+        var ledger = RuleSuggestionLedger()++        ledger.dismiss(hostname: "a.example", side: .title)++        #expect(ledger.isDismissed(hostname: "a.example", side: .title))+        #expect(!ledger.isDismissed(hostname: "a.example", side: .url))+        #expect(!ledger.isDismissed(hostname: "b.example", side: .title))+    }++    @Test("The Suggest action clears one side's dismissal")+    func dismissalCleared() {+        var ledger = RuleSuggestionLedger()+        ledger.dismiss(hostname: "a.example", side: .title)+        ledger.dismiss(hostname: "a.example", side: .url)++        ledger.clearDismissal(hostname: "a.example", side: .title)++        #expect(!ledger.isDismissed(hostname: "a.example", side: .title))+        #expect(ledger.isDismissed(hostname: "a.example", side: .url))+    }++    // MARK: - Invalidation (Req 5.5, Q18)++    @Test("Invalidation clears the held suggestion, the attempt and the fingerprint")+    func invalidateClearsRunState() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))++        let mustCancel = ledger.invalidate(hostname: "a.example")++        #expect(!mustCancel)+        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.fingerprints["a.example"] == nil)+        #expect(ledger.budgetSpent == .seconds(1))+    }++    @Test("Invalidation does not clear a dismissal (Req 2.8)")+    func invalidateKeepsDismissals() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))+        ledger.dismiss(hostname: "a.example", side: .title)++        ledger.invalidate(hostname: "a.example")++        #expect(ledger.isDismissed(hostname: "a.example", side: .title))+    }++    @Test("Invalidating the hostname in flight asks the caller to cancel it")+    func invalidateCancelsInFlight() {+        var ledger = Self.running("a.example")++        let running = ledger.invalidate(hostname: "a.example")+        let other = ledger.invalidate(hostname: "b.example")++        #expect(running)+        #expect(!other)+    }++    // MARK: - Voided attempts (Reqs 5.5, 5.6, Q54)++    @Test("A result that lands after invalidation is discarded, not held")+    func invalidatedAttemptCannotResurrectHeldState() {+        var ledger = Self.running("a.example")+        ledger.invalidate(hostname: "a.example")++        // The coordinator has asked for the cancellation, but the model+        // answered first: the answer is about a corpus that no longer exists.+        ledger.settle(hostname: "a.example", .suggestion(Self.suggestion("a.example")),+                      modelPhase: .seconds(3))++        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.fingerprints["a.example"] == nil)+        // Charged like any other ending (Req 5.2), and the slot is free again.+        #expect(ledger.budgetSpent == .seconds(3))+        #expect(ledger.inFlight == nil)+    }++    @Test("Every settlement for a voided attempt is treated as a cancellation",+          arguments: [AttemptSettlement.noSuggestion, .timedOut, .cancelled])+    func voidedAttemptSettlesAsCancelled(settlement: AttemptSettlement) {+        var ledger = Self.running("a.example")+        ledger.invalidate(hostname: "a.example")++        ledger.settle(hostname: "a.example", settlement, modelPhase: .seconds(1))++        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.budgetSpent == .seconds(1))+        #expect(ledger.inFlight == nil)+    }++    @Test("A result that lands after a memory warning is discarded, not held")+    func memoryWarningVoidsTheAttempt() {+        var ledger = Self.running("a.example")+        _ = ledger.memoryWarning()++        ledger.settle(hostname: "a.example", .suggestion(Self.suggestion("a.example")),+                      modelPhase: .seconds(2))++        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.inFlight == nil)+    }++    @Test("A result that lands after a reconcile mismatch is discarded, not held")+    func reconcileVoidsTheAttempt() {+        var ledger = Self.running("a.example")++        let invalidated = ledger.reconcile(against: ["a.example": Self.fingerprint(entryCount: 9)])+        ledger.settle(hostname: "a.example", .suggestion(Self.suggestion("a.example")),+                      modelPhase: .seconds(1))++        #expect(invalidated == ["a.example"])+        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+    }++    @Test("A voided attempt is not attached to; the reader's start pre-empts it instead",+          arguments: [Origin.open, .request])+    func voidedAttemptIsNotAttachedTo(origin: Origin) {+        var ledger = Self.running("a.example")+        ledger.invalidate(hostname: "a.example")++        let outcome = ledger.start(hostname: "a.example", origin: origin,+                                   fingerprint: Self.fingerprint(entryCount: 9),+                                   environment: Self.foreground)++        #expect(outcome == .preempt(hostname: "a.example"))+    }++    @Test("An untouched attempt still attaches")+    func liveAttemptStillAttaches() {+        var ledger = Self.running("a.example")+        ledger.invalidate(hostname: "b.example")++        let outcome = ledger.start(hostname: "a.example", origin: .open,+                                   fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(outcome == .attach)+    }++    // MARK: - Reconcile (Q43)++    @Test("A changed candidate row invalidates its hostname")+    func fingerprintMismatchInvalidates() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))++        let invalidated = ledger.reconcile(against: ["a.example": Self.fingerprint(entryCount: 4)])++        #expect(invalidated == ["a.example"])+        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+    }++    @Test("A newly stored rule version invalidates the hostname")+    func ruleVersionMismatchInvalidates() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))++        let invalidated = ledger.reconcile(+            against: ["a.example": Self.fingerprint(titleRuleVersion: 1)])++        #expect(invalidated == ["a.example"])+    }++    @Test("An unchanged candidate row invalidates nothing")+    func fingerprintMatchKeepsState() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))++        let invalidated = ledger.reconcile(against: ["a.example": Self.fingerprint()])++        #expect(invalidated.isEmpty)+        #expect(ledger.held(for: "a.example") != nil)+        #expect(ledger.isAttempted("a.example"))+    }++    @Test("A tracked hostname the library no longer reports is invalidated")+    func disappearedHostnameInvalidates() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))++        let invalidated = ledger.reconcile(against: [:])++        #expect(invalidated == ["a.example"])+        #expect(ledger.held(for: "a.example") == nil)+    }++    @Test("Tracked hostnames are the held, attempted and in-flight ones")+    func trackedHostnames() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))+        _ = ledger.start(hostname: "b.example", origin: .background,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)+        ledger.settle(hostname: "b.example", .noSuggestion, modelPhase: .seconds(1))+        _ = ledger.start(hostname: "c.example", origin: .open,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)+        ledger.dismiss(hostname: "d.example", side: .title)++        #expect(ledger.trackedHostnames == ["a.example", "b.example", "c.example"])+    }++    // MARK: - Memory warning (Req 5.6, Q50)++    @Test("A memory warning drops held suggestions, attempts and fingerprints, and cancels in flight")+    func memoryWarning() {+        var ledger = Self.settled("a.example", .suggestion(Self.suggestion("a.example")))+        ledger.dismiss(hostname: "a.example", side: .url)+        _ = ledger.start(hostname: "b.example", origin: .open,+                         fingerprint: Self.fingerprint(),+                         environment: Self.foreground)++        let toCancel = ledger.memoryWarning()++        #expect(toCancel == "b.example")+        #expect(ledger.held(for: "a.example") == nil)+        #expect(!ledger.isAttempted("a.example"))+        #expect(ledger.fingerprints.isEmpty)+        #expect(ledger.isDismissed(hostname: "a.example", side: .url))+        #expect(ledger.budgetSpent == .seconds(1))+    }++    @Test("A memory warning with nothing in flight asks for no cancellation")+    func memoryWarningWithoutAnAttempt() {+        var ledger = RuleSuggestionLedger()++        let toCancel = ledger.memoryWarning()++        #expect(toCancel == nil)+    }++    // MARK: - Resign active (Req 5.3, Q28)++    @Test("Resigning active cancels a background attempt and ends the sweep")+    func resignActiveCancelsBackground() {+        var ledger = Self.running("a.example", origin: .background)++        let toCancel = ledger.resignActive()++        #expect(toCancel == "a.example")+        #expect(!ledger.sweepActive)+        // The cancellation itself is settled by the coordinator, which leaves+        // the hostname attemptable.+        ledger.settle(hostname: "a.example", .cancelled, modelPhase: .seconds(1))+        #expect(!ledger.isAttempted("a.example"))+    }++    @Test("Resigning active leaves reader-initiated attempts running (Req 5.3)",+          arguments: [Origin.open, .request])+    func resignActiveLeavesReaderAttempts(origin: Origin) {+        var ledger = Self.running("a.example", origin: origin)++        let toCancel = ledger.resignActive()++        #expect(toCancel == nil)+        #expect(ledger.inFlight?.hostname == "a.example")+        #expect(!ledger.sweepActive)+    }++    // MARK: - Fingerprints++    @Test("A fingerprint is recorded when the attempt starts")+    func fingerprintRecordedAtStart() {+        var ledger = RuleSuggestionLedger()++        _ = ledger.start(hostname: "a.example", origin: .background,+                         fingerprint: Self.fingerprint(), environment: Self.foreground)++        #expect(ledger.fingerprints["a.example"] == Self.fingerprint())+    }++    @Test("An in-flight attempt is fingerprinted, so a matching reconcile leaves it alone")+    func inFlightFingerprintSurvivesReconcile() {+        var ledger = Self.running("a.example")++        let invalidated = ledger.reconcile(against: ["a.example": Self.fingerprint()])++        #expect(invalidated.isEmpty)+        #expect(ledger.inFlight?.voided == false)+    }++    @Test("A refused start records nothing")+    func refusedStartRecordsNothing() {+        var ledger = RuleSuggestionLedger()+        let environment = RuleSuggestionEnvironment(isActive: false, isLowPowerMode: false,+                                                    thermalState: .nominal)++        _ = ledger.start(hostname: "a.example", origin: .background,+                         fingerprint: Self.fingerprint(), environment: environment)++        #expect(ledger.fingerprints.isEmpty)+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismIntelligenceTests/StubRuleSuggestionModelClientTests.swift b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/StubRuleSuggestionModelClientTests.swiftnew file mode 100644index 0000000..c352e0a--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismIntelligenceTests/StubRuleSuggestionModelClientTests.swift@@ -0,0 +1,154 @@+import Foundation+import Testing++@testable import AsterismIntelligence++/// The stub is a test fixture, but the coordinator and suggester suites will+/// lean on it to assert "no model call" and to drive Req 3.7's halve-and-retry,+/// so its recording and scripting are worth pinning down here.+@Suite("StubRuleSuggestionModelClient")+struct StubRuleSuggestionModelClientTests {+    static func corpus(_ hostname: String = "example.net", contextCount: Int = 0) -> SuggestionCorpus {+        SuggestionCorpus(+            hostname: hostname,+            anchor: SuggestionExample(title: "Sylver Seeker - Chapter 12",+                                      rawURL: "https://example.net/sylver-seeker/12"),+            context: (0..<contextCount).map {+                SuggestionExample(title: "Sylver Seeker - Chapter \(11 - $0)",+                                  rawURL: "https://example.net/sylver-seeker/\(11 - $0)")+            })+    }++    static let proposal = RuleProposal(workName: "Sylver Seeker", chapterText: "Chapter 12",+                                       urlWorkIdentity: "sylver-seeker", urlSequenceText: "12")++    // MARK: - Call log++    @Test("Every corpus propose is given is recorded, in order")+    func recordsEveryCall() async throws {+        let client = StubRuleSuggestionModelClient(proposal: Self.proposal)++        _ = try await client.propose(Self.corpus("a.example"))+        _ = try await client.propose(Self.corpus("b.example"))++        #expect(client.recorder.callCount == 2)+        #expect(client.recorder.recordedCorpora.map(\.hostname) == ["a.example", "b.example"])+    }++    @Test("A client never asked for a proposal has recorded nothing")+    func recordsNothingWithoutACall() {+        let client = StubRuleSuggestionModelClient(proposal: Self.proposal)++        #expect(client.recorder.callCount == 0)+        #expect(client.recorder.recordedCorpora.isEmpty)+    }++    @Test("A failing call is recorded too")+    func recordsFailures() async {+        let client = StubRuleSuggestionModelClient(+            error: StubRuleSuggestionModelClientError.contextWindowOverflow)++        await #expect(throws: StubRuleSuggestionModelClientError.contextWindowOverflow) {+            _ = try await client.propose(Self.corpus())+        }++        #expect(client.recorder.callCount == 1)+    }++    @Test("Copies of the stub share one log: the coordinator's copy is the test's copy")+    func copiesShareTheRecorder() async throws {+        let client = StubRuleSuggestionModelClient(proposal: Self.proposal)+        let copy = client++        _ = try await copy.propose(Self.corpus("a.example"))++        #expect(client.recorder.callCount == 1)+    }++    // MARK: - Scripted results++    @Test("Scripted results are consumed in order and the last one repeats")+    func scriptIsConsumedInOrder() async throws {+        let second = RuleProposal(workName: "Deep Blue Sky")+        let client = StubRuleSuggestionModelClient(+            results: [.failure(StubRuleSuggestionModelClientError.contextWindowOverflow),+                      .success(second)])++        await #expect(throws: StubRuleSuggestionModelClientError.contextWindowOverflow) {+            _ = try await client.propose(Self.corpus(contextCount: 4))+        }+        let first = try await client.propose(Self.corpus(contextCount: 2))+        let repeated = try await client.propose(Self.corpus(contextCount: 2))++        #expect(first == second)+        #expect(repeated == second)+        #expect(client.recorder.recordedCorpora.map(\.context.count) == [4, 2, 2])+    }++    @Test("An empty script falls back to the canned error, then the canned proposal")+    func scriptFallsBackToTheCannedAnswers() async throws {+        let cannedOnly = StubRuleSuggestionModelClient(proposal: Self.proposal)+        let withError = StubRuleSuggestionModelClient(+            proposal: Self.proposal,+            error: StubRuleSuggestionModelClientError.noCannedProposal)++        #expect(try await cannedOnly.propose(Self.corpus()) == Self.proposal)+        await #expect(throws: StubRuleSuggestionModelClientError.noCannedProposal) {+            _ = try await withError.propose(Self.corpus())+        }+    }++    @Test("A stub with neither a script nor a canned proposal says so")+    func noCannedProposal() async {+        let client = StubRuleSuggestionModelClient()++        await #expect(throws: StubRuleSuggestionModelClientError.noCannedProposal) {+            _ = try await client.propose(Self.corpus())+        }+    }++    @Test("The delay still applies, and the call is logged before it")+    func delayStillApplies() async throws {+        let client = StubRuleSuggestionModelClient(proposal: Self.proposal,+                                                   delay: .milliseconds(20))++        let started = ContinuousClock.now+        _ = try await client.propose(Self.corpus())++        #expect(ContinuousClock.now - started >= .milliseconds(20))+        #expect(client.recorder.callCount == 1)+    }++    @Test("The stub reports the availability it was given")+    func availabilityIsScripted() {+        let client = StubRuleSuggestionModelClient(availability: .unavailable(reason: "test"))++        #expect(client.availability() == .unavailable(reason: "test"))+    }++    // MARK: - Overflow recognition (Req 3.7, Q56)++    @Test("The stub recognises its own overflow error through the protocol")+    func recognisesItsOwnOverflow() {+        let client: any RuleSuggestionModelClient = StubRuleSuggestionModelClient()++        #expect(client.isContextWindowOverflow(StubRuleSuggestionModelClientError+            .contextWindowOverflow))+        #expect(!client.isContextWindowOverflow(StubRuleSuggestionModelClientError+            .noCannedProposal))+        #expect(!client.isContextWindowOverflow(CancellationError()))+    }++    @Test("A client that says nothing about overflow never overflows")+    func defaultImplementationSaysNo() {+        struct SilentClient: RuleSuggestionModelClient {+            func availability() -> ModelAvailability { .available }+            func propose(_ corpus: SuggestionCorpus) async throws -> RuleProposal { RuleProposal() }+        }++        let client: any RuleSuggestionModelClient = SilentClient()++        #expect(!client.isContextWindowOverflow(StubRuleSuggestionModelClientError+            .contextWindowOverflow))+    }+}