valis Operations Runbook

The shipped unit expresses an FHS layout the launcher threads into valis's XDG rooting. Provision these before first start:

StateDirectory holds the irreplaceable durable state. systemd creates and chowns it on first boot; the parent's CAP_CHOWN=/=CAP_FOWNER make the owner-seed write under it succeed. Everything backup-critical lives here, and the valis --backup verb seals the backup-critical subset out of it, see 14.

The binary must be the serving-capable delivery core, not a plain :valis core: the plain core lacks the additive DNS-serving stack and fails closed at boot with c3po's serving codec … not available. Stage it from the versioned delivery tarball that make dist produces (valis-serving-<version>.tar.gz); never rebuild the core on the host. See the contract's serving-capable resident binary section.

The units ship under deploy/systemd/. Install them onto the host:

# The supervisor unit.
install -m 0644 deploy/systemd/valis.service /etc/systemd/system/valis.service

# The bootstrap environment seed. Copy the template, fill it, lock it down.
install -d -m 0750 -o root -g valis /etc/valis
install -m 0640 -o root -g valis deploy/systemd/valis.env.example /etc/valis/valis.env
# ... edit /etc/valis/valis.env (next section) ...

systemctl daemon-reload

The ExecStart is /opt/valis/bin/fulcrum-resident, the fulcrum delivery binary that owns the whole bring-up. Stage that binary and the run account per the contract's provisioning surface before enabling the unit.

/etc/valis/valis.env is the node's genesis seed. The node reads each value in it once, at the first boot that considers that value's key, and keeps the result in its configuration store under the data root: <StateDirectory>/valis/config/, which is /var/lib/valis/valis/config/ under the shipped unit. From then on the store is the node's configuration. Change a setting with valis config or through /config over the owner session (see changing a setting). Editing valis.env afterwards has no effect on a key the node has already considered, and the boot log names each such key as superseded by the store, by name and never by value. A key that a newer release adds is seeded from this file once, at that release's first boot.

The file is re-authored by provisioning, is 0640 root:valis, and never enters the tracked repo. Its values travel nowhere: the node's configuration directory is what a backup carries (see backup and restore).

valis apply checks the site facts a boot needs against the node's own configuration first and this file second, the order the node reads them in. Without --confirm-zone it confirms the node's own edge.domain, unless you have set one of your own (see below). When apply cannot read the node's configuration, it checks this file alone and says so; see letting apply read the node's settings.

Each variable below seeds the configuration key beside it:

The database DSN names a local UNIX-domain socket, so the resident reaches Postgres by filesystem path under peer authentication rather than over the network: no password travels in the environment or the configuration, and no TCP listener need be open. Put the socket-path DSN in valis.env for the first boot, and change it afterwards with valis config set operator-state.dsn in the form changing a setting gives. (Moving the database onto a dedicated address inside the netns is deferred hardening; the host is the root of trust for the resident copy.)

The tools you run read seven more variables, from the environment you run them in. They are not node configuration and have no configuration key: the node never reads them, and they do not belong in valis.env.

One more is read only on the host that builds the binary, while it compiles. No node reads it, and it does not belong in valis.env either.

valis config reads and changes the node's settings and any module's. Against a running node it goes through the node's owner session, so from your own machine you name the node, as you do for every owner verb (see Reaching a node's owner control plane):

valis --node NODE config list               # every node key: path, origin, type, when it applies, value
valis --node NODE config list SYSTEM        # a module's keys, and what an upgrade kept aside
valis --node NODE config get edge.domain
valis --node NODE config set edge.domain example.org
valis --node NODE config reset edge.domain  # back to the shipped default
valis --node NODE config menu               # walk the node's settings, one at a time
valis --node NODE config interview SYSTEM   # a module's own questions; a blank answer keeps a value
valis --node NODE config set --module SYSTEM KEY VALUE   # a module's key
valis --node NODE config purge SYSTEM       # delete a removed module's kept settings

config get prints one line of five fields separated by tabs: the key, where its value came from (default or operator), its type, when a change to it applies, and the value, which is empty when the key is unset. A value set equal to the default reads back with the origin default. A change answers with when it takes effect, described below, then key KEY and origin ORIGIN. With a key the node has not enrolled, the verb is refused with exit 2 and changes nothing.

From the node's host, the break-glass route. When you cannot use the route from your machine (the owner port closed, the pin or the device key lost, or the node not answering on the owner port), run the verb on the node's host the way you run the other owner-keyed verbs there, inside the node's namespace with its keyfile and endpoint named (see the break-glass route):

v() {
  sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
    /opt/valis/bin/valis config \
    --keyfile /var/lib/valis/valis/keyfile \
    --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)" "$@"
}
v list
v get edge.domain
v set edge.domain example.org

On the host, reading the node's own settings does not need the owner session. config list and config get KEY, run as the run account on the node's data root, read its store directly, running or stopped. The read takes no lock and writes nothing, so it never delays the node:

sudo -u valis env XDG_DATA_HOME=/var/lib/valis /opt/valis/bin/valis config get edge.domain

I made reads work this way because a running node's owner session lives inside its network namespace, out of reach of the host's, and reading a setting should not need nsenter and root. A module's settings are still read over the owner session, since only a node that has loaded the module can list them.

Against a stopped node, run it as the run account on the node's data root, and it changes the node's own settings directly:

sudo -u valis env XDG_DATA_HOME=/var/lib/valis /opt/valis/bin/valis config set edge.domain example.org

A module's settings change only through the running node, since only a node that has loaded the module can check a value for it. A secret is only ever shown as set or unset. Run against a stopped node as any account but the one owning its data root, the verb is refused with exit 3, as a configuration that could not be changed. Run without --keyfile and --endpoint, it acts on the data root of the account running it, so under sudo alone it reads and writes root's own store and not the node's.

A change answers with when it takes effect:

• committed-applied: the value is stored and the running node is using it.
• committed-on-restart: the value is stored and the node takes it at the next restart. ⚠ This is a success, not a fault: some keys, such as the development listener port and the ACME store, only ever take effect at a restart, and every change to a stopped node answers this way.
• committed-rebind-failed: the value is stored, the running code refused it, and a reason line names the kind of condition. The next restart applies the value.

A purge answers purged or nothing-to-purge, and a purge of a loaded module also answers when its return to the defaults takes effect, as one of the outcomes above. A refusal names what was wrong and changes nothing. The exit status is 0 when the verb read or committed, 2 when the node or the verb refused and nothing changed, which includes a key file that is missing or one the verb will not present, and 3 when the node could not be reached or its configuration could not be changed.

The configuration directory is part of every backup, so a restored node comes back with the settings it had.

systemctl enable --now valis.service     # enable at boot + start now
systemctl status valis.service           # unit + MainPID (fulcrum) state
journalctl -u valis.service -f           # follow the bring-up + serving log

Readiness is meaningful, and it is reported in two places that are not the same place. The bring-up writes its account to the journal, and the resident separately publishes a one-line summary to the supervisor, which systemctl status shows as Status:. Neither carries the other's text, so a phrase you cannot find in the journal is very likely a status-field phrase, and looking harder will not turn it up.

In the journal (journalctl -u valis.service), the bring-up says what it did:

• site configuration complete: every declared site fact was answered, and the count of facts checked follows on the same line. A boot missing one stops here instead, naming the variable it wanted.
• adopting the DNS descriptor pair: the DNS handoff took; valis is serving authoritative DNS over fulcrum's inherited :53 descriptors, binding nothing privileged itself.
• the launch handed down the DNS descriptor pair ... and 53 is not configured: the pair arrived, but this node's served set leaves DNS out, so valis closes it once the fabric is up. DNS does not answer on this node; this is not an adoption.
• :443 public edge opening — certificate in custody for <domain>: a cert was found for the configured domain and the edge is coming up.
• no usable certificate in custody for <domain>; :443 public edge cert-gated dark: the domain is named but no cert has been issued for it yet. This is what an operator sees between naming a domain and completing the first obtain, and it is the line that says the gate is the certificate rather than the configuration.
• no edge.domain configured; :443 public edge stays dark: no served domain named, so :443 is intentionally dark by configuration.

In the supervisor's status field (systemctl status valis.service, the Status: line), the resident publishes its serving state and refreshes it on every health-loop pass. It reads <serving state>; cert <days>; store gen <n>, where the serving state is one of:

• serving :53 + :443: a usable certificate was in custody at boot; the public HTTPS edge is open.
• serving :53; :443 dark (no cert): a healthy genesis boot: :53 is up (which is exactly what dns-01 needs to obtain the first certificate), and :443 is cert-gated dark until a cert is issued. This is not an error and does not withhold readiness.

A silently dark port would look like a fault; between the two surfaces you get why :443 is or is not open, so you never have to guess.

Nothing in the resident gauges descriptor headroom: there is no count in the journal, no field in the status line, and the liveness gate does not read it. A node that has exhausted its descriptors keeps reporting itself as serving and the supervisor is given no reason to restart it, so headroom is a reading the operator takes from outside the process, on the host:

pid=$(pgrep -o -x valis)                   # the resident is fulcrum's child, not MainPID
ls /proc/$pid/fd | wc -l                   # descriptors held right now
grep 'Max open files' /proc/$pid/limits    # the ceiling this process actually has

Match the process name to whatever the launch configuration's :valis-command stages. Take the reading as root or as the run account: another account's /proc/<pid>/fd is not yours to list. The unit sets no descriptor limit of its own, so the ceiling is the service manager's default on this host: read it rather than assume it.

One reading tells you little. Take two, some hours apart under comparable load: a busy node's count moves in both directions, while a count that only ever climbs is a leak, and the moment to act on it is while the number is still nowhere near the ceiling. Put that pair of readings into whatever monitoring you run against the node. Nothing on the node will raise it for you, and the failure it precedes is one every other instrument reports as healthy. Why that is, and what the liveness gate does and does not ask, is set out in backup-and-observability.org.

The :443 edge is obtained and renewed over the ACME/dns-01 spine (custody and the ACME lifecycle are mercer's; valis is the edge that consumes the cert):

1. Genesis (no cert). Boot with edge.domain set but no cert yet: :53 comes up, :443 is cert-gated dark. Serving :53 is the precondition for dns-01: the authoritative answer proves domain control to the CA.
2. Issuance. Once a certificate is issued and lands in the custody store (acme.store-path), a boot with the cert in hand opens :443. dns-01 is the only challenge a node answers today, and there is no fallback. Nothing answers an http-01 challenge on :80 or a tls-alpn-01 challenge on :443, so an order for either has nothing to validate against. That is why serving :53 is a precondition of issuance rather than a convenience.
3. Renewal (hot-swap, no restart). On a successful renewal the live :443 cert is reloaded in place through the shared credential cell: the edge swaps the new leaf without dropping the listener or restarting the unit. A renewal orders under the same account identity the first order used, and it reads that identity from the node's acme.account-contact setting: set it (valis config set acme.account-contact ADDRESS), or renewal refuses every attempt and backs off while the certificate you are serving walks toward its expiry. The boot line reports whether a contact is configured, so check it there rather than waiting for the backoff to tell you.
4. Staging vs production. Default is the ACME staging CA. Set acme.production to true only when you want a real, publicly-trusted certificate: production carries a strict rate ceiling, so exhaust staging first.
5. Wildcards, and the name a certificate is filed under. Custody files an issued certificate under one name, and a wildcard identifier such as *.example.com is a matching rule rather than a name: no filesystem will hold it as a directory. So an order is placed with a host name leading, whatever order you asked for it in, and the certificate covers exactly the names you named. Ask for nothing but wildcards and the order is refused before it reaches the CA, because the alternative is to buy a certificate that has no name to be filed under. Every issuance counts against a rate limit whether or not you get to keep it.
6. A certificate per name, chosen per connection. Ask the node for a name it holds a certificate for and you are presented that certificate. Ask for anything else and you meet the credential sourced for edge.domain, which is the fallback rather than a failure: an unknown name gets the base certificate, and your client then rejects it on a hostname mismatch as it should. Two names count as one only when they differ in case or in a single trailing root dot, because DNS and custody both file them that way. ⚠ Do not read the boot line holds a certificate for N name(s) as any one certificate's subject names: that is the admission list, the names the edge will answer for. Which certificate each of them is served is decided per connection, from custody.

A domain whose DNS lives elsewhere. A node is meant to prove control of every name it serves. For a domain you bring while its DNS stays with a third party, the proof is tls-alpn-01, answered on the node's live :443 edge inside the TLS stack that already serves it, once you enroll that domain through the control plane. That is not built yet. Today such a domain cannot obtain a certificate, and its site does not serve: valis obtain refuses it as a name the node does not serve, before any order reaches the CA. The same holds for a node whose served set leaves out :53, since a node answers dns-01 only from its own :53. To serve a domain today, delegate its DNS to this node and hold its zone here.

Driving the first obtain by hand. The obtain verb runs the order on the process that serves :53, which is what makes the dns-01 challenge answerable at all. Run it from your own machine and name the node:

valis --node NODE config get acme.production
valis --node NODE obtain --domain example.org --contact hostmaster@example.org

Its whole form is:

valis obtain --domain <fqdn> --contact <email> [--profile <name>] [--directory-url <url>]

⚠ Read acme.production first. The first obtain does not refuse a node whose acme.production is false: it orders from the staging authority, or from acme.directory-url when that is set, and serves the certificate it gets, which no browser trusts, on the node's :443 edge. On a node meant to serve the public, set it before the first obtain with valis --node NODE config set acme.production true. A renewal on a node with edge.domain set is refused while acme.production is false, but the first obtain is not, so that read is yours to make.

The verb answers once the order is done. Its reply begins obtained, then a domain NAME line for each name and a next-renewal line, then a line saying where the new certificate is served: edge serving now when the :443 edge took it at once, or edge not open: serving from the next start on a node whose edge is not open yet. A line for each name follows, saying whether a client asking for that name is handed the certificate. With a key the node has not enrolled, the verb is refused with exit 2 and no order is placed.

To tell the new certificate from the one it replaced, compare the leaf's serial and its notBefore. Its issuer may differ, since the authority can sign the new leaf from another of its intermediates, and a production re-order did. The order also places its dns-01 challenge records in the node's zone and takes them out again, and each change moves the zone's SOA serial forward, so expect a higher serial after an obtain.

Both --domain and --contact are required; --domain repeats, or takes a comma-set. ⚠ Take a comma-set only for names that genuinely belong on one credential. Certificate Transparency publishes the name set permanently, so packing several of your domains into one certificate publishes that you hold them all, and nothing takes it back. One certificate per registrable domain.

Like the other owner verbs it takes a pinned node through --node or VALIS_NODE, and it stays on staging unless the node's acme.production setting is true. When you cannot use the route from your machine (the owner port closed, the pin or the device key lost, or the node not answering on the owner port), run it on the node's host as the break-glass route, inside the node's namespace with --keyfile and --endpoint (see the break-glass route):

sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
  /opt/valis/bin/valis obtain --domain example.org --contact hostmaster@example.org \
  --keyfile /var/lib/valis/valis/keyfile \
  --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)"

A first-obtain can also be driven remotely by the authenticated owner over the /acme/ctl 9P door: obtain <domain> <contact> starts the dns-01 order on a background thread (single-flight: a second obtain while one runs is refused, since every attempt burns CA rate-limit budget), and status reports idle/running plus the last completed outcome. The door threads no CA selection of its own; the staging-unless-opted-in default above applies unchanged.

Reading back what a node holds. I added valis cert list so you can see which certificates a node holds, and whether its edge serves each one, without a shell on its host. Name the node as you do for every owner verb:

valis --node NODE cert list

The verb changes nothing on the node. It prints one line per certificate the node holds, sorted by the name each is filed under, with five fields separated by tabs:

1. the name the certificate is filed under;
2. its not-after instant;
3. its next renewal;
4. whether the node's :443 edge serves it: served when the edge hands it out for every name it carries, partial for only some of them, not-served for none, no-edge when the node has no edge listening, and unconfirmed when the node could not read what its edge serves;
5. the DNS names it carries, joined by commas.

Both instants are whole numbers in the same encoding as the next-renewal line of an obtain reply, or unknown when the node cannot read them from the certificate. For a node that holds no certificate the verb prints nothing, and no line carries key material. Only the node's owner can read the list: a key the node has not enrolled meets an empty view and is refused before the list is read, as with every owner verb. On the node's host it runs by the break-glass route, as obtain does above.

ubik's certificate panel reads the same list, and orders a certificate through the same door valis obtain writes. On a node that predates cert list, the panel says that the node does not list certificates and still offers the order.

The owner-keyed verbs (zone, apart from load, secondary --offline and delegation; obtain; publish; publisher; restart; key; and config against a running node) reach the node's owner control plane. You run them from your own machine and name the node:

valis --node NODE key list
valis --node NODE config get edge.served-ports
valis --node NODE zone export --origin example.org

That is the normal route, and it needs three things in place: the node pinned on your machine, a device key on your machine that the node has enrolled, and the node's owner port open. From another machine below shows how to set up all three. The client dials the address you pinned and refuses a responder that cannot prove the pinned DID before your key or any request reaches it. The node's answers print as they do on the host.

A key the node has not enrolled. The node still admits the session, but only to an empty view, in which nothing manages the node. Every owner verb reads that view before it sends a request, refuses with exit 2, and says that the node gave the key no owner view: the key is not enrolled on that node, or was retired, and valis key list on the node's host lists the keys it has enrolled. Nothing on the node changes.

The host route stays for when you cannot use the route from your machine: a shell on the node's host, and the verb run inside the node's network namespace with the node's own key. The break-glass route gives it and says when to reach for it.

A node has one owner identity, its did:key, and one seed behind it, which never leaves the host. I wanted the owner's other devices to manage a node without a copy of that seed, so the node's factotum holds a keyring of device keys beside the seed. Each is a device's own Ed25519 did:key, enrolled under the node's fixed owner identity. Enrolling or retiring a device key never changes the node's identity and never moves, rewrites, or copies the seed.

What an enrolled key reaches. A session presenting a live enrolled key is admitted to the owner frame: the node's services through their loaded modules, minting grants, signing with the node's own key, and backups. It is the frame an owner client such as ubik reaches over the node's capability system. The session keeps the device's own DID as its principal, so the session listing names the device rather than the owner.

The node's REPL is not in that frame. The owner's total reach is host authority: ssh to the host, and from there the node's REPL. No device key reaches it, and the ssh-reality proof, which mints a grant over the whole namespace, admits only the pinned operator SSH key. Enrol only your own devices. Give another person a grant, or an instance of their own, never a place on your keyring.

What a key carries. Each key records its DID, a label you choose, the key that enrolled it, and when. Retiring it records who retired it and when, and ends it. It has no expiry, so it stays admitted until you retire it. Read the listing from time to time and retire the key of any device you no longer hold.

Who may change the keyring. Only a session holding the node's own key enrols, so enrolment happens on the host. The node's own key or any live enrolled key may retire a key, so a lost device can be cut off from another device you still hold. The node's own key can never be retired, and a retired key cannot be enrolled again while the keyring records its retirement: a device whose key was retired mints a new one and is enrolled under that. Setting a refused keyring aside discards those records (see Healing a keyring the node refused).

A module loads only with two signatures: its publisher's vouch and your grant. You give a grant for one module, or once for a publisher as a standing grant, which covers everything that publisher vouches. You file publishers and grants by writing commands to /cap/admit in your owner session; grant-publisher PUBLISHER-DID mints a standing grant that lasts a century and files it in one step. A grant you mint yourself and file with file-standing-grant ends at its own expiry, which admission checks. Because a standing grant can stand for a century, I made the node keep a record of every change to your trust and ask you to look at each standing grant again from time to time.

Two read-only files sit beside /cap/admit in the owner's /cap, and nowhere else: no grant, bearer name, or delegated token reaches them. Each is rendered when you open it, so everything you read from one open is one state.

/cap/grants

the inventory: one stanza for each grant you hold, then one for each publisher you have filed, each a run of KEY VALUE lines, stanzas separated by a blank line. A standing grant's stanza carries grant (its hash), kind, state (active, withdrawn, backed-out, or revoked), publisher, filed-at, reviewed-at (or never), review (due or ok), last-admission, modules, and one admitted line for each module it admitted. Times are Unix times. No stanza carries the text of a grant or a vouch.

/cap/audit

the grant audit trail, one entry a line, oldest first: UNIX-TIME ACT SUBJECT ACTOR. ACT is one of filed-publisher, filed-vouch, filed-list, filed-owner-grant, cleared-owner-grant, filed-standing-grant, granted-publisher, withdrew, backed-out, revoked, reviewed, and restored. SUBJECT is a grant hash, a designation, or a did:key, and ACTOR is the DID of the session that acted, or local.

On a node in service the trail only grows, and a restore whose backup carries a trail replaces it whole. It records changes to trust, so a refused act, or one that changes nothing, leaves no entry. When an entry cannot be written the act still stands, and its reply ends with a line saying the trail did not record it. A torn final line, left by a crash during an append, is skipped. Any other line that is not an entry makes /cap/audit an error beginning cap audit unreadable: line N. An unreadable or unsafe trail gives cap audit unreadable: and the reason, with no line number. Either way /cap/grants, which takes its filing and review times from the trail, is an error beginning cap grants unreadable. Backups carry the trail (see Backup and restore).

Reviewing a standing grant. An active standing grant is due a review once more than module.standing-grant-review-days days have passed since the later of its filing and its latest review: 90 unless you set it, a whole number from 1 to 3,650 (see the environment seam). An active grant with neither on record is due at once. Write reviewed GRANT-HASH to /cap/admit to stamp it, and read back:

reviewed standing grant <hash> at <unix-time>; the review is advisory and admits nothing

The stamp is the trail's reviewed entry and nothing else, so a review whose entry cannot be written is refused and nothing is stamped. Only an active grant you hold takes one: a withdrawn, backed-out, or revoked grant is refused. The review is advisory: nothing refuses a module under a grant that is due. While any active standing grant is due, the node's status line (systemctl status valis.service) ends by counting them:

; 2 standing grants due a review (90-day interval)

Previewing before you withdraw or back out. Write preview withdraw GRANT-HASH or preview back-out GRANT-HASH and read what the act would do, with nothing changed. The first line is preview ACT HASH: nothing was changed, the second state and the grant's state, and then what the act would do: for a withdrawal, the modules that stay and what a fresh install from that publisher would then need; for a back-out, the modules admitted under the grant, every one refused from then on. When the act would change nothing, one line says so. A back-out preview is refused wherever the back-out itself would be.

Withdrawing and backing out. withdraw-standing-grant GRANT-HASH ends the grant for anything new: it admits nothing more, and the modules it admitted stay, across restarts too. back-out-standing-grant GRANT-HASH withdraws it and revokes its hash, so every module it admitted is refused from then on. Withdrawal is one way, and there is no reinstate: to trust that publisher again, file a new standing grant, which carries a new hash and its own filing time. A publisher holds one active standing grant at a time, so filing a different one while one is active is refused, naming the active grant's hash.

⚠ Where this stands. The command line has no verb for /cap/admit, /cap/grants, or /cap/audit, and ubik does not yet compose any of them; you reach them with a 9P client in your owner session. A back-out refuses the modules it names from then on, but nothing removes them from a running node: they run until a restart, when the boot refuses each by name and comes up serving the rest.

valis is authoritative for the SOA zones it serves on :53. The zone data itself is operator state: a node comes up serving whatever zones are in its operator-state store, and comes up with none on a genesis boot. Loading and maintaining that data is the valis zone verb family: a headless, owner-authenticated client the deploy recipe drives non-interactively, and the operator drives by hand.

How it authenticates. From your own machine you name a pinned node with --node NAME or VALIS_NODE, and each verb presents your enrolled device key and reaches the node's owner-gated management axis through its owner port, as From another machine describes:

valis --node NODE zone record add --origin example.org --owner www --ttl 300 --type A --rdata 192.0.2.10
valis --node NODE zone export --origin example.org
valis --node NODE zone record delete --origin example.org --owner www --type A --rdata 192.0.2.10

An added record appears in the export and is answered over UDP and TCP; a deleted one is gone from both. Only a key the node holds in its keyring is given the management axis, so an absent or wrong key fails closed: the management axis never opens to an anonymous caller, and a key the node has not enrolled is refused with exit 2 and changes nothing.

From the node's host, the break-glass route. When you cannot use the route from your machine (the owner port closed, the pin or the device key lost, or the node not answering on the owner port), or to mint a transfer key for a secondary (see secondary below), run the verb on the node's host. There it reaches the management axis over the resident's loopback fabric, inside the resident's network namespace, at the endpoint the resident wrote at boot, and presents the owner key custody holds in the StateDirectory keyfile. The key is supplied as a path, resolved --keyfile PATH > VALIS_KEYFILE > the StateDirectory keyfile; the key bytes never cross the command line. The break-glass route gives the command that gets it there:

sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
  /opt/valis/bin/valis zone export --origin example.org \
  --keyfile /var/lib/valis/valis/keyfile \
  --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)"

A transfer key is kept under the data root of the process that mints it, and the recipe above keeps root's environment, whose data root is not the node's. To mint one the node can use, name the node's data root as well, so the key lands in the node's custody under /var/lib/valis/valis/tsig/:

sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
  /usr/bin/env XDG_DATA_HOME=/var/lib/valis \
  /opt/valis/bin/valis zone secondary --origin example.org --peer 198.51.100.2 \
  --keyfile /var/lib/valis/valis/keyfile \
  --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)"

Either way, a verb that refuses before anything is sent exits 2: for a key file it will not present, a responder that is not the expected node, or arguments it refuses.

The verbs.

valis zone create --origin <fqdn> [--peer <addr>] [--secondary-ns <name>]
valis zone record add --origin <fqdn> --owner <name> --ttl <s> --type <type> --rdata <value>
valis zone record delete --origin <fqdn> --owner <name> --type <type> --rdata <value>
valis zone import --origin <fqdn> --file <master-file>
valis zone export --origin <fqdn> [--out <file>] [--full]
valis zone delete --origin <fqdn>
valis zone delegation --origin <fqdn> [--wait] [--timeout <s>] [--interval <s>] [--allow-range <client=range,...>]
valis zone secondary --origin <fqdn> --peer <addr> [--notify <ref>] [--key-name <name>] [--master-ip <addr>]
valis zone secondary --origin <fqdn> --peer <addr> --key-name <name> --existing-key

# Straight to operator state, for a node that is not serving yet:
valis zone load --origin <fqdn> --file <master-file> [--migrate]
valis zone secondary --offline --origin <fqdn> --peer <addr> [--notify <ref>] [--key-name <name>]

• create brings a whole domain up in one move: it mints the apex records from the domain template, enrols the secondary when you name a peer, and prints the block you paste at the registrar. Reach for this before reaching for import on a new domain.
• record add and record delete publish or retract one typed record and leave the rest of the zone alone. This is the editing path. An --owner ending in a dot is absolute; without one it is relative to the zone. The master-file text format is a boundary format for the secondary, never the format you edit in.
• delegation asks the parent zone's nameservers whether the delegation has settled, and exits non-zero until it has. It needs no resident, no keyfile and no database, so you can run it from anywhere while you wait on a registrar. --wait polls. It asks nameservers on port 53 and nowhere else. The zones it walks are somebody else's, so a nameserver whose address lies in a private or other special-purpose range is skipped unless net.dial-allow allows that range for the client delegation-probe. --allow-range names the allowance for one run instead, in the same client=range form: a lab whose simulated internet sits in 192.168.140.0/22 passes --allow-range delegation-probe=192.168.140.0/22. The check holds that value to the net.dial-allow rules before it asks any nameserver: a member they refuse stops the run with exit status 2 and an error naming --allow-range, the member and why.
• import loads an RFC-1035 zone master file as the named zone, committing it atomically; a malformed master is refused with a non-zero exit and changes nothing, so a bad file never half-lands. Re-importing an origin replaces its zone (advance the SOA serial).
• export writes the zone's master text (to --out, or standard output). It defaults to the durable, re-importable master: the published records, the faithful thing to archive or re-load. Pass --full for the whole serving set, which also includes any transient turn-up records (e.g. ACME challenge records) present at that moment.
• delete removes the whole zone (apex-SOA removal is whole-zone removal).
• secondary enrols a downstream secondary for a zone: it lands the allowlist row for the address the secondary pulls from, mints a TSIG key, and prints the secret and a BIND snippet to paste on the secondary. Over the owner session the key is minted only after the node has accepted the enrolment, so a refused, unserved, or unreachable node leaves no secret behind. With --offline it is minted only after operator state has recorded the row, so a write that fails leaves the key already in custody under that name as it was. --existing-key mints nothing: it lands the allowlist row for a key already installed on both sides, and prints no secret. Over a pinned node (--node or VALIS_NODE) only --existing-key applies. The minting form and --offline are both refused with exit 2, before any setting is read, anything is minted, or anything is dialled. A key minted on your machine stays in your machine's custody, where the node cannot use it to authenticate a transfer, and --offline writes your machine's operator state, never the node's. To mint a new key, run the verb on the node's host. ⚠ The gap. No door on the node mints a transfer key for an existing zone yet, so a new key for a pinned node is minted only on its host.
• load and secondary –offline are the two routes that do not need a running resident. They write operator state directly, reading no keyfile and no management endpoint, with the connection coming from the node's operator-state.dsn setting (or, when the address carries a password, from VALIS_PG_DSN) and never from the command line. Reach for them on a node that is fresh or recovered and not answering yet. ⚠ --offline is what selects that route. secondary without it drives a running resident over the fabric, exactly like the owner-keyed verbs above, so on a node that is not serving yet it refuses and tells you to add the flag. load takes no such flag and is always direct. Either way secondary records the allowlist row; without --existing-key it also mints the TSIG key and prints the BIND snippet to paste on the secondary. Both are walked through in first boot and operator moves.

A committed change is picked up by the running resident without a restart: the serving side re-reads the store, so the node begins answering the new data authoritatively.

At go-live. After a fresh node is up and healthy (serving :53, restore-proven per the go-public gate above) the deploy recipe imports the node's own zone before the address is cut over: whichever domain that node serves, with its apex SOA, its apex NS, and the ns1 address record. The recipe runs valis zone import as the account that can read the 0600 keyfile, then confirms the node answers the zone over loopback (dig against :53) and that valis zone export round-trips before declaring the node live. Zone master files are operator data staged onto the host, not part of the delivery binary.

Neither of these takes the node down, and neither wants you editing files on the host.

Publishing a page. publish places a publication into /pub on a running node, owner-keyed like the zone verbs. It is an ordinary operator act at any time, not a deploy-time one, and you run it from your own machine and name the node:

valis --node NODE publish --slug notes --file notes.html --content-type text/html

Its whole form is:

valis publish --slug <name> --file <path> --content-type <type>

All three are required. The slug is lower-case letters, digits, and hyphens, and --file names a file on the machine you run the verb on, placed on the node byte for byte. A slug that already exists is revised, not refused, and the node serves the new text at once. With a key the node has not enrolled, the verb is refused with exit 2 and nothing is placed.

⚠ The gap. No verb retracts a publication. A page you publish stays served until you revise it, so publish only what you mean to leave up.

From the node's host, the break-glass route. When you cannot use the route from your machine (the owner port closed, the pin or the device key lost, or the node not answering on the owner port), run publish on the node's host, inside the node's namespace with its keyfile and endpoint (see the break-glass route). The file must then be on the host, readable by the run account:

sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
  /opt/valis/bin/valis publish --slug notes --file /var/lib/valis/notes.html \
  --content-type text/html \
  --keyfile /var/lib/valis/valis/keyfile \
  --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)"

Updating the binary. apply takes a delivery archive that is already on the host, puts it in place, restarts the serving unit, and confirms the node still answers:

valis apply --artifact <path> --confirm-server <addr> --confirm-zone <fqdn>

It transfers nothing, so move the archive onto the host first. Without --confirm-server it reads VALIS_APPLY_CONFIRM_SERVER; without --confirm-zone it reads edge.domain in the configuration under your own account's data root, or VALIS_EDGE_DOMAIN in your shell, and when neither is set, the node's own edge.domain. When yours and the node's name different domains, the apply refuses and names both: that disagreement is exactly the wrong-node case confirmation is there to catch. Pass --confirm-zone to settle it; the flag always wins, since a node may confirm for a zone other than its edge domain. The report names the zone it confirmed and where that zone came from. There is no loopback default: name them or the apply refuses before anything moves. That refusal is the point. Exit 2 means it refused and nothing moved; exit 3 means it moved and could not confirm, which is the case that wants you looking. --dry-run walks it without touching the host.

By default apply places the serving binary alone. --with-resident and --with-steer are the explicit ask for the wider set, so the privileged parts of the delivery never move because you forgot they were in the archive.

An apply leaves the host agent's configuration store as it is, so a node whose owner port was open answers on it again once the unit is back, under the same DID, and you go on managing it from your own machine with the pin you already hold.

module.source-root (seeded from VALIS_MODULE_SOURCE_ROOT) names the directory holding the bytes of every module the node admits. Each module lives in a directory named for the identity of its bytes, written once and never changed, and a new version of a module is a new directory beside the old one. Never edit files under it. Keep it apart from the directory that holds the owner keyfile, and keep it, and every directory above it, unwritable by other users: an install refuses a root that is not.

I made the root a fact you state rather than a place valis picks, because it is where the code a node compiles into itself comes from. It is a boot-site requirement, so it is checked at three points:

• A resident whose configuration names no root refuses to boot, and the refusal names the key, and the variable that seeds it at a first boot. With a root named, the resident creates the directory at boot.
• valis apply reads the node's settings, and the unit's environment, before it moves anything. When the root, or any other fact the resident needs to boot, is missing from both, the apply refuses with exit 2 and the node keeps serving what it served. Set it as the run account with valis config set module.source-root ... with the node stopped, or, before the node's first boot, add the line to /etc/valis/valis.env, then apply.
• Provisioning renders the env file from the same requirements, so a provisioned node carries the root.

What a node does with its modules. A module recorded as installed is admitted again from its identity directory at every boot, and its publisher's and owner's signatures are checked again then. A credential that expired after the module was admitted still admits it; a revocation recorded since stops it from loading. While a node serves real names, because it declares an edge domain or is authoritative for zones held on someone's behalf, it refuses to record a module install: a recorded module is stood up at every restart, and nothing yet falls back from a module that fails to stand up. A module that cannot be admitted again at boot does not run: the node logs it by name with the reason, comes up serving everything else, and names it on its status line. A backup carries no module bytes, so a node restored with modules recorded comes up without each one whose identity directory is not back under its module source root. Put those directories back and restart the unit to bring them up.

To install a module into a running node, or to supersede the version it carries, use valis module install (Installing a module as the owner below). Two verbs let you check a module first, on the node's host. Neither binds a port or writes the node's stores, so either may run beside the running node:

• valis module try-install /module/HEX installs the module into a process of its own, through the same gate a running node applies, reading the node's keys and stores, and records nothing. Run it as the run account on the node's data root, so it reads the node's configuration:

  sudo -u valis env XDG_DATA_HOME=/var/lib/valis \
    /opt/valis/bin/valis module try-install /module/<hex>
  

  Exit 0 means the module was admitted and loaded. Exit 2 means you gave the verb no designation or more than one; 3, the argument is not a module designation; 4, no identity directory holds that module; 5, the module was refused before any of its code ran; 6, the module source root or the node state the verb needs is missing or unusable, or something else stopped the verb, such as a scratch directory it could not make; 7, both signatures admitted the module and its load then failed, so some of its code may have run. The verb's last line on standard output begins valis-dry-run: and carries the same JSON verdict try-supersede prints, with phase set to new. That line is what a node reads when it tries an install first: before installing a module, a running node runs this verb in a child process of its own binary and goes on only when the verdict says the module loaded.

• valis module try-supersede /module/OLD /module/NEW loads the old version as a restart would and then the new one as an install would, again in a process of its own. It prints one line beginning valis-dry-run:, carrying a JSON verdict that names what the new version redefined, and exits with the try-install status for the version named in the verdict's phase field. The node's log can write to standard output as well, so take the line with that prefix. A node runs this same check in a child process before it supersedes a running module.

Where a node compiles modules. A node compiles each module beneath module-fasls/ in its data root (/var/lib/valis/module-fasls/ on a packaged node), in a directory named for the module's identity, and compiles a library a module needs that the binary does not carry beneath module-fasls/deps/. Nothing is compiled into the run account's home. A node upgraded from an earlier release keeps that release's compiled output under module-fasls/, filed by each source's full path (.../var/lib/...); nothing reads it any more. To reclaim the space, stop the unit, remove module-fasls/, and start it: the next boot compiles its modules again.

A supersede is always tentative. A change which a running image cannot make in place is refused before any of it is compiled: a changed structure, macro, constant, type, or inline or ftype declaration, a removed file, a changed grouping form, or a change inside a top-level form the comparison compares only whole. The new version must then pass the child dry run and the node's own gate. Even then the old version's code can stay live: a closure that captured it keeps running it, and the scan for leftover code can miss some. So the node records its image as diverged from what a restart would build. Restart the unit when you need the running image to match its record.

The backup-critical set is irreplaceable: the owner Ed25519 seed (0600), the store head, the store blocks the head's root tree reaches, the vouch and revocation stores, the grant audit trail beside them (see Managing standing grants), the owner keyring of enrolled device keys (see Enrolling and retiring an owner device key), the node's configuration (its own settings and every module's, under <data-root>/config/), and the ACME account and leaf keys. Losing the owner seed is losing the node's sovereign identity; there is no re-mint.

Run both verbs as the run account, never as root. The configuration directory is private to the account that owns it, and a backup reads the grant audit trail only when the account running it owns the file, so a root-run backup is refused at whichever of the two it reaches first, before anything is written. A restore run as any account other than the one owning --state-dir (or, for a directory not made yet, the nearest directory above it) is refused before any write, with exit code 2, because the node could not open the files it would land. A restore run as root into a directory that does not exist yet is refused the same way, since whatever it made would belong to root. The same holds for --acme-store-dir.

The valis binary carries the backup and restore verbs. Each seals or opens a single encrypted, self-contained artifact, not a copy of the whole StateDirectory. The passphrase is read interactively (or piped on standard input for an unattended run); it is never a command-line flag, so it never lands in shell history or /proc.

• Back up. Seal the backup-critical set into one artifact:

  sudo -u valis env XDG_DATA_HOME=/var/lib/valis valis --backup --out /path/to/valis-backup.sealed
  # prompts: Backup passphrase:
  

  The artifact is small. It carries the node's configuration as written, so it carries what that configuration names: absolute paths such as the ACME store (acme.store-path, /var/lib/valis/acme/ on a standard install) and the module source root, and the node's own domains and addresses. It carries no database password: the configuration never holds one. A memory-hard key derivation (argon2id) turns the passphrase into the key, and authenticated encryption (ChaChaPoly) seals it: a tampered artifact is rejected rather than silently restored. Treat it as you would a private-key store, and store the artifact and the passphrase separately. An owner seed that is absent, or that is not exactly 32 octets, stops the backup with exit 1 before anything is sealed. A backup can also be driven remotely by the authenticated owner over the /backup/ctl 9P door (backup <passphrase> [name]; status reports the last outcome). The passphrase rides one ctl line over the sealed owner session (never cleartext on the wire, never shell history) and the artifact always lands in the node's backup directory, <data-root>/backups/ (/var/lib/valis/valis/backups/ under the shipped unit), under NAME or, with no name, a timestamped bundle. NAME is a bare file name: a path, a name starting with a dot, or a name already present there is refused with an error destination reply, so no session can aim a sealed copy of the seed elsewhere. To write the artifact to a path of your choosing, run valis --backup --out <path> on the host. A restore is deliberately not served over 9P: it requires the unit down and a pristine state directory, so it stays valis --restore on the host.

• Restore. Open the artifact into a pristine state directory. When the state directory does not exist yet, make it as the run account first; starting the unit once also has systemd make it:

  sudo install -d -o valis -g valis -m 0700 /var/lib/valis
  sudo -u valis valis --restore --in /path/to/valis-backup.sealed --state-dir /var/lib/valis
  # prompts: Restore passphrase:
  

  The restore lands the configuration first, then places the ACME store where that configuration says the node keeps it. The ACME store must lie inside --state-dir: one the configuration places elsewhere is refused before any write, with exit code 2, so a restore never overwrites certificates outside its target. To restore somewhere else, such as a scratch directory for a proof, name where the ACME store lands with --acme-store-dir:

  sudo -u valis mkdir -m 0700 /tmp/restore-proof
  sudo -u valis valis --restore --in /path/to/valis-backup.sealed \
    --state-dir /tmp/restore-proof --acme-store-dir /tmp/restore-proof/acme
  

  The restored configuration still names the original ACME store, so a node you boot from a proof directory looks for its certificates there; the proof checks the keys under --acme-store-dir. A non-pristine target (one that already holds valis state, configuration, or an ACME store where this restore lands one) is refused up front, before any write, with exit code 2; a wrong passphrase or corrupt artifact fails cleanly with a single message and exit code 1. The normal resident boot then condenses the durable namespace from the restored head: restore is the first-deploy path run from a saved head instead of from genesis, and a faithful restore reproduces the origin's durable identity byte-for-byte. Deploy, evacuate, and restore are one condense mechanism, see the contract's deploy/evacuate/restore section.

• The keyring on restore. A restore lands the owner keyring with its retirements, so a key retired before the backup was taken stays retired, and it prints every key it restores, live or retired, for you to review:

  valis: restored owner key did:key:z6Mk... label=laptop live
  

  A restore cannot know of a key retired after its backup was taken. Retire any such key again once the restored node is up. A backup taken before the node kept a keyring restores the seed alone, with a warning saying the node admits only its own key until you enrol your devices again. A binary older than the keyring refuses a backup that carries one, before writing anything. A keyring the backup cannot read whole, or one written for another owner, stops the backup before anything is written, and one a restore cannot land rolls the whole restore back.

• The grant audit trail on restore. Backups carry the trail from container format 6. A restore lands it right after the revocation store and appends one restored entry, so the trail shows when the node came back. A backup in an older format restores with this warning, and the restored trail starts at the restore:

  valis: WARNING: this backup is in container format 5, which cannot carry the grant audit trail. The restored node's trail starts at the restore: when each grant was filed and reviewed before it is not known.
  

  Each active standing grant then has no known filing and no review, so each is due a review at once: review them again (see Managing standing grants). A target that already holds a trail is refused as not pristine unless the backup carries one, which then replaces it whole. When the restored entry cannot be written, the restore stands and a warning beginning the restore stands, but its restored entry was not written to the grant audit trail says so. A backup that cannot read the trail is refused before anything is written.

The restore-proven backup is the go-public gate, and nothing else enforces it. Do not cut a node over to a public address until a restore has been proven: restore the artifact into a scratch state directory and confirm the three properties a good restore demonstrates (the owner axis resolves, the store generation matches the source, the TLS keys load). Those properties, and why a silently-wrong restore is treated as worse than an obvious failure, are set out in backup-and-observability.org.

• Restart is just re-running bring-up: it is idempotent. The single-writer instance fence makes a re-claim of the current generation a no-op, so recovery is safe to repeat.

  systemctl restart valis.service
  

• Restart as the owner with valis restart, when you hold the owner key, or when the node has told you a restart clears threads a retired module left running. The node asks fulcrum to have systemd restart valis.service, so it is the same stop and start as systemctl restart, with the same few seconds without service. Run it from your own machine and name the node:

  valis --node NODE restart
  

  • It waits for the new boot. After it asks, the verb waits, 120 seconds by default (--wait SECONDS sets the bound), until the node answers again over the same pin from a boot identity other than the one it had when asked. It then prints valis: the node is back, boot with the new identity, and exits 0. The owner port keeps its address across the restart, so the wait needs no shell on the host.
  • Every owner session ends. The restart ends every session the node held, including ubik's. Each valis verb opens a session of its own, so the next one you run attaches to the new boot. ubik attaches again on its own once the node is back, checking the pin as it does, and every panel reads the node again. When you restart the node from ubik's restart panel, the panel shows the node's boot identity before and after; Managing a node from ubik covers the panels.
  • Exit statuses. 0: the node came back from a new boot, or you passed --wait 0 and the restart was accepted. 2: the node refused, or the client refused before asking (for example, for a key the node has not enrolled), so nothing was asked. 3: the node could not be reached to ask, or did not come back within the wait; the message says which.
  • A refusal says why. A node running without a supervisor that can restart it, such as a development image or --run, says so and tells you to restart it the way it was started. When fulcrum is too old to serve the restart request, the refusal says it cannot restart the node: restart the service on the host with systemctl restart valis.service.

• Restart as the owner from the node's host, the break-glass route, when you cannot use the route from your machine (the owner port closed, the pin or the device key lost, or the node not answering on the owner port). Run the verb inside the resident's namespace as the run account (see the break-glass route), and confirm from the host:

  systemctl show -p MainPID -p ExecMainStartTimestamp valis.service
  sudo nsenter -t "$(pgrep -o -x valis)" -n -S "$(id -u valis)" -G "$(id -g valis)" \
    /opt/valis/bin/valis restart --wait 0 \
    --keyfile /var/lib/valis/valis/keyfile \
    --endpoint "$(sudo cat /var/lib/valis/valis/mgmt-endpoint)"
  systemctl show -p MainPID -p ExecMainStartTimestamp valis.service
  

  • Pass --wait 0 from inside the namespace. A restart replaces the namespace and draws a new fabric port, so a verb entered into the old namespace, or pinned to the old port with --endpoint, can never see the new boot and would wait out the whole bound. With --wait 0 the verb asks, prints the boot the node answered from, and exits.
  • Confirm on the host. MainPID is fulcrum, which every restart replaces, so a different MainPID and a later ExecMainStartTimestamp after the restart than before it say the node was restarted. Run any owner verb again through a fresh nsenter to see it answering. Where the node's owner port is open and you name it with --endpoint, the address survives the restart and the verb's own wait works, with no root shell at all.

• Stop drives an ordered teardown. On SIGTERM the resident unwinds in reverse bring-up order (long-lived active modules drain first, then edge, then fabric, then listener); fulcrum (the MainPID) removes the sk_lookup link and tears the netns down. KillMode=mixed lets fulcrum drive that ordered pair-teardown rather than systemd SIGTERMing both at once.

  systemctl stop valis.service
  

  • This stop does not depend on the stop notice. systemctl stop signals fulcrum first, and fulcrum ends the run on that request and reaps the resident. The resident gives its stop notice as it does on any orderly stop, but the outcome does not depend on it, so a warning about the notice during this stop needs no action. The same holds for an owner restart, which goes through fulcrum and systemd.
• A signal sent to the resident's own process is a stop the resident begins itself: SIGTERM or SIGINT delivered to the resident directly, for example kill with its PID. The bullets below cover this stop only.
  • The resident tells fulcrum the stop is intended. Before it stops anything, the resident sends fulcrum a stop notice over its control session, and it closes that session last. Once the session ends, fulcrum waits up to 70 seconds for the resident to exit and exits with the resident's status; a resident still running at 70 seconds is killed and fulcrum exits 1. The journal shows the host agent was told this stop is intended at info level.
  • A warning about the notice means the stop can read as a failure. An older fulcrum has no file to take the notice, and the resident warns the host agent serves no stopping file; update fulcrum to clear it. Any other warning about the notice (a request still held the session, the session had ended, or fulcrum refused or did not acknowledge it) means the notice did not land this once. Either way the stop itself carries on, and fulcrum gives the resident only 2 seconds from the session's end: a resident that exits in that time has its status passed on, and one still running makes fulcrum exit 1.
• A superseded writer fails closed. Two instances sharing one operator-state database coordinate only through the single-row write-fence; a superseded writer is fenced out (the fenced-out condition) and writes nothing. This is the split-brain stop that makes a cross-location handover safe. Expect the older instance to fail closed once a successor claims a higher generation.

The default run account is a dedicated static valis:valis. A legacy operator running the resident out of their own account is supported via a drop-in: install legacy-operator.conf.example as /etc/systemd/system/valis.service.d/legacy-operator.conf and set the <operator> / <operator-home> placeholders:

install -d -m 0755 /etc/systemd/system/valis.service.d
install -m 0644 deploy/systemd/valis.service.d/legacy-operator.conf.example \
        /etc/systemd/system/valis.service.d/legacy-operator.conf
# ... edit <operator>/<operator-home>, then ...
systemctl daemon-reload

Overriding User=/=Group and pointing XDG_DATA_HOME (and HOME) at the operator's home keeps valis rooting durable state there; on the first boot after such a move, the resident relocates pre-XDG ~/.valis state cleanly. To fall all the way back to ~/.local/share, clear the inherited StateDirectory (an empty StateDirectory=).

For the architectural why behind each of these, the privilege split, the descriptor handoff, the sandbox directives that ship vs. those deliberately omitted (MemoryDenyWriteExecute, LockPersonality), read the annotated valis.service unit and the host-deployment contract.