impl journald audit log

[danneu]

Just an idea. I didn't even look over the following plan yet since this isn't a high priority change.

[danneu]

Plan: journald-backed diagnostic audit logging (v1)

Context

braid mutates pool membership and durable state across multiple commands
(add, remove, remove-missing, replace, recover, ack, enroll,
unlock, ...). When something goes wrong -- a corrupt pool.json, an
interrupted operation, a refused mutation, a failed btrfs subprocess --
operators today reconstruct what happened from terminal scrollback,
pool.json sidecars, and the contents of pending-op.json. There is no
durable, queryable, after-the-fact record of "what did braid actually do
on this NAS, when, and why did it refuse/fail."

This plan adds a diagnostic-only audit trail to systemd-journald.
journald is the right v1 target because it is already the operator's
default log surface on NixOS, gives us free retention/rotation/boot-IDs/
unit metadata, ships with journalctl filtering, and adds no new state
lifecycle for braid to own.

The audit trail is not a source of truth. pool.json,
pending-op.json, alert latch, and ack state remain authoritative.
braid must remain fully recoverable with no audit history at all.

Goals

• Operator can answer with one journalctl invocation:
  • What braid command ran on this host, when, and by whom?
  • What did braid refuse, and what was the reason?
  • Which durable state file was classified/written/cleared?
  • Which pending-op phase was created, advanced, or recovered?
  • What recovery decision did braid make from a discovered journal?
  • Which external subprocess (cryptsetup/btrfs/...) failed?
• Audit emission is best-effort and never alters command outcome.
• Zero new state files. journald is the only target.

Non-goals

• Not a state store. Never read audit events to drive control flow.
• Not a replacement for normal CLI stdout/stderr output.
• Not a streamed/IPC protocol for external consumers.
• Not a security audit log (no tamper-evidence, no signed records).
• Not retroactive: nothing in this plan changes existing on-disk
  formats or command behavior.
• Not a refactor of error handling or command dispatch. Threading
  run_id must not change any cmd_* function signature.

Recommended approach

1. New crate-internal module cli/src/audit.rs exposes a typed
   AuditEvent enum, an AuditSink trait, a process-global
   PROCESS_STATE: OnceLock<ProcessState> (production), a
   thread-local TEST_CONTEXT (for cargo test parallel isolation;
   see D2), an audit::emit(event) entrypoint that reads the
   thread-local first and falls back to the process-global, and the
   ExitOutcome/audited_exit(...) terminal-event funnel (see D11).
2. Production sink writes structured records directly to the journald
   socket via the pure-Rust libsystemd crate (no C linkage, no FFI;
   plays well with Crane builds and NixOS sandbox).
3. run_id is generated once in main() (Uuid::now_v7() -- time-
   ordered) and stored in the audit module's static state alongside the
   parsed command name. No cmd_* signature changes.
4. Events fire at four kinds of seams:
   • command boundary (in cli/src/main.rs only): command_started
     fires at the top of each command match arm; every terminal event
     (command_finished / command_failed / command_refused) flows
     through the single audit::audited_exit(outcome, code) funnel
     that replaces all post-parse std::process::exit / clap::Error ::exit() calls in main.rs (D11). No event is emitted around
     individual match-arm tails; the funnel owns terminal emission.
   • state I/O callers (membership.rs, journal.rs, discover.rs)
     -- not inside state_io::atomic_write, because the caller carries
     the semantic identity of the file being written.
   • semantic subprocess-failure classification sites -- the
     callers that already turn a non-zero exit_status (or an
     unexpected output) into a typed braid error are the ones that
     know it was a real failure. They invoke a shared
     audit::report_external_command_failed(...) helper. The runner
     primitive output_to_raw is not a seam: it returns
     Ok(RawCommandOutput { exit_status }) for normal non-zero exits,
     so hooking there would only catch spawn/signal failures and miss
     every real btrfs/cryptsetup error (see D10).
   • explicit refusal sites (preflight.rs, ack.rs, replace.rs,
     remove.rs, etc.) -- a one-line audit::refused(...) call at each
     known refusal point. audit::refused also marks the run so the
     main-loop wrapper does not double-emit command_failed for the
     same outcome (see D3).
5. Tests use an InMemorySink to assert event sequences without any
   live journald. Two VM tests assert real journalctl output for high-
   value flows.

Design decisions resolved here

D1. Mechanism: direct journald via pure-Rust libsystemd crate (Linux only)

Pure-Rust libsystemd (crates.io: libsystemd) speaks the journal
socket protocol directly. No C dependency, no FFI, no link-time coupling
to a system libsystemd.so version.

Platform gating is mandatory. libsystemd and journald are
Linux-only, but just test-rust runs cargo test on the host
(macOS in this project's primary dev workflow per CLAUDE.md). The dep
and the production sink must be cfg-gated so unit tests build on
macOS:

• In cli/Cargo.toml, declare libsystemd under
  [target.'cfg(target_os = "linux")'.dependencies], not under the
  unconditional [dependencies] table.
• In cli/src/audit.rs, gate JournaldSink with
  #[cfg(target_os = "linux")]. The default sink installer picks
  JournaldSink on Linux and NoopSink on non-Linux.
• InMemorySink is unconditional so unit tests work on every host.
• cargo build / cargo check / just test-rust must pass on macOS
  before merge.

Vet libsystemd during implementation and fall back to the systemd
C-binding crate only if libsystemd proves unsuitable; either way the
platform gating above stays.

Rejected: stderr-with-prefix. braid runs interactively (sudo braid unlock over SSH) as often as it runs from a systemd unit. Emitting to
stderr pollutes the operator's terminal in the interactive case; gating
emission on isatty would silence audit in exactly the case operators
debug most often.

Rejected: tracing + tracing-journald. braid has no tracing
infrastructure today; adding a tracing framework for a fixed set of
~15 event types is overkill.

D2. run_id lifetime, threading, and test isolation

Uuid::now_v7() (uuid crate is already a dep). Generated once at the
top of main() before any command logic, stored in
audit::PROCESS_STATE: OnceLock<ProcessState> together with the
parsed command name string. audit::emit(event) reads the audit
context (see below); if unset (e.g. early panic, unit test that did
not install one), emission is a no-op.

This deliberately does not thread run_id through cmd_* function
signatures. The audit module is a side-channel; coupling correctness
code to it would violate the diagnostic-only invariant.

Test isolation via thread-local override, not just a sink swap.
cargo test runs tests in parallel within a single process. The
ProcessState is mutable (run_refused: AtomicBool,
audit_dropped: AtomicU64) -- a bare sink swap is not enough; one
test that flips run_refused would leak that state into every other
test reading the same OnceLock, making the mutual-exclusion tests
order-dependent. To prevent this, the audit module exposes a
thread-local override:

thread_local! {
    static TEST_CONTEXT: RefCell<Option<TestAuditContext>> = ...;
}

TestAuditContext owns: sink: Box<dyn AuditSink>,
run_id: Uuid, command_name: &'static str,
run_refused: AtomicBool, audit_dropped: AtomicU64, started_at.

audit::emit checks TEST_CONTEXT first; if Some(_), every field
read and write goes through the test context. Only if None does it
fall back to PROCESS_STATE. The same dispatch rule applies to
audit::refused, report_external_command_failed, and the
audit-dropped counter.

audit::test_with_context(|ctx| { ... }) is the test entry point:
it installs a fresh TestAuditContext for the current thread on
entry, runs the closure, and removes the context on exit (RAII via a
guard, so panicking tests still uninstall). Tests can then call
ctx.events(), ctx.dropped(), and ctx.was_refused() on the
context handle. Because the context is thread-local, parallel tests
do not contend, and there is no global mutex to serialize them.

D3. Refusal classification (and refusal/failure mutual exclusion)

command_refused is fired by an explicit audit::refused(reason)
call (one &'static str arg, no detail) at each known refusal site.
The site still returns Err(_) to its caller so the user-visible
CLI error path is unchanged.

audit::refused also flips a run_refused: AtomicBool in the audit
module's process state. The main-loop error wrapper that would
otherwise emit command_failed checks that flag: if set, it emits
nothing additional (the command_refused event already covers the
outcome). If unset, it emits command_failed as before. Net effect:
exactly one of {command_refused, command_failed, command_finished}
fires per run.

This is more verbose than a generic "classify the final error" hook,
but it (a) gives each refusal a stable reason_code symbol independent
of error message text, (b) avoids parsing free-form error strings, and
(c) prevents refusal/failure double-logging.

Initial reason code set:

• pool_not_mounted (ack, remove, remove-missing, replace)
• pending_operation_present (any mutation, preflight)
• pending_operation_unreadable (preflight)
• duplicate_uuid (add, replace)
• target_uuid_mismatch (add)
• live_pool_changed (replace pre-journal recheck)
• offline_btrfs_errors (ack)
• managed_format_flag (add)
• root_required (root gate in main.rs -- the early exit when
  the CLI is invoked without root and the subcommand requires it)

No free-form detail field. Earlier drafts included a
BRAID_REFUSE_DETAIL slot and a validation_other catch-all that
would carry "the error message" verbatim. That model is unsafe: real
refusal errors -- e.g. AddError::DuplicateUuid (cli/src/add.rs:62)
and AddError::TargetUuidMismatchAtOpen (cli/src/add.rs:77) -- embed
/dev/disk/by-id/... strings in their Display text, which the
plan's own D5 sensitive-data rule forbids. Passing that text to
audit::refused would leak by-id paths into journald.

v1 therefore drops the detail field entirely. command_refused
carries only BRAID_REFUSE_REASON from the fixed set above. The
validation_other catch-all is removed; any refusal that does not
match a listed reason code calls for a new reason code (a one-line
addition), not a free-text dump.

audit::refused(reason: &'static str) takes a &'static str only --
no String parameter, no Display arg -- so the type system
prevents accidentally passing an error message as detail. If a
refusal site wants to distinguish sub-cases (e.g. duplicate_uuid
in live pool vs membership), add a more specific reason code
(duplicate_uuid_live_pool / duplicate_uuid_membership) instead.

D4. Emission failure policy: silent drop, with explicit observability caveats

If audit::emit() cannot reach journald (socket missing, EAGAIN,
permission, etc.) it silently swallows the error. Justification:

• Audit is diagnostic; making it fatal would violate the core
  constraint "audit logging must not be fatal for pool mutations."
• Logging a warning to stderr per failure would spam the operator's
  terminal under exactly the conditions (journald sick, disk full)
  that already produce noise from everywhere else.
• A per-process counter of failed emits is recorded in audit module
  state and surfaced in the final command_finished/command_failed
  event as BRAID_AUDIT_DROPPED=N.

Observability caveat. BRAID_AUDIT_DROPPED is observable only if
the final emit reaches journald. If journald is up but flapping --
e.g. a few transient EAGAINs during a long-running mutation -- the
counter is incremented for each failed earlier emit and reported on
the final event. If journald is permanently down for the whole
invocation, every emit including the final one is dropped and there
is no journald-side trace; in that case, observability comes from
the command's normal stdout/stderr exit path, not from audit. v2
(braid doctor) could surface the in-process counter directly; out
of v1 scope.

(This caveat is the reason verification step 5 only asserts command
outcome under journald-down, not BRAID_AUDIT_DROPPED content.)

D5. Sensitive data handling

command_started carries only:

• BRAID_COMMAND = subcommand name (e.g. add)
• BRAID_FLAGS_SUMMARY = comma-sorted list of present flag names
  (e.g. dry-run,passphrase-stdin) -- never flag values
• per-command counts (e.g. BRAID_ADD_DISK_COUNT=2) computed from
  parsed args, never raw argv strings

Never logged anywhere in the audit trail:

• passphrases or any byte that flowed through a Zeroizing<...> buffer
• raw stdin bytes
• raw argv strings (especially the disks: Vec<String> slot)
• by-id paths (operator-supplied paths can identify hardware; treat
  as PII-adjacent)
• full subprocess stdout/stderr blobs

external_command_failed logs only:

• BRAID_EXTCMD_NAME = the static CmdRequest variant name
  (e.g. BtrfsDeviceAdd) -- a Rust-side symbol, not argv
• BRAID_EXTCMD_STATUS = one of two typed values: "exit:<code>"
  for a normal non-zero exit, or "runner_error" when the runner
  returned Err(CmdError::Failed(_)) for any reason. Signal death
  falls into "runner_error" because output_to_raw returns
  Err(CmdError::Failed) on signals (the runner translates the
  signal name into the error's internal detail string, but that
  string is never logged). The raw CmdError::Failed(detail)
  string is never logged (it carries the full argv and stderr).
• BRAID_EXTCMD_KIND = the typed braid error variant the caller
  classified the failure into (e.g. EnospcOnReplace,
  DeviceBusy, Cmd for the runner-error path) -- another Rust-
  side symbol, not free text

Raw subprocess stderr is not logged in v1. cryptsetup, btrfs,
util-linux and friends echo device paths, mapper names, mount points,
and other operator-supplied identifiers into stderr; the plan already
forbids logging by-id paths, and a regex scrubber over free-form
tool output is too leaky to be the line of defence. Operators who
need the full stderr can read it from the unit's normal journald
stream alongside the audit event (same BRAID_RUN_ID).

D6. Always-on; no NixOS option

No services.braid.audit.enable toggle. Audit is a small, fixed
volume (a handful of events per command invocation), always-on,
zero-config. journald already provides retention/rotation knobs via
services.journald.extraConfig -- operators control durability there,
not via braid. Documenting the relevant journald knobs is part of
this plan (D9 below).

D7. SyslogIdentifier on existing braid units (sub-step)

Add SyslogIdentifier = "braid" to every braid-* systemd unit
defined in modules/braid/. Verified inventory at time of writing
(grep modules/braid/ -e 'systemd.services.braid-'):

• modules/braid/storage.nix: braid-unlock, braid-online,
  braid-scrub, braid-scrub-resume-trigger, braid-auto-unlock
• modules/braid/monitor.nix: braid-monitor, braid-alert
• modules/braid/ups.nix: braid-ups-secrets
• modules/braid/fan-control.nix: braid-fan-reload (and not
  hddfancontrol-braid, which is not braid-* prefixed and is
  left out by the prefix rule)

Without SyslogIdentifier = "braid" on each, journalctl -t braid
only catches direct-CLI invocations; with it, both invocation modes
(direct CLI and systemd-driven) converge under one identifier.

This is a small unrelated cleanup but pairs naturally with audit work
because it determines the canonical journalctl filter shape we
document.

D8. Event taxonomy

Each event carries:

• MESSAGE_ID -- a stable per-event-name UUID, generated once and
  hard-coded in audit::message_ids. Lets operators do
  journalctl MESSAGE_ID=<uuid> to find every instance regardless of
  field schema drift.
• SYSLOG_IDENTIFIER=braid
• BRAID_AUDIT=1 (discriminator -- one filter to find all audit
  records: journalctl BRAID_AUDIT=1)
• BRAID_RUN_ID=<uuid-v7>
• BRAID_COMMAND=<subcommand name>
• BRAID_EVENT=<event name>
• PRIORITY= (6 info / 5 notice / 3 err -- see per-event table below)
• MESSAGE=<short human summary> for default journalctl output
• event-specific BRAID_* fields

v1 event list with priority and event-specific fields:

event	priority	extra fields
command_started	info	BRAID_FLAGS_SUMMARY, per-cmd counts
command_finished	info	BRAID_DURATION_MS, BRAID_AUDIT_DROPPED
command_failed	err	BRAID_ERROR_KIND, BRAID_DURATION_MS, BRAID_AUDIT_DROPPED
command_refused	notice	BRAID_REFUSE_REASON (D3 codes; no detail field, see D3)
pool_json_classified	info	BRAID_POOL_JSON_SHAPE (Missing/ValidUuidKeyed/LegacyNameKeyed/Corrupt)
pool_json_written	info	BRAID_MEMBER_COUNT
pending_op_written	notice	BRAID_OP_KIND (Add/Remove/RemoveMissing/Replace), BRAID_OP_PHASE
pending_op_cleared	info	BRAID_OP_KIND, BRAID_OP_PHASE (final phase)
pending_op_recovery_started	notice	BRAID_OP_KIND, BRAID_OP_PHASE, BRAID_OP_STARTED_AT
pending_op_recovery_finished	notice	BRAID_OP_KIND, BRAID_DURATION_MS
recovery_decision	notice	BRAID_RECOVERY_DECISION (mirror of RecoverCompletion discriminant), BRAID_OP_KIND
external_command_failed	err	BRAID_EXTCMD_NAME, BRAID_EXTCMD_STATUS (exit:/runner_error), BRAID_EXTCMD_KIND
sidecar_written	notice	BRAID_SIDECAR_PATH (filename only, not full path), BRAID_SIDECAR_REASON

Stable event names are part of the v1 contract: do not rename them in
subsequent versions; add new events rather than rename. (This is the
only "compat" rule audit logging owns -- it does not touch braid's
"no backwards compatibility" stance for on-disk formats or CLI flags.)

Emit-site rule: pending_op_written is emitted by write_journal
because it owns the &Journal argument; pending_op_cleared is
emitted by the call sites of clear_journal because the primitive
itself does not (see Critical files for the exact sites). This
asymmetry is deliberate, not an oversight.

D10. Subprocess failure seam: semantic classifiers, not the runner

cli/src/cmd.rs output_to_raw returns Ok(RawCommandOutput { exit_status }) for every normal non-zero exit; it only returns
Err(CmdError::Failed) on spawn errors and signal death. Real
btrfs/cryptsetup/lsblk failures (ENOSPC, device busy, wrong
passphrase, unknown subvol, malformed JSON, etc.) flow through Ok
and are turned into typed braid errors by the caller (e.g.
add::install_target, replace::execute, remove::run_balance,
probe::probe_pool).

external_command_failed therefore fires from the caller, not from
the runner. Each caller already pattern-matches on
output.exit_status (or parses stderr) to decide "expected" vs
"failure"; that classifier is the seam.

Implementation shape:

pub enum ExtcmdStatus {
    Exit(i32),     // serializes to "exit:<n>"
    RunnerError,   // serializes to "runner_error"
}

pub fn report_external_command_failed(
    name: &'static str,
    status: ExtcmdStatus,
    kind: &'static str,
);

name is the static CmdRequest variant name available at every
call site; kind is the Rust variant name of the typed braid error
the call site actually constructs at that path. Most non-zero-exit
paths construct a Failed variant; runner-error paths construct
whichever variant the call site uses (see two patterns below).

Dual emit pattern is mandatory at each audited classifier. In
this codebase typed errors carry a #[from] CmdError arm so that
the runner.run(...)? pattern short-circuits before any
exit_status block runs. The arm's name varies: it is Cmd in
pool.rs:15, luks.rs:139, mount.rs:23, but InvocationFailed
in ups.rs:35 (UpsQueryError::InvocationFailed(#[from] CmdError)),
and could be anything else in a new module. Emitting only inside
the exit_status != 0 branch would silently miss every spawn /
signal / stdin-pipe failure. Each audited classifier therefore
emits on both paths. There are two call-site shapes in the
current tree, and in both the kind argument must be the actual
variant name the call site constructs.

Pattern A: ? with #[from] CmdError -- the dominant pattern in
pool.rs, luks.rs, mount.rs, ups.rs. The runner-error
short-circuits into whichever typed-error variant carries the
#[from] CmdError attribute. The audit kind is the literal name
of that variant -- not a hard-coded "Cmd":

let result = runner.run(&req).map_err(|e| {
    audit::report_external_command_failed(
        "BtrfsDeviceScanForget",
        ExtcmdStatus::RunnerError,
        "Cmd",            // matches PoolError::Cmd(#[from] CmdError)
    );
    e
})?;
if result.exit_status != 0 {
    audit::report_external_command_failed(
        "BtrfsDeviceScanForget",
        ExtcmdStatus::Exit(result.exit_status),
        "Failed",
    );
    return Err(PoolError::Failed(/* ... */));
}

For ups.rs::query_ups, the same Pattern A shape but with the
correct kind:

let raw = runner.run(&CmdRequest::UpscQuery { name: ... }).map_err(|e| {
    audit::report_external_command_failed(
        "UpscQuery",
        ExtcmdStatus::RunnerError,
        "InvocationFailed",   // matches UpsQueryError::InvocationFailed(#[from] CmdError)
    );
    e
})?;
if raw.exit_status != 0 {
    audit::report_external_command_failed(
        "UpscQuery",
        ExtcmdStatus::Exit(raw.exit_status),
        "QueryFailed",        // matches UpsQueryError::QueryFailed { ... }
    );
    return Err(UpsQueryError::QueryFailed { /* ... */ });
}

Pattern B: .map_err(|e| TypedError::Variant(format!(...)))? --
used by the three direct classifiers in
recover.rs::relock_and_remount (Umount, BtrfsDeviceScanForget,
CryptsetupClose). These intentionally construct
RecoverError::Failed, not RecoverError::Cmd, to preserve
recovery-specific context in the message. The audit kind must
match what the site actually returns:

let forget = runner
    .run(&CmdRequest::BtrfsDeviceScanForget { devices: forget_devs })
    .map_err(|e| {
        audit::report_external_command_failed(
            "BtrfsDeviceScanForget",
            ExtcmdStatus::RunnerError,
            "Failed",     // matches RecoverError::Failed(format!(...))
        );
        RecoverError::Failed(format!("recover remount cycle: scan --forget: {e}"))
    })?;
if forget.exit_status != 0 {
    audit::report_external_command_failed(
        "BtrfsDeviceScanForget",
        ExtcmdStatus::Exit(forget.exit_status),
        "Failed",
    );
    return Err(RecoverError::Failed(format!(...)));
}

General rule (one rule for both patterns): the runner-error
kind is always the literal Rust variant name the call site
constructs on the runner-error path. For Pattern A that's
whichever variant carries #[from] CmdError at that module --
"Cmd" for pool.rs/luks.rs/mount.rs typed errors,
"InvocationFailed" for UpsQueryError, and whatever name the
typed error literally uses elsewhere. For Pattern B it's the
variant named in the .map_err constructor (e.g. "Failed").
The unit tests in the test section assert this per-site.

output_to_raw itself stays audit-free: it does not know the
caller's static CmdRequest variant name or typed-error kind, and
threading those into the runner would re-introduce the
"hope-one-hook-catches-everything" trap D10 explicitly avoids.

Coverage scope: helper-level classifiers, not command modules.
Auditing "every site where a typed error is constructed from a
CmdRequest result" inside top-level command modules
(add.rs/remove.rs/...) misses the actual ownership boundary: in
this codebase, top-level commands compose shared helpers that
own the exit_status -> typed error classification. add /
remove / replace / unlock / recover mostly call those
helpers and re-map their errors. Auditing only at the command layer
would either miss failures or log them after a generic wrap that
loses BRAID_EXTCMD_KIND fidelity.

Inclusion rule (audit these): each classifier function below, at the
site where a typed *Error::* variant is constructed from a non-zero
RawCommandOutput. The inventory is per-function (not per-module)
because classifiers in this codebase do not match cleanly to module
boundaries -- luks.rs exports many distinct classifiers, lock.rs
keeps a couple of CmdRequest classifiers inline rather than
delegating, and cryptsetup close classification lives in its own
small module. Audited functions confirmed in the current tree:

• cli/src/pool.rs -- function-level classifiers (each constructs a
  fatal PoolError::* from a non-zero RawCommandOutput):

  • pool_add_device (line 206) -> btrfs device add + pre-step
    BtrfsDeviceScanForget and WipefsBtrfs
  • pool_balance_raid1 (line 339), pool_balance_single
    (line 363), pool_balance_raid1_soft (line 388),
    pool_balance_resume (line 417) -> btrfs balance family;
    failure shape produced by helper balance_error (line 253)
  • pool_remove_device (line 479) and pool_remove_device_using
    (line 496) -> btrfs device remove; failure shape via helper
    device_remove_error (line 302)
  • pool_replace_device (line 534) -> btrfs replace start;
    failure shape via helper replace_error (line 274)
  • pool_resize_device (line 558) -> btrfs filesystem resize
  • pool_bootstrap_mount (line 656) and
    pool_bootstrap_mount_raid1 (line 691) -> initial mount
    classifier used by add/recover on a freshly assembled pool

  evict_present_device (line 594) is not in the audited list:
  it composes pool_balance_single + pool_remove_device (both
  already audited) plus close_mapper_best_effort (excluded as a
  warn-and-return-bool path). The audit emits land in the callees,
  not the composer.

• cli/src/luks.rs -- function-level classifiers:

  • luks_format (line 451) -> LuksError::FormatFailed
  • verify_passphrase (line 593) -> verify-flow LuksError variants
  • verify_key_file (line 1000) -> key-file verify
  • ensure_luks_open (line 921) -> cryptsetup luksOpen failure
  • ensure_luks_open_with_key_file (line 968) -> luksOpen with key
  • enroll_key_file (line 1013) -> cryptsetup luksAddKey failure
  • check_key_slot (line 1037) -> cryptsetup luksDump keyslot
    inspection; fatal classifier (distinct from the probe path in
    probe_pool_keyfile_enrollment at line 1067, which is on the
    exclusion list)
  • backup_luks_header_to (line 487) and the two backup_luks_header*
    wrappers (lines 528, 549) -> cryptsetup luksHeaderBackup

  There is no luks_close / luks_open / luks_test_passphrase
  function (those names were stale from an earlier draft). There is
  no luksKillSlot or luksHeaderRestore classifier path -- the
  names appear only in operator-facing remediation text. Do not add
  audit hooks for them in v1.

  Two additional luks.rs helpers are parser-mediated rather than
  direct exit-status classifiers and live in the per-site policy
  table below (parser-mediated classifiers) instead of this
  function-level list, because their runner-error and parser branches
  are both fatal via ? (all-fatal Pattern A) and need the dual
  emit pair documented there:

  • luks_uuid_for_device (line 828) -- CryptsetupLuksUuid ->
    parse_cryptsetup_luks_uuid; OwnershipError::{Cmd, Parse}.
  • classify_mapper_ownership (line 838) -- runs two
    CmdRequest calls (CryptsetupStatus at line 850-852 and
    CryptsetupLuksUuid at line 894-896) plus their parsers.
    Three audited classifier sites total (the second
    CryptsetupLuksUuid site is mixed-fatal -- the "backing not
    LUKS" arm at line 899-905 is a semantic Conflict outcome,
    not a subprocess failure).
    Top-level luks.rs callers (ensure_luks_open /
    ensure_luks_open_with_key_file) call these helpers and re-map
    OwnershipError into LuksError via the existing
    From<OwnershipError> for LuksError impl; the helper-level emit
    carries BRAID_EXTCMD_NAME accurately, so the callers do not
    get a separate emit for the same subprocess (D10's "emit at the
    call site that still has the static CmdRequest in scope" rule).

• cli/src/mapper_close.rs -- close_mapper_with_retry (line 22)
  classifies CryptsetupClose exits into CloseMapperError::Failed /
  CloseMapperError::DeviceBusy. This is where cryptsetup close
  classification actually lives, not in luks.rs. close_mapper_best_effort
  (line 70) is best-effort (warns and returns bool); it does not
  construct a typed failure, so it stays out of the audited list.

• cli/src/mount.rs -- scan_and_mount (line 796) classifies
  BtrfsDeviceScanAll and the mount syscall into MountError::Failed.
  Mount only; there is no unmount tail in this module.

• cli/src/lock.rs -- one inline classifier inside cmd_lock_impl:
  the Umount classifier around line 528 (umount exit ->
  LockError). The BtrfsDeviceScanForget block around line 567 is
  not audited: that path warns-and-continues on non-zero (see
  source, "continuing" status line), so it does not construct a
  typed LockError and has no BRAID_EXTCMD_KIND to report. It is
  a nonfatal cleanup warning, deliberately out of scope for
  external_command_failed in v1.

• cli/src/recover.rs -- recover-specific direct classifiers that
  do not delegate to a helper:

  • scan_mapper (line 2278) -> RecoverError from
    BtrfsDeviceScan on a single mapper
  • relock_and_remount (line 3462) -- this function intentionally
    does not delegate to the standard helpers; three of its
    CmdRequest calls are direct classifiers that each construct
    RecoverError::Failed on both the runner-error and non-zero
    branches:
    1. inline Umount classifier (the "recover remount cycle:
       umount" path)
    2. inline BtrfsDeviceScanForget classifier at line 3521 (the
       "recover remount cycle: scan --forget" path -- it does
       not delegate to lock.rs either)
    3. inline CryptsetupClose classifier at line 3555 (does not
       delegate to mapper_close.rs::close_mapper_with_retry)
       All three sites need a dual-path emit pair. The subsequent
       re-scan_and_mount call delegates to mount.rs and is covered
       by that helper's emit.

• cli/src/enroll_key_file.rs -- mostly orchestration; the actual
  cryptsetup luksAddKey / header-backup classification is done by
  the luks.rs helpers it composes (see above). Audit emits land in
  those luks.rs callees. One direct classifier remains inside
  validate_generated_keyfile_target (around line 552): the
  MountpointCheck runner.run at line 579-581 is a mixed-fatal
  state-check (runner-error branch only audited; non-zero exit is
  a Validation refusal driven by the documented "not a mountpoint"
  state, not a subprocess failure). See D10 table.

• cli/src/scrub_cancel.rs -- cmd_scrub_cancel (line 50): direct
  classifier for btrfs scrub cancel exit. Has its own typed
  error; not delegated to a helper.

• cli/src/scrub_resume_or_start.rs -- cmd_scrub_resume_or_start
  (line 24): direct classifier for btrfs scrub start/resume
  exits. Has its own typed error.

• cli/src/scrub_needs_resume.rs -- cmd_scrub_needs_resume
  (line 24): single BtrfsScrubStatus site whose typed error
  carries both Cmd(#[from] CmdError) (runner-error path) and
  Parse(#[from] ParseError) (parser-error path, including
  ParseError::CommandFailed for the non-zero exit). Both branches
  are fatal via ?. Treated as an all-fatal site for testing: a
  full dual-path pair, with runner-error kind = "Cmd" and
  parser-path kind = "Parse" (see D10 per-site policy table).

• cli/src/ups.rs -- query_ups (line 42): classifier for
  upsc invocation; constructs UpsQueryError::QueryFailed on
  non-zero exit and UpsQueryError::InvocationFailed on
  Err(CmdError::Failed(_)). Both paths are fatal and get the
  dual-path emit pair.

Branch-specific classifier table (parser-mediated + state-check,
mixed-fatal-aware). Two related shapes share this table:

1. Parser-mediated classifiers. Braid's parsers return a typed
   ParseError, one variant of which is ParseError::CommandFailed { exit_code, stderr, .. }. The classifier seam is the caller's
   match arm that lifts that variant into a typed module-error.
2. State-check helpers. runner.run(&CmdRequest::MountpointCheck { ... })? followed by if mp_result.exit_status == 0 { ... }
   (or != 0) is a direct exit-status state branch -- no parser
   involved. The non-zero exit means "not a mountpoint", which is a
   state, not a subprocess failure; but the ? on runner.run
   still makes the runner-error branch a real subprocess failure.

Only the caller knows whether the non-zero exit is fatal or an
expected state. Several sites in the current tree are mixed:
the runner-error branch (Err(e) from runner.run(...)) and the
non-zero-exit / parser-CommandFailed branch take different
policies. Audit only the fatal branches at each site; leave
the nonfatal (state / semantic-outcome) branches alone.

Per-site audit policy table (verified against source -- emit at
each row's file:line, where the static CmdRequest variant is
still in scope; never emit from a generic handler that has already
lost the variant):

Site	runner-error branch	parser branch
probe.rs:175-191 CryptsetupLuksUuid (in probe_disk)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	maps to Ok(ConfigDisk { state: PresentNotLuks }) at line 183 -- NOT fatal, do not audit
probe.rs:204-214 CryptsetupLuksDumpText (in probe_disk, LUKS version + label)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	fatal via ? -> ProbeError::Parse (parse_cryptsetup_luks_version and parse_cryptsetup_luks_label) -- audit, kind "Parse". Also note the explicit ProbeError::UnsupportedLuksVersion arm on line 213 -- that is not a subprocess failure (the command succeeded, the version is wrong), so it does not emit external_command_failed.
probe.rs:312-315 BtrfsFilesystemShow (in probe_pool_alerts)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	fatal via ? -> ProbeError::Parse(#[from] ParseError) -- audit, kind "Parse"
probe.rs:334-337 CryptsetupStatus (sibling probe function)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	fatal via ? -> ProbeError::Parse -- audit, kind "Parse". The if !status.is_active { ... } arm at line 339 is not a subprocess failure (command succeeded; status content drives the outcome) -- do not emit.
probe.rs:397-400 BtrfsFilesystemShow (sibling probe function)	fatal via ? -> ProbeError::Cmd -- audit	fatal via ? -> ProbeError::Parse -- audit
probe.rs:427-430 CryptsetupStatus (second sibling probe function)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	fatal via ? -> ProbeError::Parse -- audit, kind "Parse". Same is_active/device == None arms are not subprocess failures and do not emit.
probe.rs:460-463 CryptsetupLuksUuid (in the same sibling probe function)	fatal via ? -> ProbeError::Cmd -- audit, kind "Cmd"	fatal via ? -> ProbeError::Parse -- audit, kind "Parse"
probe.rs:521-524 BtrfsFilesystemShow (sibling probe function)	fatal via ? -> ProbeError::Cmd -- audit	fatal via ? -> ProbeError::Parse -- audit
preflight.rs::probe_missing_devids BtrfsDeviceUsageRaw (~line 305)	fatal `.map_err(	e
remove.rs:694 check_eviction_space BtrfsDeviceUsageRaw	Ok(EvictionCheck::ProceedWithWarning(...)) -- warn-and-proceed, NOT fatal, do not audit	fatal -> Err(RemoveError::Validation { ... }) -- audit, kind "Validation"
remove.rs:760 check_single_survivor BtrfsDeviceUsageRaw	fatal .map_err -> RemoveError::Validation(...) -- audit	fatal .map_err -> RemoveError::Validation(...) -- audit
remove.rs:782 check_single_survivor BtrfsFilesystemDfJson	fatal .map_err -> RemoveError::Validation(...) -- audit	fatal .map_err -> RemoveError::Validation(...) -- audit
status.rs:578-581 BtrfsFilesystemDfJson (get_pool_df)	fatal via ? -> StatusError::Cmd -- audit	fatal via ? -> StatusError::Parse -- audit
status.rs:625-628 BtrfsFilesystemUsageRaw (get_capacity)	fatal via ? -> StatusError::Cmd -- audit	fatal via ? -> StatusError::Parse -- audit
status.rs:631-634 BtrfsDeviceUsageRaw (get_capacity)	fatal via ? -> StatusError::Cmd -- audit	fatal via ? -> StatusError::Parse -- audit
status.rs:652-655 BtrfsDeviceStatsJson (get_device_stats)	fatal via ? -> StatusError::Cmd -- audit	fatal via ? -> StatusError::Parse -- audit
ack.rs:84-86 BtrfsDeviceStatsJson	fatal via ? -> AckError::Cmd -- audit, kind "Cmd" (or literal variant on the typed enum)	fatal via ? -> AckError::Parse -- audit, kind "Parse"
monitor.rs:78-84 BtrfsDeviceStatsJson (inline)	fatal `.map_err(	e
scrub_needs_resume.rs::cmd_scrub_needs_resume BtrfsScrubStatus site	fatal via ? -> ScrubNeedsResumeError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	fatal via ? -> ScrubNeedsResumeError::Parse(#[from] ParseError) -- audit, kind "Parse"
luks.rs:828 luks_uuid_for_device CryptsetupLuksUuid (helper, called by classify_mapper_ownership via the expected_uuid closure and by direct callers)	fatal via ? -> OwnershipError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	fatal via ? -> OwnershipError::Parse(#[from] ParseError) -- audit, kind "Parse"
luks.rs:850-852 classify_mapper_ownership CryptsetupStatus (helper, called by ensure_luks_open, ensure_luks_open_with_key_file, and other open/probe paths)	fatal via ? -> OwnershipError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	fatal via ? -> OwnershipError::Parse(#[from] ParseError) -- audit, kind "Parse"
luks.rs:894-896 classify_mapper_ownership second CryptsetupLuksUuid (the backing-UUID readback after the mapper is confirmed active)	fatal via ? -> OwnershipError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	mixed: the explicit Err(_) if cryptsetup_luks_uuid_reports_not_luks(...) arm at line 899-905 returns OwnershipError::Conflict { found: None } -- this is a semantic outcome ("backing device isn't LUKS, so mapper backing is wrong"), not a subprocess failure: do not emit. The general Err(e) => OwnershipError::Parse(e) arm at line 906 is fatal -- audit, kind "Parse".
discover.rs:340-342 CryptsetupIsLuks (in the per-by-id-symlink loop in the discover scanner)	fatal via ? -> DiscoverError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	if raw.exit_status != 0 { continue; } at line 343-345 -- the non-zero exit means "not LUKS, skip this disk", which is the documented expected-non-LUKS path: NOT fatal, do not audit. (This is one of the few sites where the runner-error and non-zero-exit branches take opposite policies. ? is fatal because a real runner failure shouldn't get silently lumped in with "this disk isn't LUKS"; the explicit continue is nonfatal because non-zero is the documented "not LUKS" answer.)
discover.rs:353-355 CryptsetupLuksDumpText (in the same loop, after CryptsetupIsLuks succeeded with exit 0)	fatal via ? -> DiscoverError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	three nonfatal match parse_cryptsetup_luks_version(&dump_raw) arms at line 357-376: Err(ParseError::CommandFailed) -> DiscoverWarning::LuksDumpFailed + continue; Err(other) -> DiscoverWarning::LuksDumpUnparseable + continue; the UnsupportedLuksVersion arm at line 377-383 is also a warn-and-continue. Subsequent parse_cryptsetup_luks_label at line 385-387 uses .ok() (silent skip). NOT fatal, do not audit on the parser side.
recover.rs:3369-3381 wait_for_kernel_replace_to_finish BtrfsReplaceStatus (the kernel-resumed dev_replace wait loop)	Err(_) => { emit_status(... "kernel dev_replace status check failed -- proceeding"); return Ok(()); } at line 3373-3380 -- best-effort warn-and-proceed (a transient runner Err on a never-replaced pool would otherwise force-fail every recover): NOT fatal, do not audit.	Err(_) => { ...; return Err(RecoverError::Failed(message)) } at line 3384-3391 -- any parser Err (including ParseError::CommandFailed for a non-zero btrfs replace status exit) means "we cannot reason about kernel replace state", which preserves the journal and aborts with a fatal RecoverError::Failed: audit, kind "Failed" (matches the variant the Err arm constructs at line 3390).
mount.rs:216 plan_open_pool_inner MountpointCheck (state-check, not parser-mediated)	fatal via ? -> MountError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	if mp_result.exit_status == 0 { ... return Ok(None); } (already-mounted) vs fall-through to the open plan (not-mounted) -- both are documented states, not subprocess failures: NOT fatal, do not audit.
lock.rs:680 plan_lock_inner MountpointCheck (state-check, not parser-mediated)	fatal via ? -> LockError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	let pool_was_mounted = mp_result.exit_status == 0; (state captured into a bool and used to route the rest of plan_lock_inner): NOT fatal, do not audit.
recover.rs:2082 discover_add_targets_before_mount MountpointCheck (state-check, not parser-mediated)	fatal via ? -> RecoverError::Cmd(#[from] CmdError) -- audit, kind "Cmd"	if mount_result.exit_status == 0 { return Ok(None); } (already mounted, no per-target add work needed): NOT fatal, do not audit.
enroll_key_file.rs:579 validate_generated_keyfile_target MountpointCheck (state-check, not parser-mediated)	fatal via ? -> EnrollKeyFileError::Cmd(#[from] crate::cmd::CmdError) -- audit, kind "Cmd"	if mountpoint.exit_status != 0 { return Err(EnrollKeyFileError::Validation(...)) } at line 582-593 -- the validation error is a semantic "USB not mounted / not a mountpoint" refusal driven by the documented non-zero state, not a subprocess failure: NOT fatal, do not audit. (The refusal is surfaced by braid's normal Validation path; if a refusal-reason code is desired here it belongs in D3, not as external_command_failed.)
add.rs:336 probe_closed_present_luks_target_uuid CryptsetupLuksUuid (open-boundary re-probe before mapper open)	`.map_err(	e
replace.rs:995 probe_existing_luks_new_target_uuid CryptsetupLuksUuid (open-boundary re-probe before mapper open on the replace new disk)	`.map_err(	e

Explicitly excluded (not audit sites):

• probe.rs:183 (Ok(ConfigDisk { state: PresentNotLuks })).
  Auditing this would log a normal classification as a failure.
• remove.rs:694 runner-error and Err(other) parse branches
  (check_eviction_space warn-and-proceed).
• discover.rs:340-345 non-zero exit (not-LUKS skip via
  continue).
• discover.rs:353-376 and discover.rs:377-383 parser branches
  (LuksDumpFailed / LuksDumpUnparseable /
  UnsupportedLuksVersion warnings -- discover surfaces these as
  structured DiscoverWarnings for the operator; they are
  documented expected states, not subprocess failures).
• luks.rs:899-905 classify_mapper_ownership "backing not LUKS"
  arm (OwnershipError::Conflict { found: None }). The cryptsetup
  command succeeded; the parser detected "this device isn't LUKS",
  which is the documented "stale/misbacked mapper" outcome. Logging
  it as external_command_failed would mislead the operator.
• recover.rs:3373-3380 wait_for_kernel_replace_to_finish
  runner-error branch (warn-and-proceed via return Ok(())).
• mount.rs:216, lock.rs:680, recover.rs:2082,
  enroll_key_file.rs:579 MountpointCheck non-zero-exit
  branches. Non-zero on MountpointCheck is the documented "not a
  mountpoint" state (mount.rs / lock.rs / recover.rs use it for
  routing; enroll_key_file.rs surfaces it as a
  Validation refusal). It is not a subprocess failure for audit
  purposes. The runner-error branch via ? is fatal and is
  audited above.
• online_state.rs::is_mountpoint (line 128) is a production
  MountpointCheck helper, but its callers (mark_online,
  mark_offline) treat every OnlineError it returns as a
  warn-and-proceed via eprintln!("braid: WARNING: ...") plus an
  Ok(()) (see lines 239-244, 290-298). That includes both
  OnlineError::Spawn (runner-error) and OnlineError::Mountpoint
  (exit > 1) -- there is no fatal path. The lifecycle helper is
  therefore best-effort by construction; see the dedicated
  online_state.rs lifecycle subsection below for the full
  policy. All other MountpointCheck grep hits not enumerated in
  the table are test-only fixtures/mocks.
• add.rs:336 and replace.rs:995 "UUID mismatch" arms (Ok(parsed) => where parsed.uuid != *expected). The subprocess succeeded and
  answered with a UUID; the caller's policy is "the wrong UUID is a
  semantic refusal, not a subprocess failure". Same exclusion for
  the Err(other) parse arm at each site (output-shape corruption
  after a possibly-successful command -- the "HasBtrfs follow-up"
  rule, see D10 below).
• monitor.rs::cmd_monitor's ProbeError::Parse handler. By the
  time cmd_monitor sees ProbeError::Parse (wrapped twice -- by
  probe_pool_alerts calling the parser, then by cmd_monitor
  catching the wrap), the static CmdRequest variant name is no
  longer in scope. The only safe surrogate would be the parsed
  error's to_string(), which carries argv and stderr and is
  forbidden by D5. Audit emission for that failure must happen
  upstream at the concrete probe call site
  (probe.rs:312-315, where BtrfsFilesystemShow is still in
  scope as the static CmdRequest). Do not add an audit emit in
  cmd_monitor's ProbeError::Parse arm; the upstream site
  covers it.

Coverage rule: emit at the call site that still has the static
CmdRequest variant in scope. Where multiple upstream emit sites
feed one downstream handler (e.g. probe.rs -> cmd_monitor),
the upstream sites are the authoritative emit points and the
downstream handler does not emit.

When an audited site fires, emit the dual-path pair with:

• BRAID_EXTCMD_NAME = the static CmdRequest variant the parser
  was reading (e.g. BtrfsDeviceUsageRaw).
• BRAID_EXTCMD_STATUS = "exit:<n>" from CommandFailed's
  exit_code field for the parser branch; "runner_error" for
  the runner-error branch if that branch is audited at this site.
• BRAID_EXTCMD_KIND = the typed-error variant the classifier is
  constructing for that branch (e.g. "Validation" for
  remove.rs sites, "Parse" for the scrub_needs_resume
  wrapper, etc. -- always the actual variant name).

The "no caller of a parser is left unaudited if its non-zero branch
is fatal" rule is enforced by behavioral tests per audited site
(see test section); the explicit exclusions above mean the rule is
trivially satisfied at the nonfatal sites because they never enter
the audit funnel.

classify_btrfs_probe sites (variant-classification, distinct
from ParseError::CommandFailed). BtrfsFilesystemShowTarget
output can also be passed to
parse::btrfs_filesystem_show::classify_btrfs_probe, which returns
a DeviceBtrfsProbe enum (NoBtrfs, HasBtrfs, Unknown(msg)).
The caller branches on the variant -- this is a different
classification mechanism than the parser-mediated CommandFailed
table above (no ParseError is constructed; the classifier picks
between three documented outcomes). NoBtrfs and HasBtrfs are
not subprocess failures and do not emit; Unknown is a fatal
subprocess-failure classifier and emits. The runner-error branch
(Err from runner.run) is fatal at the callers below and emits.

Site	runner-error branch	DeviceBtrfsProbe::Unknown branch
add.rs:168 classify_braid_disk_fsid BtrfsFilesystemShowTarget	fatal via ? -> AddError::Cmd (Pattern A #[from]) -- audit, kind "Cmd"	fatal AddError::Cmd(CmdError::Failed(format!(...))) (Pattern B) -- audit, kind "Cmd" (matches the typed-error variant constructed at line 175)
recover.rs:2265 visible_btrfs_fsid BtrfsFilesystemShowTarget	fatal via ? -> RecoverError::Cmd (Pattern A #[from]) -- audit, kind "Cmd"	fatal RecoverError::Failed(msg) (Pattern B) -- audit, kind "Failed"

Excluded DeviceBtrfsProbe branches (not subprocess failures, do
not emit):

• DeviceBtrfsProbe::NoBtrfs at both sites (Ok(...) return).
• DeviceBtrfsProbe::HasBtrfs at both sites (falls through to the
  subsequent parse_btrfs_filesystem_show(&show_raw)? parser
  call -- see "follow-up parse calls" below).

Excluded full site (nonfatal bootstrap detection):

• recover.rs:1010 -- a match runner.run(...) { Ok(raw) => matches!(classify_btrfs_probe(&raw), DeviceBtrfsProbe::NoBtrfs), Err(_) => false } inside the bootstrap-mount-failure advisory
  path. Runner errors are explicitly mapped to false here, not
  propagated as a fatal subprocess failure. Do not emit; it would
  log a false external_command_failed for what is documented as
  a best-effort detection.

Follow-up parse calls after HasBtrfs are not
external_command_failed sites. The follow-up
parse_btrfs_filesystem_show(&show_raw)? calls at add.rs:184
(in the HasBtrfs arm) and recover.rs:2272 (inside the
HasBtrfs arm) only run after classify_btrfs_probe returned
HasBtrfs, which by construction requires exit_status == 0 on
the same RawCommandOutput. The ? can therefore never short-
circuit on ParseError::CommandFailed -- the subprocess has
already succeeded. Any error there is output-shape corruption
after a successful command (malformed JSON, missing UUID line,
etc.), not a subprocess failure. Auditing them as
external_command_failed would either log a false-positive event
or require an impossible non-zero test setup. They are explicitly
not in this plan's external_command_failed inventory. (A
future v2 event like external_command_output_unparseable could
cover them; out of scope.)

Top-level command modules (add.rs, remove.rs, remove_missing.rs,
replace.rs, recover.rs, unlock.rs) do not get a separate
audit emit; their job is to call the helpers above and re-map their
errors. The helper-level emit already carries BRAID_EXTCMD_NAME /
BRAID_EXTCMD_KIND accurately. If a top-level command introduces a
new direct CmdRequest classifier of its own (not delegated to a
helper), it joins the inclusion list at that site.

discover.rs's CryptsetupIsLuks and CryptsetupLuksDumpText
sites (in the per-by-id-symlink loop in the discover scanner) are
also direct classifiers, not helper-delegated. They sit in the
parser-mediated table above with only the runner-error branch
audited: their non-zero-exit and parser-CommandFailed branches
are documented expected/warning states (not-LUKS skip, LuksDump
upstream wording change), not subprocess failures. Auditing the
nonfatal branches would log normal "this disk isn't LUKS / LuksDump
quirk" outcomes as failures.

recover.rs::wait_for_kernel_replace_to_finish (line 3358) is a
direct classifier whose policy is the inverse of the discover
ones: only the parser-CommandFailed branch is audited, because
the runner-error branch is best-effort (transient runner Err on a
never-replaced pool would otherwise force-fail every braid recover)
while the parser branch indicates "we cannot reason about kernel
replace state" and preserves the journal with a fatal
RecoverError::Failed. These three mixed-fatal sites get the same
per-branch coverage tests called out for remove.rs:694 and the
probe.rs PresentNotLuks site (see test section).

MountpointCheck state-check helpers at mount.rs:216,
lock.rs:680, recover.rs:2082, and enroll_key_file.rs:579 are
direct classifiers with runner-error-only audit policy: a successful
runner call always returns a documented state (exit 0 = is a
mountpoint, non-zero = not a mountpoint). Non-zero is never a
subprocess failure here; it routes the caller (mount.rs into "open
plan", lock.rs into the unmount branch, recover.rs into the
per-target probe loop, enroll_key_file.rs into a Validation
refusal). Only the ? on runner.run -- a real
spawn/signal/stdin-pipe failure -- is audited. The fact that the
non-zero branch can produce an EnrollKeyFileError::Validation
refusal at enroll_key_file.rs:582-593 does not make it a
subprocess failure; if a stable D3 refusal-reason code is desired
for that path, it belongs in D3, not in external_command_failed.

Open-boundary re-probes at add.rs:336
(probe_closed_present_luks_target_uuid) and replace.rs:995
(probe_existing_luks_new_target_uuid) are direct classifiers
whose policy distinguishes ParseError::CommandFailed (subprocess
non-zero exit -- audit) from "successful subprocess answered with
the wrong UUID" (semantic mismatch -- do not audit). The
implementation must therefore match on Err(ParseError::CommandFailed { exit_code, .. }) specifically and emit the exit-branch audit
there, while leaving the Err(other) arm and the semantic-mismatch
Ok(parsed) arm out of external_command_failed. The runner-error
branch via .map_err is always audited. The variant constructed on
all error paths is the same (TargetUuidMismatchAtOpen /
NewTargetUuidMismatchAtOpen), so the audit BRAID_EXTCMD_KIND
also matches that name on the two audited branches (runner-error +
parser-CommandFailed).

online_state.rs lifecycle helpers are not external_command_failed
sites. cli/src/online_state.rs exposes a OnlineStateOps trait
whose production impl is RealOnlineStateOps (line 102, not
SystemOnlineStateOps -- earlier drafts of this plan named it
wrong). The impl wraps five CmdRequest variants:

• SystemctlShowActiveState at line 116 (unit_active_state).
• MountpointCheck at line 132 (is_mountpoint).
• SystemctlStart at line 169 (systemctl_start).
• SystemctlStop at line 185 (systemctl_stop).
• SystemctlShowBoundBy at line 204 (list_bound_by).

Each helper does construct a typed OnlineError::* on failure
(Spawn for the runner-error branch via .map_err, plus
variant-specific exit-code errors for non-zero exits). Treated in
isolation, these look like classifier sites that would belong on
D10's inclusion list.

But every production caller of these helpers converts the error
into either a warning, an Unknown lifecycle state, or an early
return without propagating a fatal failure:

• online_state.rs::snapshot (line 226-231) ->
  unit_active_state(...).unwrap_or_else(|e| UnitActiveState::Unknown(e.to_string())). The error is folded
  into the Unknown variant; no propagation.
• online_state.rs::mark_online (line 233-286) -> the
  is_mountpoint Err arm prints "braid: WARNING: failed to check mountpoint ..." and returns Ok(()). The
  systemctl_start Err arm prints "braid: WARNING: failed to activate braid-online.service ..." and falls through to
  Ok(()). The chown/chmod errors are printed as warnings and
  ignored. The UnitActiveState::Unknown branch prints "braid: WARNING: could not read braid-online.service ActiveState ..."
  and falls through.
• online_state.rs::mark_offline (line 288-305) ->
  is_mountpoint Err is printed as a warning and execution
  continues; systemctl_stop Err is printed as a warning and
  ignored.
• lock.rs::run_lock_pre_steps (line 995-1033) is the only
  production caller of list_bound_by. The pattern is let Ok( bound_by) = online_ops.list_bound_by("braid-online.service") else { return; }; (line 1008-1010) -- an Err(_) causes
  run_lock_pre_steps to return early without printing a
  warning and without propagating an error to its caller
  (run_lock_pre_steps returns ()). The rest of the lock
  command continues. The same function also calls systemctl_stop
  in two places: line 1005 uses let _ = online_ops.systemctl_stop( unit, false); (silently swallow), and line 1018-1031 uses a
  match e that prints "braid: WARNING: failed to stop {unit} ..." and continues. Both are warn-and-proceed shapes.

There is no fatal subprocess-failure path from any of these
helpers. Auditing them as external_command_failed would log a
real subprocess failure for what braid documents as a "warn and
proceed" (or "silently skip the rest of this pre-step") lifecycle
outcome -- the operator already sees the braid: WARNING: ...
stderr line where one exists, and braid's behavior on the
control-flow side is identical whether the subprocess succeeded
or not. The audit event would be noise.

Therefore, all five online_state.rs lifecycle classifier sites
are excluded from external_command_failed in v1, both on the
runner-error branch and on the non-zero-exit branch, regardless of
caller. If v2 adds an online_state_warning event for these (a
separate, lower-priority event with explicit "diagnostic-only,
never indicates command failure" framing), it would replace this
exclusion; in v1 they are silent on the audit side.

Tests for these sites assert the negative property -- driving each
helper through the corresponding failure mode and asserting no
external_command_failed is emitted; see the test section.

Exclusion rule (do not audit these): any CmdRequest site that
treats a documented non-zero exit as a valid state, or whose
exit_status is parsed into a state value rather than a failure,
or whose caller folds every failure (including runner-error)
into a warning or Unknown-lifecycle state. Concrete excluded
sites:

• cryptsetup status <name> -- exit 4 means "no such mapper"; used
  as an existence check (e.g. lock.rs pre-check, doctor).
• Pool-state probes in cli/src/probe.rs that interpret
  not-mounted / not-present / not-yet-assembled as valid outcomes.
• btrfs filesystem show calls used purely to detect presence.
• Any cmd.rs test/mock site.
• All online_state.rs lifecycle helper sites: is_mountpoint
  (line 128), systemctl_start (line 169), systemctl_stop
  (line 185), unit_active_state (line 116), and list_bound_by
  (line 204). Callers (mark_online, mark_offline, snapshot)
  intentionally convert every error to a braid: WARNING: ...
  stderr line plus Ok(()) or fold it into UnitActiveState::Unknown.
  No fatal classifier path exists. See the dedicated subsection
  above for the rationale.

(CmdRequest::SystemctlShowActiveState -- systemctl show -P ActiveState <unit>, cmd.rs:324 -- is also excluded from
external_command_failed for a different reason from the
online_state.rs lifecycle rule: it exits 0 even for inactive
units and emits the state in stdout, so it does not reach the
non-zero classification path the audit rule applies to. The only
non-test caller other than online_state.rs::unit_active_state is
doctor.rs, which is read-only diagnostic; it is treated the same
way.)

Enforcement: implementation step 5 produces, as part of code review,
a checklist of audited CmdRequest classifier sites -- not
functions. Many audited functions classify multiple CmdRequest
calls, each of which needs its own emit pair. Concrete examples:

• pool_add_device has three classifier sites when force=true:
  BtrfsDeviceScanForget, WipefsBtrfs, BtrfsDeviceAdd.
• pool_bootstrap_mount has two sites: MkfsBtrfs and Mount.
• pool_bootstrap_mount_raid1 has two sites: MkfsBtrfsRaid1 and
  Mount.
• scan_and_mount has three runner.run(...)? sites
  (BtrfsDeviceScanAll, MountWithOptions, Mount) feeding two
  non-zero-exit classifications (one for scan -> MountError::Failed,
  one shared for both mount paths -> MountError::MountFailed).
• relock_and_remount has three direct sites (Umount,
  BtrfsDeviceScanForget, CryptsetupClose).

Each site contributes its own row to the checklist, and each row
gets a dual-path test pair (see test section). "One pair per
function" would silently drop coverage on the WipefsBtrfs /
MkfsBtrfs / second-mount sites. The plan does not enumerate every
site here because that detail belongs in the implementation PR and
would drift if hard-coded; the checklist + tests + the
"every-site-has-a-pair" anti-drift rule are the contract.

D9. NixOS documentation

A new doc docs/audit-logging.md covers:

• one-screen overview of what is logged and what is not
• canonical journalctl recipes:
  • journalctl BRAID_AUDIT=1 --output=json-pretty
  • journalctl BRAID_AUDIT=1 -t braid -p err
  • journalctl MESSAGE_ID=<external_command_failed uuid>
  • journalctl BRAID_RUN_ID=<uuid> (one invocation, end to end)
• retention guidance: point at
  services.journald.extraConfig/Storage=persistent,
  SystemMaxUse=, MaxRetentionSec= -- braid does not set these.

Add the new doc to docs/index.md.

A short new ADR docs/decisions/026-audit-logging.md (status Active)
captures: motivation, why journald and not SQLite/JSONL, the diagnostic-
only invariant, the stable-event-name contract. (024 and 025 are taken
by 024-luks-uuid-identity.md and 025-browse-vs-curated.md.)

D11. Command-outcome auditing across every main.rs exit path

cli/src/main.rs does not have a single "return value -> exit code"
funnel. Post-parse, the process exits through ~40 direct
std::process::exit(...) sites: the root gate (line 337), the
load_config_or_exit helper (definition at line 957, called at
lines 411, 578, 641, 754, 772, 865, 995, 1056), and many command-
specific direct exits inside match arms -- including special-meaning
exit codes for lock (AlreadyHeld -> 0, generic conflict -> 2,
unmount stuck -> 3), idle / monitor / scrub-needs-resume
status exits (0/1/2), and UPS JSON failure exits.

"Emit command_started / command_finished / command_failed
around each match arm" is insufficient: a naive wrapping would miss
the root gate, every load_config_or_exit, and every special-meaning
exit, and could accidentally change exit codes while threading
emission in.

Mechanism: a single audit::audited_exit(outcome: ExitOutcome, exit_code: i32) -> ! helper -- the only legal post-parse exit path.
Every existing std::process::exit(N) after CLI parse is replaced
with audit::audited_exit(<outcome>, N), where outcome selects
which terminal audit event fires:

pub enum ExitOutcome {
    /// Success path. Emits `command_finished`.
    Finished,
    /// Generic failure. Emits `command_failed` unless `run_refused`
    /// is set on the active audit context (in which case
    /// `command_refused` has already fired and nothing else emits).
    Failed,
    /// Explicit refusal helper for refusal sites that own their own
    /// exit (e.g. the root gate -- it does not return `Err` to a
    /// match arm to refuse via D3). Calls `audit::refused(reason)`
    /// internally to flip `run_refused`, then emits no extra
    /// terminal event itself. Use the matching D3 reason code.
    Refused { reason: &'static str },
}

Coverage rule: every post-parse process-terminating call --
not just std::process::exit, but any API that ends the
process -- goes through audit::audited_exit. The current exit
codes are preserved verbatim: this is a wrapping refactor, not a
semantics change.

Banned post-parse APIs in cli/src/main.rs:

• std::process::exit(_) -- direct termination.
• clap::Error::exit() (e.g. the Err(e) => e.exit() at
  main.rs:341 inside print_help_for) -- clap's error-exit
  helper calls std::process::exit internally with clap's chosen
  exit code. The replacement is to convert the clap::Error into
  a (message, exit_code) pair via the existing clap public API
  (clap::Error::print for the rendered message, .exit_code()
  for the code), print the message, then call
  audit::audited_exit(ExitOutcome::Failed, code).
• std::process::abort(), panic! in code paths intended as
  normal termination, and any other process-terminating shortcut.
  Panics that represent genuine programmer errors are out of scope
  (no audit emit; they were never reachable in normal flow).

After the patch, the following must both pass:

grep -n 'std::process::exit'   cli/src/main.rs   # zero hits except pre-parse
grep -n 'clap::Error::exit\|\.exit()'   cli/src/main.rs # zero hits in post-parse code paths

Pre-parse early exits (clap argv-parse failure before
audit::init_process_state runs) are too early for audit and stay
raw; they live above the init line and are the only documented
exception.

Root gate: at the root gate (main.rs:337 area), instead of a raw
exit(1), the call becomes
audit::audited_exit(ExitOutcome::Refused { reason: "root_required" }, 1).
This is the only place root_required is used; it justifies the new
D3 reason code.

Special exit codes preserved: the lock-path codes (0 for
AlreadyHeld, 2 for generic conflict, 3 for unmount stuck) and the
idle/monitor/scrub-needs-resume 0/1/2 codes flow through
audited_exit unchanged. The audit event chosen per path is the
semantically correct one (Finished for the 0 cases, Failed
for non-zero conflict cases, Refused { reason: ... } only if the
exit corresponds to a documented refusal).

This wrapper does not replace D3's audit::refused(...) calls
at scattered refusal sites inside command code: those fire from
inside command logic and the command's cmd_* function returns
Err(_) up to a match arm that then calls
audit::audited_exit(ExitOutcome::Failed, N) -- the run_refused
flag suppresses the duplicate command_failed. ExitOutcome::Refused
is reserved for refusal sites that own their own exit() directly
(today: only the root gate; v2 may add more).

Critical files

Files to add:

• cli/src/audit.rs -- new module: AuditEvent enum, AuditSink
  trait, JournaldSink (Linux-only), InMemorySink, NoopSink,
  init_process_state, emit, refused,
  report_external_command_failed, ExitOutcome enum (D11) and
  audited_exit(outcome, code) -> !, run_refused: AtomicBool,
  MESSAGE_ID table.
• docs/audit-logging.md -- operator-facing journalctl recipes.
• docs/decisions/026-audit-logging.md -- ADR.
• tests/cli/audit-discover-corrupt-pool-json.{nix,py} -- VM test Migrate to rust #1.
• tests/cli/audit-ack-refused.{nix,py} -- VM test Nuke schema_version #2.

Files to modify:

• cli/Cargo.toml -- add libsystemd under
  [target.'cfg(target_os = "linux")'.dependencies] (production
  Linux only); audit infrastructure stays usable on non-Linux hosts
  via NoopSink so just test-rust builds on macOS.

• cli/src/lib.rs -- pub mod audit;

• cli/src/main.rs -- one-time audit::init_process_state at the
  top of main() after CLI parse and before the root gate. Emit
  command_started at the top of each command match arm. Replace
  every post-parse std::process::exit(N) and
  clap::Error::exit() call with audit::audited_exit(outcome, N)
  (D11), which emits the single terminal event
  (command_finished / command_failed / command_refused) for
  that run. Reuses existing print_cli_error path on the failure
  branch; existing exit codes are preserved verbatim.

• cli/src/preflight.rs:44 (check_no_pending_operation) -- call
  audit::refused(...) on the Some(j) and parse-error branches
  (also flips the run_refused flag so the main wrapper does not
  emit command_failed).

• cli/src/main.rs:782 (the discover --write arm that already
  calls classify_pool_json) -- emit pool_json_classified here
  using the returned PoolJsonShape. Do not emit from inside
  membership::load_membership_from and do not emit from inside
  discover::classify_pool_json: the classifier internally invokes
  load_membership_from, so emitting at both layers would double-
  log (e.g. raw-loader emits Corrupt, then the classifier resolves
  to LegacyNameKeyed for the same file). The single emit site is
  the caller that already has the final shape.

• cli/src/membership.rs:495-510 (save_membership_to) -- emit
  pool_json_written on Ok(()) of atomic_write.

• cli/src/membership.rs:521-586 (write_corrupt_sidecar_at) --
  emit sidecar_written on successful sidecar creation.

• cli/src/journal.rs:229 (write_journal) -- emit pending_op_written
  on success, with OP_KIND / OP_PHASE derived from the journal
  argument the caller passes in. write_journal already has the
  &Journal it needs; no signature change.

• pending_op_cleared -- emit at the call sites of clear_journal,
  not inside clear_journal itself. clear_journal(paths: &StatePaths) -> Result<(), JournalError> (cli/src/journal.rs:261)
  has no Journal argument and returns Ok even when
  pending-op.json is absent (NotFound is idempotent), so it has
  neither the data nor the certainty required to emit
  BRAID_OP_KIND / BRAID_OP_PHASE. Audit-emitting inside
  clear_journal would either log spurious "cleared" events for
  no-op deletions, or require it to load+parse the journal first --
  adding new failure modes to a deletion primitive. Instead, emit
  pending_op_cleared at each call site after clear_journal(...)?
  succeeds, using the Journal already in scope at that site. Call
  sites (all in mutation/recovery paths that already hold the
  journal): cli/src/add.rs:1384, cli/src/add.rs:1466,
  cli/src/replace.rs:935, cli/src/remove.rs:455,
  cli/src/remove_missing.rs:304, and the recovery completion sites
  in cli/src/recover.rs:1170, 2372, 2750, 2876, 3045,
  3062, 3110, 3335. clear_journal itself stays audit-free.

• cli/src/recover.rs:1533 (cmd_recover) -- emit
  pending_op_recovery_started after journal load,
  recovery_decision after plan_recover resolves a RecoverCompletion
  discriminant, pending_op_recovery_finished before successful return.

• Subprocess failure call sites (D10) -- not output_to_raw,
  and not a wildcard over every CmdRequest caller. The sites are
  the per-function classifiers enumerated in D10's inclusion list:

  • pool.rs: pool_add_device, the four pool_balance_* functions,
    pool_remove_device (+ _using), pool_replace_device,
    pool_resize_device, pool_bootstrap_mount,
    pool_bootstrap_mount_raid1 (not evict_present_device; see D10)
  • luks.rs: direct exit-status classifiers -- luks_format,
    verify_passphrase, verify_key_file, ensure_luks_open (the
    CryptsetupLuksOpen site at line 936-942 -- not the
    classify_mapper_ownership call it composes; see below),
    ensure_luks_open_with_key_file (the CryptsetupLuksOpenKeyFile
    site at line 983-987 -- same caveat), enroll_key_file,
    check_key_slot, the three backup_luks_header* functions.
    Parser-mediated helpers -- luks_uuid_for_device (line 828;
    CryptsetupLuksUuid -> parse_cryptsetup_luks_uuid,
    OwnershipError::{Cmd, Parse}) and classify_mapper_ownership
    (line 838; two CmdRequest sites: CryptsetupStatus at
    850-852 and CryptsetupLuksUuid at 894-896). All three
    parser-mediated sites land in D10's per-site policy table; the
    second CryptsetupLuksUuid is mixed-fatal (the "backing not
    LUKS" arm at line 899-905 is a semantic Conflict, not a
    subprocess failure).
  • mapper_close.rs::close_mapper_with_retry
  • mount.rs::scan_and_mount, plus the mixed-fatal
    MountpointCheck state-check at mount.rs:216 (runner-error
    branch only audited).
  • lock.rs::cmd_lock_impl -- only the Umount inline classifier
    (line 528). The BtrfsDeviceScanForget block (line 567) is
    explicitly excluded (nonfatal warn-and-continue; see D10).
    Plus the mixed-fatal MountpointCheck state-check at
    lock.rs:680 in plan_lock_inner (runner-error branch only
    audited).
  • recover.rs: scan_mapper (line 2278), plus the three direct
    classifier sites inside relock_and_remount (line 3462) -- the
    inline Umount classifier, the inline BtrfsDeviceScanForget
    classifier at line 3521, and the inline CryptsetupClose
    classifier at line 3555 (none of these delegate to a helper).
    All three use the Pattern B (.map_err -> RecoverError::Failed)
    shape, so their runner-error kind is "Failed" (see D10).
    Plus the mixed-fatal BtrfsReplaceStatus site in
    wait_for_kernel_replace_to_finish at line 3369-3391 -- runner-
    error branch is best-effort warn-and-proceed (not audited);
    parser branch (including ParseError::CommandFailed) is fatal
    RecoverError::Failed (audited, kind "Failed"). See D10
    table. Also the mixed-fatal MountpointCheck state-check at
    recover.rs:2082 in discover_add_targets_before_mount
    (runner-error branch only audited).
  • discover.rs: two parser-mediated classifier sites in the per-
    by-id-symlink loop -- CryptsetupIsLuks at line 340-342 and
    CryptsetupLuksDumpText at line 353-355. Runner-error branch
    only is audited at each (kind "Cmd" from
    DiscoverError::Cmd(#[from] CmdError)); the non-zero-exit /
    parser-CommandFailed / version-unsupported branches are all
    documented warn-and-skip outcomes (not-LUKS, LuksDump quirk,
    LUKS1 disk) and explicitly excluded -- see D10.
  • scrub_cancel.rs::cmd_scrub_cancel,
    scrub_resume_or_start.rs::cmd_scrub_resume_or_start,
    scrub_needs_resume.rs::cmd_scrub_needs_resume,
    ups.rs::query_ups -- each command has its own direct
    classifier(s); add dual-path emit pairs per D10.
  • add.rs::probe_closed_present_luks_target_uuid at line 336
    and replace.rs::probe_existing_luks_new_target_uuid at line
    995 -- mixed-fatal open-boundary CryptsetupLuksUuid re-probes
    that distinguish ParseError::CommandFailed (subprocess
    non-zero -- audit) from Err(other) parse and semantic
    UUID-mismatch arms (do not audit). The runner-error .map_err
    branch is always audited. Audit kind is the variant the site
    constructs: "TargetUuidMismatchAtOpen" for add.rs:336,
    "NewTargetUuidMismatchAtOpen" for replace.rs:995.
  • enroll_key_file.rs::validate_generated_keyfile_target at
    line 552 -- mixed-fatal MountpointCheck state-check at line
    579-581 (runner-error branch audited; non-zero exit is a
    Validation refusal, not a subprocess failure).
  • online_state.rs lifecycle helpers on RealOnlineStateOps
    (unit_active_state line 116, is_mountpoint line 128,
    systemctl_start line 169, systemctl_stop line 185,
    list_bound_by line 204) -- all excluded from
    external_command_failed. Production callers are
    online_state.rs::{snapshot, mark_online, mark_offline} and
    lock.rs::run_lock_pre_steps (the only production caller of
    list_bound_by, which uses a silent let Ok(...) else { return; } early-return on Err). Every error is folded into
    a braid: WARNING: ... stderr line + Ok(()), an
    UnitActiveState::Unknown(...), or an early return; there is
    no fatal path. See D10's dedicated subsection.
  • Parser-mediated classifier sites are per-branch, with the
    exhaustive inventory in D10's per-site policy table. Headline
    rules (table is authoritative):
    • All-fatal sites (both branches audited, dual-path pair
      required): the three probe.rs BtrfsFilesystemShow sites
      (lines 312-315, 397-400, 521-524), probe.rs:204-214
CryptsetupLuksDumpText, probe.rs:334-337 and
      probe.rs:427-430 CryptsetupStatus, probe.rs:460-463
CryptsetupLuksUuid, remove.rs:760 and remove.rs:782,
      the four status.rs sites (lines 578-655), ack.rs:84-86,
      monitor.rs:78-84 (Pattern B with a String error type;
      the kind strings come from the implementation and are
      documented in the test row),
      preflight.rs::probe_missing_devids (BtrfsDeviceUsageRaw
      at ~line 305; Pattern B with String error type),
      scrub_needs_resume.rs::cmd_scrub_needs_resume, plus the two
      luks.rs parser-mediated helper sites
      (luks_uuid_for_device at line 828 and the first
      classify_mapper_ownership CryptsetupStatus at lines
      850-852; both Pattern A with OwnershipError::{Cmd, Parse}).
      (The parse_btrfs_filesystem_show(&show_raw)? calls at
      add.rs:184 and recover.rs:2272 are deliberately not
      in this list; they run only after classify_btrfs_probe
      returned HasBtrfs, so the underlying subprocess has
      exit_status == 0 and any parse failure is output-shape
      corruption, not an external_command_failed event. See D10.)
    • Additional classify_btrfs_probe sites -- mixed-fatal
      by branch: add.rs:168 (classify_braid_disk_fsid) and
      recover.rs:2265 (visible_btrfs_fsid) each audit only
      the runner-error branch and the DeviceBtrfsProbe::Unknown
      arm; NoBtrfs/HasBtrfs branches do not emit (see D10).
    • Mixed-fatal carve-outs (audit only the marked branch, plus a
      nonfatal-branch exclusion test): probe.rs:175-191
CryptsetupLuksUuid site (runner-error fatal; parser branch
      at line 183 returns Ok(PresentNotLuks)); remove.rs:694
check_eviction_space (parser branch fatal; runner-error
      and Err(other) parse branches are warn-and-proceed);
      the two classify_btrfs_probe sites at add.rs:168 and
      recover.rs:2265 (runner-error + Unknown audited;
      NoBtrfs/HasBtrfs not audited);
      luks.rs:894-896 classify_mapper_ownership second
      CryptsetupLuksUuid site (runner-error + generic-Parse
      branches audited; "backing not LUKS" Conflict arm at line
      899-905 is a semantic outcome, not audited); discover.rs:340
CryptsetupIsLuks and discover.rs:353 CryptsetupLuksDumpText
      (runner-error branch only audited; non-zero-exit and parser
      branches are warn-and-skip); recover.rs:3369-3391
wait_for_kernel_replace_to_finish BtrfsReplaceStatus
      (parser branch only audited; runner-error branch is best-
      effort warn-and-proceed); the four MountpointCheck state-
      check sites at mount.rs:216, lock.rs:680,
      recover.rs:2082, enroll_key_file.rs:579 (runner-error
      branch only audited; non-zero exit is a documented state);
      and the two open-boundary CryptsetupLuksUuid re-probes at
      add.rs:336 and replace.rs:995 (runner-error and
      ParseError::CommandFailed parser branches audited;
      semantic UUID-mismatch Ok(parsed) and Err(other) parse
      branches not audited).
    • Do not add an emit in monitor.rs::cmd_monitor's
      ProbeError::Parse arm: the static CmdRequest variant is
      already lost there. The upstream probe.rs:312-315 (and the
      two sibling probe sites) own the emit instead -- D10
      "emit at the call site that still has the static
      CmdRequest in scope" rule.
    • Do not add an emit at recover.rs:1010's bootstrap
      detection match runner.run(...) { Ok(raw) => matches!(..., NoBtrfs), Err(_) => false }: runner errors are explicitly
      mapped to false (best-effort detection), not propagated as
      fatal. See D10's excluded full sites.
      Each audited branch gets a single emit with BRAID_EXTCMD_NAME
      from the static CmdRequest variant the parser was reading
      (see D10). Branch-specific coverage replaces the "always a
      pair" rule at the mixed-fatal sites.

  Apply the D10 exclusion list to skip expected-non-zero probes
  (cryptsetup status, probe.rs state checks, presence-detection
  calls, test/mock sites). The per-CmdRequest-classifier-site
  checklist -- one dual-path test pair per site at non-mixed
  audited sites, and per-fatal-branch tests at the mixed sites
  enumerated above -- is produced during implementation step 5
  (D10 enforcement paragraph); do not regress to "per function"
  coverage, and do not regress to a "union of all nonzero matches"
  rule.

• Refusal sites (one audit::refused(reason) call per site,
  driven by the D3 reason-code set). The inventory below maps the
  D3 reason codes to current-tree sites; every documented reason
  code has at least one site, and every site has a matching unit
  assertion in the per-site test list.

  • pool_not_mounted:
    • cli/src/ack.rs:126 (offline ack)
    • cli/src/remove.rs:499
    • cli/src/remove_missing.rs:377
    • cli/src/replace.rs:1208, cli/src/replace.rs:1214
      (plan_replace -- both the ProbeError::NotBtrfs arm and the
      !pool.mounted arm; both surface as
      ReplaceError::Validation("pool is not mounted. Cannot replace."))
  • offline_btrfs_errors: cli/src/ack.rs:138
  • live_pool_changed: cli/src/replace.rs:947-977
    (verify_replace_execute_live_pool_uuid) -- the Validation
    branches for "pool unmounted between planning and execution"
    and "pool fsid changed between planning and execution"
  • duplicate_uuid:
    • cli/src/replace.rs:947-977 (the DuplicateUuid branch in
      verify_replace_execute_live_pool_uuid, execute-time)
    • cli/src/replace.rs:1440 (assert_new_uuid_unique,
      plan-time)
    • cli/src/add.rs:1949 (assert_target_uuid_unique)
  • target_uuid_mismatch: cli/src/add.rs:1050
    (the TargetUuidMismatchAtOpen construction site)
  • managed_format_flag:
    • cli/src/add.rs:1510-1512
      (AddError::ManagedFormatFlag from
      LuksFormatExtraOpts::parse)
    • cli/src/replace.rs:1179
      (ReplaceError::ManagedFormatFlag from the same parser)
  • pending_operation_present, pending_operation_unreadable:
    covered above under cli/src/preflight.rs:44
    (check_no_pending_operation).

• modules/braid/storage.nix, monitor.nix, ups.nix,
  fan-control.nix -- add SyslogIdentifier = "braid" to every
  braid-* unit's serviceConfig, per D7's verified inventory
  (braid-unlock, braid-online, braid-scrub,
  braid-scrub-resume-trigger, braid-auto-unlock, braid-monitor,
  braid-alert, braid-ups-secrets, braid-fan-reload).

Reused, not rewritten:

• state_io::atomic_write (cli/src/state_io.rs:53) -- callers do the
  emission; the primitive stays semantics-free.
• uuid::Uuid::now_v7 -- already in deps.
• time crate -- already in deps; used for duration measurement.
• Existing test preamble convention from docs/testing.md.
• Existing journalctl test pattern from
  tests/module/auto-unlock-key-wrong.py:29.

Implementation steps

1. Add libsystemd to cli/Cargo.toml under
   [target.'cfg(target_os = "linux")'.dependencies]. Run
   just test-rust (cargo test on macOS host) and a Linux build
   via the VM-test plumbing to confirm both targets resolve.
2. Create cli/src/audit.rs with: AuditSink trait,
   #[cfg(target_os = "linux")] JournaldSink (libsystemd-backed),
   unconditional InMemorySink + NoopSink, ProcessState struct
   containing run_id, command_name, started_at,
   run_refused: AtomicBool, audit_dropped: AtomicU64,
   PROCESS_STATE: OnceLock<ProcessState>, init_process_state(...),
   TestAuditContext (same fields as ProcessState, plus an owned
   Box<dyn AuditSink>), a TEST_CONTEXT thread-local cell,
   test_with_context(closure) RAII guard, emit(AuditEvent)
   (checks thread-local first, falls back to PROCESS_STATE),
   refused(reason: &'static str) (takes only a &'static str --
   no String, no Display -- per D3; also flips run_refused on
   the active context), ExtcmdStatus { Exit(i32), RunnerError },
   report_external_command_failed(name: &'static str, status: ExtcmdStatus, kind: &'static str) (per D10's dual emit
   pattern), MESSAGE_ID table. Default-sink installer picks
   JournaldSink on Linux, NoopSink elsewhere.
3. Wire audit::init_process_state into main() right after CLI parse,
   right before the root gate (so refusals at the root gate get a
   command_refused). Emit command_started at the top of each
   command match arm. Then route every post-parse process-
   terminating call through audit::audited_exit(outcome, code)
   (D11) -- this is the only legal post-parse exit path. Concrete
   sites to convert (all in cli/src/main.rs):
   • Root gate (around line 337) -> ExitOutcome::Refused { reason: "root_required" }, exit code 1.
   • load_config_or_exit (definition at line 957, callers at
     lines 411, 578, 641, 754, 772, 865, 995, 1056) -> the helper
     itself takes an explicit exit code; route its exit(code)
     through audited_exit(ExitOutcome::Failed, code).
   • All std::process::exit(N) sites inside match arms (the
     ~40 enumerated in the grep) -> audited_exit(<outcome>, N)
     with outcome chosen by semantic meaning of the exit:
     Finished for the 0 paths, Failed for the non-zero paths,
     unless a specific D3 reason code applies (currently only the
     root gate qualifies).
   • print_help_for (main.rs:330) and its Err(e) => e.exit()
     at line 341. This is clap::Error::exit() -- it calls
     std::process::exit internally with clap's chosen code, so
     the std::process::exit grep would not catch it. Replace
     with: print the error via clap's public API
     (clap::Error::print for the rendered message), read its
     .exit_code(), then call
     audit::audited_exit(ExitOutcome::Failed, code).
     After the patch, both of D11's grep gates must pass:

   grep -n 'std::process::exit' cli/src/main.rs           # zero hits except pre-parse
   grep -n 'clap::Error::exit\|\.exit()' cli/src/main.rs  # zero hits in post-parse code paths
   

4. Add emits at each state I/O site listed in "Critical files"
   (one PR step per file is fine; each is mechanical). For
   pool_json_classified specifically: emit only at the
   cmd_discover call site that already invokes classify_pool_json.
5. At every audited CmdRequest classifier site in D10's
   inventory (not per function -- per individual runner.run/
   run_with_stdin site), add both audit emits (D10's dual emit
   pattern). On the runner-error path, the kind argument is the
   literal Rust variant name the call site constructs on that path
   (D10 general rule): for Pattern A (? with #[from] CmdError)
   that is whichever variant carries the #[from] -- usually
   "Cmd" (pool/luks/mount), but "InvocationFailed" for
   UpsQueryError, and whatever the typed error literally uses
   elsewhere. For Pattern B (.map_err(|e| TypedError::Variant( format!(...)))?, e.g. the three recover.rs::relock_and_remount
   sites) it is the variant named in the .map_err constructor
   (e.g. "Failed"). No cmd_* signature changes; the call-site
   pattern is mechanical.
6. Add explicit audit::refused calls at the refusal sites listed.
7. Add SyslogIdentifier = "braid" to existing braid-* units.
8. Write two VM tests (see Tests section).
9. Write docs/audit-logging.md and docs/decisions/026-audit-logging.md,
   update docs/index.md.
10. Update README.md with a one-paragraph "Looking at audit logs"
    section pointing to the new doc.

Each step is independently revertible. Steps 4, 5, and 6 can be split
into per-file commits if review prefers smaller chunks.

Tests

Rust unit tests (in cli/src/audit.rs and per-module)

All tests run inside audit::test_with_context(|ctx| { ... }) (D2),
which installs a fresh thread-local audit context (sink, run_id,
run_refused, audit_dropped) for the closure and tears it down on exit.
This means parallel cargo test runs do not share refusal/drop
state, and the mutual-exclusion test below is order-independent.

• audit::emit against InMemorySink (via the test context) --
  emitting an event records it; emitting with no context installed is
  a no-op.

• audit::refused -- records a command_refused event with the given
  reason code and flips run_refused on the active context. Verify
  there is no detail/message parameter (compile-time prevention of
  the by-id-leak class of bug; D3).

• Refusal carries no operator-supplied paths (D3/D5 privacy) --
  build an AddError::DuplicateUuid whose Display text contains a
  /dev/disk/by-id/... string, drive the refusal site that handles
  that error, and assert the recorded InMemorySink.events()
  contains a command_refused whose every field (event payload and
  MESSAGE) is free of /dev/disk/by-id. Same assertion for
  TargetUuidMismatchAtOpen. This pins the privacy property at the
  type-system layer (since audit::refused takes no String) and
  at the test layer (in case someone later adds a free-form field).

• Refused-vs-failed mutual exclusion -- a synthetic test that
  drives the main-loop wrapper helper with an Err(_) outcome
  preceded by audit::refused(...); asserts the recorded sink contains
  exactly one command_refused and zero command_failed for that run.
  Also assert the inverse: an Err(_) with no prior audit::refused
  records exactly one command_failed. This is the regression check
  for the double-logging trap, and is the test that needed thread-
  local isolation in D2.

• Audit-dropped counter under transient sink failure (D4) --
  install a FailNTimesThenSucceedSink (fails the first N emits with
  an Err(_), then behaves as InMemorySink). Emit N+2 events;
  assert: (a) the test context's audit_dropped counter equals N,
  (b) the final recorded event still made it into the sink, and
  (c) the final event's BRAID_AUDIT_DROPPED field carries N. This
  is the only place the dropped counter is asserted -- the
  journald-down VM check (verification 5) covers command outcome
  only, per the D4 observability caveat.

• audited_exit coverage and exit-code preservation (D11) --
  drive audit::audited_exit (extracted from noreturn for the
  test via a thin wrapper that returns the chosen exit code instead
  of calling std::process::exit, so tests can observe it) with
  each of the dimensions the wrapper must cover. One test per row:

  • Finished, 0 -> exactly one command_finished, recorded code 0.
  • Failed, 1 with no prior audit::refused -> exactly one
    command_failed, recorded code 1.
  • Failed, 1 with a prior audit::refused("pool_not_mounted") ->
    exactly one command_refused, zero command_failed, recorded
    code 1 (the suppression rule from D3 holds across the wrapper).
  • Refused { reason: "root_required" }, 1 -> exactly one
    command_refused with BRAID_REFUSE_REASON=root_required,
    zero command_failed, recorded code 1.
  • Representative special exit codes flow through unchanged:
    Finished, 0 (lock AlreadyHeld), Failed, 2 (lock generic
    conflict), Failed, 3 (lock unmount stuck), Failed, 2
    (idle/monitor/scrub status). Assert the recorded code matches
    the argument verbatim in every case. This pins D11's "this is
    a wrapping refactor, not a semantics change" invariant.
  • braid help <bad-subcommand> (clap-exit replacement) --
    drive the print_help_for failure path that currently hits
    clap::Error::exit() at main.rs:341. Assert: exactly one
    command_failed is recorded (no leaked second termination
    without an audit event); the recorded exit code equals the
    code clap would have chosen for InvalidSubcommand (currently
    2, but the test asserts whatever clap returns -- the invariant
    is "code preserved verbatim from clap"); the stderr output
    still contains clap's usage message (so the user-visible CLI
    behaviour is unchanged). This is the regression check for the
    clap::Error::exit() ban in D11.

• Subprocess-failure coverage (per classifier site, dual path
  where both branches are fatal). One pair of tests per
  audited CmdRequest classifier site whose runner-error AND
  non-zero-exit branches are both fatal -- not per function or
  per module. A function such as pool_add_device (three sites:
  BtrfsDeviceScanForget, WipefsBtrfs, BtrfsDeviceAdd)
  contributes three pairs, not one. At mixed-fatal sites (D10
  parser-mediated table) write only the test(s) for the audited
  branch(es): a runner-error test if and only if the runner-error
  branch is fatal at that site, and a non-zero-exit /
  ParseError::CommandFailed test if and only if that branch is
  fatal. Auditing a nonfatal branch as external_command_failed
  is a bug; tests pin the policy in both directions.

  • Non-zero exit test (write when this branch is fatal):
    MockRunner returns Ok(RawCommandOutput { exit_status: <non-zero>, ... }) for the target CmdRequest. Assert
    InMemorySink.events() contains external_command_failed
    with BRAID_EXTCMD_NAME matching the static CmdRequest
    name, BRAID_EXTCMD_STATUS == "exit:<n>", and
    BRAID_EXTCMD_KIND matching the literal typed-error variant
    the classifier constructs on that branch (e.g. "Failed" for
    most pool/luks/mount sites, "QueryFailed" for ups.rs,
    "Validation" for remove.rs parser-mediated sites).
  • Runner-error test (write when this branch is fatal):
    MockRunner returns Err(CmdError::Failed(_)) for the target
    CmdRequest. Assert InMemorySink.events() contains
    external_command_failed with BRAID_EXTCMD_STATUS == "runner_error" and BRAID_EXTCMD_KIND matching the literal
    Rust variant the site constructs on the runner-error path
    (D10 general rule): for Pattern A (? with #[from] CmdError), that is whichever variant carries the #[from] --
    "Cmd" for pool.rs/luks.rs/mount.rs, but
    "InvocationFailed" for ups.rs::query_ups
    (UpsQueryError::InvocationFailed(#[from] CmdError)), and
    whatever the typed error literally uses elsewhere. For
    Pattern B (.map_err(|e| TypedError::Variant(format!(...)))?),
    that is the variant named in the .map_err constructor (e.g.
    "Failed"). Also assert the recorded payload contains none
    of the CmdError::Failed(_) detail string -- the raw
    argv/stderr it carries must not leak (D5).
  • Nonfatal-branch exclusion tests (write at each mixed-fatal
    site): drive the site's nonfatal branch with the appropriate
    mock (Err(CmdError::Failed) for nonfatal runner-error
    branches like remove.rs:694's Err(e) -> ProceedWithWarning,
    Ok(RawCommandOutput { exit_status: 1 }) paired with a stale-
    parser stub for nonfatal ParseError::CommandFailed branches
    like probe.rs:183's Ok(PresentNotLuks)) and assert
    InMemorySink.events() contains no external_command_failed
    record for that BRAID_EXTCMD_NAME. Prevents a future cleanup
    from accidentally promoting these nonfatal branches into audit
    events.

  The full per-site inventory under test spans pool.rs,
  luks.rs (direct exit-status classifiers, plus the two parser-
  mediated helpers luks_uuid_for_device at line 828 and
  classify_mapper_ownership at line 838 -- the latter has three
  classifier sites: CryptsetupStatus 850-852 all-fatal,
  CryptsetupLuksUuid 894-896 mixed-fatal with the line 899-905
  Conflict { found: None } arm excluded as a semantic outcome),
  mapper_close.rs, mount.rs (including the mixed-fatal
  MountpointCheck state-check at line 216, runner-error branch
  only), lock.rs (including the mixed-fatal MountpointCheck at
  line 680 in plan_lock_inner, runner-error branch only),
  recover.rs (including all three direct sites in
  relock_and_remount -- Umount, BtrfsDeviceScanForget,
  CryptsetupClose -- plus scan_mapper plus the mixed-fatal
  BtrfsReplaceStatus site at 3369-3391 in
  wait_for_kernel_replace_to_finish, parser branch only, plus
  the mixed-fatal MountpointCheck at 2082 in
  discover_add_targets_before_mount, runner-error branch only),
  enroll_key_file.rs (mixed-fatal MountpointCheck at line
  579-581 in validate_generated_keyfile_target, runner-error
  branch only), add.rs::probe_closed_present_luks_target_uuid
  at line 336 (mixed-fatal open-boundary re-probe, runner-error +
  ParseError::CommandFailed audited), replace.rs:: probe_existing_luks_new_target_uuid at line 995 (same shape),
  scrub_cancel.rs, scrub_resume_or_start.rs,
  scrub_needs_resume.rs (both branches fatal -- see D10 table),
  ups.rs, the parser-mediated classifier sites in probe.rs
  (all eight rows: CryptsetupLuksUuid at 175-191 mixed-fatal,
  CryptsetupLuksDumpText at 204-214, BtrfsFilesystemShow at
  312-315 / 397-400 / 521-524, CryptsetupStatus at 334-337 /
  427-430, CryptsetupLuksUuid at 460-463), remove.rs (694
  mixed-fatal, 760, 782), status.rs (four sites), ack.rs:84-86,
  monitor.rs:78-84, preflight.rs::probe_missing_devids,
  discover.rs (mixed-fatal CryptsetupIsLuks at 340-342 and
  CryptsetupLuksDumpText at 353-355, runner-error branch only),
  and the classify_btrfs_probe sites at add.rs:168 and
  recover.rs:2265 (mixed-fatal per D10). The
  parse_btrfs_filesystem_show(&show_raw)? calls at add.rs:184
  and recover.rs:2272 are deliberately not test rows --
  they run only after HasBtrfs (subprocess exit 0), so any
  parse failure is output-shape corruption, not an
  external_command_failed event (D10). The downstream
  monitor.rs::cmd_monitor ProbeError::Parse handler and the
  recover.rs:1010 bootstrap-detection match are also not
  test rows -- their coverage comes from upstream emits (per D10).

  Anti-drift rule, adjusted for the mixed-fatal policy:

  • At all-fatal sites (both runner-error and non-zero-exit
    branches are fatal -- the common case, and scrub_needs_resume.rs):
    a dual-path test pair is required; a missing runner-error row
    counts as missing coverage.
  • At mixed-fatal sites (the per-site rows in D10's table
    where one branch is nonfatal -- e.g. probe.rs:178/183,
    remove.rs:694, discover.rs:340, discover.rs:353,
    recover.rs:3369, the luks.rs:894-896 second
    CryptsetupLuksUuid site, the four MountpointCheck
    state-check sites at mount.rs:216 / lock.rs:680 /
    recover.rs:2082 / enroll_key_file.rs:579, and the two
    open-boundary CryptsetupLuksUuid re-probes at add.rs:336
    / replace.rs:995): write tests only for the branches D10
    marks as audited, plus the nonfatal-branch exclusion test
    (above) for each nonfatal branch; do not force a pair
    where one half would have to assert a false event.
  • The test count must match the D10 inclusion list exactly: no
    audited site in D10 lacking the tests it requires under the rule
    above; no test pointing at a site D10 does not list.

  Concrete nonfatal-branch exclusion tests required by this round's
  additions:

  • discover.rs:340-345 CryptsetupIsLuks non-zero exit: drive
    the runner with Ok(RawCommandOutput { exit_status: 1 }) for a
    by-id symlink and run the discover scanner; assert no
    external_command_failed is emitted for CryptsetupIsLuks
    (the scanner should simply skip that disk).
  • discover.rs:353-376 CryptsetupLuksDumpText parser-warning
    branches: drive with Ok(RawCommandOutput { exit_status: 1, stderr: "..." }) (forces ParseError::CommandFailed) and with
    malformed stdout for the unparseable arm; assert no
    external_command_failed is emitted for CryptsetupLuksDumpText.
  • discover.rs:377-383 UnsupportedLuksVersion: drive with a
    LUKS1-shaped dump output; assert no external_command_failed
    is emitted.
  • recover.rs:3369-3381 wait_for_kernel_replace_to_finish
    runner-error: drive with Err(CmdError::Failed(_)) for
    BtrfsReplaceStatus; assert the function returns Ok(())
    (warn-and-proceed) AND no external_command_failed is emitted
    for BtrfsReplaceStatus.
  • luks.rs:899-905 "backing not LUKS" Conflict { found: None }
    arm: drive classify_mapper_ownership so the second
    CryptsetupLuksUuid (line 894-896) returns a RawCommandOutput
    that satisfies cryptsetup_luks_uuid_reports_not_luks; assert
    the call returns Err(OwnershipError::Conflict { ... }) AND no
    external_command_failed is emitted for that second
    CryptsetupLuksUuid invocation.
  • MountpointCheck non-zero-exit (state) branches at
    mount.rs:216, lock.rs:680, recover.rs:2082,
    enroll_key_file.rs:579: drive the runner so
    MountpointCheck returns Ok(RawCommandOutput { exit_status: 1 }) at each site; assert no external_command_failed is
    emitted for MountpointCheck in that call. (At
    enroll_key_file.rs:579 the function returns
    Err(EnrollKeyFileError::Validation(...)) -- the test asserts
    the error variant and the absence of the audit event; at
    the other three sites the function returns
    Ok(None) / Ok(snapshot) per source.)
  • add.rs:336 and replace.rs:995 semantic-mismatch and
    Err(other) parse branches: drive the runner with
    Ok(RawCommandOutput { exit_status: 0, stdout: <UUID-shaped stdout for a *different* UUID> }) so the parser succeeds and
    the caller takes the Ok(parsed) => Err(TargetUuidMismatchAtOpen / NewTargetUuidMismatchAtOpen { ... }) arm; assert no
    external_command_failed is emitted for CryptsetupLuksUuid.
    Repeat with Ok(RawCommandOutput { exit_status: 0, stdout: "<malformed>" }) to drive Err(other) parse; assert the
    error is constructed AND no external_command_failed is
    emitted. Both arms protect against future cleanups that might
    fold these into the audit funnel.
  • online_state.rs lifecycle exclusion tests (one per
    classifier site): each test drives RealOnlineStateOps
    through both failure modes -- the runner-error branch
    (Err(CmdError::Failed) from the runner) and the non-zero
    exit branch (Ok(RawCommandOutput { exit_status: <nonzero> }))
    -- and asserts the negative property: no
    external_command_failed is emitted, and the production
    caller's documented public behavior holds. Concrete rows:
    1. is_mountpoint runner-error / non-zero (cases > 1) via
       mark_online -> eprintln!("braid: WARNING: failed to check mountpoint ...") + Ok(()).
    2. systemctl_start runner-error / non-zero via
       mark_online on a UnitActiveState::Inactive snapshot ->
       eprintln!("braid: WARNING: failed to activate ...") +
       Ok(()).
    3. systemctl_stop runner-error / non-zero -- two production
       call sites, both tested: (a) via mark_offline ->
       eprintln!("braid: WARNING: failed to deactivate ...") +
       Ok(()); (b) via lock.rs::run_lock_pre_steps (the
       line 1018-1031 match e { OnlineError::SystemctlStop { exit_code, .. } => eprintln!("braid: WARNING: failed to stop ..."), other => eprintln!(...) } branches; the
       let _ = online_ops.systemctl_stop(...) at line 1005 is
       silently swallowed). Assert in both cases that
       run_lock_pre_steps returns and the lock command
       continues.
    4. unit_active_state runner-error / non-zero via
       snapshot -> UnitActiveState::Unknown(<err.to_string()>).
    5. list_bound_by runner-error / non-zero via
       lock.rs::run_lock_pre_steps (the only production
       caller). Assert: run_lock_pre_steps early-returns via
       the let Ok(bound_by) = ... else { return; }; at line
       1008-1010 (no eprintln!, no propagation, no fold to an
       empty list -- the rest of the per-bound-by loop is simply
       skipped). Assert no external_command_failed is emitted
       for SystemctlShowBoundBy. This is the row whose public
       behavior earlier drafts of this plan described as
       "warn-and-fold-to-empty"; the actual behavior is silent
       early-return.
       Each row covers both error shapes so neither the runner-error
       fold (OnlineError::Spawn) nor the non-zero fold
       (OnlineError::Mountpoint/SystemctlStart/SystemctlStop/
       SystemctlShow) can leak into the audit funnel via a future
       refactor.

• Expected-nonzero exclusion -- one test per excluded site listed
  in D10 (cryptsetup status for a non-existent mapper, a
  pool-state probe in probe.rs for a not-mounted pool, a
  btrfs filesystem show presence-detection call) confirming that
  these do not emit external_command_failed. Prevents a future
  cleanup from accidentally promoting expected non-zero into an
  audit event. (The five online_state.rs lifecycle helper sites
  have their own dedicated exclusion rows above -- they are
  covered there rather than here, because the rule applies to both
  runner-error and non-zero branches, not just non-zero.)

• Per refusal site test -- one per D3 reason code, walking the
  inventory in "Files to modify". Concretely:

  • pool_not_mounted: tests for ack, remove, remove_missing,
    and the two plan_replace arms (NotBtrfs and !pool.mounted).
  • offline_btrfs_errors: ack.
  • live_pool_changed: replace execute-time recheck.
  • duplicate_uuid: replace plan-time (assert_new_uuid_unique),
    replace execute-time, and add (assert_target_uuid_unique).
  • target_uuid_mismatch: add open-time mismatch.
  • managed_format_flag: add and replace parser-time refusal.
  • pending_operation_present and pending_operation_unreadable:
    preflight::check_no_pending_operation.
    Each existing unit test for the error path gains a single
    assertion that InMemorySink.events() contains a command_refused
    with the right reason code. Behavioral, not structure-sensitive:
    tests assert event names and reason codes, not field ordering or
    byte format. The test count must match the refusal-site inventory
    exactly (every D3 reason code has at least one test row; every
    inventory site has a test row).

NixOS VM tests

Two new VM tests under tests/cli/. Both set
services.journald.extraConfig = "Storage=persistent" and assert on
journalctl ... --output=json filtered by BRAID_AUDIT=1.

Test #1: audit-discover-corrupt-pool-json

• Intent: Verify that running braid discover --write against a
  corrupt /var/lib/braid/pool.json emits the expected audit chain --
  shape classification followed by sidecar preservation.
• Why it exists: Sidecar preservation and shape classification are the
  primary diagnostic signals the audit log adds. A regression here
  silently kills the diagnostic value. The test uses discover, not
  status, because the corrupt sidecar is only written from the
  discover --write path (cli/src/discover.rs:637); braid status
  intentionally tolerates a corrupt pool.json when unmounted (covered
  by the existing cmd_status_unmounted_corrupt_membership_returns_ok
  test in status.rs), and turning status into a write path would
  violate the read-only contract.
• Scenario: With pool online, write garbage into pool.json. Run
  braid discover --write (which has its own preconditions met by
  the live mounted pool). Assert journalctl shows
  pool_json_classified with BRAID_POOL_JSON_SHAPE=Corrupt,
  followed by sidecar_written, followed by pool_json_written (the
  rebuilt membership), all sharing the same BRAID_RUN_ID, ending in
  command_finished.

Test #2: audit-ack-refused

• Intent: Verify that refused commands produce a command_refused
  event with a stable reason code, and that command_failed is not
  also emitted for the same run.
• Why it exists: Reason codes are the primary filter operators use to
  spot pattern-of-failure. They must be present and stable. The
  refused-not-failed assertion guards the mutual-exclusion invariant
  end-to-end (the unit test above guards the same invariant in
  isolation; this test pins the wire shape).
• Scenario: With pool unmounted, run braid ack. Assert journalctl
  shows command_refused with BRAID_REFUSE_REASON=pool_not_mounted,
  zero command_failed records for the same BRAID_RUN_ID, and no
  pool_json_written or pending_op_written events for that run.

Both tests follow the AGENTS.md preamble form (Intent / Why it exists / Scenario) and are registered in flake.nix under
checks.<system> per docs/testing.md.

Parser / fixture tests

Out of scope. Audit logging does not parse any new tool output, so no
parser-compatibility fixtures change.

Verification (end-to-end)

After implementation, the following should hold on a fresh VM build:

1. just test-rust passes including all new audit-related unit tests.
2. just test-vm audit-discover-corrupt-pool-json audit-ack-refused passes.
3. just test-vm (full suite) passes -- no regression in any existing
   test, including tests that already assert journalctl output for
   existing braid units.
4. On a live VM, after braid status + braid ack + a recovery cycle:
   journalctl BRAID_AUDIT=1 --output=json-pretty returns one record
   per documented event for each invocation; every record has
   BRAID_RUN_ID, BRAID_COMMAND, BRAID_EVENT, SYSLOG_IDENTIFIER=braid.
5. Simulating journald-down (mask the journal socket) and running
   braid status: command still exits 0 and produces normal
   stdout/stderr. Audit records are not asserted because under
   permanent journald-down nothing reaches the journal (see D4
   observability caveat). Drop-counter behaviour under transient
   journald failure is covered by a unit test against a fail-then-
   succeed sink (see Tests).
6. journalctl BRAID_RUN_ID=<uuid> returns the full end-to-end story
   of one invocation in chronological order.

Rejected alternatives

• JSONL file under /var/lib/braid/audit.log -- adds a new state
  lifecycle (rotation, fsync, corruption handling, permissions, cleanup
  on uninstall) that braid would own and have to test. journald solves
  all of those. Rejected.
• SQLite database for audit events -- gives queryability but at the
  cost of a new on-disk format with its own corruption modes, plus a
  large dependency. Out of proportion for v1 diagnostic needs. Rejected.
• Audit log as a source of truth / replay log -- replacing
  pending-op.json with an event log would change braid's recovery
  model and add operational risk. The diagnostic-only invariant exists
  precisely to keep this off the table. Rejected.
• tracing + tracing-journald -- a heavier framework than a fixed
  ~15-event taxonomy needs. Rejected.
• C-binding systemd crate -- works fine but links a system C
  library version, complicating Crane caching and cross-builds.
  Keep as a documented fallback only if pure-Rust libsystemd proves
  unworkable during implementation.
• Threading a RuntimeContext { run_id, ... } through every cmd_*
  function -- touches a large surface area for a side-channel concern,
  invites accidental coupling between audit state and command
  correctness. Rejected in favor of the OnceLock + side-channel module.
• Classifying refusal vs failure by parsing the error Display --
  fragile, couples audit reason codes to free-form error strings.
  Rejected in favor of explicit audit::refused(reason) calls at
  each site (one &'static str arg; see D3).
• NixOS module option services.braid.audit.enable -- audit is
  low-volume and diagnostic; gating it behind an option creates a
  configuration matrix where "operator forgot to enable" leaves them
  without diagnostics exactly when they need them. Rejected; always on.

Open follow-ups (out of v1 scope)

• v2: surface BRAID_AUDIT_DROPPED count in braid doctor.
• v2: add enroll/unlock/lock specific events if operator
  experience shows them missing.
• v2: an optional braid audit tail/braid audit list UX that wraps
  journalctl BRAID_AUDIT=1 .... Pure UX sugar; not a new data path.