Skip to content
SHC Docs

The runtime is the placement contract

Archived, superseded by the new line (SHC-1092), which removed Swarm.

Status: PROPOSED. The policy is the owner’s, stated 2026-08-11. This page specifies it so it can be built, corrects one premise inside it that is measurably false, and surfaces one collision with a ruling that landed the same day (§1).

Baselines. shc main 0e5621a79, ce main 4b8d471. Every figure marked MEASURED was read out of those trees or produced in this session; the reproduction script is Appendix B. Everything else is marked PROPOSED, RULING-OWED, or INHERITED (taken from the brief or a prior page, not re-measured here).

★ The census of §4.2 is now a standing test, not a snapshot: tests/unit/catalog/placement_census_test.go walks the merged catalogue on every make test/unit and asserts the movable set by name. The tables below are the reading that produced it; the test is what keeps the reading true. See Appendix B for what the two measure differently.


0. The proposal, and what survives contact with the measurement

Section titled “0. The proposal, and what survives contact with the measurement”

“How about the automatic rebalancing is leverage on top of Swarm? And if you use Compose, you’re essentially opting in to it not moving automatically. You would have to explicitly move it if you put it on a Compose node, which actually is really nice because sometimes that’s what you specifically want, which is one of the downsides of something like Kubernetes. So you get the best of both worlds.”, owner, 2026-08-11

The policy is right and this page adopts it. Making “pinned” a supported answer rather than a limitation is the correct product move, and it is the one thing Kubernetes genuinely cannot say. Two things have to change on the way in.

★ The premise “Swarm rebalances” is false. INHERITED from the brief, and consistent with everything in the tree: swarmkit’s own design doc says “Once a task is assigned to a node, this decision cannot be revisited,” and Docker’s admin guide states the refusal is deliberate: “If the swarm periodically shifted tasks to different nodes for the sake of balance, the clients using those tasks would be disrupted.” The only escape is the operator verb docker service update --force. Swarm supplies initial spread and reschedule-on-node-failure. It never rebalances.

So the design substitutes one clause and keeps its shape:

the proposal sayswhat it must say
composenever moves without an operator verbunchanged, and it is already true by construction (§2)
swarmopts into swarm’s rebalanceropts into SHC’s mover; swarm supplies the eligibility boundary and node-failure rescheduling (§3)

★ MEASURED: the mover already exists and is already wired. This is not a thing to build. ce modules/clone ships Service.Move, SelectMoveStrategy, a move journal and a commit point; shc move <src> <tgt> --node N is its CLI; ce daemon/services_extra.go:2184-2262 wires it as the drain migrator. What is missing is not a mover. It is a rule about when SHC is allowed to call one, which is exactly what this page is.


1. ★★ The collision with R1, stated first because it ranks everything else

Section titled “1. ★★ The collision with R1, stated first because it ranks everything else”

RULING-OWED, and nothing below can be built until it is answered.

docs/decisions/2026-08-11-rebalancer-v1-foundations.md §1 and docs/architecture/cluster/swarm-contention-map.md §8 record, RULED 2026-08-11, the same day as the proposal above:

R1: RULED: runtime: swarm is LEGACY / SECOND-CLASS. […] Swarm code is not deleted and Swarm is not broken; it is simply not where new capability goes.

The proposal on this page makes runtime: swarm the sole carrier of the single largest new capability on the roadmap. Those two sentences cannot both govern. This is not a wording clash to be smoothed over; R1 is already acted on in code in both directions (the install-time scorer declines when SchedulerOwnedRuntime(runtime); the capacity substrate was deliberately built runtime-neutral so none of it needs swarm to exist), so choosing differently now has a code cost, not just a documentation cost.

The census in §4 is what should decide it, because it prices the option. Under this proposal, “swarm = movable” would today make 5 of 90 catalogue apps movable, and all five are stateless bridge sidecars.

Three ways out, in the order I would put them:

  • R1-A: Hold R1; take the policy, drop the runtime as its carrier. Keep “the placement contract is declared, not inferred” and carry it on the never_move flag plus the data shape, not on --runtime. Costs nothing already built. Loses the owner’s clean two-word explanation.
  • R1-B: Amend R1 to a narrower claim. R1’s evidence is about swarm as a hosting runtime (it cannot load 40% of the catalogue or the ingress). That evidence does not speak to swarm as a placement substrate. Amending R1 to “swarm is legacy as a hosting runtime; it remains the declared placement boundary” is coherent, but it re-opens the swarm lane R1 just closed and makes the never-verified swarm install path load-bearing.
  • R1-C: Overturn R1. Only defensible with a plan to close the 36-app ordering gap and the ingress, which §4 shows is not a packaging problem SHC can engineer around.

★ My recommendation is R1-A, for a reason that is in the measurement rather than in the politics: the predicate that actually decides mobility turns out not to mention the runtime at all (§4.4). The runtime is a good proxy for it and a bad definition of it.


2.1 Today it is pinned by accident of construction

Section titled “2.1 Today it is pinned by accident of construction”

MEASURED: ce modules/app/placement_intent.go:60-68:

func PlacementIntent(requestedNode, resolvedNode, runtime string) string {
if req := strings.TrimSpace(requestedNode); req != "" {
return req
}
if SchedulerOwnedRuntime(runtime) { // "swarm" only
return "" // NULL == unpinned
}
return strings.TrimSpace(resolvedNode) // compose/podman/empty: always pinned
}

So pinned_node_id is non-NULL for every compose, podman and empty-runtime deployment, and the file’s own header explains that this is not a loophole: those runtimes have nowhere else to put the bytes. The proposal promotes that fact from an implementation consequence to a promise. That is worth doing, and it costs one thing: a promise with silent exceptions is worse than no promise, so every exception has to be named.

2.2 The promise, stated so it can be falsified

Section titled “2.2 The promise, stated so it can be falsified”

THE COMPOSE PLACEMENT PROMISE. No autonomous SHC process will relocate a compose deployment. Exactly four operator verbs can, each of which names either the deployment or the node explicitly, and each of which reports what it is about to move before it moves it. A node failure does not relocate a compose deployment; it stops it.

2.3 Every path that could move a compose deployment today

Section titled “2.3 Every path that could move a compose deployment today”

MEASURED, by walking the tree at the baselines above.

#pathmoves compose today?verdict
M1shc move <src> <tgt> --node Nyes✅ the intended escape hatch; the operator named the deployment
M2shc node drain <node>yes⚠️ the real exception; see below
M3shc move --presumed-deadyes✅ explicit, already heavily gated, refuses unless the node’s registry state is unreachable AND a fresh probe fails now
M4shc recover / restore onto another nodeyes✅ explicit; reconstructs from an archive rather than relocating
M5shc node rm / cluster forget / cluster repair sweepno, REFUSES✅ closed by ce modules/cluster/occupancy.go
M6shc doctor run --fixno✅ closed, MEASURED: no diagnosis under ce modules/doctor/diagnoses/ relocates anything; grep for clone./Move(/drain across that package returns zero non-test hits
M7health reconcile loopno✅ reconcileStackAction restarts the stack in place
M8estate rebuild / terraform apply replacing a nodeno✅ the provider’s node Delete calls cluster forget, which discharges M5’s guard
M9install-time placement scorern/a, chooses, never moves✅ and MEASURED: not wired at shc HEAD: modules/placement/placement.go exists, SetPlacementAdvisor has no non-test caller, so a first install still lands on the node that handled the request

★ M2 is the exception the promise must name. shc node drain <node> lists every running deployment on the node and calls DeploymentMigrator.Migrate per row. At HEAD that migrator is a real relocation: ce daemon/services_extra.go:2212-2262 routes it through clone.Move, the same path as shc move --node. (The July review docs/reviews/2026-07-20-drain-does-not-migrate.md says the migrator is a bare SQL row rewrite. That review is stale; the adapter’s own header records the rewrite and why: “It used to be UPDATE deployment SET host_node = ?. Nothing moved […] That is worse than doing nothing.” Another instance of the docs-lag-code class.)

Drain moves deployments the operator did not name. That is not a defect: the owner has already ruled on precisely this shape, and the ruling is quoted in ce modules/cluster/occupancy.go:7-12:

“you would have to actually move those deployments in order to remove that node… it shouldn’t just auto move things.” Relocation is shc node drain, an explicit verb, with a wall-clock budget and a real failure mode.

So drain stays a legal mover of compose deployments, and the promise says “operator verb”, not “per-deployment verb”. PROPOSED, three requirements so it does not become the silent exception:

  1. Drain must enumerate before it moves. Print the deployment list, the per-row strategy SelectMoveStrategy will choose, and the fact that every compose row takes the heavy path, then confirm. Today’s --dry-run shape on shc move is the model.
  2. never_move must make drain REFUSE that row, loudly, not skip it silently, and not stop it in place under a different name. A drain that reports success having left a row running on the draining node is the M2 version of the bug the migrator rewrite already fixed once.
  3. protected already produces this behaviour and it is worth stating: MEASURED: clone.Move calls refuseMoveIfAnyProtected at ce modules/clone/service.go:331, before any phase runs, so every protected deployment is already effectively never-move, and a drain that hits one fails that row and aborts the run at step 6.

2.4 What the promise is worth against each hazard

Section titled “2.4 What the promise is worth against each hazard”
hazardwhat happens to a compose deploymentis that acceptable?
node drainmoves, via M2, on an explicit verbyes, with §2.3’s three requirements
node failuredoes not move. It stays down until a human runs M3 or M4.★ yes, and this must be said out loud, not implied
doctor --fixnever moves (M6)yes
estate rebuildnever moves; removal of an occupied node refuses (M5/M8)yes
daemon restart / reconcilerestarts in place (M7)yes

★ The node-failure row is the honest cost of the whole design and it is already public. docs/reviews/2026-07-20-drain-does-not-migrate.md states it better than I can: “with three voters, losing one node keeps the cluster alive and writable; raft holds quorum, the control plane is genuinely HA. But the apps that were on the lost node stay dark until a human intervenes.” Under this proposal that is no longer a gap to be closed later; for compose it is the declared contract. That reframing is only legitimate if the product says so on the page where the operator chooses, which is a docs requirement, not an engineering one.


3.1 The user is opting into SHC’s mover, not swarm’s

Section titled “3.1 The user is opting into SHC’s mover, not swarm’s”

Swarm has no rebalancer (§0). The division PROPOSED:

who does itstatus at HEAD
initial placementswarm’s schedulerMEASURED: SHC feeds it real input: ApplyResourceQuotas writes deploy.resources.reservations on 327 of 328 services, runtime-independently
rebalancingSHC’s mover (clone.Move, ephemeral strategy)exists; nothing calls it autonomously
reschedule on node failureswarm★ MEASURED: this is the dangerous one, §3.2
eligibility boundarythe runtime declarationthis page

★ Two facts make swarm’s “initial spread” worth less than it sounds. MEASURED: 0 of 90 catalogue apps declare replicas:, and 69 x-shc-scale blocks across 64 apps all say max: 1. Swarm’s spread distributes replicas of one service; with one replica there is nothing to spread. SHC also writes no docker node labels anywhere in either repo, so placement.preferences: spread: node.labels.* has no source to read. Swarm’s contribution to a 90-single-replica-app fleet is bin-packing by reservation, and nothing else.

3.2 ★★ Swarm’s node-failure reschedule is the dangerous path, and it is the default path

Section titled “3.2 ★★ Swarm’s node-failure reschedule is the dangerous path, and it is the default path”

MEASURED: ce modules/app/install_runner.go:4094:

if swarmRuntime && !hasBinding {
// UNBOUND swarm DATA mount: keep the named-volume reference (swarm
// provisions it per-node on whichever node the task lands) …

An unbound named-volume mount on swarm is provisioned per node. A reschedule therefore gives the task a fresh empty volume, and the app comes up blank, and serving. No error, no refusal, no health signal that distinguishes “restored” from “reinitialised”.

MEASURED: 0 of 90 catalogue apps declare x-shc-volumes. So hasBinding is false for every DATA mount in the catalogue and this is not an edge case; it is the only path. Every stateful swarm install in the catalogue today is one node failure away from a silent data fork.

3.3 Should SHC suppress swarm’s reschedule for stateful services? CONFIRMED it already does, for a set that is empty

Section titled “3.3 Should SHC suppress swarm’s reschedule for stateful services? CONFIRMED it already does, for a set that is empty”

MEASURED: ce modules/app/swarm_placement.go:104-160, ApplyVolumePlacement: for each RWO x-shc-volume it pins the service to node.hostname==<attachment node> (overriding any conflicting app self-pin, because a wrong pin on an RWO volume is the corruption case) and forces deploy.mode: replicated, replicas: 1 unconditionally. That does exactly suppress swarm’s reschedule, and the two movers cannot fight. Confirmed as asked.

★ But it fires only on placements []RWOPlacement, which is derived from x-shc-volumes bindings, of which there are zero. The guard is correct, complete, and currently covers nothing.

PROPOSED: extend the pin to unbound DATA mounts, or refuse the install. A swarm service with a named-volume DATA mount and no binding must either:

  • (P1) be pinned to its install node with replicas: 1, same mechanism as the RWO path, which converts a silent data fork into an honest outage and makes the deployment behave exactly like compose; or
  • (P2) refuse at install with a coded error naming the mount, in the same family as X400324VOLSWMNB (“bound swarm mount but no volume backend”).

P1 is the smaller change and the safer default. It also has a consequence the proposal has to absorb: under P1, a stateful swarm deployment is pinned, so “swarm = movable” is false for it too. That is not a flaw in P1; it is the predicate in §4 showing up in the code.


4. ★★ (c) THE ELIGIBILITY PREDICATE, and the census that decides its worth

Section titled “4. ★★ (c) THE ELIGIBILITY PREDICATE, and the census that decides its worth”

4.1 The predicate, over facts SHC already has

Section titled “4.1 The predicate, over facts SHC already has”

No new declarations, no new columns. Every input below is already parsed today.

ELIGIBLE(deployment) :=
runtime == "swarm" // R1-A: see §4.4
AND ORDERING_OK(compose)
AND NO_LOCAL_STATE(compose)
AND NO_NODE_LOCAL_MATERIAL(compose)
AND NOT protected // clone/protection.go
AND NOT never_move // placement-policy §3.4
AND NOT self_pinned(compose) // author's own node.hostname/node.id
ORDERING_OK(c) :=
no service declares depends_on.<t>.condition in
{ service_healthy, service_completed_successfully }
// authority: ce modules/app/swarm_compat.go swarmOrderingConditions.
// Not a policy choice; swarm has no start-ordering primitive, so these
// are refused at render (X400073SWMXLT) and the stack cannot deploy at all.
NO_LOCAL_STATE(c) :=
for every service mount m with DetectMountType(m) == MountData:
m.name ∈ keys(document."x-shc-volumes")
// authority: ce core/volume/resolve.go DetectMountType.
// A DATA mount is a named-volume reference; SHC host-binds it under the
// per-deployment mounts dir on ONE node. Unbound == local persistent data.
NO_NODE_LOCAL_MATERIAL(c) :=
no mount classifies MountFile // rendered beside the compose, one node only
AND no /etc/shc/* platform mount that is not peer-synced
// authority: ce modules/app/platform_mount_peers.go. A swarm task whose
// bind source is missing is REJECTED outright, measured there, and unlike
// compose swarm does not auto-create it. WarnSwarmFileMounts logs this and
// does nothing else (X200995PMTFIL), so today it is a warning, not a gate.

Note what is not in the predicate. x-shc-scale.max: 1 does not make a deployment ineligible: it is a ceiling on replication, not on relocation. One replica moved from node A to node B is still one replica. R3 of the contention map (max: 1 means single-writer) is honoured by moving, not by staying.

MEASURED. Method: parse each apps/**/compose.yaml (Jinja control flow stripped, expressions tokenised; this keeps the union of all branches, so it over-reports mounts and never under-reports them), then apply the ce classifiers above. Test-fixture consumer apps under **/tests/apps/ are excluded (8 of the 98 compose.yaml in the tree). Script: Appendix B.

verdictappsshare
INELIGIBLE, stateful (unbound DATA mount)3741%
INELIGIBLE, ordering (also all stateful)3640%
ELIGIBLE1719%
total90

★ And the 17 does not mean what it looks like. Broken down:

what the “eligible” apps actually arecount
zero-service connection stubs: external-{imap,llm,mongodb,mysql,oidc,postgres,redis,s3,smtp}, standalone/s3. These declare no services: at all; they are external-resource declarations, not workloads. Nothing to place.10
test fixtures: fixtures/test-simple, fixtures/whoami2
real, movable production workloads: collaboration/huly-nextcloud, collaboration/nextcloud-picker, knowledge-base/affine-rs, management/gitlab-huly, security/identity-broker★ 5

★★ THE HONEST SCOPE OF THE PROGRAMME IS 5 OF 90, and all five are single-service stateless bridge/broker sidecars whose durable state lives in a different stack. Four of the five declare x-shc-scale.max: 1 for singleton-semantics reasons (one Kafka consumer-group member, one Keycloak admin-event poller, one in-memory write queue), which, per §4.1, does not block a move but is a reminder that these are not the workloads anyone wants rebalanced.

Two cross-cutting facts fall out of the same pass:

  • ★ Ordering is a strict subset of stateful. All 36 ordering-refused apps also carry unbound DATA mounts. Ordering never decides eligibility on its own; it decides whether the stack can deploy on swarm at all, which is a different and earlier question. If every ordering refusal were fixed tomorrow, the eligible count would not move by one.
  • ★ 73 of 90 apps (81%) carry unbound local persistent data. That single fact is the whole census.

Reconciling with R1. R1 records “37 of 99” for the ordering set. At HEAD the tree has 98 compose.yaml (90 non-fixture) and both a grep -rl (R1’s method) and a structural YAML parse return exactly the same 36 apps, verified as a set, not just a count. R1’s substance is confirmed; its arithmetic is one app stale, from the app retirement that landed between.

The four ce builtins, classified the same way (MEASURED):

builtinverdictwhy
traefikINELIGIBLE: ordering and stateful and host-sockettraefik → traefik-init: service_completed_successfully; acme/static volumes; binds /var/run/docker.sock. The system ingress cannot run on swarm at all.
postgresINELIGIBLE: ordering, statefulpostgres → postgres-guard: service_completed_successfully; pgdata
openobserveINELIGIBLE: statefuldata
keycloakINELIGIBLE: platform mount/etc/shc/license, system-only, per-node

4.3 Four ineligibility classes, and which are fixable

Section titled “4.3 Four ineligibility classes, and which are fixable”
classappsfixable?
unbound local persistent data73yes, per app: declare x-shc-volumes and give the mount a block volume. This is a catalogue change, one app at a time, and it is the only lever that moves the number.
swarm-inexpressible ordering36no: swarm has no start-ordering primitive. Restructuring 36 apps to not need one is a rewrite, not a packaging fix.
node-local rendered files (MountFile)6: dify, fusionpbx, hyperswitch, ivatar, openreplay, supabaseyes: translate to configs: (swarm distributes those over raft) or ship them in the image. ApplySwarmLoaderCompat already does the reverse translation for configs.content.
per-node platform material3: medusa, affine, huly (/etc/shc/tls.ca)partly: SyncTLSTrustAnchorsToPeers repairs the PEM leg best-effort; the JVM leg is adopted only once every peer confirms.

metabase (/dev/urandom) and immich (/etc/localtime) bind only systemMountSafelist entries, which are byte-identical on every node and therefore do not constrain placement. They are ineligible for other reasons.

4.4 ★ The reframe: eligibility is decided by DATA. The runtime decides COST.

Section titled “4.4 ★ The reframe: eligibility is decided by DATA. The runtime decides COST.”

Read §4.1 again with the first clause removed. Nothing else in the predicate mentions the runtime. What actually decides whether a deployment can move is where its bytes are, and that is identical on compose and on swarm.

The runtime decides something different, and MEASURED: ce modules/clone/move_strategy.go:309-368:

relocateBlocked := nodeChanging && !swarm
…
if !anyPersistent {
if relocateBlocked { return StrategyBackupRestore }
return StrategyEphemeralOnly
}
  • swarm + no persistent mount → EPHEMERAL_ONLY: re-render the placement constraint and restart. Seconds.
  • compose + node change → BACKUP_RESTORE, always, whatever the mount class: stop, archive, ship, restore, health-gate. Minutes to hours, with a commit point after which failure rolls forward.

★ So the owner’s policy is true in the way that matters, for a better reason than the one stated. Compose is not “unmovable”; compose is movable only through a full stateful cutover, which is exactly why nothing autonomous should ever do it. Swarm is not “automatically rebalanced by swarm”; swarm is cheaply movable by SHC, which is what makes automation defensible there. The runtime is the placement contract; it just signs for the mechanism and the downtime, not for the possibility.

That framing is what makes R1-A workable: keep the two-word explanation, and define it against cost rather than against capability.


5. (d) The user-facing surface: is --runtime already the declaration?

Section titled “5. (d) The user-facing surface: is --runtime already the declaration?”

The owner’s phrasing implies no new surface is needed. Tested: --runtime is necessary but not sufficient, for four measured reasons.

5.1 It is per-deployment and already mutable, including by accident

Section titled “5.1 It is per-deployment and already mutable, including by accident”

MEASURED. --runtime (compose|swarm|podman) is a flag on shc install (ce modules/app/commands/install.go:193) and on the stack-lifecycle verbs (stack_lifecycle.go:902), not a cluster property. shc init --runtime sets a cluster default only. And install_runner.go:270-273 is explicit:

“an explicit --runtime compose over a swarm deployment is a deliberate re-platform and has to be obeyed. Evidence decides what “unsaid” means; it does not get to overrule what was said.”

That is correct engineering and it makes --runtime a poor contract on its own: a placement guarantee you can revoke as a side effect of an unrelated update is not a guarantee. PROPOSED: a runtime change on an existing deployment becomes a confirmed operation; it is a re-platform and a contract change, and it should say both.

5.2 “Unset” means inherited, never re-declared

Section titled “5.2 “Unset” means inherited, never re-declared”

MEASURED: install_runner.go:274-286: an empty opts.Runtime is filled from the manifest sidecar via RuntimeFromEvidence, deliberately, because taking the compose arm against a swarm stack is the duplicate-stack bomb. Good behaviour; but it means most deployments’ placement contract was declared once, at install, possibly by a default nobody typed, and is silently inherited forever. A contract nobody restates is a contract nobody remembers agreeing to. PROPOSED: shc status / shc ls render the contract as a first-class column (PLACEMENT: pinned (compose) / PLACEMENT: managed (swarm)) reusing ce core/placement, which already owns exactly this rendering decision and exists precisely because two copies of it drifted.

5.3 ★ The per-deployment never-move annotation IS required, and it is already designed

Section titled “5.3 ★ The per-deployment never-move annotation IS required, and it is already designed”

The owner previously named it, and the census says why it is not optional: a swarm deployment with an unbound DATA mount (§3.2) is precisely “a swarm app that must not move,” and there is no other way to say so. Do not re-invent it; docs/proposals/2026-08-11-placement-policy.md §3.4 already specifies the shape, copying ce modules/app/protected.go exactly: a deployment-scoped config row through the 5-level cascade, mirrored onto the manifest sidecar (because the config resolver is nil in the CLI process), fail-closed so an unreadable flag reads as never_move = true, and a write that reports which halves landed.

Two clarifications this page adds:

  1. There is deliberately no always-move. A compose deployment cannot be made automatically movable by annotation. The only way is to change the runtime, which is the point of the whole design, a one-way door in the safe direction.
  2. never_move must be honoured by drain (§2.3), not only by a future rebalancer. Today drain is the only autonomous-ish mover in the product; an annotation that the one live mover ignores is decorative, and this repo has a documented habit of shipping exactly that.

PROPOSED. --runtime is the declaration; never_move is the per-deployment override; nothing else is added. But the declaration only becomes a contract once it is (i) rendered where the operator looks, (ii) confirmed when it changes, and (iii) enforced by drain. Those three are the actual work in this section.


6. (e) The migration story: and the ugly part is not where the brief expected

Section titled “6. (e) The migration story: and the ugly part is not where the brief expected”

6.1 ★ Correction: the runtime is NOT fixed at shc init

Section titled “6.1 ★ Correction: the runtime is NOT fixed at shc init”

The brief states that fabric/swarm exclusivity at shc init means a compose deployment cannot become a swarm one without reinstalling. MEASURED, that is wrong in two directions:

  • The exclusivity is about the FABRIC, not the runtime. ce modules/fabric/types.go:93-109 ValidateSelection refuses exactly two pairs: fabric=shc × runtime=swarm, and fabric=swarm × runtime=podman. On a fabric=swarm or fabric=none estate the per-deployment runtime is unconstrained.
  • A re-platform in place already has a code path. --runtime on shc update re-platforms (§5.1), and clone.StackMoveRequest.Runtime is documented as “the engine dialect the move REQUESTED for the target”, so shc move can change runtime and node in one operation.

6.2 ★★ A gap that must be closed before this design ships

Section titled “6.2 ★★ A gap that must be closed before this design ships”

MEASURED: ValidateSelection has exactly three call sites, all at cluster formation, ce modules/cluster/commands/init.go:182, ce modules/cluster/service.go:813, and shc modules/cluster/enroll_handler.go:338. It is never called on the install path. So on a fabric=shc estate an operator can shc install <app> --runtime swarm today and get a swarm service that cannot attach to the WireGuard fabric its peers are on. Under this proposal that same command is the primary user-facing gesture, which turns a latent misconfiguration into the happy path.

PROPOSED: call ValidateSelection(fabricMode, opts.Runtime) in the install funnel, beside EditionValidateRuntime. Small, and it should land before anything else on this page.

6.3 The real migration story, and it is a catalogue problem

Section titled “6.3 The real migration story, and it is a catalogue problem”

A compose deployment “becomes eligible later” only by satisfying NO_LOCAL_STATE; its DATA mounts must be declared in x-shc-volumes and backed by block volumes. MEASURED: 0 of 90 apps declare x-shc-volumes.

★ So the migration does not begin at the deployment. It begins in the catalogue, and nothing in the catalogue is shaped to be flipped. Said plainly, because it is the ugliest fact on this page: the transition from “pinned” to “managed” is not an operator action today, for any app, at all. The sequence, PROPOSED, four steps each with a different owner:

  1. App author declares x-shc-volumes on the app’s DATA mounts. Per app. Blocks everything downstream. (Also unblocks StrategyRebind on compose, which is worth having on its own; see §6.4.)
  2. Operator provisions block volumes and re-installs, or moves with --storage, so the data leaves the per-deployment mounts dir.
  3. Operator re-platforms: shc move <s> <s> --node N --runtime swarm, which is the only step that is genuinely one command today.
  4. Estate must be on fabric=swarm or fabric=none. If it is on fabric=shc, step 3 is impossible and the estate must be rebuilt; this is the one place where “reinstall the estate” is really the answer, and it is the fabric’s constraint, not the runtime’s.

Steps 1 and 2 are a per-app migration with a data cutover in it. Step 4 is an estate rebuild. Neither is reversible cheaply. PROPOSED: do not ship a “convert to managed placement” verb. A one-command wrapper around a four-owner, data-moving, occasionally-estate-rebuilding sequence is a lie with a progress bar.

6.4 A cheaper prize hiding in the same work

Section titled “6.4 A cheaper prize hiding in the same work”

★ Step 1 above is worth doing whether or not R1 is amended. MEASURED: SelectMoveStrategy picks StrategyRebind, detach, reattach, no archive, when every persistent mount is MountClassRebindable. With zero x-shc-volumes in the catalogue, every move of a stateful deployment takes BACKUP_RESTORE today, on either runtime. Declaring bindings makes shc move dramatically cheaper for the 73 stateful apps right now, under the existing verb, with no scheduler, no rebalancer, and no ruling. That is the highest value-per-risk item this whole lane produced.


Ordered by (blocks-others × already-measured-as-broken), not by size.

#itemgated on
1ValidateSelection on the install path (§6.2)nothing; this is a live gap
2Swarm unbound-DATA-mount pin or refusal, P1/P2 (§3.2)nothing; this is a silent-data-loss gap
3Drain enumerate-and-confirm (§2.3 req. 1)nothing
4x-shc-volumes declarations, per app, starting with the flagship set (§6.4)nothing, pays off under the existing shc move
5never_move flag per placement-policy §3.4nothing; honoured by drain from day one (§2.3 req. 2)
6Placement contract rendered in shc status / shc ls (§5.2)5
7Confirmed re-platform on runtime change (§5.1)6
8Anything that moves a deployment autonomouslyR1 (§1), and the census being worth more than 5 of 90

Items 1–7 are all useful under R1-A; they do not require swarm to become first-class, and none of them presumes the collision is resolved one way.

  1. ★★ R1 vs. this proposal (§1): R1-A / R1-B / R1-C. Ranks everything else.
  2. Swarm unbound DATA mount (§3.2): pin (P1) or refuse (P2)? P1 recommended.
  3. Is “a compose deployment does not survive node failure” a declared contract or an accepted gap? (§2.4). The answer changes the landing page, not the code.
  4. Does shc node drain stay a legal mover of pinned deployments? (§2.3). The occupancy.go ruling says yes; this page asks for it to be restated under the new contract, with enumerate-and-confirm.
  5. Reservation/limit ratios: correcting the brief, MEASURED at ce HEAD: defaultReservationRatio = 1.0 (resource_reservations.go:102) and defaultLimitRatio = 1.5 (resource_quota.go). The brief’s 0.25 / 1.0 are the pre-L4-2 values. No ruling needed; recorded so the next reader does not re-inherit stale numbers.

ord = services with a swarm-inexpressible depends_on condition; data = unbound DATA mounts; file = MountFile mounts; plat = /etc/shc/* platform mounts; sock = non-safelist raw host binds. Inert safelist binds (/etc/localtime, /etc/timezone, /dev/urandom, /dev/random) are excluded from sock because they are identical on every node.

appsvcorddatafileplatsockverdict
ai/agent-canvas214000ordering, stateful
ai/dify1247100ordering, stateful, nodefile
ai/graphiti214000ordering, stateful
ai/librechat418000ordering, stateful
analytics/matomo101000stateful
analytics/superset536000ordering, stateful
automation/windmill612000ordering, stateful
business/medusa553020ordering, stateful, platmount
cms/wordpress101000stateful
collaboration/huly-nextcloud100000ELIGIBLE
collaboration/nextcloud303000stateful
collaboration/nextcloud-picker100000ELIGIBLE
communication/fusionpbx101200stateful, nodefile
communication/hookshot101000stateful
communication/matrix7110000ordering, stateful
crm/monica202000stateful
design/penpot504000stateful
devops/gitea102000stateful
devops/gitlab205000stateful
devops/pulp9912000ordering, stateful
devops/sonarqube205000stateful
documents/paperless404000stateful
email/mailbox-reconciler101000stateful
email/mailcow171533000ordering, stateful
enterprise/metabase202000stateful
finance/hyperswitch872100ordering, stateful, nodefile
fixtures/test-data101000stateful
fixtures/test-simple100000ELIGIBLE (fixture)
fixtures/whoami100000ELIGIBLE (fixture)
identity/ivatar202300stateful, nodefile
infrastructure/blockscout613000ordering, stateful
knowledge-base/affine415010ordering, stateful, platmount
knowledge-base/affine-rs100000ELIGIBLE
licensing/keygen553000ordering, stateful
management/gitlab-huly100000ELIGIBLE
management/huly1402020stateful, platmount
management/huly-matrix-notifier101000stateful
marketing/mautic3012000stateful
marketing/postiz414000ordering, stateful
media/immich524000ordering, stateful
media/jellyfin336000ordering, stateful
media/peertube203000stateful
monitoring/glitchtip201000stateful
monitoring/openreplay225618400ordering, stateful, nodefile
monitoring/uptime-kuma101000stateful
networking/netbird715000ordering, stateful
platform/frappe8622000ordering, stateful
platform/supabase1175400ordering, stateful, nodefile
productivity/docuseal202000stateful
productivity/journiv454000ordering, stateful
productivity/shlink302000stateful
project-management/plane1117000ordering, stateful
security/ciso-assistant624000ordering, stateful
security/crowdsec102000stateful
security/defectdojo735000ordering, stateful
security/defectdojo-classic735000ordering, stateful
security/dependency-track302000stateful
security/fleet524000ordering, stateful
security/greenbone201345000ordering, stateful
security/identity-broker100000ELIGIBLE
security/midpoint212000ordering, stateful
security/midpoint-classic212000ordering, stateful
security/vaultwarden101000stateful
security/wazuh4216000ordering, stateful
standalone/clickhouse102000stateful
standalone/ethereum204000stateful
standalone/external-imap000000ELIGIBLE (no services)
standalone/external-llm000000ELIGIBLE (no services)
standalone/external-mongodb000000ELIGIBLE (no services)
standalone/external-mysql000000ELIGIBLE (no services)
standalone/external-oidc000000ELIGIBLE (no services)
standalone/external-postgres000000ELIGIBLE (no services)
standalone/external-redis000000ELIGIBLE (no services)
standalone/external-s3000000ELIGIBLE (no services)
standalone/external-smtp000000ELIGIBLE (no services)
standalone/gitlab-runner214000ordering, stateful
standalone/hockeypuck314000ordering, stateful
standalone/kubo213000ordering, stateful
standalone/mail101000stateful
standalone/mariadb101000stateful
standalone/mongodb102000stateful
standalone/mysql101000stateful
standalone/nginx102000stateful
standalone/ollama101000stateful
standalone/pmm212000ordering, stateful
standalone/redis102000stateful
standalone/s3000000ELIGIBLE (no services)
storage/minio201000stateful
storage/minio-classic101000stateful
tools/kutt312000ordering, stateful

★ Superseded as the census’s authority by tests/unit/catalog/placement_census_test.go, which runs on every make test/unit. The script below is kept because it is what produced the tables above and because it is readable in one sitting; where the two disagree, the test is the measurement. Four deliberate differences, each of which moves a number:

  • It renders rather than strips. The script drops Jinja control flow and keeps the union of all branch bodies; the test renders each document with the real jinja package in the three catalogue scenarios (sparse / dense-true / dense-empty) and unions the facts. Both over-report mounts and neither under-reports them, which is the only direction that matters; a lost mount RELEASES an app into the movable set.
  • It calls ce rather than porting it. volume.DetectMountType, volume.ParseMount, volume.ParseVolumeBindings and app.SwarmLoaderRefusals are invoked directly, so a change to the product’s idea of a mount reaches the census without a second implementation to keep in step. Only systemMountSafelist is mirrored, and it is unexported.
  • It censuses the BUILT-INS too, resolved from both builtin trees rather than from apps/. That is why its two counts both run ahead of this page’s, and the two deltas are different sizes:
    • 95 packages against this page’s 90: the FIVE built-ins join the walk (branding, keycloak, openobserve, postgres, traefik), exactly as the built-in table above records them;
    • 38 ordering-refused against §4.2’s 36: only TWO of those five carry a swarm-inexpressible depends_on (postgres and traefik); the other three are ordering-clean and add nothing to this count.
  • It names a fourth class, rebindable: durable state whose every DATA mount is declared in x-shc-volumes, so it rides a block volume that can be detached and reattached. Measured zero, today and in this page’s reading. It exists in the classifier because it is the only class that can grow the movable set, and the first app to reach it should surface as a diff.

Measured by the test at the tree that landed it: 95 packages: 78 pinned, 0 rebindable, 7 schedulable (5 of them products, 2 fixtures), 10 no-workload, and the five products are the same five named in §4.2.

#!/usr/bin/env python3
"""Eligibility census over the shc app catalogue (docs/proposals/2026-08-11-
runtime-is-the-placement-contract.md §4). Ports three ce classifiers:
ce/core/volume/resolve.go DetectMountType
ce/modules/app/swarm_compat.go swarmOrderingConditions
ce/modules/app/replica_ceiling.go x-shc-scale.max
Run from the shc checkout root: python3 census.py apps
"""
import json, os, re, sys, yaml
APPS = sys.argv[1] if len(sys.argv) > 1 else "apps"
ORDERING = {"service_healthy", "service_completed_successfully"}
SAFELIST = {"/etc/localtime", "/etc/timezone", "/dev/urandom", "/dev/random"}
JINJA_BLOCK = re.compile(r"^\s*\{%-?.*?-?%\}\s*$")
JINJA_EXPR = re.compile(r"\{\{.*?\}\}")
def strip_jinja(text):
# Control flow is DROPPED, not evaluated: the parse keeps the UNION of all
# branch bodies, so mounts are over-reported and never under-reported.
out = []
for line in text.splitlines():
if JINJA_BLOCK.match(line):
continue
line = re.sub(r"\{%-?.*?-?%\}", "", line)
out.append(JINJA_EXPR.sub("JINJA", line))
return "\n".join(out)
def detect_mount_type(source, target, app_dir):
if source.startswith("/"):
return "SYSTEM"
if target == "/tmp" or target.startswith("/tmp/"):
return "RUNTIME"
if source.startswith("./") or source.startswith("../"):
return "FILE"
if app_dir and os.path.exists(os.path.join(app_dir, source)):
return "FILE"
return "DATA"
def classify(app_dir):
doc = yaml.safe_load(strip_jinja(open(os.path.join(app_dir, "compose.yaml")).read()))
if not isinstance(doc, dict):
return None
services = doc.get("services") or {}
bound = set((doc.get("x-shc-volumes") or {}).keys())
f = {"services": len(services), "ordering": [], "data": [], "file": [],
"plat": [], "sock": [], "self_pinned": []}
for name, svc in (services if isinstance(services, dict) else {}).items():
if not isinstance(svc, dict):
continue
for tgt, spec in (svc.get("depends_on") or {}).items() \
if isinstance(svc.get("depends_on"), dict) else []:
if isinstance(spec, dict) and spec.get("condition") in ORDERING:
f["ordering"].append(f"{name}->{tgt}:{spec['condition']}")
for c in ((svc.get("deploy") or {}).get("placement") or {}).get("constraints") or []:
if isinstance(c, str) and ("node.hostname" in c or "node.id" in c):
f["self_pinned"].append(f"{name}:{c}")
for spec in svc.get("volumes") or []:
if not isinstance(spec, str) or ":" not in spec:
continue
src, tgt = spec.split(":")[0], spec.split(":")[1]
mt = detect_mount_type(src, tgt, app_dir)
if mt == "DATA" and src not in bound:
f["data"].append(f"{name}:{src}")
elif mt == "FILE":
f["file"].append(f"{name}:{src}")
elif mt == "SYSTEM":
(f["plat"] if src.startswith("/etc/shc/")
else (f["sock"] if src not in SAFELIST else [])).append(f"{name}:{src}")
reasons = [label for key, label in (("ordering", "ordering"), ("data", "stateful"),
("file", "nodefile"), ("plat", "platmount"),
("sock", "hostsock"), ("self_pinned", "selfpinned"))
if f[key]]
f["verdict"] = ", ".join(reasons) or "ELIGIBLE"
return f
rows, tally = {}, {}
for dirpath, _, filenames in os.walk(APPS):
if "app.yaml" not in filenames or "compose.yaml" not in filenames:
continue
rel = os.path.relpath(dirpath, APPS)
if "/tests/apps/" in "/" + rel + "/": # fixture consumers, not catalogue apps
continue
rows[rel] = classify(dirpath)
tally[rows[rel]["verdict"]] = tally.get(rows[rel]["verdict"], 0) + 1
print(json.dumps({"apps": len(rows), "tally": tally, "rows": rows},
indent=1, sort_keys=True))

Expected at the baselines above: 90 apps, and the three headline numbers of §4.2 fall out as stateful (37) + ordering, stateful (30) + ordering, stateful, nodefile (4) + ordering, stateful, platmount (2) = 73 stateful, of which 36 also ordering, against 17 ELIGIBLE:

{"apps": 90,
"tally": {"ELIGIBLE": 17,
"stateful": 34,
"stateful, nodefile": 2,
"stateful, platmount": 1,
"ordering, stateful": 30,
"ordering, stateful, nodefile": 4,
"ordering, stateful, platmount": 2}}

Cross-check of the ordering set against R1’s method: the two agree on the identical 36 apps, as a set:

Terminal window
grep -rl 'service_healthy\|service_completed_successfully' apps --include=compose.yaml | wc -l # 36
find apps -name compose.yaml | wc -l # 98 (90 non-fixture)
grep -rl 'x-shc-volumes' apps --include=compose.yaml | wc -l # 0
grep -rn 'replicas:' apps --include=compose.yaml | wc -l # 0
grep -rn 'x-shc-scale' -A3 apps --include=compose.yaml | grep -c 'max: *1' # 69
  • docs/decisions/2026-08-11-rebalancer-v1-foundations.md, R1, and the four rulings this page must not contradict
  • docs/architecture/cluster/swarm-contention-map.md §8, where R1 was asked
  • docs/proposals/2026-08-11-placement-ownership-fork.md, the fork this page answers from the product side
  • docs/proposals/2026-08-11-placement-policy.md §3.4–3.5, the never_move and protected shapes, not re-specified here
  • docs/proposals/2026-08-11-rebalance-trigger-and-safety.md, what may fire a move, once §1 is ruled
  • docs/reviews/2026-07-20-drain-does-not-migrate.md, stale: the migrator it describes was rewritten; see §2.3