docs: fix genuine passive-voice hits in docs/process

Fourth batch of hyperhive#4042's Passive pass (see #4098/#4099/#4100
for the first three and the read-every-hit discipline this pass
uses). 44 hits across pr-review-gate.md (4), conventions.md (18), and
gotchas.md (22) -- highest genuine-catch rate so far, 23/44 (~52%),
because this architecture/mechanism documentation has a lot of "X
does Y via Z" sentences where the actor is already named
parenthetically or in a nearby clause -- the single most productive
rewrite shape across every batch so far.

Recurring rewrite shapes this batch:
- Actor already named in the same sentence, just not as the
  grammatical subject: "X is configured per repo in its
  branch-protection settings" -> "Each repo's branch-protection
  settings configure X" (pr-review-gate.md); "the broker" (reserved
  names), "rsvg-convert" (PNG rendering), "the website repo" (HTML/CSS
  rendering), "systemd.globalEnvironment" (D-Bus address export), and
  several more -- all the same shape.
- Subject already established one clause or one sentence earlier,
  just needs continuing rather than restarting with a new passive
  subject: "the harness reads HIVE_TOOL_GROUPS (...). Unrecognised
  tokens are logged and skipped." -> "...logging and skipping
  unrecognised tokens" (continues "the harness"), same pattern twice
  more (job_queue::templates::rebuild, HIVE_CAPABILITIES resolution).
- Sibling-inconsistency: a bolded lead-in bullet was the one passive
  sentence in an otherwise-active paragraph/table (the
  read_host_journal capability row sat between two "may X" rows; the
  HTML+CSS bullet's own tail clauses were already active voice around
  the one passive lead phrase).
- One caught-and-fixed authoring mistake worth noting for future
  passes: the first attempt at the "Nix treats X as a package" rewrite
  landed in the wrong sentence (a similarly-worded but unrelated
  passage two paragraphs up) -- caught by re-reading the diff before
  running vale, not by vale itself (which would have shown 0 remaining
  hits either way, since the intended sentence's hit just wouldn't
  have been touched -- a silently-wrong edit vale's own count can't
  catch). Re-reading the actual diff, not just trusting the before/
  after hit count, is what caught it.

21 of 44 left alone -- same recurring legitimate shapes as prior
batches (predicate-adjective copulas, quoted/literal text, generic-
actor statements, negative-capability invariants, "is tracked/rooted/
scoped at X" property-description idioms, and two more thesis-
statement headings matching the "Ownership is declared, not repaired"
precedent from #4100).

Verified: vale docs/process before/after -- 44 -> 21 write-good.Passive
hits, exactly the 23 rewritten, re-read every changed line's full
surrounding context after editing (not just the vale count) to catch
exactly the kind of misplaced-edit mistake described above.
This commit is contained in:
iris 2026-09-08 12:24:03 +02:00
commit c41c67c949
3 changed files with 37 additions and 38 deletions

View file

@ -91,7 +91,7 @@ Two things to get right when a daemon needs outbound TCP:
works until DNS hands back the other family;
- list `AF_NETLINK` too. glibc's `getaddrinfo` opens a netlink socket to
enumerate local addresses before it returns any, so name resolution
fails without it even when `AF_INET` is allowed.
fails without it even when the unit allows `AF_INET`.
**The directive is a claim about what the program does, and nothing
re-checks it when the program changes.** A unit that only served a unix
@ -143,15 +143,15 @@ to options the operator writes: **any** option of type `package` fed a
store-path _string_ coerces through `lib.toDerivation`, i.e.
`builtins.storePath`. `environment.systemPackages` and
`systemd.services.<name>.path` both do it (the latter takes plain
strings like `/run/wrappers` happily, but anything under
`builtins.storeDir` is treated as a package). A path handed to the
strings like `/run/wrappers` happily, but Nix treats anything under
`builtins.storeDir` as a package). A path handed to the
container as text has to be wrapped in a real derivation — a symlink
farm built from the interpolated string — before it can go anywhere a
package is expected.
The catch is that a path written into a generated flake is text, not a
reference — the container's closure doesn't keep the binary alive.
The **host** does: the package is interpolated into
The **host** does: it interpolates the package into
`/etc/hyperhive/serve.json`, so it lands in the host's system closure
and is gc-rooted by the running generation. `builtins.toJSON` preserves
string context, which is the load-bearing detail; discard the context
@ -204,14 +204,14 @@ the `TIME_WAIT` case from a clean previous exit; retry covers the
genuine "previous process is still alive during a systemd restart
overlap" case. REUSEADDR does **not** allow two simultaneous
`LISTEN` sockets on the same port (that would be `SO_REUSEPORT`,
which we don't use) — exclusivity is preserved.
which we don't use) — it preserves exclusivity.
## Approvals
### Orphan approvals
If state dirs are wiped out from under a pending approval (test
scripts, manual `rm -rf`), the dashboard's next render marks them
If test scripts or a manual `rm -rf` wipe state dirs out from under a
pending approval, the dashboard's next render marks them
`failed` with note `"agent state dir missing"` so they fall out of
`pending`. They stay in sqlite for audit.
@ -323,7 +323,7 @@ rust build's `src` was the whole repo tree, any tweak to
invalidated the cargo cache and forced a full rebuild. crane (and
naersk before it) couldn't see "these inputs are unused by rust" on
its own — the split breaks the coupling at the derivation boundary.
The agent-configs PNG is rendered from the SVG via `rsvg-convert` at
`rsvg-convert` renders the agent-configs PNG from the SVG at
build time; librsvg dependency lives here, not in the rust
derivation's `nativeBuildInputs`.
@ -400,10 +400,9 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
= invisible window even though CDP works). The fix is **not** to wrap
each client in its own `dbus-run-session` (a private throwaway bus per
process — that's a _separate_ session, defeating the one-session
model); it's this one shared bus, whose address is exported as
`DBUS_SESSION_BUS_ADDRESS=unix:path=/run/gui/bus` via
`systemd.globalEnvironment` so weston, the harness and every GUI client
inherit it.
model); it's this one shared bus; `systemd.globalEnvironment` exports
its address as `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/gui/bus` so
weston, the harness and every GUI client inherit it.
- **Fixed Wayland socket name (`--socket=wayland-0`)**: weston is
launched with `--socket=wayland-0` so the socket path is
deterministic. `nix/agent-modules/weston-vnc.nix` exports `WAYLAND_DISPLAY=wayland-0`
@ -471,12 +470,12 @@ Pipeline:
- CommonMark from `nixosOptionsDoc.optionsCommonMark` is the only
output — the source of truth, emitted as `.md`.
- **HTML + CSS is rendered downstream by the website repo**
(its own `options.nix`), which consumes this bundle's `host.md` /
`agent.md`, renders them with `cmark-gfm`, and shares one
- **The website repo renders HTML + CSS downstream**
(its own `options.nix`), consuming this bundle's `host.md` /
`agent.md`, rendering them with `cmark-gfm`, and sharing one
stylesheet (`docs.css`) across `/options/` and the prose `/docs/`
tree. Keeping rendering in the website means the theme has a single
home and the colours are shared.
home, sharing colours across both trees.
- `transformOptions` strips the nix-store prefix from option
declaration paths and rewrites them as forge URLs, so the
rendered docs link back to the source.
@ -512,7 +511,7 @@ The fix (`nix/docs/default.nix`):
never forces a package — no stubs needed, and the Rust/frontend
build closure stays out of the eval.
3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
3. Nix evaluates both `hostEval` and `agentEval` from `nixSrc` paths
(not `self`), so the docs drv dependency chain ends at `nixSrc`.
Why `builtins.unsafeDiscardStringContext`? The path string