Realign code with the 2026-07-29 findings-resolution rulings
Nine rulings land as code. Reorders don't stamp — one container-change predicate (WriteOperation.rewritesOrderOnly): within-container reorders and the renumber rescale rewrite only order, while cross-lane, cross-board, and trash moves stamp modified and clear modified-by; no trash special case exists, and the m8 undo inverses conform through the same seam. Copies are transactions: the root-strict/nested-lenient split retires for a whole-subtree stampability preflight that refuses loudly naming the offender, and every item-level copy severs remote/remote-state at every level (whole-board forks carry them verbatim). Paste refuses, never degrades: the embedded-index.md materialization and its loss row retire; a missing staged snapshot produces nothing and posts an error-tone one-shot named from manifest metadata. Coerce-tier fallbacks log through the Defect stream with path context attached loader-side. Displacement is level-uniform: a file squatting attachments inside a card heals by the same rename ladder as board-root squatters; comments stays tolerated. Delete Immediately joins card and lane context menus as Delete's ⌥-alternate with its own VO custom action, routed through an explicit container so the menu target outranks standing selection. Agent guide v7 teaches the stamp discipline and the card-level attachments claim, and sheds two stale v6 lines (lanes trash now; kind is taught). Verified conformant, unchanged: edition-aware Undo/Redo disable, trash marquee full-height backdrop. Both schemes 1854 tests / 318 suites green; verify-editions 30/30. Claude-Session: https://claude.ai/code/session_01SR4XGjmBE16ZUYWpfFHXwY
This commit is contained in:
@@ -21,9 +21,11 @@ import UniformTypeIdentifiers
|
||||
/// the full folder snapshots a paste reproduces byte-for-byte from — and to a pending cut. It is
|
||||
/// also the whole of "the snapshot survives relaunch exactly as long as the pasteboard still points
|
||||
/// at it": a sweep keeps the one directory this id names and collects every other.
|
||||
/// - Each `Entry` embeds the item's complete `index.md` text, so a paste still lands when the
|
||||
/// snapshot is missing or unreadable — "the staging-less fallback: content intact, attachments
|
||||
/// absent", announced by a banner rather than discovered later.
|
||||
/// - Each `Entry` embeds the item's complete `index.md` text as **identification metadata**
|
||||
/// (04-interactions.md ▸ Clipboard, re-ruled 2026-07-29): menu validation, the refusal's wording,
|
||||
/// and the plain-text flavor read it. It is emphatically **not** a materialization source — a paste
|
||||
/// whose staged snapshot is missing or unreadable refuses whole and writes nothing, because "an item
|
||||
/// arrives whole — index, attachments, loose files — or not at all".
|
||||
///
|
||||
/// `kind` and `container` are the selection's own vocabulary (`SelectionKind`, `ItemContainer`) rather than
|
||||
/// near-copies of it: a clipboard payload is a selection that was copied, and the cards-XOR-lanes and
|
||||
@@ -67,15 +69,23 @@ public struct ClipboardManifest: Codable, Sendable, Equatable {
|
||||
public var folder: String
|
||||
|
||||
/// The title as written, or `nil` for an untitled item — "Untitled" is a rendering, never a
|
||||
/// value (03-board-ui.md § Card face). Feeds the plain-text representation and the degraded
|
||||
/// paste's banner.
|
||||
/// value (03-board-ui.md § Card face). Feeds the plain-text representation and the refused
|
||||
/// paste's banner, which names the offending entry from exactly this.
|
||||
public var title: String?
|
||||
|
||||
/// The complete `index.md` at copy time — the staging-less fallback's source bytes.
|
||||
/// The complete `index.md` at copy time — **identification metadata, never materialized**
|
||||
/// (see the type comment). Kept because it is what lets the app answer "what was on the
|
||||
/// clipboard" without touching the staging store: the plain-text flavor and a refusal's wording
|
||||
/// both come from here, and both have to work when the snapshot is exactly what is missing.
|
||||
public var index: String
|
||||
|
||||
/// How many files the item's own `attachments/` held. Zero for a lane, which has none; a
|
||||
/// lane's attachments are its cards' and are counted there.
|
||||
///
|
||||
/// Identification metadata like the rest of the entry. It used to feed the degraded paste's
|
||||
/// loss accounting ("Pasted 'Fix login' without its 3 attachments"), which is retired with the
|
||||
/// degraded paste itself — an item now arrives whole or not at all, so there is no partial
|
||||
/// arrival left to count.
|
||||
public var attachmentCount: Int
|
||||
|
||||
/// A **lane** entry's cards, index text and all — "a lane entry embeds its cards' too,
|
||||
@@ -83,9 +93,9 @@ public struct ClipboardManifest: Codable, Sendable, Equatable {
|
||||
///
|
||||
/// **Exactly the lane's cards**, which needs no filter: "a lane carries exactly its cards —
|
||||
/// the trash is board-level, so there is nothing lane-nested to strip or carry"
|
||||
/// (04-interactions.md ▸ Drag and drop, resettled 2026-07-28), and the fallback only ever
|
||||
/// materializes a copy — a cut's move carries the real folder whole and never comes near this
|
||||
/// array. So the embedded set is exactly what a fallback paste should produce.
|
||||
/// (04-interactions.md ▸ Drag and drop, resettled 2026-07-28). Like the lane's own `index`, the
|
||||
/// cards' text is identification metadata: it describes what the copy held, and nothing
|
||||
/// materializes from it.
|
||||
public var cards: [Card]
|
||||
|
||||
/// One card inside a copied lane.
|
||||
@@ -103,9 +113,9 @@ public struct ClipboardManifest: Codable, Sendable, Equatable {
|
||||
}
|
||||
}
|
||||
|
||||
/// Everything a fallback paste of this entry would leave behind — its own attachments plus,
|
||||
/// for a lane, its cards'.
|
||||
public var lostAttachmentCount: Int {
|
||||
/// Every file this entry's subtree carried in an `attachments/` — its own plus, for a lane, its
|
||||
/// cards'. Identification metadata; nothing gates on it since the degraded paste retired.
|
||||
public var totalAttachmentCount: Int {
|
||||
attachmentCount + cards.reduce(0) { $0 + $1.attachmentCount }
|
||||
}
|
||||
|
||||
|
||||
@@ -14,8 +14,10 @@ import os
|
||||
/// folder trees, attachments and strays and all — is **staged** under
|
||||
/// `<group container>/Library/Application Support/Clipboard/<copyID>/`, so a paste reproduces the item
|
||||
/// byte-for-byte across boards rather than reconstructing it from a summary. The manifest's embedded
|
||||
/// `index.md` per entry is the fallback when a snapshot is missing, and a fallback paste is **loud**:
|
||||
/// a banner names exactly what was lost.
|
||||
/// `index.md` per entry is **identification metadata only** — menu validation, the refusal's wording,
|
||||
/// the plain-text flavor — and never a materialization source: a paste whose staged snapshot is
|
||||
/// missing or unreadable **refuses whole and writes nothing** (04-interactions.md ▸ Clipboard,
|
||||
/// re-ruled 2026-07-29 — Finder's invariant: an item arrives whole or not at all).
|
||||
///
|
||||
/// **The store is shared by every installed edition** (12-editions.md ▸ Both editions installed, ruled
|
||||
/// 2026-07-29): the group container is one container, so ⌘C in base pastes full-fidelity in Pro. The
|
||||
@@ -116,8 +118,9 @@ public final class ClipboardStore {
|
||||
/// > edition pastes **full-fidelity** in the other — snapshot, attachments and all.
|
||||
///
|
||||
/// Nothing about the lifecycle changes: both editions read the same pasteboard, so both sweeps
|
||||
/// compute the same answer from the same input, and the degraded embedded-`index.md` fallback stays
|
||||
/// for genuinely missing snapshots rather than being the structural cross-edition outcome.
|
||||
/// compute the same answer from the same input. The shared home is also what keeps the refusal a
|
||||
/// rare corner rather than the structural cross-edition outcome — a copy in one edition pastes
|
||||
/// full-fidelity in the other, so neither has to reach for bytes that are not there.
|
||||
public static var defaultStagingRoot: URL {
|
||||
AppGroup.stateDirectory.appendingPathComponent("Clipboard", isDirectory: true)
|
||||
}
|
||||
@@ -182,9 +185,10 @@ public final class ClipboardStore {
|
||||
/// The order is the contract: capture from the snapshot (main actor, no I/O — every item's
|
||||
/// `index.md` is already parsed into the snapshot and `FrontmatterDocument.serialized()` returns
|
||||
/// it verbatim), schedule the snapshots behind it, then write the pasteboard, then sweep. The
|
||||
/// pasteboard is written *before* the copies land, which is safe precisely because the manifest
|
||||
/// carries the fallback text: a paste that somehow beat the chain would still materialize the
|
||||
/// right items.
|
||||
/// pasteboard is written *before* the copies land, which is safe because a paste **awaits the same
|
||||
/// chain** (`paste(into:)`): it can never read a half-written snapshot, so it never sees a tree the
|
||||
/// staging has not finished. This used to lean on the manifest's fallback text instead; with
|
||||
/// refuse-don't-degrade the chain is the whole guarantee, and it is the stronger one.
|
||||
private func write(from store: BoardStore, cut: Bool) {
|
||||
guard let capture = Self.capture(selection: store.selection, snapshot: store.snapshot) else { return }
|
||||
|
||||
@@ -348,9 +352,8 @@ public final class ClipboardStore {
|
||||
// doing nothing.
|
||||
guard payload?.copyID == manifest.copyID else { return }
|
||||
|
||||
store.transient.noteUserCreation()
|
||||
|
||||
if let move = armedMove(for: manifest) {
|
||||
store.transient.noteUserCreation()
|
||||
let sources = move.folders.map(BoardStore.ItemSource.folder)
|
||||
switch plan {
|
||||
case let .cards(target):
|
||||
@@ -373,31 +376,29 @@ public final class ClipboardStore {
|
||||
return
|
||||
}
|
||||
|
||||
// The copy path — the staged snapshot per entry, or the embedded `index.md` where that
|
||||
// snapshot is missing or unreadable. Mixed is legal and is the honest outcome of a partial
|
||||
// staging failure: the entries that have snapshots arrive whole.
|
||||
// **The copy path's preflight: refuse, never degrade** (04-interactions.md ▸ Clipboard,
|
||||
// re-ruled 2026-07-29). Every entry must have its staged snapshot on disk *before* anything is
|
||||
// materialized — the first one that does not refuses the whole paste, names itself from the
|
||||
// manifest's metadata, and writes nothing at all. All-or-nothing for the whole paste, which is
|
||||
// the copies-are-transactions posture (01-storage-format.md § Frontmatter) read one level up:
|
||||
// the transaction is the gesture, not the entry.
|
||||
let stagingDir = stagingRoot.appendingPathComponent(manifest.copyID, isDirectory: true)
|
||||
var sources: [BoardStore.ItemSource] = []
|
||||
var losses: [BannerCenter.AttachmentLoss] = []
|
||||
for entry in manifest.entries {
|
||||
let staged = stagingDir.appendingPathComponent(entry.folder, isDirectory: true)
|
||||
if FileManager.default.fileExists(
|
||||
guard FileManager.default.fileExists(
|
||||
atPath: staged.appendingPathComponent(BoardLoader.indexFileName).path
|
||||
) {
|
||||
sources.append(.folder(staged))
|
||||
continue
|
||||
}
|
||||
sources.append(.text(index: entry.index, cards: entry.cards.map(\.index)))
|
||||
// "A degraded paste is loud, never silent … a one-shot banner names exactly what was
|
||||
// lost." An entry with no attachments lost nothing — its content is intact and its bytes
|
||||
// are the source bytes — so it contributes no row.
|
||||
if entry.lostAttachmentCount > 0 {
|
||||
losses.append(BannerCenter.AttachmentLoss(
|
||||
title: entry.title,
|
||||
attachments: entry.lostAttachmentCount
|
||||
))
|
||||
) else {
|
||||
// The offending entry, named — and the destination's search is left exactly as it was.
|
||||
// "Any user-initiated creation on the board clears the query" (04 ▸ Search) is a rule
|
||||
// about creations, and this paste created nothing; the preflight therefore runs *before*
|
||||
// `noteUserCreation`, so a refusal costs the user neither content nor their filter.
|
||||
store.banners.postRefusedPaste(title: entry.title, stagedAt: staged.path)
|
||||
return
|
||||
}
|
||||
sources.append(.folder(staged))
|
||||
}
|
||||
store.transient.noteUserCreation()
|
||||
|
||||
// A card copied out of the trash needs nothing done to it on arrival: it carries no
|
||||
// `deleted:` key, because there is no such key any more (03-board-ui.md § Trash, resettled
|
||||
@@ -419,7 +420,6 @@ public final class ClipboardStore {
|
||||
normalizingLooseFiles: true
|
||||
)
|
||||
}
|
||||
store.banners.postDegradedPaste(losses)
|
||||
}
|
||||
|
||||
/// The armed cut's surviving originals, in flatten order and as folders under the **source**
|
||||
@@ -486,9 +486,11 @@ public final class ClipboardStore {
|
||||
let destination: URL
|
||||
}
|
||||
|
||||
/// Appends this copy's snapshots to the staging chain. Best-effort per item: one that fails to
|
||||
/// copy simply falls back to the manifest's embedded `index.md` at paste time, which is the
|
||||
/// degraded paste the banner already has words for.
|
||||
/// Appends this copy's snapshots to the staging chain. Best-effort per item, and the *consequence*
|
||||
/// of a failure changed with the refuse-don't-degrade ruling: an item whose snapshot never landed
|
||||
/// makes the next paste **refuse whole**, naming it (`perform`'s preflight), rather than
|
||||
/// materializing it hollow from the manifest's embedded `index.md`. Failing to stage is therefore
|
||||
/// as loud as it should be, one gesture later.
|
||||
private func stage(_ jobs: [StagingJob], into stagingDir: URL) {
|
||||
enqueue { [jobs, stagingDir] in
|
||||
guard (try? FileManager.default.createDirectory(
|
||||
@@ -628,9 +630,11 @@ public final class ClipboardStore {
|
||||
/// the app already states once.
|
||||
///
|
||||
/// **The index text comes from the snapshot, not from disk.** `FrontmatterDocument` edits by line
|
||||
/// span, so `serialized()` on an untouched document returns the file's bytes exactly — which
|
||||
/// makes the manifest's fallback text genuinely *the source bytes* while costing ⌘C no file I/O
|
||||
/// at all, even for a lane carrying two hundred cards.
|
||||
/// span, so `serialized()` on an untouched document returns the file's bytes exactly — which makes
|
||||
/// the manifest's embedded text a faithful record of the item while costing ⌘C no file I/O at all,
|
||||
/// even for a lane carrying two hundred cards. It is **identification metadata**, not a
|
||||
/// materialization source (see the type comment): the refusal's wording and the plain-text flavor
|
||||
/// read it, and nothing writes it.
|
||||
static func capture(
|
||||
selection: ItemReferenceSet,
|
||||
snapshot: BoardModel
|
||||
|
||||
@@ -8,7 +8,8 @@ import os
|
||||
///
|
||||
/// A template is a board folder, so discovery is `BoardLoader.load` and instantiation is a tree copy
|
||||
/// plus the Writer's own remint-and-restamp machinery (`BoardWriter.remintDescendants`,
|
||||
/// `stampCopiedDescendant`, `updateIndex`). There is no template schema, no template catalog in
|
||||
/// `checkCopiedDescendantsAreStampable`, `applyCopyContract`, `stampCopiedDescendant`,
|
||||
/// `updateIndex`). There is no template schema, no template catalog in
|
||||
/// Swift, and no second copy path — which is 09's "dogfood" clause and 02-architecture.md's single
|
||||
/// write door, both held by having nothing here to hold them with.
|
||||
///
|
||||
@@ -379,19 +380,35 @@ enum TemplateEngine {
|
||||
/// The born half, on the tree already at the destination: fresh identities, fresh stamps, the
|
||||
/// chosen title, and the loose-file normalization an import boundary owes.
|
||||
///
|
||||
/// **The root is strict and the descendants are lenient**, which is `BoardWriter.copyItem`'s
|
||||
/// split for its reason: the root *must* be rewritten (it carries the title the user just typed),
|
||||
/// so a template whose own `index.md` cannot be edited in place refuses the create — while a
|
||||
/// nested card that is readable-but-uneditable is copied byte-verbatim and simply not stamped,
|
||||
/// because failing a whole create over one hand-dropped flow mapping would be hostile. Its stale
|
||||
/// `modified-by` surviving is the self-reported-provenance honest limit 01 § Frontmatter already
|
||||
/// acknowledges.
|
||||
/// **An instantiation is a copy transaction**, which is `BoardWriter.copyItem`'s posture since
|
||||
/// 2026-07-29 and for its reason: the whole tree is preflighted for stampability before a single
|
||||
/// folder is reminted, and a template carrying one readable-but-uneditable card refuses the create
|
||||
/// whole, naming that card (01-storage-format.md § Frontmatter: "preflights the entire subtree and
|
||||
/// refuses whole, loudly, naming the offending item — never a partial copy, never a silently
|
||||
/// unstamped descendant").
|
||||
///
|
||||
/// This retired the former root-strict/descendants-lenient split, which copied such a card
|
||||
/// byte-verbatim and skipped its stamp. Two things were wrong with the kindness: an unstamped
|
||||
/// descendant keeps a `modified-by` naming somebody who never touched this board, and — since the
|
||||
/// tracker sever joined the copy contract — a live `remote` claim on an object the new board has
|
||||
/// no relationship with. "Proceed partially, lose a little" is never a verdict (01's leniency
|
||||
/// doctrine).
|
||||
///
|
||||
/// **The preflight runs on the destination, not the template**, deliberately: the copy has already
|
||||
/// applied its top-level exclusions, so `.trash/`'s cards — which are not part of what a template
|
||||
/// instantiates — cannot refuse a create they were never going to appear in. Nothing is lost by
|
||||
/// preflighting a step later, because `instantiate`'s construct-then-clean removes the whole
|
||||
/// destination on any throw (09-templates.md's atomicity).
|
||||
private static func mintIdentitiesAndStamps(
|
||||
at root: URL,
|
||||
title: String,
|
||||
operation: WriteOperation
|
||||
) throws(Failure) {
|
||||
do throws(BoardWriteError) {
|
||||
// Before the remint, so a refusal names folders by the paths the user's template actually
|
||||
// has rather than by minted UUIDs they have never seen.
|
||||
try BoardWriter.checkCopiedDescendantsAreStampable(of: root, operation: operation)
|
||||
|
||||
var materialized: [URL] = []
|
||||
try BoardWriter.remintDescendants(of: root, collecting: &materialized, operation: operation)
|
||||
|
||||
@@ -402,7 +419,10 @@ enum TemplateEngine {
|
||||
// cannot answer, and this write is where a template's kind-less root gains it
|
||||
// (`BoardWriter.updateIndex`'s on-touch backfill; no template migration, by design).
|
||||
try BoardWriter.updateIndex(inItemFolder: root, kind: .board, operation: operation) { document in
|
||||
document.set(FrontmatterKeys.created, to: .date(now))
|
||||
// `.born` restamps `created`; the copy contract also severs the reserved tracker keys,
|
||||
// which at board level is the `remote` a template could have carried in from the board
|
||||
// it was saved from (01 ▸ Identity lifecycle, ruled 2026-07-29).
|
||||
BoardWriter.applyCopyContract(to: &document, stamps: .born, now: now)
|
||||
document.set(FrontmatterKeys.title, to: .string(title))
|
||||
}
|
||||
for folder in materialized {
|
||||
|
||||
@@ -37,8 +37,8 @@ public struct OneShotBanner: Identifiable, Sendable, Equatable {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
/// surface, "Loss rows are the warning-tone class for non-failure losses", settled 2026-07-28) —
|
||||
/// folders skipped from a Finder drop, the app's own relocation and repair notices, 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
|
||||
@@ -173,8 +173,8 @@ public enum BannerRow: Identifiable, Sendable {
|
||||
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,
|
||||
/// Content that didn't arrive though nothing failed — folders skipped from a Finder drop, the
|
||||
/// app's own relocation and repair notices. 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
|
||||
@@ -392,43 +392,36 @@ public final class BannerCenter {
|
||||
postSignpost(Self.skippedStepMessage(direction, subject: subject))
|
||||
}
|
||||
|
||||
/// One item a degraded paste could not bring its attachments with — what
|
||||
/// `degradedPasteMessage(for:)` names.
|
||||
/// **The refused paste** (04-interactions.md ▸ Clipboard, re-ruled 2026-07-29): the staged
|
||||
/// snapshot was missing or unreadable, so the paste produced **nothing**, and this is the row that
|
||||
/// says so — "the paste produces nothing, and a one-shot failure banner names it from the
|
||||
/// manifest's metadata".
|
||||
///
|
||||
/// `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 `oneShot`, not a loss row** — which is the pivot, and it is the vocabulary reading the
|
||||
/// event correctly rather than a reclassification for its own sake. The degraded paste *was* a loss
|
||||
/// row because the items landed and only their attachments did not: content that didn't arrive
|
||||
/// though nothing failed. Under refuse-don't-degrade nothing lands at all, which is exactly
|
||||
/// 02-architecture.md's definition of a one-shot — a write that did not happen — so the row
|
||||
/// carries a `BoardWriteError` like every other failure, ranks with the true failures, and says
|
||||
/// "Couldn't paste" rather than "Pasted … without".
|
||||
///
|
||||
/// **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.
|
||||
/// The retired member is `postDegradedPaste(_:)` and its `AttachmentLoss` payload: with the
|
||||
/// degraded materialization gone there is no partial arrival to account for, and the
|
||||
/// loss-accounting problem it existed to report — what didn't arrive, and whether the totals were
|
||||
/// honest — dissolves rather than being solved. **The loss class itself is untouched**: folder-drop
|
||||
/// skips still post one (`postSkippedFolders`), and the relocation, migration, displacement and
|
||||
/// remint notices are all still its.
|
||||
///
|
||||
/// 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)
|
||||
/// `title` is the offending entry's, from the manifest's own metadata, `nil` for an untitled item —
|
||||
/// "Untitled" is a rendering, never a value (03-board-ui.md § Card face), so `actionPhrase(for:)`
|
||||
/// says "the item" instead. The staging path is what the error names as its `path`: it is the file
|
||||
/// that was not there, and naming it is what makes a bug report about this actionable.
|
||||
public func postRefusedPaste(title: String?, stagedAt path: String) {
|
||||
post(BoardWriteError(
|
||||
operation: .paste(title: title),
|
||||
path: path,
|
||||
reason: .clipboardContentGone
|
||||
))
|
||||
}
|
||||
|
||||
/// One card whose loose files were relocated into `attachments/` — what
|
||||
@@ -547,9 +540,10 @@ public final class BannerCenter {
|
||||
/// 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.
|
||||
/// banner names the skipped folders" — now a loss row (settled 2026-07-28): folders that never
|
||||
/// arrived are a non-failure loss, not a write failure. With the degraded paste retired
|
||||
/// (`postRefusedPaste`) this is the loss class's clearest remaining instance: the drop *did* land,
|
||||
/// and only the payload the attachment model cannot hold stayed behind.
|
||||
///
|
||||
/// A drop with no skipped folders posts nothing — nothing was lost, so there is nothing to say.
|
||||
public func postSkippedFolders(count: Int) {
|
||||
@@ -653,7 +647,7 @@ public final class BannerCenter {
|
||||
///
|
||||
/// `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`).
|
||||
/// included, since a Finder drop that skipped folders already posts one (`postSkippedFolders`).
|
||||
public nonisolated static func rows(
|
||||
lock: ReadOnlyLockReason?,
|
||||
breakage: BoardLoadError?,
|
||||
@@ -756,6 +750,13 @@ public final class BannerCenter {
|
||||
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 .paste(title):
|
||||
// **The command's own verb** (04-interactions.md ▸ Clipboard's own example sentence,
|
||||
// "Couldn't paste 'Fix login' — the copied content is gone"). The user pressed ⌘V, and
|
||||
// "Couldn't copy" — the operation the Writer would have run — would name a gesture they
|
||||
// never made. The item is named from the manifest's metadata, which is what the embedded
|
||||
// `index.md` is kept for now that it is never a materialization source.
|
||||
if let title { "Couldn't paste '\(title)'" } else { "Couldn't paste the item" }
|
||||
case let .delete(title):
|
||||
if let title { "Couldn't delete '\(title)'" } else { "Couldn't delete the item" }
|
||||
case let .purge(title):
|
||||
@@ -865,6 +866,13 @@ public final class BannerCenter {
|
||||
// outlet raises this in its alert and never here — the store validates before it opens a
|
||||
// write bracket — so this line exists for a caller that reached the Writer directly.
|
||||
error.reason.description
|
||||
case .clipboardContentGone:
|
||||
// **04's own words** ("the copied content is gone"), and the whole of what can honestly be
|
||||
// said: the snapshot the pasteboard promised is not on disk, so there is no cause to
|
||||
// diagnose past that. It deliberately says nothing about *why* — a sweep that ran early, a
|
||||
// container the system reclaimed, an unmounted volume — because the user's recovery is the
|
||||
// same in every case, and 04 names it: ⌘C again.
|
||||
"the copied content is gone"
|
||||
}
|
||||
return trimmed(text)
|
||||
}
|
||||
@@ -904,32 +912,6 @@ public final class BannerCenter {
|
||||
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.
|
||||
@@ -954,9 +936,8 @@ public final class BannerCenter {
|
||||
/// a list of names would be the first thing to truncate; the card is still named, which is
|
||||
/// what makes the notice actionable — the user knows exactly which `attachments/` to look in.
|
||||
/// - **Several cards** folds again, to two counts: "Moved 5 files into attachments — 3 cards"
|
||||
/// (settled here, the judgment 01 leaves to the implementation). It is the degraded paste's
|
||||
/// own shape — "Pasted 2 items without their 5 files" — and for its reason: the true total
|
||||
/// plus the true item count is the honest summary where a truncated list of titles would not
|
||||
/// (settled here, the judgment 01 leaves to the implementation): the true total plus the true
|
||||
/// item count is the honest summary where a truncated list of titles would not
|
||||
/// be. This case is the whole-board sweep (a board opened after an agent scattered files
|
||||
/// across it), where naming three cards of eleven would read as a bug.
|
||||
///
|
||||
|
||||
@@ -2495,21 +2495,25 @@ public final class BoardStore: HealHost {
|
||||
|
||||
/// Where one arriving item's bytes come from.
|
||||
///
|
||||
/// **Two producers, one arrival path.** A drag names folders in the source board; a paste names
|
||||
/// folders in the clipboard's staging directory — and, when that snapshot is missing or
|
||||
/// unreadable, the manifest's embedded `index.md` instead (04-interactions.md ▸ Clipboard's
|
||||
/// staging-less fallback). Modelling the fallback as a second kind of *source* rather than as a
|
||||
/// second arrival method is what keeps the rank insertion, the tombstone stripping and the
|
||||
/// `deleted:` clearing stated once: everything downstream of "where do the bytes come from" is
|
||||
/// identical, and a paste that half-falls-back mixes the two cases inside one bracket.
|
||||
/// **One producer shape, because there is only one kind of source left.** A drag names folders in
|
||||
/// the source board; a paste names folders in the clipboard's staging directory. There used to be a
|
||||
/// second case — the manifest's embedded `index.md`, materialized when the staged snapshot was
|
||||
/// missing or unreadable — and it is **retired with the degraded paste** (04-interactions.md ▸
|
||||
/// Clipboard, re-ruled 2026-07-29: "A paste whose staged snapshot is missing or unreadable refuses
|
||||
/// loudly — never degrades"). An item arrives **whole — index, attachments, loose files — or not at
|
||||
/// all**, so a paste can no longer half-fall-back inside one bracket, and the loss-accounting
|
||||
/// problem the second case created dissolves rather than being solved. The manifest still embeds
|
||||
/// `index.md`, now purely as identification metadata: menu validation, the refusal's wording, and
|
||||
/// the plain-text flavor.
|
||||
///
|
||||
/// It stays a single-case enum rather than collapsing to a bare `URL`: the arrival paths read as
|
||||
/// "where do these bytes come from", the drag and the clipboard each say so at their own call
|
||||
/// sites, and a future third producer (an import, a drop from another document type) has a place to
|
||||
/// land that is not a rewrite of every signature in between.
|
||||
public enum ItemSource: Sendable, Equatable {
|
||||
|
||||
/// A folder on disk — the source board's own, or a staged snapshot of it.
|
||||
case folder(URL)
|
||||
|
||||
/// The manifest's embedded text: the item's `index.md`, and (for a lane) its cards'.
|
||||
/// Materialized by `BoardWriter.materializeItem`, byte-faithfully.
|
||||
case text(index: String, cards: [String])
|
||||
}
|
||||
|
||||
/// A cross-board card drop, landing contiguously at `index` among `laneID`'s rendered cards.
|
||||
@@ -2535,10 +2539,11 @@ public final class BoardStore: HealHost {
|
||||
/// independently (04-interactions.md ▸ Clipboard).
|
||||
///
|
||||
/// It is the same commit as a drop's, deliberately: `.copy` materializes from the staged snapshot
|
||||
/// (or, per entry, from the embedded `index.md`) and `.move` is the armed cut's — "the ⌘-drag
|
||||
/// move path — identity travels", which is also the keyboard restore when the cut was made in the
|
||||
/// trash (▸ The trash: "cut in the trash, paste into a lane is the keyboard-native restore, an
|
||||
/// ordinary folder move").
|
||||
/// and `.move` is the armed cut's — "the ⌘-drag move path — identity travels", which is also the
|
||||
/// keyboard restore when the cut was made in the trash (▸ The trash: "cut in the trash, paste into a
|
||||
/// lane is the keyboard-native restore, an ordinary folder move"). A copy whose staged snapshot is
|
||||
/// missing never reaches here at all: the clipboard refuses the whole paste in front of this call
|
||||
/// (04 ▸ Clipboard, re-ruled 2026-07-29), so every source this sees is a folder that exists.
|
||||
///
|
||||
/// **The trash's old copy-out rule is gone with the tombstone it stripped** (resettled
|
||||
/// 2026-07-28): a trashed card carries no `deleted:` key, so a card copied out of the trash is
|
||||
@@ -2616,15 +2621,14 @@ public final class BoardStore: HealHost {
|
||||
}
|
||||
}
|
||||
|
||||
/// One arrival's materialization — the two `ItemSource` kinds crossed with the two operations,
|
||||
/// in the one place both the card path and the lane path can share.
|
||||
/// One arrival's materialization — the source crossed with the two operations, in the one place
|
||||
/// both the card path and the lane path can share.
|
||||
///
|
||||
/// **`.move` of a `.text` source is unreachable and answers `nil`.** A move needs a folder whose
|
||||
/// identity travels, and the only producer of text sources is the clipboard's fallback, which is
|
||||
/// a *copy* by construction (04-interactions.md ▸ Clipboard: an armed cut moves the surviving
|
||||
/// originals, and a cut that cannot find them is void). Skipping is the standing posture for an
|
||||
/// arrival that names nothing — the same silent no-op every other drop commit gives a source that
|
||||
/// has gone.
|
||||
/// A copy is `copyItem` (fresh GUIDs throughout, the copy contract applied to every folder it
|
||||
/// materializes) and a move is `moveItem` (identity travels, the import boundary reminting only
|
||||
/// what collides). The `ItemID?` return survives the retired text case because the lane and card
|
||||
/// arrival loops read it as "did this arrival land": a `nil` is the standing silent no-op for a
|
||||
/// source that names nothing.
|
||||
private static func materialize(
|
||||
_ source: ItemSource,
|
||||
operation: TransferOperation,
|
||||
@@ -2644,15 +2648,6 @@ public final class BoardStore: HealHost {
|
||||
destinationBoardRoot: destinationBoardRoot,
|
||||
order: order
|
||||
).id
|
||||
case let (.text(index, cards), .copy):
|
||||
return try BoardWriter.materializeItem(
|
||||
inParent: parent,
|
||||
indexText: index,
|
||||
children: cards,
|
||||
order: order
|
||||
)
|
||||
case (.text, .move):
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2677,7 +2672,7 @@ public final class BoardStore: HealHost {
|
||||
)
|
||||
}
|
||||
|
||||
/// **The clipboard's lane arrival** — `receiveLanes` with the staging-less fallback folded in
|
||||
/// **The clipboard's lane arrival** — `receiveLanes` with the paste's own axis folded in
|
||||
/// (04-interactions.md ▸ Clipboard).
|
||||
///
|
||||
/// The two operations keep their drag semantics exactly, because 04 says they are the same
|
||||
@@ -3445,8 +3440,19 @@ public final class BoardStore: HealHost {
|
||||
/// The selection is cleared rather than walked to a successor: unlike ⌫, this is the command a
|
||||
/// confirmation stands in front of, and what follows it is reading the board rather than pressing
|
||||
/// the key again.
|
||||
public func deleteImmediately(_ ids: Set<ItemID>) {
|
||||
let container = selection.container
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - ids: the items to purge — the caller's explicit set, not this store's selection.
|
||||
/// - container: **which side those ids live on**, supplied rather than read off the selection
|
||||
/// (added with the context menu's ⌥-alternate — 11-command-nexus.md ▸ Context menus). The
|
||||
/// menu-bar caller passes the selection's own container and behaves exactly as before; a
|
||||
/// context-menu caller passes `.board`, because "the click names its target" and the target can
|
||||
/// legitimately sit on the other side of the container boundary from a standing selection
|
||||
/// (797d020's explicit-set resolution, whose whole point is that the two can disagree). Reading
|
||||
/// it off the selection here would silently resolve a board card against `.trash` and purge
|
||||
/// nothing — a confirmed destructive command turning into a no-op, which is the one outcome a
|
||||
/// confirmation must never lead to.
|
||||
public func deleteImmediately(_ ids: Set<ItemID>, in container: ItemContainer) {
|
||||
let paths = ItemPath.resolve(ids, in: container, snapshot: snapshot).filter { !$0.isLane }
|
||||
guard !paths.isEmpty else { return }
|
||||
let root = rootURL
|
||||
@@ -3604,19 +3610,28 @@ public final class BoardStore: HealHost {
|
||||
|
||||
// MARK: - The claimed-name displacement
|
||||
|
||||
/// Moves a squatter off a board-root name the app claims, and posts the notice naming old and
|
||||
/// new — the **act** half of the claimed-names ruling (01-storage-format.md § Fractal layout ▸
|
||||
/// Rules, ruled 2026-07-29: "Lanework owns the board, so an invalid artifact on a claimed name is
|
||||
/// a defect, not a resident").
|
||||
/// Moves squatters off the names the app claims, and posts the notice naming old and new — the
|
||||
/// **act** half of the claimed-names ruling (01-storage-format.md § Fractal layout ▸ Rules, ruled
|
||||
/// 2026-07-29: "Lanework owns the board, so an invalid artifact on a claimed name is a defect, not
|
||||
/// a resident").
|
||||
///
|
||||
/// Today that is `.trash` and only `.trash`: a file or symlink sitting on the name the trash
|
||||
/// needs, which breaks deletion for as long as it stands — which is exactly why the timing is
|
||||
/// *scheduled* rather than on-touch (§ Validation and healing: "proactive when the defect is
|
||||
/// load-bearing now"). `CLAUDE.md`'s squatter is displaced by the guide's own heal, which owns
|
||||
/// that file end to end.
|
||||
/// **Two levels, one heal** (extended 2026-07-29 — "the rule is level-uniform"): the board root's
|
||||
/// `.trash`, and any card's `attachments`. Each is a file or symlink sitting on a name the app needs
|
||||
/// — breaking deletion in the first case, and every import, Finder drop and sidebar listing for that
|
||||
/// card in the second — which is exactly why the timing is *scheduled* rather than on-touch
|
||||
/// (§ Validation and healing: "proactive when the defect is load-bearing now"). `CLAUDE.md`'s
|
||||
/// squatter is displaced by the guide's own heal, which owns that file end to end; a wrong-kinded
|
||||
/// `comments` is a tolerated stray until the feature consumes the name.
|
||||
///
|
||||
/// **Displacement, never destruction**, and never a mint: the freed name is left empty and the
|
||||
/// *next delete* creates the real `.trash/`, exactly as it does on a board that never had one.
|
||||
/// **One bracket over every displacement the load found**, whatever their levels: the batch is one
|
||||
/// app-mediated reload and, on git boards, one heal commit — the loose-file relocation's rule, and
|
||||
/// this heal's own memo is board-wide anyway.
|
||||
///
|
||||
/// **Displacement, never destruction**, and never a mint: the freed name is left empty and the next
|
||||
/// gesture that needs it creates the real folder — the next delete mints `.trash/`, the next import
|
||||
/// mints `attachments/` — exactly as on a board that never had one. The displaced file, now an
|
||||
/// ordinary loose file beside the card's `index.md`, is picked up by the next load's loose-file
|
||||
/// relocation and lands in the real `attachments/`: the heals compose, which is 01's own word for it.
|
||||
public func displaceClaimedNames() {
|
||||
let work = claimedNameSquatters
|
||||
let root = rootURL
|
||||
|
||||
@@ -55,8 +55,16 @@ enum AgentGuide {
|
||||
/// pointer) and supersedes it on the next open. v6 adds the one-folder-at-a-time move warning:
|
||||
/// a real agent incident (2026-07-29) showed `mv <lane>/*` sweeping the lane's own `index.md`
|
||||
/// along with the cards and destroying the destination lane's identity — the guide now says
|
||||
/// *why* the named-folder form is load-bearing, not just what to type.
|
||||
static let version = 6
|
||||
/// *why* the named-folder form is load-bearing, not just what to type. v7 teaches two more
|
||||
/// things settled after v6 shipped: the refined stamp-discipline predicate
|
||||
/// (01-storage-format.md ▸ `modified`'s scope, ruled 2026-07-29, refined 2026-07-30) — a
|
||||
/// within-container reorder rewrites only `order`, while a move that changes an item's
|
||||
/// container (another lane, another board, into or out of `.trash/`) stamps `modified` and
|
||||
/// `modified-by` like any content edit, the trash move included, since it's the same rule and
|
||||
/// not a special case — and the card-level `attachments` claimed name
|
||||
/// (01-storage-format.md § Fractal layout ▸ Rules, "level-uniform"): that name belongs to the
|
||||
/// app's own folder, so a *file* by that name is a defect the app displaces on sight.
|
||||
static let version = 7
|
||||
|
||||
// MARK: - The version marker
|
||||
|
||||
@@ -325,7 +333,7 @@ enum AgentGuide {
|
||||
<board>/ this folder (the board)
|
||||
├── index.md board title + settings; body = board description
|
||||
├── CLAUDE.md this guide (app-maintained)
|
||||
├── .trash/ deleted cards (app-managed — see Deleting)
|
||||
├── .trash/ deleted cards and lanes (app-managed — see Deleting)
|
||||
├── <uuid>/ a LANE
|
||||
│ ├── index.md lane title + order; body = lane notes/policy
|
||||
│ ├── <uuid>/ a CARD
|
||||
@@ -350,7 +358,7 @@ enum AgentGuide {
|
||||
- Lane titles carry the workflow semantics (e.g. To Do → In Progress →
|
||||
Done). Read the board's and lanes' index.md bodies for descriptions and
|
||||
per-lane policy before deciding where a card belongs.
|
||||
- `.trash/` holds deleted cards; everything else at board root that isn't a
|
||||
- `.trash/` holds deleted cards and lanes; everything else at board root that isn't a
|
||||
UUID-named folder is not part of the board's content.
|
||||
|
||||
## Frontmatter
|
||||
@@ -397,6 +405,7 @@ enum AgentGuide {
|
||||
```markdown
|
||||
---
|
||||
schema: 1
|
||||
kind: card
|
||||
title: Short imperative card title
|
||||
order: 3072
|
||||
created: 2026-07-24T18:00:00Z
|
||||
@@ -406,11 +415,24 @@ enum AgentGuide {
|
||||
The card's content — any Markdown.
|
||||
```
|
||||
|
||||
Creating a lane is the same one level up (body optional; `order` ranks
|
||||
lanes left→right).
|
||||
Creating a lane is the same one level up (body optional; `kind: lane`;
|
||||
`order` ranks lanes left→right).
|
||||
|
||||
**Always write `kind`** at creation — `kind: card`, `kind: lane`,
|
||||
`kind: board` at board root. Depth already says what an item is on the
|
||||
board, but `.trash/` is flat, and there the value is the only thing that
|
||||
tells a trashed lane from a card. Omitting it is healable, never fatal: the
|
||||
app fills a missing `kind` in the next time it rewrites that file.
|
||||
|
||||
## Moving and reordering
|
||||
|
||||
- **The stamp rule**: a move that changes an item's container — another
|
||||
lane, another board, or into/out of `.trash/` — stamps `modified` and
|
||||
re-stamps `modified-by`, the same as any content edit. A reorder that
|
||||
keeps an item in the same container (a card among its lane's cards, a
|
||||
lane among the board's) rewrites only `order`; leave `modified` and
|
||||
`modified-by` alone. The trash move isn't an exception to this — it
|
||||
stamps because every container change stamps.
|
||||
- Move to another lane: `mv <laneA>/<card-uuid> <laneB>/` — the folder move
|
||||
IS the move. Then set the card's `order` to place it among the
|
||||
destination's cards, update `modified`, and re-stamp `modified-by`.
|
||||
@@ -418,28 +440,39 @@ enum AgentGuide {
|
||||
A lane folder holds its own `index.md` beside its cards, so a glob
|
||||
sweeps the lane's identity file along with them and overwrites the
|
||||
destination lane's.
|
||||
- Reorder within a lane: rewrite only that card's `order`.
|
||||
- Reorder within a lane: rewrite only that card's `order` — don't touch
|
||||
`modified` or `modified-by`.
|
||||
|
||||
## Editing and deleting
|
||||
|
||||
- Edit bodies freely; update `modified` on every write. Preserve frontmatter
|
||||
keys you don't recognize and don't reformat content you didn't change.
|
||||
- **Delete a card = move it into `<board>/.trash/`**: `mv <lane>/<card-uuid>
|
||||
<board>/.trash/` (create `.trash/` if missing). Arrivals go on top: set
|
||||
the card's `order` to the smallest `order` already in `.trash/` minus
|
||||
1024 (empty trash: any number), and update `modified`. Restore is the
|
||||
same move in reverse — into a lane, with a fresh `order`.
|
||||
- **Delete a card or a lane = move its folder into `<board>/.trash/`**:
|
||||
`mv <lane>/<card-uuid> <board>/.trash/`, or `mv <lane-uuid>
|
||||
<board>/.trash/` for a whole lane (create `.trash/` if missing). A lane
|
||||
travels with its cards inside it. Arrivals go on top: set the moved
|
||||
item's `order` to the smallest `order` already in `.trash/` minus 1024
|
||||
(empty trash: any number). It's a container change like any other move
|
||||
(Moving and reordering above): stamp `modified` and re-stamp
|
||||
`modified-by`. Restore is the same move in reverse — a card into a lane,
|
||||
a lane back to board root, with a fresh `order`, stamped the same way.
|
||||
- **Stamp `kind: lane` when you trash a lane that lacks it.** `.trash/` is
|
||||
flat, so an empty lane folder looks exactly like a card folder; the `kind`
|
||||
value is what tells them apart in there.
|
||||
- Never write a `deleted:` key — that convention is retired; the app
|
||||
migrates any it finds.
|
||||
- Remove a folder outright (`rm -r`) only when you mean permanent,
|
||||
unrecoverable deletion. Lanes have no trash: deleting a lane folder is
|
||||
permanent, so be sure.
|
||||
unrecoverable deletion — the trash is the recoverable path for both
|
||||
cards and lanes.
|
||||
|
||||
## Attachments
|
||||
|
||||
- A card's files live in `attachments/` inside the card folder, flat at its
|
||||
top level. **Put files there, never beside `index.md`** — the app
|
||||
relocates loose files into `attachments/` and tells the user it did.
|
||||
The name `attachments` itself belongs to that folder — never create a
|
||||
*file* called `attachments` in a card; the app treats one as a defect
|
||||
and displaces it on sight.
|
||||
- To attach a file: create `attachments/` if missing and copy the file in.
|
||||
If the name is taken, pick a free one Finder-style (`shot.png` →
|
||||
`shot 2.png`) — never overwrite.
|
||||
|
||||
@@ -168,6 +168,27 @@ public enum BoardLoader: Sendable {
|
||||
// views over it (`LoadResult.looseCardFiles`, `.legacyTombstones`).
|
||||
var defects: [IntegrityRules.Defect] = []
|
||||
|
||||
// **The coerce tier's trace** (01-storage-format.md § Frontmatter, ruled 2026-07-29: "A
|
||||
// no-sensible-reading fallback logs: field, path, and raw text, carried as coerce-tier entries
|
||||
// in the integrity service's Defect stream"). Called once per document this walk parses, at
|
||||
// every level, because the rule is about *fields* and every level has them — and called here
|
||||
// rather than inside `readDocument` for the reason the whole defect stream lives in `load`: the
|
||||
// reading functions are pure and total, and the walk is what owns what it found.
|
||||
//
|
||||
// `logger.info`, not `warning`: the value rendered as its default, nothing is degraded, and the
|
||||
// line exists to be findable later rather than to be noticed now ("no banner, no behavior
|
||||
// change").
|
||||
func noteCoercions(in document: FrontmatterDocument, at path: String) {
|
||||
let fields = document.coercedFields
|
||||
guard !fields.isEmpty else { return }
|
||||
defects.append(.coercedFrontmatter(CoercedFrontmatter(path: path, fields: fields)))
|
||||
for field in fields {
|
||||
logger.info(
|
||||
"\(path, privacy: .public): '\(field.key, privacy: .public)' has no sensible reading — \(field.raw, privacy: .public) — rendering the field's default"
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// Detected before the walk, so a board whose `.trash` is squatted reports it even though
|
||||
// the trash read below finds nothing to parse. Read-only here, like every other detection:
|
||||
// the displacement is the store's, through the Writer (the Repair precedent).
|
||||
@@ -187,6 +208,8 @@ public enum BoardLoader: Sendable {
|
||||
warn(.boardLevelDeletedIgnored)
|
||||
}
|
||||
|
||||
noteCoercions(in: boardDocument, at: indexFileName)
|
||||
|
||||
// Every lane the walk read, in folder order — **not** `Lane` values yet. The board-wide
|
||||
// identity dedupe below decides which folders render at all, and a `Lane` is built only on
|
||||
// the far side of that decision, because a `Lane` carrying a withheld card would be exactly
|
||||
@@ -211,6 +234,7 @@ public enum BoardLoader: Sendable {
|
||||
let laneDocument = try readDocument(at: laneURL.appendingPathComponent(indexFileName), path: lanePath)
|
||||
let laneSchema = try validatedSchema(in: laneDocument, path: lanePath)
|
||||
let laneOrder = try validatedOrder(in: laneDocument, path: lanePath)
|
||||
noteCoercions(in: laneDocument, at: lanePath)
|
||||
|
||||
var cards: [Card] = []
|
||||
for cardURL in try directoryCandidates(in: laneURL) {
|
||||
@@ -226,6 +250,20 @@ public enum BoardLoader: Sendable {
|
||||
}
|
||||
|
||||
let card = try parseCard(at: cardURL, path: cardRelPath)
|
||||
noteCoercions(in: card.document, at: cardRelPath + "/" + indexFileName)
|
||||
|
||||
// **The card-level claimed name** (01-storage-format.md § Fractal layout ▸ Rules,
|
||||
// extended 2026-07-29 — "the rule is level-uniform"): a file or symlink wearing
|
||||
// `attachments` breaks every import into this card, every Finder drop on it and the
|
||||
// window's listing for as long as it stands, so it is scheduled work exactly as a
|
||||
// squatted `.trash` is. Detection is read-only here, like every other defect; the
|
||||
// displacement is the store's, through the Writer.
|
||||
for squatter in IntegrityRules.squattedClaimedNames(inCardAt: cardURL, path: cardRelPath) {
|
||||
defects.append(.claimedNameSquatted(squatter))
|
||||
logger.warning(
|
||||
"\(cardRelPath, privacy: .public)/\(squatter.name, privacy: .public): claimed name held by \(squatter.found.description, privacy: .public) — to be displaced"
|
||||
)
|
||||
}
|
||||
|
||||
// Noticed, never acted on: the relocation is the store's, through the Writer.
|
||||
let loose = looseFileNames(in: cardURL)
|
||||
@@ -287,6 +325,7 @@ public enum BoardLoader: Sendable {
|
||||
continue
|
||||
}
|
||||
let entry = try parseCard(at: cardURL, path: cardRelPath)
|
||||
noteCoercions(in: entry.document, at: cardRelPath + "/" + indexFileName)
|
||||
// **The trash's discriminator, applied where the flat container needs it**
|
||||
// (01-storage-format.md § Deletion, re-ruled 2026-07-29): the *value* is trusted
|
||||
// outright, and only an unrecognized value or no key at all falls through to shape.
|
||||
@@ -944,6 +983,17 @@ public struct LoadResult: Sendable {
|
||||
public var duplicateIdentities: [DuplicateIdentity] {
|
||||
defects.compactMap { if case let .duplicateIdentity(work) = $0 { work } else { nil } }
|
||||
}
|
||||
|
||||
/// Every file whose lenient fields fell back to their defaults — a **view over `defects`**
|
||||
/// (01-storage-format.md § Frontmatter, ruled 2026-07-29).
|
||||
///
|
||||
/// **Nothing consumes it, and that is the point**: the coerce tier changes no behavior, so this is
|
||||
/// the observability handle — a suite pins it, a developer reads the log lines it produced, and the
|
||||
/// day a shape shows up often enough to deserve a heuristic heal, this is where the evidence
|
||||
/// already is. In walk order: the board, then each lane and its cards, then the trash.
|
||||
public var coercedFrontmatter: [CoercedFrontmatter] {
|
||||
defects.compactMap { if case let .coercedFrontmatter(work) = $0 { work } else { nil } }
|
||||
}
|
||||
}
|
||||
|
||||
/// A tolerated anomaly the loader kept going past. Never blocks a load — see `BoardLoadError`
|
||||
|
||||
+274
-115
@@ -17,8 +17,10 @@ import Foundation
|
||||
/// and the body survive every write by construction rather than by remembering to preserve
|
||||
/// them.
|
||||
/// - **`modified` stamped, `modified-by` cleared** (§ Frontmatter): on every app-mediated write
|
||||
/// path. Absence of `modified-by` means "the board's user, via the app"; the file is being
|
||||
/// rewritten anyway, so clearing an external writer's self-reported stamp costs nothing.
|
||||
/// path that rewrites *content*. Absence of `modified-by` means "the board's user, via the app";
|
||||
/// the file is being rewritten anyway, so clearing an external writer's self-reported stamp costs
|
||||
/// nothing. The one class of write that does neither is the **order-only rewrite**
|
||||
/// (`WriteOperation.rewritesOrderOnly` — the reorders-don't-stamp rule).
|
||||
/// - **Encoding** (§ Fractal layout ▸ Rules): writes are BOM-less UTF-8; reads are strict
|
||||
/// UTF-8, and a file that does not decode is a loud, specific error rather than a
|
||||
/// lossy best guess.
|
||||
@@ -44,6 +46,26 @@ public enum BoardWriter: Sendable {
|
||||
/// two keys, and no call site has to remember them.
|
||||
/// 4. **Atomic replace.**
|
||||
///
|
||||
/// ## The reorders-don't-stamp predicate
|
||||
///
|
||||
/// Step 3 is **skipped for an order-only rewrite** (01-storage-format.md § Frontmatter ▸
|
||||
/// `modified`'s scope — ruled 2026-07-29 as moves-don't-stamp, refined 2026-07-30 to the
|
||||
/// container-change predicate). `order` is logically the *container's* property — a relationship
|
||||
/// among a lane's members that the format happens to store inside each member's file — so a
|
||||
/// rewrite that only restates position touches no content: no `modified` stamp, and no
|
||||
/// `modified-by` clear (the two are paired; attribution cannot change when content didn't).
|
||||
///
|
||||
/// **The predicate is the operation's, not a parameter** (`WriteOperation.rewritesOrderOnly`):
|
||||
/// the vocabulary already draws the line this rule needs — `.reorder` is by construction the
|
||||
/// same-container case (`moveItem` decides it from the two URLs before it touches disk) and
|
||||
/// `.renumberChildren` is the whole-lane rescale. Deriving it here rather than asking each call
|
||||
/// site means no caller can forget, and the rule stays one exhaustive switch a suite can pin
|
||||
/// without a filesystem.
|
||||
///
|
||||
/// **There is no trash branch anywhere**, deliberately: a move into or out of `.trash/` changes
|
||||
/// the item's container, so it stamps for the same reason a cross-lane move does. The trash move
|
||||
/// is the container rule's plainest instance rather than an exception to a rule about moves.
|
||||
///
|
||||
/// The **one path that deliberately bypasses this** is the card window's raw-source Apply
|
||||
/// (05-card-window.md): it writes the user's text byte-for-byte and does *not* clear a
|
||||
/// `modified-by` the user typed or kept — the validated-then-verbatim contract outranks the
|
||||
@@ -90,8 +112,13 @@ public enum BoardWriter: Sendable {
|
||||
// After `edits`, so a caller that wrote its own `kind` is left alone, and before the stamps,
|
||||
// which outrank everything for their own reason.
|
||||
IntegrityRules.healOnTouch(&document, kind: kind ?? derivedKind(ofItemFolder: folder))
|
||||
document.set(FrontmatterKeys.modified, to: .date(Date()))
|
||||
document.remove(FrontmatterKeys.modifiedBy)
|
||||
// The reorders-don't-stamp predicate, read off the operation. An order-only rewrite restates
|
||||
// the container's own arrangement and leaves both provenance keys exactly as it found them —
|
||||
// a standing `modified-by` survives a reorder, which is the pairing 01 spells out.
|
||||
if !operation.rewritesOrderOnly {
|
||||
document.set(FrontmatterKeys.modified, to: .date(Date()))
|
||||
document.remove(FrontmatterKeys.modifiedBy)
|
||||
}
|
||||
|
||||
try atomicReplace(text: document.serialized(), at: indexURL, operation: operation)
|
||||
}
|
||||
@@ -403,6 +430,12 @@ public enum BoardWriter: Sendable {
|
||||
/// - **Display order is the assignment order** (`Ranks.isOrderedForDisplay`: `order`
|
||||
/// ascending, folder name breaking ties) — the same rule the loader sorts by, so a
|
||||
/// renumber is guaranteed to be sequence-preserving: nothing visibly moves.
|
||||
/// - **Nothing is stamped.** A rescale is order-only, so no sibling's `modified` moves and no
|
||||
/// sibling's `modified-by` is cleared (01-storage-format.md § Ordering, verbatim: "order-only
|
||||
/// rewrites, so no `modified` stamp and no `modified-by` clear"). That falls out of
|
||||
/// `.renumberChildren` answering `rewritesOrderOnly` rather than being arranged here — which is
|
||||
/// what keeps a whole lane's worth of bookkeeping from looking like a whole lane's worth of
|
||||
/// edits to the card window, to a future auto-purge, and to an agent's own attribution.
|
||||
///
|
||||
/// Each child's rewrite is atomic; the batch is not. An interrupted renumber leaves some
|
||||
/// siblings renumbered and some not — every `order` still a valid float, display order
|
||||
@@ -498,10 +531,17 @@ public enum BoardWriter: Sendable {
|
||||
/// construction rather than by copying carefully.
|
||||
///
|
||||
/// Exactly one file is rewritten — the moved root's `index.md`, and only to carry its new
|
||||
/// `order` (§ Ordering, "a reorder rewrites only the moved item's `index.md`"), stamped and
|
||||
/// `modified-by`-cleared like every other app write. `order` is the caller's explicit rank
|
||||
/// (a drop between two siblings), or `nil` to append after the destination's visible
|
||||
/// siblings.
|
||||
/// `order` (§ Ordering, "a reorder rewrites only the moved item's `index.md`"). `order` is the
|
||||
/// caller's explicit rank (a drop between two siblings), or `nil` to append after the
|
||||
/// destination's visible siblings.
|
||||
///
|
||||
/// **Whether that rewrite stamps is the container question** (§ Frontmatter ▸ `modified`'s scope,
|
||||
/// refined 2026-07-30 — `WriteOperation.rewritesOrderOnly`), and this call is where it is
|
||||
/// answered for every move in the app: the same-parent degenerate path below is a `.reorder` and
|
||||
/// rewrites `order` alone, while a real move — cross-lane, cross-board, into or out of `.trash/`
|
||||
/// — is a `.move` and stamps `modified` and clears `modified-by` like any content write. The
|
||||
/// branch that already exists for the *rank arithmetic* is therefore the whole of the stamping
|
||||
/// rule too; there is no second test, and pointedly no trash case.
|
||||
///
|
||||
/// **The import boundary is the one place within-board uniqueness is enforced** (§ Fractal
|
||||
/// layout ▸ Rules). `sourceBoardRoot` and `destinationBoardRoot` are compared by resolved,
|
||||
@@ -762,23 +802,36 @@ public enum BoardWriter: Sendable {
|
||||
/// `Date` for the whole tree: a card made from a template is born today, not forked from
|
||||
/// the template (09-templates.md).
|
||||
///
|
||||
/// Two deliberate leniencies below the root, both of them "what a hand copy would do":
|
||||
/// Plus the tracker sever, which is the copy contract's third clause: every folder this
|
||||
/// materializes drops the reserved `remote`/`remote-state` keys, at every level
|
||||
/// (`applyCopyContract`).
|
||||
///
|
||||
/// - A nested `index.md` that is **readable-but-uneditable** (§ Frontmatter), or that cannot
|
||||
/// be read at all, is copied byte-verbatim and simply not stamped. Refusing an entire copy
|
||||
/// because one nested card is a flow mapping would be hostile, and the file arrives
|
||||
/// *exactly* as it was rather than corrupted — its stale `modified-by` attribution
|
||||
/// surviving is the self-reported-provenance honest limit § Frontmatter already
|
||||
/// acknowledges. The **root** gets no such leniency: it must be rewritten (it needs its
|
||||
/// new `order`), so an unreadable or uneditable root refuses the copy up front, before
|
||||
/// anything is materialized.
|
||||
/// - A nested UUID-shaped folder with **no `index.md`** — interrupted-create residue — is
|
||||
/// copied and reminted like any other, and not rewritten: the same skip the loader applies
|
||||
/// to it (`.missingIndex`).
|
||||
/// ## A copy is a transaction (ruled 2026-07-29)
|
||||
///
|
||||
/// **The whole subtree is preflighted for stampability before anything is materialized**, and a
|
||||
/// copy that cannot honor the contract on one nested card refuses whole, loudly, naming that card
|
||||
/// (01-storage-format.md § Frontmatter: "every copy flow that rewrites descendants' `index.md` …
|
||||
/// preflights the entire subtree and refuses whole, loudly, naming the offending item — never a
|
||||
/// partial copy, never a silently unstamped descendant").
|
||||
///
|
||||
/// This **retired the former root-strict/nested-lenient split**, which copied an unreadable or
|
||||
/// readable-but-uneditable nested `index.md` byte-verbatim and simply skipped its stamp. The
|
||||
/// leniency read as kindness and was in fact the one verdict 01's doctrine forbids: "leniency is
|
||||
/// recovering recoverable issues through reliable heuristics — never accepting loss that could
|
||||
/// surprise the user … 'proceed partially, lose a little' is never a verdict". A silently
|
||||
/// unstamped descendant carries a stale `modified-by` and, since 2026-07-29, a *live tracker
|
||||
/// claim* into a second local object — which is exactly the surprise. The finest-grain precedent
|
||||
/// covers identity collisions (a per-folder repair that loses nothing), not skipped contract work.
|
||||
///
|
||||
/// The preflight runs over the **source**, so a refusal costs nothing on disk: nothing is copied,
|
||||
/// nothing is renamed, nothing has to be cleaned up. A folder with **no `index.md`** —
|
||||
/// interrupted-create residue — is not an offense: it is copied and reminted like any other and
|
||||
/// simply has nothing to stamp, the same skip the loader applies to it (`.missingIndex`).
|
||||
///
|
||||
/// **All-or-nothing at the destination**, unlike a move: any failure once copying has begun
|
||||
/// removes the partially copied tree best-effort and rethrows, because a half-copied item is
|
||||
/// pure residue — nothing was there before, so there is no true state for a reload to show.
|
||||
/// pure residue — nothing was there before, so there is no true state for a reload to show. After
|
||||
/// a clean preflight the only thing left to fail is disk, and that is what this catch is for.
|
||||
/// The source is never touched on any path.
|
||||
public static func copyItem(
|
||||
at sourceFolder: URL,
|
||||
@@ -794,6 +847,9 @@ public enum BoardWriter: Sendable {
|
||||
// failure from here on in this call — including inside the materialized-but-not-yet-
|
||||
// stamped tree below — reuses the enriched value.
|
||||
operation = try checkIndexIsRewritable(inItemFolder: sourceFolder, operation: operation)
|
||||
// The transaction's preflight, over the *source*: a subtree that cannot honor the copy
|
||||
// contract refuses here, where nothing has been materialized and there is nothing to undo.
|
||||
try checkCopiedDescendantsAreStampable(of: sourceFolder, operation: operation)
|
||||
|
||||
let rank = try destinationOrder(order, inParent: destinationParent, operation: operation)
|
||||
|
||||
@@ -816,9 +872,7 @@ public enum BoardWriter: Sendable {
|
||||
|
||||
let now = Date()
|
||||
try updateIndex(inItemFolder: root, operation: operation) { document in
|
||||
if case .born = stamps {
|
||||
document.set(FrontmatterKeys.created, to: .date(now))
|
||||
}
|
||||
applyCopyContract(to: &document, stamps: stamps, now: now)
|
||||
document.set(FrontmatterKeys.order, to: .double(rank))
|
||||
}
|
||||
for folder in copied {
|
||||
@@ -864,13 +918,102 @@ public enum BoardWriter: Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
/// Stamps one copied folder below the root — best-effort by design (see `copyItem`): a
|
||||
/// missing, unreadable, or uneditable `index.md` is left exactly as the copy found it rather
|
||||
/// than failing the gesture. `order` is not touched: a nested item keeps its rank among its
|
||||
/// own siblings, which travelled with it.
|
||||
/// **The copy contract's frontmatter edits**, applied to every folder an item-level copy
|
||||
/// materializes — root and descendants alike, in one place so the two can never disagree about
|
||||
/// what a copy owes.
|
||||
///
|
||||
/// Two clauses, and `updateIndex` adds the third:
|
||||
///
|
||||
/// - **`created` per `stamps`** — `.fork` keeps it (a copy really was created when its original
|
||||
/// was), `.born` restamps it, because a board or card made from a template is born today
|
||||
/// (09-templates.md).
|
||||
/// - **The reserved tracker keys go** — `remote` and `remote-state`, at every level
|
||||
/// (01-storage-format.md § Fractal layout ▸ Rules, ruled 2026-07-29: "**Item-level copies sever
|
||||
/// tracker identity** … because two local objects must never both claim to be the same remote
|
||||
/// object"). Content preserved, mapping severed. Nothing reads the keys until Teams, and that is
|
||||
/// the argument rather than an objection: the copies made today are the boards Teams will meet,
|
||||
/// so the sever costs nothing now and spares a stale double-claim later. `FrontmatterDocument.remove`
|
||||
/// takes every occurrence, so a hand-duplicated key cannot leave a twin behind to resurrect the
|
||||
/// claim.
|
||||
/// - **`modified` stamped and `modified-by` cleared** come from `updateIndex`, because a copy is an
|
||||
/// app write like any other (§ Frontmatter) — not something this function has to remember.
|
||||
///
|
||||
/// `order` is deliberately absent: the copied *root* takes its new rank from its caller, and a
|
||||
/// nested item keeps its rank among its own siblings, which travelled with it.
|
||||
///
|
||||
/// **Whole-board forks do not call this at all** — Duplicate and Save as Template carry bytes
|
||||
/// verbatim, GUIDs, timestamps and tracker keys included (01 ▸ Identity lifecycle's carve-out).
|
||||
static func applyCopyContract(
|
||||
to document: inout FrontmatterDocument,
|
||||
stamps: CopyStamps,
|
||||
now: Date
|
||||
) {
|
||||
if case .born = stamps {
|
||||
document.set(FrontmatterKeys.created, to: .date(now))
|
||||
}
|
||||
document.remove(FrontmatterKeys.remote)
|
||||
document.remove(FrontmatterKeys.remoteState)
|
||||
}
|
||||
|
||||
/// **The copy transaction's preflight**: every identity-bearing folder beneath `folder` whose
|
||||
/// `index.md` the copy contract will rewrite, checked for readability and editability *before*
|
||||
/// anything is materialized — and the first offender refuses the whole copy, named
|
||||
/// (01-storage-format.md § Frontmatter, ruled 2026-07-29: "preflights the entire subtree and
|
||||
/// refuses whole, loudly, naming the offending item").
|
||||
///
|
||||
/// **Naming the offender is the point**, so the thrown error is re-enriched with *that* item's
|
||||
/// title rather than the copy root's: a refusal reading "Couldn't copy 'Sprint 12'" when the
|
||||
/// unwritable file is one card inside it would send the user looking in the wrong place. A file
|
||||
/// that cannot be read at all has no title to offer, and its path — which the error always
|
||||
/// carries — is then the whole of what can honestly be said about it.
|
||||
///
|
||||
/// **A folder with no `index.md` is not an offense** and is skipped: it is interrupted-create
|
||||
/// residue, the loader skips it too (`.missingIndex`), and there is no contract work to fail. The
|
||||
/// walk is `identityDescendants`', which is `remintDescendants`' own reach — so the set checked
|
||||
/// here is exactly the set that will be stamped, never a superset that could refuse a copy over a
|
||||
/// file nobody was going to touch.
|
||||
///
|
||||
/// **Internal rather than `private`**: template instantiation preflights its own tree with this,
|
||||
/// for `remintDescendants`' reason — one definition of what a copy owes its descendants.
|
||||
static func checkCopiedDescendantsAreStampable(
|
||||
of folder: URL,
|
||||
operation: WriteOperation
|
||||
) throws(BoardWriteError) {
|
||||
for descendant in identityDescendants(of: folder) {
|
||||
let indexURL = descendant.appendingPathComponent(BoardLoader.indexFileName)
|
||||
guard FileManager.default.fileExists(atPath: indexURL.path) else { continue }
|
||||
let document = try readDocument(at: indexURL, operation: operation)
|
||||
try checkEditable(document, at: indexURL, operation: operation.withTitle(document.title.value))
|
||||
}
|
||||
}
|
||||
|
||||
/// Every identity-bearing folder beneath `folder`, depth first — `remintDescendants`' walk with
|
||||
/// the renaming taken out, so the preflight and the remint can never disagree about which folders
|
||||
/// a copy materializes as items.
|
||||
private static func identityDescendants(of folder: URL) -> [URL] {
|
||||
var found: [URL] = []
|
||||
for child in childCandidates(of: folder) {
|
||||
found.append(child)
|
||||
found.append(contentsOf: identityDescendants(of: child))
|
||||
}
|
||||
return found
|
||||
}
|
||||
|
||||
/// Stamps one copied folder below the root — **strictly**, since the preflight has already cleared
|
||||
/// the whole subtree (`checkCopiedDescendantsAreStampable`): an `index.md` that cannot be read or
|
||||
/// edited here is a disk failure between the two reads, not a shape to tolerate, and it fails the
|
||||
/// copy like any other mid-flight failure (whose partial result the caller removes wholesale).
|
||||
///
|
||||
/// The former best-effort posture — copy it verbatim, skip its stamp — is retired with the
|
||||
/// root-strict/nested-lenient split (see `copyItem`): a silently unstamped descendant is a
|
||||
/// descendant still carrying somebody else's `modified-by` and, since 2026-07-29, somebody else's
|
||||
/// tracker claim.
|
||||
///
|
||||
/// A folder with **no `index.md`** is still skipped, and for a different reason entirely: there is
|
||||
/// nothing there to stamp (interrupted-create residue, which the loader skips too).
|
||||
///
|
||||
/// **Internal rather than `private`**, with `remintDescendants` and for its reason: an
|
||||
/// instantiated board's lanes and cards are stamped by this exact rule, leniency included.
|
||||
/// instantiated board's lanes and cards are stamped by this exact rule.
|
||||
static func stampCopiedDescendant(
|
||||
at folder: URL,
|
||||
stamps: CopyStamps,
|
||||
@@ -878,85 +1021,13 @@ public enum BoardWriter: Sendable {
|
||||
operation: WriteOperation
|
||||
) throws(BoardWriteError) {
|
||||
let indexURL = folder.appendingPathComponent(BoardLoader.indexFileName)
|
||||
guard FileManager.default.fileExists(atPath: indexURL.path),
|
||||
let copied = try? readDocument(at: indexURL, operation: operation),
|
||||
copied.uneditableShape == nil
|
||||
else { return }
|
||||
guard FileManager.default.fileExists(atPath: indexURL.path) else { return }
|
||||
|
||||
try updateIndex(inItemFolder: folder, operation: operation) { document in
|
||||
if case .born = stamps {
|
||||
document.set(FrontmatterKeys.created, to: .date(now))
|
||||
}
|
||||
applyCopyContract(to: &document, stamps: stamps, now: now)
|
||||
}
|
||||
}
|
||||
|
||||
/// Materializes an item from **supplied `index.md` text** rather than from a folder on disk —
|
||||
/// the clipboard's staging-less fallback (04-interactions.md ▸ Clipboard: "if the staged
|
||||
/// snapshot is missing or unreadable at paste time, paste falls back to the embedded
|
||||
/// `index.md` — content intact, attachments absent").
|
||||
///
|
||||
/// **The text is written byte-faithfully, because it *is* the source bytes.** It was captured
|
||||
/// verbatim at copy time and travels through the manifest untouched, so this call writes it as
|
||||
/// given — unknown keys, comments, blank lines, line endings, body and all — rather than
|
||||
/// re-serializing anything. That is the round-trip guarantee applied to a file the app is
|
||||
/// minting from bytes it was handed (01-storage-format.md § Fractal layout ▸ Rules).
|
||||
///
|
||||
/// **Fresh identity, fork stamps** — the same semantics `copyItem` gives an ordinary copy, and
|
||||
/// necessarily so: this is a copy that happened to arrive as text. Every folder is a fresh mint,
|
||||
/// `created` survives in the supplied bytes (a duplicate is a fork), and the root's `order` and
|
||||
/// `modified` are rewritten by the closing `updateIndex`, which also clears `modified-by`.
|
||||
///
|
||||
/// `children` are a **lane's** cards, each its own supplied `index.md`, materialized under the
|
||||
/// new root in the order given and deliberately *not* rewritten: "a nested item keeps its rank
|
||||
/// among its own siblings, which travelled with it" (`copyItem`'s rule). A card passes none.
|
||||
///
|
||||
/// **The root gets `copyItem`'s strictness and the children get its leniency.** The root must be
|
||||
/// rewritten — it needs its new `order` — so unparseable or uneditable text fails the call;
|
||||
/// a child is never rewritten, so whatever it is arrives exactly as it was.
|
||||
///
|
||||
/// **All-or-nothing at the destination**, `copyItem`'s rule for its reason: any failure once the
|
||||
/// folder exists removes the partial tree best-effort and rethrows, because a half-materialized
|
||||
/// item is pure residue — nothing was there before.
|
||||
public static func materializeItem(
|
||||
inParent destinationParent: URL,
|
||||
indexText: String,
|
||||
children: [String] = [],
|
||||
order: Double?
|
||||
) throws(BoardWriteError) -> ItemID {
|
||||
let operation = WriteOperation.copy(title: nil)
|
||||
try checkIsDirectory(destinationParent, describedAs: "destination parent folder", operation: operation)
|
||||
|
||||
let rank = try destinationOrder(order, inParent: destinationParent, operation: operation)
|
||||
|
||||
// The same mint the create path uses, so every identity this app materializes is materialized
|
||||
// one way — fresh lowercase UUIDv4, folder and all.
|
||||
let root = try mintUUIDFolder(in: destinationParent, operation: operation)
|
||||
|
||||
do throws(BoardWriteError) {
|
||||
try atomicReplace(
|
||||
text: indexText,
|
||||
at: root.appendingPathComponent(BoardLoader.indexFileName),
|
||||
operation: operation
|
||||
)
|
||||
for child in children {
|
||||
let childFolder = try mintUUIDFolder(in: root, operation: operation)
|
||||
try atomicReplace(
|
||||
text: child,
|
||||
at: childFolder.appendingPathComponent(BoardLoader.indexFileName),
|
||||
operation: operation
|
||||
)
|
||||
}
|
||||
try updateIndex(inItemFolder: root, operation: operation) { document in
|
||||
document.set(FrontmatterKeys.order, to: .double(rank))
|
||||
}
|
||||
} catch {
|
||||
try? FileManager.default.removeItem(at: root)
|
||||
throw error
|
||||
}
|
||||
|
||||
return ItemID(rawValue: root.lastPathComponent)
|
||||
}
|
||||
|
||||
// MARK: - The materialized trash
|
||||
|
||||
/// `<boardRoot>/.trash/` — the board's trash container, named but not created.
|
||||
@@ -994,10 +1065,13 @@ public enum BoardWriter: Sendable {
|
||||
/// *snapshot*, which the store holds and this stateless layer does not. Value-passing keeps
|
||||
/// the seam: the Writer takes a rank, the store computes it.
|
||||
///
|
||||
/// **The `modified` stamp is the point, not a side effect.** Deletion is the one exception to
|
||||
/// moves-don't-stamp — "deletion is an edit to the card's story" — and the stamp is what a
|
||||
/// future age-based auto-purge reads. It falls out of `updateIndex` here rather than being
|
||||
/// asked for, which is why there is nothing extra in step 5.
|
||||
/// **The `modified` stamp is the point, not a side effect** — and it needs no exception to earn
|
||||
/// it. The trash move changes the card's *container*, which is the whole predicate
|
||||
/// (`WriteOperation.rewritesOrderOnly`, refined 2026-07-30): "deletion is an edit to the item's
|
||||
/// story", so it stamps exactly as a cross-lane move does, and the stamp is what a future
|
||||
/// age-based auto-purge reads. It falls out of `updateIndex` here rather than being asked for,
|
||||
/// which is why there is nothing extra in step 5 — and why the reorders-don't-stamp rule needs no
|
||||
/// trash carve-out to coexist with this call.
|
||||
///
|
||||
/// **Collision inside `.trash/` is impossible by construction**, and it is checked anyway. The
|
||||
/// card is a resident of this very board, and board-wide uniqueness now spans lanes *and* the
|
||||
@@ -1358,8 +1432,8 @@ public enum BoardWriter: Sendable {
|
||||
/// trees.
|
||||
/// - **The bytes are written verbatim** — nothing is stamped, nothing is re-serialized, no
|
||||
/// `index.md` is parsed. This replays; it does not edit.
|
||||
/// - **All-or-nothing**: any failure removes the partial tree best-effort and rethrows, the
|
||||
/// `materializeItem` rule — a half-restored lane is pure residue, since nothing was there.
|
||||
/// - **All-or-nothing**: any failure removes the partial tree best-effort and rethrows,
|
||||
/// `copyItem`'s rule — a half-restored lane is pure residue, since nothing was there.
|
||||
///
|
||||
/// `folder`'s own name governs, not `snapshot.name`: a caller restoring to the path it removed
|
||||
/// passes the same URL, and the snapshot's name is carried for identification, not as an
|
||||
@@ -1533,8 +1607,8 @@ public enum BoardWriter: Sendable {
|
||||
/// Puts a removed item's folder back, at its own path and with its own bytes — the redo half of
|
||||
/// an undone create (13-native-undo.md ▸ Rules).
|
||||
///
|
||||
/// **The identity is the point.** `createLane`/`createCard` mint a fresh UUID and
|
||||
/// `materializeItem` mints a fresh one too, so neither can replay a create: redoing through them
|
||||
/// **The identity is the point.** `createLane`/`createCard` mint a fresh UUID, so they cannot
|
||||
/// replay a create: redoing through them
|
||||
/// would produce a *different* item, and every step registered above this one on the stack
|
||||
/// (a rename, a move, a body edit of that very card) would then name nothing. This call takes the
|
||||
/// path as given.
|
||||
@@ -1577,7 +1651,7 @@ public enum BoardWriter: Sendable {
|
||||
operation: operation
|
||||
)
|
||||
} catch {
|
||||
// `materializeItem`'s all-or-nothing rule: a half-made folder is pure residue, since
|
||||
// `copyItem`'s all-or-nothing rule: a half-made folder is pure residue, since
|
||||
// nothing was there before.
|
||||
try? FileManager.default.removeItem(at: itemFolder)
|
||||
throw error
|
||||
@@ -2178,6 +2252,14 @@ public enum BoardWriter: Sendable {
|
||||
/// **It stamps nothing.** A heal that only renames never opens an `index.md`, so the existing
|
||||
/// write discipline decides and there is no rule to add (§ Validation and healing).
|
||||
///
|
||||
/// **Level-uniform** (extended 2026-07-29): the squatter's own `location` names the folder the
|
||||
/// claimed name lives in — the board root, or a card's folder for a file wearing `attachments`. That
|
||||
/// is the whole of the difference, which is the point of the ruling: one ladder, one notice, one
|
||||
/// write, whichever level the name is claimed at. A card whose folder has since gone takes the
|
||||
/// re-verification's `nil` path like any other vanished defect.
|
||||
///
|
||||
/// - Parameter root: the board root. The squatter's location is resolved against it, so a board
|
||||
/// renamed since the load heals at its new location.
|
||||
/// - Returns: the name the squatter now has, or `nil` when the defect was already gone.
|
||||
@discardableResult
|
||||
public static func displaceClaimedName(
|
||||
@@ -2185,13 +2267,14 @@ public enum BoardWriter: Sendable {
|
||||
atBoardRoot root: URL
|
||||
) throws(BoardWriteError) -> String? {
|
||||
let operation = WriteOperation.displaceClaimedName(name: squatter.name)
|
||||
let occupied = root.appendingPathComponent(squatter.name)
|
||||
let container = squatter.location.folder(under: root)
|
||||
let occupied = container.appendingPathComponent(squatter.name)
|
||||
guard let found = IntegrityRules.node(at: occupied), found != squatter.expected else {
|
||||
return nil
|
||||
}
|
||||
|
||||
let freed = freshName(for: squatter.name, in: root)
|
||||
let destination = root.appendingPathComponent(freed)
|
||||
let freed = freshName(for: squatter.name, in: container)
|
||||
let destination = container.appendingPathComponent(freed)
|
||||
do {
|
||||
try FileManager.default.moveItem(at: occupied, to: destination)
|
||||
} catch {
|
||||
@@ -2565,6 +2648,23 @@ public enum WriteOperation: Sendable, Equatable, CustomStringConvertible {
|
||||
case move(title: String?)
|
||||
case reorder(title: String?)
|
||||
case copy(title: String?)
|
||||
|
||||
/// ⌘V — **a paste that refused before it wrote anything** (04-interactions.md ▸ Clipboard,
|
||||
/// re-ruled 2026-07-29: "A paste whose staged snapshot is missing or unreadable refuses loudly —
|
||||
/// never degrades … the paste produces **nothing**, and a one-shot failure banner names it from
|
||||
/// the manifest's metadata").
|
||||
///
|
||||
/// **Its own case rather than a fold into `.copy`**, on `.rename`'s and `.duplicateBoard`'s
|
||||
/// reasoning: the user pressed *Paste*, and a banner telling them the app "couldn't copy 'Fix
|
||||
/// login'" would name a gesture they never made. It is also the one operation in this vocabulary
|
||||
/// the Writer itself never performs — a paste's *arrivals* are `.copy` and `.move` — because the
|
||||
/// refusal happens at the clipboard's preflight, before any arrival is materialized; the
|
||||
/// vocabulary grows with the surfaces, and the surface here is the refusal.
|
||||
///
|
||||
/// `title` is the offending entry's, read off the manifest's own metadata (which is exactly what
|
||||
/// the embedded `index.md` is kept for now that it is never a materialization source), `nil` for
|
||||
/// an untitled item.
|
||||
case paste(title: String?)
|
||||
/// ⌫ / ⌘⌫ — a card moving into `.trash/` (`deleteCardToTrash`) or a lane being removed
|
||||
/// outright (`removeLane`). The word the user pressed, whichever staging it took.
|
||||
///
|
||||
@@ -2733,6 +2833,10 @@ public enum WriteOperation: Sendable, Equatable, CustomStringConvertible {
|
||||
case .move: .move(title: title)
|
||||
case .reorder: .reorder(title: title)
|
||||
case .copy: .copy(title: title)
|
||||
// Identity, like `.repairDuplicateID` and for its reason: a refused paste never opens an
|
||||
// `index.md`, so there is no `readDocument` to enrich from — its title arrives already filled
|
||||
// in from the manifest entry the refusal names.
|
||||
case .paste: self
|
||||
case .delete: .delete(title: title)
|
||||
case .purge: .purge(title: title)
|
||||
case .migrateTombstone: .migrateTombstone(title: title)
|
||||
@@ -2747,6 +2851,46 @@ public enum WriteOperation: Sendable, Equatable, CustomStringConvertible {
|
||||
}
|
||||
}
|
||||
|
||||
/// **Whether this rewrite only restates the item's position among its container's members** —
|
||||
/// the reorders-don't-stamp predicate (01-storage-format.md § Frontmatter ▸ `modified`'s scope,
|
||||
/// ruled 2026-07-29 as moves-don't-stamp, refined 2026-07-30).
|
||||
///
|
||||
/// One question decides it: **does the rewrite change the item's container?** If it does — a
|
||||
/// cross-lane move, a cross-board arrival, a move into or out of `.trash/` — the item's story
|
||||
/// changed (which lane a card lives in is state) and the write stamps `modified` and clears
|
||||
/// `modified-by` like any content write. If it does not — a card reordered among its lane's
|
||||
/// siblings, a lane reordered on the board, a renumber's whole-lane rescale — only `order` is
|
||||
/// rewritten: no stamp, no clear. Where an item *stands in line* is presentation, and `order` is
|
||||
/// logically the container's property that the format happens to store inside the member's file.
|
||||
///
|
||||
/// **The vocabulary already draws the line**, which is why this is a property here rather than a
|
||||
/// flag threaded through `updateIndex`'s call sites:
|
||||
///
|
||||
/// - `.reorder` is the same-container case by construction — `moveItem` decides it from the source
|
||||
/// parent and the destination parent before it touches disk (`isSameLocation`), and the two
|
||||
/// inverse paths that rewrite a rank directly (`BoardStore.setOrder`, the within-lane sort) are
|
||||
/// same-container for the same reason: a lane's parent is the board root, and a card the sort
|
||||
/// permutes never leaves its lane.
|
||||
/// - `.renumberChildren` is the midpoint-exhaustion rescale — "order-only rewrites, so no
|
||||
/// `modified` stamp and no `modified-by` clear" (01 § Ordering, verbatim).
|
||||
/// - **Everything else stamps.** `.move` covers every container change including the trash's, and
|
||||
/// there is deliberately **no trash case anywhere**: the trash move stamps because every
|
||||
/// container change stamps, so a branch for it would be a second rule saying the same thing.
|
||||
///
|
||||
/// Exhaustive with no `default`, like every other switch over this enum: a new operation has to
|
||||
/// answer "does this rewrite content?" before it compiles.
|
||||
public var rewritesOrderOnly: Bool {
|
||||
switch self {
|
||||
case .reorder, .renumberChildren:
|
||||
true
|
||||
case .createBoard, .createLane, .createCard, .move, .copy, .delete, .purge, .migrateTombstone,
|
||||
.style, .resize, .rename, .duplicateBoard, .saveAsTemplate, .paste, .importAttachment,
|
||||
.listAttachments, .removeAttachment, .relocateLooseFile, .agentGuide, .displaceClaimedName,
|
||||
.repairDuplicateID, .toggleTask, .editBody, .rawSource:
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
/// A short imperative phrase — `"move 'Fix login'"`, `"create card"`, `"import attachment
|
||||
/// 'photo.png'"` — for logs and diagnostics **only**: `BoardWriteError.description` (test
|
||||
/// failures, `po error`, console output), never the banner's text. The banner owns every
|
||||
@@ -2761,6 +2905,7 @@ public enum WriteOperation: Sendable, Equatable, CustomStringConvertible {
|
||||
case let .move(title): Self.phrase("move", title)
|
||||
case let .reorder(title): Self.phrase("reorder", title)
|
||||
case let .copy(title): Self.phrase("copy", title)
|
||||
case let .paste(title): Self.phrase("paste", title)
|
||||
case let .delete(title): Self.phrase("delete", title)
|
||||
case let .purge(title): Self.phrase("purge", title)
|
||||
case let .migrateTombstone(title): Self.phrase("migrate the legacy 'deleted' key on", title)
|
||||
@@ -2844,6 +2989,18 @@ public struct BoardWriteError: Error, Sendable, Equatable, CustomStringConvertib
|
||||
/// the *proposal* is not, so nothing was attempted and nothing changed.
|
||||
case invalidSource(BoardLoadError)
|
||||
|
||||
/// **The bytes a paste was to reproduce are not there** — the staged clipboard snapshot is
|
||||
/// missing or unreadable, so the paste produces nothing rather than a hollowed item
|
||||
/// (04-interactions.md ▸ Clipboard, re-ruled 2026-07-29 — Finder's invariant, and 01's
|
||||
/// leniency doctrine: "proceed partially, lose a little" is never a verdict).
|
||||
///
|
||||
/// **Payload-free on purpose.** There is exactly one thing to say about it, the banner owns
|
||||
/// the words (`BannerCenter.causePhrase`), and the offending item is already named by the
|
||||
/// operation's own title — so a free-form message here could only be a second, worse copy of
|
||||
/// a sentence that lives one layer up. That also keeps it distinct from `.unreadable`, whose
|
||||
/// message is a developer's diagnostic about a file the app *did* open.
|
||||
case clipboardContentGone
|
||||
|
||||
public var description: String {
|
||||
switch self {
|
||||
case let .unreadable(message):
|
||||
@@ -2856,6 +3013,8 @@ public struct BoardWriteError: Error, Sendable, Equatable, CustomStringConvertib
|
||||
message
|
||||
case let .invalidSource(error):
|
||||
"the source text wouldn't load: \(error.description)"
|
||||
case .clipboardContentGone:
|
||||
"the copied content is no longer staged"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -573,6 +573,22 @@ public enum FrontmatterKeys {
|
||||
/// when absent (`IntegrityRules.healOnTouch`), and never stripped.
|
||||
public static let kind = "kind"
|
||||
|
||||
/// The reserved tracker keys — `remote` (board, card) and `remote-state` (lane) — of the enhanced
|
||||
/// schema's future connectors (01-storage-format.md § Enhanced schema).
|
||||
///
|
||||
/// **Named here without joining `schemaOwned`**, which is the ruling rather than an oversight: 01
|
||||
/// says the app "treats reserved keys as ordinary unknown keys (preserved verbatim, invisible in
|
||||
/// the UI)", and `schemaOwned` is exactly the set `unknownFields` subtracts. Nothing about their
|
||||
/// ordinary posture changes.
|
||||
///
|
||||
/// They are named at all because of the one act that does touch them: **an item-level copy severs
|
||||
/// tracker identity** (§ Fractal layout ▸ Rules, ruled 2026-07-29) — "two local objects must never
|
||||
/// both claim to be the same remote object" — so every folder a paste, an ⌥-drag duplicate, a
|
||||
/// cross-board copy or a template instantiation materializes drops both keys, at every level.
|
||||
/// Whole-board forks (Duplicate, Save as Template) carry them verbatim, as always.
|
||||
public static let remote = "remote"
|
||||
public static let remoteState = "remote-state"
|
||||
|
||||
public static let schemaOwned: Set<String> = [
|
||||
schema, title, order, width, created, modified, modifiedBy, deleted, background, icon,
|
||||
iconColor, kind,
|
||||
|
||||
@@ -39,7 +39,69 @@ public enum FieldValue<Value: Sendable & Equatable>: Sendable, Equatable {
|
||||
}
|
||||
}
|
||||
|
||||
/// One **lenient** field that had no sensible reading and fell back to its default — the coerce
|
||||
/// tier's observability record (01-storage-format.md § Frontmatter, ruled 2026-07-29: "A
|
||||
/// no-sensible-reading fallback logs: field, path, and raw text, carried as coerce-tier entries in the
|
||||
/// integrity service's Defect stream").
|
||||
///
|
||||
/// **Two of the three facts, because this layer only has two.** `FrontmatterFields` is a pure reading
|
||||
/// of one document's bytes and has no idea which file it came from, so the *path* is attached by the
|
||||
/// loader, which does (`CoercedFrontmatter`). Threading a path down here to satisfy the record's shape
|
||||
/// would put filesystem context into the one layer that is deliberately free of it.
|
||||
public struct CoercedField: Sendable, Equatable {
|
||||
/// The frontmatter key, as the schema spells it.
|
||||
public let key: String
|
||||
/// The value exactly as written — the raw source span, which is the only form worth recording:
|
||||
/// this exists so that a shape observed in the wild can later be promoted to a heuristic heal, and
|
||||
/// a normalized rendering of a value nobody could read would defeat that.
|
||||
public let raw: String
|
||||
|
||||
public init(key: String, raw: String) {
|
||||
self.key = key
|
||||
self.raw = raw
|
||||
}
|
||||
}
|
||||
|
||||
extension FrontmatterDocument {
|
||||
|
||||
// MARK: - The coerce tier's own report
|
||||
|
||||
/// Every **lenient** field in this document that had no sensible reading, in schema order — the
|
||||
/// coerce tier's whole observability contribution (01-storage-format.md § Frontmatter, ruled
|
||||
/// 2026-07-29: "the family posture: every silent recovery leaves a trace").
|
||||
///
|
||||
/// **Read-side only, and nothing branches on it.** The values still render as their defaults —
|
||||
/// untitled placeholder, width 1, no color, no icon, no timestamp — the bytes on disk are still
|
||||
/// preserved verbatim, and no banner is raised. The list exists so the fallback is *visible*: it is
|
||||
/// "the one place where an observed-in-the-wild shape can later be promoted to a heuristic heal or
|
||||
/// a notice".
|
||||
///
|
||||
/// **The strict fields are absent, and so is `deleted`.** `schema` and `order` are the *refuse*
|
||||
/// tier — a malformed one fails the load loudly (`IntegrityRules.validatedSchema`/`validatedOrder`),
|
||||
/// so there is no silent recovery to leave a trace of. `deleted` is the odd one out on purpose: its
|
||||
/// rule is *presence, not validity* (a malformed `deleted` still deletes — `Lane`/`Card.isDeleted`),
|
||||
/// so nothing falls back to a default and the migration reports it under its own defect anyway.
|
||||
///
|
||||
/// A document whose fields all read cleanly answers `[]`, which is the overwhelmingly common case
|
||||
/// and costs one pass over the lenient fields.
|
||||
public var coercedFields: [CoercedField] {
|
||||
var found: [CoercedField] = []
|
||||
func record(_ key: String, _ field: FieldValue<some Sendable & Equatable>) {
|
||||
guard let raw = field.rawText else { return }
|
||||
found.append(CoercedField(key: key, raw: raw))
|
||||
}
|
||||
record(FrontmatterKeys.title, title)
|
||||
record(FrontmatterKeys.width, width)
|
||||
record(FrontmatterKeys.created, created)
|
||||
record(FrontmatterKeys.modified, modified)
|
||||
record(FrontmatterKeys.modifiedBy, modifiedBy)
|
||||
record(FrontmatterKeys.background, background)
|
||||
record(FrontmatterKeys.icon, icon)
|
||||
record(FrontmatterKeys.iconColor, iconColor)
|
||||
record(FrontmatterKeys.kind, kind)
|
||||
return found
|
||||
}
|
||||
|
||||
// MARK: - Strict (structure — the loader fails fast on `.malformed`)
|
||||
|
||||
public var schema: FieldValue<Int> {
|
||||
|
||||
@@ -182,6 +182,30 @@ public enum IntegrityRules: Sendable {
|
||||
ClaimedName(name: ".gitignore", expected: .file, displacesSquatters: false),
|
||||
]
|
||||
|
||||
/// **The card-level claimed names** — the same table one level down (01-storage-format.md § Fractal
|
||||
/// layout ▸ Rules, extended 2026-07-29: "**The rule is level-uniform**: a card's reserved child
|
||||
/// names are claimed the same way — a regular file or symlink squatting `attachments` (a directory
|
||||
/// name) displaces by the same ladder (`attachments` → `attachments 2`), so imports, Finder drops,
|
||||
/// and the sidebar listing never fail one gesture at a time against a squatted name").
|
||||
///
|
||||
/// **`attachments` displaces; `comments` does not**, and the split is the *timing principle*
|
||||
/// rather than a hedge — 01 calls the reserved-but-unconsumed `comments` "the timing principle's own
|
||||
/// illustration": nothing reads that name until the tracker era, so a wrong-kind holder degrades no
|
||||
/// behavior while it stands and stays a **tolerated stray** today, joining the scheduled class the
|
||||
/// day the name becomes load-bearing. `attachments`, by contrast, is load-bearing now: while a file
|
||||
/// wears the name, every import into that card, every Finder drop on it, and the card window's
|
||||
/// listing are broken — which is exactly the "proactive when the defect is load-bearing now"
|
||||
/// condition (§ Validation and healing).
|
||||
///
|
||||
/// `index.md` is deliberately not here. It is not a *reserved child* the app protects from
|
||||
/// squatters — it is the card's content, and a directory named `index.md` makes the folder an
|
||||
/// index-less stray the loader already skips with a warning (§ Fractal layout ▸ Rules). Displacing it
|
||||
/// would mean the app deciding a folder's content is a squatter.
|
||||
public static let claimedCardChildNames: [ClaimedName] = [
|
||||
ClaimedName(name: attachmentsFolderName, expected: .directory, displacesSquatters: true),
|
||||
ClaimedName(name: "comments", expected: .directory, displacesSquatters: false),
|
||||
]
|
||||
|
||||
/// The claimed names as the lane walk needs them: lowercased, for a `contains` against a
|
||||
/// directory entry. Compared lowercased for `reservedCardChildNames`' reason.
|
||||
public static let claimedRootNameSet: Set<String> = Set(claimedRootNames.map { $0.name.lowercased() })
|
||||
@@ -222,6 +246,38 @@ public enum IntegrityRules: Sendable {
|
||||
return ClaimedNameSquatter(name: claimed.name, found: found, expected: claimed.expected)
|
||||
}
|
||||
|
||||
/// The claimed-name defects inside one **card** folder — the level-uniform half of the same ruling
|
||||
/// (`claimedCardChildNames`, extended 2026-07-29).
|
||||
///
|
||||
/// Only names whose `displacesSquatters` is `true` can produce one, which today means `attachments`
|
||||
/// and only `attachments`: a `comments` held by the wrong kind of node is a tolerated stray until
|
||||
/// the feature consumes the name.
|
||||
///
|
||||
/// **A plural answer, unlike the board root's**, because the reason the root's is singular does not
|
||||
/// apply here: there, the second displacing name (`CLAUDE.md`) is the agent guide's own to heal, so
|
||||
/// answering it twice would be two mechanisms racing one node. Nothing else owns a card's children,
|
||||
/// so this returns every offender it finds and the table stays the only thing to edit when
|
||||
/// `comments` graduates.
|
||||
///
|
||||
/// - Parameter path: the card folder's path **relative to the board root**, carried into the defect
|
||||
/// so the write lands wherever the board lives at heal time (`LooseCardFiles`' convention).
|
||||
public static func squattedClaimedNames(inCardAt cardFolder: URL, path: String) -> [ClaimedNameSquatter] {
|
||||
claimedCardChildNames.compactMap { claimed in
|
||||
guard claimed.displacesSquatters,
|
||||
let found = node(at: cardFolder.appendingPathComponent(claimed.name)),
|
||||
found != claimed.expected
|
||||
else {
|
||||
return nil
|
||||
}
|
||||
return ClaimedNameSquatter(
|
||||
name: claimed.name,
|
||||
found: found,
|
||||
expected: claimed.expected,
|
||||
location: .card(path: path)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Object kinds
|
||||
|
||||
/// The kinds the schema knows (01-storage-format.md § Frontmatter ▸ Common to all levels, the
|
||||
@@ -454,6 +510,20 @@ public enum IntegrityRules: Sendable {
|
||||
/// and reminted by the scheduled heal (re-ruled 2026-07-29 — the silent remint).
|
||||
case duplicateIdentity(DuplicateIdentity)
|
||||
|
||||
/// **A coerce-tier fallback**: one file's lenient fields that had no sensible reading and
|
||||
/// rendered as their defaults (ruled 2026-07-29 — "A no-sensible-reading fallback logs: field,
|
||||
/// path, and raw text, carried as coerce-tier entries in the integrity service's Defect
|
||||
/// stream").
|
||||
///
|
||||
/// **The one case in this enum that is not work**, which is the ruling rather than a
|
||||
/// contradiction: the design puts coerce-tier fallbacks in *this* stream on purpose, because
|
||||
/// this is where "an observed-in-the-wild shape can later be promoted to a heuristic heal or a
|
||||
/// notice" — and the promotion would happen right here, by giving the case a heal class. Until
|
||||
/// then it has none (`healClass` answers `nil`), raises no banner, and changes no behavior: the
|
||||
/// value already rendered as its default and the bytes on disk are untouched. It is
|
||||
/// observability, carried in the vocabulary that would act on it if the app ever decided to.
|
||||
case coercedFrontmatter(CoercedFrontmatter)
|
||||
|
||||
/// The scheduled-heal classes, which are also the engine's memo keys and its
|
||||
/// banner-posture rows (`HealScheduler`).
|
||||
///
|
||||
@@ -470,12 +540,18 @@ public enum IntegrityRules: Sendable {
|
||||
case staleAgentGuide
|
||||
}
|
||||
|
||||
public var healClass: Class {
|
||||
/// The scheduled-heal class this defect belongs to, or **`nil` where there is no heal** — the
|
||||
/// coerce tier (`coercedFrontmatter`), which is carried for observability and acted on by
|
||||
/// nothing. Optional rather than a synthetic class, because a class *is* a memo key and a
|
||||
/// banner-posture row in the engine (`HealScheduler`): inventing one for work that does not
|
||||
/// exist would arm a memo against a repair nobody wrote.
|
||||
public var healClass: Class? {
|
||||
switch self {
|
||||
case .looseCardFiles: .looseCardFiles
|
||||
case .legacyTombstone: .legacyTombstone
|
||||
case .claimedNameSquatted: .claimedNameSquatted
|
||||
case .duplicateIdentity: .duplicateIdentity
|
||||
case .coercedFrontmatter: nil
|
||||
}
|
||||
}
|
||||
|
||||
@@ -495,13 +571,21 @@ public enum IntegrityRules: Sendable {
|
||||
case let .claimedNameSquatted(work):
|
||||
// The node *kind* is part of the picture: a squatter replaced by a different kind
|
||||
// of squatter is a new defect, and a heal that failed on one has no claim to have
|
||||
// failed on the other.
|
||||
["claimed:\(work.name):\(work.found.rawValue)"]
|
||||
// failed on the other. The location leads, so two cards squatting `attachments` are two
|
||||
// pieces of work — and a board-root squatter signs exactly as it always did.
|
||||
["claimed:\(work.location.signatureComponent)\(work.name):\(work.found.rawValue)"]
|
||||
case let .duplicateIdentity(work):
|
||||
// The *identity* is part of the picture beside the path: the same folder losing a
|
||||
// different collision (its winner reminted, a third copy landing) is new work, and a
|
||||
// heal that failed on one has no claim to have failed on the other.
|
||||
["duplicate:\(work.path):\(work.identity)"]
|
||||
case let .coercedFrontmatter(work):
|
||||
// One signature per field, `looseCardFiles`' shape: the unit of the observation is a
|
||||
// field, and a file whose `width` healed while its `icon` did not is a changed picture.
|
||||
// Nothing memoizes these today — there is no heal to guard — but a signature is what a
|
||||
// defect *is* in this vocabulary, and omitting it would make this case the one members
|
||||
// of the stream cannot be compared by.
|
||||
work.fields.map { "coerce:\(work.path):\($0.key)" }
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -805,18 +889,59 @@ public struct LegacyTombstone: Sendable, Equatable {
|
||||
/// **An invalid artifact, not a resident.** The heal moves it aside via the Finder-style rename
|
||||
/// ladder (`.trash` → `.trash 2`), preserved verbatim and never destroyed, with a warning-tone
|
||||
/// notice naming old and new — the invariant that survives is displacement-never-destruction.
|
||||
/// **The rule is level-uniform** (extended 2026-07-29): a card's `attachments` is claimed exactly as the
|
||||
/// board root's `.trash` is, and displaces by the same ladder — which is why `location` exists rather
|
||||
/// than a second defect type. The heals compose: the displaced file, now an ordinary loose file, rides
|
||||
/// the next loose-file relocation into the real `attachments/`.
|
||||
public struct ClaimedNameSquatter: Sendable, Equatable {
|
||||
/// The claimed name, exactly as the app spells it (`.trash`, `CLAUDE.md`).
|
||||
|
||||
/// **Which claimed name this is** — the board root's, or one card's reserved child.
|
||||
///
|
||||
/// A path rather than a URL, relative to the board root, so the heal joins it onto the store's
|
||||
/// *current* root and a board renamed mid-session heals at its new location (`LooseCardFiles`' and
|
||||
/// `IdentityOccurrence.path`'s convention).
|
||||
public enum Location: Sendable, Equatable {
|
||||
case boardRoot
|
||||
case card(path: String)
|
||||
|
||||
/// The folder the claimed name lives in, under `root`.
|
||||
public func folder(under root: URL) -> URL {
|
||||
switch self {
|
||||
case .boardRoot: root
|
||||
case let .card(path): root.appendingPathComponent(path, isDirectory: true)
|
||||
}
|
||||
}
|
||||
|
||||
/// The location as a signature component — `""` for the board root, so the existing root-level
|
||||
/// signature spelling is unchanged and only a card-level defect adds a path segment.
|
||||
var signatureComponent: String {
|
||||
switch self {
|
||||
case .boardRoot: ""
|
||||
case let .card(path): path + "/"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The claimed name, exactly as the app spells it (`.trash`, `CLAUDE.md`, `attachments`).
|
||||
public let name: String
|
||||
/// What is actually sitting there — never followed if it is a symlink.
|
||||
public let found: IntegrityRules.NodeKind
|
||||
/// What the app needs the name to be.
|
||||
public let expected: IntegrityRules.NodeKind
|
||||
/// Where the name lives. Defaults to the board root, which is where every squatter was before the
|
||||
/// rule went level-uniform — so the root-level call sites and their tests read exactly as they did.
|
||||
public let location: Location
|
||||
|
||||
public init(name: String, found: IntegrityRules.NodeKind, expected: IntegrityRules.NodeKind) {
|
||||
public init(
|
||||
name: String,
|
||||
found: IntegrityRules.NodeKind,
|
||||
expected: IntegrityRules.NodeKind,
|
||||
location: Location = .boardRoot
|
||||
) {
|
||||
self.name = name
|
||||
self.found = found
|
||||
self.expected = expected
|
||||
self.location = location
|
||||
}
|
||||
}
|
||||
|
||||
@@ -855,6 +980,33 @@ public struct DuplicateIdentity: Sendable, Equatable {
|
||||
}
|
||||
}
|
||||
|
||||
/// One file's **coerce-tier fallbacks**: the lenient fields whose value had no sensible reading, so the
|
||||
/// field rendered as its default (01-storage-format.md § Frontmatter, ruled 2026-07-29: "A
|
||||
/// no-sensible-reading fallback logs: field, path, and raw text, carried as coerce-tier entries in the
|
||||
/// integrity service's Defect stream — the one place where an observed-in-the-wild shape can later be
|
||||
/// promoted to a heuristic heal or a notice; no banner, no behavior change").
|
||||
///
|
||||
/// **Per file, not per field** — `LooseCardFiles`' shape and for its reason: the walk meets a document
|
||||
/// once and reads all of its fields there, so one record per `index.md` is what the loader naturally
|
||||
/// has, and a caller that wants per-field granularity has `fields` (and the per-field `signatures`).
|
||||
///
|
||||
/// The path is root-relative, as every load-side path in this app is (`BoardLoadError.path`,
|
||||
/// `IdentityOccurrence.path`) — it names the `index.md`, because that is the file whose bytes were
|
||||
/// read and the thing a developer would open.
|
||||
public struct CoercedFrontmatter: Sendable, Equatable {
|
||||
/// The `index.md`'s path relative to the board root — `"index.md"`, `"<lane>/index.md"`,
|
||||
/// `"<lane>/<card>/index.md"`, `".trash/<card>/index.md"`.
|
||||
public let path: String
|
||||
/// The fields that fell back, in schema order. Never empty — a document that read cleanly
|
||||
/// contributes no defect at all.
|
||||
public let fields: [CoercedField]
|
||||
|
||||
public init(path: String, fields: [CoercedField]) {
|
||||
self.path = path
|
||||
self.fields = fields
|
||||
}
|
||||
}
|
||||
|
||||
/// A folder whose name is a **case-spelled twin** of another occurrence of the same identity — one
|
||||
/// item typed two ways, not two items (01-storage-format.md § Fractal layout ▸ Rules: "the canonical
|
||||
/// all-lowercase spelling wins where present, else the lexicographically first spelling; the loser
|
||||
|
||||
@@ -452,7 +452,8 @@ struct BoardView: View {
|
||||
slotWidth: slotWidth,
|
||||
drops: dropContext,
|
||||
marquee: marqueeControl,
|
||||
openCard: openCard
|
||||
openCard: openCard,
|
||||
confirmations: confirmations
|
||||
)
|
||||
.frame(width: resizing ? resize.liveWidth : slotWidth, alignment: .leading)
|
||||
}
|
||||
|
||||
@@ -26,11 +26,17 @@ import SwiftUI
|
||||
/// Plus the two that are not about editing: Finder file drops are inert over the trash (▸ The trash),
|
||||
/// so the file-hover highlight is board-only; and the trash's context-menu Delete is *permanent*, so
|
||||
/// it needs the window's confirmation host (11-command-nexus.md ▸ Context menus' Trash cards row).
|
||||
///
|
||||
/// **Both sides carry the confirmation host now** (settled — Delete's ⌥-alternate, Delete
|
||||
/// Immediately, 11-command-nexus.md ▸ Context menus' Card row): the board side's Delete stays the
|
||||
/// ordinary staged move, but the alternate skips straight to the permanent purge, which needs the
|
||||
/// same window-level alert the trash side's Delete already does (`TrashConfirmations`).
|
||||
enum CardFaceRole {
|
||||
|
||||
/// A card in a lane. Carries the board window's card opener — ⌘↩'s pointer twin
|
||||
/// (04-interactions.md ▸ Selection).
|
||||
case board(openCard: (ItemID) -> Void)
|
||||
/// (04-interactions.md ▸ Selection) — and the window's purge-alert host, for Delete's
|
||||
/// ⌥-alternate.
|
||||
case board(openCard: (ItemID) -> Void, confirmations: TrashConfirmations)
|
||||
|
||||
/// A card in `<root>/.trash/`. Carries the window's purge-alert host, because the trash's Delete
|
||||
/// is the permanent one and "confirms exactly where the loss is real" (03 § Trash).
|
||||
@@ -143,7 +149,7 @@ struct CardFaceView: View {
|
||||
@ViewBuilder
|
||||
var body: some View {
|
||||
switch role {
|
||||
case let .board(openCard):
|
||||
case let .board(openCard, confirmations):
|
||||
face
|
||||
// "A fast double-click opens the card window (⌘↩'s pointer twin)" (04 ▸ Selection).
|
||||
//
|
||||
@@ -158,14 +164,18 @@ struct CardFaceView: View {
|
||||
guard ClickModifier.current == .plain else { return }
|
||||
openCard(card.id)
|
||||
})
|
||||
.contextMenu { boardMenu(openCard: openCard) }
|
||||
.contextMenu { boardMenu(openCard: openCard, confirmations: confirmations) }
|
||||
// **The menu's rows, additionally as custom actions** — "where SwiftUI additionally
|
||||
// surfaces menu items as custom accessibility actions, that's free improvement, not
|
||||
// a separate design surface" (10-accessibility.md ▸ Actions come from the context
|
||||
// menu). The menu stays the inventory and stays reachable the standard way (VO-⇧-M).
|
||||
// Style… is absent for `LaneView`'s reason: it opens a popover, and the quick-style
|
||||
// swatch `Picker` beside it is not an action.
|
||||
.accessibilityActions { boardActions(openCard: openCard) }
|
||||
// swatch `Picker` beside it is not an action. Delete Immediately rides along too,
|
||||
// its own row rather than the ⌥-alternate above — VoiceOver's action rotor has no
|
||||
// held-key concept, so the alternate needs a first-class custom action of its own
|
||||
// (11-command-nexus.md ▸ Context menus' Card row: "surfaces as its own VO custom
|
||||
// action per 10's cut").
|
||||
.accessibilityActions { boardActions(openCard: openCard, confirmations: confirmations) }
|
||||
.popover(isPresented: styleEditorPresentation(store, anchor: card.id), arrowEdge: .bottom) {
|
||||
StyleEditorPopover(store: store, recents: appModel.styleRecents)
|
||||
}
|
||||
@@ -443,10 +453,10 @@ struct CardFaceView: View {
|
||||
|
||||
// MARK: - Context menus
|
||||
|
||||
/// Open, Rename, Style…, the quick-style recents row, Delete — 11-command-nexus.md ▸ Context
|
||||
/// menus' Card row, in its order.
|
||||
/// Open, Rename, Style…, the quick-style recents row, Delete — with Delete Immediately as its
|
||||
/// ⌥-alternate — 11-command-nexus.md ▸ Context menus' Card row, in its order.
|
||||
@ViewBuilder
|
||||
private func boardMenu(openCard: @escaping (ItemID) -> Void) -> some View {
|
||||
private func boardMenu(openCard: @escaping (ItemID) -> Void, confirmations: TrashConfirmations) -> some View {
|
||||
// Open: Board ▸ Open Card's pointer twin (`OpenCardCommand`), restricted to the clicked card
|
||||
// alone — "a card window is tied to one card" (11-command-nexus.md), so unlike Style… and
|
||||
// Delete below it, this row never widens to the selection; Open never opens multiple, even
|
||||
@@ -474,19 +484,38 @@ struct CardFaceView: View {
|
||||
// Delete: File ▸ Delete's exact store path (`store.delete`, `TrashCommands`'s twin), on the
|
||||
// widened target set below (`targetIDs`) — the successor-selection rule is `delete(_:)`'s own,
|
||||
// so this row gets it for free.
|
||||
//
|
||||
// **Delete Immediately rides as its ⌥-alternate** (Finder's own pattern — hold ⌥ and Delete
|
||||
// becomes Delete Immediately, 11-command-nexus.md ▸ Context menus' Card row, settled
|
||||
// 2026-07-29). `.modifierKeyAlternate(.option)` is SwiftUI's macOS-native mechanism for
|
||||
// exactly this swap (macOS 15+); the alternate's title matches File ▸ Delete Immediately's
|
||||
// own verbatim (`TrashCommands`), since menu titles are the system remapping key and the two
|
||||
// rows name the same command. It widens over the same `targetIDs` Delete itself reads, so an
|
||||
// ⌥-held click purges exactly what a plain click would have trashed.
|
||||
Button("Delete") { deleteTargets() }
|
||||
.disabled(!store.acceptsBoardMutations)
|
||||
.modifierKeyAlternate(.option) {
|
||||
Button("Delete Immediately") { requestDeleteImmediately(confirmations) }
|
||||
.disabled(!canDeleteImmediately)
|
||||
}
|
||||
}
|
||||
|
||||
/// `boardMenu`'s plain rows as VoiceOver custom actions — every one calling the *same* private
|
||||
/// method its menu row does, so the two surfaces cannot come to mean different things.
|
||||
///
|
||||
/// Delete Immediately gets its own row here rather than riding `modifierKeyAlternate` — the
|
||||
/// action rotor has no held-key concept, so the alternate needs a first-class custom action of
|
||||
/// its own to be reachable at all ("surfaces as its own VO custom action per 10's cut",
|
||||
/// 11-command-nexus.md ▸ Context menus' Card row).
|
||||
@ViewBuilder
|
||||
private func boardActions(openCard: @escaping (ItemID) -> Void) -> some View {
|
||||
private func boardActions(openCard: @escaping (ItemID) -> Void, confirmations: TrashConfirmations) -> some View {
|
||||
Button("Open") { openCard(card.id) }
|
||||
Button("Rename") { beginRename() }
|
||||
.disabled(!store.acceptsBoardMutations)
|
||||
Button("Delete") { deleteTargets() }
|
||||
.disabled(!store.acceptsBoardMutations)
|
||||
Button("Delete Immediately") { requestDeleteImmediately(confirmations) }
|
||||
.disabled(!canDeleteImmediately)
|
||||
}
|
||||
|
||||
/// Delete and Reveal in Finder — the two rows 11-command-nexus.md gives a trash card, and no
|
||||
@@ -536,6 +565,15 @@ struct CardFaceView: View {
|
||||
confirmations.requestTrashDelete(of: targetIDs, in: store)
|
||||
}
|
||||
|
||||
/// The board side's **permanent** delete — Delete's ⌥-alternate and its VoiceOver custom-action
|
||||
/// twin — through the same window confirmation host `requestPurge` above uses, but
|
||||
/// `TrashConfirmations`'s board-side entry point (`requestBoardPurge`): the alert (or the
|
||||
/// git-board shrug) is what stands between this row and an unrecoverable loss, exactly as it does
|
||||
/// for the trash's own Delete (03 § Trash).
|
||||
private func requestDeleteImmediately(_ confirmations: TrashConfirmations) {
|
||||
confirmations.requestBoardPurge(of: targetIDs, in: store)
|
||||
}
|
||||
|
||||
private func revealInFinder() {
|
||||
NSWorkspace.shared.activateFileViewerSelecting(targetFolders)
|
||||
}
|
||||
@@ -566,6 +604,18 @@ struct CardFaceView: View {
|
||||
return store.selection.ids
|
||||
}
|
||||
|
||||
/// Whether Delete Immediately's ⌥-alternate has something to purge — File ▸ Delete Immediately's
|
||||
/// own predicate (`TrashModel.canDeleteImmediately`), read over this row's `targetIDs` rather
|
||||
/// than the standing selection, `targetIDs`' own reason: a context menu names its target by where
|
||||
/// it was invoked (11-command-nexus.md ▸ Context menus' Card row).
|
||||
private var canDeleteImmediately: Bool {
|
||||
guard store.acceptsBoardMutations else { return false }
|
||||
return TrashModel.canDeleteImmediately(
|
||||
selection: ItemReferenceSet(ids: targetIDs, container: role.container),
|
||||
in: store.snapshot
|
||||
)
|
||||
}
|
||||
|
||||
/// The folders Reveal in Finder points at — resolved in this face's container, so a trash row
|
||||
/// reveals `<root>/.trash/<uuid>` and never a lane path that no longer holds the card.
|
||||
private var targetFolders: [URL] {
|
||||
@@ -605,7 +655,7 @@ struct CardFaceView: View {
|
||||
onCommitAndOpen: {
|
||||
let id = card.id
|
||||
store.commitRename()
|
||||
if case let .board(openCard) = role { openCard(id) }
|
||||
if case let .board(openCard, _) = role { openCard(id) }
|
||||
}
|
||||
)
|
||||
.font(.body)
|
||||
|
||||
@@ -21,8 +21,8 @@ import SwiftUI
|
||||
///
|
||||
/// "The lane has one context menu (settled), invoked on the header or on lane empty space alike"
|
||||
/// (03-board-ui.md § Lane), so both surfaces attach the *same* `laneMenu`. It carries Rename, Style…,
|
||||
/// the quick-style recents row, the Width stepper and Delete — 11-command-nexus.md ▸ Context menus'
|
||||
/// Lane row, in its order, complete as of m5.
|
||||
/// the quick-style recents row, the Width stepper and Delete — with Delete Immediately as its
|
||||
/// ⌥-alternate — 11-command-nexus.md ▸ Context menus' Lane row, in its order, complete as of m5.
|
||||
///
|
||||
/// ### The card face
|
||||
///
|
||||
@@ -65,6 +65,11 @@ struct LaneView: View {
|
||||
/// business knowing about `WindowGroup` keys.
|
||||
let openCard: (ItemID) -> Void
|
||||
|
||||
/// The window's purge-alert host — Delete's ⌥-alternate needs it to raise the same confirmation
|
||||
/// File ▸ Delete Immediately does (`TrashConfirmations`, `BoardView`'s own copy handed straight
|
||||
/// down, since a lane has no business owning window-scoped state either).
|
||||
let confirmations: TrashConfirmations
|
||||
|
||||
/// Reduce Motion, for the card transition below (10-accessibility.md). Read from the environment
|
||||
/// and handed to `Motion`, which owns what "reduced" means.
|
||||
@Environment(\.accessibilityReduceMotion) private var reduceMotion
|
||||
@@ -298,14 +303,27 @@ struct LaneView: View {
|
||||
// Delete: File ▸ Delete's exact store path (`store.delete`), on the same widened target set
|
||||
// Style… above reads (`targetIDs`, `styleTarget`'s `Set<ItemID>` sibling below) — the
|
||||
// successor-selection rule is `delete(_:)`'s own, so this row gets it for free.
|
||||
//
|
||||
// **Delete Immediately as its ⌥-alternate** — the same swap the card row wears
|
||||
// (11-command-nexus.md ▸ Context menus' Lane row: "Delete — with the same ⌥-alternate Delete
|
||||
// Immediately. The trash needs no alternate"), `modifierKeyAlternate(.option)` again, the
|
||||
// title matching File ▸ Delete Immediately's own verbatim (`TrashCommands`).
|
||||
Button("Delete") { deleteTargets() }
|
||||
.disabled(!store.acceptsBoardMutations)
|
||||
.modifierKeyAlternate(.option) {
|
||||
Button("Delete Immediately") { requestDeleteImmediately() }
|
||||
.disabled(!canDeleteImmediately)
|
||||
}
|
||||
}
|
||||
|
||||
/// The menu's plain rows again, as VoiceOver custom actions (see the `.accessibilityActions`
|
||||
/// call site). Every one of them calls the *same* private method its menu row does, so the two
|
||||
/// surfaces cannot drift into meaning different things — which is the only way "not a separate
|
||||
/// design surface" is checkable rather than merely intended.
|
||||
///
|
||||
/// Delete Immediately gets its own row rather than riding `modifierKeyAlternate`, `CardFaceView
|
||||
/// .boardActions`' own reason: the action rotor has no held-key concept, so the alternate needs a
|
||||
/// first-class custom action to be reachable at all.
|
||||
@ViewBuilder
|
||||
private var laneActions: some View {
|
||||
let units = LaneLayoutMath.displayUnits(of: lane)
|
||||
@@ -317,6 +335,8 @@ struct LaneView: View {
|
||||
.disabled(!store.acceptsBoardMutations || units <= 1)
|
||||
Button("Delete") { deleteTargets() }
|
||||
.disabled(!store.acceptsBoardMutations)
|
||||
Button("Delete Immediately") { requestDeleteImmediately() }
|
||||
.disabled(!canDeleteImmediately)
|
||||
}
|
||||
|
||||
/// Board ▸ Rename's store path, seeded with the lane's live title — one method, two callers
|
||||
@@ -331,6 +351,15 @@ struct LaneView: View {
|
||||
store.delete(targetIDs)
|
||||
}
|
||||
|
||||
/// Delete's ⌥-alternate — the lane's **permanent** delete, through the window's confirmation host
|
||||
/// rather than straight to the store (`CardFaceView.requestDeleteImmediately`'s own reason): the
|
||||
/// alert (or the git-board shrug) is what stands between this row and an unrecoverable loss.
|
||||
/// `TrashConfirmations.requestBoardPurge` is the shared entry point both rows call, over each
|
||||
/// one's own `targetIDs`.
|
||||
private func requestDeleteImmediately() {
|
||||
confirmations.requestBoardPurge(of: targetIDs, in: store)
|
||||
}
|
||||
|
||||
/// VO-Space's landing: the ⌘-click funnel, on this lane. `togglesOnRepeat` stays false because
|
||||
/// only the *plain* branch reads it — the ⌘ branch is already a toggle, which is the point.
|
||||
private func toggleLaneSelection() {
|
||||
@@ -389,6 +418,24 @@ struct LaneView: View {
|
||||
return store.selection.ids
|
||||
}
|
||||
|
||||
/// Whether Delete Immediately's ⌥-alternate has something to purge — File ▸ Delete Immediately's
|
||||
/// own predicate (`TrashModel.canDeleteImmediately`), read over this row's `targetIDs`
|
||||
/// (`CardFaceView.canDeleteImmediately`'s own reason: a context menu names its target by where it
|
||||
/// was invoked, not by the standing selection).
|
||||
///
|
||||
/// **Presently always disabled on a lane-only target**: `canDeleteImmediately` is cards only
|
||||
/// today — "a lane's delete is physical already … there is nothing for 'skip the trash' to mean
|
||||
/// on one" (`TrashModel`) — so this row is wired per 11-command-nexus.md's Lane row ahead of the
|
||||
/// store gaining the capability, the same posture the File-menu command already takes on a
|
||||
/// lane-only selection.
|
||||
private var canDeleteImmediately: Bool {
|
||||
guard store.acceptsBoardMutations else { return false }
|
||||
return TrashModel.canDeleteImmediately(
|
||||
selection: ItemReferenceSet(ids: targetIDs, container: .board),
|
||||
in: store.snapshot
|
||||
)
|
||||
}
|
||||
|
||||
private var headerContent: some View {
|
||||
HStack(alignment: .firstTextBaseline, spacing: BoardMetrics.laneHeaderSpacing(bodyPointSize: pointSize)) {
|
||||
Image(systemName: ItemSymbol.name(lane.icon, fallback: ItemSymbol.lane))
|
||||
@@ -669,7 +716,7 @@ struct LaneView: View {
|
||||
CardFaceView(
|
||||
store: store,
|
||||
card: card,
|
||||
role: .board(openCard: openCard),
|
||||
role: .board(openCard: openCard, confirmations: confirmations),
|
||||
marquee: marquee,
|
||||
drops: drops
|
||||
)
|
||||
|
||||
@@ -36,7 +36,12 @@ final class TrashConfirmations {
|
||||
/// names the whole container and re-derives its targets at the moment it runs).
|
||||
enum Action: Equatable {
|
||||
case deleteTrashCards(Set<ItemID>)
|
||||
case purge(Set<ItemID>)
|
||||
/// **The container travels with the ids**, because a purge can be aimed at either side and
|
||||
/// the two entry points below disagree about which: the menu-bar command means the
|
||||
/// selection's container, a context menu means `.board` whatever is selected. Re-reading
|
||||
/// the selection when the alert is answered would resolve a board card against `.trash` and
|
||||
/// purge nothing — a confirmed destructive command becoming a silent no-op.
|
||||
case purge(Set<ItemID>, ItemContainer)
|
||||
case emptyTrash
|
||||
}
|
||||
}
|
||||
@@ -91,20 +96,54 @@ final class TrashConfirmations {
|
||||
/// expression rather than three call sites.
|
||||
///
|
||||
/// Its one caller is File ▸ Delete Immediately, which passes the selection's own ids — which is
|
||||
/// what makes reading `store.selection.container` for the prompt correct here and wrong for a
|
||||
/// context menu (`requestTrashDelete` above exists for exactly that difference).
|
||||
/// what makes reading `store.selection.container` correct here and wrong for a context menu
|
||||
/// (`requestTrashDelete` above exists for exactly that difference).
|
||||
func requestPurge(of ids: Set<ItemID>, in store: BoardStore) {
|
||||
let container = store.selection.container
|
||||
guard store.purgeIsUnrecoverable else {
|
||||
store.deleteImmediately(ids)
|
||||
store.deleteImmediately(ids, in: container)
|
||||
return
|
||||
}
|
||||
guard let prompt = TrashModel.purgePrompt(
|
||||
for: ids,
|
||||
in: store.selection.container,
|
||||
in: container,
|
||||
snapshot: store.snapshot,
|
||||
unrecoverable: true
|
||||
) else { return }
|
||||
pending = Pending(prompt: prompt, action: .purge(ids))
|
||||
pending = Pending(prompt: prompt, action: .purge(ids, container))
|
||||
}
|
||||
|
||||
/// **Delete's ⌥-alternate, aimed at an explicit set** — the board-side card and lane
|
||||
/// context-menu rows' Delete Immediately (11-command-nexus.md ▸ Context menus' Card and Lane
|
||||
/// rows: "Delete — with Delete Immediately as its ⌥-alternate … Finder's pattern: hold ⌥ and
|
||||
/// Delete becomes Delete Immediately").
|
||||
///
|
||||
/// A third entry point beside `requestPurge` and `requestTrashDelete`, for `requestTrashDelete`'s
|
||||
/// own reason mirrored onto the other container: `requestPurge(of:in:)` reads
|
||||
/// `store.selection.container` for the prompt, which is correct for its one caller (File ▸
|
||||
/// Delete Immediately, whose ids *are* the selection) and wrong for a context menu, which names
|
||||
/// its target by where the ⌥-held click landed — right-clicking a card or lane while a *trash*
|
||||
/// selection stands must still purge the clicked item.
|
||||
///
|
||||
/// The container is always `.board`: this alternate exists only on the board-side rows —
|
||||
/// "the trash needs no alternate: its Delete is already permanent" (11-command-nexus.md's Lane
|
||||
/// row).
|
||||
///
|
||||
/// **The container is supplied end to end**, prompt and write alike: `store.deleteImmediately`
|
||||
/// takes it as a parameter rather than reading the selection, so a confirmed purge aimed at a board
|
||||
/// item cannot silently find nothing because a trash selection happened to be standing.
|
||||
func requestBoardPurge(of ids: Set<ItemID>, in store: BoardStore) {
|
||||
guard store.purgeIsUnrecoverable else {
|
||||
store.deleteImmediately(ids, in: .board)
|
||||
return
|
||||
}
|
||||
guard let prompt = TrashModel.purgePrompt(
|
||||
for: ids,
|
||||
in: .board,
|
||||
snapshot: store.snapshot,
|
||||
unrecoverable: true
|
||||
) else { return }
|
||||
pending = Pending(prompt: prompt, action: .purge(ids, .board))
|
||||
}
|
||||
|
||||
/// Raises Empty Trash…'s alert. **Always** — it guards bulk scope rather than per-item
|
||||
@@ -124,7 +163,7 @@ final class TrashConfirmations {
|
||||
self.pending = nil
|
||||
switch pending.action {
|
||||
case let .deleteTrashCards(ids): store.deleteTrashCards(ids)
|
||||
case let .purge(ids): store.deleteImmediately(ids)
|
||||
case let .purge(ids, container): store.deleteImmediately(ids, in: container)
|
||||
case .emptyTrash: store.emptyTrash()
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user