From bb936068dbab2b6a50382386859bbaa8bcdf6ffd Mon Sep 17 00:00:00 2001 From: rzen Date: Thu, 6 Aug 2026 20:26:24 -0400 Subject: [PATCH] =?UTF-8?q?The=20environmental=20carve-out=20=E2=80=94=20n?= =?UTF-8?q?o=20walk=20to=20collect=20from,=20the=20welcome=20row=20answers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gap #6 ratified into 01 ▸ Malformed input ▸ The decision surface: a root that is gone/unreadable or is a file throws immediately as a single-defect failure — nothing to walk, nothing a surface could repair or reveal — so it retires to the welcome failure row on every open, attended or not. Judged per failure, not per defect (the 31fee00 refinement, ratified): an environmental defect among repairable ones still shows the surface, and the vocabulary keeps the unreachable-root seat for the re-walk that meets one under a standing surface. Claude-Session: https://claude.ai/code/session_014PtZdPwqZuqEDLc6wZMtEy --- DESIGN/01-storage-format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DESIGN/01-storage-format.md b/DESIGN/01-storage-format.md index ec2cab5..dd0c3c3 100644 --- a/DESIGN/01-storage-format.md +++ b/DESIGN/01-storage-format.md @@ -128,7 +128,7 @@ Loud, specific error (path + what's wrong) for: unparseable YAML, `schema` newer Fail-fast is the **initial-load** contract. Once a board is open, a failed live reload does not blank the board: the window keeps the last good snapshot and surfaces the same loud specifics in a non-modal banner — see 02-architecture.md's live-reload resilience. -**The decision surface (settled 2026-07-31).** Blocking means one aggregated surface hosted by the pre-snapshot loading window (02-architecture.md ▸ the loading state) — the loading content transforms in place, never a sheet over a spinner. It appears on **attended opens only** (welcome click, File ▸ Open…, Finder): restoration failures keep the retire-to-welcome-row landing, and the row's retry click is the attended open that then shows the surface — repair is an attended act, and launch never chains dialogs. The loader collects every fail-fast defect in the walk rather than stopping at the first. The surface groups defects **by class**: each class section states the defect once, lists the affected files (path + specifics, each with Reveal in Finder and Open in Editor), and carries one class-level choice preselected to its default, with per-item override behind a disclosure. The vocabulary offers only honest choices per class: +**The decision surface (settled 2026-07-31).** Blocking means one aggregated surface hosted by the pre-snapshot loading window (02-architecture.md ▸ the loading state) — the loading content transforms in place, never a sheet over a spinner. It appears on **attended opens only** (welcome click, File ▸ Open…, Finder): restoration failures keep the retire-to-welcome-row landing, and the row's retry click is the attended open that then shows the surface — repair is an attended act, and launch never chains dialogs. The loader collects every fail-fast defect in the walk rather than stopping at the first. **The environmental carve-out (ruled 2026-08-06):** two failures never aggregate — a root that is gone or unreadable, and a root that is a file rather than a directory. Each throws immediately as a single-defect failure: there is no walk to collect from and nothing on disk a surface could repair or reveal. So they keep the retire-to-welcome-row landing on every open, attended or not — the row's loud specifics are the whole answer, and its retry click is how the user tries again once the world is fixed. The carve-out judges the **failure, not the defect** (refined with the built surface, ratified 2026-08-06): a failure whose single defect is environmental retires; an environmental defect arriving *among* repairable ones still shows the surface — the rest of it is still actionable. The surface's class vocabulary keeps a seat for the family anyway (*unreachable root*: a blocked row, no choices, Cancel and Re-check the exits) — not for opens, which never route it there, but for the one path that can meet it: a re-walk under a standing surface after the board folder is deleted or replaced underneath it, where a class without a seat would be a crash and a blocked surface is the honest answer. The surface groups defects **by class**: each class section states the defect once, lists the affected files (path + specifics, each with Reveal in Finder and Open in Editor), and carries one class-level choice preselected to its default, with per-item override behind a disclosure. The vocabulary offers only honest choices per class: - *Unparseable YAML* — no app-minted rewrite (the app would be guessing at content): Open in Editor + Re-check, or Skip. - *`schema` present but unreadable* (`schema: one`, a sequence where a scalar belongs — ruled 2026-08-06, the fifth class) — the YAML family's posture, no app-minted rewrite: a present-but-garbled value is evidence of intent, and stamping `1` over it would both guess and destroy the one clue about what was meant (the garble may be a newer schema's value mangled — precisely the file the app must never quietly claim as its own; the missing-schema mint's "the walk just validated against schema 1" argument does not transfer to a value that contradicts it). Open in Editor + Re-check, or Skip below the root. At the root there is no Skip — root `schema` is the this-really-is-a-board gate — but Editor + Re-check **is** offered, unlike newer-than-app's Cancel-only root row: that class has no honest fix short of updating the app, while this one is a typo-shaped, user-fixable defect and the repair loop is exactly the surface's answer to those; Cancel remains the surface's standing exit. @@ -144,7 +144,7 @@ Buttons: **Repair and Open** applies every chosen fix in one write bracket — e Every rule in this document that refuses, tolerates, recovers, or repairs is an instance of **one five-verdict taxonomy**, owned by one vocabulary — the **integrity service** (`IntegrityRules` + `HealScheduler`, 02-architecture.md ▸ Components). A detectable defect classifies into exactly one verdict, and the verdict fixes everything downstream — surface, write behavior, race posture — so no mechanism ever re-reasons its posture individually. The doctrine behind every lenient verdict (stated 2026-07-29): **leniency is recovering recoverable issues through reliable heuristics owned by this service — never accepting loss that could surprise the user.** Where a reliable recovery exists, it applies (silently where nothing is lost); where it doesn't, the defect surfaces — refusal and alerting are the honest ends of the same scale, and "proceed partially, lose a little" is never a verdict: -- **Refuse** — fail-fast (Malformed input above): the defect defeats rendering or ordering. Initial-load refusal; once open, the reload-breakage condition (02-architecture.md). **Refusal is the healer's last resort, and no longer a dead end** (re-ruled 2026-07-29 — fail-fast is *gated by the integrity service*): a defect with a reliable heal heals and moves on (a non-blocking notice at most); only an unhealable defect blocks, and blocking means a **decision surface** — the load pauses, the user chooses the fix, the fix applies, the load proceeds. Never a modal chain: the loader collects every fail-fast defect in the walk rather than stopping at the first, and one aggregated surface presents them all. The surface's design is settled (2026-07-31) — Malformed input above ▸ The decision surface. +- **Refuse** — fail-fast (Malformed input above): the defect defeats rendering or ordering. Initial-load refusal; once open, the reload-breakage condition (02-architecture.md). **Refusal is the healer's last resort, and no longer a dead end** (re-ruled 2026-07-29 — fail-fast is *gated by the integrity service*): a defect with a reliable heal heals and moves on (a non-blocking notice at most); only an unhealable defect blocks, and blocking means a **decision surface** — the load pauses, the user chooses the fix, the fix applies, the load proceeds. Never a modal chain: the loader collects every fail-fast defect in the walk rather than stopping at the first, and one aggregated surface presents them all (environmental root failures excepted — nothing to walk, the welcome row answers: the carve-out above, ruled 2026-08-06). The surface's design is settled (2026-07-31) — Malformed input above ▸ The decision surface. - **Refuse writes** — readable-but-uneditable shapes (Frontmatter above): the file renders fine, and every app write to it fails loudly per file. - **Tolerate** — outside the schema's claim: strays, symlinks, case-twins, lane- and board-level `deleted:`. Preserved verbatim, logged, never rendered (or rendered with the key inert). - **Coerce** — a sensible reading exists (the coercion rulebook, last-wins, null-as-missing, the rescue family): silent, read-side only, bytes preserved — the recovered value is exactly what the writer meant.