Topology

A role bound to an actor (actor = "M.A" in [roles], D23): one actor per offer, spawned by [mk] (the generated fn () -> spawn(M.A, env)) and handed to [open] (the generated <P>_Run.offer_hosted_<R> call whose start, deliver and cancel callbacks forward to it). An actor spawned for an offer that could not be opened is kept for the next attempt rather than spawned again. Supervision re-offers the role when its actor dies. When the offer closes (placement moved the role, its capacity changed, or its protocol did: reoffer), the actor keeps serving the sessions it hosts and is stopped once they have all ended (6.1: a protocol change spawns a new hosting actor; the old one drains and exits).

[base] (the roles this build contains, as the generated main placed them) under [desired]: a pinned role is left as the build placed it; a role the digest no longer serves here is PlaceNowhere; otherwise its placement and (unless fixed by the build, capacity 0) its capacity come from the digest.

Stop placing and close every offer of [node] (running sessions finish): what SIGTERM does under drain_on_signal. Returns at once.

The node's configuration from the environment (ClusterNode.config_from_env), with defaults for a lone local run: MARCH_NODE_NAME defaults to local-1 and MARCH_NODE_PORT to 7946.

Offer the role on [n] of the eligible live nodes, by rendezvous hashing (place = { count = n }).

How many nodes [p] places on (n for a count = n role; 0 for an unranked one).

count(n) among the nodes carrying [label] (place = { on = label, count = n }).

What the digest [text] asks of this process: for each role one of [pools] serves, its placement and capacity (a role no such pool serves is absent); the drain deadlines; and an error for text that is not a version-1 digest.

Drain [node] now, as SIGTERM does under drain_on_signal.

On SIGTERM or SIGINT: close every offer of [node] (new invitations are refused), drain every code epoch the process runs (running sessions end at their next loop boundary, D27, and actors take the epoch drain's deadlines), then exit 0 once no session is running. At [soft_ms] a drain still waiting is reported; at [hard_ms] the process exits 1, naming how many sessions it cut. A second signal escapes the watcher and stops the process at once.

Whether this node may take part in [p] at all: it carries the label, if any.

Offer the role on every node that serves it (no place in the topology).

Run the pool hook [name] ([f]), which must return promptly: offers open only after every hook has returned. A watchdog reports a hook still running after MARCH_HOOK_TIMEOUT_MS (default 10000) and exits the process with status 1: offering nothing would be worse than failing loudly. Long-lived work belongs in a task or actor the hook spawns.

Labels from a comma-separated list: `\

The name an eligible node registers for a ranked role.

Whether this node may OPEN ranked role [p] it now ranks for (it is not offering it yet), at [now]: the settle rule its peers apply to it, applied by the node itself. A node that started at [started] and has not yet merged a peer's registry ([synced] false) knows no other node's marker, so it opens nothing ranked until it has, or until [settle_ms] have passed (seeds unreachable: a lone node still takes its roles). A node that a peer last showed as rejoining at [rejoined_at] (ClusterNode.rejoined_at) is not counted by those peers for [settle_ms], so for that long it opens the role only if the [others] other non-dead nodes marked eligible cannot fill its count without it. Never stops a node keeping an offer it holds.

This node's labels: MARCH_NODE_LABELS, comma-separated (set by the launcher from the overlay).

This node's name as the membership and the control plane know it.

actor_role, offered at [capacity] sessions: [open] takes the actor and the capacity (the generated fn (topology_a, topology_cap) -> <P>_Run.offer_hosted_<R>(io, node, topology_cap, topology_a, ...)).

A role bound to a function, offered at [capacity] sessions: [open] is the generated fn topology_cap -> <P>_Run.offer_<R>(io, node, topology_cap, ...). A reload that changes the role's capacity reopens its offer at the new size.

The actor answering invitations for [role_name]'s open offer on [node], if one is open.

The roles [node] offers right now, by name, sorted.

Does [node] offer [role_name] right now? (For a count = 1 role: is this node the one that serves it.)

Offer the role on the nodes whose MARCH_NODE_LABELS include [label] (place = { on = label }).

[r], pinned: a pushed topology leaves its placement and capacity as the build set them (apply_desired). For roles the generated main adds itself and a topology digest cannot name, such as the control plane's Ctl.Control (placed from [control]): without the pin, every re-read of the topology (a signed push, SIGHUP, or a restart onto a verified copy) would place it nowhere, and the cluster would lose its leader.

Open the offers the topology places on [node], one per entry of [roles], and keep them placed: a task re-evaluates every MARCH_PLACEMENT_TICK_MS (default 200 ms) against the current membership, opening a role this node now ranks for and closing (draining) one it no longer does. Membership events are recorded as they arrive; a node that rejoins counts after the settling period. This node applies that period to itself too (may_open): it opens no ranked role before its first registry sync (bounded by MARCH_PLACEMENT_SETTLE_MS), and while a peer counts it as rejoined it leaves a ranked role to the nodes already offering it. Returns once the first evaluation has opened the offers it may open now (a ranked one held back opens on a later tick).

A digest's place object as a placement: null is everywhere (D18), { on }, { count }, or both.

A placement as the topology writes it, for reports.

[ids] ranked for [role_name], best first (highest score; ties by id).

Whether [p] ranks nodes (and so needs the eligible set).

Re-evaluate [node]'s placement now, as the next tick would. For tests that drive membership through a fake dictionary and should not wait for a tick (run them with a long MARCH_PLACEMENT_TICK_MS).

Re-read the topology now, as SIGHUP does: the signature-checked copy the reload server keeps (MARCH_TOPOLOGY_VERIFIED_FILE) when there is one, else MARCH_TOPOLOGY_FILE, is parsed and the roles this build contains take their placement and capacity from it; the next evaluation (run at once) opens and drains offers to match. A file that cannot be read or parsed changes nothing and is reported.

Re-open each of [node]'s open offers with the code now running (distributed-deploys build step 9): an offer whose protocol fingerprint changed is opened again under the new one (a hosted role with a fresh actor) and the old offer is closed; its sessions finish on the old version and a hosting actor exits once they have (6.1). An offer whose fingerprint did not change stays as it is (the new offer's name is already taken). The placement loop runs this itself after a deploy; call it directly only from a test.

A role bound to a function (body = "M.f" in [roles]). [open] is the generated <P>_Run.offer_<R>(io, node, capacity, fn (s, caps..., st) -> M.f(env, s, caps..., st)).

The members that currently mark themselves eligible for the ranked role [role_name] (a place = { on = ..., count = n } role), this node included when it is: its candidates, whichever of them ranks first. The control plane finds its standbys and its leader with it. A dead member is left out.

Sessions still running on [node]'s offers, open or draining.

Whether this process runs pool [pool]: MARCH_POOLS (comma-separated) names the pools a process of a shared build runs; unset, it runs every pool the build contains (forge run's one process, D9).

A node's rendezvous score for [role]: every node computes the same one.

A member that rejoined at [rejoined_at] counts again once [settle_ms] have passed.

Report that the node could not start ([why]) and stop the program with status 1. The generated main starts the node itself -- ClusterNode.start(io, Topology.config_from_env()) -- because only ClusterNode may hand out a Cap(ClusterNode.Live).

What this node reports to the reconciler: its name, the digest it applied (sha256, or compiled before any reload), its offers, how many closed offers are still draining, the sessions running on them all, and a conflict line per placed role that cannot be offered because another offer on this node holds its endpoint name.

Stop [node] and everything placed on it: close every offer (running sessions are cut when the node goes), end placement and supervise_offers, then ClusterNode.stop. For a program (a test, say) that ends on its own rather than on a signal.

Re-offer any role whose offer actor, or hosting actor, has died, and keep the calling task (the generated main) alive until the node stops or drains. A process whose main returned would exit, taking its offers with it.

Whether node [me], with [labels], offers [role_name] under [p], given the settled eligible nodes [eligible] (other nodes; [me] is added when it is eligible itself).