ADR 0260: say what review narrowed — one key per grant, per-machine state, wider path roots, a follower that speaks

02-DECISIONS/0260-a-bar-block-shows-a-value-its-module-keeps-on-the-bus-and-no-module-reads-anothers-files.md

@@ -44,26 +44,44 @@ What the mesh already had:
 
 ## Decision
 
-**1. Modules talk over the bus, never through each other's files.** No module names a path under
-`/run` or `/var/lib` that another module's manifest places. Within one module, parts may pass a file:
-its root process and its bundle are one module.
+**1. Modules talk over the bus, never through each other's files.** No module names a path that
+another module's manifest places under `/run`, `/var/lib`, `/usr/local/lib` or `/etc`. Within one
+module, parts may pass a file: its root process and its bundle are one module.
+
+Two exceptions are written down beside the check:
+- a short list of paths every program on a machine reads as the machine's own, such as `/etc/hosts`;
+- the cross-module reads that stood on the day the rule took `/etc` in. These may only go: there are
+  five, all the laptop model's module reading the power module's and the hotkey daemon's files.
+
+A path a container sees inside itself is the container's own. The check reads text, so it cannot see
+a path built in code from pieces, read from a setting, or reached through a shell the module runs.
 
 **2. A block may show a value its module keeps on the bus.** This adds `shows: state` to ADR 0255 §5:
 - options `state`, naming the state as `<module>.<name>`;
-- option `key`, the machine's own name when absent;
+- option `key`, lower-case letters, digits and hyphens, the machine's own name when absent;
 - the value is an object, and its `text` is what is shown.
 
 A module offers only state it keeps itself. A block naming another module's state, or one the
 contributor does not keep, is refused at registration. The holder's template sees `machine`, the node
 it renders for, so the key needs no setting.
 
-**3. The holder is granted the read, without naming the contributor.** The controller derives the
-holder's reads per machine: every state that the modules on the holder's machine offer in pieces of a
-kind its seat receives as data. The bar's manifest names no power module. A bar on a machine without
-the power module reads nothing of it. The contributor may write its own state, and the holder may only
-read it, as ADR 0201 already grants.
+**3. The holder is granted the read of one key, without naming the contributor.** The controller
+derives the holder's reads per machine: each state that the modules on the holder's machine offer in
+pieces of a kind its seat receives as data, and of each only the key the piece shows. The bar's manifest
+names no power module, and a bar on a machine without the power module reads nothing of it.
+- On the bus the grant is that one key: a direct get of its subject, and a consumer filtered to it.
+  A client watching one key creates its consumer by the create-with-filter form, which the server
+  holds to the filter it names.
+- Binding to the bucket, deleting a consumer and flow control stay per bucket. None of them reads or
+  writes a value.
+- **State may be per machine.** A state declared `per-machine` is written and read by each machine's
+  instance at the key named for its machine, and the bus grants that key and no other. The power
+  module's `draw` is per machine, so a machine's power module can write only its own draw.
+- One account per machine carries every module there, so the bus enforces the union of their grants.
+  For the power draw, that union is still the machine's one key.
+- The membership names the key, so the runtime can refuse first. Until it does, the bus refuses.
 
-**4. The power draw is the power module's state `draw`, keyed by the machine.** It holds one value
+**4. The power draw is the power module's state `draw`, per machine.** It holds one value
 per machine, with these fields:
 - `text`, the line shown;
 - `watts`;
@@ -77,8 +95,14 @@ four machines that is under one message a second.
 **5. The bar shows a bus value in its own way.** For i3status-rust:
 - the bar's bundle watches each state its bars name;
 - it leaves the value's text in the bar module's own runtime directory;
-- the block runs the bar module's own command, which prints the text, or nothing when it is more than
-  30 seconds old, so the block hides.
+- it dates each value by its own `at`, not by when it arrived;
+- the block runs the bar module's own command, which prints the text, or nothing when the value was
+  measured more than 30 seconds ago, so a value frozen at its source hides;
+- a watch that says nothing for twice the value's lifetime is read again, and the bundle says so in its
+  log;
+- a refused watch is logged and tried again;
+- a value no bar shows any more is dropped. The SDK has no way to end a watch, so a dropped watch
+  lasts until the bundle restarts, and what it hands over is ignored.
 
 Another bar module would show the same state in its own way.
 
@@ -100,11 +124,12 @@ power-supply class itself. That is the bar reading the machine, not another modu
 
 | Rule | Checked by |
 |---|---|
-| No module names a path under `/run` or `/var/lib` that another module's manifest places | the catalogue's `checks/paths`, run by its `merge-check.sh` over every module, and that check's own tests |
+| No module names a path under `/run`, `/var/lib`, `/usr/local/lib` or `/etc` that another module's manifest places; the known exceptions only shrink | the catalogue's `checks/paths` with its `shared` and `known` lists, run by its `merge-check.sh` over every module, and that check's own tests |
 | A block shows only state its contributor keeps | the catalogue check; the controller's `TestAModuleOffersItsOwnStateOnly` |
-| The holder is granted the read of what the modules on its machine offer, and nothing more | `TestAStateBlockIsRenderedForThisMachineAndTheHolderIsGrantedToReadIt`; `TestABarIsGrantedTheStateItsMachinesModulesOfferIt` against a real store |
+| The holder is granted the one key each piece on its machine shows, and nothing more | `TestAStateBlockIsRenderedForThisMachineAndTheHolderIsGrantedToReadIt`; `TestABarIsGrantedTheStateItsMachinesModulesOfferIt` against a real store |
+| A keyed read and per-machine state reach one key on the bus, also as the machine's union | the controller's `TestPerMachineStateAndAKeyedReadReachOneKey`, `TestAMembershipNamesTheOneKeyOfKeyedState` |
 | Only a fresh reading that measured something is put, keyed by the machine | the power module's `publish_test.go` |
-| The bar keeps a value's text, removes a deleted one, retries a refused watch, and hides an old value | the i3status-rust module's `values_test.go` |
+| The bar dates a value by its reading, says a refused or silent watch, rereads a silent one, drops a removed block, and hides a value measured more than 30 s ago | the i3status-rust module's `values_test.go` |
 
 ## References