The runtime is the placement contract
Archived, superseded by the new line (SHC-1092), which removed Swarm.
The runtime is the placement contract
Section titled “The runtime is the placement contract”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 says | what it must say | |
|---|---|---|
| compose | never moves without an operator verb | unchanged, and it is already true by construction (§2) |
| swarm | opts into swarm’s rebalancer | opts 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: swarmis 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_moveflag 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. (a) What compose GUARANTEES
Section titled “2. (a) What compose GUARANTEES”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.
| # | path | moves compose today? | verdict |
|---|---|---|---|
| M1 | shc move <src> <tgt> --node N | yes | ✅ the intended escape hatch; the operator named the deployment |
| M2 | shc node drain <node> | yes | ⚠️ the real exception; see below |
| M3 | shc move --presumed-dead | yes | ✅ explicit, already heavily gated, refuses unless the node’s registry state is unreachable AND a fresh probe fails now |
| M4 | shc recover / restore onto another node | yes | ✅ explicit; reconstructs from an archive rather than relocating |
| M5 | shc node rm / cluster forget / cluster repair sweep | no, REFUSES | ✅ closed by ce modules/cluster/occupancy.go |
| M6 | shc doctor run --fix | no | ✅ closed, MEASURED: no diagnosis under ce modules/doctor/diagnoses/ relocates anything; grep for clone./Move(/drain across that package returns zero non-test hits |
| M7 | health reconcile loop | no | ✅ reconcileStackAction restarts the stack in place |
| M8 | estate rebuild / terraform apply replacing a node | no | ✅ the provider’s node Delete calls cluster forget, which discharges M5’s guard |
| M9 | install-time placement scorer | n/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:
- Drain must enumerate before it moves. Print the deployment list, the
per-row strategy
SelectMoveStrategywill choose, and the fact that every compose row takes the heavy path, then confirm. Today’s--dry-runshape onshc moveis the model. never_movemust 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.protectedalready produces this behaviour and it is worth stating: MEASURED:clone.MovecallsrefuseMoveIfAnyProtectedatce 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”| hazard | what happens to a compose deployment | is that acceptable? |
|---|---|---|
| node drain | moves, via M2, on an explicit verb | yes, with §2.3’s three requirements |
| node failure | does not move. It stays down until a human runs M3 or M4. | ★ yes, and this must be said out loud, not implied |
doctor --fix | never moves (M6) | yes |
| estate rebuild | never moves; removal of an occupied node refuses (M5/M8) | yes |
| daemon restart / reconcile | restarts 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. (b) What swarm OPTS INTO
Section titled “3. (b) What swarm OPTS INTO”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 it | status at HEAD | |
|---|---|---|
| initial placement | swarm’s scheduler | MEASURED: SHC feeds it real input: ApplyResourceQuotas writes deploy.resources.reservations on 327 of 328 services, runtime-independently |
| rebalancing | SHC’s mover (clone.Move, ephemeral strategy) | exists; nothing calls it autonomously |
| reschedule on node failure | swarm | ★ MEASURED: this is the dangerous one, §3.2 |
| eligibility boundary | the runtime declaration | this 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.
4.2 The census: 90 catalogue apps
Section titled “4.2 The census: 90 catalogue apps”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.
| verdict | apps | share |
|---|---|---|
| INELIGIBLE, stateful (unbound DATA mount) | 37 | 41% |
| INELIGIBLE, ordering (also all stateful) | 36 | 40% |
| ELIGIBLE | 17 | 19% |
| total | 90 |
★ And the 17 does not mean what it looks like. Broken down:
| what the “eligible” apps actually are | count |
|---|---|
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/whoami | 2 |
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):
| builtin | verdict | why |
|---|---|---|
traefik | INELIGIBLE: ordering and stateful and host-socket | traefik → traefik-init: service_completed_successfully; acme/static volumes; binds /var/run/docker.sock. The system ingress cannot run on swarm at all. |
postgres | INELIGIBLE: ordering, stateful | postgres → postgres-guard: service_completed_successfully; pgdata |
openobserve | INELIGIBLE: stateful | data |
keycloak | INELIGIBLE: 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”| class | apps | fixable? |
|---|---|---|
| unbound local persistent data | 73 | yes, 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 ordering | 36 | no: 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, supabase | yes: 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 material | 3: 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 composeover 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:
- 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. never_movemust 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.
5.4 The answer
Section titled “5.4 The answer”PROPOSED.
--runtimeis the declaration;never_moveis 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-109ValidateSelectionrefuses exactly two pairs:fabric=shc×runtime=swarm, andfabric=swarm×runtime=podman. On afabric=swarmorfabric=noneestate the per-deployment runtime is unconstrained. - A re-platform in place already has a code path.
--runtimeonshc updatere-platforms (§5.1), andclone.StackMoveRequest.Runtimeis documented as “the engine dialect the move REQUESTED for the target”, soshc movecan 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:
- App author declares
x-shc-volumeson the app’s DATA mounts. Per app. Blocks everything downstream. (Also unblocksStrategyRebindon compose, which is worth having on its own; see §6.4.) - Operator provisions block volumes and re-installs, or moves with
--storage, so the data leaves the per-deployment mounts dir. - Operator re-platforms:
shc move <s> <s> --node N --runtime swarm, which is the only step that is genuinely one command today. - Estate must be on
fabric=swarmorfabric=none. If it is onfabric=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.
7. What to build, in order
Section titled “7. What to build, in order”Ordered by (blocks-others × already-measured-as-broken), not by size.
| # | item | gated on |
|---|---|---|
| 1 | ValidateSelection on the install path (§6.2) | nothing; this is a live gap |
| 2 | Swarm unbound-DATA-mount pin or refusal, P1/P2 (§3.2) | nothing; this is a silent-data-loss gap |
| 3 | Drain enumerate-and-confirm (§2.3 req. 1) | nothing |
| 4 | x-shc-volumes declarations, per app, starting with the flagship set (§6.4) | nothing, pays off under the existing shc move |
| 5 | never_move flag per placement-policy §3.4 | nothing; honoured by drain from day one (§2.3 req. 2) |
| 6 | Placement contract rendered in shc status / shc ls (§5.2) | 5 |
| 7 | Confirmed re-platform on runtime change (§5.1) | 6 |
| 8 | Anything that moves a deployment autonomously | R1 (§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.
8. RULING-OWED
Section titled “8. RULING-OWED”- ★★ R1 vs. this proposal (§1): R1-A / R1-B / R1-C. Ranks everything else.
- Swarm unbound DATA mount (§3.2): pin (P1) or refuse (P2)? P1 recommended.
- 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.
- Does
shc node drainstay a legal mover of pinned deployments? (§2.3). Theoccupancy.goruling says yes; this page asks for it to be restated under the new contract, with enumerate-and-confirm. - Reservation/limit ratios: correcting the brief, MEASURED at ce HEAD:
defaultReservationRatio = 1.0(resource_reservations.go:102) anddefaultLimitRatio = 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.
Appendix A: the census, all 90 apps
Section titled “Appendix A: the census, all 90 apps”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.
| app | svc | ord | data | file | plat | sock | verdict |
|---|---|---|---|---|---|---|---|
| ai/agent-canvas | 2 | 1 | 4 | 0 | 0 | 0 | ordering, stateful |
| ai/dify | 12 | 4 | 7 | 1 | 0 | 0 | ordering, stateful, nodefile |
| ai/graphiti | 2 | 1 | 4 | 0 | 0 | 0 | ordering, stateful |
| ai/librechat | 4 | 1 | 8 | 0 | 0 | 0 | ordering, stateful |
| analytics/matomo | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| analytics/superset | 5 | 3 | 6 | 0 | 0 | 0 | ordering, stateful |
| automation/windmill | 6 | 1 | 2 | 0 | 0 | 0 | ordering, stateful |
| business/medusa | 5 | 5 | 3 | 0 | 2 | 0 | ordering, stateful, platmount |
| cms/wordpress | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| collaboration/huly-nextcloud | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE |
| collaboration/nextcloud | 3 | 0 | 3 | 0 | 0 | 0 | stateful |
| collaboration/nextcloud-picker | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE |
| communication/fusionpbx | 1 | 0 | 1 | 2 | 0 | 0 | stateful, nodefile |
| communication/hookshot | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| communication/matrix | 7 | 1 | 10 | 0 | 0 | 0 | ordering, stateful |
| crm/monica | 2 | 0 | 2 | 0 | 0 | 0 | stateful |
| design/penpot | 5 | 0 | 4 | 0 | 0 | 0 | stateful |
| devops/gitea | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| devops/gitlab | 2 | 0 | 5 | 0 | 0 | 0 | stateful |
| devops/pulp | 9 | 9 | 12 | 0 | 0 | 0 | ordering, stateful |
| devops/sonarqube | 2 | 0 | 5 | 0 | 0 | 0 | stateful |
| documents/paperless | 4 | 0 | 4 | 0 | 0 | 0 | stateful |
| email/mailbox-reconciler | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| email/mailcow | 17 | 15 | 33 | 0 | 0 | 0 | ordering, stateful |
| enterprise/metabase | 2 | 0 | 2 | 0 | 0 | 0 | stateful |
| finance/hyperswitch | 8 | 7 | 2 | 1 | 0 | 0 | ordering, stateful, nodefile |
| fixtures/test-data | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| fixtures/test-simple | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (fixture) |
| fixtures/whoami | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (fixture) |
| identity/ivatar | 2 | 0 | 2 | 3 | 0 | 0 | stateful, nodefile |
| infrastructure/blockscout | 6 | 1 | 3 | 0 | 0 | 0 | ordering, stateful |
| knowledge-base/affine | 4 | 1 | 5 | 0 | 1 | 0 | ordering, stateful, platmount |
| knowledge-base/affine-rs | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE |
| licensing/keygen | 5 | 5 | 3 | 0 | 0 | 0 | ordering, stateful |
| management/gitlab-huly | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE |
| management/huly | 14 | 0 | 2 | 0 | 2 | 0 | stateful, platmount |
| management/huly-matrix-notifier | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| marketing/mautic | 3 | 0 | 12 | 0 | 0 | 0 | stateful |
| marketing/postiz | 4 | 1 | 4 | 0 | 0 | 0 | ordering, stateful |
| media/immich | 5 | 2 | 4 | 0 | 0 | 0 | ordering, stateful |
| media/jellyfin | 3 | 3 | 6 | 0 | 0 | 0 | ordering, stateful |
| media/peertube | 2 | 0 | 3 | 0 | 0 | 0 | stateful |
| monitoring/glitchtip | 2 | 0 | 1 | 0 | 0 | 0 | stateful |
| monitoring/openreplay | 22 | 56 | 18 | 4 | 0 | 0 | ordering, stateful, nodefile |
| monitoring/uptime-kuma | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| networking/netbird | 7 | 1 | 5 | 0 | 0 | 0 | ordering, stateful |
| platform/frappe | 8 | 6 | 22 | 0 | 0 | 0 | ordering, stateful |
| platform/supabase | 11 | 7 | 5 | 4 | 0 | 0 | ordering, stateful, nodefile |
| productivity/docuseal | 2 | 0 | 2 | 0 | 0 | 0 | stateful |
| productivity/journiv | 4 | 5 | 4 | 0 | 0 | 0 | ordering, stateful |
| productivity/shlink | 3 | 0 | 2 | 0 | 0 | 0 | stateful |
| project-management/plane | 11 | 1 | 7 | 0 | 0 | 0 | ordering, stateful |
| security/ciso-assistant | 6 | 2 | 4 | 0 | 0 | 0 | ordering, stateful |
| security/crowdsec | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| security/defectdojo | 7 | 3 | 5 | 0 | 0 | 0 | ordering, stateful |
| security/defectdojo-classic | 7 | 3 | 5 | 0 | 0 | 0 | ordering, stateful |
| security/dependency-track | 3 | 0 | 2 | 0 | 0 | 0 | stateful |
| security/fleet | 5 | 2 | 4 | 0 | 0 | 0 | ordering, stateful |
| security/greenbone | 20 | 13 | 45 | 0 | 0 | 0 | ordering, stateful |
| security/identity-broker | 1 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE |
| security/midpoint | 2 | 1 | 2 | 0 | 0 | 0 | ordering, stateful |
| security/midpoint-classic | 2 | 1 | 2 | 0 | 0 | 0 | ordering, stateful |
| security/vaultwarden | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| security/wazuh | 4 | 2 | 16 | 0 | 0 | 0 | ordering, stateful |
| standalone/clickhouse | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| standalone/ethereum | 2 | 0 | 4 | 0 | 0 | 0 | stateful |
| standalone/external-imap | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-llm | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-mongodb | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-mysql | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-oidc | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-postgres | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-redis | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-s3 | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/external-smtp | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| standalone/gitlab-runner | 2 | 1 | 4 | 0 | 0 | 0 | ordering, stateful |
| standalone/hockeypuck | 3 | 1 | 4 | 0 | 0 | 0 | ordering, stateful |
| standalone/kubo | 2 | 1 | 3 | 0 | 0 | 0 | ordering, stateful |
| standalone/mail | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| standalone/mariadb | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| standalone/mongodb | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| standalone/mysql | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| standalone/nginx | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| standalone/ollama | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| standalone/pmm | 2 | 1 | 2 | 0 | 0 | 0 | ordering, stateful |
| standalone/redis | 1 | 0 | 2 | 0 | 0 | 0 | stateful |
| standalone/s3 | 0 | 0 | 0 | 0 | 0 | 0 | ELIGIBLE (no services) |
| storage/minio | 2 | 0 | 1 | 0 | 0 | 0 | stateful |
| storage/minio-classic | 1 | 0 | 1 | 0 | 0 | 0 | stateful |
| tools/kutt | 3 | 1 | 2 | 0 | 0 | 0 | ordering, stateful |
Appendix B: reproducing the census
Section titled “Appendix B: reproducing the census”★ 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
jinjapackage 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.ParseVolumeBindingsandapp.SwarmLoaderRefusalsare invoked directly, so a change to the product’s idea of a mount reaches the census without a second implementation to keep in step. OnlysystemMountSafelistis 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(postgresandtraefik); the other three are ordering-clean and add nothing to this count.
- 95 packages against this page’s 90: the FIVE built-ins join the walk
(
- It names a fourth class,
rebindable: durable state whose every DATA mount is declared inx-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) + 1print(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:
grep -rl 'service_healthy\|service_completed_successfully' apps --include=compose.yaml | wc -l # 36find apps -name compose.yaml | wc -l # 98 (90 non-fixture)grep -rl 'x-shc-volumes' apps --include=compose.yaml | wc -l # 0grep -rn 'replicas:' apps --include=compose.yaml | wc -l # 0grep -rn 'x-shc-scale' -A3 apps --include=compose.yaml | grep -c 'max: *1' # 69Related
Section titled “Related”docs/decisions/2026-08-11-rebalancer-v1-foundations.md, R1, and the four rulings this page must not contradictdocs/architecture/cluster/swarm-contention-map.md§8, where R1 was askeddocs/proposals/2026-08-11-placement-ownership-fork.md, the fork this page answers from the product sidedocs/proposals/2026-08-11-placement-policy.md§3.4–3.5, thenever_moveandprotectedshapes, not re-specified heredocs/proposals/2026-08-11-rebalance-trigger-and-safety.md, what may fire a move, once §1 is ruleddocs/reviews/2026-07-20-drain-does-not-migrate.md, stale: the migrator it describes was rewritten; see §2.3