Issue 169: network-share is the module responsible for a node's network shares — a node role

nfs-share and smb-share share an intent, not a contract; one seat would be
a union with every field optional. What the exemplar exposes is that a
seat declared inside one module cannot be implemented by another without
depending on it.

04-ISSUES/169-a-machine-shares-its-files-and-the-mesh-does-not-know/00-report.md

@@ -0,0 +1,128 @@
+---
+status: open
+opened: 2026-09-30
+located-in:
+  - mesh-catalog (no module shares a path over the network)
+  - hq 02-DECISIONS (a file-share seat, per ADR 0126, is a module's own to define)
+fixed-by:
+amended-design:
+---
+
+# 169 — A machine shares its files, and the mesh does not know
+
+## What was observed
+
+ace serves the operator's media library to the home network with two host services no module
+declares and HAL never managed either:
+
+```
+/etc/exports:   /storage/media  192.168.1.0/24(rw,sync,root_squash,…)     nfs-server active, :2049
+/etc/samba/smb.conf: [media] path = /storage/media/  valid users = media   smb active, :139/:445
+```
+
+Two LAN clients were connected at survey (2026-09-30). The library itself is operator data
+(ADR 0051: ~40 TB on ZFS, the mesh owns nothing about it — [issue 153](../153-an-adopted-machines-data-cannot-be-placed-where-it-is/00-report.md)
+is about modules reaching it in place).
+
+Under the mesh as it stands, this arrangement has no expression and one failure mode:
+
+- **Nothing declares the listens.** At `converge ace` the filter is the sum of what modules listen
+  on (ADR 0045); 2049 and 445 are nobody's, so the shares close — silently, for the two clients
+  that mount them.
+- **Nothing owns the configuration.** `/etc/exports` and `smb.conf` are hand-written files on one
+  machine; a second machine sharing a directory would be written by hand again.
+- **Nothing can consume it.** A module on another node that wanted the library (a player, an
+  indexer, a backup) has no `requires` to state and no binding to read; it would mount by a
+  hand-typed host and path.
+- The clients are LAN devices, so this also meets [issue 154](../154-a-machines-own-network-is-not-a-reach/00-report.md)
+  (no reach for the machine's own network).
+
+## The proposal (the operator's, 2026-09-30, settled after two rounds)
+
+**Two module-defined seats, one per protocol, because NFS and SMB share an intent and not a
+contract.** A seat in the mesh's sense is a contract — what it accepts, emits and serves, and the
+tools its holder must answer (ADR 0126, 0132) — and lined up, the two share almost none of it:
+
+| | `nfs-share` | `smb-share` |
+|---|---|---|
+| serves | export path(s); the client ranges allowed (`sec=sys` authorises by address) | share name(s), path |
+| pair credential | none | a user and password per consumer |
+| consumer's mount | `at:/path` | `//at/share` with credentials |
+| holder's tools | export / unexport a path for a range | add / remove a share, create a user |
+
+One `file-share` seat would be the union with every field optional — a consumer could bind it and
+still not know how to mount what it got (the emptiness ADR 0129 warns against). "Export a path to
+the network" is a category, and the mesh needs no seat category: a consumer requires the one it
+can mount. If "give me the library, however" is ever needed, it is a provision an umbrella module
+serves, not a seat.
+
+Both are node-scoped, one holder per node (ADR 0110), so ace holds both. `nfs` and `samba` are the
+first implementations; a second (Ganesha for `nfs-share`, ksmbd for `smb-share`) is what proves
+0126's promise that "replacing the implementation changes nothing for any caller".
+
+The holder module:
+
+- declares the exported paths as `accesses` (ADR 0051: it owns nothing about them — never creates,
+  chowns or removes), and *which* paths as the assignment's settings (ADR 0046/0112);
+- writes the share configuration (`/etc/exports`, `smb.conf`) as mesh-managed files and drives the
+  units, like `dnsmasq`/`sshd` do for theirs;
+- declares its endpoints (`nfs` 2049/tcp; `smb` 445/tcp, …) so the reach — internal, or the LAN
+  once 154 has an answer — is the assignment's, and converge keeps them open;
+- **provides** the seat's provision, so a consumer on another node `requires nfs-share` (or
+  `smb-share`) and reads `${bound:nfs-share:at}` and the path from its binding instead of a
+  hand-typed mount.
+
+## The design gap this exposes
+
+**A seat definition has no home outside the module that first declared it.** Today a seat is
+declared inside a manifest (`showcase` declares `the-showcase`, `ca-trust` its own). If `nfs`
+declared `nfs-share`, Ganesha could hold it only by depending on nfs's manifest — the coupling
+0126 removed for callers, reintroduced for implementations. The protocol needs a neutral place in
+the catalogue beside the modules (a seat definition registered like a manifest), with a module
+saying which seats it implements. This is the first role with an obvious second implementation,
+which is what makes it the exemplar for that mechanism.
+
+## The consumer's half: a module mounts it (2026-09-30, third and fourth round)
+
+A binding tells a consumer *where* the share is; it does not put the files on its machine. Mounting
+is something done on a machine, and something done on a machine is a module's work — not the host's
+(the vocabulary stays closed; no `mount` resource kind).
+
+**A consumer-side module, `network-share` — the module responsible for setting up the network
+shares a node uses** (the operator's framing). A node role, like `node-uplink` or
+`node-dns-resolver`: each machine has it at most once, which is a reason for it to hold a
+node-scoped seat, so two modules can never both be writing mount units on one machine. Assigned on
+the node that wants the files:
+
+- `requires nfs-share` (or `smb-share`); several shares on one node are several local names of
+  the requirement (ADR 0094);
+- its manifest is a `package` (nfs-utils), a `file` writing a systemd `.mount` unit filled from
+  the binding — `What=${bound:nfs-share:at}:${bound:nfs-share:path}` — and a `service` enabling it
+  after the overlay is up: the same shape as `resolv-conf` or `sshd`, files and a unit;
+- *where* it mounts is the assignment's setting (`/srv/media` on one machine, elsewhere on
+  another); which machine mounts what is an operator decision made at assignment, exactly as which
+  paths a machine shares is.
+
+**The modules that use the files never learn about NFS.** A player, an indexer, a backup declares
+the mounted path as an `access` — an operator-chosen, pre-existing path the mesh never owns
+(ADR 0051), exactly as `/storage/media` is on ace. The same app manifest then runs on ace against
+the local library and on another node against the mounted one, with only its assignment differing.
+
+**The one check to add, because it is the data-loss case.** An `access` is confirmed today by the
+path being present. For a mountpoint that is not enough: a writer whose container starts before the
+mount is up writes into the empty directory underneath it, and the files vanish when the mount
+lands. The access check must confirm the path is *a mountpoint* when the module says so (or the
+module's unit is ordered before the consumer's container — which crosses modules and is exactly
+what the mesh does not order). Which of the two is the decision's.
+
+**Identity crosses the wire.** `sec=sys` NFS trusts the client's uid, so a consumer must run as the
+library's owner on the server (ace: `media`, 1001:2000) — hq 153's `${access:<id>:uid}`, read from
+the mounted tree, answers it on the consumer's side too.
+
+## Open questions for the decision
+
+- Whether an NFS export over the overlay is an `internal` reach of the same endpoint or a second
+  export line — NFS authorises by client address, so the mesh range and the LAN range are two
+  entries in one file.
+- How a consumer's binding expresses a *path* to mount (today bindings carry `at`, `port`, `as` and
+  whatever the provider `serves`), and whether one share can serve several paths.