Ops - API reference

(assert-netns-materialised node)

Refuse to go on unless NODE has materialised the runtime directory.

Answers the observation on success. Signals NETNS-NOT-MATERIALISED when the node answered and the answer was not the present token, HOST-OBSERVATION-UNAVAILABLE when the observation could not be taken at all, and SEAM-UNBOUND when nothing was positioned to take it.

RETRY-OBSERVATION takes the observation again and tests it again. Nothing here accepts a refusal and continues.

(assert-zone-servable node zone)

Refuse to start NODE unless its operator state holds a servable ZONE.

Answers a plist of what it read on success. Signals ZONE-NOT-SERVABLE when the reads answered and what they answered is not servable, HOST-OBSERVATION-UNAVAILABLE when a read could not be made at all, and SEAM-UNBOUND when nothing was positioned to make one.

RETRY-OBSERVATION takes the reads again and tests them again. Nothing here accepts a refusal and continues.

(netns-materialised-p observation)

Has the node materialised the runtime directory the unit mounts?

True only when OBSERVATION is the present token. Absence and silence both refuse: a probe that could not run at all must never read as a directory that is there, and NIL, the empty string, the absent token and any other text all answer NIL.

(zone-servable-p anchor state record-count)

Does operator state hold a zone this node can actually answer from?

True only when ANCHOR is the zone anchor kind, STATE is the primary cutover state, and RECORD-COUNT reads whole as a count of at least one. Each argument is the text a read answered, so an empty database reaches this with three empty strings and is refused by the predicate rather than by a case ahead of it.

The effect that reads one scalar out of a node's operator state.

Bound to a function of two arguments, the node designator and the statement to run there, answering the raw scalar text, or signalling when the read could not be made at all.

The default is unbound rather than local on purpose: this verb is normally driven from a host that is NOT the node, so a local default would take its reading from the deploy host and pass while the node was broken. Binding the local host is LOCAL-RUNNER, an act a caller performs deliberately.

One seam, one named effect, raw output. It answers one statement per call rather than assembling a reading, so what it read and where it read it stay the same question.

The effect that answers whether a node has materialised its runtime directory.

Bound to a function of one argument, the node designator, answering the raw text the probe printed on that node, or signalling when it could not run there.

The default is unbound rather than local on purpose: this verb is normally driven from a host that is NOT the node, so a local default would take its reading from the deploy host and pass while the node was broken. Binding the local host is LOCAL-RUNNER, an act a caller performs deliberately.

One seam, one named effect, raw output. It must never compose its answer from a second source, because a rebound seam moves only one of them.

The word a node says when the runtime directory the unit mounts is not there.

Named rather than assumed: a probe that answers this said something, and a probe that could not run said nothing at all. The guard treats those as two different events and needs both words to do it.

The word a node says when the runtime directory the unit mounts is there.

Byte-identical to the token the deploy recipe has always used, so a person reading a transcript sees the same word before and after this verb replaced it.

(condense-onto-host node zone &key report-facts)

Stage ZONE onto NODE, assert both preconditions, start the resident, report.

In this order and no other: the zone reaches operator state, operator state is asserted to hold something answerable, the runtime directory the unit mounts is asserted to be there, and only then does the unit start. A refusal at any step propagates and every step after it is never reached.

Answers a report plist naming the node and zone, what the stager answered, the reading each guard took, and what the starter said, with REPORT-FACTS appended verbatim so a caller's own values come back unchanged. This verb's keys are written first, so a fact sharing one of their names does not displace a reading this verb took.

Signals ZONE-NOT-SERVABLE or NETNS-NOT-MATERIALISED when a guard refuses, HOST-OBSERVATION-UNAVAILABLE when a guard's observation could not be taken, SEAM-UNBOUND when either effect has nothing bound to it, and RESIDENT-NOT-ACTIVE when the unit was started and did not come up. Nothing here catches a refusal: only a process boundary turns one into a status.

The effect that starts the resident on a node and waits for it to be active.

Bound to a function of one argument, the node designator, answering a plist. :ACTIVE decides: a true value means the unit reached active, and anything else is refused. :JOURNAL names where the starter captured the unit's log when it captured one, which is the first thing anybody asks for.

A starter that cannot say it reached active has not said it, so a bare true value refuses along with everything else. The alternative is a verb that reports a running node because its starter answered something shaped like success.

Unbound by default, for the same reason the stager is.

The effect that puts a zone into a node's operator state.

Bound to a function of two arguments, the node designator and the zone, answering whatever it wants carried into the report and signalling when the staging did not happen.

Unbound by default. Reaching a machine is an act, never an omission: this verb is normally driven from a host that is not the node, so a seam that quietly acted locally would stage a zone on the deploy host and report success.

One seam, one named effect. It must never compose its answer from a second source, because a rebound seam moves only one of them and the half that stays behind reports on whichever host the Lisp is running on.

Signalled when the observation a guard needs could not be taken.

NODE is the host the attempt was aimed at, COMMAND is what it tried to run there, and EXIT-CODE is the status it saw when the failure reported one. DETAIL carries the underlying condition.

This is deliberately not a subtype of either guard's refusal. A probe nobody could run must not read as a directory that is absent any more than as one that is present, and a guard that answered either way from an unreachable host would be reporting a verdict it never earned.

Signalled when a host does not meet every clause of the contract.

HOST is what was graded, REPORT is the whole reading with one line per registered clause, and the two name lists say which clauses were unmet and which could not be observed at all.

The whole report travels rather than the first failure, because the alternative is an operator fixing one thing, running again, and meeting the next: six round trips to a host is how an afternoon goes.

A clause that could not be observed refuses alongside one that is unmet, and is counted apart from it. A host that would not answer and a host that is missing something ask for different next moves, but neither of them is a host that is ready.

Signalled when the node has not materialised the runtime directory.

NODE is the host observed and OBSERVATION is exactly what the probe answered, so a person reading the refusal sees the word the node said rather than a summary of it.

The unit mounts /run/netns before its command runs. /run is a tmpfs, so installing the rule that creates that directory does nothing until the rule is applied or the node reboots. A run that installs the rule and starts the unit without applying it fails once, at namespace setup, and then works on every boot afterwards. A failure that cannot be reproduced the next morning is the one nobody ever gets to the bottom of.

Root of every way a node start guard can refuse.

DETAIL carries the underlying condition or a short statement of what was seen, never a message assembled for printing, because a caller that can dispatch on a condition should not have to parse a string to find one.

A caller that only needs to know that bring-up refused handles this one class. Without it every such caller grows a typecase over the subclasses and every one of them falls out of step the day a fifth refusal is added.

Signalled when the host answered and what it answered is not a network.

NODE and INTERFACE name what was asked about. MISSING names which of the four things could not be established, as one of :INTERFACE-NAME, :ADDRESS, :DEFAULT-ROUTE or :GATEWAY-CONFIRMATION, so a caller dispatches on the keyword rather than reading the sentence. GATEWAY carries the address that was found and not confirmed, because that is the one an operator goes and looks at.

⛔ A gateway present in a routing table is not a gateway that answered, and this refusal is where the two are kept apart. A configured gateway nothing has heard from produces a node that comes up, passes every check it makes of itself, and reaches nothing.

Never signalled for a probe that could not be run. That is HOST-OBSERVATION-UNAVAILABLE, and the distinction is the whole point: a question nobody could ask is not an answer of no, and merging them sends an operator to reconfigure a host that is fine.

Signalled when the unit was started and did not reach active.

NODE is the host it was started on, REPORT is whatever the starter answered, carried whole rather than summarised, and JOURNAL names where the starter captured the unit's log when it captured one.

The journal is part of the refusal rather than a line in a transcript because a resident that will not boot blocks everything after it, and the first question is always where its log went.

Signalled when the seam a guard observes through holds nothing.

SEAM names which one, so the refusal tells the caller what to bind rather than that something is missing.

Distinct from a failed observation because nothing was attempted. A caller that could not tell them apart would retry a binding that cannot answer, and a deployment driver whose binding failed to take effect would look exactly like a node that was briefly unreachable.

Signalled when a zone master body names no serial to substitute.

TOKEN is the placeholder that was looked for and SOURCE names where the body came from, which is empty when the body was handed over directly rather than read.

The refusal fires before anything is written anywhere. A master file carrying a serial of its own loads exactly once, because the import will not accept a serial older than the one already stored, and the second run fails against a file nobody has touched since. Refusing at render time is what turns that into a sentence an operator reads now instead of a puzzle next month.

Signalled when the file a zone body was to be read from cannot be read.

SOURCE is the path as the caller wrote it, because the operator who mistyped it in the site configuration is looking for what they typed. DETAIL carries the underlying condition.

Kept apart from the missing-token refusal on purpose: a path that is not there and a file written the wrong way ask for two different corrections, and a caller that could not tell them apart would send an operator to edit a file that does not exist.

Signalled when operator state holds no zone the node can answer from.

NODE, ZONE, ANCHOR, STATE and RECORD-COUNT are what the reads saw, quoted rather than interpreted, so the refusal can be compared against the database by hand.

This is the worst-shaped failure available on a node, which is why it refuses rather than warns. A resident started before its zone reaches active, passes every liveness check, logs nothing wrong, and answers nothing. Every surface reports success, so the fault surfaces from the far end of a query somebody else made, days later.

(host-observation-unavailable-command condition)

Undocumented: this exported symbol needs a docstring.

(host-observation-unavailable-exit-code condition)

Undocumented: this exported symbol needs a docstring.

(host-observation-unavailable-node condition)

Undocumented: this exported symbol needs a docstring.

(host-readiness-unmet-clauses condition)

Undocumented: this exported symbol needs a docstring.

(host-readiness-unmet-host condition)

Undocumented: this exported symbol needs a docstring.

(host-readiness-unmet-report condition)

Undocumented: this exported symbol needs a docstring.

(host-readiness-unmet-unobservable condition)

Undocumented: this exported symbol needs a docstring.

(netns-not-materialised-node condition)

Undocumented: this exported symbol needs a docstring.

(netns-not-materialised-observation condition)

Undocumented: this exported symbol needs a docstring.

(ops-refusal-detail condition)

Undocumented: this exported symbol needs a docstring.

(public-network-underivable-gateway condition)

Undocumented: this exported symbol needs a docstring.

(public-network-underivable-interface condition)

Undocumented: this exported symbol needs a docstring.

(public-network-underivable-missing condition)

Undocumented: this exported symbol needs a docstring.

(public-network-underivable-node condition)

Undocumented: this exported symbol needs a docstring.

(public-network-underivable-observation condition)

Undocumented: this exported symbol needs a docstring.

(resident-not-active-journal condition)

Undocumented: this exported symbol needs a docstring.

(resident-not-active-node condition)

Undocumented: this exported symbol needs a docstring.

(resident-not-active-report condition)

Undocumented: this exported symbol needs a docstring.

(seam-unbound-seam condition)

Undocumented: this exported symbol needs a docstring.

(zone-master-serial-token-absent-source condition)

Undocumented: this exported symbol needs a docstring.

(zone-master-serial-token-absent-token condition)

Undocumented: this exported symbol needs a docstring.

(zone-master-unreadable-source condition)

Undocumented: this exported symbol needs a docstring.

(zone-not-servable-anchor condition)

Undocumented: this exported symbol needs a docstring.

(zone-not-servable-node condition)

Undocumented: this exported symbol needs a docstring.

(zone-not-servable-record-count condition)

Undocumented: this exported symbol needs a docstring.

(zone-not-servable-state condition)

Undocumented: this exported symbol needs a docstring.

(zone-not-servable-zone condition)

Undocumented: this exported symbol needs a docstring.

One clause of the host-deployment contract, with the way to observe it.

NAME is a keyword naming the clause. WHAT is the clause in the contract's own words, so a refusal tells an operator what is missing and why it matters rather than naming a keyword they then have to go and look up. PROBE is the command text to run on the host, or the name of a function of the site plist answering that text. READING names a pure function of the probe's output and exit status, answering one of :SATISFIED, :UNMET or :UNKNOWN.

PROBE and READING are held as names rather than as function objects so that redefining either takes effect without re-registering the entry.

Signalled when the registry itself is wrong.

⛔ Deliberately NOT part of the OPS-REFUSAL hierarchy, and the distinction is the point. A caller dispatching on that root is asking what a host is missing; a clause declared without a reading, or a reading answering something no report can use, is a fault in this file. Merging the two would let a broken registry read as a broken host, which sends somebody to a machine that is fine.

Signalled when a host does not meet every clause of the contract.

HOST is what was graded, REPORT is the whole reading with one line per registered clause, and the two name lists say which clauses were unmet and which could not be observed at all.

The whole report travels rather than the first failure, because the alternative is an operator fixing one thing, running again, and meeting the next: six round trips to a host is how an afternoon goes.

A clause that could not be observed refuses alongside one that is unmet, and is counted apart from it. A host that would not answer and a host that is missing something ask for different next moves, but neither of them is a host that is ready.

(host-contract-fault-clause condition)

Undocumented: this exported symbol needs a docstring.

(host-contract-fault-detail condition)

Undocumented: this exported symbol needs a docstring.

(assess-host host &key (run-account +default-run-account+) (state-directory +default-state-directory+) (binary-path +default-binary-path+) (operator-state-socket-directory +default-operator-state-socket-directory+))

Put HOST to the host-deployment contract and answer, clause by clause, what it satisfies.

Answers a report plist on success: :HOST, :LINES (one per registered clause, in the document's order, each naming the clause, its verdict, its words and what the host actually said), :CHECKED, :SATISFIED, :UNMET and :UNKNOWN.

Signals HOST-READINESS-UNMET when any clause is unmet or unknown, carrying the whole report so a caller prints every line rather than the first failure. Fixing one thing at a time across six round trips to a host is how an afternoon goes.

Signals SEAM-UNBOUND when nothing is positioned to reach the host, because a local fallback would put the machine driving the deploy to the contract and pass while the target was missing everything.

A clause that could not be observed refuses along with one that is unmet. They are counted and named separately, so an operator can tell a host that is missing something from a host that would not answer, but neither of them is a host that is ready.

⚠ This observes. It corrects nothing, and it must not grow the ability to.

(host-prerequisite-name instance)

Undocumented: this exported symbol needs a docstring.

(host-prerequisite-named name)

The registered clause called NAME, or an error naming it.

A caller that reaches for a clause by name and finds nothing has a fault in the source rather than a host that is missing something, so this is loud.

(host-prerequisite-p object)

Undocumented: this exported symbol needs a docstring.

(host-prerequisite-probe instance)

Undocumented: this exported symbol needs a docstring.

(host-prerequisite-reading instance)

Undocumented: this exported symbol needs a docstring.

(host-prerequisite-what instance)

Undocumented: this exported symbol needs a docstring.

(host-site &key (run-account +default-run-account+) (state-directory +default-state-directory+) (binary-path +default-binary-path+) (operator-state-socket-directory +default-operator-state-socket-directory+))

The site particulars the contract's clauses are read against, as one plist.

A probe that needs one of these takes the whole plist rather than an argument of its own, so a clause added later that needs a fifth particular changes this function and nothing else.

(probe-command prerequisite site)

The command text PREREQUISITE's probe runs on a host, for SITE.

(define-host-prerequisite name &key what probe reading)

Declare one clause of the host-deployment contract and how to observe it.

⛔ The three halves cannot be added separately, and that is the entire point. A report holding its own list of clause names drifts from the code the moment somebody adds a clause and edits only one of them, and nothing goes red: the assessment passes, the node takes the binary, and the resident then refuses to boot on a condition the assessment never asked about.

PROBE is either a literal command string or the name of a function of the site plist answering one. READING is the name of a function of two arguments, the probe's output text and its exit status.

Every clause of the host-deployment contract, in the document's order.

⛔ Nothing adds to this list by hand. DEFINE-HOST-PREREQUISITE registers the entry, its probe and its reading from the SAME form, so a clause cannot exist for one of them and not the others. A second list kept in step by hand is the defect this registry exists to make impossible: it drifts silently, and the drift is found by a deploy that has already stranded a host.

The effect that runs one command on a host and answers what it said.

Bound to a function of two arguments, the host designator and the command text, answering (values OUTPUT EXIT-CODE): the raw text the command printed there and the status it exited with.

The default is unbound rather than local on purpose. This verb is normally driven from a machine that is NOT the host being graded, so a local default would put the deploy host to the contract and pass while the target was missing everything. Binding the local host is LOCAL-RUNNER, an act a caller performs deliberately.

One seam, one named effect, raw output. It must never compose its answer from a second source, because a rebound seam moves only one of them.

Where the versioned delivery tarball unpacks the serving-capable binary.

The directory Postgres puts its local UNIX-domain socket in on Debian.

The dedicated unprivileged account the contract defaults the resident to.

The durable-state directory the unit's StateDirectory setting produces.

Signalled when the observation a guard needs could not be taken.

NODE is the host the attempt was aimed at, COMMAND is what it tried to run there, and EXIT-CODE is the status it saw when the failure reported one. DETAIL carries the underlying condition.

This is deliberately not a subtype of either guard's refusal. A probe nobody could run must not read as a directory that is absent any more than as one that is present, and a guard that answered either way from an unreachable host would be reporting a verdict it never earned.

(bounded-argv argv deadline)

ARGV under DEADLINE, as the argv to run.

The bound is a prefix rather than a wrapper around the whole thing as one word, which keeps every element of ARGV a separate argument.

(command-text command)

COMMAND rendered for a person to read in a refusal.

For display only. Nothing built from this is ever executed: an argv rendered as one line is exactly the shape this file exists to avoid running.

(local-probe node command &key (deadline +local-probe-deadline+))

Run COMMAND on this host and answer what it said.

Answers (values OUTPUT EXIT-CODE STDERR). The first two are the seam's call convention and are what every reading destructures; the error text follows them where nothing can mistake it for a status.

NODE must designate this host. A node designator naming somewhere else signals HOST-OBSERVATION-UNAVAILABLE and runs nothing, because a probe that answered anyway would be grading this machine under another machine's name.

COMMAND is an argv list or command text; see PROBE-ARGV for which becomes what.

A command that could not be started answers no output at all and a status the readings call unreached, so the clause it was taken for reads :UNKNOWN rather than :UNMET. A command that ran and exited non-zero is an ordinary observation and is answered as one: the status is the reading's to interpret.

(probe-argv node command)

COMMAND as the argv this host will execute.

A LIST is the argv itself, element for element. Whatever an element holds reaches the program as one argument, so a value carrying shell syntax stays data.

A STRING is the seam's own convention, and it is placed as ONE argument after the shell's -c rather than joined with anything. The text is shell because its author wrote shell, and quoting what was interpolated into it is that author's act, made where the value's shape is known.

Signals HOST-OBSERVATION-UNAVAILABLE for anything else, before running a thing.

(this-host-p node)

Does NODE designate the host this process is running on?

True for the local names above, for the machine's own name, and for a bare label matching the label of that name. Everything else is refused, the qualified form of a bare local name included: a host that does not know its own domain cannot confirm that it is the one somebody named in one, and two hosts called ghost in different domains are two hosts. Answering anyway would grade this machine under another machine's name, which is the failure the seam exists to prevent.

The status the deadline tool reports when the command outlived its deadline.

The readings on the other side of the seam treat this as a probe that did not reach the host, which is what a command that never finished amounts to.

The names that designate the host a process is running on, whatever it is.

An operator driving this from the node itself writes one of these or the node's own name. Anything else names a machine, and this probe cannot reach one.

Seconds a probe may take before the deadline tool ends it.

Every clause of the host contract is a stat, an id lookup or a file read, so a probe that has not answered in half a minute is not going to. The bound exists so a wedged command cannot hold an assessment open indefinitely.

The deadline tool's own statuses for a command that never started.

125 is the tool failing, 126 a program that was found and could not be invoked, 127 a program that was not found. A command is free to exit any of these of its own accord, and this reading resolves that ambiguity towards never ran, which is the direction that refuses rather than the direction that reports a healthy host.

The status answered when the probe could not be started at all.

The same number ssh reports for a host it could not connect to, and for the same reason: nothing ran, so nothing was read. The readings recognise it, so a caller gets :UNKNOWN rather than a verdict nobody earned.

Signalled when the host answered and what it answered is not a network.

NODE and INTERFACE name what was asked about. MISSING names which of the four things could not be established, as one of :INTERFACE-NAME, :ADDRESS, :DEFAULT-ROUTE or :GATEWAY-CONFIRMATION, so a caller dispatches on the keyword rather than reading the sentence. GATEWAY carries the address that was found and not confirmed, because that is the one an operator goes and looks at.

⛔ A gateway present in a routing table is not a gateway that answered, and this refusal is where the two are kept apart. A configured gateway nothing has heard from produces a node that comes up, passes every check it makes of itself, and reaches nothing.

Never signalled for a probe that could not be run. That is HOST-OBSERVATION-UNAVAILABLE, and the distinction is the whole point: a question nobody could ask is not an answer of no, and merging them sends an operator to reconfigure a host that is fine.

(default-route-command interface)

The command that asks the host where it sends what it cannot place.

⚠ Deliberately NOT filtered by device, and INTERFACE is taken only so that every command in this file is built the same way. Filtering removes the `dev` field from the output, which is the one field the reading checks.

(derive-public-network node interface)

Derive INTERFACE's address, prefix and gateway from NODE itself.

Answers a plist on success: :INTERFACE, :ADDRESS, :PREFIX-LENGTH, :CIDR, :GATEWAY and :CONFIRMED. :CIDR is composed from the address and the prefix rather than carried alongside them, so the two cannot come to disagree.

Signals PUBLIC-NETWORK-UNDERIVABLE when the host answered and what it answered is not a network: no address on the interface, no default route on it, or a gateway that has not been heard from. The refusal names which of those it was.

Signals HOST-OBSERVATION-UNAVAILABLE when a probe could not be run at all, and SEAM-UNBOUND when nothing is positioned to run one. Neither of those is a statement about the host's network: a question nobody could ask is not an answer of no.

RETRY-OBSERVATION takes the observations again and derives again, and it is the same restart the bring-up guards offer, so one handler serves every ops observation. ⛔ There is no restart that accepts an unconfirmed gateway. That is the one refusal this verb exists to make.

⚠ This observes. It configures nothing, and it must not grow the ability to.

(gateway-confirmed-p neigh-output gateway)

Did GATEWAY answer this host, according to NEIGH-OUTPUT?

True only for an entry naming GATEWAY that carries a learned link-layer address in a state meaning a reply arrived. An absent entry, empty output, a permanent entry nobody heard from, an outstanding question and a failed one all answer NIL.

⛔ Listed in a routing table is not confirmed, and this is the reading that keeps the two apart. A gateway that is configured and does not answer produces a node that comes up, passes every check it makes of itself, and reaches nothing.

(interface-address-command interface)

The command that asks INTERFACE what address and prefix it carries.

Filtered by device, which is safe here: this listing still names the interface on every line it prints, so the reading can check that it is looking at the right one.

(neighbour-command interface)

The command that asks what INTERFACE has actually heard from.

Filtered by device on purpose: the kernel then answers only for the interface in question, so an entry it returns is one this host learned over that link.

(parse-default-gateway output interface)

The gateway INTERFACE's default route points at, read from OUTPUT, or NIL.

NIL for empty output, for a routing table carrying no default at all, and for a default route that belongs to another interface.

⚠ The line must NAME the interface. A listing filtered by device prints no `dev` field, so its output is refused here rather than assumed to be about the right one: the probe that feeds this reading does not filter, for exactly that reason.

(parse-interface-address output interface)

The address and prefix length INTERFACE carries, read from OUTPUT.

Answers (values ADDRESS PREFIX-LENGTH) for the first line of OUTPUT that is about INTERFACE and carries an IPv4 address, and (values NIL NIL) otherwise: for empty output, for an interface holding no IPv4 address, and for output naming a different interface.

⭐ That last case is not caution for its own sake. A reading that ignores which interface it is looking at will answer happily about the management NIC, and the whole point of this verb is the other one.

(plain-interface-name-p interface)

Is INTERFACE a plain interface name, safe to place in a command?

The name reaches the host inside a command string, so a name carrying a quote or a semicolon would run something other than the observation this verb claims to have taken. Refusing the shape up front is cheaper than quoting and leaves nothing to get wrong later: a device name has no legitimate reason to hold a character this rejects.

The neighbour states that mean the gateway answered this host.

Each of them stands over a link-layer address the kernel learned from a reply. STALE and DELAY say the entry has aged past its confidence window, which is a statement about when the reply arrived rather than about whether one did.

The status a bounded exec reports when the command outlived its deadline.

The status ssh reports when it could not connect or authenticate.

Read as unreached even though a remote command may exit 255 of its own accord. The ambiguity resolves towards could not run, which refuses rather than reporting a network nobody observed.

(render-zone-master master-text serial)

MASTER-TEXT with every serial token replaced by SERIAL.

SERIAL is printed as a caller would write it, so an integer and its digits render the same way. Answers the rendered body and nothing else: no file is written and no host is reached.

Signals ZONE-MASTER-SERIAL-TOKEN-ABSENT when MASTER-TEXT carries no token. Nothing is returned in that case and nothing has moved anywhere, which is the point of checking before the caller starts a transfer.

(zone-master-from-file path serial)

The body of the master file at PATH, rendered for SERIAL.

Signals ZONE-MASTER-UNREADABLE when PATH cannot be read, and ZONE-MASTER-SERIAL-TOKEN-ABSENT when it can be read and carries no serial token. Those are separate refusals because a mistyped path and a file written the wrong way ask the operator for two different corrections.

The placeholder a site master file puts where its SOA serial goes.

Byte-identical to what the site's files already carry, so a file written before this verb existed renders through it unchanged. Renaming it would refuse every master file on disk, which is why it is named here once and read everywhere else.