fuse

Overview ¶

Package fuse is the STATE half of the ingestion fuse: reading and writing the box, the JSON file the two emergency powers live in. cmd/nova-fuse is the thin command on top of it. The box's path always comes from the caller — there is no default location and no environment variable, per this repo's no-guessed-paths rule.

WHAT IS ACTUALLY DECIDED HERE, and why each one is not arbitrary:

1. THE READ HAS THREE ANSWERS, NEVER TWO. "no box" is a VERIFIED FACT -- a fuse box that was never created holds no blown fuses. "cannot read the box" is a THIRD answer and it is never the reassuring one. A reader that collapses them (an exists-style probe answers false both when the file is absent AND when the directory above it cannot be stat'd) turns a permissions change into "nothing blown" -- a fail-open in a safety control. os.ReadFile + errors.Is(err, fs.ErrNotExist) tells UNREADABLE apart from NONEXISTENT, which is why the read is written with the stdlib primitive that distinguishes those two rather than the one that does not. What that primitive does NOT distinguish: a missing box file from a missing parent directory -- both come back fs.ErrNotExist, so `--box /no/such/dir/fuses.json` also answers VERIFIED CLEAR. Accepted, deliberately, not overlooked: --box is a locator, the caller's statement of where the box lives, and a caller that names the wrong box gets that box's truth -- here, an empty one. The case is pinned by test (TestCheckIntoANonexistentDirectoryIsAlsoClear in cmd/nova-fuse), so changing this answer is a decision, never a drive-by.

2. MALFORMED IS UNREADABLE. A JSON array, a bare string, a truncated file, a lockdown whose value is not an object -- every one fails the unmarshal and comes back as CANNOT TELL, which every caller must treat as BLOWN. Reaching the fail-closed answer by a crash deep inside a caller is not a design; this is.

3. THE WRITE IS TEMP-FILE + RENAME. The file whose corruption means PERMANENT LOCKDOWN must never be left torn: a truncating write can leave half a file if the process dies, and a half file is an unreadable box that only your person can clear, by hand, live. Rename within one directory is atomic, so a reader sees the old box or the new one and never a fragment. Two copies of the tool blowing fuses at once lose one WRITE, but neither can produce a corrupt box.

4. SURFACE NAMES ARE MATCHED NORMALIZED, AND THAT CUTS BOTH WAYS. Raw string comparison lets `quarantine Discord` then `check discord` answer CLEAR -- a fail-OPEN in a safety control, reached by a capital letter. Normalizing collapses spellings into one surface, and the honest statement of what that does is not "it can only ever block more": it is that EQUIVALENT SPELLINGS ARE ONE SURFACE, IN BOTH DIRECTIONS. `check` refuses on any spelling, so the class blocks more. LiftQuarantine removes EVERY spelling in the class, so a lift lifts more too -- deliberately, because a lift that left one spelling behind would verify its own failure, and because an operator who lifts a surface means the surface. It is not silent either way: each removal is returned under its stored spelling so the caller can announce it on its own line. The consequence to know: a box holding two keys that fold together holds ONE surface, not two.

5. THE ESCAPE LIVES AT PRINT TIME, because the tool cannot trust what it did not write. The box is world-readable on purpose (a fuse nobody else can see is a fuse that stops nothing) and hand-editable on purpose (that is the only lockdown-replacement mechanism there is), so on a shared machine the reason, the `at` stamp and the stored surface names are authored by whoever can write the file. Echoed raw into a one-line output grammar, a newline forges a SECOND event line beneath a real one -- a `FUSE OK lockdown=clear` under a `FUSE FAIL`, which a caller scanning the grammar reads as permission -- and an ESC sequence does the same to an operator's terminal. OneLine escapes every control character as the text is printed, which holds for a box this tool never wrote; Fold only tidies what this tool writes itself, and is never a refusal, because a fuse you cannot blow is not a fuse. Constraining writes alone would defend exactly the case that needs no defending. The escaped set is category Cc plus U+2028 and U+2029, which break a line for readers that follow Unicode rather than counting newlines. Folding also widens the surface classes of note 4, in both directions -- see there.