Skip to content
SHC Docs

Node selection UX: what the operator has to say, and what the product should decide for them

Status: open design. Not ruled and not built. Every fact below is marked MEASURED (read out of the trees named in Baselines, in this session), INHERITED (measured by a sibling lane and re-stated, not re-verified here), PROPOSED (my recommendation), or RULING-OWED (needs the owner).

Baselines. shc main 0e5621a79, ce main 0796595. Sibling lanes landed a large amount of substrate a few hours before this page was written, so several claims in this lane’s own brief are now stale; where that happens this page says so and gives the current figure.

Scope. This page is the interface layer only: what the operator types, what the product prints back, and what it refuses. The decision function underneath it is not re-designed here; that is docs/proposals/2026-08-11-placement-policy.md, and the rulings it now operates under are docs/decisions/2026-08-11-rebalancer-v1-foundations.md. Where this page and those disagree about the mechanism, they are right. Where they disagree about what the operator sees, this page is the one that looked.

The question this exists to answer, in the owner’s words:

“How does it know what node to run, or am I supposed to explicitly specify that? Keep in mind, we want the UX to be easy for users, but we also want things to (when you add more nodes) at least be balanced.”


  1. Today the operator says nothing and the product decides nothing. The node is “whichever daemon answered the phone”, and it is never printed. MEASURED.
  2. An app can already write down where it may run. Nothing reads it. Both spellings, requires.runtimes: and the legacy top-level runtimes:, are parsed by no Go code in either repo. The owner’s own example, mailcow, carries runtimes: [compose] and it is decorative. MEASURED, §2.
  3. Three documentation sites state that it is enforced. One of them names the refusal code. That code fires on a different condition entirely. MEASURED, §2.3.
  4. Scoring should be the default and --node the override, but the decision must be printed. An automatic placement nobody sees is the same failure mode as no placement at all. PROPOSED, §3.
  5. On swarm, pin when the deployment has bytes; leave it unpinned when it does not. Derived from a signal the render path already computes, not from a blanket policy. PROPOSED with the owner’s ruling owed, §4.
  6. “Add a node and things balance” is not true on either runtime and should never be promised. The honest sentence is “a new node becomes a candidate for the next install; it does not redistribute what is already running.” PROPOSED, §5.

1. What the operator can say today, and what happens

Section titled “1. What the operator can say today, and what happens”
what the operator typeswhere it goeseffect
shc install <app>nonethe stack lands on the daemon that received the API call
shc install <app> --node X / -n XInstallArgs.Node → body["node_id"] (ce modules/app/commands/install.go:140,302)routed to X via makeRoutingStackInstaller; also written to deployment.pinned_node_id
shc install <app> --runtime compose|swarm|podmaninstall.go:193,348overrides the runtime for this stack; empty means the node’s own declared runtime

The --node flag’s entire help text is "target node" (install.go:140). It does not say what happens if you omit it, and omitting it is the case every operator is in.

1.2 ★ The app’s own declaration is inert: MEASURED

Section titled “1.2 ★ The app’s own declaration is inert: MEASURED”

The owner’s question, “apps should be able to specify where they can run, but also what’s preferred… mailcow cannot run on swarm”, has a sharper answer than the brief suggested.

Three apps of 98 declare anything:

appfilespelling
ivatarapps/identity/ivatar/app.yaml:17-18requires:\n runtimes: [compose, swarm]
dependency-trackapps/security/dependency-track/app.yaml:39-40requires:\n runtimes: [compose]
mailcowapps/email/mailcow/app.yaml:13legacy top-level runtimes: [compose]

★ Neither spelling is read by any code, in either repo. There is no yaml:"requires" or yaml:"runtimes" struct tag anywhere in ce. The app manifest struct the detail view parses, appDetailManifest, ce modules/app/detail.go:60-68, has six fields: name, version, description, category, homepage, vars. The only occurrence of the word in a config sense is ce modules/completion/service.go:66, a shell tab-completion word list.

This is not a new discovery; it is a re-confirmed one. A prior audit filed it and marked it open:

docs/reviews/2026-07-02-feature-scan/app-packaging.md:66: “Five app.yaml keys are declared by catalogue apps and parsed by nothing… requires.runtimes/architectures are never checked at install.”; STILL OPEN at HEAD, re-verified here.

docs/app-development/app-definition.md:290-292 explains why the key looks alive: it says the legacy forms are “merged into requires: at load time (get_required_runtimes etc.)”. That is a Python function name. The capability existed in the retired Python CLI and did not survive the Go port; the documentation did.

So the consequence, stated plainly: shc install mailcow on a swarm-runtime node proceeds. Nothing consults the declaration the packager wrote precisely to prevent it.

1.3 ★ And the runtime guard does not catch it either: MEASURED

Section titled “1.3 ★ And the runtime guard does not catch it either: MEASURED”

There are two guards named CheckRuntimeMatchesNode (ce modules/app/runtime_guard.go:135, ce modules/stack/service.go:1018). Both refuse only a cross-engine pin: podman vs docker-class. The stack one says so in its own header:

“Strict matching blocked legitimate cross-mode pins; swarm↔compose therefore passes freely and any residual error surfaces at deploy time through docker’s own messages.”, ce modules/stack/service.go:998-1000

The reasoning is sound (every SHC node joins swarm at bootstrap for overlay networking, so a compose node can genuinely dispatch docker stack deploy). The problem is that docs/guide/getting-started/concepts.md:100-107 states the opposite as a hard contract:

“shc install <app> --node X --runtime swarm requires X.runtime == "swarm". Otherwise the install fails with X400955RTMPIN. … This is a hard constraint, not a hint.”

MEASURED: X400955RTMPIN fires on (req.Runtime == "podman") != (nodeRuntime == "podman") and on nothing else. A compose/swarm mismatch never reaches it.

Two more doc sites make the same promise about the app declaration:

  • docs/guide/getting-started/concepts.md:89-91: “A stack’s runtime is picked by matching the app’s requires.runtimes against what the target node supports.”
  • docs/app-development/creating-apps.md:394: “requires.runtimes: [swarm] restricts to swarm nodes.”

★ This is the answer to the owner’s question, and it is worse than “not built”: it is documented as built. An app packager reading creating-apps.md will write the key, ship it, and believe the restriction holds.

1.4 So how is the runtime chosen?, MEASURED

Section titled “1.4 So how is the runtime chosen?, MEASURED”

It is a property of the node, not of the app. Each node has exactly one declared runtime, fixed at shc init --runtime … or shc node join --runtime …. shc install --runtime overrides per-install; empty resolves to the receiving node’s row (LocalNodeRuntime, runtime_guard.go:65-76).

The app never participates. Nothing about the app can steer, prefer, or refuse. INHERITED: fabric and swarm runtime are mutually exclusive at shc init with no in-place flip, and both estates are 100% compose with zero swarm stacks, so in production this decision is made exactly once per estate, at init, and never revisited.

At install: nothing. ce modules/app/commands/install.go contains one Fprintf naming any placement-adjacent fact, and it is the restore path (:241, "restoring stack %q from %s"). No node is printed, before or after. There is no --dry-run.

Afterwards: a genuinely good column. ce core/placement owns the rendering and has four cases:

compose -> "compose01"
swarm, pinned -> "swarm01 (pinned)"
swarm, unpinned, seen -> "swarm01, swarm02"
swarm, unpinned, unseen -> "\u2014"

with a header that switches NODE → NODES when any row names a set. That package is the right foundation for everything in §3: the vocabulary “pinned” is already user-visible and already means the right thing. The gap is that it only exists after the fact, on a list page the operator has to know to go look at.


2. (a) The install-time experience, per runtime

Section titled “2. (a) The install-time experience, per runtime”

INHERITED (this lane’s brief, not re-verified; no estate contact): the bitspur overcommit: 128 containers and 191.65 GiB of declared limits on a 30.60 GiB node, beside two nodes at roughly 90% idle. MEASURED is only the mechanism: absent --node, every install lands on the receiving daemon, and nothing prints where that was.

★ The mechanism and the invisibility are one defect, not two. A silent default that is usually right trains the operator to stop checking; by the time it is wrong, checking is not a habit anyone has.

2.2 Compose: score by default, --node overrides, and SAY SO

Section titled “2.2 Compose: score by default, --node overrides, and SAY SO”

PROPOSED. The mechanism is already designed and half-landed: the seam is at ce modules/stack/service.go:425-437, the scorer is shc modules/placement, and the live advisor is on origin/feat/rebalancer-v1-advisor awaiting a ce pin bump. This section adds only the surface.

shc install should print one line, unconditionally, whenever the product chose the node rather than being told it:

$ shc install gitlab
placement node-b (most free memory of 3 candidates; --node overrides)
installing gitlab -> node-b …

and when the operator chose:

$ shc install gitlab --node node-a
placement node-a (you named it)

and when there was nothing to decide: the single-node case the advisor already declines (advisor.go, “ONE CANDIDATE IS NOT A DECISION”):

$ shc install gitlab
installing gitlab …

Three properties, each of which is easy to get wrong:

  • Print the reason, not just the node. “node-b” alone reads as an arbitrary machine decision. “most free memory of 3 candidates” is a claim the operator can check and disagree with, and disagreement is the feedback the weights need; §6 of the foundations doc says plainly that the weights “are a starting point and are not tuned”.
  • Name the override in the same line. The first time an operator is surprised by a placement is the moment they need to know --node exists. Sending them to --help at that moment is a worse product than printing eight extra characters every time.
  • Say nothing when nothing was decided. A product that announces a decision on a single-node estate is noise, and noise is how operators learn to skip output. This matches the advisor’s existing refusal rather than adding a second rule.

--dry-run is the other half, and it is cheap. The scorer is a pure function over a slice; a dry run is the scorer plus the capacity gates plus no install. It is the only way to answer “where would this go?” without committing, and it is the natural home for the full table docs/proposals/2026-08-11-placement-policy.md §4.4 designs for shc placement explain. PROPOSED: --dry-run on install, and shc placement explain <stack> for the after-the-fact replay. They are the same renderer against two data sources, the live scorer and the recorded decision, and §4.4’s warning applies to the second: it must be a replay of what was recorded, never a re-derivation, or it will disagree with what happened and destroy the trust it exists to build.

2.3 Swarm: SHC does not choose, and should say that too

Section titled “2.3 Swarm: SHC does not choose, and should say that too”

MEASURED (ruled): R1 is settled, docs/architecture/cluster/swarm-contention-map.md §8 and the foundations doc §1: runtime: swarm is legacy / second-class. The advisor acts on it: ChooseNode returns “no opinion” for swarm before it issues a single query.

Re-measured at this HEAD, since the catalogue moved under the ruling: 36 of 98 compose files carry depends_on conditions swarm cannot express (service_healthy / service_completed_successfully), plus ce’s builtin/traefik, the system ingress. R1 measured 37 of 99 at shc 2a5800aaf; the delta is the errors-league swap (2d74ae68d, highlight retired, glitchtip added), not a change in the ratio. The ruling stands unchanged on my numbers.

PROPOSED surface: on a swarm install, print the honest statement rather than nothing:

$ shc install ivatar --runtime swarm
placement swarm scheduler (SHC supplies reservations, not a node)

That single line does three jobs: it tells the operator SHC did not choose, it tells them who did, and it makes the (pinned) rendering they will later see in shc ls legible as a deliberate state rather than an anomaly.


3. (b) The owner’s open question: should swarm pin by default?

Section titled “3. (b) The owner’s open question: should swarm pin by default?”

“swarm is more straightforward in the sense that it’s just deployed, not pinned to anything, unless maybe it should by default be pinned to something, I don’t know.”

factfigureclass
compose files under apps/98MEASURED
mentioning volumes: anywhere74MEASURED
declaring a top-level named-volume block45MEASURED
declaring x-shc-volume (the RWO metadata)0MEASURED
declaring replicas:0MEASURED
declaring x-shc-scale64 apps, 69 services, every one max: 1MEASURED

Two consequences follow directly.

★ The one guard that would make an unpinned swarm deployment safe fires for zero apps. ApplyVolumePlacement (ce modules/app/swarm_placement.go:104-160) pins an RWO-volume service to its attachment node and clamps it to mode: replicated, replicas: 1 “regardless of the authored replicas / x-shc-scale.max”. It is exactly the right shape. It is driven off x-shc-volume, which 0 of 98 apps declare.

★ Nothing in the catalogue is written to run more than one replica. Zero replicas:, and all 69 x-shc-scale.max values are 1. Swarm’s spread is a capability the catalogue cannot currently use, which means the thing an unpinned swarm deployment buys today is not “load spread across nodes”, it is only “restart somewhere else if this node dies”.

INHERITED (docs/proposals/2026-08-11-placement-ownership-fork.md §3.3), and it is the decisive chain: an unbound data mount renders as a per-node named volume; on reschedule docker provisions a fresh, empty one; the app comes up blank and serves; users write into it, a data fork, not a loss, and then the next backup resolves the mounting service’s most recent task node, archives the empty volume, and reports success, after which retention rotates the last good archive away.

Pin a swarm deployment when it has bytes. Leave it unpinned when it does not. Derive that from a signal the render path already computes, and print which one happened.

The signal exists at exactly the right seam. INHERITED from this lane’s brief: install_runner.go takes the swarmRuntime && !hasBinding branch and keeps the named-volume reference, at which point SHC already knows this deployment will get a per-node volume. That is the pin condition. It needs no new declaration from 74 app packagers, and it is true of the undeclared case, which is the dangerous one and the default one.

So:

  • has an unbound data mount → pin to the install node, and print placement swarm01 (pinned: unbound data mount).
  • no data mount → leave unpinned, and print placement swarm scheduler (stateless). This is the ~24-app set where swarm’s restart-on-surviving-node is genuinely free, and the only place it should be spent.
  • declares x-shc-volume → unchanged, the existing RWO clamp already does the right thing and does it better (it also forces replicas: 1).

3.3 The two alternatives, and why I reject them

Section titled “3.3 The two alternatives, and why I reject them”

Blanket pin everything. Simpler to explain, and safe. Rejected because it converts swarm into a strictly worse compose, all of swarm’s operational complexity, none of its scheduling, and it does so silently for the stateless set that was correctly unpinned. It also fights StatedNodeID, which exists specifically to keep “the operator pinned this” and “SHC routed this” distinguishable, and which an earlier two-way fold destroyed once already (foundations §6.1).

Change nothing, refuse instead. Refuse the install of a volume-carrying app onto swarm, and make the operator opt in. Rejected as the default, but it is the right shape for the residual risk and I would take it as a second layer: a pin protects the data, and it does so by converting “reschedules and forks” into “stays down until the node returns”, which is compose’s guarantee, and is the trade this product has already chosen everywhere else. The operator should be told that is what they got, which is what the printed reason does.

★ What the pin does NOT fix, stated because it will otherwise be discovered later: pinning stops the fork; it does not give the deployment HA. A pinned swarm task on a dead node stays pending, exactly as a compose deployment on a dead node stays dead. Swarm’s automatic restart is precisely what is being traded away, deliberately, for the 74.

RULING-OWED. This changes the default placement of a runtime the product has ruled legacy, on estates that run zero swarm stacks. That makes it cheap to land and impossible to validate in production; there is no swarm estate to prove it on. My read is that it should land anyway, because the cost of being wrong is an unpinned stateless app that could have been pinned, and the cost of not landing it is the fork chain in §3.1. But it is the owner’s call whether a legacy runtime earns a behaviour change at all, or whether the honest answer is a loud refusal at install and no further engineering, which is what the ownership fork recommends for swarm work generally.


4. (c) ★★ “Add a node and things balance”: what is actually true

Section titled “4. (c) ★★ “Add a node and things balance”: what is actually true”

The owner’s constraint was “when you add more nodes, at least be balanced.” This section is the one I most want read, because the gap between what that sentence sounds like and what either runtime does is large.

4.1 The honest promise, per runtime: MEASURED

Section titled “4.1 The honest promise, per runtime: MEASURED”
what happens when you add node D
composeD becomes a candidate for the next install. Nothing that is already running moves, ever, without an explicit shc move.
swarm, unpinnedD receives new tasks. Existing tasks do not move: swarm does not rebalance on its own, and only re-places on a docker service update --force or a node failure.
swarm, pinned (incl. every RWO service, and every deployment under §3.2)D receives nothing from this deployment, now or ever.

So the sentence that belongs in the documentation, and that should be said to the owner before he finds out another way:

Adding a node makes it a candidate for the next install. It does not redistribute what is already running.

★ On compose this is the contract, not a defect, the owner’s own settled position this session: compose = pinned, moves only by an explicit operator verb, and that is the stated advantage over Kubernetes. The doc should say that in the same breath, because “nothing moves” reads as a limitation unless the reason is adjacent to it.

★ On swarm, “swarm rebalances for you” is the belief to head off. It does not. docker service update --force re-places tasks, and, per the owner’s own standing decision, SHC supplies that trigger rather than building a mover. But with §3.2’s default, most deployments are pinned and a force update re-places nothing. That is correct and it should be printed, not discovered.

4.2 The advisory report: PROPOSED, recommend FOR

Section titled “4.2 The advisory report: PROPOSED, recommend FOR”

The vSphere “Partially Automated” answer: compute the recommendation, show it, never act on it.

$ shc placement report
3 of 14 deployments would be better placed elsewhere.
deployment node score best score Δ
gitlab/default node-a 388 node-b 612 +224
frappe/prod node-a 401 node-c 588 +187
windmill/default node-a 412 node-b 560 +148
node-a carries 11 of 14 deployments and 191.65 GiB of declared limits
against 30.60 GiB of memory.
To move one: shc move gitlab --node node-b
★ `shc move` is a full stateful cutover: stop, archive, ship, restore,
health gate. Budget downtime. It is refused on a protected deployment.

For, on four grounds:

  1. It is nearly free. The scorer is already a pure exported function, and Decision.All already carries every candidate’s score and every abstained term with its reason (foundations §8). The report is a renderer over data that exists.
  2. It is the only thing that closes the loop on the weights. Nobody can tune weights that are never displayed against outcomes anybody sees.
  3. It is the safe half of the rebalancer, and it can ship long before the dangerous half, which the foundations doc deliberately excluded from v1 for reasons I agree with.
  4. It answers the owner’s constraint honestly. It cannot say “things balanced themselves”. It can say “here is what is unbalanced, here is the command”, which is true.

Two requirements, and they are what make it not-nagging:

  • It must print the COST, not just the benefit. A recommendation to move a stateful stack that omits “this is a full cutover with downtime” is a recommendation to cause an outage. The Δ column and the warning belong in the same output.
  • It must be pull, not push. A command the operator runs. Not a banner, not a notification, not a doctor --fix action. ★ This product has already had one doctor --fix that would have duplicated every swarm stack; a fixer that moves live stateful data is a strictly larger version of that hazard.

Against, stated fairly: on a single-node estate it prints nothing forever, and on both current estates, 100% compose, and the compose contract says nothing moves, it produces advice the operator will mostly decline. That is acceptable: declining a recommendation you can see is a different state from not knowing.

Recommend AGAINST any variant that acts, schedules, or nags.


5.1 The kill switch: LANDED (on the advisor branch)

Section titled “5.1 The kill switch: LANDED (on the advisor branch)”

deploy.placement_scoring ∈ on | off, default on, through the ordinary 5-level cascade (deployment > stack > environment > tenant > global). off returns before a single query is issued, do not score, not “score and ignore”, and an unreadable value leaves scoring on, because a disabled feature and a broken one look identical from outside. That is all correct and I propose no change.

One naming hazard: PROPOSED. deploy.placement_scoring sits one word away from compose’s own deploy.placement, which SHC reads and writes on the swarm path in at least four files (swarm_placement.go, swarm_placement_replay.go, backup_swarm_replay.go, resource_reservations.go). They are unrelated: one is an SHC config key, the other is a compose-file stanza. Anyone grepping deploy.placement will hit both. Worth a sentence in the key’s documentation, and worth considering placement.scoring instead, which is also the spelling the policy doc uses (§4.5), so the two documents currently disagree on the key’s name. RULING-OWED: which spelling ships. It must be settled before the advisor lands, because a config key is a compatibility surface and this product does no backcompat.

5.2 never-move, and a UX defect it exposes

Section titled “5.2 never-move, and a UX defect it exposes”

The policy doc (§3.4) proposes copying deployment.protected exactly. The mechanism is right and it is already wired: move is refused on a protected deployment, at the first mutation-free instant, and it fails closed; an undeterminable answer refuses too (ce modules/clone/protection.go:15-40). The reasoning there is excellent and I would not touch it.

★ But the flag does not say so. MEASURED: shc install --protected help text, ce modules/app/commands/install.go:203:

"protect the deployment: refuse uninstall/destroy until 'shc unprotect'"

It refuses move as well, and move is what shc node drain runs. So an operator who protected their database, reasonably, to stop it being deleted, discovers at drain time, mid-maintenance, that they cannot evacuate it without unprotecting it first. The help text names two verbs and the flag governs three.

PROPOSED, cheap and now:

  1. Fix the help text to name move/drain: “refuse uninstall, destroy and move (including shc node drain) until shc unprotect”.
  2. Make the drain refusal name the fix; see §6.
  3. RULING-OWED: should protected and never-move stay one flag? The argument for splitting: “do not delete this” and “do not move this” are different intents, and the common case (a protected production database an operator would happily have drained onto another node during maintenance) currently gets the wrong answer. The argument against splitting, which I find stronger for v1: two flags is two things to get wrong, the conflation currently fails in the safe direction, and the protection doc’s own analysis shows the flag cannot follow a move across a rename/tenant/env change, so “protected things do not move” is not merely a policy, it is a limitation of where the flag is stored. I recommend one flag, honest help text, and revisiting only if an operator hits it.

The 5-level cascade is the right idiom and deploy.placement_scoring already uses it. Two clarifications worth stating:

  • off at any level means “do not evaluate at that scope”, and the effect is byte-for-byte the pre-scorer behaviour: the install runs on the daemon that received it. That is a complete, describable fallback, which is what makes the switch safe to flip during an incident.
  • The advisory report (§4.2) must honour the same key at the same scopes. Recommending moves under a scope where scoring is disabled is advice the operator has already declined.

6. (e) What the operator sees when it goes wrong

Section titled “6. (e) What the operator sees when it goes wrong”

The governing rule: a refusal must name the fix. Today most of these paths do not refuse at all; they silently fall back, which is worse.

6.1 ★ The candidate set is empty, and the fallback lands on the draining node: MEASURED

Section titled “6.1 ★ The candidate set is empty, and the fallback lands on the draining node: MEASURED”

This is a live defect, not a hypothetical. The advisor’s candidate query (shc modules/placement/advisor.go) filters availability IS NULL OR availability = 'active', which is what shc node drain writes, and cluster_state IN ('healthy','degraded'). ChooseNode then does:

cands, err := a.candidates(ctx, req)
if err != nil || len(cands) == 0 {
return "", err
}

An empty candidate set returns “no opinion”, the seam leaves target.NodeID empty, and the install runs on the daemon that received the call, which may be the very node being drained. The advisor filtered the draining node out of the candidate set and then handed the install to it anyway.

The design principle that produces this is right and should not be reverted: “it never returns an error that matters… a default that can refuse is not a default.” The scorer must not gate admission. But “no candidate is eligible” is not the same event as “I have no opinion”, and collapsing them loses the one case where the fallback is actively wrong.

PROPOSED: distinguish the two. When the candidate set is empty and the receiving node is itself excluded, the install should refuse with a message that names why and what to do:

X4030xx NOPLACE no node can accept this install
node-a draining (shc node drain node-a --cancel)
node-b quarantined (cluster_state=lease_pending)
node-c drained
This node (node-a) is draining and cannot take new work.
To install anyway: shc install gitlab --node node-a

An explicit --node must still win; the operator overriding a drain is a decision they are allowed to make, and the drain doctrine already treats an explicit pin as an instruction rather than a hint.

6.2 No node has capacity: the refusal names one node, the question is about the fleet

Section titled “6.2 No node has capacity: the refusal names one node, the question is about the fleet”

MEASURED: X403010NODCPU / X403011NODMEM now report free capacity (total minus committed reservations), and the code comment records why that matters; the previous wording told an operator a node had 16 cores free at the moment it did not. That is a real improvement and the wording is good.

The residual gap is scope. Both messages name one node and its free figure, because they are per-node gates fired against an already-chosen node. The operator’s actual question is “is there room anywhere?”, and the answer they get is about the one machine the scorer happened to pick.

PROPOSED: when the gate refuses an install whose node was derived (not named by the operator), append the fleet:

X403011NODMEM node memory capacity exceeded
requested 8.00 GiB; node-b has 2.10 GiB free (total minus committed)
node-a 1.40 GiB free
node-b 2.10 GiB free <- chosen
node-c 0.90 GiB free
No node in this fleet has 8.00 GiB free.
Reduce the request: --memory-quota <service>=4Gi
Or add capacity: shc node join …

The distinction matters because the two situations need opposite actions: one node short means pick another node, every node short means shrink the request or grow the fleet. A message that cannot tell them apart cannot name the fix.

Note the gate boundary this respects: EnforceLargestReplicaFitsNode stays on total, deliberately: “is any node physically big enough for one replica” is a different question and subtracting usage could only make it refuse what would fit once something stops.

6.3 The app cannot run on any available runtime

Section titled “6.3 The app cannot run on any available runtime”

Currently unreachable, because nothing reads the declaration (§1.2). Once it is read, this becomes the message the owner’s mailcow example needs:

X4000xx RTMAPP mailcow cannot run on this fleet's runtime
mailcow declares: requires.runtimes: [compose]
this fleet runs: swarm (node-a, node-b, node-c)
mailcow needs a compose-runtime node. Add one:
shc node join --runtime compose …
A node's runtime is fixed at join and cannot be changed in place.

The last line is load-bearing. INHERITED: the runtime is chosen once at init/join and there is no in-place flip, so an operator who hits this refusal cannot fix it by reconfiguring, and a message that does not say so sends them looking for a knob that does not exist.

6.4 The three fixes this section depends on, ranked

Section titled “6.4 The three fixes this section depends on, ranked”

PROPOSED, in dependency order:

  1. Read requires.runtimes: one struct field, one merge of the legacy top-level spelling, one check at install. Until this exists, §6.3 is unreachable and three documentation pages are false.
  2. Correct the three doc sites (§1.2, §1.3), and correct them first, because it is a five-minute change and it stops new apps being written against a contract that does not hold. If the ruling is that the key should stay unread, the docs must say the key is advisory.
  3. Split “no candidate” from “no opinion” (§6.1), the only item here that is a live defect rather than a missing surface.

  • It does not tune the weights. They are memory 40 / cpu 20 / count 20 / tenant 10 / app 10 and the foundations doc is explicit that they are untuned. §2.2’s printed reason and §4.2’s report are the instruments that would let anyone tune them; this page does not pretend to have the data.
  • It does not propose a preference vocabulary. The owner asked for “preferred” as well as “restricted”, and I am deliberately not designing prefers.runtimes: because the restriction half is not read yet, and a second unread key is worse than one. RULING-OWED: whether preference is wanted at all, once restriction actually works. My read: on a fleet whose runtime is fixed at init and uniform in practice, “preferred” has no operand to act on, and the honest v1 is restriction only.
  • It does not touch the mover. Per the owner’s standing decision, the swarm path gets swarm’s own primitive and SHC supplies the trigger; the atomic mover stays in the compose shc move story.
  • It has no live proof. Both estates are 100% compose with zero swarm stacks, so every swarm claim here is read out of code and none of it has been observed. §3 in particular proposes changing a default for a runtime nobody can currently test against.

#question§
1Should requires.runtimes be read, or documented as advisory? Three doc pages currently claim enforcement.1.2, 6.4
2Should a swarm deployment with an unbound data mount be pinned by default? Or is a loud refusal the whole of the swarm work?3.3
3deploy.placement_scoring or placement.scoring; the two design docs disagree, and there is no backcompat.5.1
4Does protected stay one flag covering uninstall + destroy + move?5.2
5Is shc placement report wanted at all, given both estates are compose and the compose contract is that nothing moves?4.2
6Is “preferred runtime” wanted once “restricted” works?7

Terminal window
# §1.2: the declarations, and that nothing reads them
grep -rn -A1 '^requires:' apps/*/*/app.yaml | grep runtimes
grep -rn '^runtimes:' apps/*/*/app.yaml
cd ../ce && grep -rn 'yaml:"requires\|yaml:"runtimes' --include='*.go' . # no hits
# §1.3: what the runtime guard actually refuses
cd ../ce && sed -n '1018,1036p' modules/stack/service.go
# §2.3: the R1 corpus at this HEAD
find apps -name compose.yaml | wc -l # 98
grep -rl 'service_healthy\|service_completed_successfully' \
apps --include=compose.yaml | wc -l # 36
# §3.1: the volume and replica facts
grep -rl 'volumes:' apps --include=compose.yaml | wc -l # 74
grep -rl '^volumes:' apps --include=compose.yaml | wc -l # 45
grep -rl 'x-shc-volume' apps --include=compose.yaml | wc -l # 0
grep -rl 'replicas:' apps --include=compose.yaml | wc -l # 0
grep -rh -A3 'x-shc-scale' apps --include=compose.yaml | grep max: | sort | uniq -c
  • docs/decisions/2026-08-11-rebalancer-v1-foundations.md: the four rulings this page’s mechanism sits on, incl. R1 and the kill switch
  • docs/proposals/2026-08-11-placement-policy.md: the scoring function, shc placement explain, and the install seam
  • docs/proposals/2026-08-11-placement-ownership-fork.md: §3.3, the swarm stateful chain that §3 acts on
  • docs/proposals/2026-08-11-rebalance-trigger-and-safety.md: the trigger and the safety envelope this page’s report deliberately stops short of
  • docs/architecture/cluster/swarm-contention-map.md §8: where R1 is answered
  • ce core/placement/: the four renderings §2 builds on
  • ce modules/clone/protection.go: why protected refuses move