A fifth reading status, toRead: created by the New Work form, promoted to reading by a capture or a Move To, kept off Today's plan.
ModelContainer temporaries in three test helpers, and two test gaps (Move To into a non-to-read work, reparse does not promote).Development Mac build.Ready to push
Four parallel reviews raised no blocking or major finding, and none at all in production code. Every finding worth acting on was fixed in the working tree. make test-core passes after the fixes: 2,834 + 227 + 42 tests, zero known issues, zero compiler warnings. No JUnit or coverage data: the repo has no Swift package at its root and make test-core emits none, so the Tests card records runner not detected. The three Works-options UI suites passed after the helper change (subagent run). Two UI cases that fail at main's tip still fail here.
c34425be T-2354: to-read requirements and decision log 8f9f9a35 T-2354: to-read design 0bce6fec T-2354: to-read tasks and prerequisites 99dcede0 T-2354: add to-read to the specs overview 4d6903bd T-2354: the toRead reading status and its presentation 134242da T-2354: changelog for phase 1 18dd2c89 T-2354: to-read in progress, and the journey pin moves with the UI task dafe7803 T-2354: the three to-read writes on the Core side d6d26ddc [merge]: phase 2 stream 1 74e78373 T-2354: Req 3.7 is last-writer-wins on an ordinary Save (Q27) 17c2b5e5 T-2354: changelog for phase 2 69922804 T-2354: the app view models and the editor journeys meet the fifth segment bfb71f5a [merge]: phase 3 stream 2, tasks 10 and 11 a407bc56 T-2354: the five-segment card moved no journey scroll step (Q28) d2d72cb6 T-2354: Vesper Tide joins the Works-options fixture (task 12) 3fcede56 T-2354: two more menu-label and strip-cell assertions made deterministic d6bfdfc1 T-2354: the full suites are run and every failure classified (task 13) a6fd45f2 T-2354: changelog for phase 3 eb324d34 T-2354: to-read is done in the specs overview working-tree Fixes applied in this review Every work in the library used to read as Reading from the moment it existed, even one only written down to try later. There is now a fifth reading status, To read, with a bookmark glyph, listed first: to read, reading, catching up, finished, abandoned.
A to-read work stays off the Today plan. Its release days are kept and count once it is Reading.
The library can tell "I am reading this" from "I mean to read this", and the reader does not have to flip the status by hand when they start.
DomainEnums.swift: case toRead, declared first. isDone unchanged, so the verdict stays hidden.WorkStatusPresentation.swift: three exhaustive switches gain an arm. Hue, accessibility label and identifier derive from the name and raw value.RepositoryDrafts.swift, LibraryRepository.swift: NewWorkDraft.readingStatus, defaulted to .reading; createWork assigns it before its one save. NewWorkFormModel is the one production caller passing .toRead.Models.swift: Work.promoteFromToRead(), called from the capture commit's .reuse/.claim arm and moveEntry's .existing arm.DuplicateReconciler.swift: the carry guard covers two values.The picker, filter menu, row glyph, Today schedule, archive and merge iterate allCases or read a value and needed no change. The design's parity audit lists each site; none was missed.
A raw-string enum column with a tolerant read needs no schema, marker or archive generation change. Creation is narrow because the status rides on the draft, not in Work.create, so Move To a new work, the capture .create arm and import cannot mint a to-read work. Promotion sits in two loops that already stamp every row, before the operation's single save.
reading over a sibling's abandoned waiting on the review card.WorkMetadataDraft, because about sixty fixture callers must keep reading.Ordering. Declaration order is display order only. The representative order and VariantID use the raw string, and "reading" < "toRead", so a toRead sibling does not displace a reading representative.
Carry guard. toRead and catchingUp are authored content that may write only over a row on the default; finished and abandoned carriers stay unnarrowed. All 25 carrier/row combinations were checked against Req 5.2 in this review. A disagreeing authored pair is two variants and never reaches apply, so the unnarrowed done-carrier write is reachable only through the scan/write race the guard exists for.
Promotion. It compares and writes readingStatusRaw: an unknown stored spelling reads as reading through the tolerant accessor and is not a to-read row. No clock, value-guarded, idempotent. Move To is gated on !priorWorkIDs.contains(workID) (Q20), narrower than the no-op return: re-moving a rule-attached entry is a real write but not the reader starting to read. An entry with no prior work gives an empty set and promotes.
No new table, relationship, reconciler or trigger. The share extension gains nothing. One accepted consequence (Decision 1): a promoted, otherwise bare reading row beside a toRead twin converges back to toRead.
WorkEditBasis.matches is consulted only by the post-collapse redirect, so a stale editor can save toRead back over a promotion.toRead as reading, may write it back, and refuses to export (Q9).Packages/AsterismCore/Sources/AsterismCore/Models.swift
Why it matters. The one new write in the feature. It must be idempotent, clock-free and must not rewrite a row holding an unknown status spelling.
What to look at. Models.swift, Work.promoteFromToRead()
Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ReparseCapture.swift
Why it matters. Correctness of Req 3.1 and 3.3. It must not be reachable from reparse or teaching, and must write per row.
What to look at. applyCaptureAssignment, .reuse/.claim arm
Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift
Why it matters. The gate decides whether a Move To counts as the reader starting to read. Too wide promotes on a provenance repair; too narrow misses an unattached entry.
What to look at. moveEntry .existing arm, `let promotes = !priorWorkIDs.contains(workID)`
Packages/AsterismCore/Sources/AsterismCore/DuplicateReconciler.swift
Why it matters. Convergence runs silently on every device. A wrong direction here overwrites a reader's status without asking.
What to look at. apply(_:to:types:), writesOnlyOverDefault / carryMayOverwrite
Packages/AsterismCore/Sources/AsterismCore/RepositoryDrafts.swift
Why it matters. API surface. It is the opposite choice from WorkMetadataDraft, which has no defaults so an editor cannot forget a field.
What to look at. NewWorkDraft.init(displayTitle:hostname:readingStatus:)
Asterism/AsterismUITests/UIJourneySupport.swift
Why it matters. Not in the design. The fifth status moved the menu rows enough that an ambiguous label query started raising; this review bounded the pick and removed a 5 s wait regression.
What to look at. WorksOptionNeighbour, worksOptionRow, chooseWorksOption
toRead out of work-and-reading-status Q8 by name. Teaching, reparse, merge, collapse, import and re-share leave the status alone, so a to-read work can hold entries.abandoned.reading unedited.moveEntry's no-op return.WorkEditBasis.matches is consulted only by the post-collapse redirect; adding a basis check to updateWork would change every edit in the app.TodayUITests first-weekday predicate. Both blocked a green make test.| Severity | Area | Finding | Resolution |
|---|---|---|---|
| minor | specs/OVERVIEW.md detail section | The table row said Done but the per-spec section still read 'Planned ... Q1-Q25'. | Status set to Done, log range Q1-Q29, Mac hand check noted. |
| minor | specs/to-read/design.md testing table | The RepositoryWorksTests row still expected updateWork to return .conflict against a promoted work, contradicting Q27 and the design's own corrected Conflict paragraph. | Row rewritten to the last-writer-wins behaviour with a pointer to Q27. |
| minor | decision log | The shared-label menu resolution and the TodayUITests first-weekday repair were not in the design, the tasks or the decision log. | Recorded as Q29, including why firstMatch was rejected and that row identifiers are the production fix. |
| minor | UIJourneySupport.worksOptionRow: 5 s dead wait | When a label was not yet drawn the helper returned an element that never resolves, so the caller's presentation wait ran its full 5 s at about 35 call sites. Before this branch the wait was on a lazy label query. | The presentation wait runs on a lazy label query used only for waiting; the tapped row is still resolved by worksOptionRow. |
| minor | UIJourneySupport.worksOptionRow: unbounded neighbour pick | The .above/.below pick took the nearest materialised same-label row at any distance. In a lazy menu it could return another picker's Any and tap it. | Bounded to 3 anchor row heights. Every intended row sits within 2, every wrong one beyond 3.5; out of bound the scroll loop keeps walking and a miss fails by name. The five call sites were checked against WorksView.optionsMenu. |
| minor | UIJourneySupport.worksOptionRow: frame round-trips | frame was re-fetched inside the sort comparator and again in the following pass; each access is an accessibility round-trip. | Each candidate's minY is read once into a tuple before sorting. |
| minor | RepositoryCaptureTests store helpers | Three new helpers built a ModelContext from an unretained temporary ModelContainer and took no lock lease, unlike the two helpers beside them and against the project's Swift rules. | All three bind the container and take a CrossProcessLibraryLock lease, shared for reads and exclusive for the seeding write. |
| minor | Test gap: Req 3.3 at the Move To site | Per-row promotion was proven for the capture site only. Nothing moved an entry into a non-toRead work or into a torn {toRead, abandoned} destination. | Two tests added in RepositoryWorksTests; both were seen failing against a group-wide ungated write, then the probe was reverted. |
| minor | Test gap: reparse does not promote | The Non-Goals name reparse, and commitReparse's worksToReuse loop re-points entries onto existing works, but no test pinned that it leaves toRead alone. | reparseOntoAToReadWorkDoesNotPromoteIt added; asserts the entry really moved onto the work first, and was seen failing against a probe call. |
| nit | Comments: 'nine pickers draw an Any' | There are eight filterPicker call sites, each with an Any; the Sort picker has none. Stated wrongly in three places. | Corrected in the agent note, UIJourneySupport and WorksCreatorOptionsUITests. |
| minor | Core test helper duplication | setReadingStatus, captureThroughRules and teachWorkIdentity are copied between test files, and three new reconciler cases repeat one skeleton. | Left alone: test-only style, and the review's rule is not to refactor tests that are not wrong. Worth a shared support file if these suites grow. |
| nit | revealInEditor duplicates revealInTheList | A third copy of the scroll-until-hittable loop, differing only in the scroll target; assertTheFiveSegmentsAreOperable re-implements private assertions from the phone suite. | Left alone: matches the suite's existing convention. |
| nit | TodayUITests exists && isSelected | Two reads leave a tiny window in which the cell can leave the tree between them. | Left alone: the strip is settled at that point and the change already removes the deterministic failure. |
| nit | Vesper Tide / Quill Harbour seed order | The pinned no-entries order rests on the two works landing in different quantized milliseconds, which nothing asserts. | Left alone: a capture's full save sits between the two creates, and the rest of this fixture relies on the same separation. |
| nit | DuplicateReconciler.writesOnlyOverDefault | A two-value classification of the enum that could live on ReadingStatus beside isDone. | Left alone: the comment justifying the narrowing belongs at the use site, and the code is correct either way. |
| nit | Requirement 1.1 wording | It lists the merge preview's discarded-field list as a place the status is shown, but that row never renders a status value for any status. | Left alone: toRead is handled exactly as the other four, and design.md states it correctly. |
Source: local run at 2026-09-22T09:39:04+10:00 · snapshot eb324d34d66cacb78f49135b1de41dff3bc8e017 (dirty working tree)
Baseline: none
Execution: passed · JUnit: none · Coverage: none · Baseline: absent
Coverage scope: as the project configures it
The test runner could not be detected.
Derived by declaration name, from the diff (no baseline run).
Files that import a changed file on the left, changed files in the centre, files a changed file imports on the right. Snapshot working-tree against base 1d0a96f6.
Click to expand.
diff --git a/Asterism/Asterism/UITestLaunchSupport.swift b/Asterism/Asterism/UITestLaunchSupport.swiftindex 227e3341..481f0ecc 100644--- a/Asterism/Asterism/UITestLaunchSupport.swift+++ b/Asterism/Asterism/UITestLaunchSupport.swift@@ -153,7 +153,7 @@ enum UITestLaunchSupport { static let seededSpanningMonthsScenario = "seeded-spanning-months" /// The two preserved captures the drain's Settings surfaces need. static let seededPendingCapturesScenario = "seeded-pending-captures"- /// The four works the Works list's sort and filter journey runs over.+ /// The five works the Works list's sort and filter journey runs over. static let seededWorksOptionsScenario = "seeded-works-options" /// The five works, three series and two links the series journeys run over. static let seededSeriesScenario = "seeded-series"
diff --git a/Asterism/Asterism/ViewModels/AppLibraryModel.swift b/Asterism/Asterism/ViewModels/AppLibraryModel.swiftindex 5cbdcfde..b51419e9 100644--- a/Asterism/Asterism/ViewModels/AppLibraryModel.swift+++ b/Asterism/Asterism/ViewModels/AppLibraryModel.swift@@ -2632,7 +2632,7 @@ public final class AppLibraryModel { /// `works-list-options`: the smallest library the Works list's sort and /// filter controls have something to say about. ///- /// Four works over two hostnames, whose titles order differently by letter+ /// Five works over two hostnames, whose titles order differently by letter /// than by date, so each of the four sorts draws a different list and a /// journey can tell them apart: ///@@ -2642,10 +2642,22 @@ public final class AppLibraryModel { /// | Ashfall | beta.test | second | webtoon, then removed | — | hiatus | reading | — | Sat | /// | Zephyr Court | alpha.test | third | novel | — | finished | finished | yes | — | /// | Quill Harbour | beta.test | no entries | — | — | ongoing | reading | — | — |+ /// | Vesper Tide | alpha.test | no entries | — | — | ongoing | **toRead** | — | — | /// /// Plus one unattached entry, so the group a filter hides (Q9) is on screen /// before the filter is chosen. ///+ /// **Vesper Tide is `to-read`'s row** (Q21, Q24): the fifth reading status+ /// needs a work carrying it for the glyph, the filter value and Req 1.5's+ /// no-entries placement to be asserted against. Its title sorts between+ /// Quill Harbour and Zephyr Court, so all four pinned orders place it+ /// unambiguously; it is seeded **last**, after the loose capture, so its+ /// `modifiedAt` falls in a later millisecond than Quill Harbour's and the+ /// two entry-less works order deterministically (`works()` breaks a+ /// no-entry tie on `modifiedAt` descending). It is created through+ /// `createWork` naming `.toRead` — the one seed that names a status, since+ /// Q15 keeps every other fixture caller on `reading`.+ /// /// `update-schedule` Req 11.2 gives two of the four release days and leaves /// two without, so the presence filter has both answers in one library. The /// days are fixed weekdays rather than ones derived from the launch clock —@@ -2711,6 +2723,11 @@ public final class AppLibraryModel { captureTitle: "Loose Note", captureTitleSource: .host, rawURLString: "https://alpha.test/loose/1"))+ // `to-read` Q24: last, so this work's `modifiedAt` is later than Quill+ // Harbour's and the no-entries run has a deterministic order.+ _ = try await repo.createWork(+ NewWorkDraft(+ displayTitle: "Vesper Tide", hostname: "alpha.test", readingStatus: .toRead)) Self.logger.debug("Seeded the works-list-options UI test fixture") }
diff --git a/Asterism/Asterism/ViewModels/NewWorkFormModel.swift b/Asterism/Asterism/ViewModels/NewWorkFormModel.swiftindex 316bab8b..8743320a 100644--- a/Asterism/Asterism/ViewModels/NewWorkFormModel.swift+++ b/Asterism/Asterism/ViewModels/NewWorkFormModel.swift@@ -36,7 +36,11 @@ public final class NewWorkFormModel { state = .submitting errorMessage = nil do {- let draft = NewWorkDraft(displayTitle: draftTitle, hostname: draftHostname)+ // `to-read` Req 2.1: a work added by hand has no entries, so the+ // reader has not started it. The form offers no status control and+ // this is the only production caller that names one (Q5, Q15).+ let draft = NewWorkDraft(+ displayTitle: draftTitle, hostname: draftHostname, readingStatus: .toRead) let result = try await library.createWork(draft) await onMutation() state = .created(result)
diff --git a/Asterism/Asterism/Views/WorkStatusPresentation.swift b/Asterism/Asterism/Views/WorkStatusPresentation.swiftindex 6980725b..f098af8c 100644--- a/Asterism/Asterism/Views/WorkStatusPresentation.swift+++ b/Asterism/Asterism/Views/WorkStatusPresentation.swift@@ -68,6 +68,7 @@ nonisolated enum ReadingStatusPresentation { static func name(_ status: ReadingStatus) -> String { switch status {+ case .toRead: "To read" case .reading: "Reading" case .catchingUp: "Catching up" case .finished: "Finished"@@ -76,7 +77,7 @@ nonisolated enum ReadingStatusPresentation { } /// Marked everywhere but the default: `reading` is where every work starts- /// and draws nothing, and each of the other three carries its own symbol+ /// and draws nothing, and each of the other four carries its own symbol /// (Reqs 4.3, 5.1, 5.2). /// /// The glyph used to mean "done reading" and no longer does: `catchingUp`@@ -84,8 +85,15 @@ nonisolated enum ReadingStatusPresentation { /// in a state worth seeing on the row, and `isDone` is false for it. The /// forward arrow is the one thing it says — the reader is moving through a /// backlog — and it is used nowhere else in the app.+ ///+ /// `toRead` is the second such mark on a work that is not done (`to-read`+ /// Q17): a bookmark is a place to come back to, which is what a work the+ /// reader has not started is. It is used nowhere else in the app either —+ /// the share sheet's cyan `bookmark.fill` beside `Chapter:` is a different+ /// symbol on a screen that never shows a reading status. static func systemImage(_ status: ReadingStatus) -> String? { switch status {+ case .toRead: "bookmark" case .reading: nil case .catchingUp: "forward.fill" case .finished: "checkmark"@@ -111,9 +119,11 @@ nonisolated enum ReadingStatusPresentation { /// — a placeholder vanishes the moment the reader types. /// /// Nil exactly where the field is absent: a work still being read has no- /// verdict to write yet, and a reader catching up is still reading.+ /// verdict to write yet, a reader catching up is still reading, and a work+ /// the reader has not started has nothing to say about it at all. static func verdictPrompt(_ status: ReadingStatus) -> String? { switch status {+ case .toRead: nil case .reading: nil case .catchingUp: nil case .finished: "How was it?"
diff --git a/Asterism/AsterismTests/DuplicateSurfaceTests.swift b/Asterism/AsterismTests/DuplicateSurfaceTests.swiftindex 5da69448..c8928957 100644--- a/Asterism/AsterismTests/DuplicateSurfaceTests.swift+++ b/Asterism/AsterismTests/DuplicateSurfaceTests.swift@@ -202,8 +202,8 @@ struct DuplicateSurfaceTests { DuplicateResolutionView.readingStatusLine( Self.workVariant(readingStatus: $0), differing: [.readingStatus]) } == [- "Reading: Reading", "Reading: Catching up", "Reading: Finished",- "Reading: Abandoned",+ "Reading: To read", "Reading: Reading", "Reading: Catching up",+ "Reading: Finished", "Reading: Abandoned", ]) }
diff --git a/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift b/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swiftindex 1a2a31cd..7dc24fa4 100644--- a/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift+++ b/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift@@ -156,6 +156,22 @@ struct NewWorkFormModelTests { #expect(tracker.mutationCount == 1) } + /// `to-read` [2.1](../../../specs/to-read/requirements.md#2.1): the form is+ /// the one production caller that names a reading status, and it names+ /// `.toRead` (Q5, Q15). There is no status control on the form, so the draft+ /// is where the value is observable at all.+ @Test("The form's draft creates the work as to read")+ @MainActor func createSendsToRead() async {+ let mock = MockLibraryProvider()+ mock.createWorkResult = .success(TestFixtures.makeWork(displayTitle: "Planned"))+ let model = NewWorkFormModel(library: mock, onMutation: {})+ model.draftTitle = "Planned"+ model.draftHostname = "example.com"+ await model.create()+ #expect(mock.lastNewWorkDraft?.readingStatus == .toRead)+ #expect(mock.lastNewWorkDraft?.displayTitle == "Planned")+ }+ @Test("Create failure preserves editing state") @MainActor func createFailure() async { let mock = MockLibraryProvider()
diff --git a/Asterism/AsterismTests/WorkDetailModelTests.swift b/Asterism/AsterismTests/WorkDetailModelTests.swiftindex e3c60f08..24297db7 100644--- a/Asterism/AsterismTests/WorkDetailModelTests.swift+++ b/Asterism/AsterismTests/WorkDetailModelTests.swift@@ -947,6 +947,32 @@ struct WorkDetailModelTests { #expect(model.draftReadingStatus == .catchingUp) } + /// `to-read` Req 1.3: to read is not done reading, so choosing it needs no+ /// work-status precondition and raises no dialog — a finished story the+ /// reader has not started is exactly the case.+ ///+ /// And the revert and the restore still move a draft between `reading` and+ /// `finished` only, so a to-read draft is left where it is when the work+ /// status changes under it.+ @MainActor @Test(+ "To read needs no work status, raises no prompt, and survives a work-status change",+ arguments: [WorkStatus.ongoing, .hiatus, .finished])+ func toReadIsChosenFreely(work workStatus: WorkStatus) async {+ let (model, mock, _) = makeSUT(+ work: TestFixtures.makeWork(workStatus: workStatus, readingStatus: .reading))+ await model.load()+ model.beginEditing()++ model.setDraftReadingStatus(.toRead)++ #expect(model.draftReadingStatus == .toRead)+ #expect(model.finishedReadingPrompt == nil)+ #expect(mock.updateWorkCallCount == 0)++ model.setDraftWorkStatus(workStatus == .finished ? .ongoing : .finished)+ #expect(model.draftReadingStatus == .toRead)+ }+ /// Req 3.5: a stored pair that violates the rule is shown as stored. Tapping /// the segment it is already on is not a change, so it must not ask. @MainActor @Test("Re-selecting the reading status a stored violating pair already has is a no-op")@@ -2428,6 +2454,27 @@ struct WorkDetailReleaseDaysTests { } } + /// `to-read` Req 4.3: a to-read work is off Today whatever its work status,+ /// so the existing line is already true for it and there is no new wording.+ /// It takes that line under every work status, `ongoing` included — the+ /// condition's other half is the one that fails.+ @MainActor @Test("A to-read draft keeps the existing line under every work status")+ func theNoteIsTheExistingLineWhileToRead() async {+ for workStatus in WorkStatus.allCases {+ let (model, _) = makeSUT(+ work: TestFixtures.makeWork(+ workStatus: workStatus, readingStatus: .toRead,+ releaseDays: [.monday]))+ await model.load()++ #expect(+ model.releaseDaysNote+ == "Shown on Today only while the work is ongoing and you are reading it",+ "\(workStatus)")+ #expect(model.releaseDaysNote == ReleaseDaysText.note, "\(workStatus)")+ }+ }+ /// With no day toggled there is nothing to explain, so the line is absent /// whatever the statuses say — including on the three pairs that would /// otherwise show it.@@ -2435,7 +2482,7 @@ struct WorkDetailReleaseDaysTests { func theNoteIsAbsentWithNoDayToggled() async { let cases: [(WorkStatus, ReadingStatus)] = [ (.ongoing, .reading), (.hiatus, .reading), (.ongoing, .finished),- (.finished, .abandoned), (.ongoing, .catchingUp),+ (.finished, .abandoned), (.ongoing, .catchingUp), (.ongoing, .toRead), ] for (workStatus, readingStatus) in cases { let (model, _) = makeSUT(
diff --git a/Asterism/AsterismTests/WorkStatusPresentationTests.swift b/Asterism/AsterismTests/WorkStatusPresentationTests.swiftindex 50f07ac6..fd749fdc 100644--- a/Asterism/AsterismTests/WorkStatusPresentationTests.swift+++ b/Asterism/AsterismTests/WorkStatusPresentationTests.swift@@ -21,7 +21,23 @@ struct WorkStatusPresentationTests { == ["Ongoing", "Finished", "On hiatus"]) #expect( ReadingStatus.allCases.map(ReadingStatusPresentation.name)- == ["Reading", "Catching up", "Finished", "Abandoned"])+ == ["To read", "Reading", "Catching up", "Finished", "Abandoned"])+ }++ /// `to-read` Req 1.1: the fifth value's own words, spelled here rather than+ /// only inside the array above, because these four strings are what the+ /// reader, VoiceOver and the journeys each address the value by.+ @Test("The to-read value is named, marked, labelled and addressable")+ func toReadCarriesItsOwnPresentation() {+ #expect(ReadingStatusPresentation.name(.toRead) == "To read")+ #expect(ReadingStatusPresentation.systemImage(.toRead) == "bookmark")+ #expect(ReadingStatusPresentation.hue(.toRead) == AsterismColors.cyan)+ #expect(ReadingStatusPresentation.accessibilityLabel(.toRead) == "Reading: To read")+ #expect(+ ReadingStatusPresentation.controlIdentifier(.toRead)+ == "work-detail-reading-status-toRead")+ // Req 1.3: not done reading, so there is no verdict to prompt for.+ #expect(ReadingStatusPresentation.verdictPrompt(.toRead) == nil) } // MARK: - Glyphs (Reqs 4.3, 5.1, 5.2, Q27)@@ -38,6 +54,7 @@ struct WorkStatusPresentationTests { #expect(WorkStatusPresentation.systemImage(.finished) == "flag.checkered") #expect(WorkStatusPresentation.systemImage(.hiatus) == "pause.circle") + #expect(ReadingStatusPresentation.systemImage(.toRead) == "bookmark") #expect(ReadingStatusPresentation.systemImage(.reading) == nil) #expect(ReadingStatusPresentation.systemImage(.catchingUp) == "forward.fill") #expect(ReadingStatusPresentation.systemImage(.finished) == "checkmark")@@ -48,7 +65,9 @@ struct WorkStatusPresentationTests { let symbols = WorkStatus.allCases.compactMap(WorkStatusPresentation.systemImage) + ReadingStatus.allCases.compactMap(ReadingStatusPresentation.systemImage)- #expect(Set(symbols).count == 5)+ // Six since `to-read` added `bookmark`: a place the reader means to come+ // back to, distinct from the other five marks (Q17).+ #expect(Set(symbols).count == 6) } /// Q27: no third hue. Work glyphs take the type tag's violet, reading glyphs@@ -76,8 +95,8 @@ struct WorkStatusPresentationTests { #expect( ReadingStatus.allCases.map(ReadingStatusPresentation.accessibilityLabel) == [- "Reading: Reading", "Reading: Catching up", "Reading: Finished",- "Reading: Abandoned",+ "Reading: To read", "Reading: Reading", "Reading: Catching up",+ "Reading: Finished", "Reading: Abandoned", ]) } @@ -88,6 +107,9 @@ struct WorkStatusPresentationTests { /// read has no verdict field, so it has no prompt. @Test("Each done-reading value has its own prompt, and reading has none") func verdictPromptsPerCase() {+ // A work the reader has not started has nothing to write a verdict+ // about either (`to-read` Req 1.3).+ #expect(ReadingStatusPresentation.verdictPrompt(.toRead) == nil) #expect(ReadingStatusPresentation.verdictPrompt(.reading) == nil) // A reader catching up is still reading, so there is nothing to write // a verdict about yet (`catch-up-mode`).
diff --git a/Asterism/AsterismTests/WorksFilterPresentationTests.swift b/Asterism/AsterismTests/WorksFilterPresentationTests.swiftindex 1e54b232..77d8c891 100644--- a/Asterism/AsterismTests/WorksFilterPresentationTests.swift+++ b/Asterism/AsterismTests/WorksFilterPresentationTests.swift@@ -163,6 +163,7 @@ struct WorksFilterPresentationTests { ]) #expect( ReadingStatus.allCases.map(WorksFilterPresentation.readingStatusRowIdentifier) == [+ "works-filter-reading-status-toRead", "works-filter-reading-status-reading", "works-filter-reading-status-catchingUp", "works-filter-reading-status-finished",
diff --git a/Asterism/AsterismTests/WorksListOptionsTests.swift b/Asterism/AsterismTests/WorksListOptionsTests.swiftindex e5c78b10..9085b66a 100644--- a/Asterism/AsterismTests/WorksListOptionsTests.swift+++ b/Asterism/AsterismTests/WorksListOptionsTests.swift@@ -212,6 +212,40 @@ struct WorksSortTests { #expect(WorksRowPresentation.isKnockedDown(catchingUp) == false) #expect(WorksRowPresentation.isKnockedDown(abandoned(3, "C"))) }++ /// `to-read` Req 1.5: a work the reader means to start is not a work they+ /// gave up on. The partition and the knock-down are both the abandoned-only+ /// predicate, so a to-read row sorts and draws exactly as an active one.+ @Test("A to-read work sorts and draws as an active one")+ @MainActor func toReadIsAnActiveWork() {+ let toRead = TestFixtures.makeWork(+ id: id(2), displayTitle: "B", entries: [TestFixtures.makeEntry(workID: id(2))],+ readingStatus: .toRead)+ let works = [work(1, "A"), toRead, abandoned(3, "C")]+ for sort in WorksSort.allCases {+ #expect(sort.apply(to: works).map(\.id).last == id(3), "\(sort)")+ #expect(sort.apply(to: works).map(\.id).contains(id(2)), "\(sort)")+ }+ #expect(WorksSort.newest.apply(to: works).map(\.id) == [id(1), id(2), id(3)])+ #expect(WorksRowPresentation.isKnockedDown(toRead) == false)+ }++ /// Req 1.5's other half: the no-entries split is `entries.isEmpty` and the+ /// status plays no part in it, so the New Work form's to-read work lands in+ /// the empty section with every other work that has nothing noted yet.+ @Test("A to-read work without entries is placed as any other empty work is")+ func toReadWithoutEntriesSitsInTheEmptySection() {+ let toRead = TestFixtures.makeWork(+ id: id(2), displayTitle: "B", readingStatus: .toRead)+ let works = [work(1, "A"), toRead, emptyWork(3, "C")]++ // The date sorts section the empty works, and the to-read one is one of+ // them: `.oldest` reverses that section as it reverses the other.+ #expect(WorksSort.newest.apply(to: works).map(\.id) == [id(1), id(2), id(3)])+ #expect(WorksSort.oldest.apply(to: works).map(\.id) == [id(1), id(3), id(2)])+ // And the title sorts do not section them at all.+ #expect(WorksSort.aToZ.apply(to: works).map(\.id) == [id(1), id(2), id(3)])+ } } @Suite("Works filter")@@ -346,9 +380,13 @@ struct WorksFilterTests { work(1, readingStatus: .reading), work(2, readingStatus: .finished), work(3, readingStatus: .abandoned),+ work(4, readingStatus: .toRead), ] #expect(WorksFilter(readingStatus: .finished).apply(to: works).map(\.id) == [id(2)]) #expect(WorksFilter(readingStatus: .abandoned).apply(to: works).map(\.id) == [id(3)])+ // `to-read` Req 1.1: the fifth value narrows the list like the other four.+ #expect(WorksFilter(readingStatus: .toRead).apply(to: works).map(\.id) == [id(4)])+ #expect(WorksFilter(readingStatus: .reading).apply(to: works).map(\.id) == [id(1)]) } /// Both dimensions have a value spelled `finished`, and they are separate@@ -1393,6 +1431,21 @@ struct WorksReleaseDaysFilterTests { ]) } + /// `to-read` Req 1.1: the pill is built from the status's name, so the fifth+ /// value reads as `Reading: To read` wherever a chosen status is shown —+ /// and the empty state says the same words back.+ @Test("A chosen to-read status draws its own pill")+ func theToReadPillNamesTheStatus() {+ let options = WorksFilterOptions(works: [work(1)], siteNames: .empty)+ let labels = WorksFilterPresentation.activeLabels(+ WorksFilter(readingStatus: .toRead), options: options, siteNames: .empty)+ #expect(labels == ["Reading: To read"])+ #expect(labels == [ReadingStatusPresentation.accessibilityLabel(.toRead)])+ #expect(+ WorksFilterPresentation.emptyDescription(labels: labels, query: nil)+ == "No works match Reading: To read.")+ }+ @Test("The empty state names the dimension in the pills' wording") func theEmptyStateNamesTheDimension() { let labels = WorksFilterPresentation.activeLabels(
diff --git a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swiftindex 6d737cb4..b5d69dec 100644--- a/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift+++ b/Asterism/AsterismUITests/AccessibilityJourneyUITests.swift@@ -299,7 +299,12 @@ final class AccessibilityJourneyUITests: XCTestCase { // the same menu at this size, and the row it leaves wears a work-status // glyph and a reading-status glyph — the row that has to stay hittable. // ANDed with the site filter above, it is Zephyr Court alone.- chooseWorksOption("works-filter-work-status-finished", labelled: "Finished", in: app)+ // Named by a neighbour because the menu rows carry no identifiers and+ // the reading side has a "Finished" too (`work-and-reading-status`+ // Q23): this is the one directly below Ongoing.+ chooseWorksOption(+ "works-filter-work-status-finished", labelled: "Finished",+ nextTo: .below("Ongoing"), in: app) let marked = app.buttons.matching( NSPredicate(format: "label BEGINSWITH %@", "Open Work Zephyr Court")).firstMatch XCTAssertTrue(@@ -367,7 +372,12 @@ final class AccessibilityJourneyUITests: XCTestCase { // and at this size it still owns a 44 pt target. for identifier in [ "work-detail-work-status-ongoing", "work-detail-work-status-finished",- "work-detail-work-status-hiatus", "work-detail-reading-status-reading",+ "work-detail-work-status-hiatus",+ // `to-read` Req 1.6: the fifth segment, first in the capsule (Q8).+ // The list is walked in the order the capsule draws it, because the+ // scrolls below only ever go one way.+ "work-detail-reading-status-toRead",+ "work-detail-reading-status-reading", // `catch-up-mode` Q14: the fourth segment, at the size where the // capsule is most likely to have stacked. "work-detail-reading-status-catchingUp",@@ -1482,9 +1492,9 @@ final class WideLayoutAccessibilityUITests: XCTestCase { /// Landscape (1194 pt on an 11-inch iPad) is the sidebar-shown layout, so /// every case below starts on the side of the threshold where a collapse /// means something.- private func launch(textSize: String? = nil) {+ private func launch(scenario: String = "seeded-m1", textSize: String? = nil) { XCUIDevice.shared.orientation = .landscapeLeft- app.launchEnvironment["ASTERISM_UI_TEST_SCENARIO"] = "seeded-m1"+ app.launchEnvironment["ASTERISM_UI_TEST_SCENARIO"] = scenario app.launchEnvironment["ASTERISM_UI_TEST_RUN_ID"] = UUID().uuidString if let textSize { app.launchArguments += ["-UIPreferredContentSizeCategoryName", textSize]@@ -1524,6 +1534,117 @@ final class WideLayoutAccessibilityUITests: XCTestCase { assertAccessibilitySizeLayout(named: "AccessibilityXXXL") } + // MARK: - `to-read` Req 1.6 — the five reading-status segments on iPad++ /// Req 1.6's iPad half: with a fifth `ReadingStatus` the reading-status+ /// capsule draws five segments, and every one of them has to stay reachable+ /// and operable in edit mode in **both** of the iPad's wide layouts.+ ///+ /// The rotation is what makes that plural. Landscape is 1194 pt with the+ /// sidebar beside the pane; portrait is 834 pt with it collapsed, and the+ /// detail column the capsule has to fit inside is the narrower of the two+ /// there — which is where a row of five caption segments gives out and+ /// `ViewThatFits` takes the stacked arm (`to-read` Q4, Q16). It is done by+ /// turning the device rather than by a second launch because a portrait+ /// launch opens with no sidebar row and no tab bar, so the walk to the work+ /// could not start from one.+ ///+ /// **At the default text size**, for the reason+ /// `WideLayoutUITests.testThePlacesSectionAndReviewKindControlInTheDetailColumn`+ /// gives: at an accessibility size this device opens collapsed and there is+ /// nothing to select Works from. Req 1.6's largest-size half is the phone's,+ /// in `AccessibilityJourneyUITests` above.+ ///+ /// Zephyr Court is `seeded-works-options`' work that is finished on both+ /// sides, so its stored reading status is one of the five and choosing+ /// `toRead` asks nothing — Req 3.1's dialog belongs to `finished` alone, and+ /// `toRead` needs no work-status precondition at all (`to-read` Req 1.3).+ func testTheFiveReadingStatusSegmentsAreOperableInBothWideLayouts() {+ launch(scenario: "seeded-works-options")++ selectTab(.works, in: app)+ waitFor(app.collectionViews["works-list"], "Works lists the seeded library")+ waitFor(+ app.buttons.matching(+ NSPredicate(format: "label BEGINSWITH %@", "Open Work Zephyr Court")).firstMatch,+ "The doubly marked work is listed"+ ).tap()+ waitFor(app.anyElement("work-detail-pulse"), "The work fills the detail column")+ waitFor(app.buttons["work-detail-edit-button"], "The work page offers the editor").tap()+ waitFor(app.textFields["work-detail-title-field"], "The editor is open", timeout: 20)++ assertTheFiveSegmentsAreOperable(choosing: "toRead", layout: "landscape")++ XCUIDevice.shared.orientation = .portrait+ // The editor is view-model state, so the rotation keeps it — the same+ // fact `WideLayoutUITests.testRotationKeepsTheSelectedEntryOnScreen`+ // pins for a selection. Waited on rather than read once: the split view+ // re-lays out before the column settles at its portrait width.+ waitFor(+ app.buttons["work-detail-reading-status-toRead"],+ "The editor survives the turn into the collapsed layout", timeout: 20)+ assertTheFiveSegmentsAreOperable(choosing: "catchingUp", layout: "portrait")+ }++ /// Every segment of the reading-status capsule is present, hittable, named+ /// and a full 44 pt target — and `chosen` is tapped, because a target the+ /// right size that cannot be chosen is no better than a small one.+ ///+ /// Walked in the order the capsule draws them (`to-read` Q8 puts `toRead`+ /// first), because the reveal below only ever swipes one way — and the tap+ /// afterwards swipes the *other* way for the same reason: the walk ends at+ /// the last segment and `chosen` is above it+ /// (`docs/agent-notes/testing.md`).+ private func assertTheFiveSegmentsAreOperable(+ choosing chosen: String, layout: String,+ file: StaticString = #filePath, line: UInt = #line+ ) {+ for value in ["toRead", "reading", "catchingUp", "finished", "abandoned"] {+ let segment = app.buttons["work-detail-reading-status-\(value)"]+ revealInEditor(+ segment, "The capsule offers \(value) in \(layout)", file: file, line: line)+ XCTAssertFalse(+ segment.label.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,+ "\(value) needs an accessibility label", file: file, line: line)+ XCTAssertGreaterThanOrEqual(+ segment.frame.height.rounded(), 44,+ "\(value) is a full target in \(layout)", file: file, line: line)+ }++ let target = app.buttons["work-detail-reading-status-\(chosen)"]+ scrollUntilTappableAndTap(+ target, in: app, "\(chosen) is operable in \(layout)",+ scroll: { $0.swipeDown() }, file: file, line: line)+ let selected = XCTNSPredicateExpectation(+ predicate: NSPredicate { _, _ in+ self.app.buttons["work-detail-reading-status-\(chosen)"].isSelected+ }, object: nil)+ XCTAssertEqual(+ XCTWaiter().wait(for: [selected], timeout: 10), .completed,+ "Req 1.6: choosing \(chosen) moves the capsule in \(layout)", file: file, line: line)+ }++ /// Scrolls the detail column until `element` is **hittable**, and fails if+ /// eight screenfuls do not reach it.+ ///+ /// Reachable at a width means reachable by scrolling, so existence is not+ /// the question: a segment half in the column exists while the reader still+ /// cannot tap it. `app.swipeUp()` in the middle of the window is the detail+ /// column's own gesture here, which is the fact `revealInTheList` below+ /// records from the other side.+ private func revealInEditor(+ _ element: XCUIElement, _ message: String,+ file: StaticString = #filePath, line: UInt = #line+ ) {+ _ = element.waitForExistence(timeout: 15)+ for _ in 0..<8 {+ if element.exists, element.isHittable { return }+ app.swipeUp()+ _ = element.waitForExistence(timeout: 2)+ }+ XCTFail(message, file: file, line: line)+ }+ /// Req 8.3's rule: at an accessibility size the sidebar starts collapsed /// whatever the width, and the list column widens to 420 pt. ///
diff --git a/Asterism/AsterismUITests/TodayUITests.swift b/Asterism/AsterismUITests/TodayUITests.swiftindex 04febd09..5584f33d 100644--- a/Asterism/AsterismUITests/TodayUITests.swift+++ b/Asterism/AsterismUITests/TodayUITests.swift@@ -428,11 +428,22 @@ final class TodayUITests: XCTestCase { "The cell carries the day's full date rather than being an unlabelled target") assertNoDayTitle(daysFromLaunch: 0) + // **`currentCell` may not be on the strip at all** once the previous+ // day is selected: on the calendar's first weekday — which this suite+ // runs on one day in seven, and did on 2026-09-21 under a region whose+ // week starts on Monday — yesterday falls in the *previous* displayed+ // week, `selectDay` pages the strip back, and the current day's cell+ // leaves the accessibility tree. A bare `!currentCell.isSelected` then+ // raises `Failed to get matching snapshot` rather than reading false,+ // and the failure names the missing identifier as if the strip were+ // broken. The claim is that the current day is no longer the selected+ // one, which a cell that is not drawn satisfies. selectDay(daysFromLaunch: -1, "The previous day is on the strip, or one chevron back") let previousCell = stripCell(daysFromLaunch: -1) let moved = XCTNSPredicateExpectation( predicate: NSPredicate { _, _ in- previousCell.exists && previousCell.isSelected && !currentCell.isSelected+ previousCell.exists && previousCell.isSelected+ && !(currentCell.exists && currentCell.isSelected) }, object: nil) XCTAssertEqual( XCTWaiter().wait(for: [moved], timeout: 15), .completed,@@ -837,10 +848,15 @@ final class TodayUITests: XCTestCase { // the strip's **selected cell** — the one place the day is named, and // the thing that moves when the day changes. waitFor(app.anyElement("today-week-range"), "Req 3.6: Back returns to the day's chrome")+ // Read as "not the selected one" rather than "selected == false", for+ // the reason `testTheTabIsTodayAndTheScreenCarriesNoDayTitle` records:+ // on the calendar's first weekday the strip has paged back a week and+ // the current day's cell is not drawn. let currentCell = stripCell(daysFromLaunch: 0) let sameDay = XCTNSPredicateExpectation( predicate: NSPredicate { _, _ in- selectedCell.exists && selectedCell.isSelected && !currentCell.isSelected+ selectedCell.exists && selectedCell.isSelected+ && !(currentCell.exists && currentCell.isSelected) }, object: nil) XCTAssertEqual( XCTWaiter().wait(for: [sameDay], timeout: 15), .completed,
diff --git a/Asterism/AsterismUITests/UIJourneySupport.swift b/Asterism/AsterismUITests/UIJourneySupport.swiftindex 8d9dec0e..4cbde8c4 100644--- a/Asterism/AsterismUITests/UIJourneySupport.swift+++ b/Asterism/AsterismUITests/UIJourneySupport.swift@@ -72,6 +72,46 @@ extension XCUIApplication { } } +/// Which of several same-labelled rows of the Works options menu a caller+/// means, named by a uniquely labelled row of the same picker.+///+/// `.above("Has release days")` is "the `Any` directly above that row", which+/// is the Release days picker's own `Any` and not one of the other eight.+enum WorksOptionNeighbour {+ case above(String)+ case below(String)++ var label: String {+ switch self {+ case let .above(label), let .below(label): label+ }+ }++ /// How far from its anchor a candidate may sit and still be taken as that+ /// anchor's neighbour, in multiples of the **anchor row's own height** — so+ /// it scales with Dynamic Type instead of pinning a point distance.+ ///+ /// Three, which is the one number that fits every call site in+ /// `WorksView.optionsMenu`'s order. Counting rows, and remembering that+ /// each inline picker's title is drawn as a section header that takes space+ /// without being a button:+ ///+ /// - `.above("Has release days")` → the Release days `Any`, **two** rows up+ /// (`Any`, `No release days`, `Has release days`). The widest gap anyone+ /// asks for, and the reason the bound is not two.+ /// - `.above("No creators")` → the Creator `Any`, one row up. The nearest+ /// wrong `Any` is the Series picker's, three rows and a header further.+ /// - `.below("Ongoing")` → the Work status `Finished`, one row down. The+ /// reading side's `Finished` is six rows and a header below it.+ /// - `.below("Catching up")` → the Reading status `Finished`, one row down.+ /// No other `Finished` is below it at all.+ ///+ /// So every intended row is at two or less and every wrong one at more than+ /// three and a half. Verified on `iPhone Air` at the default text size and,+ /// for the first `.below("Ongoing")` site, at AXXXL.+ static let rowSpan: CGFloat = 3+}+ extension XCTestCase { /// Waits for whichever control selects `tab` in the layout on screen, taps /// it, and returns it.@@ -392,11 +432,79 @@ extension XCTestCase { /// the work editor's type picker is driven by its visible label for exactly /// that reason (`WorkDetailActionsUITests`). Preferring the identifier and /// falling back to the label lets either spelling drive the row.+ ///+ /// **For this menu the fallback is the only path.** Measured on 2026-09-21+ /// by dumping every button in the open popover: not one picker row carries+ /// its identifier — `works-sort-newest`, `works-filter-site-alpha.test`,+ /// `works-filter-release-days-any` and the rest all resolve to nothing, and+ /// the only identifier that survives into the menu is+ /// `works-list-group-by-series`, which is a `Toggle` rather than a `Picker`+ /// row. Every choice this helper has ever made was made by label.+ ///+ /// **Which matters because two of the labels are not unique**: every one of+ /// the eight `filterPicker` rows in `WorksView.optionsMenu` draws an `Any`+ /// row — the Sort picker is the ninth picker and the one that draws none —+ /// and both status vocabularies have a+ /// `Finished` (`work-and-reading-status` Q23 is about exactly that pair).+ /// The rows are drawn in a lazy collection view, so how many same-labelled+ /// rows are in the tree at once depends on where the menu is scrolled —+ /// which is why `app.buttons["Finished"]`, a subscript that *raises* on a+ /// query matching more than one element, resolved to one row for as long as+ /// it did. `to-read`'s fifth reading status moved every offset below Work+ /// status by 42 pt, and two `WorksListOptionsUITests` cases started dying+ /// with `Multiple matching elements found` — reported as "The menu offers+ /// Any" / "The menu offers Finished", which reads like a missing row rather+ /// than an ambiguous one.+ ///+ /// So a caller whose label is shared names a **uniquely labelled neighbour+ /// in the same picker** and gets the occurrence nearest to it on the named+ /// side — **and only when that occurrence is within+ /// ``WorksOptionNeighbour/rowSpan`` anchor row heights of the anchor**. That+ /// is a claim about the menu's own order, which is the production view's+ /// (`WorksView.optionsMenu`), rather than about how far the popover happens+ /// to be scrolled.+ ///+ /// The bound is what makes the claim honest. `.above`/`.below` otherwise+ /// take the nearest *materialised* same-labelled row at any distance, so a+ /// tree in which the intended row is not drawn yet answers another picker's+ /// row — an `Any` seven rows away is still "the nearest one above". Out of+ /// bound, and without a neighbour at all, an ambiguous label resolves to the+ /// (absent) identifier element, so the walk keeps scrolling and a genuine+ /// miss fails by name rather than tapping whichever row came first and+ /// quietly changing a different dimension. func worksOptionRow(- _ identifier: String, labelled label: String, in app: XCUIApplication+ _ identifier: String, labelled label: String,+ nextTo neighbour: WorksOptionNeighbour? = nil, in app: XCUIApplication ) -> XCUIElement { let byIdentifier = app.anyElement(identifier)- return byIdentifier.exists ? byIdentifier : app.buttons[label]+ if byIdentifier.exists { return byIdentifier }+ let candidates = app.buttons.matching(NSPredicate(format: "label == %@", label))+ .allElementsBoundByIndex+ guard let neighbour else {+ return candidates.count == 1 ? candidates[0] : byIdentifier+ }+ // Resolved through the neighbour even when only one candidate is in the+ // tree: the other occurrence may simply not be materialised yet, and+ // taking the lone one on trust is how a `Finished` tap lands on the+ // wrong dimension.+ let anchors = app.buttons.matching(NSPredicate(format: "label == %@", neighbour.label))+ .allElementsBoundByIndex+ guard anchors.count == 1 else { return byIdentifier }+ // Every `frame` is an accessibility round trip, so each element's is+ // read exactly once and carried as a number from here on.+ let anchorFrame = anchors[0].frame+ let anchorY = anchorFrame.minY+ let bound = anchorFrame.height * WorksOptionNeighbour.rowSpan+ let ordered = candidates.map { (element: $0, minY: $0.frame.minY) }+ .sorted { $0.minY < $1.minY }+ switch neighbour {+ case .above:+ return ordered.last { anchorY - $0.minY > 0 && anchorY - $0.minY <= bound }?.element+ ?? byIdentifier+ case .below:+ return ordered.first { $0.minY - anchorY > 0 && $0.minY - anchorY <= bound }?.element+ ?? byIdentifier+ } } /// Opens the Works options menu and chooses one row.@@ -405,8 +513,12 @@ extension XCTestCase { /// row below the fold is not in the accessibility tree at all — which is the /// ordinary case at the accessibility text sizes, where four sections of /// rows do not fit on a phone.+ ///+ /// `nextTo` is for the rows whose label is shared with another picker's;+ /// see ``worksOptionRow(_:labelled:nextTo:in:)``. func chooseWorksOption(- _ identifier: String, labelled label: String, in app: XCUIApplication,+ _ identifier: String, labelled label: String,+ nextTo neighbour: WorksOptionNeighbour? = nil, in app: XCUIApplication, file: StaticString = #filePath, line: UInt = #line ) { scrollUntilTappableAndTap(@@ -415,9 +527,19 @@ extension XCTestCase { // Give the menu its presentation animation before the first look: a row // that is not in the tree yet cannot be told apart from one that is // below the fold.- _ = worksOptionRow(identifier, labelled: label, in: app).waitForExistence(timeout: 5)+ //+ // The wait is on a **lazy label query**, and only ever waited on — it+ // is never the element that is tapped. `worksOptionRow` answers the+ // *identifier* element whenever it declines to resolve, and no menu row+ // carries its identifier, so waiting on its answer would sit out the+ // whole timeout at every one of the ~35 call sites before doing+ // anything. `firstMatch` is ambiguity-tolerant (unlike the `[label]`+ // subscript, which raises), and "some row with this label exists" is+ // all the presentation animation needs proving.+ _ = app.buttons.matching(NSPredicate(format: "label == %@", label)).firstMatch+ .waitForExistence(timeout: 5) for _ in 0..<8 {- let row = worksOptionRow(identifier, labelled: label, in: app)+ let row = worksOptionRow(identifier, labelled: label, nextTo: neighbour, in: app) if row.exists, row.isHittable { row.tap() waitUntilGone(@@ -462,6 +584,12 @@ extension XCTestCase { /// the step-by-step overlap is a claim about the old menu only. Re-measure /// it, the way `series-and-related-works` did, if a tenth dimension lands /// or a row starts being stepped over.+ ///+ /// **The menu does open at its head every time**, measured on 2026-09-21+ /// over the run that added the fifth reading status: with `Has release+ /// days` chosen in the last picker, the reopened popover still showed+ /// `Newest first` at y 78. So a one-way walk is enough and the row a walk+ /// cannot reach is an ambiguous label rather than a row behind it. private func scrollWorksOptionsMenu(in app: XCUIApplication) { app.swipeUp(velocity: .slow) }
diff --git a/Asterism/AsterismUITests/WorkDetailStatusUITests.swift b/Asterism/AsterismUITests/WorkDetailStatusUITests.swiftindex c003458b..ac388953 100644--- a/Asterism/AsterismUITests/WorkDetailStatusUITests.swift+++ b/Asterism/AsterismUITests/WorkDetailStatusUITests.swift@@ -13,8 +13,9 @@ import XCTest /// `seeded-works-options` is the fixture, shared with `WorksListOptionsUITests` /// so one seeded scenario carries the whole feature: **Marrow Lane** is /// abandoned with a verdict and is the work this suite edits, **Zephyr Court**-/// is finished on both sides, **Ashfall** is on hiatus, and **Quill Harbour** is-/// on the defaults.+/// is finished on both sides, **Ashfall** is on hiatus, **Quill Harbour** is+/// on the defaults, and **Vesper Tide** — `to-read`'s addition, entry-less on+/// alpha.test — carries `toRead`. /// /// `update-schedule` rides on the same four works: Marrow Lane carries Monday /// and Thursday, Ashfall carries Saturday, and Zephyr Court and Quill Harbour@@ -256,6 +257,78 @@ final class WorkDetailStatusUITests: XCTestCase { "Req 2.3: the verdict field goes with the done-reading status") } + // MARK: - `to-read` Reqs 1.1, 1.3, 1.4, 1.6 — the fifth segment++ /// The fifth reading-status segment, from the capsule to the meta line.+ ///+ /// `to-read` Req 1.6 is the half only a journey can say: five segments no+ /// longer fit across a phone's card at the default text size, so the control+ /// takes `ViewThatFits`' stacked arm here rather than only at an+ /// accessibility size (Q4's accepted cost, Q16's "no change to the+ /// control") — and the whole card grows by a row, which is why every step+ /// below reaches its target by scrolling rather than by looking where it+ /// used to be.+ ///+ /// Marrow Lane is the fixture's abandoned work **with entries and a+ /// verdict**, which makes it the case Req 1.4 names: a work the reader has+ /// noted chapters of can still be marked to read. The verdict field going+ /// with the change is Req 1.3 — `toRead` is not done reading — and nothing+ /// is asked on the way, because Req 3.1's dialog belongs to `finished`+ /// alone.+ func testMarkingAWorkToReadReachesTheFifthSegmentAndTheMetaLine() {+ launch()+ openWork("Marrow Lane")+ enterEditMode()++ let toRead = app.buttons["work-detail-reading-status-toRead"]+ scrollUntilPresent(toRead, in: app, "Req 1.6: the capsule offers the fifth segment")+ // The segment speaks its visible title; `Reading: To read` is the+ // qualified form the meta line and the filter pill carry, asserted at+ // the foot of this case.+ XCTAssertEqual(+ toRead.label, "To read", "Req 1.1: the segment names itself as the other four do")+ XCTAssertTrue(+ app.buttons["work-detail-reading-status-abandoned"].isSelected,+ "The editor opens on the stored reading status")+ waitFor(+ app.anyElement("work-detail-verdict-field"),+ "…so the abandoned work's verdict field is on screen before anything is tapped")++ scrollUntilTappableAndTap(toRead, in: app, "Req 1.6: and the fifth segment is operable")+ let chosen = XCTNSPredicateExpectation(+ predicate: NSPredicate { _, _ in+ self.app.buttons["work-detail-reading-status-toRead"].isSelected+ }, object: nil)+ XCTAssertEqual(+ XCTWaiter().wait(for: [chosen], timeout: 10), .completed,+ "Req 1.4: a work that has entries can be marked to read")+ XCTAssertFalse(+ app.dialogButton("work-detail-finished-mark-work").exists,+ "Req 1.3: to read needs no work-status precondition, so nothing is asked")+ XCTAssertTrue(+ app.buttons["work-detail-work-status-ongoing"].isSelected,+ "…and the work status is left where it was")+ waitUntilGone(+ app.anyElement("work-detail-verdict-field"),+ "Req 1.3: the verdict field is hidden for to read, as it is for Reading")++ waitFor(app.buttons["work-detail-save-button"], "The checkmark commits the editor").tap()+ waitUntilGone(+ app.textFields["work-detail-title-field"], "A committed editor returns to view mode")+ // View mode keeps the offset the editor was left at, and the walk above+ // scrolled past the meta line to reach the capsule — so the head of the+ // page is swiped back to rather than waited for where it used to be+ // (`docs/agent-notes/testing.md`; `scrollUntilPresent` only goes down).+ for _ in 0..<4 where !app.anyElement("work-detail-pulse").exists { app.swipeDown() }+ waitFor(app.anyElement("work-detail-pulse"), "View mode is back")++ let readingItem = waitFor(+ app.anyElement("work-detail-status-reading"),+ "Req 1.1: the meta line carries the new value")+ XCTAssertEqual(+ readingItem.label, "Reading: To read", "…qualified as the other four are")+ }+ // MARK: - The merge destination picker (Req 5.4) /// Req 5.4/Q32: the picker draws the library's own row, so its rows wear the@@ -294,6 +367,13 @@ final class WorkDetailStatusUITests: XCTestCase { XCTAssertTrue( labels.contains { $0.hasPrefix("Merge into Quill Harbour") && !$0.contains("Reading:") }, "…while a destination on both defaults reads as it always did — was \(labels)")+ // `to-read` Req 1.1: the fifth value is one of the marks a picker row+ // wears, in the same qualified words the meta line and the pill use.+ XCTAssertTrue(+ labels.contains {+ $0.hasPrefix("Merge into Vesper Tide") && $0.hasSuffix(". Reading: To read")+ },+ "…and the to-read destination names the new value — was \(labels)") waitFor(app.buttons["merge-cancel-button"], "The sheet offers the way out").tap() waitUntilGone(destinations.firstMatch, "Cancelling closes the picker")
diff --git a/Asterism/AsterismUITests/WorksCreatorOptionsUITests.swift b/Asterism/AsterismUITests/WorksCreatorOptionsUITests.swiftindex 1376d0d9..9910db7d 100644--- a/Asterism/AsterismUITests/WorksCreatorOptionsUITests.swift+++ b/Asterism/AsterismUITests/WorksCreatorOptionsUITests.swift@@ -117,11 +117,16 @@ final class WorksCreatorOptionsUITests: XCTestCase { XCTFail("The menu offers a row labelled \(label)", file: file, line: line) } + /// `nextTo` names a uniquely labelled row of the same picker, for a label+ /// another picker also draws — every one of the eight filter pickers draws an `Any`, and+ /// the menu's rows carry no identifiers (`worksOptionRow`). private func chooseOption( _ identifier: String, labelled label: String,+ nextTo neighbour: WorksOptionNeighbour? = nil, file: StaticString = #filePath, line: UInt = #line ) {- chooseWorksOption(identifier, labelled: label, in: app, file: file, line: line)+ chooseWorksOption(+ identifier, labelled: label, nextTo: neighbour, in: app, file: file, line: line) } // MARK: - Req 5.1 — the creator filter@@ -201,7 +206,9 @@ final class WorksCreatorOptionsUITests: XCTestCase { // Req 5.2: nothing about the rows changed — the list the filter narrows // is the one that was there.- chooseOption("works-filter-creator-any", labelled: "Any")+ // The Creator picker's own "Any", which is the row directly above its+ // "No creators" — seven other pickers draw an "Any" too.+ chooseOption("works-filter-creator-any", labelled: "Any", nextTo: .above("No creators")) assertListed(newestOrder, "Req 5.1: Any returns the whole list") } }
diff --git a/Asterism/AsterismUITests/WorksListOptionsUITests.swift b/Asterism/AsterismUITests/WorksListOptionsUITests.swiftindex e3509309..3d8a2b7d 100644--- a/Asterism/AsterismUITests/WorksListOptionsUITests.swift+++ b/Asterism/AsterismUITests/WorksListOptionsUITests.swift@@ -16,8 +16,16 @@ import XCTest /// status `hiatus`) and **Zephyr Court** (alpha.test, `novel`, finished on both /// sides with a verdict) captured in that order — so the date order is the /// reverse of it and disagrees with the alphabet at every position — plus the-/// entry-less **Quill Harbour** (beta.test, both statuses on their defaults)-/// and one unattached entry.+/// entry-less **Quill Harbour** (beta.test, both statuses on their defaults),+/// the entry-less **Vesper Tide** (alpha.test, reading `toRead`) and one+/// unattached entry.+///+/// `to-read` rides on the same scenario (Q21, Q24): Vesper Tide is the work+/// carrying the fifth reading status, and being entry-less it is also Req 1.5's+/// claim that a to-read row is placed exactly as any other work without entries+/// — inside the no-notes run under the date sorts, and among everything else+/// under the title ones. It is seeded last, so under Newest first it precedes+/// Quill Harbour in that run. /// /// `work-and-reading-status` rides on that one scenario rather than a second /// fixture, which is why the four order constants below sink Marrow Lane: Req@@ -39,10 +47,28 @@ final class WorksListOptionsUITests: XCTestCase { /// stable, so the abandoned work sinks inside the section it was already in /// while everything else keeps the sort's own order. Under Newest first it /// was already there, which is why only three of the four constants moved.- private let newestOrder = ["Zephyr Court", "Ashfall", "Marrow Lane", "Quill Harbour"]- private let oldestOrder = ["Ashfall", "Zephyr Court", "Marrow Lane", "Quill Harbour"]- private let aToZOrder = ["Ashfall", "Quill Harbour", "Zephyr Court", "Marrow Lane"]- private let zToAOrder = ["Zephyr Court", "Quill Harbour", "Ashfall", "Marrow Lane"]+ ///+ /// **Vesper Tide is the second entry-less work** (`to-read` Q24): under the+ /// date sorts the two of them are the trailing no-notes run, ordered by+ /// `modifiedAt` — Vesper Tide was seeded last, so Newest first puts it+ /// before Quill Harbour and Oldest first after it. Under the title sorts+ /// they join the one section and the alphabet decides.+ private let newestOrder = [+ "Zephyr Court", "Ashfall", "Marrow Lane", "Vesper Tide", "Quill Harbour",+ ]+ private let oldestOrder = [+ "Ashfall", "Zephyr Court", "Marrow Lane", "Quill Harbour", "Vesper Tide",+ ]+ private let aToZOrder = [+ "Ashfall", "Quill Harbour", "Vesper Tide", "Zephyr Court", "Marrow Lane",+ ]+ private let zToAOrder = [+ "Zephyr Court", "Vesper Tide", "Quill Harbour", "Ashfall", "Marrow Lane",+ ]++ /// The alpha.test site filter, under the opening Newest first sort: two+ /// works with notes and Vesper Tide in the trailing no-notes run.+ private let alphaSiteOrder = ["Zephyr Court", "Marrow Lane", "Vesper Tide"] override func setUp() { continueAfterFailure = false@@ -116,11 +142,17 @@ final class WorksListOptionsUITests: XCTestCase { /// Opens the menu and chooses one row. `chooseWorksOption` is shared with /// the accessibility journey (`UIJourneySupport`) and carries the /// identifier-or-label resolution and the scrolling a tall menu needs.+ ///+ /// `nextTo` names a uniquely labelled row of the same picker, for the rows+ /// whose own label another picker also draws — `Any`, which all nine draw,+ /// and `Finished`, which both status vocabularies have. private func chooseOption( _ identifier: String, labelled label: String,+ nextTo neighbour: WorksOptionNeighbour? = nil, file: StaticString = #filePath, line: UInt = #line ) {- chooseWorksOption(identifier, labelled: label, in: app, file: file, line: line)+ chooseWorksOption(+ identifier, labelled: label, nextTo: neighbour, in: app, file: file, line: line) } // MARK: - The journey@@ -165,9 +197,9 @@ final class WorksListOptionsUITests: XCTestCase { chooseOption("works-sort-newest", labelled: "Newest first") assertListed(newestOrder, "…and the reader can put it back") - // Req 5: one site, which is two of the four works.+ // Req 5: one site, which is three of the five works. chooseOption("works-filter-site-alpha.test", labelled: "alpha.test")- assertListed(["Zephyr Court", "Marrow Lane"], "A site filter keeps that site's works")+ assertListed(alphaSiteOrder, "A site filter keeps that site's works") waitFor(app.anyElement("works-filter-pills"), "Req 7: the active filter is on a pill") waitFor(app.anyElement("works-filter-clear"), "…beside the control that removes it") XCTAssertEqual(@@ -252,13 +284,13 @@ final class WorksListOptionsUITests: XCTestCase { waitFor(app.collectionViews["works-list"], "Works lists the seeded library") chooseOption("works-filter-site-alpha.test", labelled: "alpha.test")- assertListed(["Zephyr Court", "Marrow Lane"], "A site filter narrows the list")+ assertListed(alphaSiteOrder, "A site filter narrows the list") selectTab(.today, in: app) waitFor(app.collectionViews["recent-list"], "Recent is on screen") selectTab(.works, in: app) waitFor(app.collectionViews["works-list"], "Works is back")- assertListed(["Zephyr Court", "Marrow Lane"], "The filter survives a tab switch")+ assertListed(alphaSiteOrder, "The filter survives a tab switch") XCTAssertEqual( optionsMenu.label, "Sort and filter works, filters active", "…and the control still says so")@@ -267,7 +299,7 @@ final class WorksListOptionsUITests: XCTestCase { waitFor(app.anyElement("work-detail-pulse"), "The work opens", timeout: 20) app.navigationBars.buttons.element(boundBy: 0).tap() waitFor(app.collectionViews["works-list"], "The list is back")- assertListed(["Zephyr Court", "Marrow Lane"], "The filter survives a push and back")+ assertListed(alphaSiteOrder, "The filter survives a push and back") } /// The seeder itself, asserted from a launch rather than from a unit test@@ -317,18 +349,20 @@ final class WorksListOptionsUITests: XCTestCase { chooseOption("works-sort-aToZ", labelled: "A to Z") assertListed(aToZOrder, "A to Z sinks the abandoned work to the end") - // With a filter: alpha.test is Marrow Lane and Zephyr Court, which the- // alphabet on its own would order the other way round.+ // With a filter: alpha.test is Marrow Lane, Vesper Tide and Zephyr+ // Court, which the alphabet on its own would put Marrow Lane first of.+ // A to Z draws one section, so the entry-less Vesper Tide sits in the+ // alphabet rather than behind it (Req 2). chooseOption("works-filter-site-alpha.test", labelled: "alpha.test") assertListed(- ["Zephyr Court", "Marrow Lane"],+ ["Vesper Tide", "Zephyr Court", "Marrow Lane"], "Req 5.3: the partition holds with a filter on top of the sort") app.anyElement("works-filter-clear").tap() assertListed(aToZOrder, "The filter is cleared before the query goes on") - // And with a query: the title search keeps three of the four, and the- // abandoned one is still last of them. Typed last, so the field never- // has to be cleared again.+ // And with a query: the title search keeps three of the five — Zephyr+ // Court and Vesper Tide have no `a` — and the abandoned one is still+ // last of them. Typed last, so the field never has to be cleared again. let field = searchField(in: app) field.tap() field.typeText("a")@@ -366,7 +400,12 @@ final class WorksListOptionsUITests: XCTestCase { // Req 6.3: the two dimensions are not faceted and their vocabularies are // closed, so a pair no work carries is reachable — and the empty state // names both dimensions rather than reading "Finished, Abandoned".- chooseOption("works-filter-work-status-finished", labelled: "Finished")+ // "Finished" is also the reading side's name for a value (Q23), and+ // the menu rows carry no identifiers — so the picker is named by a row+ // only it has, and this is the Finished directly below Ongoing.+ chooseOption(+ "works-filter-work-status-finished", labelled: "Finished",+ nextTo: .below("Ongoing")) waitFor( app.anyElement("works-filter-empty"), "A combination no work carries is reachable and explains itself")@@ -381,17 +420,32 @@ final class WorksListOptionsUITests: XCTestCase { // Q23's whole reason: both vocabularies have a value called "Finished", // and with the pair the fixture does carry, both pills are on screen at // once and have to be tellable apart.- chooseOption("works-filter-reading-status-finished", labelled: "Finished")+ chooseOption(+ "works-filter-reading-status-finished", labelled: "Finished",+ nextTo: .below("Catching up")) assertListed(["Zephyr Court"], "The pair one work does carry lists it") waitFor(pill("Work: Finished"), "The work side's Finished names itself") waitFor(pill("Reading: Finished"), "…and the reading side's names itself too")++ // `to-read` Req 1.1: the fifth value is a filter row like the other+ // four, and the fixture's one to-read work answers to it. Clear first,+ // so the work-status Finished above is not ANDed into a miss.+ app.anyElement("works-filter-clear").tap()+ assertListed(newestOrder, "Clear removes both filters before the fifth value goes on")+ chooseOption("works-filter-reading-status-toRead", labelled: "To read")+ assertListed(["Vesper Tide"], "Req 1.1: the to-read filter keeps the to-read work")+ waitFor(pill("Reading: To read"), "Req 1.1: under the qualified pill the value spells")+ XCTAssertTrue(+ row(titled: "Vesper Tide").label.hasSuffix(". Reading: To read"),+ "Req 1.1: and the row itself names the value — was "+ + "\(row(titled: "Vesper Tide").label)") } // MARK: - `update-schedule`: the release-days dimension (Reqs 11.1, 11.3) /// Req 11.1's ninth dimension over the same fixture: **Marrow Lane** carries /// Monday and Thursday and **Ashfall** carries Saturday, while **Zephyr- /// Court** and **Quill Harbour** carry none.+ /// Court**, **Quill Harbour** and **Vesper Tide** carry none. /// /// Req 11.2's point is the pair the fixture was given: neither work with /// days is a *scheduled* work — Marrow Lane is abandoned and Ashfall is on@@ -425,7 +479,7 @@ final class WorksListOptionsUITests: XCTestCase { // and no schedule answers to it. chooseOption("works-filter-release-days-none", labelled: "No release days") assertListed(- ["Zephyr Court", "Quill Harbour"],+ ["Zephyr Court", "Vesper Tide", "Quill Harbour"], "Req 11.2: No release days keeps the rest, Quill Harbour among them") waitFor(pill("No release days"), "…under its own pill") XCTAssertFalse(@@ -463,7 +517,11 @@ final class WorksListOptionsUITests: XCTestCase { // others alone. chooseOption("works-filter-release-days-some", labelled: "Has release days") assertListed(["Ashfall", "Marrow Lane"], "The dimension is on again")- chooseOption("works-filter-release-days-any", labelled: "Any")+ // Every picker draws an "Any"; this is the one directly above the+ // Release days row that is on.+ chooseOption(+ "works-filter-release-days-any", labelled: "Any",+ nextTo: .above("Has release days")) assertListed(newestOrder, "Req 11.1: Any returns the whole list") XCTAssertFalse( pill("Has release days").exists, "…with the pill gone")
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7d0fc243..d3c79ae4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -176,6 +176,61 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- **To read, the app and its journeys (T-2354, `specs/to-read/`, tasks 10+ to 13).** The view models are pinned for the fifth status: choosing+ `To read` raises no finished-reading prompt, a work-status change+ leaves a to-read draft alone, the release-days line keeps its existing+ wording, the Works filter matches it under a `Reading: To read` pill,+ and a to-read row is active rather than sorted with abandoned. The+ editor journeys operate five segments at the largest Dynamic Type on+ iPhone and in both wide layouts on iPad; no scroll step had to change+ for the taller status card (Q28). The Works-options UI fixture gains+ `Vesper Tide`, a to-read work with no entries, and the four pinned+ orders are the design's. The fifth status moved the Works options+ menu's rows far enough to expose that its picker rows carry no+ accessibility identifiers and two labels (`Any`, `Finished`) are+ shared, so the UI journeys now pick a shared label by its uniquely+ labelled neighbour in the same picker. Unrelated to this feature,+ two `TodayUITests` assertions failed on the calendar's first weekday,+ when selecting yesterday pages the strip back a week and the current+ day's cell is no longer drawn; they now read "not the selected one".+ `make test-core` passes with zero known issues. `make test` and+ `make test-ui-ipad` pass apart from the two cases+ `docs/agent-notes/testing.md` records as failing at `main`'s tip and+ runner crashes that pass when run alone.++- **To read, the Core writes (T-2354, `specs/to-read/`, tasks 4 to 9).**+ The New Work form now creates a work as `toRead`: `NewWorkDraft` gains+ a `readingStatus` defaulted to `reading`, and the form is the one+ production caller that passes `toRead`, so Move To a new work, a+ capture and import still create `reading`. A committed capture into a+ to-read work, drained pending captures included, and a Move To of an+ entry not already in the work set `reading` in the same commit, on the+ rows that are on `toRead` only (`Work.promoteFromToRead`, Decision 1).+ Teaching, reparse, merge, collapse, import and a re-share do not+ promote. In the duplicate phase a `toRead` carrier writes only over+ `reading`, a `catchingUp` carrier does not write over `toRead`, and+ `finished` and `abandoned` carriers are unchanged. A Save from an+ editor opened before a promotion is last-writer-wins like any other+ field changed elsewhere, and may write `toRead` back (Q27).++- **To read, the status and its presentation (T-2354, `specs/to-read/`,+ tasks 1 to 3).** `ReadingStatus` has a fifth value, `toRead`, declared+ first so the order reads as a work's life. It is named `To read`,+ marked with the `bookmark` glyph, labelled `Reading: To read`, and has+ no verdict prompt because `isDone` is unchanged. No write path sets it+ yet. The pinned case lists moved with it, and the Core behaviours that+ need no code are pinned: it fans out to every row of a work group, it+ is authored content in the duplicate scan (folding a bare `reading`+ sibling, divergent against `catchingUp`, `finished` or `abandoned`), a+ to-read work reaches no Today releases or catch-up section while its+ entries stay in the noted section, it round-trips through the 14/15+ archive, and a merge keeps the target's status and lists a differing+ source `toRead` as discarded. No `allCases` dependency outside the+ design's audit surfaced; the golden archive and the library graph+ baseline did not move. `make test-core` and `make test-quick` pass+ with zero known issues.+ - **Empty Library, verification (T-2118, `specs/empty-library/`, tasks 19 and 20).** The `empty-library-m4` arm's provisional 60 s ceiling is replaced by 16 s, about twice its reading inside the full
diff --git a/Packages/AsterismCore/Sources/AsterismCore/DomainEnums.swift b/Packages/AsterismCore/Sources/AsterismCore/DomainEnums.swiftindex d9a2f0f8..e03e961d 100644--- a/Packages/AsterismCore/Sources/AsterismCore/DomainEnums.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/DomainEnums.swift@@ -58,9 +58,20 @@ public enum WorkStatus: String, CaseIterable, Codable, Sendable { /// terminal state, which is why it sits second (Q11) — the case order is /// display order only, and the stored value is the raw string. ///+/// `toRead` is a work the reader means to read and has not started: it is what+/// the New Work form creates, and a capture or a Move To into such a work+/// replaces it with `reading` in the same commit (`to-read` Decision 1). It is+/// declared **first** because the order then reads as a work's life — to read,+/// reading, catching up, finished, abandoned (`to-read` Q8) — and because the+/// order is display order only: nothing indexes `allCases`, the enum is not+/// `Comparable`, and reconciliation compares the raw string, where+/// `"reading" < "toRead"` keeps an existing `reading` row the representative of+/// a mixed group.+/// /// Same freezing rules as `WorkStatus`: the order is Req 6.1's, the raw values /// are `Work.readingStatusRaw`'s stored spellings. public enum ReadingStatus: String, CaseIterable, Codable, Sendable {+ case toRead case reading case catchingUp case finished@@ -69,7 +80,8 @@ public enum ReadingStatus: String, CaseIterable, Codable, Sendable { /// "Done reading" — the one derived predicate over this enum. Everything /// that shows or hides the verdict reads it, so the two-case test is /// spelled once rather than at every surface. `catchingUp` is not done:- /// the verdict stays hidden for it exactly as it does for `reading`.+ /// the verdict stays hidden for it exactly as it does for `reading`, and+ /// neither is `toRead`, which is the reader not having started at all. public var isDone: Bool { self == .finished || self == .abandoned } }
diff --git a/Packages/AsterismCore/Sources/AsterismCore/DuplicateReconciler.swift b/Packages/AsterismCore/Sources/AsterismCore/DuplicateReconciler.swiftindex 95f19739..51e60daa 100644--- a/Packages/AsterismCore/Sources/AsterismCore/DuplicateReconciler.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/DuplicateReconciler.swift@@ -1751,17 +1751,27 @@ enum DuplicateReconciler { row.workStatus = carriedWorkStatus changed = true }- // `catch-up-mode` Q10 narrows the reading status by one step. A- // carrier on `catchingUp` is authored content like any other, but it- // is a variant of `reading` rather than a done state: a group- // disagreeing between it and `finished` or `abandoned` is two- // variants and went to the reader before this write was reached, so- // the only sibling a `catchingUp` carrier may write over here is one- // still on the default. Same shape as the guard above, and for the- // same reason — the scan and the write read the rows at two- // different moments.- let carryMayOverwrite =- carriedReadingStatus != .catchingUp || row.readingStatus == .reading+ // `catch-up-mode` Q10 narrows the reading status by one step, and+ // `to-read` Q10 and Q12 narrow it by a second one. Two of the five+ // values are authored content like any other and yet may write only+ // over a row still on the default:+ //+ // - `catchingUp` is a variant of `reading` rather than a done state;+ // - `toRead` is the state *before* reading, and the reader may hold+ // it on a work that has entries (`to-read` Req 1.4).+ //+ // For both, a group disagreeing between the carrier's value and any+ // other authored one is two variants and went to the reader before+ // this write was reached, so the only sibling either may write over+ // here is one still on the default. `finished` and `abandoned`+ // carriers are unnarrowed and may write over either of them, which+ // `catch-up-mode` Q15 accepted and `to-read` Q12 leaves alone. Same+ // shape as the guard above, and for the same reason — the scan and+ // the write read the rows at two different moments, so a value guard+ // that only holds while they agree is not a guard at all.+ let writesOnlyOverDefault =+ carriedReadingStatus == .catchingUp || carriedReadingStatus == .toRead+ let carryMayOverwrite = !writesOnlyOverDefault || row.readingStatus == .reading if carriedReadingStatus != .reading, row.readingStatus != carriedReadingStatus, carryMayOverwrite {
diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ReparseCapture.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ReparseCapture.swiftindex 9d03bf04..32621587 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ReparseCapture.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository+ReparseCapture.swift@@ -473,6 +473,21 @@ extension LibraryRepository { // one on `Work`, so the two cannot drift: an identity match // refreshes the parsed title too. work.refreshParsedTitle(to: derivation.workName, commit: true)+ // `to-read` [3.1](../../../../specs/to-read/requirements.md#3.1)+ // and Decision 1: a chapter noted against a work the reader had+ // not started is evidence that they have. Per row rather than+ // per group (Q13): this commit does not refuse a torn work group+ // the way edit mode's Save does, so a group-wide write would put+ // `reading` over a sibling's `abandoned` that is still waiting on+ // the review card. The loop already stamps every row, so this+ // adds no fetch and dirties nothing new+ // ([3.3](../../../../specs/to-read/requirements.md#3.3),+ // [3.4](../../../../specs/to-read/requirements.md#3.4)).+ //+ // `applyCaptureAssignment` has one caller, `commitCapture`,+ // which the pending-capture drain also goes through, so this one+ // site covers Req 3.1 whole. A re-share never reaches it.+ work.promoteFromToRead() work.modifiedAt = timestamp } applyAssignmentProvenance(to: &citations, derivation: derivation,
diff --git a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swiftindex 2075892e..366ed7ce 100644--- a/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/LibraryRepository.swift@@ -1150,6 +1150,13 @@ public actor LibraryRepository { let work = Work.create( in: context, title: draft.displayTitle, hostname: hostname, site: site, timestamp: timestamp)+ // `to-read` [2.1](../../../../specs/to-read/requirements.md#2.1),+ // before the one save this call already makes. `Work.create` is+ // deliberately left alone: every other creation path goes through it+ // — Move To a new work, the capture commit's `.create` arm, import —+ // and none of them may mint a to-read work+ // ([2.2](../../../../specs/to-read/requirements.md#2.2)).+ work.readingStatus = draft.readingStatus do { try saveStrategy.save(context) } catch { throw LibraryRepositoryError.libraryUnavailable(@@ -1466,7 +1473,19 @@ public actor LibraryRepository { && $0.workAssignmentProvenance == .manual }) { return .committed } try self.stampWorkGroups(priorWorkIDs, at: timestamp, context: context)- for row in destinationGroup.rows { row.modifiedAt = timestamp }+ // `to-read` [3.2](../../../../specs/to-read/requirements.md#3.2)+ // and Decision 1: moving a noted chapter into a work is the same+ // evidence as capturing one into it. Gated on the entry group+ // not already pointing at this Work (Q20) — narrower than the+ // no-op return above, which also requires manual provenance on+ // every row, so re-moving an entry a rule attached is a real+ // write and not the reader starting to read. Per row rather than+ // per group, for the capture site's reason (Q13).+ let promotes = !priorWorkIDs.contains(workID)+ for row in destinationGroup.rows {+ if promotes { row.promoteFromToRead() }+ row.modifiedAt = timestamp+ } // Every row of the Entry group points at one row of the // destination group, which is the whole Work as far as Req 5.5's // presentation is concerned.
diff --git a/Packages/AsterismCore/Sources/AsterismCore/Models.swift b/Packages/AsterismCore/Sources/AsterismCore/Models.swiftindex c6235e66..aba36d1b 100644--- a/Packages/AsterismCore/Sources/AsterismCore/Models.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/Models.swift@@ -1879,6 +1879,27 @@ extension Work { if titleProvenance == .parsed { displayTitle = name } return changes }++ /// `to-read` [3.3](../../../../specs/to-read/requirements.md#3.3): a row on+ /// `toRead` becomes `reading`; a row on any other status is left alone.+ ///+ /// Carved out by name, which is what keeps `work-and-reading-status` Q8+ /// intact for the other four: an `abandoned` work that receives a capture+ /// stays `abandoned`. It is called from exactly two reader commits — the+ /// `.reuse`/`.claim` arm of `applyCaptureAssignment` and the `.existing` arm+ /// of `moveEntry` — and from nowhere else (Q19). Teaching's apply is the+ /// structural twin of the first and deliberately does not call it+ /// (Decision 1).+ ///+ /// It reads no clock and writes one column, so two devices given the same+ /// row reach the same answer and a second call changes nothing. The write+ /// goes through the raw column because the tolerant accessor reads an+ /// unknown stored spelling as `reading` — a row holding one is not a to-read+ /// row and must not be rewritten as though it were.+ func promoteFromToRead() {+ guard readingStatusRaw == ReadingStatus.toRead.rawValue else { return }+ readingStatusRaw = ReadingStatus.reading.rawValue+ } } extension UUID {
diff --git a/Packages/AsterismCore/Sources/AsterismCore/RepositoryDrafts.swift b/Packages/AsterismCore/Sources/AsterismCore/RepositoryDrafts.swiftindex ccab5dde..4864fa08 100644--- a/Packages/AsterismCore/Sources/AsterismCore/RepositoryDrafts.swift+++ b/Packages/AsterismCore/Sources/AsterismCore/RepositoryDrafts.swift@@ -34,10 +34,22 @@ public enum CaptureSiteStatus: Equatable, Sendable { public struct NewWorkDraft: Equatable, Sendable { public let displayTitle: String public let hostname: String+ /// `to-read` Q18: the reading status the created work is born with, and+ /// **defaulted**, which is the opposite choice from `WorkMetadataDraft`'s+ /// statuses below and made for the opposite reason. That draft writes every+ /// row of an existing group, so an omitted field would silently reset a+ /// reader's status; this one creates a row that has no status yet, and it+ /// has one production caller — the New Work form, which passes `.toRead`+ /// ([2.1](../../../../specs/to-read/requirements.md#2.1)) — beside some+ /// sixty fixture, seed and test callers that model a captured work and must+ /// keep `reading` ([2.2](../../../../specs/to-read/requirements.md#2.2),+ /// Q15). The default is what keeps those callers unedited.+ public let readingStatus: ReadingStatus - public init(displayTitle: String, hostname: String) {+ public init(displayTitle: String, hostname: String, readingStatus: ReadingStatus = .reading) { self.displayTitle = displayTitle self.hostname = hostname+ self.readingStatus = readingStatus } }
diff --git a/Packages/AsterismCore/Sources/ConstellationKit/ConstellationRecipes.swift b/Packages/AsterismCore/Sources/ConstellationKit/ConstellationRecipes.swiftindex 6a9a1021..2901e8fb 100644--- a/Packages/AsterismCore/Sources/ConstellationKit/ConstellationRecipes.swift+++ b/Packages/AsterismCore/Sources/ConstellationKit/ConstellationRecipes.swift@@ -251,7 +251,7 @@ extension View { // MARK: - Segmented capsule -/// The segmented capsule of §7: two or three short labels, all of them visible,+/// The segmented capsule of §7: a handful of short labels, all of them visible, /// so the reader sees the state instead of opening something to read it. /// /// One definition for both of its users — work detail's `Newest | Chapter` sort@@ -266,10 +266,20 @@ extension View { /// visual is the floor once it passes 44, or the selected fill would overflow /// the row it is drawn behind. ///-/// At the largest accessibility sizes the labels cannot share a line even on a-/// line of their own, so a second `ViewThatFits` candidate stacks them full-/// width in a card-radius rectangle. §10 forbids clipping and truncation, and a-/// hyphenated control label reads no better than either.+/// When the labels cannot share a line even on a line of their own, a second+/// `ViewThatFits` candidate stacks them full width in a card-radius rectangle.+/// §10 forbids clipping and truncation, and a hyphenated control label reads no+/// better than either.+///+/// **That arm is no longer only the largest accessibility sizes' business.**+/// `to-read` gave the reading-status capsule a fifth value, and five caption+/// segments do not fit across a phone's card at the default text size — so the+/// stacked layout is what a phone draws there, and the row is what the wider+/// iPad and Mac columns get. The control is unchanged for it (`to-read` Q16):+/// `ViewThatFits` is the whole mechanism, and the only thing that moved is+/// which candidate is usual. What follows from it belongs to the callers: a+/// card holding this control is taller than it was, so a UI journey reaching a+/// field below one scrolls to it rather than looking where it used to be. public struct ConstellationSegmentedControl<Value: Hashable>: View { private let values: [Value] @Binding private var selection: Value
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/BackupV14ArchiveTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/BackupV14ArchiveTests.swiftindex 52cd0b9a..09c2a63b 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/BackupV14ArchiveTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/BackupV14ArchiveTests.swift@@ -3742,6 +3742,39 @@ struct BackupV14ImportTests { try await target.repository.work(id: BackupV14Fixtures.composedWorkID).readingStatus == .catchingUp) }++ /// `to-read` Req 6.1, and the same reasoning as the case above: the fifth+ /// reading status is vocabulary rather than structure, so it travels under+ /// the **unchanged** 14/15 pair and no generation moves for it.+ ///+ /// The composed fixture's work carries an entry, which is the point of+ /// running it through this seam: a to-read work with chapters noted against+ /// it is a state the reader can author (Req 1.4) and a restore has to bring+ /// back as it was, rather than reading the entries as evidence that the+ /// work was started.+ @Test("A work on toRead exports and imports unchanged under 14/15")+ func toReadRoundTrips() async throws {+ let source = try await M5Fixture()+ try await source.repository.confirmImport(+ plan: BackupV14Fixtures.plan(+ BackupV14Fixtures.composedPayload(readingStatus: .toRead)))++ let payload = try await source.repository.backupV14Snapshot()+ #expect(+ payload.works.first { $0.id == BackupV14Fixtures.composedWorkID }?.readingStatus+ == .toRead)++ let encoded = try BackupV14Codec.encode(+ payload: payload, metadata: BackupV14Fixtures.metadata())+ #expect(try BackupV14Codec.decode(encoded).backupFormatVersion == 14)++ let target = try await M5Fixture()+ try await target.repository.confirmImport(plan: try BackupImporter.plan(from: encoded))++ let restored = try await target.repository.work(id: BackupV14Fixtures.composedWorkID)+ #expect(restored.readingStatus == .toRead)+ #expect(restored.entries.count == 1)+ } } // MARK: - Test Doubles
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swiftindex 74d4773e..93b0f651 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/ComposedTeachingRepositoryTests.swift@@ -379,6 +379,41 @@ struct ComposedTeachingRepositoryTests { #expect(work.primaryMembership?.urlIdentityState == .rule) } + /// `to-read` Decision 1's third rejected alternative, pinned. Teaching's+ /// apply is the structural twin of the capture site — the same+ /// `.reuse`/`.claim` arm over the same group rows — and it deliberately does+ /// **not** promote: the sweep is a bulk repair that can claim many entries+ /// across many works in one pass, its timing says nothing about when reading+ /// began, and promoting from it would put a shelf of planned works on Today+ /// at once. A to-read work that gains entries this way keeps `toRead`, and+ /// the reader changes it in edit mode (Non-Goal).+ @Test("Teaching's claim of earlier captures into a to-read Work leaves it to read")+ func teachingClaimDoesNotPromoteAToReadWork() async throws {+ let fixture = try ComposedRepoFixture()+ let e10 = UUID(), e11 = UUID()+ try seedTapasEpisodes(fixture, e10, e11)+ // Titled as the untrimmed rule parses these captures, with no entries+ // and no identity, which is what makes it claim-eligible.+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Read The Regressor Creates Everything", hostname: host,+ readingStatus: .toRead))++ let contract = try await fixture.repository.projectComposedTeaching(+ hostname: host,+ request: ComposedTeachingRequest(+ titleDefinition: try tapasSegment(), urlDefinition: tapasURL()))+ guard case .committed = try await fixture.repository.commitComposedTeaching(contract) else {+ Issue.record("expected the teach to commit"); return+ }++ let context = fixture.freshContext()+ let claimed = try #require(+ try context.fetch(FetchDescriptor<Work>()).first { $0.id == planned.id })+ #expect(claimed.entryValues.count == 2, "the sweep did claim the two episodes")+ #expect(claimed.readingStatus == .toRead)+ }+ @Test("A manual display title survives the rename an identity match applies (Req 3.21)") func manualDisplayTitleSurvivesRename() async throws { let fixture = try ComposedRepoFixture()
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateReconcilerTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateReconcilerTests.swiftindex 96597219..fe9dfdfb 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateReconcilerTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateReconcilerTests.swift@@ -578,6 +578,197 @@ struct DuplicateReconcilerTests { #expect(works.allSatisfy { $0.genericNotes == "reader notes" }) } + // MARK: - `to-read` Req 5.2: the fifth status's carry directions++ /// `to-read` Q10 and Q12. A carrier on `toRead` is authored content like any+ /// other, so the arm would carry it over anything — including a sibling the+ /// reader has since caught up on, finished or abandoned on another device.+ /// `toRead` gets `catchingUp`'s narrowing and for the same reason: it is a+ /// state *before* reading rather than a done one, so the only sibling it may+ /// write over here is one still on the default.+ ///+ /// The third row, left on `reading`, is the control: the guard is a+ /// direction, not a veto on `toRead` propagating at all. It is what pins the+ /// first half of Req 5.2 — a `toRead` carrier does write over `reading`.+ @Test(+ "A toRead carrier writes over a sibling on reading and never over another status",+ arguments: [ReadingStatus.catchingUp, .finished, .abandoned])+ func toReadCarrierOnlyWritesOverAReadingSibling(_ sibling: ReadingStatus) throws {+ let store = try DuplicateStore()+ let site = store.addSite()+ let workID = DuplicateStore.rankedID(1)+ let carrier = store.addWork(+ id: workID, title: "The Serial", createdAt: 0, notes: "reader notes", site: site)+ carrier.readingStatus = .toRead+ store.addWork(id: workID, title: "The Serial", createdAt: 30, site: site)+ store.addWork(id: workID, title: "The Serial", createdAt: 60, site: site)+ try store.commit()++ try store.reconcile(afterScan: { context in+ // One of the two bare rows takes the other status after the scan+ // classified the set; the other is left on the default.+ let rows = try context.fetch(FetchDescriptor<Work>())+ .filter { $0.genericNotes.isEmpty }+ .sorted { $0.createdAt < $1.createdAt }+ rows.first?.readingStatus = sibling+ })+ // The blocked group is a *stable* state: the two authored statuses+ // disagree, so every later pass calls the set divergent and hands it to+ // the reader rather than picking a winner.+ try store.reconcileToFixedPoint()++ let works = try store.workFacts()+ #expect(works.count == 3, "a split group's rows are converged, never collapsed")+ #expect(works.filter { $0.readingStatus == sibling }.count == 1)+ #expect(+ works.filter { $0.readingStatus == .toRead }.count == 2,+ "the carrier and the sibling still on the default")+ #expect(works.allSatisfy { $0.genericNotes == "reader notes" })+ }++ /// The other direction of the same narrowing, and the one `to-read` Q12+ /// names: a `catchingUp` carrier may write only over `reading`, so a sibling+ /// the reader has since set back to `toRead` on another device keeps it.+ /// Without this the fifth status would be silently disposable by a carrier+ /// on the fourth.+ @Test("A catchingUp carrier never writes over a toRead sibling")+ func catchingUpCarrierNeverOverwritesAToReadSibling() throws {+ let store = try DuplicateStore()+ let site = store.addSite()+ let workID = DuplicateStore.rankedID(1)+ let carrier = store.addWork(+ id: workID, title: "The Serial", createdAt: 0, notes: "reader notes", site: site)+ carrier.readingStatus = .catchingUp+ store.addWork(id: workID, title: "The Serial", createdAt: 30, site: site)+ store.addWork(id: workID, title: "The Serial", createdAt: 60, site: site)+ try store.commit()++ try store.reconcile(afterScan: { context in+ let rows = try context.fetch(FetchDescriptor<Work>())+ .filter { $0.genericNotes.isEmpty }+ .sorted { $0.createdAt < $1.createdAt }+ rows.first?.readingStatus = .toRead+ })+ try store.reconcileToFixedPoint()++ let works = try store.workFacts()+ #expect(works.count == 3, "a split group's rows are converged, never collapsed")+ #expect(works.filter { $0.readingStatus == .toRead }.count == 1)+ #expect(works.filter { $0.readingStatus == .catchingUp }.count == 2)+ #expect(works.allSatisfy { $0.genericNotes == "reader notes" })+ }++ /// `to-read` Q12's other half, on the shape of+ /// `aDoneCarrierStillOverwritesACatchingUpSibling` above: the narrowing is+ /// one-directional, so a carrier on `finished` or `abandoned` may still write+ /// over a sibling authored `toRead`, exactly as it may over one authored+ /// `catchingUp` today. This feature changes neither direction, so what is+ /// asserted here is the *accepted* outcome rather than a desirable one — a+ /// later change that closes it should have to come here and say so.+ @Test("A finished carrier still writes over a toRead sibling, as Q12 accepts")+ func aDoneCarrierStillOverwritesAToReadSibling() throws {+ let store = try DuplicateStore()+ let site = store.addSite()+ let workID = DuplicateStore.rankedID(1)+ let carrier = store.addWork(+ id: workID, title: "The Serial", createdAt: 0, notes: "reader notes", site: site)+ carrier.readingStatus = .finished+ store.addWork(id: workID, title: "The Serial", createdAt: 30, site: site)+ store.addWork(id: workID, title: "The Serial", createdAt: 60, site: site)+ try store.commit()++ try store.reconcile(afterScan: { context in+ // The reader sets one of the two bare rows back to `toRead` on+ // another device, after the scan has already classified the set as+ // bare folding into authored.+ let rows = try context.fetch(FetchDescriptor<Work>())+ .filter { $0.genericNotes.isEmpty }+ .sorted { $0.createdAt < $1.createdAt }+ rows.first?.readingStatus = .toRead+ })+ try store.reconcileToFixedPoint()++ let works = try store.workFacts()+ #expect(works.count == 3, "a split group's rows are converged, never collapsed")+ #expect(+ works.allSatisfy { $0.readingStatus == .finished },+ "Q12: the done carrier wins and the group settles on it, the toRead overwritten")+ #expect(works.allSatisfy { $0.genericNotes == "reader notes" })+ }++ /// One of `to-read` Decision 1's non-callers, from the silent path: a+ /// collapse re-points a loser's Entries onto the survivor, which is a Work+ /// gaining entries without anybody noting a chapter. A survivor on `toRead`+ /// keeps it — the reconcilers never write a status on the basis of an event,+ /// only on the basis of synced content.+ @Test("A collapse re-pointing entries onto a to-read survivor leaves it to read")+ func aCollapseLeavesAToReadSurvivorToRead() throws {+ let store = try DuplicateStore()+ let site = store.addSite()+ let survivorID = DuplicateStore.rankedID(9)+ let loserID = DuplicateStore.rankedID(1)+ let survivor = store.addWork(+ id: survivorID, title: "The Serial", urlIdentity: "series-a", createdAt: 0, site: site)+ survivor.readingStatus = .toRead+ let loser = store.addWork(+ id: loserID, title: "The Serial", urlIdentity: "series-a", createdAt: 100, site: site)+ let moved = store.addEntry(+ key: "chapter-2", capturedAt: 5, work: loser, site: site)+ moved.editCitations { $0.workAssignment = .manual }+ try store.commit()++ try store.reconcileToFixedPoint()++ let works = try store.workFacts()+ #expect(works.count == 1)+ let kept = try #require(works.first)+ #expect(kept.id == survivorID)+ #expect(kept.entryIDs == [moved.id])+ #expect(kept.readingStatus == .toRead)+ }++ /// `to-read` Decision 1's **accepted negative consequence**, pinned here so a+ /// later reader meets the decision rather than a bug report.+ ///+ /// A capture mints a `reading` row on one device and promotes it; the same+ /// work's `toRead` row arrives from another device that has not seen the+ /// capture. The promoted row is otherwise bare, so the scan folds it into the+ /// authored `toRead` one and convergence writes `toRead` back over it: the+ /// promotion is an *event*, not a function of synced content, and the silent+ /// path only knows the latter. The reader's own to-read marking is the thing+ /// that survives, which is the side to err on.+ ///+ /// **This is not a defect to repair here.** Making `toRead` unauthored so+ /// `reading` could win was considered and rejected at Q11: both rows would+ /// then be bare, the carry is gated on a non-`reading` carrier, and a+ /// deliberate `toRead` would become silently disposable.+ @Test("A promoted bare reading row beside a toRead twin converges back to toRead (Decision 1)")+ func aPromotedBareRowConvergesBackToToRead() throws {+ let store = try DuplicateStore()+ let site = store.addSite()+ let workID = DuplicateStore.rankedID(1)+ // The reader's row: authored `toRead`, arriving from the device where+ // they planned the work.+ let planned = store.addWork(+ id: workID, title: "The Serial", createdAt: 0, site: site)+ planned.readingStatus = .toRead+ // The other device's row, promoted by its own capture and carrying+ // nothing else the reader wrote.+ let promoted = store.addWork(+ id: workID, title: "The Serial", createdAt: 30, site: site)+ promoted.readingStatus = .reading+ store.addEntry(key: "chapter-1", capturedAt: 40, work: promoted, site: site)+ try store.commit()++ try store.reconcileToFixedPoint()++ let works = try store.workFacts()+ #expect(works.count == 2, "a split group's rows are converged, never collapsed")+ #expect(+ works.allSatisfy { $0.readingStatus == .toRead },+ "Decision 1: the promotion is undone by the carry, and that is accepted")+ }+ // MARK: - V11: the series pair (Reqs 9.6, 11.3) /// Req 11.3, on the `genreTags` shape: a membership the carrier holds
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateScanTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateScanTests.swiftindex 3055eba8..c5023b4a 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateScanTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/DuplicateScanTests.swift@@ -257,6 +257,48 @@ struct DuplicateScanTests { #expect(set.variants.map(\.content.readingStatus) == [.catchingUp, done]) } + /// `to-read` Q10, the same rule for the fifth value: `toRead` is+ /// reader-authored content, so a member still on the default `reading`+ /// folds into it and the reader is never asked about a decision they have+ /// already made on another device.+ ///+ /// The fold is narrow by construction: a work made by the New Work form+ /// carries a manual title, which is authored content of its own, so only a+ /// capture-minted row with nothing else authored can fold this way.+ @Test("A toRead member beside a bare one on reading resolves silently to toRead")+ func toReadBesideBareReadingResolvesSilently() throws {+ let store = try ScanStore()+ store.addWork(title: "A Serial", parsedTitle: "A Serial", offset: 0)+ let planned = store.addWork(title: "A Serial", parsedTitle: "A Serial", offset: 60)+ planned.readingStatus = .toRead+ try store.commit()++ let set = try #require(try store.scan().workSets.first)+ #expect(set.classification == .silentlyResolvable)+ #expect(set.variants.map(\.content.readingStatus) == [.toRead])+ }++ /// The other half of `to-read` Q10: a work the reader has not started and+ /// one they have finished or abandoned are two things the reader said, so+ /// the set is two variants and goes to the review card with the reading+ /// status among the fields that differ (Req 5.1). `catchingUp` makes the+ /// same set for the same reason.+ @Test("A toRead member against a moved one is divergent", arguments: [+ ReadingStatus.catchingUp, .finished, .abandoned,+ ])+ func toReadAgainstAMovedStatusIsDivergent(_ moved: ReadingStatus) throws {+ let store = try ScanStore()+ let planned = store.addWork(title: "A Serial", parsedTitle: "A Serial", offset: 0)+ planned.readingStatus = .toRead+ let started = store.addWork(title: "A Serial", parsedTitle: "A Serial", offset: 60)+ started.readingStatus = moved+ try store.commit()++ let set = try #require(try store.scan().workSets.first)+ #expect(set.classification == .divergent)+ #expect(set.variants.map(\.content.readingStatus) == [.toRead, moved])+ }+ /// Req 3.3: bare and agreeing members must not enlarge the decision. @Test("Bare members do not enlarge a divergent set's variant list") func bareMembersDoNotEnlargeTheDecision() throws {
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/FanOutWriteTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/FanOutWriteTests.swiftindex 787b823c..97286ed8 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/FanOutWriteTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/FanOutWriteTests.swift@@ -287,6 +287,48 @@ struct FanOutWriteTests { #expect(rows.allSatisfy { $0.verdict == "a fine ending" }) } + /// `to-read` Req 1.4: the fifth reading status is written by the ordinary+ /// edit-mode path, on a work that **has entries** as readily as on one that+ /// has none — the reader can mark something they mean to start again — and+ /// it fans out to every row of the group like any other metadata field.+ ///+ /// Nothing here is new code; the test exists so the behaviour cannot drift+ /// into a promotion rule or an entry-count gate later.+ @Test("updateWork writes toRead to every row of a Work group that has entries")+ func updateWorkFansOutToRead() async throws {+ let library = try WriteFixture()+ let workID = UUID()+ try library.seed { store in+ store.insertSite(hostname: "dup.example")+ let first = store.insertWork(+ id: workID, hostname: "dup.example", title: "A Serial", offset: 0)+ store.insertWork(id: workID, hostname: "dup.example", title: "A Serial", offset: 30)+ let entry = store.insertEntry(+ id: UUID(), hostname: "dup.example", title: "Chapter", offset: 0)+ entry.work = first+ entry.editCitations { $0.workAssignment = .manual }+ }+ let repository = try await library.openForApp()++ let outcome = try await repository.updateWork(+ id: workID, basis: try library.workBasis(id: workID),+ draft: WorkMetadataDraft(+ displayTitle: "A Serial", typeAssignment: .none, genreTags: [],+ genericNotes: "",+ workStatus: .ongoing, readingStatus: .toRead, verdict: "", releaseDays: [],+ membership: nil, thumbnail: .keep))++ #expect(outcome == .committed)+ let rows = try library.workRows(id: workID)+ #expect(rows.count == 2)+ #expect(rows.allSatisfy { $0.readingStatus == .toRead })+ // Req 5.1: the value is reader-authored content, so neither row reads as+ // bare and the duplicate phase cannot fold one away silently.+ #expect(rows.allSatisfy {+ GroupOrdering.authoredContent(of: $0, types: .empty).isBare == false+ })+ }+ /// Q33's trim is what keeps a verdict of nothing but spaces from counting as /// authored content: `isBare` tests `verdict.isEmpty`, so an untrimmed /// `" "` would make the Work non-bare for good and take silent duplicate
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/GroupOrderingTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/GroupOrderingTests.swiftindex 172cc1b1..43a15ab2 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/GroupOrderingTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/GroupOrderingTests.swift@@ -429,6 +429,36 @@ struct GroupOrderingTests { #expect(GroupOrdering.authoredContent(of: work, types: .empty).isBare) } + /// `to-read` Req 5.1: the fifth value is authored content like the other+ /// three non-defaults — `isBare` asks for `reading` and nothing else, so a+ /// row the reader marked to read can never be collapsed away silently.+ ///+ /// The second half is why the enum's declaration order is display order+ /// only: the row order compares the **raw string**, and `"reading"` sorts+ /// before `"toRead"`, so a `toRead` sibling does not displace an existing+ /// `reading` row as the group's representative.+ @Test("A Work on toRead is authored content and orders behind one on reading")+ func toReadIsAuthoredContent() throws {+ let store = try OrderingStore()+ let work = store.addWork(title: "A Work", offset: 0)+ work.lastParsedTitle = "A Work"+ try store.commit()+ #expect(GroupOrdering.authoredContent(of: work, types: .empty).isBare)++ work.readingStatus = .toRead+ #expect(GroupOrdering.authoredContent(of: work, types: .empty).readingStatus == .toRead)+ #expect(GroupOrdering.authoredContent(of: work, types: .empty).isBare == false)++ let tokens = { (content: WorkAuthoredContent) in+ content.orderComponents.map(\.canonicalToken)+ }+ #expect(tokens(WorkAuthoredContent(readingStatus: .toRead)) != tokens(WorkAuthoredContent()))+ #expect(+ tokens(WorkAuthoredContent(readingStatus: .toRead))+ != tokens(WorkAuthoredContent(readingStatus: .catchingUp)))+ #expect(ReadingStatus.reading.rawValue < ReadingStatus.toRead.rawValue)+ }+ /// Req 7.2: each of the three has to reach `orderComponents`, or two rows /// differing only on one of them would hash to a single variant and one /// reader's value would be lost to the other's.
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/ModelContractTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/ModelContractTests.swiftindex 9a1be65f..be5682d2 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/ModelContractTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/ModelContractTests.swift@@ -56,9 +56,15 @@ struct ModelContractTests { // rather than structure, so the column, the snapshot and the archive // generation all stand still, and the case order is the display order // the picker and the filter menu iterate.+ //+ // `to-read` Q4 and Q8 add the fifth value **first**, for the same+ // reason and at the same cost: the order now reads as a work's life —+ // to read, reading, catching up, finished, abandoned. The order is+ // display order only and gives `toRead` no precedence in+ // reconciliation, where the raw string is what is compared. #expect( ReadingStatus.allCases.map(\.rawValue)- == ["reading", "catchingUp", "finished", "abandoned"])+ == ["toRead", "reading", "catchingUp", "finished", "abandoned"]) // V15's release days. The raw values are the strings // `Work.releaseDaysRaw` holds, and the **case order** is the canonical // storage and wire order — fixed at Monday first so two rows given the@@ -71,6 +77,11 @@ struct ModelContractTests { ]) // The one derived predicate: everything that shows or hides the verdict // reads it.+ //+ // A work the reader has not started is not done reading (`to-read`+ // Req 1.3), so the verdict is hidden for it exactly as it is for+ // `reading`.+ #expect(ReadingStatus.toRead.isDone == false) #expect(ReadingStatus.reading.isDone == false) // A reader who is behind is still reading (`catch-up-mode`), so the // verdict stays hidden for them.@@ -866,6 +877,39 @@ struct ModelContractTests { #expect(work.membership(for: "elsewhere.example") == nil) } + /// `to-read` [3.3](../../../../specs/to-read/requirements.md#3.3), over+ /// every status a row can be in. The promotion is carved out by name: it+ /// replaces `toRead` and nothing else, so `work-and-reading-status` Q8's+ /// guarantee that a capture leaves a status alone still holds for the other+ /// four — the `abandoned` row that receives a chapter is the pinned case.+ ///+ /// The second call is asserted because both call sites run inside a loop+ /// over a group's rows and the operation must be idempotent: a row already+ /// promoted is a row that is now on `reading`, which is not `toRead`.+ @Test(+ "promoteFromToRead replaces toRead and leaves every other status",+ arguments: ReadingStatus.allCases)+ func promotionReplacesOnlyToRead(_ status: ReadingStatus) throws {+ let fixture = try ModelFixture()+ let instant = Date(timeIntervalSince1970: 1_800_000_000)+ let work = Work.create(+ in: fixture.context, title: "A Work", hostname: "promote.example", timestamp: instant)+ work.readingStatus = status+ try fixture.context.save()++ work.promoteFromToRead()+ let expected: ReadingStatus = status == .toRead ? .reading : status+ #expect(work.readingStatus == expected)++ work.promoteFromToRead()+ #expect(work.readingStatus == expected, "a second call changes nothing")+ // Req 3.4: the promotion writes the reading status and nothing else.+ #expect(work.workStatus == .ongoing)+ #expect(work.verdict == "")+ #expect(work.releaseDaysRaw.isEmpty)+ #expect(work.modifiedAt == instant)+ }+ /// Req 1.2's ordering, which every site-listing surface reads. @Test("Memberships order by creation date, then identifier") func membershipOrdering() throws {
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/PendingCaptureDrainTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/PendingCaptureDrainTests.swiftindex 9231d806..e44faf38 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/PendingCaptureDrainTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/PendingCaptureDrainTests.swift@@ -536,6 +536,66 @@ struct PendingCaptureDrainTests { #expect(committed.intentionallyUnattached) } + // MARK: - `to-read` Req 3.1: the drain promotes what it captures++ /// Req 3.1 says "whether the capture is committed by the share sheet or+ /// drained from the pending-capture queue", and Q19 says why one write+ /// covers both: the drain commits through `commitCapture`, the same call the+ /// sheet uses, so the promotion is inside the commit rather than beside it.+ /// This is the drain half of that claim, driven end to end over the real+ /// spool and a taught site.+ @Test("A drained capture into a to-read work promotes it")+ func aDrainedCapturePromotesAToReadWork() async throws {+ let fixture = try DrainFixture()+ try await fixture.teachWorkIdentity()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Planned Serial", hostname: fixture.host, readingStatus: .toRead))+ _ = try await fixture.preserve(+ "https://ex.com/read?id=42&chapter=1", title: "Planned Serial",+ sharedAt: DrainFixture.shareInstant)++ let report = await fixture.drain.drain()++ #expect(report.newEntries == 1)+ let work = try await fixture.repository.work(id: planned.id)+ #expect(work.readingStatus == .reading)+ #expect(work.entries.count == 1)+ }++ /// Req 3.5 from the drain's side: a preserved share that matches an existing+ /// entry is recorded against it rather than committed as a capture, so it+ /// never reaches `applyCaptureAssignment` and never promotes. The report's+ /// counts are asserted beside the status, because a drain that had *created*+ /// an entry would promote correctly and still be the wrong outcome.+ @Test("A drained re-share of an entry in a to-read work does not promote it")+ func aDrainedReShareDoesNotPromote() async throws {+ let fixture = try DrainFixture()+ let entry = try await fixture.repository.capture(+ CaptureDraft(+ captureTitle: "Chapter 7", captureTitleSource: .host,+ rawURLString: "https://ex.com/read/1"))+ // Created on the default and set back by hand: the move itself promotes+ // (Req 3.2), so the editor's Save is what makes the work to-read.+ let work = try await fixture.repository.createWork(+ NewWorkDraft(displayTitle: "A Serial", hostname: fixture.host))+ try await fixture.repository.moveEntry(entry.id, to: .existing(work.id))+ try await fixture.repository.updateWork(+ id: work.id,+ draft: WorkMetadataDraft(+ displayTitle: "A Serial", typeAssignment: .none, genreTags: [], genericNotes: "",+ workStatus: .ongoing, readingStatus: .toRead, verdict: "", releaseDays: [],+ membership: nil, thumbnail: .keep))+ _ = try await fixture.preserve(+ "https://ex.com/read/1", sharedAt: DrainFixture.shareInstant)++ let report = await fixture.drain.drain()++ #expect(report.newEntries == 0)+ #expect(report.recordedAgainstExisting == 1)+ #expect(try await fixture.repository.work(id: work.id).readingStatus == .toRead)+ }+ // MARK: - The sheet's own commit (Reqs 1.2, 5.3, Q34) /// The sheet stamps the preserved record's id onto the Entry it creates, so@@ -1108,6 +1168,27 @@ private struct DrainFixture { return first } + /// Teaches the fixture's host a whole-title pattern and a URL rule naming+ /// the work by `id` and the chapter by `chapter`, so a drained capture+ /// resolves to a Work at all. The seed capture is what gives the teaching+ /// basis a Site and an Entry to project over.+ func teachWorkIdentity() async throws {+ _ = try await repository.capture(+ CaptureDraft(+ captureTitle: "Another Serial", captureTitleSource: .host,+ rawURLString: "https://ex.com/read?id=7&chapter=1"))+ let request = ComposedTeachingRequest(+ titleDefinition: .wholeTitle,+ urlDefinition: .workAndSequence(+ work: URLFieldSelector(locator: .query(name: ExactScalarString("id"))),+ sequence: URLFieldSelector(locator: .query(name: ExactScalarString("chapter")))))+ let contract = try await repository.projectComposedTeaching(+ hostname: host, request: request)+ guard case .committed = try await repository.commitComposedTeaching(contract) else {+ throw CocoaError(.fileWriteUnknown)+ }+ }+ func seedArticlesSite() throws { let context = ModelContext(container) let site = Site(hostname: host)
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryCaptureTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryCaptureTests.swiftindex 520c4c25..903d0d34 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryCaptureTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryCaptureTests.swift@@ -131,7 +131,13 @@ struct RepositoryCaptureTests { #expect(try await fixture.repository.debugCounts() == .seededEmpty) } - // MARK: - Req 2.6: the capture path never touches a status+ // MARK: - Req 2.6: the capture path never touches a status, except `toRead`+ //+ // `to-read` Decision 1 carves one value out of Q8's rule, and does it **by+ // name**: a committed capture promotes a work on `toRead` to `reading`, and+ // changes no other status. Every guarantee below therefore still holds for+ // the other four — the `abandoned` case is the one that pins it — and the+ // promotion has a section of its own further down. /// A capture that mints a Work hands the reader the defaults. The three /// columns are defaulted rather than `Work.create` parameters, so no@@ -182,6 +188,189 @@ struct RepositoryCaptureTests { #expect(after.readingStatus == .abandoned) #expect(after.verdict == "stopped at 12") }++ // MARK: - `to-read` Req 3.1: a capture promotes a to-read work++ /// Decision 1, the reuse arm: a chapter noted against a work the reader+ /// planned to read is direct evidence that they have started it, so the+ /// commit that attaches the entry also moves the status. The `abandoned`+ /// case above is what this is carved out of — the rule names `toRead` and+ /// only `toRead`.+ @Test("A capture that reuses a to-read Work promotes it in the same commit")+ func captureIntoAToReadWorkPromotesIt() async throws {+ let fixture = try await CaptureRepositoryFixture()+ _ = try await fixture.repository.capture(+ .fixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ let work = try #require(try await fixture.repository.works().works.first)+ try await fixture.setReadingStatus(.toRead, of: work)++ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")++ let after = try #require(try await fixture.repository.works().works.first)+ #expect(after.id == work.id)+ #expect(after.entries.count == 2)+ #expect(after.readingStatus == .reading)+ // Req 3.4: nothing else about the work moved.+ #expect(after.workStatus == .ongoing)+ #expect(after.verdict == "")+ #expect(after.releaseDays.isEmpty)+ }++ /// The other half of the arm the promotion sits in. A work made by hand has+ /// no entries and no URL identity, which is exactly what+ /// `IdentityFirstWorkMatchingPlanner` claims by exact title — so the New+ /// Work form's own product is promoted by the first chapter noted into it.+ @Test("A capture that claims a hand-made to-read Work promotes it")+ func captureClaimingAToReadWorkPromotesIt() async throws {+ let fixture = try await CaptureRepositoryFixture()+ _ = try await fixture.repository.capture(+ .fixture(title: "Another Serial", rawURL: "https://example.com/read?id=7&chapter=1"))+ try await fixture.teachWorkIdentity()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Planned Serial", hostname: "example.com", readingStatus: .toRead))++ _ = try await fixture.captureThroughRules(+ title: "Planned Serial", rawURL: "https://example.com/read?id=42&chapter=1")++ let after = try #require(+ try await fixture.repository.works().works.first { $0.id == planned.id })+ #expect(after.entries.count == 1, "the claim attached the captured entry")+ #expect(after.readingStatus == .reading)+ #expect(after.workStatus == .ongoing)+ #expect(after.verdict == "")+ }++ /// Req 3.4 stated as a difference rather than a list: the promoting capture+ /// is run beside a non-promoting one over the same library, and the only+ /// column that moves between them is `readingStatusRaw`. The clock is fixed,+ /// so even `modifiedAt` — which both captures stamp — is held still, and a+ /// write this feature added anywhere else on the path would show up here.+ @Test("A promoting capture changes no Work column a non-promoting one leaves alone")+ func promotionWritesNothingBesidesTheReadingStatus() async throws {+ let fixture = try await CaptureRepositoryFixture()+ _ = try await fixture.repository.capture(+ .fixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ let work = try #require(try await fixture.repository.works().works.first)++ // The control: a reuse capture into a work on `reading`.+ let beforeControl = try await workColumns(configuration: fixture.configuration, workID: work.id)+ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")+ let afterControl = try await workColumns(configuration: fixture.configuration, workID: work.id)+ #expect(changedColumns(beforeControl, afterControl).isEmpty)++ try await fixture.setReadingStatus(.toRead, of: work)+ let beforePromotion = try await workColumns(configuration: fixture.configuration, workID: work.id)+ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=3")+ let afterPromotion = try await workColumns(configuration: fixture.configuration, workID: work.id)+ #expect(changedColumns(beforePromotion, afterPromotion) == ["readingStatusRaw"])+ #expect(afterPromotion["readingStatusRaw"] == ReadingStatus.reading.rawValue)+ }++ /// Q13 and Req 3.3: the capture commit does not refuse a torn work group the+ /// way edit mode's Save does, so a group-wide write would put `reading` over+ /// a sibling's `abandoned` that is still waiting on the review card. The+ /// promotion therefore writes **per row**, and this is the shape that tells+ /// the two apart.+ @Test("A promotion writes only the rows on toRead, leaving a disagreeing sibling")+ func promotionLeavesADisagreeingSiblingRowAlone() async throws {+ let fixture = try await CaptureRepositoryFixture()+ _ = try await fixture.repository.capture(+ .fixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ let work = try #require(try await fixture.repository.works().works.first)+ try await fixture.setReadingStatus(.toRead, of: work)+ try await seedSplitWorkRow(+ configuration: fixture.configuration, workID: work.id, readingStatus: .abandoned)++ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")++ let statuses = try await workRowReadingStatuses(+ configuration: fixture.configuration, workID: work.id)+ #expect(statuses.sorted { $0.rawValue < $1.rawValue } == [.abandoned, .reading])+ }++ /// Req 3.1's second half: the promotion is part of the capture's one commit,+ /// so a refused save discards it with the entry. `withLockedContext` builds a+ /// context per operation and throws this one away, so there is nothing to+ /// roll back and nothing to re-fault.+ @Test("A capture whose save fails leaves the work on toRead")+ func aRefusedCaptureLeavesTheWorkOnToRead() async throws {+ let saveStrategy = ControlledSaveStrategy()+ let fixture = try await CaptureRepositoryFixture(saveStrategy: saveStrategy)+ _ = try await fixture.repository.capture(+ .fixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ let work = try #require(try await fixture.repository.works().works.first)+ try await fixture.setReadingStatus(.toRead, of: work)++ let contract = try await fixture.repository.projectCapture(+ hostname: "example.com", captureTitle: "A Serial", captureTitleSource: .safariDocument,+ rawURLString: "https://example.com/read?id=42&chapter=2", canonicalURLString: nil,+ note: "", rating: nil)+ saveStrategy.failSaves = true+ await #expect(throws: LibraryRepositoryError.self) {+ _ = try await fixture.repository.commitCapture(contract)+ }+ saveStrategy.failSaves = false++ let after = try #require(try await fixture.repository.works().works.first)+ #expect(after.readingStatus == .toRead)+ #expect(after.entries.count == 1, "the entry went with the promotion")+ }++ /// Q23: the lookup-to-commit guard re-resolves to `.new` over an unresolved+ /// duplicate set, because `duplicate-reconciliation` Req 7.1 says such a Save+ /// creates an entry rather than refusing the reader's note. That is a+ /// capture, on the same evidence as any other, so it promotes — the re-share+ /// Req 3.5 excludes is the guard resolving to `.edit`, which is covered in+ /// `RepositoryReShareTests`.+ @Test("A capture re-resolved to new over an unresolved duplicate set promotes")+ func aCaptureOverAnUnresolvedDuplicateSetPromotes() async throws {+ let fixture = try await CaptureRepositoryFixture()+ _ = try await fixture.repository.capture(+ .fixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ // Two entries on one identity key and two application UUIDs: the set the+ // lookup cannot offer for editing.+ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")+ _ = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")+ let work = try #require(try await fixture.repository.works().works.first)+ try await fixture.setReadingStatus(.toRead, of: work)++ let projected = try await fixture.repository.projectCapture(+ hostname: "example.com", captureTitle: "A Serial", captureTitleSource: .safariDocument,+ rawURLString: "https://example.com/read?id=42&chapter=2", canonicalURLString: nil,+ note: "", rating: nil)+ // The contract a lookup-first `.new` sheet carries: the keys the guard+ // re-runs under the exclusive lock.+ let guarded = CaptureContract(+ basis: projected.basis,+ request: CaptureRequest(+ captureTitle: projected.request.captureTitle,+ captureTitleSource: projected.request.captureTitleSource,+ rawURLString: projected.request.rawURLString,+ canonicalURLString: projected.request.canonicalURLString,+ note: projected.request.note, rating: projected.request.rating,+ raceGuardKeys: [projected.outcome.composedIdentityKey]),+ outcome: projected.outcome)+ guard case .committed = try await fixture.repository.commitCapture(guarded) else {+ Issue.record("expected the guard to re-resolve to a new capture and commit")+ return+ }++ let after = try #require(try await fixture.repository.works().works.first)+ #expect(after.readingStatus == .reading)+ #expect(after.entries.count == 4)+ } } private extension CaptureDraft {@@ -271,6 +460,21 @@ private struct CaptureRepositoryFixture { } return snapshot }++ /// The reader's edit-mode Save, reduced to the one field these cases move.+ /// Every other column is written back as the snapshot holds it, so the+ /// library after this call differs from the library before it in the reading+ /// status alone.+ func setReadingStatus(_ status: ReadingStatus, of work: WorkSnapshot) async throws {+ try await repository.updateWork(+ id: work.id,+ draft: WorkMetadataDraft(+ displayTitle: work.displayTitle, typeAssignment: work.typeDisplay.assignment,+ genreTags: work.genreTags, genericNotes: work.genericNotes,+ workStatus: work.workStatus, readingStatus: status, verdict: work.verdict,+ releaseDays: work.releaseDays, membership: work.membership,+ thumbnail: .keep))+ } } private final class CaptureTemporaryDirectory {@@ -314,6 +518,100 @@ private func fetchWorkModifiedAt(configuration: LibraryConfiguration, workID: UU return work.modifiedAt } +/// Every stored column of a Work row, as strings, so a test can say *which*+/// columns a write moved rather than listing the ones it hoped were untouched.+/// The relationships are left out deliberately: the entry the capture attaches+/// is the write under test, not a column the promotion is accused of moving.+private func workColumnDigest(_ work: Work) -> [String: String] {+ [+ "displayTitle": work.displayTitle,+ "lastParsedTitle": work.lastParsedTitle ?? "<nil>",+ "titleProvenanceRaw": work.titleProvenanceRaw,+ "genericNotes": work.genericNotes,+ "genreTags": work.genreTags.joined(separator: "|"),+ "workTypeID": work.workTypeID?.uuidString ?? "<nil>",+ "workStatusRaw": work.workStatusRaw,+ "readingStatusRaw": work.readingStatusRaw,+ "verdict": work.verdict,+ "releaseDaysRaw": work.releaseDaysRaw.joined(separator: "|"),+ "seriesID": work.seriesID?.uuidString ?? "<nil>",+ "seriesPosition": work.seriesPosition.map { String($0) } ?? "<nil>",+ "thumbnailShapeRaw": work.thumbnailShapeRaw ?? "<nil>",+ "thumbnailDigest": work.thumbnailDigest ?? "<nil>",+ "createdAt": String(work.createdAt.timeIntervalSince1970),+ "modifiedAt": String(work.modifiedAt.timeIntervalSince1970),+ "memberships": work.membershipValues+ .map { "\($0.hostname)/\($0.urlIdentity ?? "-")/\($0.workURLString ?? "-")" }+ .joined(separator: "|"),+ ]+}++private func changedColumns(_ before: [String: String], _ after: [String: String]) -> [String] {+ Set(before.keys).union(after.keys)+ .filter { before[$0] != after[$0] }+ .sorted()+}++private func workColumns(+ configuration: LibraryConfiguration, workID: UUID+) async throws -> [String: String] {+ let lease = try await CrossProcessLibraryLock.acquire(mode: .shared, at: configuration.lockURL, timeout: .seconds(1))+ _ = lease+ let container = try makeStoreContainer(configuration)+ let context = ModelContext(container)+ let works = try context.fetch(+ FetchDescriptor<Work>(predicate: #Predicate { $0.id == workID }))+ guard works.count == 1, let work = works.first else { throw CocoaError(.fileReadCorruptFile) }+ return workColumnDigest(work)+}++/// The reading status of every row sharing one application UUID — what a torn+/// work group looks like from outside.+private func workRowReadingStatuses(+ configuration: LibraryConfiguration, workID: UUID+) async throws -> [ReadingStatus] {+ let lease = try await CrossProcessLibraryLock.acquire(mode: .shared, at: configuration.lockURL, timeout: .seconds(1))+ _ = lease+ let container = try makeStoreContainer(configuration)+ let context = ModelContext(container)+ return try context.fetch(FetchDescriptor<Work>(predicate: #Predicate { $0.id == workID }))+ .map(\.readingStatus)+}++/// A second row for an application UUID the library already holds: the split+/// group two devices produce, which no commit path refuses and no uniqueness+/// constraint prevents.+private func seedSplitWorkRow(+ configuration: LibraryConfiguration, workID: UUID, readingStatus: ReadingStatus+) async throws {+ let lease = try await CrossProcessLibraryLock.acquire(mode: .exclusive, at: configuration.lockURL, timeout: .seconds(1))+ _ = lease+ let container = try makeStoreContainer(configuration)+ let context = ModelContext(container)+ let existing = try context.fetch(+ FetchDescriptor<Work>(predicate: #Predicate { $0.id == workID }))+ guard let original = existing.first else { throw CocoaError(.fileReadCorruptFile) }+ guard let source = original.membershipValues.first else {+ throw CocoaError(.fileReadCorruptFile)+ }+ let twin = Work.create(+ in: context, id: workID, title: original.displayTitle, hostname: source.hostname,+ site: source.site, timestamp: original.createdAt)+ twin.lastParsedTitle = original.lastParsedTitle+ twin.titleProvenanceRaw = original.titleProvenanceRaw+ twin.modifiedAt = original.modifiedAt+ twin.readingStatus = readingStatus+ // The bucket key and the identity tuple travel with the row: a twin with no+ // identity would be a *different* candidate, and the capture would mint a+ // work rather than reuse the group this case is about.+ if let membership = twin.membershipValues.first {+ membership.urlIdentity = source.urlIdentity+ membership.urlIdentityState = source.urlIdentityState+ membership.urlIdentityRuleID = source.urlIdentityRuleID+ }+ try context.save()+}+ /// The store the repository under test actually opened — the same file, read /// through the same opener, so what this reads back is what the repository wrote /// (Req 4.2).
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryReShareTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryReShareTests.swiftindex 9ee1124a..438f0596 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryReShareTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryReShareTests.swift@@ -206,6 +206,46 @@ struct RepositoryReShareTests { #expect(updated.intentionallyUnattached == original.intentionallyUnattached) } + /// `to-read` [3.5](../../../../specs/to-read/requirements.md#3.5): re-sharing+ /// a page that already has an entry is not a capture, so it promotes+ /// nothing. Structurally it cannot: `commitReShareUpdate` is a different+ /// commit from `commitCapture`, it never assigns `entry.work`, and it never+ /// reaches `applyCaptureAssignment` where the promotion lives. This pins the+ /// behaviour anyway, because the alternative — "the reader shared the page,+ /// so they must be reading it" — is a plausible thing for a later change to+ /// decide.+ @Test("A live re-share of an entry in a to-read Work does not promote it")+ func aReShareDoesNotPromoteAToReadWork() async throws {+ let fixture = try await ReShareFixture()+ let entry = try await fixture.repository.capture(+ .reShare(rawURL: "https://example.com/chapter-1", note: "first pass"))+ // Created on the default and moved back to `toRead` afterwards: the move+ // itself promotes (Req 3.2), so the editor's Save is what puts the work+ // in the state this case is about.+ let work = try await fixture.repository.createWork(+ NewWorkDraft(displayTitle: "A Serial", hostname: "example.com"))+ try await fixture.repository.moveEntry(entry.id, to: .existing(work.id))+ try await fixture.repository.updateWork(+ id: work.id,+ draft: WorkMetadataDraft(+ displayTitle: "A Serial", typeAssignment: .none, genreTags: [], genericNotes: "",+ workStatus: .ongoing, readingStatus: .toRead, verdict: "", releaseDays: [],+ membership: nil, thumbnail: .keep))++ let lookupResult = try await fixture.repository.captureLookup(+ rawURL: "https://example.com/chapter-1")+ guard case .edit(let basis) = lookupResult else {+ Issue.record("Expected edit, got \(lookupResult)")+ return+ }+ try await fixture.repository.commitReShareUpdate(+ basis: basis, note: "read it again", rating: .up)++ let after = try await fixture.repository.work(id: work.id)+ #expect(after.readingStatus == .toRead)+ #expect(try await fixture.repository.entry(id: entry.id).note == "read it again")+ }+ // MARK: - Timestamp semantics @Test("Update replaces note and rating, sets lastSharedAt and modifiedAt to update time, preserves firstCapturedAt")
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryTeachingTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryTeachingTests.swiftindex 193cbb87..9d266961 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryTeachingTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryTeachingTests.swift@@ -625,6 +625,53 @@ struct RepositoryReparseTests { #expect(entry.chapterTitle == nil) } + /// `to-read`'s Non-Goal "no promotion by reparse", pinned at the one place+ /// it could go wrong. `commitReparse`'s `worksToReuse` loop re-points an+ /// Entry onto a Work that already exists and rewrites that Work's title+ /// columns — it is the structural twin of the capture path's `.reuse` arm,+ /// which *does* promote (Decision 1). The difference is deliberate: a+ /// re-parse is the app re-deriving fields from evidence the library already+ /// held, not the reader saying they have started reading, so it must add no+ /// `promoteFromToRead()` call.+ ///+ /// The entry is asserted to have landed on the work first, because a+ /// re-parse that reused nothing would leave the status alone for the wrong+ /// reason and this case would pass saying nothing.+ @Test("A re-parse that re-points an entry onto a to-read Work does not promote it")+ func reparseOntoAToReadWorkDoesNotPromoteIt() async throws {+ let fixture = try await TeachingFixture()+ let entry = try await fixture.capture(+ title: "Ch1 - Fiction | Site", rawURL: "https://example.com/1")+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "My Fiction", hostname: "example.com", readingStatus: .toRead))+ // The exact `lastParsedTitle` match is what puts the work in the plan's+ // `worksToReuse` rather than minting a second one.+ try await fixture.seedLastParsedTitle(workID: planned.id, title: "Fiction")++ let definition = PatternDefinition.segment(+ work: try SegmentRangeSpec(origin: .end, offset: 1, length: 1),+ ignored: [try SegmentPositionSpec(origin: .end, offset: 0)]+ )+ let tc = try await fixture.repository.projectInitialTeaching(+ hostname: "example.com", patternDefinition: definition)+ _ = try await fixture.repository.commitTeaching(tc)++ // Detach, so the commit below is the write that re-points the entry.+ try await fixture.clearPatternFields(entryID: entry.id)+ #expect(try await fixture.repository.entry(id: entry.id).workID == nil)++ let contract = try await fixture.repository.projectReparse(entryID: entry.id)+ let result = try await fixture.repository.commitReparse(contract)+ guard case .committed = result else { Issue.record("Expected committed"); return }++ #expect(+ try await fixture.repository.entry(id: entry.id).workID == planned.id,+ "the re-parse reused the work — so the status below is a real reuse's")+ #expect(try await fixture.repository.debugCounts().works == 1, "and minted none")+ #expect(try await fixture.repository.work(id: planned.id).readingStatus == .toRead)+ }+ @Test("Re-parse leaves manual fields unchanged") func reparseManualProtection() async throws { let fixture = try await TeachingFixture()
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryWorksTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryWorksTests.swiftindex f95ff2b7..f67f4cad 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryWorksTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/RepositoryWorksTests.swift@@ -32,6 +32,36 @@ struct RepositoryWorksTests { #expect(try await fixture.repository.debugCounts().sites == 1) } + /// `to-read` [2.1](../../../../../specs/to-read/requirements.md#2.1) and+ /// [2.2](../../../../../specs/to-read/requirements.md#2.2). The draft's+ /// reading status is defaulted (Q18) and that default is the point: only the+ /// New Work form names `.toRead`, and the sixty-odd fixture, seed and test+ /// callers that model a captured work keep `reading` without being edited+ /// (Q15). The other two status columns are untouched by the feature, so they+ /// are asserted beside it: a new work is `ongoing` with an empty verdict+ /// whichever reading status it is born with.+ @Test("A New Work draft carries its reading status, and the default is reading")+ func creationCarriesTheDraftReadingStatus() async throws {+ let fixture = try await WorksRepositoryFixture()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(displayTitle: "Planned", hostname: "example.com", readingStatus: .toRead))+ #expect(planned.readingStatus == .toRead)+ #expect(planned.workStatus == .ongoing)+ #expect(planned.verdict.isEmpty)++ let defaulted = try await fixture.repository.createWork(+ NewWorkDraft(displayTitle: "Unstated", hostname: "example.com"))+ #expect(defaulted.readingStatus == .reading)+ #expect(defaulted.workStatus == .ongoing)+ #expect(defaulted.verdict.isEmpty)++ // The status is on the row, not only in the returned snapshot.+ let works = try await fixture.repository.works().works+ let byTitle = Dictionary(uniqueKeysWithValues: works.map { ($0.displayTitle, $0) })+ #expect(byTitle["Planned"]?.readingStatus == .toRead)+ #expect(byTitle["Unstated"]?.readingStatus == .reading)+ }+ @Test("Work creation validates title and bare hostname grammar") func standaloneValidation() async throws { let fixture = try await WorksRepositoryFixture()@@ -178,6 +208,163 @@ struct RepositoryWorksTests { #expect(moved.verdict == "") } + // MARK: - `to-read` Req 3.2: Move To promotes a to-read work++ /// Decision 1's second arm: moving a noted chapter into a work is the same+ /// evidence as capturing one into it, so the destination's `toRead` becomes+ /// `reading` in the move's own commit. The clock is fixed, so the assertions+ /// below on the other columns include `modifiedAt` implicitly — nothing the+ /// move already stamped is claimed as untouched.+ @Test("Move To an existing to-read Work promotes it in the same commit")+ func moveToAToReadWorkPromotesIt() async throws {+ let fixture = try await WorksRepositoryFixture()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Planned", hostname: "example.com", readingStatus: .toRead))+ let entry = try await fixture.repository.capture(.worksFixture())++ try await fixture.repository.moveEntry(entry.id, to: .existing(planned.id))++ let after = try #require(+ try await fixture.repository.works().works.first { $0.id == planned.id })+ #expect(after.readingStatus == .reading)+ #expect(after.entries.map(\.id) == [entry.id])+ // Req 3.4: the promotion adds nothing to what the move already writes.+ #expect(after.displayTitle == "Planned")+ #expect(after.workStatus == .ongoing)+ #expect(after.verdict == "")+ #expect(after.releaseDays.isEmpty)+ }++ /// [Req 3.3](../../../../specs/to-read/requirements.md#3.3)'s second clause+ /// at the Move To site: the carve-out is `toRead` **by name**, so the other+ /// four statuses keep what they hold. `abandoned` is the one that pins it —+ /// a work the reader put down is the case where a silent `reading` would be+ /// a lie the reader has to undo, and `promoteFromToRead`'s guard is the only+ /// thing standing between the move and that write.+ @Test("Move To an abandoned Work leaves its reading status as it was")+ func moveToAnAbandonedWorkDoesNotPromoteIt() async throws {+ let fixture = try await WorksRepositoryFixture()+ let shelved = try await fixture.repository.createWork(+ NewWorkDraft(displayTitle: "Shelved", hostname: "example.com"))+ try await fixture.setReadingStatus(.abandoned, of: shelved)+ let entry = try await fixture.repository.capture(.worksFixture())++ try await fixture.repository.moveEntry(entry.id, to: .existing(shelved.id))++ let after = try #require(+ try await fixture.repository.works().works.first { $0.id == shelved.id })+ #expect(+ after.entries.map(\.id) == [entry.id],+ "the move landed, so the status below is the one a real move left")+ #expect(after.readingStatus == .abandoned)+ }++ /// Q13 at the **second** call site. The capture commit has this case+ /// (`RepositoryCaptureTests.promotionLeavesADisagreeingSiblingRowAlone`);+ /// Move To is the other path that promotes, and it does not refuse a torn+ /// work group either, so a group-wide write here would put `reading` over+ /// the sibling's `abandoned` just the same. The move addresses the whole+ /// group and the promotion is per row, which is what the two remaining+ /// statuses read back.+ @Test("A Move To promotion writes only the rows on toRead, leaving a disagreeing sibling")+ func moveToPromotionLeavesADisagreeingSiblingRowAlone() async throws {+ let fixture = try await WorksRepositoryFixture()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Planned", hostname: "example.com", readingStatus: .toRead))+ // After the status is set, because edit mode's Save is the one commit+ // that *does* refuse a torn group.+ try await seedSplitWorkRow(+ configuration: fixture.configuration, workID: planned.id, readingStatus: .abandoned)+ let entry = try await fixture.repository.capture(.worksFixture())++ try await fixture.repository.moveEntry(entry.id, to: .existing(planned.id))++ let statuses = try await workRowReadingStatuses(+ configuration: fixture.configuration, workID: planned.id)+ #expect(statuses.sorted { $0.rawValue < $1.rawValue } == [.abandoned, .reading])+ }++ /// Q20: the promotion is gated on the entry group not already pointing at+ /// the destination, which is **narrower** than `moveEntry`'s own no-op+ /// return. That return needs manual provenance on every row, so re-moving an+ /// entry a rule attached is a real write that reaches the stamping loop — and+ /// it is not the reader starting to read, because the chapter was already in+ /// the work.+ @Test("Re-moving an entry already in the work under derived provenance does not promote")+ func reMovingAnEntryAlreadyInTheWorkDoesNotPromote() async throws {+ let fixture = try await WorksRepositoryFixture()+ _ = try await fixture.repository.capture(+ .worksFixture(title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=1"))+ try await fixture.teachWorkIdentity()+ let entry = try await fixture.captureThroughRules(+ title: "A Serial", rawURL: "https://example.com/read?id=42&chapter=2")+ let work = try #require(try await fixture.repository.works().works.first)+ #expect(work.entries.contains { $0.id == entry.id })+ #expect(+ work.entries.first { $0.id == entry.id }?.workAssignmentProvenance.kind != .manual,+ "the rule attached it, so the no-op return below does not fire")+ try await fixture.setReadingStatus(.toRead, of: work)++ try await fixture.repository.moveEntry(entry.id, to: .existing(work.id))++ let after = try #require(try await fixture.repository.works().works.first)+ #expect(after.readingStatus == .toRead)+ #expect(+ after.entries.first { $0.id == entry.id }?.workAssignmentProvenance.kind == .manual,+ "the move was a real write — it set the manual provenance")+ }++ /// Req 3.7, as the code actually spells it. The requirement is that a+ /// promotion reaches an open editor **exactly as any other change to an+ /// edited field made elsewhere does** — and that treatment, for a work that+ /// is still in the store and not torn, is last-writer-wins:+ /// `WorkEditBasis.matches` is consulted only by the post-collapse redirect+ /// (`LibraryRepository+Redirect.swift:205`), never by a write addressed to a+ /// row that is still there. So the Save commits and writes the reader's+ /// draft back, which Req 1.4 permits — `toRead` on a work that has entries+ /// is a state the reader may hold deliberately.+ ///+ /// What the promotion does owe is *visibility*: it moves a field the basis+ /// carries, so the conflict machinery sees it wherever that machinery runs+ /// at all. That is the first half of this case. A `readingStatus` the basis+ /// did not carry would be invisible to the redirect too.+ @Test("A promotion moves a field the edit basis carries, and a stale Save still commits")+ func aPromotionIsVisibleToAnOpenEditor() async throws {+ let fixture = try await WorksRepositoryFixture()+ let planned = try await fixture.repository.createWork(+ NewWorkDraft(+ displayTitle: "Planned", hostname: "example.com", readingStatus: .toRead))+ // The reader opens edit mode while the work is still to read.+ let basis = WorkEditBasis(work: planned)+ #expect(basis.readingStatus == .toRead)++ let entry = try await fixture.repository.capture(.worksFixture())+ try await fixture.repository.moveEntry(entry.id, to: .existing(planned.id))+ let promoted = try #require(+ try await fixture.repository.works().works.first { $0.id == planned.id })+ #expect(+ WorkEditBasis(work: promoted).readingStatus == .reading,+ "the promotion is in the basis, so it is visible to the conflict path")++ let outcome = try await fixture.repository.updateWork(+ id: planned.id, basis: basis,+ draft: WorkMetadataDraft(+ displayTitle: "Planned", typeAssignment: .none, genreTags: [],+ genericNotes: "a note the reader typed", workStatus: .ongoing,+ readingStatus: .toRead, verdict: "", releaseDays: [], membership: nil,+ thumbnail: .keep))++ #expect(outcome == .committed)+ let after = try #require(+ try await fixture.repository.works().works.first { $0.id == planned.id })+ #expect(+ after.readingStatus == .toRead,+ "last-writer-wins, and Req 1.4 lets the reader hold toRead on a work with entries")+ #expect(after.genericNotes == "a note the reader typed")+ }+ /// Req 7.1: a draft that moves nothing but a status is a real edit — it has /// to write and stamp, or the reader's only change would be dropped as a /// no-op.@@ -265,6 +452,7 @@ private final class WorksControlledSaveStrategy: RepositorySaveStrategy, @unchec private struct WorksRepositoryFixture { let directory: WorksTemporaryDirectory+ let configuration: LibraryConfiguration let repository: LibraryRepository init(@@ -272,12 +460,55 @@ private struct WorksRepositoryFixture { saveStrategy: any RepositorySaveStrategy = ModelContextSaveStrategy() ) async throws { directory = try WorksTemporaryDirectory()+ configuration = LibraryConfiguration(rootDirectory: directory.url) repository = try await LibraryRepository.openForApp(- LibraryConfiguration(rootDirectory: directory.url),+ configuration, clock: clock, saveStrategy: saveStrategy ).repository }++ /// Teaches `example.com` a whole-title pattern and a URL rule naming the+ /// work by `id` and the chapter by `chapter` — the same fixture+ /// `RepositoryCaptureTests` uses, because a rule-attached entry is the only+ /// way to reach a derived work assignment.+ func teachWorkIdentity() async throws {+ let request = ComposedTeachingRequest(+ titleDefinition: .wholeTitle,+ urlDefinition: .workAndSequence(+ work: URLFieldSelector(locator: .query(name: ExactScalarString("id"))),+ sequence: URLFieldSelector(locator: .query(name: ExactScalarString("chapter")))))+ let contract = try await repository.projectComposedTeaching(+ hostname: "example.com", request: request)+ guard case .committed = try await repository.commitComposedTeaching(contract) else {+ throw CocoaError(.fileWriteUnknown)+ }+ }++ /// The taught capture path, which is the one that resolves a Work.+ @discardableResult+ func captureThroughRules(title: String, rawURL: String) async throws -> EntrySnapshot {+ let contract = try await repository.projectCapture(+ hostname: "example.com", captureTitle: title, captureTitleSource: .safariDocument,+ rawURLString: rawURL, canonicalURLString: nil, note: "", rating: nil)+ guard case .committed(let snapshot) = try await repository.commitCapture(contract) else {+ throw CocoaError(.fileWriteUnknown)+ }+ return snapshot+ }++ /// The reader's edit-mode Save, reduced to the reading status: every other+ /// column goes back as the snapshot holds it.+ func setReadingStatus(_ status: ReadingStatus, of work: WorkSnapshot) async throws {+ try await repository.updateWork(+ id: work.id,+ draft: WorkMetadataDraft(+ displayTitle: work.displayTitle, typeAssignment: work.typeDisplay.assignment,+ genreTags: work.genreTags, genericNotes: work.genericNotes,+ workStatus: work.workStatus, readingStatus: status, verdict: work.verdict,+ releaseDays: work.releaseDays, membership: work.membership,+ thumbnail: .keep))+ } } private final class WorksTemporaryDirectory {@@ -288,3 +519,51 @@ private final class WorksTemporaryDirectory { } deinit { try? FileManager.default.removeItem(at: url) } }++/// A second row for an application UUID the library already holds: the split+/// group two devices produce, which no commit path refuses and no uniqueness+/// constraint prevents. Unlike the capture suite's twin this one carries no URL+/// identity, because Move To addresses its destination by UUID rather than by+/// matching a bucket key — all the destination guard asks of the group is that+/// some row holds a membership on the Entry's hostname.+private func seedSplitWorkRow(+ configuration: LibraryConfiguration, workID: UUID, readingStatus: ReadingStatus+) async throws {+ let lease = try await CrossProcessLibraryLock.acquire(mode: .exclusive, at: configuration.lockURL, timeout: .seconds(1))+ _ = lease+ let container = try makeWorksStoreContainer(configuration)+ let context = ModelContext(container)+ let existing = try context.fetch(+ FetchDescriptor<Work>(predicate: #Predicate { $0.id == workID }))+ guard let original = existing.first, let source = original.membershipValues.first else {+ throw CocoaError(.fileReadCorruptFile)+ }+ let twin = Work.create(+ in: context, id: workID, title: original.displayTitle, hostname: source.hostname,+ site: source.site, timestamp: original.createdAt)+ twin.lastParsedTitle = original.lastParsedTitle+ twin.titleProvenanceRaw = original.titleProvenanceRaw+ twin.modifiedAt = original.modifiedAt+ twin.readingStatus = readingStatus+ try context.save()+}++/// The reading status of every row sharing one application UUID — what a torn+/// work group looks like from outside.+private func workRowReadingStatuses(+ configuration: LibraryConfiguration, workID: UUID+) async throws -> [ReadingStatus] {+ let lease = try await CrossProcessLibraryLock.acquire(mode: .shared, at: configuration.lockURL, timeout: .seconds(1))+ _ = lease+ let container = try makeWorksStoreContainer(configuration)+ let context = ModelContext(container)+ return try context.fetch(FetchDescriptor<Work>(predicate: #Predicate { $0.id == workID }))+ .map(\.readingStatus)+}++/// The store the repository under test actually opened — the same file, read+/// through the same opener, so what this reads back is what the repository+/// wrote.+private func makeWorksStoreContainer(_ configuration: LibraryConfiguration) throws -> ModelContainer {+ try LibraryRepository.openContainer(at: configuration.storeURL)+}
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/TodayDayPlanTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/TodayDayPlanTests.swiftindex a61267eb..3cc754ec 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/TodayDayPlanTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/TodayDayPlanTests.swift@@ -499,6 +499,66 @@ struct TodayDayPlanTests { #expect(plan.catchingUp.map(\.title) == ["Behind"]) } + // MARK: - To read (`to-read` Req 4.1, 4.2)++ /// Q7, in one case and with no new code: Today is what the reader is+ /// reading now, and a work they have not started fails the scheduled+ /// filter by status exactly as a catch-up work does — on its **own**+ /// release weekday, the day where a missing filter would be invisible. It+ /// is in no releases section, lights no strip dot, and is not in the+ /// `Catching up` section either, which is for a reader who is behind+ /// rather than one who has not begun.+ ///+ /// Its release days are untouched on the row, so the work is scheduled the+ /// moment its status becomes `reading` — by the reader's own edit, or by a+ /// capture promoting it (Decision 1).+ @Test("A to-read work with days on the selected weekday reaches no Today section")+ func toReadWorkIsNeverScheduled() {+ let calendar = Self.calendar()+ let work = Self.work(+ id: Self.id(1), title: "Planned", releaseDays: [.thursday],+ readingStatus: .toRead)+ let schedule = TodaySchedule.build(works: [work], calendar: calendar)++ #expect(schedule.works.isEmpty)+ #expect(schedule.dueWeekdays.isEmpty)+ #expect(schedule.catchingUp.isEmpty)+ // The days themselves are kept, and are the same set the row was given.+ #expect(work.releaseDays == [.thursday])++ let plan = TodayDayPlan.build(+ day: Self.thursday, currentDay: Self.thursday, schedule: schedule,+ presentation: Self.presentation([], calendar: calendar), calendar: calendar)++ #expect(plan.releases.isEmpty)+ #expect(plan.catchingUp.isEmpty)+ }++ /// Req 4.2 and Q14: the noted section is the day's record rather than a+ /// plan, so an entry of a to-read work stays on the day it was noted — a+ /// work set back to `toRead` by hand still had those chapters noted.+ @Test("An entry of a to-read work stays in its day's noted section")+ func toReadEntryStaysInTheNotedSection() throws {+ let calendar = Self.calendar()+ let noted = Self.presentationRow(sharedAt: Self.instant(2026, 3, 12))+ let plan = TodayDayPlan.build(+ day: Self.thursday, currentDay: Self.thursday,+ schedule: TodaySchedule.build(+ works: [+ Self.work(+ id: Self.id(1), title: "Planned", releaseDays: [.thursday],+ readingStatus: .toRead,+ entries: [Self.entry(id: noted.id, sharedAt: Self.instant(2026, 3, 12))])+ ],+ calendar: calendar),+ presentation: Self.presentation(+ [(Self.day(2026, 3, 12), [noted])], calendar: calendar),+ calendar: calendar)++ #expect(plan.releases.isEmpty)+ #expect(try #require(plan.noted).rows.map(\.id) == [noted.id])+ }+ /// MUST 5's second half: the days are kept on the row while the status /// holds, so the moment it returns to `reading` the same work is scheduled /// again — a release row on its own weekday and a dot on the strip — and
diff --git a/Packages/AsterismCore/Tests/AsterismCoreTests/WorkMergeRepositoryTests.swift b/Packages/AsterismCore/Tests/AsterismCoreTests/WorkMergeRepositoryTests.swiftindex 7e671f3d..8e09876e 100644--- a/Packages/AsterismCore/Tests/AsterismCoreTests/WorkMergeRepositoryTests.swift+++ b/Packages/AsterismCore/Tests/AsterismCoreTests/WorkMergeRepositoryTests.swift@@ -93,6 +93,66 @@ struct WorkMergeRepositoryTests { #expect(target.genericNotes.contains("Verdict: gave up in book two")) } + /// `to-read` Req 5.3, the half that needs no code: the merged work keeps the+ /// **target's** reading status, and a source that differs and has been+ /// moved off the default is reported as discarded — `toRead` is such a+ /// value, so it reaches the preview like `catchingUp` or `abandoned` does.+ @Test("Merge keeps the target's status and lists a differing source toRead as discarded")+ func mergeDiscardsADifferingSourceToRead() async throws {+ let fixture = try await MergeFixture()+ let (sourceID, targetID) = try await fixture.makeSourceAndTarget()+ try await fixture.repository.updateWork(+ id: sourceID,+ draft: WorkMetadataDraft(+ displayTitle: "Source Work", typeAssignment: .none, genreTags: [],+ genericNotes: "",+ workStatus: .ongoing, readingStatus: .toRead, verdict: "", releaseDays: [],+ membership: nil, thumbnail: .keep))++ let contract = try await fixture.repository.projectMerge(+ sourceWorkID: sourceID, targetWorkID: targetID)++ #expect(contract.outcome.readingStatus == .reading)+ #expect(contract.outcome.discardedFields.contains(.sourceReadingStatus))++ guard case .committed = try await fixture.repository.commitMerge(contract) else {+ Issue.record("Expected .committed")+ return+ }+ #expect(try await fixture.repository.work(id: targetID).readingStatus == .reading)+ }++ /// `to-read` Req 5.3's other half, and one of Decision 1's non-callers: a+ /// merge moves the source's entries onto the target, but it is a+ /// restructuring rather than the reader noting a chapter, so a to-read+ /// target that gains entries this way keeps `toRead`. It is the route+ /// Decision 1 names for a work made by hand under a title the site's rules+ /// do not parse — the reader merges the two by hand, and the status is+ /// theirs to set afterwards.+ @Test("Merging a work with entries into a to-read target does not promote it")+ func mergeIntoAToReadTargetDoesNotPromoteIt() async throws {+ let fixture = try await MergeFixture()+ let (sourceID, targetID) = try await fixture.makeSourceAndTarget()+ try await fixture.repository.updateWork(+ id: targetID,+ draft: WorkMetadataDraft(+ displayTitle: "Target Work", typeAssignment: .none, genreTags: [],+ genericNotes: "",+ workStatus: .ongoing, readingStatus: .toRead, verdict: "", releaseDays: [],+ membership: nil, thumbnail: .keep))++ let contract = try await fixture.repository.projectMerge(+ sourceWorkID: sourceID, targetWorkID: targetID)+ guard case .committed = try await fixture.repository.commitMerge(contract) else {+ Issue.record("Expected .committed")+ return+ }++ let merged = try await fixture.repository.work(id: targetID)+ #expect(merged.entries.count == 2, "the source's entry did move across")+ #expect(merged.readingStatus == .toRead)+ }+ // MARK: - V14: the cover through the commit (`work-thumbnails` Req 1.5) // // The bytes here are not JPEGs and need not be: `commitMerge` copies a blob
diff --git a/docs/agent-notes/testing.md b/docs/agent-notes/testing.mdindex 4115d5f5..d767cb47 100644--- a/docs/agent-notes/testing.md+++ b/docs/agent-notes/testing.md@@ -1405,6 +1405,60 @@ swipes one way. Pass `scroll: { $0.swipeDown() }` when the target is behind you `series-and-related-works` put three rows between the type picker and the status capsules, which is all it took to break that walk at `accessibility5`. +**And none of that menu's picker rows carries its accessibility identifier.**+Measured on 2026-09-21 by dumping every button of the open popover: the+identifiers the production view sets on the `Text` inside each inline `Picker`+— `works-sort-newest`, `works-filter-site-alpha.test`,+`works-filter-release-days-any`, all of them — resolve to nothing, and the only+one that survives into the menu is `works-list-group-by-series`, a `Toggle`.+Every choice `chooseWorksOption` makes is therefore made by **label**, and two+labels are shared: each of the eight filter pickers draws an `Any` (the Sort picker has none), and both status+vocabularies have a `Finished` (`work-and-reading-status` Q23). The rows are+drawn lazily, so how many same-labelled rows sit in the tree at once depends on+where the menu is scrolled — which is why `app.buttons["Finished"]`, a+subscript that *raises* on an ambiguous query, went on working for as long as+it did. `to-read`'s fifth reading status moved every offset below Work status+by 42 pt and three cases across two suites died with `Multiple matching+elements found`, reported as "The menu offers Any" / "The menu offers+Finished". A caller whose label is shared now passes+`nextTo: .above("Has release days")` (or `.below("Ongoing")`) and gets the+occurrence nearest that uniquely labelled row of the same picker. If a future+dimension adds another `Any`-adjacent row, that is the knob; do not resolve an+ambiguous label with `firstMatch`, which taps a different dimension's row and+passes.++## Known flaky family: `CharacterExtractionUITests`' "The place can be kept"++Observed 2026-09-21/22 on the `to-read` branch, which touches neither that+suite nor `seeded-characters`. A full `make test` failed+`testAKeptPlaceIsNamedOnTheEntryItCites` and+`testKeepingAPlaceWritesItIntoThePlacesSection`; the suite re-run **alone**+passed both and failed a *third* case,+`testThePlacesCardOpensThePlaceEditorFromItsLineAndItsFooter`, on the same+message. All three die in `tapReviewControl`, which swipes the review list up+to six times looking for a hittable control — the same "a different one of+them fails per run" signature as the double-submission family above, and the+same remedy: rerun before treating one as a regression. The first full run of+the same branch had all fifteen cases green.++## A Today strip assertion must not read `isSelected` on the current day++`TodayUITests` selects yesterday and then asserts the current day is no longer+selected. On the calendar's **first weekday** — one run in seven, and 2026-09-21+under a region whose week starts on Monday — yesterday falls in the previous+displayed week, `selectDay` pages the strip back, and the current day's cell+leaves the accessibility tree entirely. `!currentCell.isSelected` then raises+`Failed to get matching snapshot: No matches found … "today-strip-2026-09-21"`,+which reads like the strip being broken rather than like the day simply not+being drawn. `testTheTabIsTodayAndTheScreenCarriesNoDayTitle` and+`testAReleaseRowOpensItsWorkOnTodayAndBackReturnsToTheSelectedDay` both failed+that way, deterministically, in isolation, on a branch that touches neither the+Today screen nor its fixture. Write the claim as+`!(currentCell.exists && currentCell.isSelected)`: a cell that is not on the+strip is not the selected one. The fixture's own doc comment+(`AppLibraryModel.seedTodayFixture`) already warned that the previous day can+fall in the previous displayed week.+ ## The work editor's per-record controls are behind a sheet, not on the page `work-creators` Decision 7 reshaped work detail's edit mode into captioned cards
diff --git a/specs/OVERVIEW.md b/specs/OVERVIEW.mdindex e5f49a45..a63afae9 100644--- a/specs/OVERVIEW.md+++ b/specs/OVERVIEW.md@@ -49,6 +49,7 @@ | [Empty Library](#empty-library) | 2026-09-17 | Done | Full spec (T-2118). A `Development`-only Settings row that exports a backup, waits for the share to complete, then deletes every row, Site rows included, through the mirrored per-row path so every device on the account ends up empty and the archive is the way back. Compiled out of `Personal`, the pass included. | | [Share Sheet Character Chips](#share-sheet-character-chips) | 2026-09-18 | In Progress | Smolspec (T-2317). The share sheets' cast text row becomes name-only chips; tapping one opens an inline card with that character's aliases and note, never facts. A cast past two chip rows collapses behind a `+N more` chip (Decision 1). Read-only, no schema change; `FlowLayout` moves into ConstellationKit. Supersedes `share-sheet-characters` Q2 (notes) and Q6 (no pills). | | [Today Announcements](#today-announcements) | 2026-09-19 | Done — `make test-core` (3,002 checks, zero known issues), `make test-quick` and `make build-mac` green; the six failures across `make test`, `make test-ui` and `make test-ui-ipad` are measured to reproduce at `main`'s tip (`verification-run.md` §2) | Smolspec. A release note and a getting-started guide surface on Today as one row that looks like an entry row and opens a sheet showing a bundled Markdown document, rendered natively with images; both stay reachable from a new About section in Settings. The release-note row shows when the marketing version differs from a per-device last-seen version kept in `UserDefaults` and hides when its sheet closes; getting started replaces the settled empty-library message and goes with the first entry. No schema change; the marketing version becomes 0.7.0. |+| [To Read](#to-read) | 2026-09-21 | Done | Full spec (T-2354). A fifth reading status, `toRead`, which the New Work form gives every work it creates and the reader can set in edit mode. A capture or a Move To into a to-read work makes it `reading` in the same commit; nothing else promotes. To-read works stay off Today's plan. No schema, marker or archive generation change. The share-sheet path is deferred to T-2363. | --- @@ -819,3 +820,17 @@ Smolspec. Two announcements, a release note and a getting-started guide, each dr - [decision_log.md](today-announcements/decision_log.md) - [verification-run.md](today-announcements/verification-run.md) - [implementation.md](today-announcements/implementation.md)++---++## To Read++**Created:** 2026-09-21 · **Status:** Done — all thirteen tasks implemented 2026-09-22. Q1–Q29 and Decision 1 in the log. The Mac half of Req 1.6 is an owner hand check (`prerequisites.md`).++Full spec (T-2354). Adds `toRead` as a fifth `ReadingStatus` value, ordered first, with the `bookmark` glyph. The New Work form creates works with it and offers no status control; every other creation path keeps `reading`. A committed capture into a to-read work, drained pending captures included, and a Move To of an entry not already in it set `reading` on the rows that are on `toRead`, in the same commit (Decision 1, which carves `toRead` out of `work-and-reading-status` Q8). Teaching, reparse, merge, collapse and import do not promote. A to-read work is in no releases or catch-up section on Today and adds no strip dot; its noted entries stay on their day. In the duplicate phase it is authored content like any non-default status, and its carrier writes only over `reading`. No schema, readiness marker or archive generation change. Adding a to-read work from the share sheet was investigated and deferred to T-2363.++- [requirements.md](to-read/requirements.md)+- [design.md](to-read/design.md)+- [tasks.md](to-read/tasks.md)+- [decision_log.md](to-read/decision_log.md)+- [prerequisites.md](to-read/prerequisites.md)
diff --git a/specs/to-read/decision_log.md b/specs/to-read/decision_log.mdnew file mode 100644index 00000000..c296aef2--- /dev/null+++ b/specs/to-read/decision_log.md@@ -0,0 +1,89 @@+# Decision Log: To Read++## Quick Decisions++| ID | Date | Decision | Rationale |+|----|------|----------|-----------|+| Q1 | 2026-09-21 | Full spec, not a smolspec (T-2354) | The share-sheet path reverses two recorded decisions (`work-and-reading-status` Q8, the two-arm `CaptureLookupDisposition`) and the request left the subject, the shape and the entry points open |+| Q2 | 2026-09-21 | The spec is named `to-read` | Names the state the feature adds, as `catch-up-mode` does; holds whichever entry points make the first cut |+| Q3 | 2026-09-21 | The thing marked to read is a `Work`, not the `Series` entity | Owner's pick. The ticket's "series" is a serial the reader has not started. A `Series` row usually has no member works yet, a series-level status was declined in `series-and-related-works` Non-Goals, and it would need a new column |+| Q4 | 2026-09-21 | To read is a fifth `ReadingStatus` value, `toRead`, not a separate flag | Owner's pick. A raw-string enum case needs no schema or archive bump (`catch-up-mode` Q2, Q6). A work is to read or reading, never both. Accepted cost: the status control gains a fifth segment and its stacked fallback (`catch-up-mode` Q14) becomes the usual layout on a phone |+| Q5 | 2026-09-21 | The New Work form creates a work as `toRead`, with no status control on the form | Owner's pick. A work made by hand has no entries, so it has not been started. Every other creation path keeps `reading`: Move To a new work and a capture both arrive with an entry, and import carries the archive's value |+| Q6 | 2026-09-21 | The share-sheet path is out of this spec and tracked as T-2363 | Owner's pick after the investigation. A work made from a landing page has no URL identity and no parsed title on most sites, so the first captured chapter mints a second work and two devices mint two works no scan links; the pending-capture record carries raw evidence only and the drain commits every record as an entry; a third lookup arm, a new contract and a new validation gate are needed. T-2363 records the prerequisite: test the taught sites' URL rules against their landing URLs |+| Q7 | 2026-09-21 | A to-read work is not on Today: no section, no release row, no strip dot; release days are kept | Owner's pick. Today is what the reader is reading now. The existing line under the release-day toggles is already true for a to-read work, so no new wording |+| Q8 | 2026-09-21 | `toRead` is ordered first in the enum, before `reading` | Case order is display order only (`work-and-reading-status` Req 6.1). The order then reads as a work's life: to read, reading, catching up, finished, abandoned |+| Q9 | 2026-09-21 | A pre-feature build reads `toRead` as `reading`, may write `reading` back on its next Save of the work, and refuses to export a library holding the value; accepted, and no archive generation bump | The standing rule for an added enum value (`catch-up-mode` Q6, Q7): tolerant read, strict wire, last-writer-wins for a single-reader library. The owner updates every device |+| Q10 | 2026-09-21 | In the duplicate phase `toRead` follows the standing rule for a non-default status: a `toRead` row and a bare `reading` row resolve silently to `toRead`, and a `toRead` carrier writes only over `reading` | The precedent of `catch-up-mode` Q10. The silent case is narrow: a work made by the New Work form is never bare, because its manual title is authored content, so a disagreeing pair of such rows goes to the review card; only a capture-minted `reading` row with nothing else authored folds. The fold can leave `toRead` on a group that holds entries, a state the reader can also set by hand (Req 1.4), so it is valid rather than damage |+| Q11 | 2026-09-21 | Rejected for a `{toRead, reading}` group: `reading` wins, a review card for that pair alone, and a rule that prefers `reading` when the group has entries | Raised at the requirements review. Making `toRead` unauthored does not make `reading` win: both rows are then bare and the carry is gated on a non-`reading` carrier, so classification and carry would both need redesign and a deliberate `toRead` would be silently disposable. A review card for one value breaks bare-folds-into-authored for a race in a single-reader library. An entries-based rule changes its answer while entries are in transit |+| Q12 | 2026-09-21 | The carry directions that involve `toRead`: a `catchingUp` carrier does not write over `toRead`; a `finished` or `abandoned` carrier may | The existing guard lets `catchingUp` write only over `reading`, and `catch-up-mode` Q15 accepted a done carrier writing over any row; this feature changes neither |+| Q13 | 2026-09-21 | Promotion writes `reading` only to the rows of the group that are on `toRead` | Raised at the requirements review. The capture commit and the Move To destination do not refuse a torn work group, unlike edit mode's Save, so a group-wide write would put `reading` over a sibling's `abandoned` that is waiting on the review card |+| Q14 | 2026-09-21 | A to-read work's entries stay in Today's noted section on the day they were noted | Raised at the requirements review. The noted section is the day's record, not a plan; a work set back to `toRead` by hand, or left on it by teaching or a merge, still had those chapters noted on those days |+| Q15 | 2026-09-21 | Only the New Work form creates `toRead`; fixtures, seeds and tests that create a work without naming a status keep `reading` | Raised at the requirements review. `createWork` has one production caller and about sixty fixture and test callers that model captured works; moving them would change the Today fixtures and the M4 `todayPublication` arm's input for no benefit to the feature |+| Q16 | 2026-09-21 | No change to `ConstellationSegmentedControl` is needed for five segments | Checked at the requirements review: the control is generic over its values, and its stacked fallback is already exercised at the largest accessibility size. Req 1.6 is a verification obligation |+| Q17 | 2026-09-21 | Glyph `bookmark`, label `To read` | Owner's pick. A bookmark marks a place to come back to, and it is distinct from `forward.fill`, `checkmark` and `book.closed` |+| Q18 | 2026-09-21 | `NewWorkDraft` gains a `readingStatus` field defaulted to `.reading`, and only the New Work form passes `.toRead` | Follows Q15. `WorkMetadataDraft` deliberately has no defaults so an editor cannot forget a field; `NewWorkDraft` is the opposite case, one production caller and about sixty fixture and test callers that must keep today's value, so the default is the point |+| Q19 | 2026-09-21 | Promotion is one instance method on `Work`, `promoteFromToRead()`, called from two sites: the `.reuse`/`.claim` arm of `applyCaptureAssignment` and the `.existing` arm of `moveEntry` | Both sites already hold the destination group's rows and already stamp each one, so the write adds no fetch and dirties no new row. `applyCaptureAssignment` has one caller, `commitCapture`, which the pending-capture drain also uses, so the capture site covers Req 3.1 whole and reparse cannot reach it |+| Q20 | 2026-09-21 | Move To promotes only when the entry group did not already point at the destination work (`!priorWorkIDs.contains(workID)`) | `moveEntry`'s no-op return needs manual provenance on every row, so re-moving an entry that is in the work under derived provenance is a real write; it is not the reader starting to read |+| Q21 | 2026-09-21 | The Works-options UI fixture gains one to-read work with no entries; the M4 fixture is untouched | The glyph, the filter value and the no-entries placement need a row to be tested against; Today excludes `toRead` by the existing predicate, so there is nothing for a performance arm to measure |+| Q22 | 2026-09-21 | For a group whose rows disagree, the reading status shown, filtered on and read by Today is the one the work's snapshot carries, the carrier row's | Raised at the design review. The requirements' Definitions first named the representative row; the snapshot projects every authored field of a split group from the carrier (`work-and-reading-status` Req 7.2), and a status that followed a different row than the verdict beside it would be a new inconsistency. The Definitions were corrected to match |+| Q23 | 2026-09-21 | A Save that the lookup-to-commit guard re-resolves to a new capture, over an unresolved duplicate set or a torn entry group, counts as a capture and promotes | Raised at the design review. Req 3.5's re-share is the lookup resolving to the edit arm; here the reader saved a new entry into the work (`duplicate-reconciliation` Req 7.1), which is the same evidence as any other capture |+| Q24 | 2026-09-21 | The fixture's to-read work is `Vesper Tide` on `alpha.test`, seeded last | A title that sorts between Quill Harbour and Zephyr Court, so all four pinned orders place it unambiguously, and a later millisecond than Quill Harbour so the no-entries run's `modifiedAt` order is deterministic |+| Q25 | 2026-09-21 | No lint guards the `NewWorkDraft` default; the design lists `createWork`'s production callers instead | Proposed at the design review and declined: the repo has no linter by choice, and one defaulted argument does not justify one |+| Q26 | 2026-09-21 | The `AccessibilityJourneyUITests` segment identifier list moves with the UI task (task 11), not the enum task | Found at the phase 1 review: the design listed it among the enum task's pins, but the list is hard-coded, so adding the case neither breaks nor extends it, and the segment it would assert does not exist in the editor until the UI phase |+| Q27 | 2026-09-21 | Req 3.7 is met by the existing last-writer-wins Save; `updateWork` gains no basis check | Found implementing task 8: the design and task 8 expected `.conflict` from a stale to-read Save, but `WorkEditBasis.matches` is consulted only by the post-collapse redirect, so no field changed elsewhere conflicts on an ordinary Save. Req 3.7 asks for the same treatment as any other such change, which is what happens; adding a basis check to `updateWork` would change every edit in the app and is out of this spec's scope. Pinned in `RepositoryWorksTests.aPromotionIsVisibleToAnOpenEditor`. `work-and-reading-status` Req 7.4 overstates the same thing |+| Q28 | 2026-09-21 | No journey scroll step changed for the five-segment status card; the iPad case walks the segments in landscape and again after rotating to portrait | The design's first risk, verified negative in task 11: every editor step in both suites already reaches its target through `scrollUntilPresent` or `scrollUntilTappableAndTap`, which walk up to eight screenfuls, so a card one row taller costs nothing. Req 1.6 says wide layouts, plural, so one launch covers both; a portrait launch has no sidebar row to start the walk from |+| Q29 | 2026-09-22 | Two UI-test repairs outside the design ride on this branch: a shared Works-options menu label is picked by its uniquely labelled neighbour (`WorksOptionNeighbour`), and two `TodayUITests` predicates read "not the selected one" | Found in task 13. The menu's picker rows carry no accessibility identifiers, and `Any` (eight filter pickers) and `Finished` (both status vocabularies) are shared labels; the fifth status moved the rows enough that the ambiguous query raised. `firstMatch` was rejected because it would tap another dimension's row and pass. The Today failure is unrelated to this feature: on the calendar's first weekday the strip pages back a week and the current day's cell is not drawn. Both blocked a green `make test`, so they were fixed here rather than ticketed. Giving the picker rows identifiers is the production fix and is not part of this spec |++## Decision 1: A capture or a move promotes a to-read work to reading++**Date**: 2026-09-21+**Status**: accepted++### Context++`work-and-reading-status` Q8 and Req 2.6 say a capture never changes a status, because a silent status flip from the share extension would surprise the reader and the extension stays out of write-side rules. `RepositoryCaptureTests` pins it, including the case of an `abandoned` work that receives a capture and stays `abandoned`.++`toRead` is different from the statuses Q8 was written for. It states that the reader has not started the work, and noting a chapter is direct evidence that they have. Left alone, every to-read work the reader starts would keep a status that is visibly false until they open the editor and correct it.++Eleven code paths attach an entry to a work: the capture commit (which the pending-capture drain shares), Move To, teaching, reparse, merge, duplicate collapse, work deletion re-pointing, import and two others. Only some of them are the reader saying "I am reading this".++### Decision++A committed capture into a to-read work, drained pending captures included, and a Move To into an existing to-read work set its reading status to `reading` in the same commit. Nothing else promotes, and no status other than `toRead` is changed by either action.++### Rationale++The rule is carved out by name: a capture promotes `toRead` and only `toRead`, so Q8's concern holds for every other status, and the `abandoned` case stays pinned. Capture and Move To are the two reader actions that put a noted chapter on a work; the other attach paths are repairs, imports or restructurings that either carry a status of their own or resolve statuses by their own rules.++The write is part of the reader's commit, not of a reconcile pass, so the convergence rule that the silent path writes only what synced content determines is untouched.++### Alternatives Considered++- **No promotion**: the reader flips the status by hand, Q8 stands verbatim - Rejected by the owner: a to-read work with a chapter noted today claims something false, and the correction is a chore the app can do.+- **Capture only**: Move To leaves the status alone - Rejected: moving a noted chapter into a work is the same evidence as capturing one into it.+- **Teaching's claim also promotes**: a capture on an untaught site attaches to the to-read work only when the site is taught - Rejected: the sweep is a bulk repair that can claim many entries across many works in one pass, its timing says nothing about when reading began, and it would put many planned works on Today at once.+- **Every attach path, reconcilers included**: the status follows the presence of entries - Rejected: a reconciler would write on the basis of an event rather than synced content, and the reader can legitimately set `toRead` on a work that has entries (Req 1.3), which such a rule would undo on the next pass.+- **Derived, not stored**: a work with no entries displays as to read - Rejected: no way to mark an entry-bearing work to read, and no way to tell a to-read work from one the reader is reading but has not noted yet.++### Consequences++**Positive:**+- A capture or a move that reaches a to-read work leaves no manual correction to make.+- The rule names one status, so every existing capture guarantee holds for the other four.++**Negative:**+- The share extension now writes a work status, the thing Q8 kept it out of.+- The promotion is an event, not a function of synced content, so it can be undone: under last-writer-wins by an unrelated edit from a device still holding `toRead`, and by the convergence carry when a `toRead` twin joins a promoted capture-minted row that has nothing else authored (Q10). Accepted for a single-reader library.+- The promotion does not reach every way a to-read work gains entries. A capture on an untaught site saves unattached, and the teaching that later claims it into the to-read work does not promote. A work made by hand under a title that differs from the parsed one has no duplicate bucket key, so the capture mints a second work that no scan links; the reader merges by hand, and a merge into the to-read work keeps `toRead`.+- A promotion made while the work is open in edit mode surfaces as an edit conflict on Save.++### Impact++`work-and-reading-status` Req 2.6 and Q8 are amended. The capture commit, which the pending-capture drain also goes through, and `moveEntry` gain the write; `RepositoryCaptureTests` gains the carve-out beside the pinned `abandoned` case.++---++## Requirements of earlier specs this amends++- `work-and-reading-status` Req 2.1 and 6.1 (the values and their fixed order): five values, `toRead`, `reading`, `catchingUp`, `finished`, `abandoned`. Req 2.6 (every creation path carries the defaults; a capture leaves the statuses alone): the New Work form creates `toRead` (Q5), and a capture or a move promotes a to-read work (Decision 1). Q8 of its decision log: carved out for `toRead` by Decision 1. Its Non-Goal of no status controls on the New Work form stands.+- `catch-up-mode` Q11 (`catchingUp` ordered second): third, after `toRead` and `reading`. Q14 (four segments): five.
diff --git a/specs/to-read/design.md b/specs/to-read/design.mdnew file mode 100644index 00000000..b4b03609--- /dev/null+++ b/specs/to-read/design.md@@ -0,0 +1,142 @@+# Design: To Read++## Overview++A fifth `ReadingStatus` case, `toRead`, plus three writes that did not exist: the New Work form creates with it, and the capture commit and Move To replace it with `reading`. No schema, marker or archive generation moves; the column is a defaulted raw string with a tolerant read. Everything else is the existing reading-status machinery gaining one value.++## Architecture++### The enum++`DomainEnums.swift`: `case toRead` is declared first. `isDone` is unchanged. `ReadingStatus` is `String, CaseIterable, Codable` with no `Comparable` conformance, and nothing indexes `allCases`, so declaration order changes iteration order only: the picker, the filter menu and the review card's status line ([1.2](requirements.md#1.2)).++The raw string is what reconciliation sees. `AuthoredContent.orderComponents` (`GroupOrdering.swift:331`) carries `readingStatus.rawValue` into the representative order and `VariantID`, and `"reading" < "toRead"`, so an existing `reading` row is not displaced as representative by a `toRead` sibling. The raw value `toRead` is therefore fixed once shipped, like the other four.++`backup-14-15-golden.json` holds no to-read work and `library-graph-baseline.txt` is structural; neither moves.++### Parity audit: consumers of a reading status value++| Site | Today | Needs change | Why |+|---|---|---|---|+| `WorkStatusPresentation.swift` `name`, `systemImage`, `verdictPrompt` | exhaustive switches | yes | `To read`, `bookmark`, `nil`; the `systemImage` doc comment gains the new glyph's meaning |+| `WorkStatusPresentation.swift` `hue`, `accessibilityLabel`, `controlIdentifier` | one cyan; label and identifier built from the name and raw value | no | yields `Reading: To read`, `work-detail-reading-status-toRead` |+| `WorkDetailView.swift:1067` picker, `WorksView.swift:355` filter menu | `allCases` | no | |+| `WorksListOptions.swift:341`, `:616` filter match and pill | the selected value | no | |+| `WorksView.swift:792`, `:937` row glyph; `WorkDetailView.swift:723` meta item | drawn when `systemImage != nil` | no | `bookmark` draws |+| `WorkDetailView.swift:590` verdict | `isDone` | no | hidden for `toRead` ([1.3](requirements.md#1.3)) |+| `WorkDetailModel.setDraftReadingStatus` | prompts only for `.finished` | no | |+| `WorkDetailModel.setDraftWorkStatus` | moves a draft between `reading` and `finished` only | no | a `toRead` draft is untouched |+| `WorkDetailModel.releaseDaysNote` (`:249-254`) | existing line for any pair other than ongoing + reading | no | [4.3](requirements.md#4.3) |+| `TodayDayPlan.swift:227-229` schedule build | `catchingUp` bucket, else `ongoing && reading` | no | `toRead` fails both ([4.1](requirements.md#4.1)) |+| `TodayDayPlan.notedSection` | entry-driven, no status filter | no | [4.2](requirements.md#4.2) |+| `WorksListOptions.abandonedLast`, `WorksView.swift:868` | `== .abandoned` | no | a to-read row is active ([1.5](requirements.md#1.5)) |+| `WorksListOptions.ordered` no-entries split | `entries.isEmpty` | no | status plays no part |+| `LibraryRepository+Groups.swift:409-439` snapshot projection | a split group's `readingStatus` is the carrier row's | no | this is the status shown, filtered on and read by Today |+| `LibraryRepository.swift:1361` `updateWork` | writes the draft status to every row; refuses a torn group | no | [1.4](requirements.md#1.4) |+| `GroupOrdering.isBare` (`:304`) | bare only on `reading` | no | `toRead` is authored ([5.1](requirements.md#5.1)) |+| `GroupOrdering.orderComponents` (`:331`) | raw value in the row order | no | see above |+| `LibraryRepository+DuplicateResolution.swift:394`, `:506`, `:770-809`; `DuplicateResolutionView.swift:371` | status as a differing field; the reader's choice written to every survivor | no | |+| `DuplicateReconciler.swift:1754-1770` carry guard | `catchingUp` writes only over `reading` | **yes** | see below |+| `WorkVariantUnion.swift:254`, `WorkMergePlanner.swift:274`, `WorkMergeView.swift:414` | target's status kept; non-`reading` differing source listed as discarded | no | [5.3](requirements.md#5.3) |+| `LibraryRepository+Redirect.swift:331` | compares to the basis | no | |+| `BackupV14Types.swift:297`, `BackupArchiveProjection`, `+ConfirmImport.swift:1013` | typed enum on the wire; import writes the record's value | no | [6.1](requirements.md#6.1) |+| `ToleratedEnum.read(…, default: .reading)` | unknown raw reads `reading` | no | the default does not move |+| `LibraryProviding`, `MockLibraryProvider.swift:153` | pass and record the draft | no | |+| `M4PerformanceFixture.swift:228` | marks `catchingUp` works | no | Non-Goal |+| Stats, markdown export, share extension views | do not read the status | no | the share sheet's cyan `bookmark.fill` beside `Chapter:` never shares a screen with a reading status |++### The carry guard++`DuplicateReconciler.apply(_:to:types:)`:++```swift+let writesOnlyOverDefault = carriedReadingStatus == .catchingUp || carriedReadingStatus == .toRead+let carryMayOverwrite = !writesOnlyOverDefault || row.readingStatus == .reading+```++A `toRead` carrier writes only over `reading`; a `catchingUp` carrier cannot write over `toRead`; `finished` and `abandoned` carriers are unchanged ([5.2](requirements.md#5.2)). The comment block above the guard (`:1754-1762`) is rewritten to describe both values.++### Creation++`NewWorkDraft` gains `readingStatus: ReadingStatus`, defaulted to `.reading` in its initialiser (Q18). `createWork` assigns it to the created work before the one save it already makes. `createWork`'s production callers are exactly one, `NewWorkFormModel.create()`, which passes `.toRead`; its other callers are the `AppLibraryModel` seeds, `CoveredWorkFixture` and tests, which name no status and keep `reading` ([2.2](requirements.md#2.2)). `Work.create` is unchanged, so Move To a new work and the capture `.create` arm cannot produce `toRead`.++### Promotion++One instance method on `Work`, beside `refreshParsedTitle`:++```swift+/// Req 3.3: a row on `toRead` becomes `reading`; a row on any other status is left alone.+func promoteFromToRead()+```++It writes `readingStatusRaw` only when the row reads `toRead`, reads no clock, and is called from the two reader commits below and nowhere else.++| Call site | Where | Condition |+|---|---|---|+| Capture | `applyCaptureAssignment`, `.reuse`/`.claim` arm, inside the existing `for work in group.rows` loop (`+ReparseCapture.swift:464-477`) | always |+| Move To | `moveEntry`, `.existing` arm, inside the existing `for row in destinationGroup.rows` stamping loop (`LibraryRepository.swift:1469`), which sits after the no-op early return | `!priorWorkIDs.contains(workID)` |++Contracts:++- **Reach.** Both sites hold every row of the work's UUID: `hostnameWorks` fetches `Work` rows by id (`LibraryRepository.swift:1811-1836`) and `workGroups` buckets on `row.id`; `fetchWorkGroup` does the same for Move To. Both loops already stamp `modifiedAt` on each row, so promotion adds no fetch and dirties no row the commit was not already dirtying ([3.3](requirements.md#3.3), [3.4](requirements.md#3.4)).+- **Atomicity.** Both writes precede the operation's single `saveStrategy.save`. `withLockedContext` builds a `ModelContext` per operation (`LibraryRepository.swift:1704`) and discards it on a refusal, a rollback or a thrown save, so an unsaved promotion never outlives its commit and no re-fault is owed ([3.1](requirements.md#3.1)).+- **Representative.** `WorkGroup.representative` is elected when the group is built and is not recomputed when a row changes, and both sites read it from a group built before any write, so `entry.work` is assigned the pre-write representative in both. Writing only the `toRead` rows does not create the row asymmetry the fan-out in that loop exists to prevent: a `{toRead, reading}` group becomes uniform, and a `{toRead, abandoned}` group already disagreed. An entry pointing at a row that a later scan no longer elects is the standing model; any row of a UUID group is the work.+- **What counts as a capture.** `applyCaptureAssignment` has one caller, `commitCapture`, and its entry is always newly constructed (`+ReparseCapture.swift:325`). The pending-capture drain commits through it. A re-share, live (`updateEntry`) or drained (`recordDrainedReShare`), never reaches it and never assigns `entry.work` ([3.5](requirements.md#3.5)). When the lookup-to-commit guard re-resolves to `.new` over an unresolved duplicate set or a torn entry group, the reader's Save creates a new entry (`duplicate-reconciliation` Req 7.1); that is a capture and it promotes (Q23).+- **Move To condition.** `priorWorkIDs` holds the application UUIDs the entry group's rows pointed at before the move. The test is narrower than the no-op return above it, which also requires manual provenance on every row: a move that only sets manual provenance on an entry already in the work is a real write and does not promote ([3.2](requirements.md#3.2)). A move between two distinct-UUID works of one unresolved duplicate set promotes, because the entry was not in the destination.+- **Non-callers.** `moveEntry`'s `.newWork` and `.unattached` arms, the reparse commit, merge, collapse re-pointing (`DuplicateReconciler.swift:625`), import, and teaching's apply. Teaching's `.reuse`/`.claim` arm (`+ComposedTeaching.swift:778-802`) is the structural twin of the capture site and does not call it.+- **Conflict.** The capture basis and contract carry no work status, so promotion cannot stale a projection. `WorkEditBasis` carries `readingStatus`, so a promotion is visible wherever the basis is compared — but that is only the post-collapse redirect (`LibraryRepository+Redirect.swift`). An ordinary Save from an editor opened before the promotion is last-writer-wins, as for any other field changed elsewhere, and writes the reader's `toRead` back, which [1.4](requirements.md#1.4) permits ([3.7](requirements.md#3.7), Q27).+- **Refresh.** No code: the app refreshes after a Move To through `onMutation` and after an extension capture as it does for the entry itself, and Today republishes from the refreshed snapshot ([3.6](requirements.md#3.6)).+- Move To commits on the tap (T-2328); promotion is part of that commit.++### UI++No new view. The work editor's reading status control is `ConstellationSegmentedControl` over `allCases`; five caption segments exceed a phone card's width at the default text size, so its `ViewThatFits` takes the stacked arm there: five full-width rows of 44 pt. The editor is a lazy `List`, so the taller card scrolls. The control is unchanged (Q16); its doc comment (`ConstellationRecipes.swift:269-272`), which places the stacked arm at the largest accessibility sizes, is corrected.++The Works-options UI fixture (`AppLibraryModel.seedWorksOptionsFixture`) gains a fifth work, **Vesper Tide** on `alpha.test`, created through `createWork` with `readingStatus: .toRead`, no entries, seeded after the loose capture so its `modifiedAt` falls in a later millisecond than Quill Harbour's. The fixture's doc table gains its row. Pinned orders in `WorksListOptionsUITests.swift:42-45`:++| Sort | Order |+|---|---|+| Newest | Zephyr Court, Ashfall, Marrow Lane, Vesper Tide, Quill Harbour |+| Oldest | Ashfall, Zephyr Court, Marrow Lane, Quill Harbour, Vesper Tide |+| A–Z | Ashfall, Quill Harbour, Vesper Tide, Zephyr Court, Marrow Lane |+| Z–A | Zephyr Court, Vesper Tide, Quill Harbour, Ashfall, Marrow Lane |++The site-filter arrays for `alpha.test` (`:170`, `:255`, `:261`, `:270`) gain Vesper Tide, and `WorkDetailStatusUITests`' scroll to Quill Harbour (`:62-84`) and its merge-list labels (`:295`) are re-checked against the extra row in the no-entries run.++## Error Handling++No new failure mode. A refused capture or move discards the promotion with the rest of its context. A pre-feature build's behaviour is the standing tolerant-read, strict-wire rule (Q9).++## Risks and Assumptions++- Risk: the five-row stacked control makes the status card tall enough that a UI journey's existing scroll counts in the editor no longer reach the fields below it. | Verify: `AccessibilityJourneyUITests` and `WorkDetailStatusUITests`, run in the first UI task. | If wrong: the journeys' scroll steps are adjusted; the control stays as it is.+- Assumption: the no-entries run orders Vesper Tide before Quill Harbour under Newest. | Verify: `WorksListOptionsUITests` in the fixture task. | If wrong: the pinned arrays take the observed order, which is deterministic because the two `modifiedAt` values differ.++## Testing Strategy++Pins that move with the enum task, before anything else changes: `ModelContractTests.swift:60` (raw-value list), `WorksFilterPresentationTests.swift:165` (identifier list), `DuplicateSurfaceTests.swift:201` (review-card status lines, the [1.1](requirements.md#1.1) trace for that surface), `WorkStatusPresentationTests.swift:51` (distinct symbol count, 5 to 6). The segment identifier list at `AccessibilityJourneyUITests.swift:368-375` is hard-coded rather than built from `allCases`, so the enum does not break it; it gains `toRead` with the UI task (Q26).++Core (`make test-core`):++| Test file | Covers |+|---|---|+| `ModelContractTests` | raw value, five-case order, `isDone == false` |+| `RepositoryCaptureTests`, beside its Req 2.6 section | capture into a to-read work promotes, `.reuse` and `.claim`; capture into `abandoned` does not; a capture that mints a work is `reading`; a `{toRead, abandoned}` group keeps `abandoned` on its sibling and `reading` lands on the other; a failing save strategy leaves `toRead`; the only work column a promoting capture changes beyond a non-promoting one is `readingStatusRaw`; a capture re-resolved to `.new` over an unresolved duplicate set promotes |+| `PendingCaptureDrainTests` | a drained new capture promotes; a drained re-share does not |+| `RepositoryReShareTests` | a live re-share edit of an entry in a to-read work does not promote |+| `RepositoryWorksTests` | `createWork` with `.toRead` and with the default; Move To into a to-read work promotes and changes no other work column beyond today's; re-moving an entry already in the work under derived provenance does not; `.newWork` yields `reading`; a promotion moves a field `WorkEditBasis` carries, and a stale Save from an editor opened before it commits last-writer-wins (Q27, which replaced this row's first expectation of `.conflict`) |+| `FanOutWriteTests` | `updateWork` setting `toRead` on a work with entries writes every row of the group |+| `ComposedTeachingRepositoryTests` | teaching's claim of earlier captures into a to-read work leaves `toRead` |+| `WorkMergeRepositoryTests` | merging a work with entries into a to-read target keeps `toRead`; a differing source `toRead` is listed as discarded |+| `DuplicateScanTests`, `GroupOrderingTests` | a `toRead` row is non-bare; `{toRead, bare reading}` is one variant; `{toRead, finished}` is two, with reading status among the differing fields |+| `DuplicateReconcilerTests`, through `reconcile(afterScan:)` | `toRead` carrier writes over `reading` and not over `catchingUp`, `finished`, `abandoned`; `catchingUp` carrier does not write over `toRead`; `finished` carrier does; collapse re-pointing entries onto a to-read survivor leaves `toRead`; a promoted, otherwise-bare `reading` row beside a `toRead` twin converges back to `toRead` (Decision 1's accepted consequence, pinned so it is not later repaired as a bug) |+| `TodayDayPlanTests` | an ongoing to-read work with release days on the selected weekday is in no releases or catch-up section and adds no due weekday; its entry is in that day's noted section |+| `BackupV14ArchiveTests` | a to-read work with entries round-trips into an empty library as `toRead` |++[6.2](requirements.md#6.2) has no test of its own: there is no migration stage and no data pass, and `EnumTolerancePolicyTests` already pins the unchanged default.++`promoteFromToRead` is parameterised over all five statuses: `toRead` becomes `reading`, the other four are unchanged, and a second call changes nothing.++App (`make test-quick`): `WorkStatusPresentationTests` (name, glyph, label, no verdict prompt), `WorkDetailModelTests` (no prompt on choosing `toRead`; a work-status change leaves a `toRead` draft; the release-days line), `WorksListOptionsTests` (filter match, pill text `Reading: To read`, active placement, no-entries placement), `MoveToAndNewWorkModelTests` (the form's draft carries `.toRead`).++UI: `WorkDetailStatusUITests` and `AccessibilityJourneyUITests` gain the fifth segment, the latter at XXXL on iPhone; `WideLayoutAccessibilityUITests` (in `AccessibilityJourneyUITests.swift`, run by `make test-ui-ipad`) operates the five segments in edit mode on iPad; `WorksListOptionsUITests` gains the `Reading: To read` filter against Vesper Tide and the arrays above. The Mac half of [1.6](requirements.md#1.6) has no automation and is an owner hand check on a `Development` Mac build.
diff --git a/specs/to-read/prerequisites.md b/specs/to-read/prerequisites.mdnew file mode 100644index 00000000..20d4f823--- /dev/null+++ b/specs/to-read/prerequisites.md@@ -0,0 +1,7 @@+# Prerequisites for To Read++These tasks must be completed by the user before or during implementation.++## Before Testing++- [ ] Mac hand check of Req 1.6, after task 11: on a `Development` Mac build, open a work, enter edit mode, and confirm all five reading status segments (`To read` first) can be reached and chosen, and that Save keeps the choice. No automation covers the Mac, and launching the Mac app is the owner's to do. It blocks no coding task.
diff --git a/specs/to-read/requirements.md b/specs/to-read/requirements.mdnew file mode 100644index 00000000..498a9ced--- /dev/null+++ b/specs/to-read/requirements.md@@ -0,0 +1,96 @@+# Requirements: To Read++## Introduction++The library has no way to hold a work the reader means to read but has not started: every work reads as `reading` from the moment it exists. This feature adds a fifth reading status, `toRead`, which the reader can set in edit mode and which the New Work form gives every work it creates. A to-read work becomes `reading` by itself when the reader captures a chapter into it or moves an entry into it. Transit ticket T-2354.++## Non-Goals++- No way to add a to-read work from the share sheet; sharing a work's landing page still creates an entry. Tracked as T-2363.+- No reading status on the `Series` entity, and no action that marks every work of a series to read.+- No status control on the New Work form or the Move To chooser.+- No to-read section, row or count on the Today screen.+- No automatic return to `toRead`: deleting or moving away a work's last entry leaves its status alone.+- No promotion by teaching, reparse, merge, duplicate collapse, import or any reconcile pass; a to-read work can hold entries after one of them, and the reader changes its status in edit mode.+- No promotion from any status other than `toRead`; an `abandoned` work that receives a capture stays `abandoned`.+- No new matching of captures to works and no new duplicate detection: a capture that the existing rules do not resolve to the to-read work promotes nothing, and a work made by hand under a title that differs from the one its site's rules parse is not linked to the work a later capture creates.+- No change to the default reading status: a work that has never been given one still reads as `reading`.+- No schema version, readiness marker or archive generation change.+- No change to the Stats tab or the markdown export, and no new performance arm or M4 fixture change.+- No support commitment for a device still on a pre-feature build sharing the library; such a build reads a to-read work as `reading`, lists it on Today if it has release days, and refuses to export (decision log Q9).++## Definitions++- **To-read work**: a work whose reading status reads as `toRead`, whatever its work status and whether or not it has entries. For a group whose rows disagree, the status shown, filtered on and used by [4.1](#4.1) is the one the work's snapshot carries, chosen as every other authored field of such a group is.+- **Promotion**: the change of reading status from `toRead` to `reading` as a consequence of [3.1](#3.1) or [3.2](#3.2).+- **Capture**: a new entry committed from the share sheet, or from a pending capture the app drains later. Re-sharing a page that matches an existing entry is not a capture.+- **Bare row**: a row of a group carrying no reader-authored content, as `specs/duplicate-reconciliation/` defines it. A work made by the New Work form is never bare, because its title is reader-authored.+- **Pre-feature build**: the app version shipping immediately before this feature.+- Edit mode, done reading, verdict, group and review surfaces are as defined in `specs/work-and-reading-status/requirements.md`.++## Requirements++### 1. The To-Read Status++**User Story:** As a reader, I want to mark a work as one I have yet to start, so that my library separates what I am reading from what I plan to read.++**Acceptance Criteria:**++1. <a name="1.1"></a>The system SHALL offer a reading status `toRead`, stored as the raw value `toRead`, named `To read`, with the glyph `bookmark` in the cyan reading hue and the accessibility label `Reading: To read`, everywhere the other reading statuses are shown: edit mode's reading status field, the work detail meta line, the Works list row glyph, the Works filter menu and its pill, the duplicate review card's status line and the merge preview's discarded-field list. +2. <a name="1.2"></a>Wherever the reading statuses are listed, `toRead` SHALL come first, before `reading`, `catchingUp`, `finished` and `abandoned`; the order is display order only and SHALL give `toRead` no precedence in reconciliation. +3. <a name="1.3"></a>`toRead` SHALL NOT be done reading: the verdict field and verdict text SHALL be hidden as they are for `reading`, a stored verdict SHALL be kept as `work-and-reading-status` Req 2.5 keeps it, choosing `toRead` in edit mode SHALL need no work-status precondition and raise no dialog, and a change of the draft work status SHALL leave a `toRead` draft where it is. +4. <a name="1.4"></a>The reader SHALL be able to set `toRead` on any work in edit mode, including a work that has entries, and to set any other reading status on a to-read work; both SHALL persist, to every row of the work's group, as the other reading statuses do. +5. <a name="1.5"></a>A to-read work's row on the Works list SHALL sort and draw as an active row, not at the reduced emphasis of an abandoned one, and a to-read work without entries SHALL be placed exactly as any other work without entries is. +6. <a name="1.6"></a>The reading status segment for the new value SHALL carry the accessibility identifier `work-detail-reading-status-toRead`, and all five segments SHALL be reachable and operable in edit mode at `UICTContentSizeCategoryAccessibilityXXXL` on iPhone, and in the wide layouts on iPad and Mac. ++### 2. New Works Start as To Read++**User Story:** As a reader adding a work by hand, I want it to start as to read, so that a work I have not captured anything for does not claim I am reading it.++**Acceptance Criteria:**++1. <a name="2.1"></a>A work created by the New Work form SHALL carry reading status `toRead`, work status `ongoing` and an empty verdict, and the form SHALL offer no status control. +2. <a name="2.2"></a>A work created by any other path — Move To a new work, a capture, teaching, or a UI-test, preview or performance fixture that names no status — SHALL carry reading status `reading` as it does today, and a work created by a backup import SHALL carry the archive's value. ++### 3. Starting to Read++**User Story:** As a reader, I want a to-read work to become one I am reading when I note a chapter of it, so that I do not have to change the status by hand after starting.++**Acceptance Criteria:**++1. <a name="3.1"></a>WHEN a capture commits a new entry into a to-read work, the work's reading status SHALL become `reading` in the same commit as the entry, whether the capture is committed by the share sheet or drained from the pending-capture queue, and IF that commit is refused or rolled back THEN the status SHALL be unchanged. +2. <a name="3.2"></a>WHEN the reader uses Move To to move an entry that is not already in it into an existing to-read work, the work's reading status SHALL become `reading` in the same commit as the move. +3. <a name="3.3"></a>Promotion SHALL set `reading` on every row of the work's group whose reading status is `toRead` and SHALL leave the reading status of every other row as it was; a work whose reading status is anything other than `toRead` SHALL keep it through a capture or a move. +4. <a name="3.4"></a>Promotion SHALL add no write beyond the reading status: the work status, verdict and release days SHALL be as they were, and whatever the capture or move writes today SHALL be unaffected. +5. <a name="3.5"></a>Re-sharing a page that matches an existing entry of a to-read work SHALL NOT promote it. +6. <a name="3.6"></a>The share sheet SHALL show no status and ask nothing about it; a promoted work SHALL show `reading` on the work detail screen and the Works list when the captured or moved entry appears there, and SHALL join Today at the next publication if it meets the existing scheduling conditions. +7. <a name="3.7"></a>IF a work is promoted while it is open in edit mode, THEN committing edit mode SHALL be treated as an edit conflict exactly as any other change to the work's edited fields made elsewhere is. ++### 4. Today++**User Story:** As a reader, I want Today's plan to stay the list of what I am reading now, so that works I have not started do not crowd it.++**Acceptance Criteria:**++1. <a name="4.1"></a>A to-read work SHALL NOT appear in Today's releases section or its `Catching up` section and SHALL NOT add a strip dot, whatever its release days and work status; its release days SHALL be kept unchanged and SHALL apply once the work meets the existing scheduling conditions. +2. <a name="4.2"></a>An entry of a to-read work SHALL stay in the noted section of the day it was noted, as an entry of any other work does. +3. <a name="4.3"></a>WHILE at least one release-day toggle is on and the draft reading status is `toRead`, the line under the toggles SHALL be the existing `Shown on Today only while the work is ongoing and you are reading it`. ++### 5. Groups, Duplicates and Merge++**User Story:** As a reader with the same work on more than one device or site, I want a to-read status to be handled as my other statuses are, so that reconciliation never surprises me with it.++**Acceptance Criteria:**++1. <a name="5.1"></a>`toRead` SHALL be reader-authored content in the duplicate phase, as the other non-default statuses are: a group of one `toRead` row and one bare `reading` row SHALL resolve silently to `toRead`, and a group whose rows disagree on any other authored content, a differing non-default reading status included, SHALL go to the review card with the reading status listed among the fields that differ. +2. <a name="5.2"></a>In the convergence pass a row carrying `toRead` SHALL write its status only over a row on `reading`; a row carrying `catchingUp` SHALL NOT write over a `toRead` row; a row carrying `finished` or `abandoned` MAY write over a `toRead` row as it may over any other today. +3. <a name="5.3"></a>WHEN two works are merged, the merged work SHALL keep the target's reading status, a differing source `toRead` SHALL be listed in the merge preview as discarded, and merging a work that has entries into a to-read target SHALL NOT promote it. ++### 6. Backup and Older Libraries++**User Story:** As a reader, I want my to-read works in my backups, so that a restore brings back the library I had.++**Acceptance Criteria:**++1. <a name="6.1"></a>A backup archive written by this build SHALL carry `toRead` under the current archive version pair, and importing it into an empty library SHALL leave every work with the reading status the archive gives it, a to-read work that the archive gives entries included. +2. <a name="6.2"></a>WHEN this build opens a library that has never held a `toRead` value, it SHALL convert nothing and every work SHALL keep the reading status it has.
diff --git a/specs/to-read/tasks.md b/specs/to-read/tasks.mdnew file mode 100644index 00000000..27e37193--- /dev/null+++ b/specs/to-read/tasks.md@@ -0,0 +1,122 @@+---+references:+ - specs/to-read/requirements.md+ - specs/to-read/design.md+ - specs/to-read/decision_log.md+---+# To Read++## Enum and presentation++- [x] 1. Move the pinned status lists and write presentation tests for toRead <!-- id:mbsdhyy -->+ - Pins that list the cases: ModelContractTests.swift:60 raw values in the order toRead, reading, catchingUp, finished, abandoned, plus isDone false for toRead; WorksFilterPresentationTests.swift:165 identifier list; DuplicateSurfaceTests.swift:201 review-card status lines; WorkStatusPresentationTests.swift:51 distinct symbol count 5 to 6+ - New in WorkStatusPresentationTests: name To read, glyph bookmark, label Reading: To read, identifier work-detail-reading-status-toRead, no verdict prompt+ - Red here is a compile failure on .toRead, which task 2 clears+ - Stream: 1+ - Requirements: [1.1](requirements.md#1.1), [1.2](requirements.md#1.2), [1.3](requirements.md#1.3)++- [x] 2. Add the toRead case and its presentation, then run test-core and test-quick <!-- id:mbsdhyz -->+ - DomainEnums.swift: case toRead declared first; isDone unchanged+ - WorkStatusPresentation.swift: the three exhaustive switches; rewrite the systemImage doc comment for the new glyph+ - No other production file changes in this task. Run make test-core and make test-quick straight after: any failure outside task 1's pins is an allCases dependency the design's audit missed and is fixed here before anything else moves+ - backup-14-15-golden.json and library-graph-baseline.txt do not move+ - Blocked-by: mbsdhyy (Move the pinned status lists and write presentation tests for toRead)+ - Stream: 1+ - Requirements: [1.1](requirements.md#1.1), [1.2](requirements.md#1.2), [1.3](requirements.md#1.3)++- [x] 3. Pin the Core behaviours that need no code <!-- id:mbsdhz0 -->+ - These pass as soon as task 2 lands; they exist so the behaviour cannot drift+ - FanOutWriteTests: updateWork setting toRead on a work with entries writes every row of the group+ - DuplicateScanTests and GroupOrderingTests: a toRead row is non-bare; toRead beside a bare reading row is one variant; toRead beside finished is two variants with reading status among the differing fields+ - TodayDayPlanTests: an ongoing toRead work with release days on the selected weekday is in no releases or catch-up section and adds no due weekday; its entry stays in that day's noted section+ - BackupV14ArchiveTests: a toRead work with entries round-trips into an empty library as toRead+ - WorkMergeRepositoryTests: a differing source toRead is listed as discarded and the target's status is kept+ - Blocked-by: mbsdhyz (Add the toRead case and its presentation, then run test-core and test-quick)+ - Stream: 1+ - Requirements: [1.4](requirements.md#1.4), [4.1](requirements.md#4.1), [4.2](requirements.md#4.2), [5.1](requirements.md#5.1), [5.3](requirements.md#5.3), [6.1](requirements.md#6.1), [6.2](requirements.md#6.2)++## Core writes++- [x] 4. Write carry guard tests for the toRead directions <!-- id:mbsdhz1 -->+ - DuplicateReconcilerTests through reconcile afterScan, on the shape of defaultCarrierNeverOverwritesASiblingStatus+ - toRead carrier writes over reading and not over catchingUp, finished or abandoned; catchingUp carrier does not write over toRead; finished carrier does+ - Blocked-by: mbsdhyz (Add the toRead case and its presentation, then run test-core and test-quick)+ - Stream: 1+ - Requirements: [5.2](requirements.md#5.2)++- [x] 5. Extend the convergence carry guard to toRead <!-- id:mbsdhz2 -->+ - DuplicateReconciler.swift near 1763: writesOnlyOverDefault covers catchingUp and toRead, per the design's snippet+ - Rewrite the comment block above the guard so it describes both values; that comment is the record+ - Blocked-by: mbsdhz1 (Write carry guard tests for the toRead directions)+ - Stream: 1+ - Requirements: [5.2](requirements.md#5.2)++- [x] 6. Write creation tests for the New Work draft status <!-- id:mbsdhz3 -->+ - RepositoryWorksTests: createWork with a draft naming toRead creates toRead, ongoing, empty verdict; the default draft creates reading+ - MoveToAndNewWorkModelTests: the form's recorded draft carries toRead via MockLibraryProvider+ - Blocked-by: mbsdhyz (Add the toRead case and its presentation, then run test-core and test-quick)+ - Stream: 1+ - Requirements: [2.1](requirements.md#2.1), [2.2](requirements.md#2.2)++- [x] 7. Add readingStatus to NewWorkDraft and pass toRead from the New Work form <!-- id:mbsdhz4 -->+ - RepositoryDrafts.swift: NewWorkDraft.readingStatus defaulted to .reading in the initialiser, decision Q18+ - LibraryRepository.createWork assigns it before its existing single save; Work.create is unchanged+ - NewWorkFormModel.create passes .toRead; no seed, fixture or test caller is edited+ - Blocked-by: mbsdhz3 (Write creation tests for the New Work draft status)+ - Stream: 1+ - Requirements: [2.1](requirements.md#2.1), [2.2](requirements.md#2.2)++- [x] 8. Write promotion and non-promotion tests <!-- id:mbsdhz5 -->+ - Work.promoteFromToRead parameterised over all five statuses: toRead becomes reading, the other four are unchanged, a second call changes nothing+ - RepositoryCaptureTests beside its Req 2.6 section: reuse and claim promote; capture into abandoned does not; a minted work is reading; a toRead plus abandoned group keeps abandoned on its sibling; a failing save strategy leaves toRead; the only work column a promoting capture changes beyond a non-promoting one is readingStatusRaw; a capture re-resolved to new over an unresolved duplicate set promotes, decision Q23+ - PendingCaptureDrainTests: a drained new capture promotes, a drained re-share does not. RepositoryReShareTests: a live re-share edit does not+ - RepositoryWorksTests: Move To into a toRead work promotes; re-moving an entry already in the work under derived provenance does not; newWork yields reading; updateWork with a toRead basis against a promoted work returns conflict+ - Non-promotion pins: ComposedTeachingRepositoryTests teaching claim; WorkMergeRepositoryTests merge of a work with entries into a toRead target; DuplicateReconcilerTests collapse re-pointing onto a toRead survivor+ - DuplicateReconcilerTests: a promoted, otherwise-bare reading row beside a toRead twin converges back to toRead. This is Decision 1's accepted consequence; the test name and comment say so+ - Blocked-by: mbsdhz2 (Extend the convergence carry guard to toRead), mbsdhz4 (Add readingStatus to NewWorkDraft and pass toRead from the New Work form)+ - Stream: 1+ - Requirements: [3.1](requirements.md#3.1), [3.2](requirements.md#3.2), [3.3](requirements.md#3.3), [3.4](requirements.md#3.4), [3.5](requirements.md#3.5), [3.7](requirements.md#3.7), [5.3](requirements.md#5.3)++- [x] 9. Implement promoteFromToRead and call it from the capture commit and Move To <!-- id:mbsdhz6 -->+ - Models.swift: instance method beside refreshParsedTitle; writes readingStatusRaw only when the row reads toRead; reads no clock+ - Capture site: inside the existing for work in group.rows loop of applyCaptureAssignment's reuse and claim arm, LibraryRepository+ReparseCapture.swift 464-477+ - Move To site: inside the existing destinationGroup.rows stamping loop of moveEntry's existing arm, after the no-op early return, under !priorWorkIDs.contains(workID)+ - Do not call it from +ComposedTeaching.swift 778-802, the structural twin of the capture site, nor from reparse, merge, collapse or import+ - Amend the Req 2.6 section comment in RepositoryCaptureTests to name the carve-out; 3.6 needs no code+ - Blocked-by: mbsdhz5 (Write promotion and non-promotion tests)+ - Stream: 1+ - Requirements: [3.1](requirements.md#3.1), [3.2](requirements.md#3.2), [3.3](requirements.md#3.3), [3.4](requirements.md#3.4), [3.5](requirements.md#3.5), [3.6](requirements.md#3.6), [3.7](requirements.md#3.7)++## App and UI++- [x] 10. Pin the app view model behaviours for toRead <!-- id:mbsdhz7 -->+ - WorkDetailModelTests: choosing toRead raises no finished-reading prompt; a work-status change leaves a toRead draft; the release-days line is the existing note for toRead+ - WorksListOptionsTests: filter match, pill text Reading: To read, a toRead row is not partitioned with abandoned, a toRead work without entries sits in the no-entries run+ - Blocked-by: mbsdhyz (Add the toRead case and its presentation, then run test-core and test-quick)+ - Stream: 2+ - Requirements: [1.3](requirements.md#1.3), [1.5](requirements.md#1.5), [4.3](requirements.md#4.3)++- [x] 11. Extend the editor journeys to five segments on iPhone and iPad <!-- id:mbsdhz8 -->+ - This task verifies the design's first risk: five stacked segments lengthen the status card, so existing scroll steps in the editor may fall short. Fix the journeys' scroll steps, not the control+ - AccessibilityJourneyUITests.swift 368-375: segment identifier list gains toRead, operated at XXXL on iPhone. WorkDetailStatusUITests: the fifth segment. WideLayoutAccessibilityUITests: the five segments in edit mode on iPad+ - ConstellationRecipes.swift 269-272: correct the doc comment; the stacked arm is now the default phone layout for five values. No change to the control+ - Run make test-ui for the two iPhone suites and make test-ui-ipad+ - Blocked-by: mbsdhyz (Add the toRead case and its presentation, then run test-core and test-quick)+ - Stream: 2+ - Requirements: [1.6](requirements.md#1.6)++- [x] 12. Add Vesper Tide to the Works-options fixture and update its UI pins <!-- id:mbsdhz9 -->+ - AppLibraryModel.seedWorksOptionsFixture: Vesper Tide on alpha.test through createWork with readingStatus toRead, no entries, seeded after the loose capture; add its row to the fixture's doc table+ - WorksListOptionsUITests.swift 42-45 take the four orders in design.md; the alpha.test site-filter arrays at 170, 255, 261 and 270 gain Vesper Tide; add a Reading: To read filter step listing only Vesper Tide+ - Verifies the design's second assumption: if Newest does not place Vesper Tide before Quill Harbour, pin the observed order+ - Re-check WorkDetailStatusUITests 62-84 scroll to Quill Harbour and the merge-list labels at 295 against the extra row+ - Blocked-by: mbsdhz4 (Add readingStatus to NewWorkDraft and pass toRead from the New Work form), mbsdhz8 (Extend the editor journeys to five segments on iPhone and iPad)+ - Stream: 2+ - Requirements: [1.1](requirements.md#1.1), [1.5](requirements.md#1.5), [2.2](requirements.md#2.2)++- [x] 13. Add the changelog entry and run the full suites <!-- id:mbsdhza -->+ - CHANGELOG.md: an Added entry under Unreleased+ - make test-core with zero known issues and no new compiler warnings, make test, make test-ui-ipad. No Personal target and no device run+ - Blocked-by: mbsdhz0 (Pin the Core behaviours that need no code), mbsdhz6 (Implement promoteFromToRead and call it from the capture commit and Move To), mbsdhz7 (Pin the app view model behaviours for toRead), mbsdhz9 (Add Vesper Tide to the Works-options fixture and update its UI pins)+ - Stream: 1+ - Requirements: [1.6](requirements.md#1.6), [3.6](requirements.md#3.6)
diff --git a/specs/to-read/implementation.md b/specs/to-read/implementation.mdnew file mode 100644index 00000000..7c026ff3--- /dev/null+++ b/specs/to-read/implementation.md@@ -0,0 +1,205 @@+# Implementation: To Read++An explanation of what branch `T-2354/to-read` does, at three levels, written+before the push as a check that every requirement can be explained from the+code. The completeness assessment is at the end.++## Beginner Level++### What Changed++Every work in the library used to read as "Reading" from the moment it+existed, even one the reader had only written down to try later. There is now+a fifth reading status, **To read**, shown with a bookmark glyph. It sits+first in the list: to read, reading, catching up, finished, abandoned.++Three things set or clear it:++- The **New Work form** creates a work as To read, because a work typed in by+ hand has no chapters noted yet.+- The reader can choose it, or leave it, in a work's **edit mode**, like any+ other status.+- When the reader **notes a chapter** of a to-read work from the share sheet,+ or **moves an entry** into it, the work becomes Reading by itself, in the+ same save.++A to-read work stays off the Today screen's plan, because Today is what the+reader is reading now. Its release days are kept and start counting once the+work is Reading.++### Why It Matters++The library can now tell "I am reading this" from "I mean to read this", and+the reader does not have to flip the status by hand when they start.++### Key Concepts++- **Reading status**: the reader's own relationship to a work, separate from+ the work's status (ongoing, finished, on hiatus).+- **Promotion**: the automatic change from To read to Reading.+- **Capture**: a new entry saved from the share sheet. Sharing a page that is+ already in the library is a re-share, not a capture, and promotes nothing.+- **Group**: the same work can exist as several rows while devices sync. The+ app treats those rows as one work and repairs disagreements between them.++---++## Intermediate Level++### Changes Overview++- `DomainEnums.swift`: `case toRead`, declared first. `isDone` is unchanged,+ so the verdict stays hidden for it.+- `WorkStatusPresentation.swift`: three exhaustive switches gain an arm (`To+ read`, `bookmark`, no verdict prompt). The hue, accessibility label and+ control identifier are derived from the name and raw value and needed none.+- `RepositoryDrafts.swift`, `LibraryRepository.swift`: `NewWorkDraft` gains+ `readingStatus`, defaulted to `.reading`; `createWork` assigns it before its+ one save. `NewWorkFormModel` is the only production caller passing `.toRead`.+- `Models.swift`: `Work.promoteFromToRead()`, a value-guarded write of the raw+ column.+- `LibraryRepository+ReparseCapture.swift`, `LibraryRepository.swift`: the two+ call sites, in the capture commit's `.reuse`/`.claim` arm and in+ `moveEntry`'s `.existing` arm.+- `DuplicateReconciler.swift`: the reading-status carry guard covers two+ values instead of one.+- `AppLibraryModel.swift`: the Works-options UI fixture gains `Vesper Tide`.+- Tests across Core, the app unit bundle and the UI suites; UI test support+ gains a way to pick a menu row whose label is shared.++Everything else — the picker, the filter menu, the row glyph, Today's+schedule, the archive, merge — iterates `allCases` or reads a value, and+handles the new case with no change. The design's parity audit lists each+site; the implementation found none it had missed.++### Implementation Approach++The status is a raw-string enum column with a tolerant read, so adding a case+needs no schema, marker or archive generation change.++Creation is kept narrow by putting the status on the draft, not in+`Work.create`: Move To a new work, the capture `.create` arm and import all go+through `Work.create` and so cannot mint a to-read work.++Promotion is one method called from two loops that already stamp+`modifiedAt` on every row of the destination group. It adds no fetch and+dirties no row the commit was not already dirtying, and it runs before the+operation's single save, so a refused commit discards it with everything+else.++### Trade-offs++- **An enum case, not a flag** (Q4): no schema bump, and a work is to read or+ reading, never both. The cost is a fifth segment, which makes the stacked+ layout the phone's usual one.+- **Per row, not per group** (Q13): the capture commit does not refuse a torn+ group, so a group-wide write could put `reading` over a sibling's+ `abandoned` that is waiting on the review card.+- **A defaulted draft field** (Q18): the opposite of `WorkMetadataDraft`, which+ has no defaults so an editor cannot forget a field. Here there is one+ production caller and about sixty fixture callers that must keep `reading`.+- **Only a capture or a move promotes** (Decision 1): teaching, reparse, merge,+ collapse and import can leave a to-read work holding entries. That state is+ valid; the reader can also reach it by hand.++---++## Expert Level++### Technical Deep Dive++**Ordering and reconciliation.** Declaration order is display order only. The+representative order and `VariantID` use the raw string, and `"reading" <+"toRead"`, so a `toRead` sibling does not displace an existing `reading` row+as representative. The raw value is fixed once shipped.++**The carry guard.** `toRead` and `catchingUp` are authored content that may+write only over a row still on the default:++```swift+let writesOnlyOverDefault = carried == .catchingUp || carried == .toRead+let carryMayOverwrite = !writesOnlyOverDefault || row.readingStatus == .reading+```++`finished` and `abandoned` carriers stay unnarrowed. The guard exists because+the scan and the write read the rows at different moments.++**Promotion.** `promoteFromToRead` compares and writes `readingStatusRaw`+rather than the tolerant accessor: an unknown stored spelling reads as+`reading` through the accessor, and such a row is not a to-read row. It reads+no clock, so two devices given the same row agree, and a second call is a+no-op, which keeps the fixed point clean.++Move To is gated on `!priorWorkIDs.contains(workID)` (Q20). That is narrower+than `moveEntry`'s no-op return, which also needs manual provenance on every+row: re-moving an entry a rule attached is a real write, but it is not the+reader starting to read.++Q23's case is covered: a Save the lookup-to-commit guard re-resolves to a new+capture still reaches `applyCaptureAssignment`, so it promotes.++### Architecture Impact++No new table, relationship, reconciler or trigger. The convergence pass keeps+its order and its idempotence. The share extension gains nothing: it commits+through the same repository call the drain uses.++One accepted consequence (Decision 1, pinned in `DuplicateReconcilerTests`): a+promoted, otherwise bare `reading` row beside a `toRead` twin converges back+to `toRead`, because bare folds into authored. It needs a capture-minted row+with nothing else authored, so it is narrow.++### Potential Issues++- **Req 3.7 is last-writer-wins** (Q27). `WorkEditBasis.matches` is consulted+ only by the post-collapse redirect, so an editor opened before a promotion+ saves its `toRead` back without a conflict. That is how every field changed+ elsewhere behaves today, which is what the requirement asks for, but it+ means a stale editor can undo a promotion.+- **A pre-feature build** reads `toRead` as `reading`, may write it back on+ Save, lists the work on Today and refuses to export (Q9).+- **Two works for one serial.** A work made by hand under a title that differs+ from what the site's rules parse is not linked to the work a later capture+ creates. It is a Non-Goal, and the to-read work then never promotes.+- **The Works options menu** has no accessibility identifiers on its picker+ rows and two shared labels. The UI journeys now disambiguate by a uniquely+ labelled neighbour (Q29), which is a claim about menu order; a new picker value+ between a row and its neighbour would need the call site revisited.++---++## Completeness Assessment++### Fully implemented++| Requirement | Where |+|---|---|+| 1.1 name, glyph, hue, label, every surface | `WorkStatusPresentation.swift`; `WorkStatusPresentationTests`, `DuplicateSurfaceTests`, `WorksListOptionsTests`, `WorksListOptionsUITests`, `WorkDetailStatusUITests` |+| 1.2 first in order, no reconciliation precedence | `DomainEnums.swift`; `ModelContractTests`, `GroupOrderingTests` |+| 1.3 not done reading, no dialog, draft left alone | `isDone` unchanged; `WorkDetailModelTests`, `WorkDetailStatusUITests` |+| 1.4 settable on any work, every row | existing `updateWork`; `FanOutWriteTests` |+| 1.5 active row, no-entries placement | `WorksListOptionsTests`, `WorksListOptionsUITests` |+| 2.1, 2.2 creation | `NewWorkFormModel`, `createWork`; `RepositoryWorksTests`, `MoveToAndNewWorkModelTests`, `ModelContractTests` |+| 3.1 to 3.6 promotion and non-promotion | `promoteFromToRead` and its two call sites; `RepositoryCaptureTests`, `PendingCaptureDrainTests`, `RepositoryReShareTests`, `ComposedTeachingRepositoryTests` |+| 4.1 to 4.3 Today | existing predicate; `TodayDayPlanTests`, `WorkDetailModelTests` |+| 5.1 to 5.3 duplicates and merge | carry guard; `DuplicateScanTests`, `DuplicateReconcilerTests`, `WorkMergeRepositoryTests` |+| 6.1 archive round trip | `BackupV14ArchiveTests` |+| 6.2 nothing converted | no migration or data pass exists; the default does not move |++### Implemented with a recorded divergence++- **3.7**: met by last-writer-wins, not by a conflict result. The design and+ task 8 expected `.conflict`; Q27 records why that was wrong and+ `RepositoryWorksTests.aPromotionIsVisibleToAnOpenEditor` pins what is true.++### Verified by hand, not by automation++- **1.6, the Mac half**: five segments in the wide layout on a `Development`+ Mac build. iPhone at XXXL and both iPad layouts are automated. This is the+ owner's check (`prerequisites.md`).++### Missing++Nothing from the requirements. The share-sheet path is out of scope (T-2363).+Found while trying the feature and ticketed separately as T-2365: the New Work+form's hostname field rejects a pasted URL with an unreadable error.
toRead back without a conflict. Correct per the requirement's wording and Q27; confirm it is the behaviour you want.Development Mac build: no automation exists, and prerequisites.md leaves it to the owner.make test and make test-ui-ipad were last run before the review fixes; two cases in them fail at main's tip too and are recorded in docs/agent-notes/testing.md.toRead as reading, may write it back and refuses to export (Q9). Update every device.