lanework/Kanban/LiveStore/BannerCenter.swift

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
    }
}

/// A loss row: content that didn't arrive though nothing failed (02-architecture.md § The banner
/// surface, "Loss rows are the warning-tone class for non-failure losses", settled 2026-07-28) — a
/// degraded paste, folders skipped from a Finder drop, their future kin.
///
/// **It takes the one-shot's lifecycle**, deliberately: "a loss the user didn't notice is the harm,
/// so it never auto-expires" is `OneShotBanner`'s "an error never evaporates unread", read for a row
/// that reports something incomplete rather than something failed. Carrying its own `id` is the same
/// consequence: two identical losses a minute apart are two rows, and dismissing one must not take
/// the other with it.
///
/// **It ranks below the true failures and above the ambient notices** — "an action that didn't
/// happen outranks one that partially did" — which is why it is its own `BannerRow` case rather than
/// an `OneShotBanner` with a `nil` error or a `InfoSignpost` with a heavier tone: neither of those
/// vocabularies has a slot at loss's precedence, and bending one to fit would blur the reading that
/// the class exists to make precise.
public struct LossBanner: Identifiable, Sendable, Equatable {
    public let id: UUID
    public let message: String
    /// When the loss happened — the sort key for "newest first within a class".
    public let occurredAt: Date

    public init(id: UUID = UUID(), message: String, occurredAt: Date = Date()) {
        self.id = id
        self.message = message
        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 seven 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`, `loss`, and `signpost`. Each reports something that already
///   happened, so only the user can clear it. `loss` shares this lifecycle deliberately (settled
///   2026-07-28) even though it reports no failure: "a loss the user didn't notice is the harm, so
///   it never auto-expires" is the same reasoning that keeps a one-shot from evaporating unread,
///   aimed at a row that isn't an error at all.
/// - **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)
    /// Content that didn't arrive though nothing failed — a degraded paste, folders skipped from a
    /// Finder drop, their future kin. Dismissable, warning tone: below the true failures above it,
    /// above the ambient notices below it (settled 2026-07-28, see `LossBanner`).
    case loss(LossBanner)
    /// 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 let .loss(loss): "loss:\(loss.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, .loss: .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 .loss(loss): loss.message
        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, loss rows, 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 .loss(loss): loss.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, loss rows, 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:losses: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] = []

    /// Newest first, like `oneShots` — content that didn't arrive though nothing failed,
    /// dismissable and untimed for the same reason a one-shot failure is (settled 2026-07-28, see
    /// `LossBanner`).
    public private(set) var losses: [LossBanner] = []

    /// 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 loss row — content that didn't arrive though nothing failed (settled 2026-07-28, see
    /// `LossBanner`). Newest first, like the one-shots it shares a lifecycle with.
    public func postLoss(_ message: String) {
        losses.insert(LossBanner(message: message), 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)
    }

    /// One item a degraded paste could not bring its attachments with — what
    /// `degradedPasteMessage(for:)` names.
    ///
    /// `title` is the item's as written, `nil` for an untitled one: "Untitled" is a rendering, never
    /// a value (03-board-ui.md § Card face), and the phrasing below says "the item" instead, exactly
    /// as `actionPhrase(for:)` does for a failure whose title never got read.
    public struct AttachmentLoss: Sendable, Equatable {
        public let title: String?
        public let attachments: Int

        public init(title: String?, attachments: Int) {
            self.title = title
            self.attachments = attachments
        }
    }

    /// **The degraded paste** (04-interactions.md ▸ Clipboard, settled): the staged snapshot was
    /// missing or unreadable, so the paste fell back to the manifest's embedded `index.md` — content
    /// intact, attachments absent — and this is the row that says so. "A degraded paste is loud,
    /// never silent … the user never discovers an empty `attachments/` later."
    ///
    /// **A loss row, not a `oneShot` and not a signpost** — the vocabulary's answer rather than a
    /// compromise (settled 2026-07-28). 02-architecture.md's `oneShot` is *a write that did not
    /// happen*, carrying a `BoardWriteError`, and nothing here failed — the items landed, whole but
    /// for files that were never on the pasteboard's side of the transfer. This row first shipped as
    /// a signpost, the vocabulary's other one-shot-lifecycle member at the time, and it read quieter
    /// than 04's "loud" deserved: a signpost ranks last and may collapse behind "+N more", exactly
    /// where a board already showing real trouble would bury it. The loss class exists to close that
    /// gap — content that didn't arrive though nothing failed ranks below the true failures and
    /// above the ambient notices, keeping the signpost's dismissable, untimed lifecycle without
    /// inheriting its bottom-of-the-strip precedence.
    ///
    /// An empty list posts nothing: a fallback that lost no attachments lost nothing at all, and a
    /// banner announcing that would be noise.
    public func postDegradedPaste(_ losses: [AttachmentLoss]) {
        guard let message = Self.degradedPasteMessage(for: losses) else { return }
        postLoss(message)
    }

    /// Posts the skipped-folders loss row for a Finder drop that imported its files but refused its
    /// folders (04-interactions.md ▸ Selection, drag & drop, "Folders are refused at hover"): "a
    /// mixed drag proposes for its files only, and the drop imports the files while a one-shot
    /// banner names the skipped folders" — now a loss row, for the same reason the degraded paste is
    /// one (settled 2026-07-28): folders that never arrived are a non-failure loss, not a write
    /// failure.
    ///
    /// A drop with no skipped folders posts nothing — nothing was lost, so there is nothing to say.
    public func postSkippedFolders(count: Int) {
        guard count > 0 else { return }
        postLoss(Self.skippedFoldersMessage(count: count))
    }

    /// Removes a dismissable row: a one-shot failure, a loss row, 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 }
        losses.removeAll { $0.id == id }
        signposts.removeAll { $0.id == id }
    }

    /// Removes every dismissable row — one-shots, losses, 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()
        losses.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 > **loss rows** > commit and attachment failures > **passive info
    /// rows**. Four 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.
    /// - **Loss rows slot between the true failures and the ambient notices** (settled 2026-07-28):
    ///   "an action that didn't happen outranks one that partially did" is why a loss ranks below
    ///   every one-shot write failure, while "content that didn't arrive though nothing failed" is
    ///   still more consequential than a condition or a signpost that only reports ambient state —
    ///   so a loss also ranks above `historySuspended` and the attachment one-shots that follow it.
    ///   Concretely: non-attachment one-shots, then loss rows, then the commit-and-attachment class,
    ///   then signposts.
    /// - **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 — `losses`
    /// included, since a degraded paste already posts one (`postDegradedPaste`).
    public nonisolated static func rows(
        lock: ReadOnlyLockReason?,
        breakage: BoardLoadError?,
        oneShots: [OneShotBanner],
        losses: [LossBanner],
        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))

        rows.append(contentsOf: newestFirst(losses).map(BannerRow.loss))

        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)
    }

    /// The same stable newest-first ordering as the overload above, for loss rows — the two classes
    /// share a lifecycle, and `postLoss` already maintains newest-first on insertion the way
    /// `post(_:)` does.
    private nonisolated static func newestFirst(_ losses: [LossBanner]) -> [LossBanner] {
        losses
            .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 match the commands the user pressed — **Delete**, Put Back, Delete
    /// Immediately — which is 03-board-ui.md § Trash's naming constraint, settled with the trash UI
    /// copy: "Finder's 'Move to Trash' phrasing is reserved for the system Trash; board deletion says
    /// 'Delete'". A banner saying a card could not be *moved to the trash* would name the wrong one
    /// of the app's two trashes (the card window's attachment Remove is the other).
    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 delete '\(title)'" } else { "Couldn't delete the item" }
        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 .resize(title):
            if let title { "Couldn't resize '\(title)'" } else { "Couldn't resize the item" }
        case let .rename(title):
            // The title here is the item's name *before* the edit — the one the user is still
            // looking at — which is what makes "Couldn't rename 'Fix login'" (02's own example
            // sentence) identify the right row rather than a name that never landed.
            if let title { "Couldn't rename '\(title)'" } else { "Couldn't rename the item" }
        case let .duplicateBoard(title):
            if let title { "Couldn't duplicate '\(title)'" } else { "Couldn't duplicate the board" }
        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 degraded paste's line — 04-interactions.md's own example sentence, "Pasted 'Fix login'
    /// without its 3 attachments", generalized over the two axes it can vary on.
    ///
    /// **It names exactly what was lost**, which is what the design asks for and what decides every
    /// choice below: the count is real (never "some"), the singular and the plural are both spelled,
    /// and a multi-item paste totals the attachments rather than listing every title — a banner is one
    /// line, and "2 items" plus the true total is the honest summary where a truncated list would not
    /// be. `nil` for an empty list: nothing was lost, so there is nothing to say.
    ///
    /// The count is the item's `attachments/` as the snapshot listed it at copy time — the design's
    /// own vocabulary for what a card carries (01-storage-format.md § Attachments). A stray file
    /// sitting loose in the card folder is not in it and is not named here; see the report's
    /// design-gap note.
    public nonisolated static func degradedPasteMessage(for losses: [AttachmentLoss]) -> String? {
        guard !losses.isEmpty else { return nil }
        let total = losses.reduce(0) { $0 + $1.attachments }
        guard total > 0 else { return nil }

        guard losses.count == 1, let only = losses.first else {
            return "Pasted \(losses.count) items without their \(total) attachments"
        }
        let subject = only.title.map { "'\($0)'" } ?? "the item"
        let tail = total == 1 ? "its attachment" : "its \(total) attachments"
        return "Pasted \(subject) without \(tail)"
    }

    /// The skipped-folders line — 04-interactions.md's own example, "Folders can't be attached — 2
    /// skipped", generalized over the count. `postSkippedFolders` never calls this at `count == 0`,
    /// so every real call already has something to report.
    ///
    /// **Singular stays "Folders can't be attached — 1 skipped"** rather than recasting the leading
    /// clause to "A folder can't be attached": the claim is always about the drag as a whole — *its*
    /// folders didn't make it in — and only the trailing count varies, which is one sentence shape
    /// for every count instead of two that would have to be kept in agreement with each other.
    public nonisolated static func skippedFoldersMessage(count: Int) -> String {
        "Folders can't be attached — \(count) skipped"
    }

    /// 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 }
    }
}