declarative `braid.mounts` pool-path mounts

[danneu]

When using btrfs or data storage in general, you generally have an administrative source-of-truth mount like /mnt/storage/ that some admin user can access.

But then you want to be able to mount additional paths in the OS file system that provide views into the data.

For example, maybe you want ~/movies to view into /mtn/storage/movies, but only your jellyfin/plex user can access ~/movies (and not /mtn/storage/movies), nor can the jellyfin/plex user access anything else in the data pool. Additionally, you might want to mount ~/movies as read-only and with other options that limit the scope if access.

One idea is for braid to let you configure these mounts declaratively in its nix config.

[danneu]

(plan)

braid.mounts -- declarative pool-path mounts

Context

braid exposes the whole pool at /mnt/storage, owned root:storage 2770. The
real-world need is to expose one path from inside the pool (a subvolume or a
plain folder) at a controlled location for a specific service or user -- e.g.
a media server reading /srv/braid/movies read-only while storage-group
members keep managing the files.

Today this is a manual recipe (docs/guides/mounting-subvolumes.md): hand-write
a systemd.mounts unit with subvol=<name> pointed at /dev/disk/by-uuid/<btrfs-fsid>,
hand-wire the triad to braid-online.service, and manually braid seal-mountpoint
the target. Three problems: it requires looking up the btrfs FSID (runtime state,
per Principle 2), it only works for subvolumes (not folders), and the offline
target seal is a manual, non-self-healing step.

The fix is a first-class braid.mounts option. The pivotal realization: a bind
mount takes a path (what = ${mountPoint}/<source>), not a device, so it needs
no FSID and can be a static build-time systemd unit. That makes the whole
thing declarative, source-agnostic (folder or subvolume), and auto-sealable.

Intended outcome: braid.mounts."/srv/braid/movies" = { source = "movies"; readOnly = true; }
generates a hardened, lifecycle-bound, auto-sealed bind mount, with the option
to lifecycle-bind dependent services. Read access to the bytes stays a documented
manual setfacl step (it is inode/content state, not a mount property).

This plan also writes the ADR that locks the design boundaries and refactors the
guide so the general mechanism is taught cleanly with Jellyfin demoted to a
bounded illustration.

Design (locked decisions -- formalized in ADR 032)

1. Bind mechanism, source-agnostic, path-based. Generate a bind mount
   (what = "${mountPoint}/${source}", options = "bind,..."), never subvol=.
   No FSID lookup; works for folders and subvolumes alike.
2. Static systemd units, not CLI-owned. The bind path is build-time-known,
   so units are generated declaratively. The CLI needs zero changes to
   function: lock.rs#run_lock_pre_steps already stops every
   BoundBy braid-online.service unit generically, and seal-mountpoint
   already has an explicit-path form. Contrast ADR 017 (pool membership is
   CLI-owned because it is mutable runtime state -- "which drives are in the
   pool right now" -- a category error to bake into declarative config; a bind
   path is build-time-known, neither mutable nor runtime-derived, so it stays
   declarative. The needs-a-live-FSID angle is Principle 2's; ADR 017's own
   stated rationale is the runtime-state-vs-declarative split).
3. Per-mount knobs = a braid-curated subset of the bind-settable flags, as
   typed booleans -- no freeform passthrough. Expose ro, noexec,
   nosuid, nodev, noatime, each a typed bool. These are a deliberate
   subset of the kernel's per-bind-settable set: at util-linux v2.42
   MNT_BIND_SETTABLE is MS_NOSUID|MS_NODEV|MS_NOEXEC|MS_NOATIME|MS_NODIRATIME|MS_RELATIME|MS_RDONLY|MS_NOSYMFOLLOW
   (libmount/src/mountP.h), i.e. it also includes nodiratime, relatime,
   nosymfollow. braid exposes only the hardening-relevant flags and provides
   no freeform extraOptions escape hatch, so a mount's option surface is
   always validated and the fail-safe defaults can never be silently reversed
   (a stray rw/exec/dev in a passthrough would reopen the hole the
   defaults close). Adding another bind-settable flag later means adding
   another typed knob, never a passthrough. Owner/group/mode/ACL are
   inode-level (shared by every bind of the same source), not per-mount, so
   they are not options.
4. Content access is not a mount property. Granting a service read access
   to the bytes is an inode ACL concern (setfacl u:svc:rX), deliberately out
   of braid.mounts: it is pool content (runtime state behind the lock, like
   the files themselves) and declaratively reconciling it has the same hazard
   class as the already-rejected braid.subvolumes. Documented as a manual
   step. (braid is uniquely positioned to apply grants at pool-online via
   mark_online; recorded in the ADR as a possible future, not built.)

Plus: triad lifecycle binding to braid-online.service, auto-seal of each
target (extends ADR 028 -- the manual recipe could not do this), and optional
dependent-service lifecycle edges.

Implementation

1. NixOS module -- new modules/braid/mounts.nix

Co-locate the option and the generation in one file (the ups.nix shape).
Module args must include utils (for utils.escapeSystemdPath).

Option schema (options.braid.mounts, attrsOf (submodule ...), key = absolute target path):

mounts = lib.mkOption {
  default = { };
  type = lib.types.attrsOf (lib.types.submodule ({ name, ... }: {
    options = {
      source       = lib.mkOption { type = str;        default = baseNameOf name; };  # pool-relative subpath
      readOnly     = lib.mkOption { type = bool;       default = false; };
      noExec       = lib.mkOption { type = bool;       default = true;  };  # fail-safe hardening
      noSuid       = lib.mkOption { type = bool;       default = true;  };
      noDev        = lib.mkOption { type = bool;       default = true;  };
      noAtime      = lib.mkOption { type = bool;       default = true;  };
      seal         = lib.mkOption { type = bool;       default = true;  };  # auto-seal target while offline
      dependentServices = lib.mkOption { type = listOf str; default = [ ]; };  # systemd.services attr names WITHOUT the .service suffix (e.g. "jellyfin"); gated + torn down with this mount; lifecycle only, not file access
    };
  }));
};

Security flags default true (fail-safe: an over-restrictive mount throws a
clear, fixable error; an over-permissive one is a silent hole). readOnly
defaults false. Document the hardening defaults in the descriptions.

dependentServices is a list of NixOS systemd.services attr names -- the unit
base name without the .service suffix (jellyfin, not jellyfin.service),
because braid uses each entry directly as a systemd.services.<name> key and
NixOS appends .service itself. For each name braid adds the full lifecycle
triad re-pointed at the generated .mount -- WantedBy + BindsTo + After
the mount, plus a ConditionPathIsMountPoint gate -- so the service starts
automatically when braid unlock activates the mount, is stopped before
braid lock tears it down, and never starts against an absent mount (this is
the ADR 018 long-running-consumer triad; without WantedBy it would stop on
lock but never restart on unlock). The edges are additive (no mkForce): the
service keeps its own boot/start edges (e.g. multi-user.target) and merely
gains the start-on-mount pull. It grants no
file access: read access to the bytes stays the manual setfacl step
(decision 4). An assertion (below) rejects empty or .service-suffixed names so
the load-bearing edge can never land on a phantom <name>.service.service unit.
Spell this out in the option's description.

Generation (config = lib.mkIf cfg.enable { ... }), three contributions
(sketch -- match existing idioms):

• systemd.mounts (a list; one bind unit per entry). Unit name is derived by
  systemd from where:

  systemd.mounts = lib.mapAttrsToList (target: m: {
    what  = "${cfg.mountPoint}/${m.source}";
    where = target;
    type  = "none";
    options = lib.concatStringsSep "," ([ "bind" ]
      ++ lib.optional m.readOnly "ro"
      ++ lib.optional m.noExec  "noexec"
      ++ lib.optional m.noSuid  "nosuid"
      ++ lib.optional m.noDev   "nodev"
      ++ lib.optional m.noAtime "noatime");
    wantedBy = [ "braid-online.service" ];
    bindsTo  = [ "braid-online.service" ];   # load-bearing: puts it in BoundBy, so braid lock tears it down
    after    = [ "braid-online.service" ];
    unitConfig = {
      # Skips silently while the pool is offline (boot before unlock).
      ConditionPathIsMountPoint = cfg.mountPoint;
      # Fail-closed on a missing/typo'd source. Without this, systemd's mount
      # path mkdir_p_label(p->what, m->directory_mode)'s the bind source (the
      # DirectoryMode default is 0755) and IGNORES the error
      # (mount.c "Failed to make bind mount source ... ignoring"), so a typo
      # silently leaves a stray root:root dir inside the pool and binds an
      # empty mount over it. The Assert blocks the unit (and thus the mkdir).
      AssertPathIsDirectory = "${cfg.mountPoint}/${m.source}";
    };
  }) cfg.mounts;

  bind,ro is applied atomically by util-linux 2.42 libmount (open_tree +
  mount_setattr) under systemd 260 -- verified on the pinned toolchain.

  Condition + Assert compose safely here: systemd's unit_start
  (reference/systemd/src/core/unit.c) tests the condition first and returns
  early when unmet, only reaching the assert when the condition passed. So
  while the pool is offline ConditionPathIsMountPoint=/mnt/storage is false
  and the unit is skipped (debug-level, not a failure) -- the
  AssertPathIsDirectory is never evaluated, so it does not spuriously
  fail every boot even though the source lives inside the unmounted pool. The
  assert fires only in the one case we want loud: pool online but source
  genuinely absent.

• systemd.tmpfiles.settings -- create each bind target before its mount unit.
  Use the structured settings form, never hand-written rules. A target
  may legitimately contain whitespace (the assertions admit any normalized
  absolute path, e.g. /srv/braid/my movies -- and the right answer is to render
  it safely, not to reject valid paths). The settings generator single-quotes
  every field it emits ('${type}' '${path}' '${mode}' ... in
  nixos/modules/system/boot/systemd/tmpfiles.nix), so a whitespace target
  survives intact; a raw rules line "d ${target} 0755 root root -" would be
  whitespace-split by tmpfiles.d into a bogus path+mode and the dir would
  never be created (so the offline seal and the mount both silently break):

  systemd.tmpfiles.settings."10-braid-mounts" =
    lib.mapAttrs (target: m: {
      d = { mode = "0755"; user = "root"; group = "root"; };
    }) cfg.mounts;

  (cfg.mounts is keyed by absolute target, so mapAttrs yields one
  settings."10-braid-mounts".<target>.d entry per mount; the d type with no
  age reproduces the old trailing - field.)

• systemd.services via lib.mkMerge [ sealServices dependentServiceEdges ]:

  • Per-target seal unit (only when m.seal), modeled exactly on
    storage.nix's braid-seal-mountpoint (Type=oneshot, NO RemainAfterExit
    -> self-heals every rebuild + boot), using the explicit-path form
    (fail-closed; a failed seal shows in systemctl --failed, non-blocking
    because wantedBy, not requiredBy):

    "braid-seal-mount-${utils.escapeSystemdPath target}" = {
      wantedBy = [ "multi-user.target" ];
      after    = [ "local-fs.target" "systemd-tmpfiles-setup.service" ];
      before   = [ "braid-auto-unlock.service" ];
      unitConfig.ConditionPathIsMountPoint = "!${target}";
      serviceConfig.Type = "oneshot";
      path   = [ braidWrapped ];
      script = "braid seal-mountpoint ${lib.escapeShellArg target}";
    };

    Mounting over a +i dir works (the pool root itself is sealed and mounted
    over -- ADR 028 precedent), so the seal does not block the bind.

    escapeShellArg is load-bearing: a NixOS service script is wrapped into
    a pkgs.writeShellScriptBin shell script (nixos/lib/systemd-lib.nix
makeJobScript), so a bare ${target} would be word-split and a whitespace
    target would reach braid seal-mountpoint as two argv entries (wrong path,
    seal fails). The script is the only shell context: the .mount unit's
    Where=/What=, the ConditionPathIsMountPoint= value, and the
    escapeSystemdPath-derived unit names are all systemd-native directive values
    (whole-line paths, not shell-split), so they take the raw target/source
    and must not be shell-escaped.

  • Dependent-service edges (per name in m.dependentServices) -- the full
    ADR 018 lifecycle triad re-pointed at the per-target .mount (not
    braid-online.service). Additive: it adds edges without mkForce and never
    removes the service's own boot/start edges.

    ${svc} = {
      wantedBy = [ "${utils.escapeSystemdPath target}.mount" ];  # start on unlock (mount activate)
      bindsTo  = [ "${utils.escapeSystemdPath target}.mount" ];  # stop before lock (mount teardown)
      after    = [ "${utils.escapeSystemdPath target}.mount" ];  # order after the mount is active
      # All three are lists, not scalars: one service may depend on several
      # mounts, so this systemd.services.<svc> attr is defined once per mount and
      # merged. NixOS unitOption merge (nixos/lib/systemd-unit-options.nix)
      # concats list-valued defs -> repeated wantedBy/bindsTo/after lines and
      # AND-ed ConditionPathIsMountPoint= gates; scalar defs go through
      # mergeEqualOption, which THROWS on two different targets. Singleton lists
      # make the multi-mount service merge cleanly.
      unitConfig.ConditionPathIsMountPoint = [ target ];
    };

    WantedBy starts the service when the mount activates on braid unlock;
    BindsTo + After stop it before the mount is torn down on braid lock
    (so it never holds the bind busy at unmount); ConditionPathIsMountPoint is
    defense-in-depth against a direct systemctl start while the mount is absent.
    Omitting WantedBy (the earlier draft) wires only the stop/gate half: at boot
    the service is condition-skipped while offline and, with no start-on-mount
    pull, never auto-starts when unlock later activates the mount. This
    half-working failure is the plan's own inference from the triad ADR 018
    prescribes for long-running pool consumers (WantedBy + BindsTo +
    After, where ADR 018 describes WantedBy as the edge that makes them
    "restart automatically when braid unlock reactivates"); ADR 018's one
    explicit failure callout is BindsTo-without-After, not this omission,
    and the canonical per-field breakdown lives in
    sharing-and-permissions.md#binding-shares-to-the-pool-lifecycle. Binding to the per-target
    .mount rather than braid-online.service keeps the edge granular (a
    service starts only when its mount is live, and an unrelated mount's
    AssertPathIsDirectory failure can't drag it down), and the .mount is
    itself BoundBy braid-online.service, so the whole chain still collapses on
    lock.

Assertions (in the same config). Validate the target by normalized path
components, not string prefixes -- a ./../// in the target defeats a
hasPrefix "${cfg.mountPoint}/" containment test, and a prefix test also misses
the two dangerous directions (root and ancestor). Let
comps = p: lib.splitString "/" (lib.removePrefix "/" p) and
isPrefix = a: b: lib.take (lib.length a) b == a. For each target:

• it is absolute: lib.hasPrefix "/" target;
• it is normalized: every component non-empty and not ./..
  (lib.all (c: c != "" && c != "." && c != "..") (comps target)) -- rejects
  /srv//x, /srv/./x, /a/../b, and a trailing slash;
• with t = comps target and mp = comps cfg.mountPoint, require
  t != [ ] && !(isPrefix t mp) && !(isPrefix mp t). This single
  either-direction prefix test rejects, in one predicate: target == cfg.mountPoint
  (equal); a target under the pool (mp prefixes t -- shadowed, collides
  with the pool seal); a target that is an ancestor of the pool (t prefixes
  mp, e.g. /mnt when the pool is /mnt/storage); and / itself (empty
  t prefixes mp). The ancestor/root case is the hazardous one: once mounted it
  shadows /mnt/storage, and braid lock -- which probes and assembles its
  close-set against the single configured config.mount_point()
  (cli/src/lock.rs#plan_lock) -- can then no longer resolve the live pool mount,
  stranding btrfs mounted or LUKS open.
• each source is a normalized pool-relative subpath -- non-empty, no
  leading /, and no "", ., or .. path component. "Relative and
  non-empty" is not enough: source = "../other" is both yet resolves outside
  ${cfg.mountPoint}, escaping the pool-source contract. Check via
  !(lib.hasPrefix "/" m.source) && lib.all (p: p != "" && p != "." && p != "..") (lib.splitString "/" m.source) (also rejects a//b and a trailing slash).
• each dependentServices entry is a bare systemd.services attr name --
  non-empty and not ending in .service. The name is used directly as a
  systemd.services.<name> key, and NixOS appends the suffix itself: its
  serviceConfig submodule sets name = "${name}.service" unconditionally
  (nixos/lib/systemd-lib.nix), with no stripping. So an entry like
  "jellyfin.service" would define a phantom jellyfin.service.service unit and
  silently attach the BindsTo/After/ConditionPathIsMountPoint edges there,
  leaving the real jellyfin.service ungated -- it could hold pool files open
  through braid lock, the one safety property the VM test exists to prove.
  Check each name across every mount:
  svc != "" && !(lib.hasSuffix ".service" svc).

2. Register the module

Add ./mounts.nix to modules/braid/default.nix imports (alongside
storage.nix, ups.nix, ...).

3. Export mounts to config.json (modules/braid/cli.nix)

Add a mounts field to the generated /etc/braid/config.json so the CLI
(doctor) can see them. Minimal shape per entry: { target, source, seal }.
Built from cfg.mounts with the existing (pkgs.formats.json { }).generate
path (cli.nix already uses this exact form -- a generator from an empty-attrs
call -- for the fan-control/ups/auto-suspend blocks).

4. Rust -- minimal read-only doctor awareness

The feature works with zero Rust; this adds robustness only.

• cli/src/config.rs: add mounts: Vec<MountEntry> to both RawConfig (as
  a #[serde(default)] field) and Config, threaded through the existing
  TryFrom<RawConfig> (the same path fan_control/ups/auto_suspend already
  take). MountEntry { target, source, seal } carries its own
  #[serde(deny_unknown_fields)]: RawConfig's deny_unknown_fields does not
  propagate into nested structs, so Pwm/FanControl/Ups/AutoSuspend each
  repeat it (with dedicated rejects_unknown_field_in_* tests) -- MountEntry
  matches that pattern, plus an unknown-field rejection test.
• cli/src/doctor.rs: add check_braid_mounts, registered in the cmd_doctor
  check loop. Per configured mount, emit one per-item CheckResult (subject =
  target), following the per-disk check pattern:
  • pool mounted -> target should be a mountpoint; Warn if not (dependent
    services gated off);
  • pool offline and seal -> target should be immutable; reuse
    doctor.rs#classify_mountpoint_immutability (the ADR 028 detector); Warn
    if not sealed.
• New doctor strings must pass just check-output-ascii.

Out of v1 (follow-up): status listing of active braid.mounts (the
~50-100 line StatusReport addition). Note it in the ADR Consequences.

5. ADR 032 -- docs/design/decisions/032-declarative-pool-mounts.md

(Next free number: 030-smart-btrfs-error-reporting.md and
031-drive-wake-posture.md already exist, so this ADR is 032.)

status: Active. Sections: Context, Decision (the four locked invariants +
lifecycle/seal/dependent-services), Rejected alternatives, Consequences, See.

The Decision also records the target-containment safety invariant: a mount
target must not equal, nest under, or be an ancestor of the pool mount (nor be
/). This is not cosmetic -- braid lock addresses exactly one configured
mount point (config.mount_point()), so an ancestor/root target that shadows
/mnt/storage would leave lock unable to resolve the live pool mount and strand
btrfs mounted or LUKS open. The invariant is enforced by eval-time assertions
(normalized component validation) and proven by the F5 eval test.

The Decision also pins the dependentServices naming contract: entries are
NixOS systemd.services attr base names with no .service suffix, because
braid uses each as a systemd.services.<name> key and NixOS appends .service
itself (serviceConfig: name = "${name}.service"). An eval-time assertion
rejects empty or .service-suffixed names so the lifecycle edge can never land
on a phantom <name>.service.service unit, silently leaving the real service
ungated through braid lock. Proven by the F6 eval test.

It also records the dependentServices lifecycle contract: each named
service gets the full ADR 018 triad (WantedBy + BindsTo + After) plus a
ConditionPathIsMountPoint gate, re-pointed at the per-target .mount instead
of braid-online.service. WantedBy is load-bearing -- it is the start-on-unlock
half; without it the service stops on lock but never restarts on the next unlock.
Binding to the granular .mount (itself BoundBy braid-online.service) scopes
the service to its own mount while preserving the pool-wide teardown cascade.
The full lifecycle (offline -> skipped, unlock -> auto-start, lock -> stop-first)
is proven by the VM test.

Amend ADR 028, do not merely cite it. ADR 028's "Separate-path subvolume
mounts (not auto-sealed)" section states separate-path mounts are not auto-sealed
and parks a Revisit-if for a braid.extraSealedMountPoints list, flagging one
wrinkle: a systemd.mounts target dir "may not exist until first mount, so an
offline-before-first-mount path reports Absent until created." braid.mounts
makes separate-path targets auto-sealed (a per-target seal oneshot on ADR 028's
own braid-seal-mountpoint template), so that section now contradicts shipped
behavior -- and AGENTS.md requires the ADR be updated, not just referenced. This
plan amends the section to (a) point at ADR 032 as the realization of that
Revisit-if (declarative auto-seal + boot/activation re-seal + per-target doctor
coverage), (b) mark the Revisit-if resolved for braid-managed targets while the
manual braid seal-mountpoint <path> lever stays for hand-written systemd.mounts,
and (c) record that the wrinkle is dissolved: systemd.tmpfiles.settings
pre-creates each target before the seal runs, so a braid.mounts target is never
Absent-until-first-mount. ADR 028's filename and its ## See link to
mounting-subvolumes.md are unchanged, so check-see-paths.py stays green.

Rejected alternatives: subvol= mounts (need FSID = runtime state); CLI-owned
runtime mounts (bind needs no FSID, static units suffice, CLI ownership would
duplicate lock/lifecycle); owner/group/mode/acl as options (inode-level, not
per-mount -- MNT_BIND_SETTABLE); a freeform extraOptions passthrough (an
unvalidated escape hatch that can silently reverse the fail-safe hardening
defaults -- a stray rw/exec/dev reopens the hole the defaults close; the
typed bool knobs ARE the allowlist, and the exposed set is a deliberate
curation of MNT_BIND_SETTABLE, not the whole kernel set -- so the ADR states
the exact v2.42 composition and the no-passthrough invariant); braid managing
content ACLs declaratively (content is runtime state behind the lock; same
hazard as the rejected braid.subvolumes).

Cite Principle 2 (FSID from live btrfs), Principle 7 (product-boundary wrap
rationale: lifecycle control + unified surface + auto-seal), ADR 017
(runtime-vs-declarative split), ADR 018 (lifecycle triad), ADR 028 (seal,
extended to targets). ## See paths must resolve (scripts/docs/check-see-paths.py):
modules/braid/mounts.nix, modules/braid/storage.nix,
cli/src/lock.rs#run_lock_pre_steps, cli/src/doctor.rs,
cli/src/mountpoint_guard.rs, and the ADR/guide markdown links.

Register ADR 032 in docs/SUMMARY.md.

6. Docs refactor -- docs/guides/mounting-subvolumes.md

Keep the filename (avoids churn across ADR 028's ## See, SUMMARY, and
cross-links); update the H1/intro to be source-agnostic ("Mounting pool paths --
subvolumes or folders"). Restructure to:

1. Mental model -- three layers, taught generically: a reachable PATH (the
   mount), READ permission on the bytes (an ACL), LIFECYCLE (triad-binding, now
   automated). Explain the 3-principal limit (owner + one group + other is
   already spent on root:storage, so a read-only reader is a 4th principal
   -> an ACL is necessary, not stylistic).
2. braid.mounts -- the declarative way (PRIMARY). Neutral target
   /srv/braid/movies. Show flags, auto-triad, auto-seal, dependentServices.
3. Granting read access (the manual companion). The one thing braid.mounts
   does not do, and why (inode/content, runtime behind the lock). setfacl
   with capital rX (fix the current lowercase rx); -d default ACL so
   new files inherit; one-time, persists on-disk.
4. Worked example: Jellyfin (bounded). Neutral /srv/braid/movies (NOT
   /var/lib/jellyfin/media -- that entangles with jellyfin's StateDirectory
   and creates an ordering hazard). One fence line: "access wiring only;
   jellyfin's state dir and transcoding are its own docs."
5. Manual alternative: subvol= / hand-written systemd.mounts. Keep the
   old recipe for users who specifically need subvol=; link ADR 018.
6. Offline mountpoint safety. braid.mounts now auto-seals targets; the
   manual recipe still needs manual braid seal-mountpoint.

Redundancy: the triad's canonical explanation stays in
sharing-and-permissions.md#binding-shares-to-the-pool-lifecycle; this page
links there and notes braid.mounts automates it. Keep
sharing-and-permissions.md's ACL cross-reference pointing here (update the
anchor if the section slug changes).

Also: add a brief braid.mounts cookbook entry to README.md (keep README and
docs in sync per AGENTS.md); add a one-line braid.mounts example under
Principle 7's examples in docs/design/principles.md.

7. Tests -- tests/

VM lifecycle test (tests/module/). This is the declarative-path gate;
the existing tests/module/subvol-mount-lifecycle.{nix,py} is retained as the
manual-recipe gate (it wires a hand-written systemd.mounts subvol mount with
a dummy-jellyfin service bound to the mount unit and already proves the same
service -> mount -> braid-online teardown, both-LUKS-mappers-inactive after lock,
and unlock -> lock -> unlock reactivation -- the manual recipe section 6 keeps), so the
two cover different config surfaces and neither is a duplicate. Model the new
test's skeleton on subvol-mount-lifecycle -- the closest structural analog: a
dummy service holding an fd inside the bind, an unlock -> lock -> unlock cycle,
and mappers asserted inactive after lock (it uses the same readlink /proc/<pid>/fd/3
busy-hold idiom); borrow the BoundBy-iteration / mapper-inactive teardown idiom
from lock-stops-bound-consumers.py. Neither template asserts the
not-running/not-failed-while-offline state, so this test adds it explicitly (below).
Register in flake.nix checks per docs/dev/testing.md; include the 3-section
Intent/Why/Scenario preamble. Config: a valid mount braid.mounts."/srv/braid/movies" = { source = "movies"; readOnly = true; dependentServices = [ "<dummy>" ]; },
plus a whitespace-target mount braid.mounts."/srv/braid/my movies" = { source = "movies"; readOnly = true; }
(source set explicitly so it binds the real movies dir, not the baseNameOf
default my movies).
Assert:

• before the first unlock (pool offline): the valid /srv/braid/movies.mount
  is skipped, not failed -- systemctl is-active <target>.mount reports
  inactive (the ConditionPathIsMountPoint=/mnt/storage gate skips it cleanly)
  and the unit is absent from systemctl --failed. This guards the
  Condition-before-Assert composition the plan justifies at length: a regression
  dropping ConditionPathIsMountPoint (leaving only AssertPathIsDirectory,
  whose source is inside the still-offline pool) would mark every valid mount unit
  failed at boot -- yet the unit could still recover on unlock via its WantedBy
  pull, so the post-unlock asserts below would all pass and hide the regression.
  Only an offline-state check catches it.
• after unlock: /srv/braid/movies is mounted, is ro, and appears in
  systemctl show -P BoundBy braid-online.service;
• the dummy dependent service follows the full mount lifecycle, not just the
  stop half: it is not running while the pool is offline (boot reaches
  multi-user.target, but its ConditionPathIsMountPoint skips it), and it
  starts automatically after braid unlock once the bind mount is active --
  driven by the additive wantedBy = [ "<target>.mount" ] start edge, ordered
  After the mount. (This is the restart-on-unlock half; a wantedBy-less
  regression leaves it stopped after unlock and fails here.);
• braid lock stops the dependent service before the bind, then unmounts the
  pool, and LUKS actually closes (no surviving bind blocks cryptsetup close
  -- the load-bearing safety property);
• while offline, the target dir is sealed (immutable);
• missing-source fail-closed: a second mount whose source names a path
  that does not exist in the pool (e.g. source = "nope") leaves its
  .mount unit failed after unlock (the AssertPathIsDirectory fires), the
  target is not a mountpoint, and crucially no /mnt/storage/nope
  directory is created (guards the systemd silent-mkdir behavior). braid
  remains online and the valid mount is unaffected (failure blast radius is one
  unit: Wants, not Requires).
• whitespace target rendered safely: the space-containing target
  /srv/braid/my movies is created by tmpfiles.settings, mounts ro, and is
  sealed (immutable) while offline. This proves the settings + escapeShellArg
  rendering survives a valid path that the old raw rules/script interpolation
  would have whitespace-split -- the tmpfiles dir is created at the full path (not
  a truncated /srv/braid/my), and braid seal-mountpoint receives one argv, not
  two. (A no-escaping regression fails this assertion at the create-or-seal step.)

Pure-eval tests (tests/eval/, registered in flake.nix checks like
eval-lock-systemd-stop-deadline-fails). The existing _braid-eval-harness.nix
only accepts lockSystemdStopDeadlineSecs and hard-codes braid.enable/package,
with no way to inject braid.mounts -- so it must first be parameterized
to take arbitrary braid module config (add an extraConfig/braidConfig arg
merged into the system modules). Then F3/F5/F6 are negative-assertion tests
reusing the existing assertion-message filter body (builtins.filter over
config.assertions for assertion.value == false && message == expected, exactly
lock-systemd-stop-deadline-assertion-fails.nix), while F4 is not an assertion
test -- it is a resolved-value-equality check that reads
config.systemd.services.<svc>.unitConfig.ConditionPathIsMountPoint and compares
it to the 2-element list (no config.assertions involvement), a shape neither
existing eval test demonstrates:

• source-escape rejected (F3): braid.mounts."/srv/x" = { source = "../escape"; }
  yields a failing assertion with the expected message; assert it is present.
• target-escape rejected (F5): each of target = "/", target = "/mnt"
  (ancestor of the /mnt/storage pool), and a non-normalized
  target = "/srv/../mnt/storage" yields a failing target assertion; assert each
  is present (one check with a small case table, same harness).
• shared dependent service merges cleanly (F4): one dependent service listed
  on two mounts (/srv/a and /srv/b) evaluates without a unitOption merge
  conflict and merges to both ConditionPathIsMountPoint entries:
  config.systemd.services.<svc>.unitConfig.ConditionPathIsMountPoint resolves
  to the two-element list [ "/srv/a" "/srv/b" ] (proves the scalar conflict is
  avoided and both gate conditions render).
• .service-suffixed dependent service rejected (F6):
  braid.mounts."/srv/x" = { dependentServices = [ "jellyfin.service" ]; }
  yields a failing assertion with the expected message; assert it is present.
  Without the assertion NixOS would generate a phantom jellyfin.service.service
  unit and leave the real jellyfin.service ungated, so this guards the
  base-name contract directly (same harness).

Files

• modules/braid/mounts.nix -- NEW: option + unit/tmpfiles/seal/dependent-service generation.
• modules/braid/default.nix -- add ./mounts.nix import.
• modules/braid/cli.nix -- export mounts into config.json.
• cli/src/config.rs -- Config.mounts: Vec<MountEntry> (#[serde(default)]).
• cli/src/doctor.rs -- check_braid_mounts, reuse classify_mountpoint_immutability.
• docs/design/decisions/032-declarative-pool-mounts.md -- NEW ADR (032: 030
  and 031 are taken).
• docs/design/decisions/028-immutable-unmounted-mountpoint.md -- amend the
  "Separate-path subvolume mounts (not auto-sealed)" section (F4: point at ADR
  032, mark the Revisit-if resolved, note the Absent-until-first-mount wrinkle
  dissolved by tmpfiles pre-creation).
• docs/guides/mounting-subvolumes.md -- major refactor (keep filename).
• docs/guides/sharing-and-permissions.md -- minor anchor/cross-ref upkeep.
• docs/design/principles.md -- Principle 7 example line.
• docs/SUMMARY.md -- register ADR 032.
• README.md -- cookbook entry.
• tests/module/<new test>.py -- VM lifecycle + missing-source fail-closed.
• tests/eval/braid-mounts-source-escape-fails.nix -- F3 negative assertion.
• tests/eval/braid-mounts-target-escape-fails.nix -- F5: /, ancestor, and
  non-normalized targets rejected.
• tests/eval/braid-mounts-shared-service.nix -- F4 clean-merge eval (one
  dependent service on two mounts).
• tests/eval/braid-mounts-dependent-service-suffix-fails.nix -- F6:
  a .service-suffixed dependentServices entry is rejected.
• tests/eval/_braid-eval-harness.nix -- parameterize to accept arbitrary braid
  module config (an extraConfig/braidConfig arg) so the four eval tests can
  inject braid.mounts; today it only takes lockSystemdStopDeadlineSecs.
• flake.nix -- checks registration for all four.

Reuse (do not rebuild)

• lock.rs#run_lock_pre_steps -- generic BoundBy braid-online.service
  teardown; the bind unit is stopped automatically. No change.
• mountpoint_guard.rs explicit-path braid seal-mountpoint <path> -- reused
  verbatim by each seal unit. No change.
• online_state.rs#mark_online -- ignores secondary mounts. No change.
• storage.nix braid-scrub (triad template) and braid-seal-mountpoint
  (self-healing seal template).
• doctor.rs#classify_mountpoint_immutability -- the seal detector.

Verification

• just test-vm <new test> -- the lifecycle/teardown/seal assertions (primary).
• just test-rust -- Config serde + check_braid_mounts unit tests.
• nixos-rebuild build (or nix eval) of an example config -- confirm the
  option type-checks and the bind/seal units render.
• just test-vm <eval tests> -- the four tests/eval/ checks: source = "../escape"
  is rejected; /, an ancestor (/mnt), and a non-normalized target are rejected;
  a .service-suffixed dependentServices entry is rejected; and one dependent
  service on two mounts merges to both ConditionPathIsMountPoint entries -- a
  two-element list (no unitOption merge conflict).
• mdbook build docs -- linkcheck the ADR + guide edits.
• scripts/docs/check-see-paths.py -- ADR ## See paths resolve.
• just check-output-ascii -- new doctor strings.
• Because this is lifecycle-adjacent, hand back for a fuller just test-vm
  run before merge (per AGENTS.md test-scope guidance) rather than only the
  focused test.

Out of scope / follow-ups

• status listing of active braid.mounts (Rust StatusReport addition).
• braid applying declared read grants at pool-online (the mark_online ACL
  hook) -- recorded in ADR 032 as a possible future, intentionally not built.
• Renaming mounting-subvolumes.md -> mounting-pool-paths.md (cosmetic;
  defer to avoid cross-file link churn).