rzen/lanework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Surface write failures — banners, locks, one modal

Browse Source 
The banner surface as one vocabulary (Kanban/LiveStore/BannerCenter,
Kanban/UI/BannerStripView): a pure precedence rule — in-progress pinned
above the collapse (ratified mid-build), lock > breakage > one-shot
write failures > commit+attachment, signposts last — with all
user-facing phrasing owned here via exhaustive switches over the closed
WriteOperation enum; free-form English survives only in diagnostics.
performWrite posts its failures before rethrowing, so no one-shot can
bypass the strip; refusals under lock post nothing.

The lock vocabulary completes: vanishedRoot and unwritableLocation join
bracketedReloadFailed, each with its own clearing rule (unwritable
clears only on a reconciling reload's writability re-probe). The
registry now owns root recovery: bookmark re-resolution absorbs renames
transparently, a dead root locks read-only and re-arms FSEvents on the
gone path so the root's return round-trips back through rootChanged,
re-minting and re-keying on the way. DirtyBufferGuard is the one modal
moment, retry / save a copy / discard, no fourth button.

36 new tests; full suite 333 tests in 62 suites green. Five findings
filed on the Redesign board.

Claude-Session: https://claude.ai/code/session_018BjQRYBR6jQja3jCRi5S3A
This commit is contained in:
rzen
2026-07-26 20:41:48 -04:00
parent dea77c3459
commit 747dea552d
10 changed files with 2343 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Kanban/LiveStore/BannerCenter.swift
+530
View File
@@ -0,0 +1,530 @@
import Foundation
import Observation
// MARK: - Tone
/// The three kinds a banner row can be (02-architecture.md § The banner surface, "Tones, not
/// components"): one layout, one accessibility path, three colorings. The card window's
/// remote-change signpost (07-sync-collab.md) is this same component in `.info` — visually calm,
/// no error color — which is precisely why the distinction is a *tone* on a shared row rather
/// than three view types that would drift apart.
public enum BannerTone: Sendable, Equatable {
case error
case warning
case info
}
// MARK: - Row payloads
/// A one-shot write failure: it happened once, it is over, and it waits to be read
/// (02-architecture.md § The banner surface, "One-shots dismiss, conditions heal").
///
/// **No timeout, ever** — "an error never evaporates unread". The row leaves the strip only when
/// the user dismisses it, which is why it carries an id of its own rather than being identified by
/// its content: two identical failures a minute apart are two rows, and dismissing one must not
/// take the other with it.
public struct OneShotBanner: Identifiable, Sendable, Equatable {
public let id: UUID
public let error: BoardWriteError
/// When the failure happened — the sort key for "newest first within a class".
public let occurredAt: Date
public init(id: UUID = UUID(), error: BoardWriteError, occurredAt: Date = Date()) {
self.id = id
self.error = error
self.occurredAt = occurredAt
}
}
/// The standing condition "changes aren't being recorded to history" (02-architecture.md §
/// Write-failure surfacing, "Auto-commit failures beyond `index.lock` contention").
///
/// `reason` is **diagnostic English, not the banner's verb** — the free-form tail the phrasing
/// rules allow ("disk full", "the repository is corrupt"). The user-facing sentence is
/// `BannerCenter.headline(for:)`'s, like every other row's.
///
/// `since` exists because this is a condition, not an event: it started at some point and has been
/// true ever since. Nothing renders it today; it is what a later "suspended for 4 minutes" reading
/// would be built from, and recording it costs a `Date`.
public struct HistorySuspension: Sendable, Equatable {
public let reason: String
public let since: Date
public init(reason: String, since: Date = Date()) {
self.reason = reason
self.since = since
}
}
/// A calm notice that something happened elsewhere — the info tone's *passive* half.
///
/// Its one producer-to-be is the card window's **remote-change signpost** (07-sync-collab.md): a
/// pull landed commits touching the very card being edited, the dirty buffer stays put and wins,
/// and the window says so without a modal or a merge UI. 02-architecture.md calls that "this same
/// component in the info tone", which is exactly what this is.
///
/// **Ranks last and may collapse** (settled, § The banner surface): "calm by design, nothing gated
/// on seeing them instantly" — the opposite end of the strip from an in-progress row, whose spinner
/// may never hide.
///
/// Dismissable, like a one-shot and unlike a condition: it reports something that already happened,
/// so there is nothing for it to heal into.
public struct InfoSignpost: Identifiable, Sendable, Equatable {
public let id: UUID
public let message: String
public let occurredAt: Date
public init(id: UUID = UUID(), message: String, occurredAt: Date = Date()) {
self.id = id
self.message = message
self.occurredAt = occurredAt
}
}
/// Work in flight, shown as an info row with a spinner (02-architecture.md § The banner surface,
/// "In-progress operations are info rows"): bracketed git operations ("Pulling…", "Switching to
/// 'main'…") and long non-git work (big-board Duplicate, template instantiation, large attachment
/// imports).
///
/// `label` is the caller's, deliberately: unlike a failure — whose vocabulary is the closed
/// `WriteOperation` enum precisely so the banner can own every word — an in-progress row names an
/// operation the banner layer has no enum for, and inventing one would mean a new git verb could
/// not describe itself without touching this file. The tradeoff is stated rather than hidden.
///
/// **Cancel appears on safe copies only** (settled): copy-shaped work — attachment imports,
/// Duplicate, template instantiation — carries `cancel`, meaning "remove the partial copy, nothing
/// lost". Git brackets pass `nil`: they are seconds long, and aborting a rebase mid-flight is a
/// repair job, not a cancel.
public struct InProgressOperation: Identifiable, Sendable {
public let id: UUID
public let label: String
public var isCancelable: Bool { cancel != nil }
/// `@MainActor @Sendable` rather than the plainer `@MainActor () -> Void` the sketch carried:
/// this value is stored in a `Sendable` struct, and a non-`Sendable` function type would make
/// that conformance a lie under strict concurrency. The isolation is unchanged — cancelling
/// runs on the main actor, where the operation's own state lives.
public let cancel: (@MainActor @Sendable () -> Void)?
public init(id: UUID = UUID(), label: String, cancel: (@MainActor @Sendable () -> Void)? = nil) {
self.id = id
self.label = label
self.cancel = cancel
}
}
// MARK: - Rows
/// One row in a window's banner strip.
///
/// The six cases are the whole vocabulary of 02-architecture.md § The banner surface, and they
/// divide into three lifecycles that the view renders differently and that the ordering rule
/// treats as classes:
///
/// - **Conditions heal**: `readOnlyLock`, `reloadBreakage`, `historySuspended`. They describe
/// ongoing state and carry no dismiss control — "an error never evaporates unread" has a twin,
/// "a condition is never dismissed while it is still true". Each leaves when the thing it
/// describes stops being true.
/// - **One-shots dismiss**: `oneShot` and `signpost`. Each reports something that already happened,
/// so only the user can clear it.
/// - **In-progress rows complete or fail**: `inProgress`. Completion clears the row; failure swaps
/// it for a one-shot (`BannerCenter.endOperation(_:)` + `post(_:)`).
///
/// **`Identifiable` by a synthetic string id**, not by content: the condition rows are singletons
/// per window (there is one lock, one breakage, one history suspension), so their ids are constant
/// and a changing *reason* updates the row rather than replacing it — no view churn, no lost
/// animation, and no diffing surprise when a lock's cause changes underneath a standing row.
public enum BannerRow: Identifiable, Sendable {
/// The board refuses writes. Condition, error tone. Producers: the failed bracketed reload
/// (built), the vanished root (this milestone), the open-time writability probe (m4).
case readOnlyLock(ReadOnlyLockReason)
/// A reload failed and the last good snapshot is still on screen. Condition, error tone.
case reloadBreakage(BoardLoadError)
/// A write that did not happen. Dismissable, error tone.
case oneShot(OneShotBanner)
/// History has stopped advancing. Condition, warning tone — the files are safe, only the undo
/// trail is degraded, which is a warning rather than an error. (m7's committer drives it.)
case historySuspended(HistorySuspension)
/// Work in flight. Info tone, spinner, **pinned above everything** and exempt from the collapse.
/// (m5's copy-shaped work and m7's git brackets drive it.)
case inProgress(InProgressOperation)
/// A calm notice — the passive half of the info tone, ranking last of all. (m6's card window
/// drives it, as 07-sync-collab.md's remote-change signpost.)
case signpost(InfoSignpost)
public var id: String {
switch self {
case .readOnlyLock: "read-only-lock"
case .reloadBreakage: "reload-breakage"
case let .oneShot(banner): "one-shot:\(banner.id.uuidString)"
case .historySuspended: "history-suspension"
case let .inProgress(operation): "operation:\(operation.id.uuidString)"
case let .signpost(signpost): "signpost:\(signpost.id.uuidString)"
}
}
public var tone: BannerTone {
switch self {
case .readOnlyLock, .reloadBreakage, .oneShot: .error
case .historySuspended: .warning
case .inProgress, .signpost: .info
}
}
/// Whether this row is pinned above the strip's collapse — true for in-progress rows and
/// nothing else (settled, 02-architecture.md § The banner surface: "a spinner may never hide
/// behind '+N more'"). The view reads this rather than re-deriving the case.
public var isPinned: Bool {
if case .inProgress = self { true } else { false }
}
/// The user-facing line. Every word of it comes from `BannerCenter`'s phrasing statics except
/// an in-progress row's, whose label is its caller's (see `InProgressOperation`).
public var headline: String {
switch self {
case let .readOnlyLock(reason): BannerCenter.headline(for: reason)
case let .reloadBreakage(error): BannerCenter.headline(for: error)
case let .oneShot(banner): BannerCenter.headline(for: banner.error)
case let .historySuspended(suspension): BannerCenter.headline(for: suspension)
case let .inProgress(operation): operation.label
case let .signpost(signpost): signpost.message
}
}
/// Only the rows reporting something that already happened carry a dismiss control — one-shot
/// failures and signposts. Conditions stand until they heal; in-progress rows complete, fail, or
/// are cancelled — neither is something a user can wave away.
public var dismissID: UUID? {
switch self {
case let .oneShot(banner): banner.id
case let .signpost(signpost): signpost.id
case .readOnlyLock, .reloadBreakage, .historySuspended, .inProgress: nil
}
}
}
// MARK: - BannerCenter
/// The model behind one window's banner strip: the rows a window owns outright, plus the ordering
/// and phrasing rules the whole app renders through (02-architecture.md § The banner surface).
///
/// ### What lives here and what does not
///
/// A center holds the state nothing else does: dismissable one-shot write failures, the history
/// suspension, in-progress operations, and passive signposts. It deliberately does **not** hold the
/// read-only lock or the reload breakage — those are `BoardStore`'s truths, and copying them here
/// would create a second place for them to be stale. `BoardStore.bannerRows` composes both halves
/// through `rows(lock:breakage:oneShots:suspension:operations:signposts:)`, which is a *pure
/// function* precisely so the precedence rule can be tested without a store, a window, or a
/// filesystem.
///
/// ### Phrasing lives here too
///
/// "The banner owns all user-facing phrasing and localization from that vocabulary" (02 §
/// Write-failure surfacing). `BoardWriteError` carries a closed `WriteOperation` enum and a
/// diagnostic `reason`; `headline(for:)` switches over that enum **exhaustively, with no
/// `default`**, so a Writer operation added without a sentence to say about it is a compile-time
/// hole rather than a silent fallback. The same rule covers locks, breakage, and the history
/// suspension: their user-facing lines are here, not on the error types.
///
/// ### One center per window, not per board
///
/// The strip is "hosted by the window of origin": a card window's own save and attachment failures
/// belong to that window's center, and re-home to the board window's when it closes (m6's job).
/// `BoardStore` owns *the board window's* center, which is why it is a stored `let` there rather
/// than something injected — a board window's strip has exactly one lifetime, the store's.
@MainActor
@Observable
public final class BannerCenter {
// MARK: State
/// Newest first, which is the order the class renders in. Kept sorted on insertion rather than
/// at render time so that two failures sharing a timestamp — plausible inside one run loop
/// turn — still order deterministically.
public private(set) var oneShots: [OneShotBanner] = []
/// The standing "history isn't advancing" condition, or `nil` when commits are landing.
public private(set) var historySuspension: HistorySuspension?
/// Work in flight, newest first for the same reason `oneShots` is.
public private(set) var operations: [InProgressOperation] = []
/// Passive notices, newest first. Empty until m6's card window starts posting the
/// remote-change signpost.
public private(set) var signposts: [InfoSignpost] = []
public init() {}
// MARK: One-shots
/// Records a write failure. **Every failed write lands here before it reaches its caller** —
/// `BoardStore.performWrite` posts before it rethrows — because the banner is how the one-way
/// flow stays honest: the action visibly did not happen, and the strip is the only place that
/// says why (02 § Write-failure surfacing).
public func post(_ error: BoardWriteError) {
oneShots.insert(OneShotBanner(error: error), at: 0)
}
/// Posts a passive notice — m6's remote-change signpost and whatever joins it. Newest first,
/// like the one-shots it shares a lifecycle with.
public func postSignpost(_ message: String) {
signposts.insert(InfoSignpost(message: message), at: 0)
}
/// Removes a dismissable row: a one-shot failure or a signpost. **An id that names an
/// in-progress operation is ignored** rather than ending it, because "dismiss" and "cancel" are
/// different promises and a row that offers one must never quietly do the other.
public func dismiss(_ id: UUID) {
oneShots.removeAll { $0.id == id }
signposts.removeAll { $0.id == id }
}
/// Removes every dismissable row — one-shots and signposts alike. The strip's own "clear all"
/// affordance later; today it is what a window uses when it re-homes its rows elsewhere (m6).
public func dismissAllDismissableRows() {
oneShots.removeAll()
signposts.removeAll()
}
// MARK: History suspension
/// Raises (or refreshes) the "changes aren't being recorded to history" condition — m7's
/// committer calls this when a commit fails past `index.lock` contention (06-history-undo.md
/// covers the lock itself, which is deliberately *not* a banner).
///
/// A second call while already suspended keeps the original `since` and takes the newer
/// `reason`: the condition never stopped being true, so restarting its clock would misreport
/// how long history has been stalled, while the newest diagnosis is the useful one.
public func suspendHistory(reason: String) {
historySuspension = HistorySuspension(reason: reason, since: historySuspension?.since ?? Date())
}
/// Clears it, on the first successful commit. Idempotent — clearing a condition that is not
/// standing is not an error, it is the ordinary shape of "commit succeeded".
public func clearHistorySuspension() {
historySuspension = nil
}
// MARK: In-progress operations
/// Starts an info row with a spinner and hands back its id.
///
/// - Parameter cancel: non-`nil` only for copy-shaped work, where cancelling means "remove the
/// partial copy, nothing lost" (02, settled). Git brackets pass `nil`.
@discardableResult
public func beginOperation(label: String, cancel: (@MainActor @Sendable () -> Void)? = nil) -> UUID {
let operation = InProgressOperation(label: label, cancel: cancel)
operations.insert(operation, at: 0)
return operation.id
}
/// Ends one — the row leaves the strip.
///
/// **Completion and failure both come through here.** There is no `failOperation`: a failure is
/// `endOperation(id)` followed by `post(error)`, which is exactly 02's "failure swaps it for
/// the error row" expressed as two calls that already exist. Ending an unknown id is a no-op;
/// a close racing a completion is ordinary, not a bug.
public func endOperation(_ id: UUID) {
operations.removeAll { $0.id == id }
}
// MARK: - Ordering
/// The strip's rows, precedence-ordered — **the whole of the ordering rule, in one pure
/// function** (02 § The banner surface, "Concurrent conditions stack").
///
/// The precedence, settled: **in-progress rows (pinned)** > read-only lock > reload breakage >
/// one-shot write failures > commit and attachment failures > **passive info rows**. Three
/// readings of it are worth stating because the code depends on them:
///
/// - **The two info classes sit at opposite ends of the strip.** An in-progress row is pinned
/// above everything: it is the only explanation the strip offers for a bracket's write lock
/// and for a close or quit deferring teardown, and a copy row's Cancel has to stay reachable
/// — "a spinner may never hide behind '+N more'". A passive signpost ranks last and may
/// collapse: calm by design, nothing gated on seeing it instantly. Same tone, opposite
/// urgency.
/// - **An attachment failure is a one-shot**, not a separate kind — its `WriteOperation` is
/// `.importAttachment`. It ranks in the commit-failure class rather than with its fellow
/// one-shots, so a fresh failed import sits below an older failed move. That is the design's
/// ordering read literally, and it is defensible: a failed import is the least destructive of
/// the failures (the drop was accepted, the partial copy was removed), so it yields its place
/// to failures that stopped the user's actual work.
/// - **Within the commit-and-attachment class the standing suspension leads**, then the
/// attachment one-shots newest first. A deliberate reading of "newest first within a class":
/// a condition and a one-shot are not comparable by recency in any way a user would read as
/// order — the condition's `since` is when it *started* being true, not when it happened —
/// so they are ordered by kind, and recency orders only the one-shots among themselves.
///
/// `signposts` carries a default because its producer is m6's card window and nothing posts one
/// today; every other class has a live producer and is spelled out at every call site.
public nonisolated static func rows(
lock: ReadOnlyLockReason?,
breakage: BoardLoadError?,
oneShots: [OneShotBanner],
suspension: HistorySuspension?,
operations: [InProgressOperation],
signposts: [InfoSignpost] = []
) -> [BannerRow] {
var rows: [BannerRow] = []
rows.append(contentsOf: operations.map(BannerRow.inProgress))
if let lock {
rows.append(.readOnlyLock(lock))
}
if let breakage {
rows.append(.reloadBreakage(breakage))
}
let ordered = newestFirst(oneShots)
rows.append(contentsOf: ordered.lazy.filter { !$0.isAttachmentImport }.map(BannerRow.oneShot))
if let suspension {
rows.append(.historySuspended(suspension))
}
rows.append(contentsOf: ordered.lazy.filter(\.isAttachmentImport).map(BannerRow.oneShot))
rows.append(contentsOf: signposts.map(BannerRow.signpost))
return rows
}
/// Newest first, and **stable**: `sorted(by:)` is not, and two failures posted in the same run
/// loop turn can share a `Date` to the microsecond. Ties fall back to the input order, which
/// `post(_:)` already maintains newest-first — so a tie renders in the order it was posted
/// rather than in whatever order the sort happened to leave.
private nonisolated static func newestFirst(_ banners: [OneShotBanner]) -> [OneShotBanner] {
banners
.enumerated()
.sorted { lhs, rhs in
lhs.element.occurredAt == rhs.element.occurredAt
? lhs.offset < rhs.offset
: lhs.element.occurredAt > rhs.element.occurredAt
}
.map(\.element)
}
// MARK: - Phrasing
/// The user-facing line for a failed write: what the app could not do, then why.
///
/// "Couldn't move 'Fix login' — disk full" is the design's own example and the shape every
/// case takes: an action clause the banner owns, an em dash, and the diagnostic cause from the
/// error's `reason` — the one place free-form English is allowed to survive.
public nonisolated static func headline(for error: BoardWriteError) -> String {
let action = actionPhrase(for: error.operation)
let cause = causePhrase(for: error.reason)
return cause.isEmpty ? action : "\(action) — \(cause)"
}
/// **Exhaustive by construction — no `default`.** A `WriteOperation` case added without a
/// sentence here fails to compile, which is the settled contract ("a new Writer operation
/// without a banner rendering is a compile-time hole, not a silent default").
///
/// Titles are quoted where the operation carries one and the phrasing stays graceful where it
/// does not: the enum knows an item's title, never its *kind*, so an untitled failure says
/// "the item" rather than guessing "card" and being wrong about a lane. The trash verbs are
/// Finder's, matching the commands the user pressed (03-board-ui.md § Trash): Move to Trash,
/// Put Back, Delete Immediately.
private nonisolated static func actionPhrase(for operation: WriteOperation) -> String {
switch operation {
case .createBoard:
"Couldn't create the board"
case .createLane:
"Couldn't create a lane"
case .createCard:
"Couldn't create a card"
case let .move(title):
if let title { "Couldn't move '\(title)'" } else { "Couldn't move the item" }
case let .reorder(title):
if let title { "Couldn't reorder '\(title)'" } else { "Couldn't reorder the item" }
case let .copy(title):
if let title { "Couldn't copy '\(title)'" } else { "Couldn't copy the item" }
case let .delete(title):
if let title { "Couldn't move '\(title)' to the trash" } else { "Couldn't move the item to the trash" }
case let .restore(title):
if let title { "Couldn't put '\(title)' back" } else { "Couldn't put the item back" }
case let .purge(title):
if let title { "Couldn't permanently delete '\(title)'" } else { "Couldn't permanently delete the item" }
case let .style(title):
if let title { "Couldn't restyle '\(title)'" } else { "Couldn't restyle the item" }
case let .importAttachment(filename):
"Couldn't import '\(filename)'"
case .listAttachments:
"Couldn't read this card's attachments"
case .renumberChildren:
"Couldn't renumber cards"
}
}
/// The cause tail. `reason`'s own English is diagnostic and already reads as a phrase ("disk
/// full", "no such file or directory"); the uneditable-frontmatter case is the one that needs
/// translating, because its `description` is a fragment written for a developer.
private nonisolated static func causePhrase(for reason: BoardWriteError.Reason) -> String {
let text = switch reason {
case let .unreadable(message):
message
case let .uneditableFrontmatter(shape):
"this file's frontmatter can't be edited in place (\(shape.description))"
case let .io(message):
message
}
return trimmed(text)
}
/// The read-only lock's line. Each cause says the same two things — what is wrong, and that
/// what is on screen is still the last good view — because the lock's whole promise is that
/// nothing was lost: reading, selecting, searching and copying out all stay live (02 § "The
/// lock's scope").
public nonisolated static func headline(for lock: ReadOnlyLockReason) -> String {
switch lock {
case .bracketedReloadFailed:
"This board couldn't be re-read after the last operation — showing the last good view, read-only"
case .vanishedRoot:
"This board's folder is gone — showing the last good view, read-only"
case .unwritableLocation:
"This board's location can't be written to — showing the last good view, read-only"
}
}
/// Reload breakage: fail-fast's specifics (the offending path and what is wrong with it), plus
/// the reassurance that the board is still the board.
///
/// The path is root-relative as `BoardLoadError` reports it, and `"."` — the root's own
/// `index.md` — is spelled as "This board" rather than shown as a lone dot.
public nonisolated static func headline(for breakage: BoardLoadError) -> String {
let reason = trimmed(breakage.reason.description)
let subject = breakage.path == "." || breakage.path.isEmpty
? "This board isn't loading"
: "'\(breakage.path)' isn't loading"
return "\(subject): \(reason) — showing the last good view"
}
/// The suspended-history line. It names the *consequence* the user cares about — undo and the
/// flush-before-overwrite guarantee are degraded — rather than the git mechanics, and carries
/// the diagnosis as its tail.
public nonisolated static func headline(for suspension: HistorySuspension) -> String {
let reason = trimmed(suspension.reason)
let line = "Changes aren't being recorded to history"
return reason.isEmpty ? line : "\(line) — \(reason)"
}
/// Trims whitespace and a trailing period: these fragments are tails inside a longer line, and
/// a stray full stop mid-sentence is the tell of machine-assembled text.
private nonisolated static func trimmed(_ text: String) -> String {
var value = text.trimmingCharacters(in: .whitespacesAndNewlines)
while value.hasSuffix(".") {
value.removeLast()
}
return value
}
}
// MARK: - Helpers
private extension OneShotBanner {
/// Whether this failure is an attachment import — the one `WriteOperation` whose one-shot
/// ranks in the last precedence class rather than with the other one-shots.
var isAttachmentImport: Bool {
if case .importAttachment = error.operation { true } else { false }
}
}
Kanban/LiveStore/BoardStore.swift
+228 -32
View File
@@ -4,21 +4,47 @@ import os
// MARK: - Vocabulary
/// Why a board is refusing writes — the read-only lock's cause, and the whole of its vocabulary
/// today.
/// Why a board is refusing writes — the read-only lock's cause, and now the whole of the
/// vocabulary 02-architecture.md names.
///
/// 02-architecture.md names three ways a board enters the lock and only the first is built here.
/// `vanishedRoot` (§ Write-failure surfacing — a root that is gone, after bookmark re-resolution
/// found nothing) and `unwritableLocation` (§ — a read-only volume or a permission-denied folder,
/// probed at open) arrive with the cards that implement them. The banner turns a case of this into
/// user-facing phrasing (§ The banner surface); the store only owns the truth of it.
/// The three cases share one *scope* (§ "The lock's scope") — every mutating command disabled
/// across every window sharing the store, drops refused, ⌘-drag moves degraded to copies, editor
/// buffers kept but their debounced saves suspended — and differ only in cause and in **what
/// clears them**, which is the one thing this enum's cases are actually asked about (see
/// `BoardStore.land(_:generation:origin:)`). The banner turns a case of this into user-facing
/// phrasing (§ The banner surface); the store only owns the truth of it.
public enum ReadOnlyLockReason: Sendable, Equatable {
/// A reload that followed a bracketed wholesale operation failed, so the last-good snapshot on
/// screen may describe a tree that no longer exists — after a branch switch, a different branch
/// entirely. Writes derived from it would land nonsense, so every write is refused until a
/// reload succeeds (02-architecture.md § Live-reload resilience, "A failed reload after a
/// bracketed operation locks the board read-only").
///
/// **Clears on the next successful reload, whatever its origin** — typically once the offending
/// file is fixed.
case bracketedReloadFailed
/// The board's root is gone and its bookmark re-resolution found nothing: the volume unmounted,
/// or the folder was deleted in Finder while the board was open (02-architecture.md §
/// Write-failure surfacing, "A vanished board root locks the board read-only"). Every write
/// would land nowhere, so the last-good snapshot stays on screen, read-only.
///
/// **Clears on the next successful reload, whatever its origin**: a reload can only succeed if
/// the root is back, so success *is* the return signal. Pending dirty buffers then save
/// normally.
case vanishedRoot
/// The board opened somewhere it cannot be written: a read-only volume (a DMG, a snapshot, a
/// read-only share) or a permission-denied folder (02-architecture.md § Write-failure
/// surfacing, "An unwritable board location enters the read-only lock at open"). Failing
/// loudly, specifically, *once* beats letting every gesture fail one at a time.
///
/// **Clears only on a successful *reconciling* reload whose writability re-probe passes** —
/// unlike its two siblings, whose cause a successful reload disproves by itself. A board on a
/// read-only DMG reloads perfectly all day long; only the probe (§ "Writability re-probes on
/// every reconciling reload" — wake, activation) can tell that the permission or the mount
/// actually changed.
case unwritableLocation
}
/// The refusal `BoardStore.performWrite` throws when the board is locked read-only.
@@ -185,11 +211,50 @@ public final class BoardStore {
/// The board's selection, re-resolved against every snapshot this store applies.
public private(set) var selection: Selection
/// The board root this store was opened on. Constant for now: absorbing a rename by
/// re-resolving the security-scoped bookmark (02-architecture.md § Write-failure surfacing) is
/// the registry's job and a later card's, and it will arrive together with `.rootChanged`
/// handling.
public let rootURL: URL
/// Where the board is **now**. Follows the folder: a rename or a move absorbed through
/// `relocate(to:)` updates it, so every URL derived from it — the Writer's paths, card-window
/// keys, Reveal in Finder — re-derives at the new location (02-architecture.md §
/// Write-failure surfacing, "A renamed or moved board root follows its file identity").
///
/// Observed, deliberately: the window title's folder-name fallback reads this, and a rename in
/// Finder should be visible in the title bar without anything else being told.
///
/// `snapshot.rootURL` is the root the *last successful reload* walked, and therefore lags this
/// by exactly one reload during an absorption. That is not a second source of truth: the
/// relocation is always followed by the watcher reattach whose reconciling reload rebuilds the
/// snapshot at the new root, after which the two agree again.
public private(set) var rootURL: URL
// MARK: Banners
/// The board window's banner strip, as a model (02-architecture.md § The banner surface).
///
/// **Owned, not injected**, and the reason is the hosting rule: the strip is "hosted by the
/// window of origin", and a board window's strip has exactly one lifetime — this store's. A
/// card window (m6) gets its *own* center for its own save, attachment, and raw-source Apply
/// failures, and re-homes those rows here when it closes; injecting a shared center would
/// erase precisely that distinction.
///
/// It holds only what nothing else does — one-shot write failures, the history suspension,
/// in-progress operations, passive signposts. The lock and the reload breakage stay this
/// store's own state and are composed in at render time by `bannerRows`.
public let banners = BannerCenter()
/// The rows the board window's strip renders, in precedence order.
///
/// Composed rather than stored: `readOnlyLock` and `reloadFailure` are the store's truths and
/// `banners` holds the rest, so a stored array would be a third copy waiting to go stale. The
/// ordering rule itself lives in `BannerCenter.rows(...)`, which is pure and tested on its own.
public var bannerRows: [BannerRow] {
BannerCenter.rows(
lock: readOnlyLock,
breakage: reloadFailure,
oneShots: banners.oneShots,
suspension: banners.historySuspension,
operations: banners.operations,
signposts: banners.signposts
)
}
// MARK: Wiring
@@ -200,6 +265,18 @@ public final class BoardStore {
@ObservationIgnored
public var watcherBrackets: (begin: @MainActor () -> Void, end: @MainActor () -> Void)?
/// What to do when the watched root changes identity — injected for the same reason the
/// brackets are: the response needs the board's **security-scoped bookmark**, and this store
/// does not own one (the registry does, along with the watcher that must be re-attached and the
/// last-known path that arms the return detection). A store that reached for a bookmark it did
/// not hold could not be built or tested without a registry.
///
/// `nil` keeps the documented no-op: the last-good snapshot stays on screen, which is what
/// every other failure path here does, and which is exactly the shape unit tests and any
/// storeless use want. `BoardStoreRegistry` wires it to its own recovery loop.
@ObservationIgnored
public var rootChangeDelegate: (@MainActor () -> Void)?
// MARK: Reload machinery
/// Monotonic id of the most recently *started* reload — and therefore also the number of tree
@@ -295,16 +372,22 @@ public final class BoardStore {
requestReload(origin)
case .rootChanged:
// Stubbed on purpose, and the stub is the whole of the honest answer today: the settled
// response is to re-resolve the board's security-scoped bookmark and either
// `reattach(to:)` the watcher at the new location — a rename absorbed with no banner and
// no lock — or enter the vanished-root read-only lock (02-architecture.md §
// Write-failure surfacing). Both halves need the registry's bookmark, which this store
// deliberately does not own yet, and a guess here would be a *wrong* guess: treating a
// rename as a vanish would lock a board that is merely somewhere else. The card that
// brings the bookmark replaces this case; until then a root change simply leaves the
// last-good snapshot on screen, which is the same thing every failure path does.
Self.logger.debug("rootChanged ignored — bookmark re-resolution is not built yet")
// Delegated, never guessed at. The settled response is to re-resolve the board's
// security-scoped bookmark and either `reattach(to:)` the watcher at the new location —
// a rename absorbed with no banner and no lock — or enter the vanished-root read-only
// lock (02-architecture.md § Write-failure surfacing). Both halves need a bookmark this
// store does not own, and a guess here would be a *wrong* guess: treating a rename as a
// vanish would lock a board that is merely somewhere else.
//
// No reload is started either way. The delegate's two outcomes both end in one —
// `reattach(to:)`'s reconciling reload at the re-resolved root, or the vanished-root
// lock's eventual clearance when the root returns — and a reload fired from here would
// walk a path that just stopped being the board.
guard let rootChangeDelegate else {
Self.logger.debug("rootChanged ignored — no delegate is wired (storeless use)")
return
}
rootChangeDelegate()
}
}
@@ -350,26 +433,26 @@ public final class BoardStore {
outcome = .failure(error)
}
await barrier?()
await self?.apply(outcome, generation: generation)
await self?.apply(outcome, generation: generation, origin: origin)
}
}
/// Lands one walk's result and starts whatever it uncovered.
private func apply(_ outcome: Result<LoadResult, BoardLoadError>, generation: Int) {
private func apply(_ outcome: Result<LoadResult, BoardLoadError>, generation: Int, origin: WatchOrigin) {
reloadInFlight = false
// The stale-apply guard. Serialization means this should not trigger today, but "only the
// newest result applies" is the rule the wholesale floor and every future overlapping-load
// change are written against, so it is enforced rather than assumed.
if generation == reloadGeneration {
land(outcome, generation: generation)
land(outcome, generation: generation, origin: origin)
}
startPendingReload()
resumeQuiescenceWaitersIfQuiet()
}
private func land(_ outcome: Result<LoadResult, BoardLoadError>, generation: Int) {
private func land(_ outcome: Result<LoadResult, BoardLoadError>, generation: Int, origin: WatchOrigin) {
// Consumed here, before the branch, because *both* outcomes end the expectation: a wholesale
// operation gets exactly one reload to prove itself, and a second failure after it is
// ordinary per-file breakage again.
@@ -385,10 +468,10 @@ public final class BoardStore {
case let .success(result):
snapshot = result.model
loadWarnings = result.warnings
// One success clears both conditions — transient breakage self-heals and a locked board
// unlocks without the user doing anything but fixing the file.
// Breakage always heals on a success — it *is* the claim "the last reload failed", and
// this one did not.
reloadFailure = nil
readOnlyLock = nil
clearLockIfDisproved(by: origin)
selection = selection.resolved(against: result.model)
case let .failure(error):
@@ -396,7 +479,13 @@ public final class BoardStore {
// replaces a good snapshot, and a selection over a snapshot that did not change has
// nothing to re-resolve against.
reloadFailure = error
if endsWholesaleOperation {
// `readOnlyLock == nil` rather than an unconditional assignment: a root that vanished
// mid-bracket already raised its own, truer lock, and 02-architecture.md is explicit
// that the bracket's final reload becomes a no-op there rather than a redundant
// failure. Overwriting `.vanishedRoot` with `.bracketedReloadFailed` would also break
// the clearing rules — the vanished root's lock must not clear on a reload that never
// proves the root came back.
if endsWholesaleOperation, readOnlyLock == nil {
readOnlyLock = .bracketedReloadFailed
}
Self.logger.error("reload \(generation, privacy: .public) failed: \(error.description, privacy: .public)")
@@ -409,6 +498,88 @@ public final class BoardStore {
startReload(origin)
}
// MARK: - The lock's clearing rules
/// Clears the read-only lock if this successful reload actually disproved its cause.
///
/// **Reason-specific, because the causes are not alike** (02-architecture.md § Write-failure
/// surfacing):
///
/// - `.bracketedReloadFailed` and `.vanishedRoot` are *disproved by the success itself*. The
/// first says "the tree could not be re-read after a wholesale change" and the second says
/// "the root is gone" — a completed tree walk at the root contradicts both, whatever origin
/// asked for it, so any success clears them.
/// - `.unwritableLocation` is not. A board on a read-only DMG reloads flawlessly forever;
/// loading proves nothing about writing. It clears only when a **reconciling** reload — wake,
/// activation, a stream re-creation — re-probes writability and finds it changed ("Writability
/// re-probes on every reconciling reload, so a fixed permission or rewritable remount clears
/// the lock without ceremony").
///
/// `FileManager.isWritableFile(atPath:)` is `access(2)` on the root directory: a real-uid
/// permission question asked of the filesystem, which is what makes it answer correctly for
/// both halves of the case — a read-only *mount* and a permission-denied *folder*.
///
/// Deliberately **one-way**: a reconciling reload that finds the root unwritable does not
/// *raise* the lock. Arming it is the open flow's job (`enterUnwritableLock()`), and inferring
/// a lock from a probe here would be a policy decision this milestone was not asked to make.
private func clearLockIfDisproved(by origin: WatchOrigin) {
switch readOnlyLock {
case nil:
break
case .bracketedReloadFailed, .vanishedRoot:
readOnlyLock = nil
case .unwritableLocation:
guard origin == .reconciling, FileManager.default.isWritableFile(atPath: rootURL.path) else { return }
Self.logger.debug("writability re-probe passed — the unwritable-location lock clears")
readOnlyLock = nil
}
}
// MARK: - Root identity and explicit locks
/// Points this store at the board's new location, absorbing a rename or a move.
///
/// Called by the registry when a `.rootChanged` re-resolved the board's bookmark somewhere else
/// (02-architecture.md § Write-failure surfacing, "A renamed or moved board root follows its
/// file identity"): the board the app has open is the *file*, not the path string, so this is
/// bookkeeping rather than an event — **no banner, no lock, nothing was ever wrong**.
///
/// It deliberately starts **no reload**. The caller follows this with the watcher's
/// `reattach(to:)`, whose reconciling reload is the one that rebuilds the snapshot at the new
/// root; a reload fired from here would be a second walk racing that one for no gain. Until it
/// lands, `rootURL` is the new location and `snapshot.rootURL` is still the old — see
/// `rootURL`'s note.
public func relocate(to newRoot: URL) {
guard newRoot != rootURL else { return }
Self.logger.debug("board root relocated; Writer URLs now derive from the new location")
rootURL = newRoot
}
/// Raises the vanished-root read-only lock — the registry's call, after bookmark re-resolution
/// found nothing and the last-known path is not there either.
///
/// Overwrites whatever lock was standing: a root that is gone is the most current and most
/// specific truth about why writes are refused, and its clearing rule (a successful reload,
/// which can only happen if the root came back) is strictly the safer one to be holding.
public func enterVanishedRootLock() {
Self.logger.error("board root vanished — entering the read-only lock")
readOnlyLock = .vanishedRoot
}
/// Raises the unwritable-location read-only lock — the open flow's call, after probing the
/// root's writability (02 § "An unwritable board location enters the read-only lock at open").
/// Public now so the vocabulary and its clearing rule ship together; m4's open flow is the
/// producer.
///
/// Does **not** overwrite a standing lock: a board that is already locked for a vanished root
/// or a failed bracketed reload has a cause that outranks "and it is also read-only", and both
/// of those clear on a success that would then re-probe anyway.
public func enterUnwritableLock() {
guard readOnlyLock == nil else { return }
Self.logger.error("board location is not writable — entering the read-only lock")
readOnlyLock = .unwritableLocation
}
// MARK: - Write gate
/// Runs a synchronous Writer operation inside the watcher bracket, so the churn it produces
@@ -418,6 +589,13 @@ public final class BoardStore {
/// disk; the watcher notices; the reload applies. That indirection is the one-way flow, and it is
/// why this method's only jobs are the gate and the bracket.
///
/// **A failure posts to the banner before it is rethrown** (02-architecture.md § Write-failure
/// surfacing): the strip is how the one-way flow keeps its honesty — the action visibly did not
/// happen, and the banner is the only thing that says why — so no call site is trusted to
/// remember, and a `try?` at some future call site cannot make a failure silent. The refusal
/// below is deliberately *not* posted: the lock row is already standing, and a second row per
/// refused gesture would bury it under echoes of itself.
///
/// - Throws: `BoardStoreWriteRefusal.readOnlyLocked` if the board is locked read-only — checked
/// *before* the bracket opens, so a refusal costs no suspended watcher and no owed reload.
/// Otherwise rethrows whatever `operation` threw, which is a `BoardWriteError`. The untyped
@@ -438,7 +616,14 @@ public final class BoardStore {
// `defer`, not a trailing call: a Writer operation that fails partway has still touched disk,
// and an unbalanced bracket would leave the watcher suspended for the rest of the session.
defer { watcherBrackets?.end() }
return try operation()
// `do throws(BoardWriteError)`: without the annotation the `catch` widens to `any Error` and
// the Writer's typed error is lost on the way to the banner.
do throws(BoardWriteError) {
return try operation()
} catch {
banners.post(error)
throw error
}
}
/// Runs an operation that rewrites the tree **wholesale** — pull-rebase, branch switch, undo
@@ -474,7 +659,18 @@ public final class BoardStore {
wholesaleReloadFloor = reloadGeneration + 1
watcherBrackets?.end()
}
try operation()
do {
try operation()
} catch let error as BoardWriteError {
// Same honesty rule as `performWrite`, applied to the one error type the banner has
// phrasing for. A wholesale operation is usually git's (m7), whose own failure
// vocabulary is not `BoardWriteError` and whose surfacing — the suspended-history
// condition, the in-progress row swapping for an error — is the committer's to drive;
// but a `BoardWriteError` escaping here is an ordinary failed write and may no more
// bypass the strip than one from `performWrite`.
banners.post(error)
throw error
}
}
// MARK: - Selection
Kanban/LiveStore/BoardStoreRegistry.swift
+152 -11
View File
@@ -78,12 +78,28 @@ struct FileIdentity: Hashable {
@MainActor
public final class BoardStoreRegistry {
/// One open board: the shared store, the watcher feeding it, and how many windows are holding
/// them open.
/// One open board: the shared store, the watcher feeding it, how many windows are holding them
/// open — and the two facts the root-recovery loop needs.
private struct Entry {
let store: BoardStore
let watcher: FolderWatcher
var referenceCount: Int
/// The board's **identity**, minted at acquire (02-architecture.md § Write-failure
/// surfacing: "the registry's security-scoped bookmark is the identity, mid-session as much
/// as across opens"). Re-minted on every absorbed rename, so it always names the folder
/// where the board is now rather than where it was opened.
///
/// Optional because bookmark creation can fail outright — vanishingly unlikely for a folder
/// just walked, and survivable: a board with no bookmark simply falls through to the
/// path-reappearance half of the recovery loop, which is the same path a *dead* bookmark
/// takes.
var bookmark: Data?
/// Where the board was last known to live. The vanished-root case re-attaches the watcher
/// here — FSEvents is content to watch a path that does not exist and reports its
/// *creation* as a root change, which is exactly the return detection the lock needs.
var lastKnownRoot: URL
}
/// Keyed by `FileIdentity`, so a board acquired through a renamed or moved path finds the entry
@@ -143,19 +159,32 @@ public final class BoardStoreRegistry {
// become no-ops the moment `release` drops the watcher. Neither closure can form a cycle
// with the object it calls into.
let watcher = FolderWatcher(root: rootURL) { [weak store] event in
// `.rootChanged` rides through like any other event. The store stubs it today; the
// settled response — re-resolve the board's security-scoped bookmark and either
// `reattach(to:)` at the new location or enter the vanished-root read-only lock
// (02-architecture.md § Write-failure surfacing) — needs `BoardRegistry`'s bookmark and
// belongs to the card that brings the two together. This registry is the natural place
// for that seam, since it is the only object holding the store, the watcher, and (by
// then) the record at once.
// `.rootChanged` rides through like any other event; the store hands it straight back
// here through `rootChangeDelegate`, below.
store?.handleWatcherEvent(event)
}
store.watcherBrackets = (
begin: { [weak watcher] in watcher?.beginBracket() },
end: { [weak watcher] in watcher?.endBracket() }
)
// The recovery loop's entry point. It captures the **store**, not the entry's key: an
// absorbed rename can re-key the entry (a delete-and-recreate at the same path changes file
// identity), and a closure holding a stale key would quietly stop finding its own board on
// the second root change. Object identity cannot go stale.
store.rootChangeDelegate = { [weak self, weak store] in
guard let self, let store else { return }
recoverFromRootChange(of: store)
}
// The bookmark is minted here — at acquire, once — because that is the moment the app
// demonstrably has access to this folder (it just walked it). A bookmark minted later,
// after the root has already gone missing, would be exactly the one that cannot be made.
let bookmark = BoardRegistry.makeBookmark(for: rootURL)?.data
if bookmark == nil {
// Not a failure to open: the board loads, renders, and writes. Only the *rename*
// half of root recovery is lost, and the path-reappearance half still works.
Self.logger.error("no bookmark could be minted for this board; a mid-session move will not be absorbed")
}
// Default debounce and latency: the numbers are settled in 02-architecture.md § Components
// (200 ms trailing over 50 ms FSEvents latency) and live in `FolderWatcher`'s defaults.
@@ -168,7 +197,13 @@ public final class BoardStoreRegistry {
Self.logger.error("watcher stream failed to start; live reload is degraded for this board")
}
entries[identity] = Entry(store: store, watcher: watcher, referenceCount: 1)
entries[identity] = Entry(
store: store,
watcher: watcher,
referenceCount: 1,
bookmark: bookmark,
lastKnownRoot: rootURL
)
return store
}
@@ -199,11 +234,117 @@ public final class BoardStoreRegistry {
entry.watcher.stop()
// Explicit rather than left to the weak captures: after this the store may still be alive in
// whatever is closing, and brackets that quietly did nothing would be a lie about a watcher
// that is gone.
// that is gone. The root-change delegate goes for the same reason — a released store has no
// entry to recover, and leaving the closure attached would invite it to look for one.
entry.store.watcherBrackets = nil
entry.store.rootChangeDelegate = nil
entries[identity] = nil
}
// MARK: - Root recovery
/// The whole response to a root-gone signal, in the one object that can give it: the store to
/// relocate or lock, the watcher to re-attach, and the bookmark that decides which
/// (02-architecture.md § Write-failure surfacing, "A renamed or moved board root follows its
/// file identity" and "A vanished board root locks the board read-only").
///
/// ### Three outcomes, tried in order
///
/// 1. **The bookmark resolves to a folder that is really there** — a rename or a move on the
/// same volume. Absorbed transparently: relocate, re-attach, re-mint. **No banner, no lock,
/// nothing was ever wrong.**
/// 2. **The bookmark is dead, but the last-known path exists again** — a Finder undo, a
/// remount, a folder recreated where the board used to be, arriving as the *creation* of a
/// watched path. Treated as the root returning: the bookmark is re-minted from the path and
/// the same absorption runs, and the reconciling reload's success is what clears the
/// vanished-root lock through the store's own rule.
/// 3. **Neither** — the root is truly vanished. The lock goes up and the watcher re-attaches at
/// the last-known path anyway: FSEvents happily watches a path that does not exist and
/// reports its creation as another `.rootChanged` (pinned in `FolderWatcherTests`), which is
/// what arms outcome 2 for later. The re-attach's reconciling reload fails against the
/// missing root, which is correct and harmless — a failed reload never replaces a good
/// snapshot, and the lock is already standing.
///
/// ### Why outcome 1 checks the filesystem
///
/// Bookmark resolution is not a liveness test. `BoardRegistryTests` says as much where it
/// refuses to build a dead-bookmark case by deleting a folder ("'ought to' is the filesystem's
/// opinion"): a bookmark can resolve by its recorded *path* to something that is no longer
/// there. Absorbing that would relocate the board onto a ghost and leave it with a reload
/// failure instead of the honest vanished-root lock, so a resolution that does not exist on
/// disk falls through to outcomes 2 and 3.
///
/// ### Re-entrancy
///
/// Every outcome ends in a fresh stream, and every future root change lands right back here.
/// That is the design, not an accident: outcome 3 arms outcome 2, and a board that is renamed
/// twice is absorbed twice. Nothing here holds state between calls beyond the entry itself, and
/// the entry is looked up by store identity on each pass, so a re-key mid-loop cannot strand a
/// later signal.
private func recoverFromRootChange(of store: BoardStore) {
guard let identity = entries.first(where: { $0.value.store === store })?.key,
let entry = entries[identity] else {
Self.logger.debug("root change for a store that is no longer registered — ignored")
return
}
// 1. The rename-absorption path.
if let bookmark = entry.bookmark,
let resolution = BoardRegistry.resolve(bookmark),
BoardRegistry.withScopedAccess(to: resolution.url, { FileManager.default.fileExists(atPath: $0.path) }) {
Self.logger.debug("root change resolved through the bookmark — absorbing the move")
absorb(newRoot: resolution.url, at: identity)
return
}
// 2. The root returning at its last-known path — Finder undo, remount, recreation.
if FileManager.default.fileExists(atPath: entry.lastKnownRoot.path) {
Self.logger.debug("root reappeared at its last-known path — absorbing the return")
absorb(newRoot: entry.lastKnownRoot, at: identity)
return
}
// 3. Truly vanished.
store.enterVanishedRootLock()
entry.watcher.reattach(to: entry.lastKnownRoot)
}
/// Moves an entry's board to `newRoot`: the store's URLs, the watcher's stream, the entry's
/// bookmark and last-known path, and — where it changed — the entry's key.
///
/// **Order matters.** `relocate(to:)` first, so the reconciling reload that `reattach(to:)`
/// schedules walks the new root and lands a snapshot that agrees with the store's `rootURL`.
/// Re-attaching first would leave a window in which the reload's tree and the Writer's URLs
/// disagreed about where the board is.
///
/// **Re-keying.** A rename keeps the folder's file identity, so the key is usually unchanged
/// and this is a no-op. A board deleted and recreated at the same path is a *different inode*
/// under the same name, and its entry has to move to the new identity or the next
/// `acquire`/`liveStore(for:)` would miss it and open a second store over the board already on
/// screen — the exact bug the identity keying exists to prevent. An identity that cannot be
/// read leaves the key alone: a stale key still finds the entry by store identity, where
/// dropping the entry would strand a live watcher.
private func absorb(newRoot: URL, at identity: FileIdentity) {
guard var entry = entries[identity] else { return }
entry.store.relocate(to: newRoot)
entry.watcher.reattach(to: newRoot)
entry.lastKnownRoot = newRoot
// Re-minted from where the board is now: a bookmark tracks moves, but a *stale* one is only
// good for a while, and this is the moment the app has both access and certainty.
if let refreshed = BoardRegistry.withScopedAccess(to: newRoot, { BoardRegistry.makeBookmark(for: $0) }) {
entry.bookmark = refreshed.data
}
guard let currentIdentity = FileIdentity(of: newRoot), currentIdentity != identity else {
entries[identity] = entry
return
}
entries[identity] = nil
entries[currentIdentity] = entry
Self.logger.debug("board re-keyed: the folder at this path is a different file than it was")
}
/// The live store for a board, if any window has it open — **without** taking a reference.
///
/// This is the "is this board already open?" question: focusing an existing window rather than
Kanban/LiveStore/DirtyBufferGuard.swift
+132
View File
@@ -0,0 +1,132 @@
import Foundation
import Observation
import os
/// The **one modal moment on the write-failure path** (02-architecture.md § Write-failure
/// surfacing), as a mechanism: closing a window — or the board, or quitting — with a dirty buffer
/// that cannot be written.
///
/// ### Why this one case is allowed to be modal
///
/// Everything else on the write path is non-modal by construction, because everything else is on
/// disk: a failed move visibly did not happen, a failed save leaves the keystrokes in the buffer
/// and the banner standing while the debounced save retries on its own cadence. Nothing is lost
/// while the window stays open. **Closing is the moment that stops being true** — the buffer is the
/// only place that text exists, and the window is about to go away. So the close stops and asks:
/// retry, save a copy elsewhere, or discard. Failing silently here would be the one place this
/// design loses a user's work.
///
/// ### What this type is, and is not
///
/// It is the *state machine* for that moment and nothing else: it does not own the buffer, does not
/// know what a card is, and does not present anything. Two closures supply everything specific —
/// `attemptSave` flushes the dirty buffer to its real home (the debounced save's target) and
/// `writeCopy` writes the buffer's current text wherever the user pointed. Presentation is
/// `View.dirtyBufferAlert(_:copyDestination:)` in `Kanban/UI/`.
///
/// ### Who will call it
///
/// - **m6's editor sessions** — the card window's body Edit buffer and its raw-source buffer, each
/// closing with a flush (05-card-window.md: "Leaving Edit flushes the debounce ... window
/// close").
/// - **m4's board-close flush** — closing a board window flushes pending debounced work before the
/// store tears down (02 § Windows, "Close flushes"), and a flush that cannot land is this moment
/// arriving at the board level.
///
/// Both are the same shape, which is why the mechanism is generic and arrives before either
/// caller: a buffer, a save that can fail, and a close that must not proceed until the text is
/// somewhere.
@MainActor
@Observable
public final class DirtyBufferGuard {
/// Whether a close is currently held up.
///
/// Deliberately two cases. There is no `.saving` or `.retrying`: `attemptSave` is synchronous
/// (it is a file write, and the buffer is already in memory), so there is no interval during
/// which a third state could be observed — inventing one would only invite a spinner over a
/// moment that does not exist.
public enum Phase: Equatable {
/// Nothing is holding the close: either the buffer is safe, or none was ever dirty.
case idle
/// The save failed. The modal must present, carrying this error's phrasing, and the close
/// must not proceed until one of `retry()`, `saveCopy(to:)`, or `discard()` returns it to
/// `.idle`.
case blocked(BoardWriteError)
}
public private(set) var phase: Phase = .idle
/// Flushes the dirty buffer to its real home — the same write the debounced save performs.
private let attemptSave: @MainActor () throws(BoardWriteError) -> Void
/// Writes the buffer's current text to an arbitrary user-picked URL — "save a copy elsewhere".
///
/// Untyped `throws` on purpose: this writes outside the board, to a destination the user chose
/// through a save panel, so its failures are `Foundation`'s (`Data.write`, `NSError` from the
/// panel's URL) rather than the Writer's closed vocabulary. Forcing them into `BoardWriteError`
/// would mean inventing a `WriteOperation` case for a file that is not part of any board.
private let writeCopy: @MainActor (URL) throws -> Void
private static let logger = Logger(subsystem: "dev.rzen.indie.Kanban", category: "dirty-buffer")
public init(
attemptSave: @escaping @MainActor () throws(BoardWriteError) -> Void,
writeCopy: @escaping @MainActor (URL) throws -> Void
) {
self.attemptSave = attemptSave
self.writeCopy = writeCopy
}
/// The close flow's gate: tries the save and answers whether the close may proceed.
///
/// - Returns: `true` when the buffer landed and the window may close. `false` when it did not —
/// `phase` is `.blocked` and the alert must present.
///
/// The caller decides *whether* to call this: a clean buffer has nothing to flush, and asking
/// this type about it would mean teaching it what "dirty" means for text it does not own.
public func beginClose() -> Bool {
attempt()
}
/// Re-attempts the save from the alert's "Try Again". Same act as `beginClose()`, named for the
/// button that calls it — a retry after the user freed some disk or reconnected a volume is the
/// case this whole moment exists to make possible.
///
/// - Returns: `true` when the buffer landed and the close may resume.
@discardableResult
public func retry() -> Bool {
attempt()
}
/// Writes the buffer's text to a destination the user picked, and unblocks on success.
///
/// **The text is safe elsewhere, so the close may proceed** — the buffer's real home is still
/// unwritten, and that is the trade the user just made knowingly. A failure rethrows and leaves
/// the phase blocked: the modal stays up, because the text is still nowhere but memory.
public func saveCopy(to url: URL) throws {
try writeCopy(url)
Self.logger.debug("dirty buffer saved as a copy; the close may proceed")
phase = .idle
}
/// The user chose to lose the text. Unblocks unconditionally — this is the one branch with
/// nothing to verify, and second-guessing an explicit discard would be its own kind of
/// dishonesty.
public func discard() {
Self.logger.debug("dirty buffer discarded at the user's request")
phase = .idle
}
private func attempt() -> Bool {
do throws(BoardWriteError) {
try attemptSave()
} catch {
Self.logger.error("dirty buffer could not be saved: \(error.description, privacy: .public)")
phase = .blocked(error)
return false
}
phase = .idle
return true
}
}