Pre-push review: T-2273/character-ranking

diff --git a/Asterism/AsterismTests/WorkDetailCharacterTests.swift b/Asterism/AsterismTests/WorkDetailCharacterTests.swiftindex 287593e..66a1896 100644--- a/Asterism/AsterismTests/WorkDetailCharacterTests.swift+++ b/Asterism/AsterismTests/WorkDetailCharacterTests.swift@@ -77,12 +77,15 @@ struct WorkDetailCharacterTests {      @Test("The page shows the work's characters as the repository ordered them")     func showsCharactersInRepositoryOrder() async {+        // Seeded out of name order on purpose: alphabetical seeds would survive+        // a re-sort by name, so they could not tell the repository's prominence+        // order from one the page invented (Req 3.3).         let (model, _) = makeSUT(-            characters: [Self.character(name: "Ada"), Self.character(name: "Brede")])+            characters: [Self.character(name: "Brede"), Self.character(name: "Ada")])          await model.load() -        #expect(model.characters.map(\.name) == ["Ada", "Brede"])+        #expect(model.characters.map(\.name) == ["Brede", "Ada"])     }      // MARK: - Drafts (Req 3.2, Q97)

diff --git a/Asterism/AsterismUITests/CharacterExtractionUITests.swift b/Asterism/AsterismUITests/CharacterExtractionUITests.swiftindex fe12831..976d860 100644--- a/Asterism/AsterismUITests/CharacterExtractionUITests.swift+++ b/Asterism/AsterismUITests/CharacterExtractionUITests.swift@@ -106,6 +106,25 @@ final class CharacterExtractionUITests: XCTestCase {             .firstMatch     } +    /// The edit session's pill for one name. Labelled from the draft, so the+    /// label is the name exactly.+    ///+    /// Addressed by name rather than by position: `character-ranking` orders the+    /// cast by prominence on both reading surfaces and the edit session inherits+    /// that order, so which pill comes first is a property of the fixture's+    /// facts rather than of the alphabet. Under that order this fixture leads+    /// with Brede, whose one quote grounds in the generic notes *and* in the+    /// chapter note and so scores two buckets (`f(1) + f(1) = 2`) against Ada's+    /// one bucket of two generic facts (`log2 3 ≈ 1.585`).+    private func editPill(named name: String) -> XCUIElement {+        app.buttons+            .matching(+                NSPredicate(+                    format: "identifier == %@ AND label == %@",+                    "work-detail-character-edit-pill", name))+            .firstMatch+    }+     /// The alias chip carrying `name` on the open character card (Q14 of     /// `work-detail-reading-redesign`). Identifier *and* label: every alias on     /// the card is one identifier, so only the label says which one.@@ -357,7 +376,7 @@ final class CharacterExtractionUITests: XCTestCase {         // statement appears only once Ada's editor pill is opened.         let statement = app.staticTexts["Ada is called Nightjar by the crew."]         XCTAssertFalse(statement.exists, "Editors stay folded until their pill is tapped")-        openPill(app.buttons.matching(identifier: "work-detail-character-edit-pill").firstMatch)+        openPill(editPill(named: "Ada"))         waitFor(statement, "The fact's statement is shown in the editor")          // A tap on the statement text itself deletes nothing.

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 16a6452..1b393a3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,56 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).  ## [Unreleased] +### Changed++- **The work page and the share sheet list characters by prominence+  (character-ranking, phase 2, T-2273).** `workDetail` builds a+  `StoryPositionIndex` from the work's logical entries (duplicate rows+  are one position, placed by the group's composite pair) and+  `characterPresentations` ranks the cast through+  `rankedCharacterGroups`, reusing the decoded facts for the fact rows+  so a work-page open decodes each character once (Decision 4).+  `shareWorkContext` walks the work's rows once, builds the same index+  without the `excludingEntryID` exclusion, and computes the ranked cast+  before the notes read, so a failed notes read still returns it (Q15)+  and a re-share of the latest chapter keeps the order (Req 2.7); the+  exclusion applies only when selecting the noted candidate. Name order+  survives only as the tie-break and on entry detail, where a new+  regression test pins it. `sortedCharacterGroups` is deleted. In the+  seeded UI fixture Brede now outranks Ada — Q24's split bonus, since+  Brede's quote grounds in both the generic notes and the chapter note —+  so `CharacterExtractionUITests` addresses Ada's edit pill by name+  (Q42). The share read now decodes the cast's fact blobs; recorded, not+  budgeted (Q43). Tests in `WorkDetailReadTests`,+  `ShareWorkContextTests` and `CharacterEditingTests`. One+  `make test-performance-m4` run puts `character-ranking-200x50` at a+  2.55 ms median (p95 4.72 ms) against the 10 ms budget, with the+  target's eight known issues unchanged+  (`specs/character-ranking/verification-run.md`); share-sheet-characters+  Q1 now points at Decision 1. The feature is complete.++### Added++- **Core character ranking (character-ranking, phase 1, T-2273).**+  `StoryPositionIndex` assigns every entry of a work an ordinal distance+  from the latest chapter (unplaced entries first, ordered by capture+  time; equal placements share one position), and `CharacterRanking`+  scores a character's facts by bucketing them on that distance,+  `Σ 2^(-d/10) · log2(n+1)`, with generic, live and dangling buckets+  accumulated in a fixed order so the score is bit-identical under any+  input permutation. `rank(_:index:)` decodes each character's facts+  once and returns them with the group (Decision 4), zero-fact groups+  trail, and exact ties fall back to name order then UUID.+  `rankedCharacterGroups(_:index:)` replaced the name-only+  `sortedCharacterGroups`, which phase 2 deleted once both callers had+  moved onto the ranked order (Q31). `EntryGroup.placementInputs` and+  `storyPositionInputs(rows:)` build the index inputs, with a single-row+  fast path that skips the group merge (Q34). Tests in+  `CharacterRankingTests` (decay table pinned to 1 ulp, two 500-case+  seeded sweeps) and `GroupFetchTests`; a `character-ranking-200x50`+  measurement in `M4ScalePerformanceTests` times ordering alone against+  the Req 4.3 10 ms budget (Q41).+ ### Fixed  - **T-2295: Recent no longer shows a permanent "records could not be

diff --git a/CLAUDE.md b/CLAUDE.mdindex 3b83d3a..13838cd 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -43,7 +43,7 @@ invocations where a target exists. - `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 **two live Apple Intelligence calls** — one per pipeline, decoding into `RuleProposal` and (since `character-extraction`) into `ExtractionResult` — both of which degrade to a `withKnownIssue` when the host has no model available. On a host that does have the model, a transient `GenerationError` (rate limited, assets unavailable) is also a known issue — only a response that will not decode into the expected structure fails the target, so the pre-commit bar stays deterministic either way. - `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. **~21 minutes** (1,093 s of test time measured 2026-08-28, plus a ~190 s release build): most 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 the accepted breaches reported as `withKnownIssue` known issues rather than failures — **eight** since `drop-superseded-columns` (four before `multi-site-works`, nine after it). Four are long-standing: Req 10.1's settling pass and Req 5.5's three diagnosis re-derivations. Three are Req 5.4's capture-projection arms (0.093–0.102 s pre-V8 → 0.160–0.170 s, the one on a path the reader waits on). The eighth is the **full**-tier no-op reconcile, and V9 recovered most of it: 1.07 s → **0.0296–0.0302 s** once `V8PopulationPass` was deleted with the columns and `MembershipReconciler.heal` was gated on the diagnosis, which is still 3.0× a 10 ms ceiling drawn before the library had a membership table. Req 10.1's *observation* pass **retired** with that fall (2.69 s → 1.01 s, back inside its 2 s budget). Every one has a regression ceiling asserted *outside* its known-issue block, so a run that drifts further still fails; `RUNS=3` completes all three runs. See `specs/drop-superseded-columns/verification-run.md` for the current numbers, `specs/multi-site-works/verification-run.md` §4 and §7 for the previous ones, and `docs/agent-notes/testing.md` for recording a band.+- `make test-performance-m4` — M4 Core budgets, host only, no device, safe to run. **~21 minutes** (1,093 s of test time measured 2026-08-28, and 1,120 s over 28 tests on 2026-08-30 after `character-ranking` added its own, plus a ~190 s release build): most 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 the accepted breaches reported as `withKnownIssue` known issues rather than failures — **eight** since `drop-superseded-columns` (four before `multi-site-works`, nine after it). Four are long-standing: Req 10.1's settling pass and Req 5.5's three diagnosis re-derivations. Three are Req 5.4's capture-projection arms (0.093–0.102 s pre-V8 → 0.160–0.170 s, the one on a path the reader waits on). The eighth is the **full**-tier no-op reconcile, and V9 recovered most of it: 1.07 s → **0.0296–0.0302 s** once `V8PopulationPass` was deleted with the columns and `MembershipReconciler.heal` was gated on the diagnosis, which is still 3.0× a 10 ms ceiling drawn before the library had a membership table. Req 10.1's *observation* pass **retired** with that fall (2.69 s → 1.01 s, back inside its 2 s budget). Every one has a regression ceiling asserted *outside* its known-issue block, so a run that drifts further still fails; `RUNS=3` completes all three runs. See `specs/drop-superseded-columns/verification-run.md` for the current numbers, `specs/multi-site-works/verification-run.md` §4 and §7 for the previous ones, and `docs/agent-notes/testing.md` for recording a band. - `make test-performance-chunks` — host-only calibration sweep of the shared bulk chunk constant (import commits and the reconciler re-pin). No device, safe to run, but gated on `ASTERISM_RUN_CHUNK_SWEEP=1` and **~20 minutes per run**, so it is deliberately *not* part of `make test-performance-m4`. It asserts nothing — a calibration is reported, not budgeted. Re-run it when the bulk write paths change (Q53 and the task 25 section of `specs/cloudkit-mirroring/implementation.md`). - `make test-performance-m4-recent` — **physical device, see above** 

diff --git a/Packages/AsterismCore/Sources/AsterismCore/CharacterRanking.swift b/Packages/AsterismCore/Sources/AsterismCore/CharacterRanking.swiftnew file mode 100644index 0000000..cce5d38--- /dev/null+++ b/Packages/AsterismCore/Sources/AsterismCore/CharacterRanking.swift@@ -0,0 +1,289 @@+import Foundation++// The prominence order a work's characters are listed in (Reqs 1 and 2).+//+// Two pure types, derived on read from data the surfaces already hold: nothing+// is stored, no fetch is added, and both the work page and the share sheet rank+// the same way against the whole work (Decision 1). Internal rather than public+// because `CharacterGroup` holds SwiftData rows and is not `Sendable` (Q36);+// the tests reach them through `@testable import`.++/// Distance of every live entry from the end of the story (Req 2).+///+/// Distance is **ordinal**, not arithmetic (Q10): chapter keys are multi-part+/// and two placement scales exist, so subtracting one from another is+/// undefined. `d` counts the distinct story positions strictly after a+/// position, which makes the half-life an absolute count of positions rather+/// than a share of the work's length.+struct StoryPositionIndex {++    /// One live entry, as the two paths that build an index describe it: the+    /// work page from an `EntrySnapshot`, the share sheet from the rows it+    /// already walked. Never a row — duplicate rows of one entry are one+    /// logical entry and one position (Req 2.1).+    struct EntryInput {+        let id: UUID+        /// Nil where the work's rules number the entry not at all; such an+        /// entry sits before every placed one (Q13).+        let placement: ChapterPlacement?+        /// The earliest capture across the entry's rows (Q9, Q23). Never+        /// `lastSharedAt`: a re-share would move an old chapter to the front+        /// and revive a character who has left (Q3).+        let firstCapturedAt: Date+    }++    private let distances: [UUID: Int]++    /// Distance of the earliest position — where a dangling fact weighs+    /// (Q14) — and 0 for a work with no live entries (Req 2.6).+    let earliestDistance: Int++    /// Precondition: one input per logical entry. Asserted rather than+    /// deduplicated, because a caller handing over two inputs for one entry has+    /// projected rows instead of records, and silently keeping one of them+    /// would hide that.+    init(entries: [EntryInput]) {+        assert(+            Set(entries.map(\.id)).count == entries.count,+            "StoryPositionIndex takes one input per logical entry")++        var ordinals: [UUID: Int] = [:]+        ordinals.reserveCapacity(entries.count)+        var ordinal = -1+        var previous: ChapterPlacement?+        for entry in entries.sorted(by: Self.precedes) {+            // Every unplaced entry takes a new ordinal (each is its own+            // position, Req 2.3); a placed one takes a new ordinal only where+            // its placement differs from the one before it, so equal placements+            // share a position (Req 2.4).+            if let placement = entry.placement {+                if placement != previous { ordinal += 1 }+                previous = placement+            } else {+                ordinal += 1+            }+            ordinals[entry.id] = ordinal+        }++        let last = ordinal+        distances = ordinals.mapValues { last - $0 }+        earliestDistance = Swift.max(last, 0)+    }++    /// Nil when the entry is not live in the work — a dangling citation, which+    /// weighs as the earliest position rather than as no position at all.+    func distance(of entryID: UUID) -> Int? { distances[entryID] }++    /// Unplaced first by `(firstCapturedAt, id)`, then placed by the existing+    /// placement comparison. Total, so the walk above is deterministic whatever+    /// order the caller collected its entries in (Req 4.1).+    private static func precedes(_ lhs: EntryInput, _ rhs: EntryInput) -> Bool {+        switch (lhs.placement, rhs.placement) {+        case (nil, .some): return true+        case (.some, nil): return false+        case (.some(let left), .some(let right)) where left != right: return left < right+        default:+            if lhs.firstCapturedAt != rhs.firstCapturedAt {+                return lhs.firstCapturedAt < rhs.firstCapturedAt+            }+            // Uncased, the same rule `rank`'s own tie-break uses: `uuidString`+            // is always uppercase, so lowercasing changes nothing but invites+            // the two comparisons to drift apart.+            return lhs.id.uuidString < rhs.id.uuidString+        }+    }+}++/// What a character's facts are worth, and the order that follows (Req 1).+///+/// `Σ w(d) · f(n)` over the character's buckets: `w` decays with distance so a+/// character who has stopped appearing drifts down, and `f` is concave so+/// appearing in many chapters beats being described at length in one+/// (Decision 2).+enum CharacterRanking {++    /// `H`: the distance at which a fact is worth half (Q28). An absolute count+    /// of positions, never a share of the work's length (Q10).+    ///+    /// The decay table *is* the half-life — one entry per position in it — so+    /// this reads the table's length rather than standing beside it as a second+    /// constant that could disagree.+    static var halfLife: Int { decay.count }++    /// `f(n) = log2(n + 1)` — `f(1) = 1`, strictly increasing, `f(n)/n`+    /// strictly decreasing (Req 1.2, Q28). The one libm call left in the+    /// scoring, on small integers.+    static func perBucket(_ n: Int) -> Double { log2(Double(n + 1)) }++    /// `2^(-k/10)` for `k = 0…9`, correctly rounded, written out.+    ///+    /// A table rather than a `pow` call because Decision 3 rests on two devices+    /// summing identical profiles to identical bits, and a libm power of a+    /// rounded quotient is exactly the kind of thing that can differ by an ulp+    /// between OS versions. Scaling by a power of two is exact, so the whole+    /// decay is bit-identical everywhere by construction.+    private static let decay: [Double] = [+        1.0,+        0.9330329915368074,+        0.8705505632961241,+        0.8122523963562355,+        0.757858283255199,+        0.7071067811865476,+        0.6597539553864471,+        0.6155722066724582,+        0.5743491774985175,+        0.5358867312681466,+    ]++    /// `w(d) = 2^(-d/H)`. Zero far past any serial's length, where the exponent+    /// leaves `Double`'s range — which is why Req 1.1 partitions zero-fact+    /// characters by rule rather than by score (Q16).+    static func weight(distance: Int) -> Double {+        precondition(distance >= 0, "a story position's distance is never negative")+        return decay[distance % decay.count] * scalbn(1, -(distance / decay.count))+    }++    /// The character's prominence (Req 1.2).+    ///+    /// Facts are counted per bucket and never weighed individually: live facts+    /// by their entry's **distance** (so two entries at one placement share a+    /// bucket, Q33), the generic notes as one bucket at `d = 0` (Q5), and the+    /// dangling citations as one bucket at the earliest position (Q14). The+    /// three never merge (Q21).+    ///+    /// The sum is accumulated in a fixed evaluation sequence — ascending+    /// distance, and generic → live → dangling within one distance — because+    /// that is what makes two identical profiles produce the same `Double` to+    /// the last bit (Decision 3).+    static func score(facts: [CharacterFact], index: StoryPositionIndex) -> Double {+        var generic = 0+        var dangling = 0+        var live: [Int: Int] = [:]+        for fact in facts {+            switch fact.source {+            case .genericNotes:+                generic += 1+            case .entry(let entryID):+                if let distance = index.distance(of: entryID) {+                    live[distance, default: 0] += 1+                } else {+                    dangling += 1+                }+            }+        }++        // `tier` is the within-distance sequence; live buckets are keyed by+        // distance, so no two of them can collide on it.+        var buckets: [(distance: Int, tier: Int, count: Int)] = []+        buckets.reserveCapacity(live.count + 2)+        if generic > 0 { buckets.append((distance: 0, tier: 0, count: generic)) }+        for (distance, count) in live { buckets.append((distance: distance, tier: 1, count: count)) }+        if dangling > 0 {+            buckets.append((distance: index.earliestDistance, tier: 2, count: dangling))+        }+        buckets.sort {+            $0.distance == $1.distance ? $0.tier < $1.tier : $0.distance < $1.distance+        }++        var total = 0.0+        for bucket in buckets {+            total += weight(distance: bucket.distance) * perBucket(bucket.count)+        }+        return total+    }++    /// A character group and the facts decoded out of its stored blob — what+    /// the ranking takes and what it hands back (Decision 4).+    ///+    /// `CharacterAuthoredContent.facts` decodes on every access, so a caller+    /// that ranked and then read `presentedContent.facts` again would decode+    /// the whole cast twice on one work-page open. Carrying the facts out with+    /// the group makes the decode the ranking already pays the only one.+    struct RankedCharacter {+        let group: CharacterGroup+        let facts: [CharacterFact]+    }++    /// The one decode: every group's stored fact blob read out, before anything+    /// is scored.+    ///+    /// Split from `order` so Req 4.3's measurement can time the arithmetic it+    /// budgets rather than the `Codable` pass around it (Decision 4).+    static func decode(_ groups: [UUID: CharacterGroup]) -> [RankedCharacter] {+        groups.values.map { RankedCharacter(group: $0, facts: $0.presentedContent.facts) }+    }++    /// A character reduced to what the order needs, derived once per character+    /// rather than inside the comparator, which sees each one as many times as+    /// the sort compares it.+    ///+    /// Both entry points below build this and sort it with `precedes`, so the+    /// facts-carrying order and the names-only order cannot drift apart+    /// (Decision 1).+    private struct SortKey {+        let score: Double+        let nameKey: String+        let hasFacts: Bool+        let id: UUID+    }++    private static func sortKey(+        of group: CharacterGroup, facts: [CharacterFact], index: StoryPositionIndex+    ) -> SortKey {+        SortKey(+            score: facts.isEmpty ? 0 : score(facts: facts, index: index),+            nameKey: CharacterNameKey.normalize(group.presentedContent.name),+            hasFacts: !facts.isEmpty,+            id: group.id)+    }++    /// Descending score, then name order; every character with no presented+    /// facts last, in name order (Reqs 1.1, 1.6).+    ///+    /// The partition is a rule, not a floor: a fact far enough back for its+    /// weight to underflow still outranks a character nobody has noted anything+    /// about (Q16). Scores are compared with `<` and fall to name order only on+    /// a bit-exact `==` (Decision 3).+    private static func precedes(_ left: SortKey, _ right: SortKey) -> Bool {+        if left.hasFacts != right.hasFacts { return left.hasFacts }+        if left.hasFacts, left.score != right.score { return left.score > right.score }+        return left.nameKey == right.nameKey+            ? left.id.uuidString < right.id.uuidString+            : left.nameKey < right.nameKey+    }++    /// The order (Reqs 1.1, 1.6) over characters whose facts a caller already+    /// holds — the seam Req 4.3's measurement times (Decision 4).+    static func order(+        _ characters: [RankedCharacter], index: StoryPositionIndex+    ) -> [RankedCharacter] {+        let keys = characters.map { sortKey(of: $0.group, facts: $0.facts, index: index) }+        return zip(characters, keys).sorted { precedes($0.1, $1.1) }.map(\.0)+    }++    /// Decode once, then order (Reqs 1.1, 1.6) — what the work page calls, which+    /// draws the facts it carries out (Decision 4).+    static func rank(+        _ groups: [UUID: CharacterGroup], index: StoryPositionIndex+    ) -> [RankedCharacter] {+        order(decode(groups), index: index)+    }++    /// The same order for a caller that wants only the groups — the share+    /// sheet, which shows names and aliases (Q43).+    ///+    /// Each group's facts are decoded, scored and dropped before the next+    /// group's are read, so the extension never holds the whole cast's facts at+    /// once. The scoring and the ordering are `rank`'s, so the share sheet and+    /// the work page still answer with one order (Decision 1).+    static func rankGroups(+        _ groups: [UUID: CharacterGroup], index: StoryPositionIndex+    ) -> [CharacterGroup] {+        groups.values+            .map { group in+                (group, sortKey(of: group, facts: group.presentedContent.facts, index: index))+            }+            .sorted { precedes($0.1, $1.1) }+            .map(\.0)+    }+}

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Groups.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Groups.swiftindex 92bd774..524d2d4 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Groups.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+Groups.swift@@ -62,6 +62,18 @@ public struct EntryGroup {         authoredContent ?? variants.first?.content ?? .bare     } +    /// The two fields a chapter placement is derived from, composed the way+    /// `snapshot(_:)` composes them: the sequence from the row that supplies+    /// capture evidence, the title from the row that holds the content+    /// (`character-ranking` Q30).+    ///+    /// Non-throwing, which is the point: the share read ranks its cast before+    /// anything that can fail, and snapshotting every group to place it would+    /// let one corrupt row take the whole cast down with it.+    internal var placementInputs: (chapterSequence: String?, chapterTitle: String?) {+        (representative.chapterSequence, carrier.chapterTitle)+    }+     /// Member timestamps (Definitions): the earliest first capture, the latest     /// share, the latest modification across the group's rows.     public var firstCapturedAt: Date { rows.map(\.firstCapturedAt).min() ?? .distantPast }@@ -252,6 +264,55 @@ extension LibraryRepository {         }     } +    /// The rows as one story-position input per logical entry+    /// (`character-ranking` Req 2.1), for the share path, which holds rows+    /// rather than snapshots.+    ///+    /// **A single-row bucket takes a fast path** (Q34): its row is its own+    /// representative and its own carrier, so the pair is the row's own two+    /// fields and nothing has to be grouped. Grouping every row would run+    /// `authoredContent(of:)` — a citation-blob decode — once per row of a+    /// 500-chapter work inside the share extension, to answer a question that+    /// only a duplicated entry can make interesting.+    ///+    /// Non-throwing, so the ranked cast survives a failure anywhere else in the+    /// share read (Q32).+    internal static func storyPositionInputs(rows: [Entry]) -> [StoryPositionIndex.EntryInput] {+        storyPositionInputs(buckets: Dictionary(grouping: rows, by: \.id))+    }++    /// The same, over buckets the caller has already built. The share read needs+    /// the rows bucketed twice — once for this index, once to find the last+    /// note's candidates — so it buckets once and hands them to both.+    internal static func storyPositionInputs(+        buckets: [UUID: [Entry]]+    ) -> [StoryPositionIndex.EntryInput] {+        buckets.compactMap { id, rows in+            guard rows.count > 1 else {+                let row = rows[0]+                return StoryPositionIndex.EntryInput(+                    id: id,+                    placement: ChapterPlacement.of(+                        chapterSequence: row.chapterSequence, chapterTitle: row.chapterTitle),+                    firstCapturedAt: row.firstCapturedAt)+            }+            guard let group = entryGroup(id: id, rows: rows, canonicalWorkIDs: [:]) else {+                // Unreachable: `entryGroup` returns nil only for an empty row+                // list, and this bucket holds more than one. Asserted rather+                // than silently dropped, because an entry missing from the+                // index is a character quietly ranked as dangling.+                assertionFailure("a bucket of rows must group into an entry")+                return nil+            }+            let pair = group.placementInputs+            return StoryPositionIndex.EntryInput(+                id: id,+                placement: ChapterPlacement.of(+                    chapterSequence: pair.chapterSequence, chapterTitle: pair.chapterTitle),+                firstCapturedAt: group.firstCapturedAt)+        }+    }+     internal static func workGroups(         _ rows: [Work], types: WorkTypeDirectory     ) -> [UUID: WorkGroup] {

diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+WorkDetail.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+WorkDetail.swiftindex ce0a19b..9705707 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+WorkDetail.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+WorkDetail.swift@@ -73,9 +73,10 @@ public struct WorkDetailPresentation: Sendable, Equatable {     public let lastNotedURLString: String?     /// Newest-first by `lastSharedAt`, the app's own ordering (§7).     public let chapterRows: [WorkChapterRow]-    /// `character-extraction` Reqs 5.1/5.2: the work's characters, in name-    /// order, with their facts in Q88's display order and their citations-    /// already resolved.+    /// `character-extraction` Reqs 5.1/5.2: the work's characters, in the+    /// prominence order `character-ranking` Req 1 defines — name order only+    /// between equals and among the characters nothing is noted about — with+    /// their facts in Q88's display order and their citations already resolved.     ///     /// Read in the same locked context as everything else here, never by a     /// second call: two surfaces answering the same question independently is@@ -182,6 +183,31 @@ extension LibraryRepository {                 uniquingKeysWith: { first, _ in first })             let dates = Dictionary(                 entries.map { ($0.id, $0.lastSharedAt) }, uniquingKeysWith: { first, _ in first })+            // Where each of the work's live entries sits in the story, which is+            // what the character ranking decays against (`character-ranking`+            // Req 2). Built from `entries` — the logical-entry projection the+            // rows above are drawn from — so duplicate rows of one entry are+            // one position (Req 2.1), and from `firstCapturedAt` rather than+            // the `lastSharedAt` `captureOrder` keys on, so re-sharing an old+            // chapter does not move it to the end of the story (Q9).+            //+            // The placement comes from the row's two derived fields rather than+            // from `ChapterPlacement.of`, which would re-parse the sequence and+            // the title this function has already parsed into them. The two+            // initialisers agree by construction: `position` yields a key only+            // where the sequence's first number group is *not* a chapter+            // number, and `chapterKey` takes that group where it is — so the+            // sequence branch, the title branch and the unplaced case all land+            // on the same case either way.+            let storyPositions = StoryPositionIndex(+                entries: zip(entries, rows).map { entry, row in+                    StoryPositionIndex.EntryInput(+                        id: entry.id,+                        placement: ChapterPlacement(+                            sequencePosition: row.sequencePosition,+                            chapterKey: row.chapterKey),+                        firstCapturedAt: entry.firstCapturedAt)+                })             // From the group's own rows, not a whole-table fetch filtered down             // to this work: the answer is identical (an orphan is unreachable             // through the inverse exactly as it failed the `work?.id` filter),@@ -197,7 +223,7 @@ extension LibraryRepository {                 lastNotedURLString: entries.first?.rawURLString,                 chapterRows: rows,                 characters: Self.characterPresentations(-                    Self.characterGroups(characterRows),+                    Self.characterGroups(characterRows), index: storyPositions,                     captureOrder: captureOrder, titles: titles, dates: dates, keys: keys),                 captureOrder: captureOrder)         }

diff --git a/Packages/AsterismCore/Sources/AsterismCore/ShareWorkContext.swift b/Packages/AsterismCore/Sources/AsterismCore/ShareWorkContext.swiftindex 77f5c98..981b8ad 100644--- a/Packages/AsterismCore/Sources/AsterismCore/ShareWorkContext.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/ShareWorkContext.swift@@ -9,8 +9,9 @@ import SwiftData // Derived here rather than in the extension for the reason sharesheet-polish Q6 // records for every other row of that card: the extension lays text out, it does // not decide what the text says. It also keeps the order one answer — the share-// row and the work page sort the same groups through `sortedCharacterGroups`,-// and the last note is selected the way the work page orders its chapters.+// row and the work page rank the same groups through `CharacterRanking`,+// against the whole work on both (Decision 1 of `character-ranking`), and the+// last note is selected the way the work page orders its chapters.  /// `captureLogger` is file-private to `LibraryRepository+Capture.swift`, so the /// notes half's own failure line gets its own logger of the same shape, as@@ -205,11 +206,31 @@ extension LibraryRepository {     ) throws -> ShareWorkContext {         let works = try context.fetch(FetchDescriptor<Work>(predicate: #Predicate { $0.id == id }))         guard !works.isEmpty else { return .empty }-        let characters = sortedCharacterGroups(characterGroups(characterRows(of: works)))-            .map { group in-                let content = group.presentedContent-                return ShareCharacter(name: content.name, aliases: content.aliases)-            }+        // Every row of every Work row of the group, walked once and shared by+        // both halves. No exclusion: the ranking needs the whole work, and the+        // notes half applies `excludingEntryID` where it selects (Q32).+        let allRows = works.flatMap(\.entryValues)+        // Bucketed once, for both halves: the index below is one input per+        // logical entry, and the last-note selection walks the same buckets to+        // find the ones that could carry an answer.+        let rowsByID = Dictionary(grouping: allRows, by: \.id)+        // The work page's order, from the work page's inputs: every live entry+        // of the work, whatever chapter is being shared (Req 2.7). Ranked here,+        // above the `do`, and out of parts that cannot throw — the row walk, the+        // index, the scoring — so a failure in the notes half below costs the+        // notes and not the cast (`share-sheet-characters` Q15).+        let storyPositions = StoryPositionIndex(entries: storyPositionInputs(buckets: rowsByID))+        // `rankGroups`, not `rank`: this sheet draws names and aliases, so a+        // character's facts are decoded, scored and dropped before the next+        // character's are read rather than the whole cast's being held at once+        // (Q43). The order is `rank`'s own.+        let characters = CharacterRanking.rankGroups(+            characterGroups(characterRows(of: works)), index: storyPositions+        )+        .map { group in+            let content = group.presentedContent+            return ShareCharacter(name: content.name, aliases: content.aliases)+        }          do {             // One row is its own carrier, so the group has nothing to decide and@@ -237,30 +258,35 @@ extension LibraryRepository {                     characters: characters, workNote: workNote, lastNote: nil)             } -            // Only the rows that could carry an answer are grouped. A candidate+            // The same buckets the index was built from, read a second time —+            // this time to find the ones that could carry an answer. A candidate             // is a group whose *carrier* has a note, and the carrier is one of-            // the group's own rows — so a UUID whose every row is blank can-            // never yield one, and neither can the excluded entry. Dropping-            // those buckets before `entryGroups` is a superset filter: it-            // changes what is walked, never what is selected. The rest of the-            // qualification — the carrier's note, the placement — stays below,-            // where the carrier is known.-            var byID: [UUID: [Entry]] = [:]-            for row in works.flatMap(\.entryValues) where row.id != excludingEntryID {-                byID[row.id, default: []].append(row)-            }-            let noted = byID.values.filter { rows in+            // the group's own rows, so a UUID whose every row is blank can never+            // yield one. Dropping those buckets before `entryGroups` is a+            // superset filter: it changes what is walked, never what is+            // selected. The rest of the qualification — the exclusion, the+            // carrier's note, the placement — stays below, where the carrier is+            // known, so the filter has one job and the selection states the+            // whole rule.+            let noted = rowsByID.values.filter { rows in                 rows.contains { !$0.note.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }             }             // Pure over the rows already faulted in: `entryGroups` builds no             // snapshots, so a corrupt row elsewhere in the work cannot fail the             // walk. Only the selected group is snapshotted, below.             let groups = Self.entryGroups(noted.flatMap { $0 }, canonicalWorkIDs: [:])+            // Where `excludingEntryID` applies: the entry the re-share sheet is+            // editing is a live entry of the work, so the ranking above counts+            // it (Req 2.7) and only the note the editor already holds is+            // dropped.+            //             // Every candidate placed by its carrier — the row whose note this             // would show — so the note and the position it claims come from one-            // row. An unplaced entry never qualifies; equal placement is not-            // "before", so a duplicate of the chapter being shared cannot show-            // its own note back to the reader.+            // row. Deliberately not `placementInputs`, which composes a split+            // group's placement from two rows for the index (Q35). An unplaced+            // entry never qualifies; equal placement is not "before", so a+            // duplicate of the chapter being shared cannot show its own note+            // back to the reader.             let candidates = groups.values.compactMap { group -> (EntryGroup, ChapterPlacement)? in                 guard group.id != excludingEntryID,                     !group.carrier.note.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,

diff --git a/Packages/AsterismCore/Sources/AsterismCore/WorkCharacterPresentation.swift b/Packages/AsterismCore/Sources/AsterismCore/WorkCharacterPresentation.swiftindex f4655b7..aede203 100644--- a/Packages/AsterismCore/Sources/AsterismCore/WorkCharacterPresentation.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/WorkCharacterPresentation.swift@@ -108,42 +108,55 @@ public struct WorkCharacterPresentation: Identifiable, Sendable, Equatable { extension LibraryRepository {      /// The one order a work's characters are listed in, wherever they are listed-    /// (Q9): by the presented name normalised, UUID as the tie-break so two-    /// devices draw one list.+    /// (Decision 1): by prominence against the whole work, name order as the+    /// tie-break and as the whole answer for characters with no facts.     ///-    /// Sorting the *groups* rather than the presentations is what lets the share-    /// sheet share it — the share row carries no facts, so it has no-    /// `WorkCharacterPresentation` to sort.-    internal static func sortedCharacterGroups(-        _ groups: [UUID: CharacterGroup]-    ) -> [CharacterGroup] {-        // The key is normalised once per group rather than inside the-        // comparator, which sees each group as many times as the sort compares it.-        let keyed: [(key: String, group: CharacterGroup)] = groups.values.map { group in-            (key: CharacterNameKey.normalize(group.presentedContent.name), group: group)-        }-        return keyed.sorted { left, right in-            left.key == right.key-                ? left.group.id.uuidString < right.group.id.uuidString-                : left.key < right.key-        }.map(\.group)+    /// It **replaced** the name-only `sortedCharacterGroups` rather than sitting+    /// beside it (Q31) — the two surfaces agreeing is the Q9 contract, and a+    /// second function is an invitation to call the wrong one. `index` is built+    /// from the same work's live entries on both paths.+    ///+    /// Ordering the *groups* rather than the presentations is what lets the+    /// share sheet share the order — the share row carries no facts, so it has+    /// no `WorkCharacterPresentation` to sort. The sheet reaches it through+    /// `CharacterRanking.rankGroups`, which is this order with the facts+    /// dropped rather than carried out (Q43); the two are one comparator.+    ///+    /// Each group comes back with its facts already decoded (Decision 4): the+    /// ranking has to decode the stored blob to score it, so it hands the+    /// result on rather than leaving `characterPresentations` to decode the+    /// same 200 blobs a second time.+    internal static func rankedCharacterGroups(+        _ groups: [UUID: CharacterGroup], index: StoryPositionIndex+    ) -> [CharacterRanking.RankedCharacter] {+        CharacterRanking.rank(groups, index: index)     } -    /// The work's characters as the page draws them, in name order.+    /// The work's characters as the page draws them, in prominence order.+    ///+    /// `index` places the work's live entries in the story, which is what the+    /// ranking decays against (`character-ranking` Req 2); it is built from the+    /// same read's entries, so the share sheet ranking the same work reaches the+    /// same order (Req 3.1).     ///     /// `captureOrder` maps a live entry's UUID to its position oldest-first,     /// `titles` to what that entry is called, `dates` to when it was captured,     /// and `keys` to its chapter key where the rules number it. All four come-    /// from the same locked read as the characters themselves.+    /// from the same locked read as the characters themselves. `captureOrder` is+    /// the fact *list's* order (Q88) and takes no part in the ranking: within a+    /// character the list is a note history, between characters the order is+    /// story prominence (Q19).     internal static func characterPresentations(         _ groups: [UUID: CharacterGroup],+        index: StoryPositionIndex,         captureOrder: [UUID: Int],         titles: [UUID: String],         dates: [UUID: Date] = [:],         keys: [UUID: ChapterKey] = [:]     ) -> [WorkCharacterPresentation] {-        sortedCharacterGroups(groups)-            .map { group in+        rankedCharacterGroups(groups, index: index)+            .map { ranked in+                let group = ranked.group                 let content = group.presentedContent                 return WorkCharacterPresentation(                     id: group.id,@@ -151,8 +164,12 @@ extension LibraryRepository {                     note: content.note,                     aliases: content.aliases,                     nameKey: group.carrier.nameKey,+                    // `ranked.facts`, never `content.facts`: the ranking has+                    // already decoded this group's stored blob, and reading the+                    // property again would decode the whole cast a second time+                    // on every work-page open (Decision 4).                     facts: factRows(-                        content.facts, captureOrder: captureOrder, titles: titles, dates: dates,+                        ranked.facts, captureOrder: captureOrder, titles: titles, dates: dates,                         keys: keys),                     isTorn: group.isTorn,                     rowCount: group.rows.count,

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterEditingTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterEditingTests.swiftindex 68dd457..d93f2db 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterEditingTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterEditingTests.swift@@ -14,6 +14,7 @@ private let workB = UUID(uuidString: "1A000000-0000-4000-8000-00000000000B")! private let entry1 = UUID(uuidString: "1A000000-0000-4000-8000-000000000101")! private let alex = UUID(uuidString: "1A000000-0000-4000-8000-000000000201")! private let terawatt = UUID(uuidString: "1A000000-0000-4000-8000-000000000202")!+private let alexTen = UUID(uuidString: "1A000000-0000-4000-8000-000000000203")!  private func fact(     _ statement: String, _ quote: String, _ source: SourceRef, key: String@@ -514,6 +515,50 @@ struct CharacterWorkIntegrationTests {         withExtendedLifetime(fixture) {}     } +    /// `character-ranking` Req 3.4 / Q8: the prominence order the work page and+    /// the share sheet moved to deliberately stops at this list, which stays in+    /// the name order `localizedStandardCompare` defines.+    ///+    /// The fixture makes both of the orders it is *not* observably wrong here,+    /// so a switch fails rather than passes by coincidence:+    ///+    /// - Terawatt cites the entry three times and carries a generic-notes fact+    ///   besides, so a ranked list would put it first rather than last.+    /// - "Alex 2" and "Alex 10" order that way only under+    ///   `localizedStandardCompare`; a plain `<` on the names puts "Alex 10"+    ///   first.+    @Test("Characters citing an entry stay in name order, not prominence order")+    func entryDetailKeepsNameOrder() async throws {+        let fixture = try await twoWorks()+        try await fixture.repository.seedM5Rows(characters: [+            M5SeedCharacter(+                id: terawatt, name: "Terawatt", nameKey: "terawatt",+                facts: [+                    fact("Leads", "Alex is Terawatt", .entry(entry1), key: "terawatt"),+                    fact("Fights", "Alex is", .entry(entry1), key: "terawatt"),+                    fact("Wins", "Terawatt", .entry(entry1), key: "terawatt"),+                    fact("Named", "source notes", .genericNotes, key: "terawatt"),+                ],+                workID: workA),+            M5SeedCharacter(+                id: alexTen, name: "Alex 10", nameKey: "alex10",+                facts: [fact("Arrives", "Alex is", .entry(entry1), key: "alex10")],+                workID: workA),+            M5SeedCharacter(+                id: alex, name: "Alex 2", nameKey: "alex2",+                facts: [fact("Arrives", "Alex is", .entry(entry1), key: "alex2")],+                workID: workA),+        ])++        let detail = try await fixture.repository.entryTeachingDetail(id: entry1)+        #expect(detail.citingCharacters.map(\.name) == ["Alex 2", "Alex 10", "Terawatt"],+                "the list is ordered by name, not by how much the entry says about whom")+        #expect(detail.citingCharacters.map(\.id) == [alex, alexTen, terawatt])+        #expect(detail.citingCharacters.map(\.factCount) == [1, 1, 3],+                "the count is of this entry's citations, and the generic-notes fact is not one")+        withExtendedLifetime(fixture) {}+    }+     @Test("An entry nothing cites carries no citing characters")     func entryDetailIsEmptyWhereNothingCites() async throws {         let fixture = try await twoWorks()

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterRankingTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterRankingTests.swiftnew file mode 100644index 0000000..578b204--- /dev/null+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/CharacterRankingTests.swift@@ -0,0 +1,557 @@+import Foundation+import Testing++@testable import AsterismCore++/// The two halves of the prominence order: where a live entry sits on the+/// story's decay axis (Req 2), and what a character's facts are worth against+/// that axis (Req 1).+///+/// Everything here is pure — no store, no container — because the ranking is:+/// it reads an entry's placement and first capture, never a row.+@Suite("Character ranking")+struct CharacterRankingTests {++    private static let epoch = Date(timeIntervalSince1970: 1_800_000_000)++    /// One live entry, placed the way the read paths place one: through the+    /// existing derivation rather than a hand-built `ChapterPlacement`, so a+    /// change to that derivation shows up here.+    private func input(+        _ id: UUID = UUID(), sequence: String? = nil, title: String? = nil,+        capturedAfter seconds: TimeInterval = 0+    ) -> StoryPositionIndex.EntryInput {+        StoryPositionIndex.EntryInput(+            id: id,+            placement: ChapterPlacement.of(chapterSequence: sequence, chapterTitle: title),+            firstCapturedAt: Self.epoch.addingTimeInterval(seconds))+    }++    // MARK: - Story positions (Req 2)++    /// Req 2.4: the *placement comparison* decides what "the same position"+    /// means, so two chapters it treats as equal are one distance step — not+    /// two, which would give a character who noted both an extra bucket.+    @Test("Entries the placement comparison treats as equal share one position (2.4)")+    func equalPlacementsShareOnePosition() {+        let first = UUID()+        let second = UUID()+        let latest = UUID()+        let index = StoryPositionIndex(entries: [+            input(first, title: "Chapter 7"),+            input(second, title: "Chapter 7: The Duel"),+            input(latest, title: "Chapter 8"),+        ])++        #expect(index.distance(of: latest) == 0)+        #expect(index.distance(of: first) == 1)+        #expect(index.distance(of: second) == 1)+        #expect(index.earliestDistance == 1)+    }++    /// Q20: `ChapterKey` equality includes the label by design, so `007` and `7`+    /// are two chapters that happen to number the same. The ranking inherits+    /// that rather than introducing a second notion of equality for a+    /// one-step difference.+    @Test("007 and 7 are two adjacent positions (Q20)")+    func differentlyWrittenNumbersAreAdjacent() {+        let padded = UUID()+        let bare = UUID()+        let index = StoryPositionIndex(entries: [+            input(padded, sequence: "007"),+            input(bare, sequence: "7"),+        ])++        // "007" < "7" on the label, so the padded spelling is the earlier of+        // the two positions.+        #expect(index.distance(of: bare) == 0)+        #expect(index.distance(of: padded) == 1)+        #expect(index.earliestDistance == 1)+    }++    /// Q25: every sequence-position placement precedes every chapter-key+    /// placement, inherited as-is from the spine's order.+    @Test("A sequence position sorts before every chapter key (Q25)")+    func positionsPrecedeKeys() {+        let positioned = UUID()+        let keyed = UUID()+        let index = StoryPositionIndex(entries: [+            // Past the chapter-number limit, so the sequence is a site-wide id.+            input(positioned, sequence: "123456"),+            input(keyed, title: "Chapter 3"),+        ])++        #expect(index.distance(of: keyed) == 0)+        #expect(index.distance(of: positioned) == 1)+    }++    /// Req 2.3: an unplaced entry has no place on the chapter scale, so it sits+    /// before everything that has one, and each is its own position — a reader+    /// with three unnumbered notes has three steps of history, not one.+    @Test("Unplaced entries precede every placed one, ordered by first capture (2.3)")+    func unplacedEntriesComeFirstInCaptureOrder() {+        let oldest = UUID()+        let middle = UUID()+        let newest = UUID()+        let placed = UUID()+        let index = StoryPositionIndex(entries: [+            input(placed, title: "Chapter 2"),+            input(newest, title: "an unnumbered note", capturedAfter: 120),+            input(oldest, title: "another unnumbered note", capturedAfter: 0),+            input(middle, title: "a third unnumbered note", capturedAfter: 60),+        ])++        #expect(index.distance(of: placed) == 0)+        #expect(index.distance(of: newest) == 1)+        #expect(index.distance(of: middle) == 2)+        #expect(index.distance(of: oldest) == 3)+        #expect(index.earliestDistance == 3)+    }++    /// The second half of Req 2.3's ordering: entries captured in the same+    /// instant — which a bulk import produces — still order totally, on the+    /// entry identifier.+    @Test("Unplaced entries captured together order by identifier (2.3)")+    func unplacedEntriesTieBreakOnIdentifier() {+        let first = UUID(uuidString: "00000000-0000-4000-8000-000000000001")!+        let second = UUID(uuidString: "00000000-0000-4000-8000-000000000002")!+        let index = StoryPositionIndex(entries: [+            input(second, title: "note two"),+            input(first, title: "note one"),+        ])++        #expect(index.distance(of: second) == 0)+        #expect(index.distance(of: first) == 1)+    }++    @Test("An entry that is not live in the work has no distance")+    func unknownEntryHasNoDistance() {+        let live = UUID()+        let index = StoryPositionIndex(entries: [input(live, title: "Chapter 1")])++        #expect(index.distance(of: live) == 0)+        #expect(index.distance(of: UUID()) == nil)+    }++    /// Req 2.6: a work with no live entries has no latest and no earliest+    /// position, and the index says so with a zero rather than an absence the+    /// scorer would have to branch on.+    @Test("An empty index has distance nil everywhere and earliestDistance 0 (2.6)")+    func emptyIndexIsZeroed() {+        let index = StoryPositionIndex(entries: [])++        #expect(index.earliestDistance == 0)+        #expect(index.distance(of: UUID()) == nil)+    }++    // MARK: - Fixtures for the scorer++    private func fact(_ source: SourceRef, _ quote: String) -> CharacterFact {+        CharacterFact(+            statement: "what \(quote) says", quote: quote,+            nameKey: CharacterNameKey.normalize("Ada"), source: source)+    }++    /// `count` **distinct** facts citing one source. Distinct because a fact's+    /// identity is `(name key, source, quote)`, so a repeated quote would be+    /// one fact wearing two statements.+    private func facts(_ count: Int, citing source: SourceRef, tag: String = "") -> [CharacterFact] {+        (0..<count).map { fact(source, "quote \($0)\(tag) of \(source.orderToken)") }+    }++    private func group(_ name: String, _ facts: [CharacterFact], id: UUID = UUID()) -> CharacterGroup {+        let record = CharacterRecord(+            id: id, name: name, nameKey: CharacterNameKey.normalize(name), facts: facts,+            timestamp: Self.epoch)+        // Nil only for an empty row list, which this never passes.+        return LibraryRepository.characterGroup(id: id, rows: [record])!+    }++    private func rankedNames(_ groups: [CharacterGroup], index: StoryPositionIndex) -> [String] {+        let keyed = Dictionary(uniqueKeysWithValues: groups.map { ($0.id, $0) })+        return CharacterRanking.rank(keyed, index: index).map(\.group.presentedContent.name)+    }++    private func score(_ facts: [CharacterFact], _ index: StoryPositionIndex) -> Double {+        CharacterRanking.score(facts: facts, index: index)+    }++    /// A chapter-per-entry index: the returned `ids[d]` is the entry whose+    /// distance is `d`, which is what the bucket fixtures below need.+    private func chapterIndex(positions: Int) -> (index: StoryPositionIndex, ids: [UUID]) {+        let ids = (0..<positions).map { _ in UUID() }+        let inputs = ids.enumerated().map { distance, id in+            input(id, title: "Chapter \(positions - distance)")+        }+        return (StoryPositionIndex(entries: inputs), ids)+    }++    // MARK: - The curve (Req 1.2, Decision 3)++    /// Decision 3: the decay is a ten-literal table scaled by a power of two,+    /// so it makes no libm call whose rounding could differ between devices.+    ///+    /// The reference here *does* make one, and that is why the band widens past+    /// the table itself: `pow(2, -d/10)` computes a power of the **rounded**+    /// quotient `-d/10`, whose error grows with `d` — up to four ulps by+    /// `d = 99`. The ten literals are pinned to one ulp against the same+    /// reference, where the quotient is small enough for that error to vanish.+    @Test("The decay table is 2^(-d/H), and H is 10 (1.2, Decision 3)")+    func decayTableMatchesThePowerOfTwo() {+        #expect(CharacterRanking.halfLife == 10)+        #expect(CharacterRanking.weight(distance: 0) == 1.0)+        // Exactly half a half-life away, by construction rather than by libm.+        #expect(CharacterRanking.weight(distance: 10) == 0.5)+        #expect(CharacterRanking.weight(distance: 20) == 0.25)++        for k in 0..<CharacterRanking.halfLife {+            let reference = pow(2.0, -Double(k) / 10.0)+            #expect(+                abs(CharacterRanking.weight(distance: k) - reference) <= reference.ulp,+                "table entry \(k) is more than one ulp from 2^(-\(k)/10)")+        }+        for distance in 0..<100 {+            let reference = pow(2.0, -Double(distance) / 10.0)+            #expect(+                abs(CharacterRanking.weight(distance: distance) - reference) <= 4 * reference.ulp,+                "weight(\(distance)) is more than four ulps from 2^(-\(distance)/10)")+        }+    }++    /// Req 1.2's conditions on `f`, pinned on the chosen one (Q28).+    @Test("f(n) = log2(n + 1) is 1 at one fact, rising, with f(n)/n falling (1.2)")+    func perBucketCurve() {+        #expect(CharacterRanking.perBucket(1) == 1.0)+        for n in 1..<64 {+            #expect(CharacterRanking.perBucket(n) < CharacterRanking.perBucket(n + 1))+            #expect(+                CharacterRanking.perBucket(n + 1) / Double(n + 1)+                    < CharacterRanking.perBucket(n) / Double(n))+        }+    }++    // MARK: - Buckets (Req 2.5, 2.6)++    /// Req 2.4 and 2.5 together: two entries the placement comparison calls+    /// equal are one position, so facts citing either land in **one** bucket.+    /// Two facts in one bucket are `f(2) = log2 3`, not `2 · f(1)`.+    @Test("Two entries at one placement contribute one bucket (2.4, 2.5)")+    func factsAtOnePlacementShareABucket() {+        let first = UUID()+        let second = UUID()+        let index = StoryPositionIndex(entries: [+            input(first, title: "Chapter 7"),+            input(second, title: "Chapter 7: The Duel"),+        ])++        let scored = score([fact(.entry(first), "one"), fact(.entry(second), "two")], index)++        #expect(scored == log2(3.0))+    }++    /// Req 2.5: the generic-notes bucket sits at `d = 0` and never merges with+    /// the live bucket there — they are different sources, and merging would+    /// make a fact's worth depend on whether the reader wrote it on the work or+    /// on a chapter (Q21).+    @Test("The generic bucket stays separate from the live bucket at d = 0 (2.5)")+    func genericFactsFormTheirOwnBucket() {+        let latest = UUID()+        let index = StoryPositionIndex(entries: [input(latest, title: "Chapter 1")])++        let split = score([fact(.genericNotes, "one"), fact(.entry(latest), "two")], index)+        let merged = score(facts(2, citing: .entry(latest)), index)++        #expect(split == 2.0)+        #expect(merged == log2(3.0))+        #expect(split > merged)+    }++    /// Q14: a citation whose entry is gone weighs as the earliest live+    /// position — the *oldest* thing the work still holds — and forms its own+    /// bucket there.+    @Test("A dangling fact weighs as the earliest position, in its own bucket (2.5)")+    func danglingFactsWeighAsTheEarliestPosition() {+        let (index, ids) = chapterIndex(positions: 3)+        #expect(index.earliestDistance == 2)++        let dangling = score([fact(.entry(UUID()), "gone")], index)+        #expect(dangling == CharacterRanking.weight(distance: 2))++        // Beside a live fact at the same distance it stays a second bucket.+        let separate = score(+            [fact(.entry(ids[2]), "live"), fact(.entry(UUID()), "gone")], index)+        let together = score(facts(2, citing: .entry(ids[2])), index)+        #expect(separate == 2 * CharacterRanking.weight(distance: 2))+        #expect(separate > together)+    }++    /// Req 2.6: with no live entries there is no scale, so every bucket sits at+    /// `d = 0` — and the two source buckets are still two.+    @Test("A work with no live entries scores every bucket at d = 0 (2.6)")+    func aWorkWithNoLiveEntriesScoresAtZero() {+        let index = StoryPositionIndex(entries: [])++        let scored = score(+            facts(2, citing: .genericNotes) + facts(3, citing: .entry(UUID())), index)++        #expect(scored == log2(3.0) + log2(4.0))+    }++    /// Q24: `f(n)/n` strictly decreasing means split buckets score more than+    /// the same facts in one, and the spec accepts that. Asserted so the bonus+    /// is stated rather than discovered.+    @Test("Facts split across two sources outscore the same count in one (Q24)")+    func theSplitBonusIsStated() {+        let latest = UUID()+        let index = StoryPositionIndex(entries: [input(latest, title: "Chapter 1")])++        let split = score(+            facts(5, citing: .genericNotes) + facts(5, citing: .entry(latest)), index)+        let whole = score(facts(10, citing: .entry(latest)), index)++        #expect(split == 2 * log2(6.0))+        #expect(whole == log2(11.0))+        #expect(split > whole)+    }++    // MARK: - The order (Req 1)++    /// Req 1.3: at one distance the fact count decides, and equal counts score+    /// **exactly** equally — which is what makes the name-order tie-break the+    /// only thing left to decide between them.+    @Test("At one distance more facts score higher and equal counts score alike (1.3)")+    func factCountDecidesAtOneDistance() {+        let (index, ids) = chapterIndex(positions: 4)++        let many = score(facts(4, citing: .entry(ids[2])), index)+        let few = score(facts(2, citing: .entry(ids[2]), tag: "b"), index)+        let alsoFew = score(facts(2, citing: .entry(ids[2]), tag: "c"), index)++        #expect(many > few)+        #expect(few == alsoFew)+    }++    /// Req 1.4, in its Q22 form: equal bucket profiles, one of them uniformly+    /// closer to the end of the story.+    @Test("Equal profiles rank by closeness to the latest position (1.4)")+    func closerProfilesRankHigher() {+        let (index, ids) = chapterIndex(positions: 8)+        let closer = group(+            "zoe",+            facts(3, citing: .entry(ids[1])) + facts(2, citing: .entry(ids[4]), tag: "b"))+        let further = group(+            "ada",+            facts(3, citing: .entry(ids[2])) + facts(2, citing: .entry(ids[5]), tag: "b"))++        #expect(rankedNames([further, closer], index: index) == ["zoe", "ada"])+    }++    /// Req 1.5: the half-life is an absolute count of positions, so `n` facts+    /// at the latest position beat `2n` a half-life back however long the work+    /// is — here proved at two work lengths.+    @Test("n facts now beat 2n facts a half-life back, at any work length (1.5)")+    func theHalfLifeIsAbsolute() {+        for positions in [11, 400] {+            let (index, ids) = chapterIndex(positions: positions)+            let recent = group("zoe", facts(3, citing: .entry(ids[0])))+            let old = group("ada", facts(6, citing: .entry(ids[CharacterRanking.halfLife])))++            #expect(rankedNames([old, recent], index: index) == ["zoe", "ada"])+        }+    }++    /// Req 1.8: the fixture that constrains `f` and `H` jointly — breadth over+    /// ten recent chapters beats one dense chapter (Q26).+    @Test("2 facts in each of ten recent chapters beat 30 in one (1.8)")+    func breadthBeatsDensity() {+        let (index, ids) = chapterIndex(positions: 12)+        let broad = group(+            "zoe", (0...9).flatMap { facts(2, citing: .entry(ids[$0]), tag: "b\($0)") })+        let dense = group("ada", facts(30, citing: .entry(ids[3])))++        #expect(rankedNames([dense, broad], index: index) == ["zoe", "ada"])+    }++    /// Req 1.1: characters with no presented facts follow every character with+    /// one, by rule rather than by score — including the one case a numeric+    /// floor could not separate, a fact so far back that its weight has+    /// underflowed to zero (Q16).+    @Test("Zero-fact characters trail every scored one, even a zero-scoring one (1.1)")+    func zeroFactCharactersTrail() throws {+        let (index, ids) = chapterIndex(positions: 3)+        let scored = group("zoe", facts(1, citing: .entry(ids[0])))+        let empty = group("ada", [])+        #expect(rankedNames([scored, empty], index: index) == ["zoe", "ada"])++        // Far enough back that `2^(-d/10)` is no longer representable.+        let underflowed = 10_760+        let ids2 = (0...underflowed).map { _ in UUID() }+        let deep = StoryPositionIndex(+            entries: ids2.enumerated().map { offset, id in+                input(id, title: "an unnumbered note", capturedAfter: TimeInterval(offset))+            })+        let oldest = try #require(ids2.first)+        #expect(CharacterRanking.weight(distance: try #require(deep.distance(of: oldest))) == 0)+        let zeroScored = group("zoe", facts(1, citing: .entry(oldest)))+        #expect(rankedNames([zeroScored, empty], index: deep) == ["zoe", "ada"])+    }++    /// Reqs 1.6 and 1.7: name order is what is left when the scores agree, and+    /// it is the whole answer for a work nobody has noted anything about.+    @Test("Equal scores and empty works fall back to name order (1.6, 1.7)")+    func tiesFallBackToNameOrder() {+        let (index, ids) = chapterIndex(positions: 2)+        let zoe = group("Zoe", facts(2, citing: .entry(ids[0])))+        let ada = group("Ada", facts(2, citing: .entry(ids[0]), tag: "b"))+        #expect(rankedNames([zoe, ada], index: index) == ["Ada", "Zoe"])++        let noFacts = [group("Zoe", []), group("Ada", []), group("The Bear", [])]+        // Name order is the *normalised* name (the existing one), so "The Bear"+        // keys as "bear" and sorts between the two rather than at the front+        // where its display spelling would put it.+        #expect(rankedNames(noFacts, index: index) == ["Ada", "The Bear", "Zoe"])+    }++    // MARK: - Determinism (Req 4.1)++    /// A deterministic 64-bit generator, so the sweeps below are the same 500+    /// cases on every run and on every machine. Seeded fuzzing is regression+    /// cover, not a proof — and it says nothing about "every supported device",+    /// which a host test cannot reach.+    private struct SplitMix64: RandomNumberGenerator {+        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)+        }+    }++    @Test("Permuting facts and entries changes neither score nor order (4.1)")+    func permutingTheInputsChangesNothing() {+        var rng = SplitMix64(seed: 0x1234_5678_9ABC_DEF0)++        for _ in 0..<500 {+            var inputs: [StoryPositionIndex.EntryInput] = []+            for position in 0..<Int.random(in: 0...8, using: &rng) {+                let placed = Bool.random(using: &rng)+                inputs.append(+                    input(+                        UUID(),+                        title: placed ? "Chapter \(position + 1)" : "an unnumbered note",+                        capturedAfter: TimeInterval(Int.random(in: 0...3, using: &rng) * 60)))+            }+            let live = inputs.map(\.id)++            var groups: [CharacterGroup] = []+            for character in 0..<Int.random(in: 1...5, using: &rng) {+                var made: [CharacterFact] = []+                for ordinal in 0..<Int.random(in: 0...6, using: &rng) {+                    let source: SourceRef+                    switch Int.random(in: 0...3, using: &rng) {+                    case 0: source = .genericNotes+                    case 1: source = .entry(UUID())  // dangling+                    default:+                        source = live.isEmpty+                            ? .genericNotes : .entry(live.randomElement(using: &rng)!)+                    }+                    made.append(fact(source, "quote \(character)-\(ordinal)"))+                }+                groups.append(group("character \(character)", made))+            }++            let index = StoryPositionIndex(entries: inputs)+            let permutedIndex = StoryPositionIndex(entries: inputs.shuffled(using: &rng))+            let scores = groups.map { score($0.presentedContent.facts, index) }+            let permutedScores = groups.map {+                score($0.presentedContent.facts.shuffled(using: &rng), permutedIndex)+            }+            // Bit-identical, not approximately equal: the comparator falls to+            // name order on exact `==`, so anything less would reorder.+            #expect(scores == permutedScores)++            // Only the index is permuted: `rank` takes a dictionary keyed by+            // character id, so there is no group order for a caller to hand+            // over differently and nothing a shuffle here would exercise.+            let order = rankedNames(groups, index: index)+            #expect(order == rankedNames(groups, index: permutedIndex))++            // Whatever the scores came out as, the empty characters are the tail.+            let scoredCount = groups.filter { !$0.presentedContent.facts.isEmpty }.count+            let scoredNames = Set(+                groups.filter { !$0.presentedContent.facts.isEmpty }.map(\.presentedContent.name))+            #expect(Set(order.prefix(scoredCount)) == scoredNames)+        }+    }++    /// Req 1.4 as a metamorphic property: one bucket moved one position closer,+    /// everything else held, always scores strictly higher.+    @Test("Moving one bucket a position closer strictly raises the score (1.4)")+    func movingABucketCloserRaisesTheScore() {+        var rng = SplitMix64(seed: 0x0FED_CBA9_8765_4321)+        let (index, ids) = chapterIndex(positions: 12)+        // Two `continue`s below can skip a case without asserting anything, so+        // the sweep counts what it actually exercised. Without this an+        // always-skipping draw would pass silently.+        var exercised = 0++        for _ in 0..<500 {+            var occupied: Set<Int> = []+            var made: [CharacterFact] = []+            for _ in 0..<Int.random(in: 1...4, using: &rng) {+                let distance = Int.random(in: 0..<ids.count, using: &rng)+                guard occupied.insert(distance).inserted else { continue }+                made += facts(+                    Int.random(in: 1...5, using: &rng), citing: .entry(ids[distance]),+                    tag: "d\(distance)")+            }+            // The target has to be unoccupied: moving a bucket onto another+            // merges the two, and `f(a) + f(b) > f(a + b)` means a merge can+            // *lower* the score. That is Decision 2's intent, not a violation+            // of 1.4, which is why Q22 narrowed the requirement.+            guard let moving = occupied.filter({ $0 > 0 && !occupied.contains($0 - 1) }).min()+            else { continue }++            let before = score(made, index)+            let after = score(+                made.map {+                    $0.source == .entry(ids[moving]) ? $0.citing(.entry(ids[moving - 1])) : $0+                }, index)+            #expect(after > before)+            exercised += 1+        }++        #expect(exercised > 400, "the sweep skipped too many draws to be evidence of anything")+    }++    /// Req 1.6's last step: two characters whose *names* key alike and whose+    /// scores are bit-equal still order, on the group identifier — the same+    /// uncased `uuidString` comparison `StoryPositionIndex` uses for its own+    /// tie-break.+    @Test("Characters with one name key and equal scores order by identifier (1.6)")+    func equalKeysAndScoresFallToTheIdentifier() {+        let (index, ids) = chapterIndex(positions: 2)+        // The existing normalisation drops a leading article, so these two+        // display differently and key identically.+        #expect(CharacterNameKey.normalize("The Bear") == CharacterNameKey.normalize("bear"))++        let low = UUID(uuidString: "00000000-0000-4000-8000-000000000001")!+        let high = UUID(uuidString: "FFFFFFFF-0000-4000-8000-000000000002")!+        let article = group("The Bear", facts(2, citing: .entry(ids[0])), id: high)+        let bare = group("bear", facts(2, citing: .entry(ids[0]), tag: "b"), id: low)++        // Equal profiles, so the scores agree to the last bit and neither the+        // score nor the key can decide.+        #expect(+            score(article.presentedContent.facts, index)+                == score(bare.presentedContent.facts, index))+        #expect(rankedNames([article, bare], index: index) == ["bear", "The Bear"])+        // And the answer does not depend on which one the caller listed first.+        #expect(rankedNames([bare, article], index: index) == ["bear", "The Bear"])+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/GroupFetchTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/GroupFetchTests.swiftindex b4bad1f..80612b9 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/GroupFetchTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/GroupFetchTests.swift@@ -261,3 +261,111 @@ private final class GroupStore {      func commit() throws { try context.save() } }++// MARK: - Story position inputs (character-ranking Reqs 2.1, 3.1)++/// The seam that keeps the two ranked surfaces agreeing: the work page places an+/// entry from the snapshot the group projects, and the share extension places it+/// from the rows themselves, without snapshotting (Q30, Q34). Both have to land+/// on the same pair.+@Suite("Story position inputs", .serialized)+struct StoryPositionInputTests {++    /// Q30: the placement pair is `(representative.chapterSequence,+    /// carrier.chapterTitle)` — the pair `snapshot(_:)` composes, read without+    /// throwing so one corrupt row cannot fail a whole share read.+    @Test("A split group's placement pair is the one the snapshot composes")+    func placementInputsMatchTheSnapshot() throws {+        let store = try GroupStore()+        let id = UUID()+        // The representative is decided by capture evidence and the carrier by+        // which row holds the authored content, so these are two different rows+        // disagreeing about both halves of the pair.+        let base = store.addEntry(id: id, captureTitle: "aaa")+        base.chapterSequence = "10"+        base.chapterTitle = "Chapter 10"+        let carried = store.addEntry(id: id, captureTitle: "zzz")+        carried.chapterSequence = "20"+        carried.chapterTitle = "Chapter 20"+        carried.editCitations { $0.chapterTitle = .manual }+        try store.commit()++        let group = try LibraryRepository.fetchEntryGroup(+            id: id, context: store.context, canonicalWorkIDs: [:])+        #expect(group.representative === base)+        #expect(group.carrier === carried)++        let pair = group.placementInputs+        #expect(pair.chapterSequence == "10")+        #expect(pair.chapterTitle == "Chapter 20")++        let snapshot = try LibraryRepository.snapshot(group)+        #expect(pair.chapterSequence == snapshot.chapterSequence)+        #expect(pair.chapterTitle == snapshot.chapterTitle)+    }++    /// Q34's fast path: one row is its own representative and its own carrier,+    /// so the input comes straight off it and no citation blob is decoded.+    @Test("A single-row entry yields its own fields verbatim")+    func singleRowInputsComeFromTheRow() throws {+        let store = try GroupStore()+        let id = UUID()+        let row = store.addEntry(id: id, captureTitle: "Chapter", offset: 300)+        row.chapterSequence = "5"+        row.chapterTitle = "Chapter 5"+        try store.commit()++        let inputs = LibraryRepository.storyPositionInputs(rows: [row])++        #expect(inputs.count == 1)+        #expect(inputs[0].id == id)+        #expect(+            inputs[0].placement+                == ChapterPlacement.of(chapterSequence: "5", chapterTitle: "Chapter 5"))+        #expect(inputs[0].firstCapturedAt == row.firstCapturedAt)+    }++    /// A duplicated entry is one logical entry and one story position (Req 2.1),+    /// placed by the composite pair and dated by the earliest of its rows (Q23).+    @Test("A multi-row entry yields one input, composite and row-minimum")+    func multiRowInputsGoThroughTheGroup() throws {+        let store = try GroupStore()+        let id = UUID()+        let base = store.addEntry(id: id, captureTitle: "aaa", offset: 600)+        base.chapterSequence = "10"+        base.chapterTitle = "Chapter 10"+        let carried = store.addEntry(id: id, captureTitle: "zzz", offset: 60)+        carried.chapterSequence = "20"+        carried.chapterTitle = "Chapter 20"+        carried.editCitations { $0.chapterTitle = .manual }+        try store.commit()++        let inputs = LibraryRepository.storyPositionInputs(rows: [carried, base])++        #expect(inputs.count == 1)+        #expect(+            inputs[0].placement+                == ChapterPlacement.of(chapterSequence: "10", chapterTitle: "Chapter 20"))+        #expect(inputs[0].firstCapturedAt == carried.firstCapturedAt)+        #expect(inputs[0].firstCapturedAt < base.firstCapturedAt)+    }++    /// The precondition `StoryPositionIndex` asserts: rows bucket into logical+    /// entries first, so a work whose rows outnumber its entries still gets one+    /// input each.+    @Test("Rows bucket into one input per entry identifier")+    func oneInputPerIdentifier() throws {+        let store = try GroupStore()+        let duplicated = UUID()+        let single = UUID()+        let first = store.addEntry(id: duplicated, captureTitle: "aaa")+        let second = store.addEntry(id: duplicated, captureTitle: "zzz")+        let other = store.addEntry(id: single, captureTitle: "mmm")+        try store.commit()++        let inputs = LibraryRepository.storyPositionInputs(rows: [first, other, second])++        #expect(inputs.count == 2)+        #expect(Set(inputs.map(\.id)) == [duplicated, single])+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/M4ScalePerformanceTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/M4ScalePerformanceTests.swiftindex 28b1a5c..9134f65 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/M4ScalePerformanceTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/M4ScalePerformanceTests.swift@@ -46,6 +46,10 @@ struct M4ScalePerformanceTests {     private let completePreviewBudget = Duration.seconds(1)     private let captureBudget = Duration.milliseconds(100)     private let extensionOpenBudget = Duration.seconds(1)+    /// `character-ranking` Req 4.3: the budget, and the regression ceiling that+    /// is asserted whatever happens to the budget (Q27).+    private let characterRankingBudget = Duration.milliseconds(10)+    private let characterRankingCeiling = Duration.milliseconds(50)     private let iterations = 20      // MARK: - Preview budgets (driving ComposedTeachingProjectionPlanner)@@ -115,6 +119,45 @@ struct M4ScalePerformanceTests {             "capture-rule-application", PerformanceDistribution(samples), captureBudget)     } +    // MARK: - Character ranking budget (character-ranking Req 4.3)++    /// The ranker on its own, over the shape Req 4.3 names: 200 characters with+    /// 50 facts each against a 500-entry story-position index.+    ///+    /// Both the index and the fact-blob decode are hoisted out of the timed+    /// region, and for the same reason: a read path builds the index once, and+    /// under Decision 4 it decodes each character's facts once and shares them+    /// with `characterPresentations`. What is timed is `order` — the scoring+    /// and the sort, which is the "ranking function alone" Req 4.3 budgets.+    ///+    /// Timing `rank` instead measured 0.0399 s, of which 0.0364 s was+    /// `CharacterAuthoredContent.facts` decoding and canonically ordering the+    /// 200 stored blobs and **0.0016 s** the arithmetic. That is a `Codable`+    /// pass, not a ranking cost, and Decision 4 removed the second one rather+    /// than recording a permanent known issue against a budget it was never+    /// drawn for.+    ///+    /// Q27 budgets the ranker rather than the work-detail read: no existing+    /// measurement covers that read, so a band for it would be a number with+    /// nothing to compare against.+    @Test("Ranking 200 characters × 50 facts over 500 entries ≤ 10 ms (4.3)")+    func characterRankingAtScale() {+        let fixture = CharacterRankingFixture()+        let decoded = CharacterRanking.decode(fixture.groups)+        #expect(+            decoded.count == 200 && decoded.allSatisfy { $0.facts.count == 50 },+            "the fixture must present the Req 4.3 shape, or the measurement is of nothing")++        let measured = measureDistribution(iterations: iterations) {+            _ = CharacterRanking.order(decoded, index: fixture.index)+        }+        expectWithinBudget("character-ranking-200x50", measured, characterRankingBudget)+        // The regression ceiling of Q27, asserted alongside the budget rather+        // than in place of it: the budget is what the requirement asks for, the+        // ceiling is what catches a drift that has not yet reached it.+        expectWithinCeiling("character-ranking-200x50", measured, characterRankingCeiling)+    }+     // MARK: - Extension open + validate budget (Req 8.5)      @Test("Extension open + validate ≤ 1 s (title-derivation replay included)")@@ -630,3 +673,65 @@ final class M4ConsolidationStore {         try? FileManager.default.removeItem(at: root)     } }++// MARK: - Fixture: the Req 4.3 ranking shape++/// 200 characters with 50 facts each over a 500-entry story-position index —+/// the shape `character-ranking` Req 4.3 budgets.+///+/// In-memory rather than seeded on disk: the ranker takes character groups and+/// an index, never a store, so a fixture that opened a container would time+/// SwiftData rather than the ranking. The rows are unmanaged `CharacterRecord`s+/// for the same reason.+///+/// The distribution is deliberately mixed, so the measurement covers every+/// bucket kind the scorer can build: two generic-notes facts and two dangling+/// ones per character, twenty clustered over five chapters — the dense-chapter+/// shape — and the remaining twenty-six spread across the work.+struct CharacterRankingFixture {+    private static let epoch = Date(timeIntervalSince1970: 1_800_000_000)++    let index: StoryPositionIndex+    let groups: [UUID: CharacterGroup]++    init(entryCount: Int = 500, characterCount: Int = 200, factsPerCharacter: Int = 50) {+        let entryIDs = (0..<entryCount).map { _ in UUID() }+        let inputs = entryIDs.enumerated().map { position, id in+            StoryPositionIndex.EntryInput(+                id: id,+                // Every twenty-fifth note is unnumbered, which is what puts+                // unplaced entries — their own position each — in the walk.+                placement: position.isMultiple(of: 25)+                    ? nil+                    : ChapterPlacement.of(+                        chapterSequence: nil, chapterTitle: "Chapter \(position + 1)"),+                firstCapturedAt: Self.epoch.addingTimeInterval(TimeInterval(position * 60)))+        }+        index = StoryPositionIndex(entries: inputs)++        var built: [UUID: CharacterGroup] = [:]+        built.reserveCapacity(characterCount)+        for character in 0..<characterCount {+            let id = UUID()+            let name = "Character \(character)"+            let key = CharacterNameKey.normalize(name)+            let facts = (0..<factsPerCharacter).map { ordinal -> CharacterFact in+                let source: SourceRef+                switch ordinal {+                case 0, 1: source = .genericNotes+                case 2, 3: source = .entry(UUID())  // dangling+                case ..<24: source = .entry(entryIDs[(character * 7 + ordinal % 5) % entryCount])+                default: source = .entry(entryIDs[(character * 37 + ordinal * 11) % entryCount])+                }+                return CharacterFact(+                    statement: "statement \(ordinal) about \(name)",+                    quote: "quote \(ordinal) about \(name)",+                    nameKey: key, source: source)+            }+            let record = CharacterRecord(+                id: id, name: name, nameKey: key, facts: facts, timestamp: Self.epoch)+            built[id] = LibraryRepository.characterGroup(id: id, rows: [record])+        }+        groups = built+    }+}

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/ShareWorkContextTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/ShareWorkContextTests.swiftindex 4da0169..082f6bb 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/ShareWorkContextTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/ShareWorkContextTests.swift@@ -143,6 +143,9 @@ struct ShareWorkContextReadTests {     private static let bob = UUID(uuidString: "1F000000-0000-4000-8000-00000000000B")!     private static let zedFirst = UUID(uuidString: "1F000000-0000-4000-8000-000000000C01")!     private static let zedSecond = UUID(uuidString: "1F000000-0000-4000-8000-000000000C02")!+    private static let ana = UUID(uuidString: "1F000000-0000-4000-8000-00000000000C")!+    private static let zara = UUID(uuidString: "1F000000-0000-4000-8000-00000000000D")!+    private static let cora = UUID(uuidString: "1F000000-0000-4000-8000-00000000000E")!     private static let orphan = UUID(uuidString: "1F000000-0000-4000-8000-00000000000F")!      private static let oldest = UUID(uuidString: "1F000000-0000-4000-8000-0000000000E1")!@@ -184,39 +187,165 @@ struct ShareWorkContextReadTests {             currentChapterSequence: anchorSequence, currentChapterTitle: anchorTitle)     } -    // MARK: - The cast (T-1916)+    // MARK: - The cast (T-1916, `character-ranking` Reqs 1–3)++    /// One fact, spelt out so a fixture reads as a profile rather than as four+    /// string literals. `nameKey` is the character's own: the ranking counts a+    /// group's presented facts, whatever they are keyed under.+    private static func fact(_ name: String, _ statement: String, citing source: SourceRef)+        -> CharacterFact+    {+        CharacterFact(+            statement: statement, quote: "\(name) \(statement)",+            nameKey: name.lowercased(), source: source)+    } -    @Test("The work's characters come back in normalised name order, UUID as the tie-break")+    @Test("The work's characters come back in prominence order, shared with the work page")     func charactersAreOrderedLikeTheWorkPage() async throws {-        let fixture = try await seeded(characters: [-            // Two names whose raw order and normalised order disagree, so the-            // assertion cannot pass on a plain string sort.-            M5SeedCharacter(id: Self.bob, name: "Bob", workID: Self.workID),-            M5SeedCharacter(-                id: Self.alice, name: "alice", aliases: ["Ally", "Al"], workID: Self.workID),-            // Same normalised name, distinct UUIDs: the tie-break decides.-            M5SeedCharacter(id: Self.zedSecond, name: "Zed", workID: Self.workID),-            M5SeedCharacter(id: Self.zedFirst, name: "Zed", workID: Self.workID),-        ])+        let fixture = try await seeded(+            entries: [+                M5SeedEntry(+                    id: Self.oldest, captureTitle: "One", hostname: "c.example", path: "one",+                    chapterSequence: "1", workID: Self.workID),+                M5SeedEntry(+                    id: Self.newest, captureTitle: "Two", hostname: "c.example", path: "two",+                    chapterSequence: "2", workID: Self.workID),+            ],+            characters: [+                // Two names whose raw order and normalised order disagree, so+                // the tie-break cannot pass on a plain string sort — and a+                // chapter apart, so the decay decides between them before the+                // names get a turn.+                M5SeedCharacter(+                    id: Self.bob, name: "Bob", nameKey: "bob",+                    facts: [Self.fact("Bob", "carries the rope", citing: .entry(Self.newest))],+                    workID: Self.workID),+                M5SeedCharacter(+                    id: Self.alice, name: "alice", nameKey: "alice", aliases: ["Ally", "Al"],+                    facts: [Self.fact("alice", "waits on the pier", citing: .entry(Self.oldest))],+                    workID: Self.workID),+                // Same normalised name and the same profile, distinct UUIDs:+                // the scores are bit-equal, so only the tie-break can separate+                // them. Distinct aliases make which one came first visible.+                M5SeedCharacter(+                    id: Self.zedSecond, name: "Zed", nameKey: "zed", aliases: ["Younger"],+                    facts: [+                        Self.fact("Zed", "rows the tender", citing: .entry(Self.newest)),+                        Self.fact("Zed", "keeps the lamp", citing: .entry(Self.newest)),+                    ],+                    workID: Self.workID),+                M5SeedCharacter(+                    id: Self.zedFirst, name: "Zed", nameKey: "zed", aliases: ["Zeta"],+                    facts: [+                        Self.fact("Zed", "rows the tender", citing: .entry(Self.newest)),+                        Self.fact("Zed", "keeps the lamp", citing: .entry(Self.newest)),+                    ],+                    workID: Self.workID),+                // Nothing noted about her: below every scored character,+                // whatever her name would say (Req 1.1).+                M5SeedCharacter(id: Self.cora, name: "Cora", nameKey: "cora", workID: Self.workID),+            ])          let characters = try await context(fixture).characters+        // Name order would read alice, Bob, Cora, Zed, Zed — so nothing here+        // passes on the sort the ranking replaced.         #expect(characters == [-            ShareCharacter(name: "alice", aliases: ["Al", "Ally"]),+            ShareCharacter(name: "Zed", aliases: ["Zeta"]),+            ShareCharacter(name: "Zed", aliases: ["Younger"]),             ShareCharacter(name: "Bob"),-            ShareCharacter(name: "Zed"),-            ShareCharacter(name: "Zed"),+            ShareCharacter(name: "alice", aliases: ["Al", "Ally"]),+            ShareCharacter(name: "Cora"),         ])         #expect(             ShareCharacterRow.text(for: characters)-                == "Characters: alice (Al, Ally), Bob, Zed, Zed")+                == "Characters: Zed (Zeta), Zed (Younger), Bob, alice (Al, Ally), Cora") -        // The claim that matters: one order, shared with the page (Q9).+        // The claim that matters: one order, shared with the page (Q9,+        // `character-ranking` Req 3.1).         let detail = try await fixture.repository.workDetail(id: Self.workID)         #expect(detail.characters.map(\.name) == characters.map(\.name))         #expect(detail.characters.map(\.aliases) == characters.map(\.aliases))         withExtendedLifetime(fixture) {}     } +    /// Two chapters and a cast that ranks the other way round from its names:+    /// Zara is noted twice in the latest chapter, Ana twice in the one before+    /// it, so the decay puts Zara first where a name sort would put Ana there.+    ///+    /// Both entries carry notes, so the notes half has something to select and+    /// a case about the cast is not quietly a case about an empty work.+    private func rankedCast(workNote: String = "") async throws -> M5Fixture {+        try await seeded(+            works: [+                M5SeedWork(+                    id: Self.workID, displayTitle: "A Serial", hostname: "c.example",+                    genericNotes: workNote)+            ],+            entries: [+                M5SeedEntry(+                    id: Self.oldest, captureTitle: "One", hostname: "c.example", path: "one",+                    note: "Where the story was", chapterSequence: "1", workID: Self.workID),+                M5SeedEntry(+                    id: Self.newest, captureTitle: "Two", hostname: "c.example", path: "two",+                    note: "Where the reader is", chapterSequence: "2", workID: Self.workID),+            ],+            characters: [+                M5SeedCharacter(+                    id: Self.ana, name: "Ana", nameKey: "ana",+                    facts: [+                        Self.fact("Ana", "stays behind", citing: .entry(Self.oldest)),+                        Self.fact("Ana", "waits on the pier", citing: .entry(Self.oldest)),+                    ],+                    workID: Self.workID),+                M5SeedCharacter(+                    id: Self.zara, name: "Zara", nameKey: "zara",+                    facts: [+                        Self.fact("Zara", "sails at dawn", citing: .entry(Self.newest)),+                        Self.fact("Zara", "keeps the lamp", citing: .entry(Self.newest)),+                    ],+                    workID: Self.workID),+            ])+    }++    /// Req 2.7: the latest position is the work's, not the sheet's. Re-sharing+    /// the last chapter must not read its own entry as gone — which would leave+    /// Zara's facts dangling at what is then the only position, tie her with Ana+    /// and hand the order back to the names.+    @Test("Re-sharing the latest chapter still ranks against the whole work (2.7)")+    func reShareOfTheLatestChapterRanksAgainstTheWholeWork() async throws {+        let fixture = try await rankedCast()++        let reShare = try await context(+            fixture, excluding: Self.newest, anchorSequence: "2", anchorTitle: nil)+        #expect(reShare.characters.map(\.name) == ["Zara", "Ana"])+        // The excluded entry is out of the *notes* half only: the block shows+        // the chapter before it, and the cast is unmoved.+        #expect(reShare.lastNote?.note == "Where the story was")++        // The page, which excludes nothing, agrees (Req 3.1).+        let detail = try await fixture.repository.workDetail(id: Self.workID)+        #expect(detail.characters.map(\.name) == reShare.characters.map(\.name))+        withExtendedLifetime(fixture) {}+    }++    /// Req 3.1: the two surfaces agree for the same work state, including where+    /// the chapter being shared has no placement at all. The cast is ranked+    /// against the work, so an anchor the rules never numbered costs the+    /// catch-up note and nothing else.+    @Test("A shared chapter with no placement still carries the ranked cast (3.1)")+    func unplaceableAnchorStillCarriesTheRankedCast() async throws {+        let fixture = try await rankedCast(workNote: "Reading with Ada.")++        let context = try await context(fixture, anchorTitle: "An Interlude")+        #expect(context.lastNote == nil)+        #expect(context.workNote == "Reading with Ada.")+        #expect(context.characters.map(\.name) == ["Zara", "Ana"])++        let detail = try await fixture.repository.workDetail(id: Self.workID)+        #expect(detail.characters.map(\.name) == context.characters.map(\.name))+        withExtendedLifetime(fixture) {}+    }+     @Test("A torn character shows the content the work page presents, with no marker")     func tornCharacterUsesPresentedContent() async throws {         let fixture = try await seeded(characters: [@@ -683,6 +812,37 @@ struct ShareWorkContextReadTests {         withExtendedLifetime(fixture) {}     } +    /// `character-ranking` Q35: the index composes a split group's placement+    /// from two rows — the representative's sequence beside the carrier's title+    /// — and the last-note selection deliberately does not. A candidate is+    /// placed by its *carrier*, the row whose note would be shown, so the note+    /// and the position it claims come from one row.+    @Test("A split group whose rows differ in chapter sequence is placed by its carrier (Q35)")+    func splitGroupCandidateIsPlacedByItsCarrier() async throws {+        let fixture = try await seeded(entries: [+            // One record, two rows. The bare row — nothing authored on it, so+            // it represents — is numbered 3; the row carrying the note is+            // numbered 8, past the chapter being shared.+            M5SeedEntry(+                id: Self.oldest, captureTitle: "One", hostname: "c.example", path: "one",+                chapterSequence: "3", workID: Self.workID, workAssignmentProvenance: .none),+            M5SeedEntry(+                id: Self.oldest, captureTitle: "One", hostname: "c.example", path: "one",+                note: "The carried note", chapterSequence: "8", workID: Self.workID),+            M5SeedEntry(+                id: Self.newest, captureTitle: "Two", hostname: "c.example", path: "two",+                note: "The one before", chapterSequence: "2", workID: Self.workID),+        ])++        // Placed by the carrier's 8, the split group is ahead of the reader and+        // does not qualify at all. Placed by the index's composite pair it would+        // sit at 3 — nearer the anchor than 2, and the wrong answer.+        let context = try await context(fixture, anchorSequence: "5", anchorTitle: nil)+        #expect(context.lastNote?.note == "The one before")+        #expect(context.lastNote?.title == "2")+        withExtendedLifetime(fixture) {}+    }+     /// Two of Req 8.12's three arms. The third — the site-cleaned capture title     /// — is unreachable for a *selected* note under Decision 4: a placement is     /// derived from the chapter title or the chapter sequence, so an entry@@ -744,20 +904,14 @@ struct ShareWorkContextReadTests {         withExtendedLifetime(fixture) {}     } -    @Test("A failure in the notes half leaves the characters as read (Decision 2)")+    /// The cast is built before the `do/catch` and out of non-throwing parts —+    /// the row walk, the story-position index, the ranking — so a notes failure+    /// costs the notes and not the order (`share-sheet-characters` Q15,+    /// `character-ranking` Q32). Ranked, not name-ordered: a cast that came back+    /// in name order here would be a cast the failure had cost its ranking.+    @Test("A failure in the notes half leaves the ranked characters as read (Decision 2, Q15)")     func notesHalfFailureKeepsTheCharacters() async throws {-        let fixture = try await seeded(-            works: [-                M5SeedWork(-                    id: Self.workID, displayTitle: "A Serial", hostname: "c.example",-                    genericNotes: "Kept")-            ],-            entries: [-                M5SeedEntry(-                    id: Self.oldest, captureTitle: "One", hostname: "c.example", path: "one",-                    note: "A note", chapterTitle: "Chapter 1", workID: Self.workID)-            ],-            characters: [M5SeedCharacter(id: Self.alice, name: "Alice", workID: Self.workID)])+        let fixture = try await rankedCast(workNote: "Kept")          // Citation bytes no decoder will read, which `snapshot(EntryGroup)`         // refuses. Set in the read's own context and never saved: the store on@@ -779,7 +933,7 @@ struct ShareWorkContextReadTests {                 currentChapterTitle: "Chapter 9", context: context)         } -        #expect(context.characters == [ShareCharacter(name: "Alice")])+        #expect(context.characters.map(\.name) == ["Zara", "Ana"])         #expect(context.workNote == "")         #expect(context.lastNote == nil)         withExtendedLifetime(fixture) {}@@ -847,9 +1001,29 @@ struct ShareWorkContextLookupTests {         return basis     } +    /// Bob is noted twice on the matched chapter, alice once: the ranking reads+    /// "Bob, alice", where a name sort reads "alice, Bob". The lookup carries+    /// whichever the projection produced, and the assertion says which.     private static let cast: [M5SeedCharacter] = [-        M5SeedCharacter(id: bob, name: "Bob", workID: workID),-        M5SeedCharacter(id: alice, name: "alice", aliases: ["Ally", "Al"], workID: workID),+        M5SeedCharacter(+            id: bob, name: "Bob", nameKey: "bob",+            facts: [+                CharacterFact(+                    statement: "carries the rope", quote: "Bob carries the rope",+                    nameKey: "bob", source: .entry(entryID)),+                CharacterFact(+                    statement: "keeps the lamp", quote: "Bob keeps the lamp",+                    nameKey: "bob", source: .entry(entryID)),+            ],+            workID: workID),+        M5SeedCharacter(+            id: alice, name: "alice", nameKey: "alice", aliases: ["Ally", "Al"],+            facts: [+                CharacterFact(+                    statement: "waits on the pier", quote: "alice waits on the pier",+                    nameKey: "alice", source: .entry(entryID))+            ],+            workID: workID),     ]      @Test("An opted-in lookup carries the matched work's cast in the work page's order")@@ -859,8 +1033,8 @@ struct ShareWorkContextLookupTests {         let basis = try await editBasis(fixture, includeWorkContext: true)         #expect(basis.entryID == Self.entryID)         #expect(basis.workContext.characters == [-            ShareCharacter(name: "alice", aliases: ["Al", "Ally"]),             ShareCharacter(name: "Bob"),+            ShareCharacter(name: "alice", aliases: ["Al", "Ally"]),         ])         // The same list the standalone read gives for that work — one order,         // one projection.

diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/WorkDetailReadTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/WorkDetailReadTests.swiftindex a425f1a..bc0e699 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/WorkDetailReadTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/WorkDetailReadTests.swift@@ -330,6 +330,187 @@ struct WorkDetailReadTests {         #expect(detail.lastNotedURLString == "https://example.com/1")     } +    // MARK: - Character order (`character-ranking` Reqs 1 and 2)++    @Test("Characters are listed by prominence, name order among equals, no-fact last (1.1, 1.6)")+    func charactersAreRankedByProminence() async throws {+        let fixture = try await M5Fixture()+        let workID = UUID()+        let chapterOne = UUID()+        let chapterTwo = UUID()+        try await fixture.repository.seedM5Rows(+            sites: [M5SeedSite(hostname: "example.com")],+            works: [M5SeedWork(id: workID, displayTitle: "A Serial", hostname: "example.com")],+            entries: [+                M5SeedEntry(+                    id: chapterOne, captureTitle: "A Serial", hostname: "example.com", path: "one",+                    chapterSequence: "1", workID: workID),+                M5SeedEntry(+                    id: chapterTwo, captureTitle: "A Serial", hostname: "example.com", path: "two",+                    chapterSequence: "2", workID: workID),+            ],+            characters: [+                // Noted in both chapters — two buckets, so breadth as well as+                // count puts her first however the tie-breaks fall.+                M5SeedCharacter(+                    id: UUID(), name: "Zara", nameKey: "zara",+                    facts: [+                        CharacterFact(+                            statement: "Sails at dawn", quote: "Zara sails at dawn",+                            nameKey: "zara", source: .entry(chapterOne)),+                        CharacterFact(+                            statement: "Keeps the lamp", quote: "Zara keeps the lamp",+                            nameKey: "zara", source: .entry(chapterTwo)),+                    ],+                    workID: workID),+                // Two walk-ons with the same single-fact profile in the same+                // chapter: equal scores, so name order decides between them.+                M5SeedCharacter(+                    id: UUID(), name: "Bram", nameKey: "bram",+                    facts: [+                        CharacterFact(+                            statement: "Carries the rope", quote: "Bram carries the rope",+                            nameKey: "bram", source: .entry(chapterTwo))+                    ],+                    workID: workID),+                M5SeedCharacter(+                    id: UUID(), name: "Ana", nameKey: "ana",+                    facts: [+                        CharacterFact(+                            statement: "Waits on the pier", quote: "Ana waits on the pier",+                            nameKey: "ana", source: .entry(chapterTwo))+                    ],+                    workID: workID),+                // Nothing noted about her at all: below every scored character,+                // whatever her name would say (Req 1.1).+                M5SeedCharacter(id: UUID(), name: "Cora", nameKey: "cora", workID: workID),+            ])++        let detail = try await fixture.repository.workDetail(id: workID)+        #expect(detail.characters.map(\.name) == ["Zara", "Ana", "Bram", "Cora"])+    }++    @Test("Duplicate rows of one entry are one story position (2.1)")+    func duplicateRowsAreOneStoryPosition() async throws {+        let fixture = try await M5Fixture()+        let workID = UUID()+        let duplicated = UUID()+        let chapterTwo = UUID()+        let day1 = try m5LocalDate(year: 2026, month: 5, day: 12)+        let day2 = try m5LocalDate(year: 2026, month: 5, day: 13)+        try await fixture.repository.seedM5Rows(+            sites: [M5SeedSite(hostname: "example.com")],+            works: [M5SeedWork(id: workID, displayTitle: "A Serial", hostname: "example.com")],+            entries: [+                // One record, two rows that place it differently — the shape the+                // index must project to a single input, and one where the+                // projection is observable. The bare, earlier-captured row+                // represents the group and carries no sequence; the row holding+                // the authored content carries a sequence of its own. The+                // record's placement is neither row's own pair but the composite+                // `snapshot(_:)` builds — the representative's sequence (none)+                // with the carrier's chapter title — which puts the entry at+                // chapter 1, one position behind `chapterTwo`.+                //+                // Built from rows instead, the same three rows would be three+                // inputs: the bare one unplaced, the carrier at 5 — the *latest*+                // position — and the duplicated entry would end up there rather+                // than one position back, flipping the order asserted below (as+                // well as tripping the index's one-input-per-entry precondition+                // in debug).+                M5SeedEntry(+                    id: duplicated, captureTitle: "A Serial", hostname: "example.com", path: "one",+                    firstCapturedAt: day1, workID: workID, workAssignmentProvenance: .urlRule),+                M5SeedEntry(+                    id: duplicated, captureTitle: "A Serial", hostname: "example.com", path: "one",+                    chapterTitle: "Chapter 1", chapterSequence: "5", firstCapturedAt: day2,+                    workID: workID),+                M5SeedEntry(+                    id: chapterTwo, captureTitle: "A Serial", hostname: "example.com", path: "two",+                    chapterSequence: "2", workID: workID),+            ],+            characters: [+                // One fact each, so nothing but the story position separates+                // them: Zed's is at the latest position and Ada's one back, and+                // the ranked order is the reverse of name order.+                M5SeedCharacter(+                    id: UUID(), name: "Ada", nameKey: "ada",+                    facts: [+                        CharacterFact(+                            statement: "Rows the tender", quote: "Ada rows the tender",+                            nameKey: "ada", source: .entry(duplicated))+                    ],+                    workID: workID),+                M5SeedCharacter(+                    id: UUID(), name: "Zed", nameKey: "zed",+                    facts: [+                        CharacterFact(+                            statement: "Waits on the pier", quote: "Zed waits on the pier",+                            nameKey: "zed", source: .entry(chapterTwo))+                    ],+                    workID: workID),+            ])++        let detail = try await fixture.repository.workDetail(id: workID)+        // The read projects rows to records everywhere else too, so the count is+        // the tell that the duplicate really is one entry here.+        #expect(detail.chapterRows.count == 2)+        #expect(detail.characters.map(\.name) == ["Zed", "Ada"])+    }++    @Test("A re-share of an old chapter leaves the character order unchanged (2.3)")+    func reSharingAnOldChapterDoesNotMoveIt() async throws {+        let fixture = try await M5Fixture()+        let workID = UUID()+        let early = UUID()+        let later = UUID()+        let day1 = try m5LocalDate(year: 2026, month: 5, day: 12)+        let day2 = try m5LocalDate(year: 2026, month: 5, day: 13)+        let today = try m5LocalDate(year: 2026, month: 5, day: 20)+        try await fixture.repository.seedM5Rows(+            sites: [M5SeedSite(hostname: "example.com")],+            works: [M5SeedWork(id: workID, displayTitle: "A Serial", hostname: "example.com")],+            entries: [+                // Neither note is numbered, so story position is first-capture+                // order (Q13) — and the earlier one has just been re-shared,+                // which is what `lastSharedAt` would wrongly read as "latest".+                M5SeedEntry(+                    id: early, captureTitle: "A Serial", hostname: "example.com", path: "one",+                    firstCapturedAt: day1, lastSharedAt: today, workID: workID),+                M5SeedEntry(+                    id: later, captureTitle: "A Serial", hostname: "example.com", path: "two",+                    firstCapturedAt: day2, lastSharedAt: day2, workID: workID),+            ],+            characters: [+                // The character who has left the story: one fact, one position back.+                M5SeedCharacter(+                    id: UUID(), name: "Ana", nameKey: "ana",+                    facts: [+                        CharacterFact(+                            statement: "Stays behind", quote: "Ana stays behind",+                            nameKey: "ana", source: .entry(early))+                    ],+                    workID: workID),+                // The one still in it: one fact at the latest position.+                M5SeedCharacter(+                    id: UUID(), name: "Zara", nameKey: "zara",+                    facts: [+                        CharacterFact(+                            statement: "Sails at dawn", quote: "Zara sails at dawn",+                            nameKey: "zara", source: .entry(later))+                    ],+                    workID: workID),+            ])++        let detail = try await fixture.repository.workDetail(id: workID)+        // The re-share did happen: the spine, which does order on `lastSharedAt`,+        // now shows the old chapter first.+        #expect(detail.chapterRows.first?.id == early)+        // The ranking does not follow it. Name order would be the other way+        // round, so this passes for neither a name sort nor a `lastSharedAt` one.+        #expect(detail.characters.map(\.name) == ["Zara", "Ana"])+    }+     @Test("A work with no entries has no pulse, no rows and no last-noted URL (5.3)")     func emptyWork() async throws {         let fixture = try await M5Fixture()

diff --git a/docs/agent-notes/testing.md b/docs/agent-notes/testing.mdindex 707a543..6985971 100644--- a/docs/agent-notes/testing.md+++ b/docs/agent-notes/testing.md@@ -202,7 +202,9 @@ Consequences: (`specs/retire-migration-chain/verification-run.md`): the target **exits 0**. A `RUNS=1` pass took ~20 minutes then, **~25 minutes** after `multi-site-works` added the membership suite (1,494 s measured 2026-08-26), and **~21 minutes**-since `drop-superseded-columns` (1,093 s of test time measured 2026-08-28).+since `drop-superseded-columns` (1,093 s of test time measured 2026-08-28, and+1,120 s over 28 tests measured 2026-08-30, after `character-ranking` added its+own). It reported **four or five known issues** — Req 10.1's settling pass (`duplicate-reconciliation` Decision 27), Req 5.5's three diagnosis re-derivations (`library-integrity-tolerance` Decision 11), and,