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

The loader collects every fail-fast defect and honors per-open skips

Browse Source 
Phase 1 of the decision surface (01 ▸ Malformed input, settled
2026-07-31): BoardLoadFailure aggregates the walk's defects in walk
order — stop-at-first retires. Environmental failures (unreadable root,
not-a-directory) stay immediate single-defect throws: there is no walk
to collect from. A defective root index is recorded and the walk
continues into the children (nothing in the walk consults the parsed
root document — verified); a defective lane, card, or trash-entry index
records and skips its subtree, Re-check's whole-walk re-aggregation
being the designed loop for what hides beneath. load(skipping:) is the
per-open skip channel: a skipped path's item is omitted from the model
and surfaces as LoadWarning.userSkipped; root paths are unskippable by
construction. The reload-breakage banner carries the aggregate ("…and
N more"), single-defect sentences byte-identical to before. Two new
multi-defect fixture boards; suite 2591 green.

Claude-Session: https://claude.ai/code/session_01CqjXB7ASoWtbyoGod68k97
This commit is contained in:
rzen
2026-08-01 09:12:49 -04:00
parent 94e60cd444
commit ba1726fa77
35 changed files with 897 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Kanban/Storage/BoardLoader.swift
+242 -32
View File
@@ -150,6 +150,18 @@ public enum BoardLoader: Sendable {
/// ruled 2026-07-31). The name is `IntegrityRules`', with the rest of the claimed names.
static let gitignoreFileName = IntegrityRules.gitignoreFileName
/// **The defect paths a skip set can never name** (01-storage-format.md § Malformed input, the
/// decision surface, settled 2026-07-31): the board root's own `index.md`, and the `"."` the
/// environmental failures carry.
///
/// The surface never offers Skip at the root — a root `schema` newer than this app "blocks the
/// whole board (Cancel is the only exit)", and the other three root defects have minted repairs
/// (create the index, stamp `schema: 1`) rather than a tolerance. Skipping one anyway would mean
/// building a `BoardModel` out of a board with no root document and no schema, which is not a
/// board. Policed in `load(boardRoot:skipping:historyRanker:)` so the impossible snapshot is
/// impossible *here*, rather than by every future caller remembering not to ask for it.
static let unskippablePaths: Set<String> = [indexFileName, "."]
private static let logger = Logger(subsystem: "dev.rzen.indie.Kanban", category: "loader")
// MARK: - The noise gate
@@ -183,21 +195,53 @@ public enum BoardLoader: Sendable {
// MARK: - Entry point
/// Walks the board and answers a snapshot — or **every fail-fast defect the walk found**, as one
/// aggregate (01-storage-format.md § Malformed input, settled 2026-07-31: "The loader collects
/// every fail-fast defect in the walk rather than stopping at the first"). One walk, one
/// `BoardLoadFailure`, and never a chain of modals over the same board.
///
/// ### What collecting means at each level
///
/// - **Environmental failures stay immediate.** An unreadable root, and a root that is a file
/// rather than a folder, throw a single-defect aggregate on the spot: there is nothing to walk
/// and so nothing to aggregate *with*. The surface would show one row either way.
/// - **The root's own `index.md` defects are collected and the walk continues** — a missing
/// index, unparseable YAML, a missing or malformed `schema`, a `schema` newer than this app.
/// Nothing below the root reads the root's document: lanes are enumerated by folder shape,
/// `.trash/` is reached by name, and the noise gate is its own file. So a board whose root is
/// broken *and* whose lanes are broken reports both in one pass, which is what lets the
/// surface state every class at once instead of revealing the next one per repair.
/// - **A below-root defect skips that item's subtree.** A lane whose `index.md` will not parse
/// is recorded and its cards are never enumerated; a card's defect takes that card out. This is
/// the designed loop rather than a gap: Repair and Open and Re-check both "re-run the whole
/// walk", so a repaired lane re-aggregates with whatever it was hiding, in the *same* surface.
///
/// Defect order is walk order — the root first, then lanes in folder-name order with each lane's
/// cards inside it, then `.trash/` — so `BoardLoadFailure.primary` is the first thing the walk
/// met and a grouped surface reads top-down like the tree does.
///
/// - Parameter skipping: **the skip channel** (01-storage-format.md § Malformed input: "Skip is
/// user-consented tolerance, loudly marked … per-open decisions, never persisted"). Defect
/// *paths* — the same root-relative strings `BoardLoadError.path` carries, e.g.
/// `"<lane>/index.md"` — chosen on the decision surface. A skipped path's defect is not
/// collected and its item leaves the model with its whole subtree, exactly the shape the
/// tolerated missing-`index.md` skip already has; a `LoadWarning.userSkipped` is the loud mark
/// the opened board's notice is written from. Nothing persists: the set arrives from one open's
/// surface and dies with the call.
///
/// **Root paths are unskippable** (`unskippablePaths`) — an entry naming the root's own
/// `index.md` is ignored and the defect collected anyway.
public static func load(
boardRoot: URL,
skipping: Set<String> = [],
historyRanker: IdentityHistoryRanker? = nil
) throws(BoardLoadError) -> LoadResult {
try checkIsReadableDirectory(boardRoot)
let boardIndexURL = boardRoot.appendingPathComponent(indexFileName)
guard FileManager.default.fileExists(atPath: boardIndexURL.path) else {
throw BoardLoadError(path: indexFileName, reason: .boardRootMissingIndex)
) throws(BoardLoadFailure) -> LoadResult {
// Environmental, so immediate: a root that cannot be listed has no walk to collect from.
do throws(BoardLoadError) {
try checkIsReadableDirectory(boardRoot)
} catch {
throw BoardLoadFailure(error)
}
let boardDocument = try readDocument(at: boardIndexURL, path: indexFileName)
// **The root's own `schema` stays required** (01-storage-format.md § Malformed input,
// re-ruled 2026-07-31): it is the this-really-is-a-board gate, and the one `schema` on the
// board that does not read as 1 when absent.
let boardSchema = try validatedRootSchema(in: boardDocument, path: indexFileName)
var warnings: [LoadWarning] = []
func warn(_ warning: LoadWarning) {
@@ -205,6 +249,47 @@ public enum BoardLoader: Sendable {
logger.warning("\(warning.description, privacy: .public)")
}
// **The fail-fast aggregate, in walk order** — empty on a board that loads, and the whole of
// what `BoardLoadFailure` carries when it does not.
var failures: [BoardLoadError] = []
/// Records one fail-fast defect — unless this open's user already consented to skipping that
/// exact path.
///
/// The item leaves the model either way; what the skip decides is whether the defect is
/// *reported*. Every caller `continue`s past the item immediately after, which is what makes
/// "skipped" and "broken" one shape in the walk and two only at the surface.
func record(_ defect: BoardLoadError) {
if skipping.contains(defect.path), !unskippablePaths.contains(defect.path) {
warn(.userSkipped(path: defect.path))
return
}
failures.append(defect)
logger.error("\(defect.description, privacy: .public)")
}
// **The root index, collected rather than thrown** — and `nil` on either side of it means
// exactly one thing: a defect was recorded for it above, so the walk below runs for the sake
// of the *other* defects it can still find and the guard past the walk never lets a
// rootless board reach `BoardModel`.
var boardDocument: FrontmatterDocument?
var boardSchema: Int?
let boardIndexURL = boardRoot.appendingPathComponent(indexFileName)
if FileManager.default.fileExists(atPath: boardIndexURL.path) {
do throws(BoardLoadError) {
let document = try readDocument(at: boardIndexURL, path: indexFileName)
// **The root's own `schema` stays required** (01-storage-format.md § Malformed input,
// re-ruled 2026-07-31): it is the this-really-is-a-board gate, and the one `schema` on
// the board that does not read as 1 when absent.
boardSchema = try validatedRootSchema(in: document, path: indexFileName)
boardDocument = document
} catch {
record(error)
}
} else {
record(BoardLoadError(path: indexFileName, reason: .boardRootMissingIndex))
}
// **The one typed defect stream** (02-architecture.md ▸ Components ▸ IntegrityRules): what
// this walk found that is pending *work*, as distinct from `warnings`, which is the
// stray-*tolerance* vocabulary — information, not work. The two ad-hoc repair channels this
@@ -253,16 +338,21 @@ public enum BoardLoader: Sendable {
)
}
// Legal per the frontmatter table, meaningless at board level — ignore and log, never
// tombstone, and **never migrate**: "a `deleted:` key at board level remains meaningless
// — ignored and logged, preserved verbatim" (01-storage-format.md § Deletion). It is
// deliberately absent from `legacyTombstones`: there is no item to relocate and no key
// the app has any business removing from a file it was told to leave alone.
if !boardDocument.deleted.isMissing {
warn(.boardLevelDeletedIgnored)
}
// Both readings of the root's own document, and both skipped when there is no document to
// read: a board whose root index is already a collected defect has nothing to say about its
// `deleted` key or its coercions, and the load is going to throw regardless.
if let boardDocument {
// Legal per the frontmatter table, meaningless at board level — ignore and log, never
// tombstone, and **never migrate**: "a `deleted:` key at board level remains meaningless
// — ignored and logged, preserved verbatim" (01-storage-format.md § Deletion). It is
// deliberately absent from `legacyTombstones`: there is no item to relocate and no key
// the app has any business removing from a file it was told to leave alone.
if !boardDocument.deleted.isMissing {
warn(.boardLevelDeletedIgnored)
}
noteCoercions(in: boardDocument, at: indexFileName)
noteCoercions(in: boardDocument, at: indexFileName)
}
// **The noise gate, read once for the whole walk** (01-storage-format.md § Fractal layout ▸
// Rules, ruled 2026-07-31): the board's `.gitignore` is what decides which loose files are
@@ -274,7 +364,11 @@ public enum BoardLoader: Sendable {
// the far side of that decision, because a `Lane` carrying a withheld card would be exactly
// the snapshot the invariant forbids.
var walkedLanes: [WalkedLane] = []
for laneURL in try directoryCandidates(in: boardRoot) {
// `try?` because `directoryCandidates` never actually throws — an unlistable folder is "no
// candidates" by its own rule — and because the two other containers in this file already
// read it exactly this way (`trashCandidates`, `identityShapedChildren`). Nothing here
// silences a fail-fast: the root's own listability was decided by `checkIsReadableDirectory`.
for laneURL in (try? directoryCandidates(in: boardRoot)) ?? [] {
let laneName = laneURL.lastPathComponent
// The app-claimed board-root names are not strays and must not warn as such. Hidden
// entries never reach here anyway (`.trash` included), so this is the rule stated
@@ -290,11 +384,23 @@ public enum BoardLoader: Sendable {
}
let lanePath = laneName + "/" + indexFileName
let laneDocument = try readDocument(at: laneURL.appendingPathComponent(indexFileName), path: lanePath)
// Below the root both keys are optional (re-ruled 2026-07-31): a missing `schema` reads
// as 1, a missing or unusable `order` as append-at-end. Both readings are coerce-tier —
// recorded here, logged, and acted on by nothing until the file's next Writer touch.
let laneSchema = try resolvedSchema(in: laneDocument, path: lanePath)
let laneDocument: FrontmatterDocument
let laneSchema: (schema: Int, coerced: CoercedField?)
// **A broken lane takes its subtree with it** (the collect-and-skip rule above): the
// defect is recorded, the lane's cards are not enumerated, and the repair's re-check is
// what surfaces whatever they were hiding.
do throws(BoardLoadError) {
laneDocument = try readDocument(
at: laneURL.appendingPathComponent(indexFileName), path: lanePath)
// Below the root both keys are optional (re-ruled 2026-07-31): a missing `schema`
// reads as 1, a missing or unusable `order` as append-at-end. Both readings are
// coerce-tier — recorded here, logged, and acted on by nothing until the file's next
// Writer touch.
laneSchema = try resolvedSchema(in: laneDocument, path: lanePath)
} catch {
record(error)
continue
}
let laneOrder = IntegrityRules.resolvedOrder(in: laneDocument)
noteCoercions(
in: laneDocument,
@@ -303,7 +409,7 @@ public enum BoardLoader: Sendable {
)
var walkedCards: [WalkedCard] = []
for cardURL in try directoryCandidates(in: laneURL) {
for cardURL in (try? directoryCandidates(in: laneURL)) ?? [] {
let cardName = cardURL.lastPathComponent
let cardRelPath = laneName + "/" + cardName
guard isUUIDShaped(cardName) else {
@@ -315,7 +421,13 @@ public enum BoardLoader: Sendable {
continue
}
let card = try parseCard(at: cardURL, path: cardRelPath)
let card: WalkedCard
do throws(BoardLoadError) {
card = try parseCard(at: cardURL, path: cardRelPath)
} catch {
record(error)
continue
}
noteCoercions(in: card.document, at: cardRelPath + "/" + indexFileName, plus: card.coercions)
// **The card-level claimed name** (01-storage-format.md § Fractal layout ▸ Rules,
@@ -425,8 +537,19 @@ public enum BoardLoader: Sendable {
// rulebook below the root — so the parse happens once, before the discriminator, and a
// schema newer than this app fails fast whichever kind the entry turns out to be.
let entryPath = entryRelPath + "/" + indexFileName
let document = try readDocument(at: entryURL.appendingPathComponent(indexFileName), path: entryPath)
let schema = try resolvedSchema(in: document, path: entryPath)
let document: FrontmatterDocument
let schema: (schema: Int, coerced: CoercedField?)
// Collected and skipped, the lane arm's rule one container over: a trash entry that will
// not parse leaves the trash rather than refusing the board, and its own subtree was
// never walked to begin with (the entry is opaque by design).
do throws(BoardLoadError) {
document = try readDocument(
at: entryURL.appendingPathComponent(indexFileName), path: entryPath)
schema = try resolvedSchema(in: document, path: entryPath)
} catch {
record(error)
continue
}
let order = IntegrityRules.resolvedOrder(in: document)
noteCoercions(
in: document,
@@ -476,6 +599,12 @@ public enum BoardLoader: Sendable {
))
}
// **The walk is over, so the aggregate is complete.** Everything below this line assembles a
// snapshot, and a board with a fail-fast defect in it has no snapshot to assemble — so the
// throw sits exactly here: late enough that the surface gets every defect the tree holds,
// early enough that a refused board pays for no dedupe, no sort and no `BoardModel`.
guard failures.isEmpty else { throw BoardLoadFailure(failures) }
// The trash's own append-at-end reading, over the container as one flat list. `order` decides
// nothing about where a trash row *sits* — that is `modified`'s job since 2026-07-31 — but
// every entry carries a rank for its eventual restore, and an entry that carries none reads
@@ -569,6 +698,14 @@ public enum BoardLoader: Sendable {
let withheld = Set(verdict.duplicates.map(\.path) + verdict.caseTwins.map(\.path))
// Unreachable, and spelled out rather than force-unwrapped: every path that leaves these
// unset recorded a defect, and the guard above already threw on any defect at all. The
// stated invariant is "no root document, no board" — a future edit that breaks it should
// surface as the honest fail-fast rather than as a crash.
guard let boardDocument, let boardSchema else {
throw BoardLoadFailure(BoardLoadError(path: indexFileName, reason: .boardRootMissingIndex))
}
let model = BoardModel(
rootURL: boardRoot,
schema: boardSchema,
@@ -1324,6 +1461,24 @@ public enum LoadWarning: Sendable, Equatable, CustomStringConvertible {
/// whole of the tolerate tier's verdict on it. Both paths are root-relative.
case caseTwinIgnored(path: String, winner: String)
/// A fail-fast defect the **user chose to skip** on the decision surface (01-storage-format.md
/// § Malformed input, ruled 2026-07-31: "Skip is user-consented tolerance, loudly marked").
///
/// The item loads out of the board — subtree and all, the tolerated missing-`index.md` skip's
/// exact shape — and the file stays on disk untouched, tolerated-invisible like a stray. This is
/// the loud mark: "the opened board carries a warning-tone notice naming the skipped items", and
/// this warning is what that notice is written from.
///
/// It is a warning rather than a defect for the tolerate tier's own reason — nothing is pending,
/// the app has no business rewriting a file the user told it to leave alone — with one honest
/// difference from its neighbours here: the tolerance was *consented to* this open rather than
/// decided by a rule. Which is also why nothing about it persists: the skip set arrived with one
/// `load` call, "the next open of a still-broken board presents the surface again".
///
/// `path` is the **defect's** path — the offending `index.md`, root-relative — because that is
/// what the surface's row named and what its Reveal in Finder resolved against.
case userSkipped(path: String)
public var description: String {
switch self {
case let .missingIndex(path):
@@ -1336,15 +1491,70 @@ public enum LoadWarning: Sendable, Equatable, CustomStringConvertible {
"\(path): lane-level 'deleted' key is inert, ignored — the lane loads live"
case let .caseTwinIgnored(path, winner):
"\(path): case-spelled twin of \(winner), ignored as a spelling artifact"
case let .userSkipped(path):
"\(path): skipped at the user's request — the board loaded without it"
}
}
}
// MARK: - Error
/// **Everything one walk refused**, as one value (01-storage-format.md § Malformed input, settled
/// 2026-07-31: "The loader collects every fail-fast defect in the walk rather than stopping at the
/// first … one aggregated surface presents them all").
///
/// The aggregate exists so no surface ever has to run a walk per defect: the decision surface groups
/// `defects` by class, the reload banner reads `primary` and counts the rest, and a re-check simply
/// produces a new one. `BoardLoadError` stays the per-defect record — the vocabulary every row,
/// banner and announcement is written against — and this type adds nothing to it but plurality.
///
/// **Never empty.** A failure with no defect is not a failure; `load` returns its `LoadResult` in
/// that case, which is what makes "throwing this means the walk produced no snapshot at all" still
/// true, defect by defect.
///
/// Ordered by the walk: the root first, then lanes in folder-name order with their cards inside
/// them, then `.trash/`.
public struct BoardLoadFailure: Error, Sendable, Equatable, CustomStringConvertible {
/// Every fail-fast defect the walk collected, in walk order. Non-empty by construction.
public let defects: [BoardLoadError]
public init(_ defects: [BoardLoadError]) {
precondition(!defects.isEmpty, "a BoardLoadFailure with no defect is not a failure")
self.defects = defects
}
/// The single-defect aggregate — the environmental failures, and every place that has exactly
/// one thing to say.
public init(_ defect: BoardLoadError) {
self.defects = [defect]
}
/// **The defect a one-line surface shows**: the first in walk order. The banner strip, the
/// welcome window's failure row and the template chooser's unloadable row each have room for one
/// sentence, and the first thing the walk met is the one that names the outermost problem —
/// a broken root before the lanes under it.
public var primary: BoardLoadError { defects[0] }
/// The primary defect's own sentence, with the rest counted rather than listed — a log line and
/// a diagnostic string, not a headline (`BannerCenter` owns the phrasing users read).
///
/// A single-defect failure reads *exactly* as its `BoardLoadError` always did, which is what
/// keeps every existing one-defect surface saying what it said before this type existed.
public var description: String {
defects.count == 1
? primary.description
: "\(primary.description) (and \(defects.count - 1) more)"
}
}
/// A fail-fast structural failure loading a board — loud and specific: `path` (relative to
/// the board root where one exists) plus `reason` says exactly what's wrong. No partial
/// loads: throwing this means `BoardLoader.load` produced nothing at all.
/// the board root where one exists) plus `reason` says exactly what's wrong.
///
/// **One defect, not the whole refusal.** A walk collects every one of these it meets and hands them
/// over together as a `BoardLoadFailure` (01-storage-format.md § Malformed input, settled
/// 2026-07-31); this stays the record a single decision-surface row, banner or announcement is
/// written against, and the unit the skip channel names by `path`.
public struct BoardLoadError: Error, Sendable, Equatable, CustomStringConvertible {
public let path: String
public let reason: Reason