Runtime declaration and selection: how a runtime gets chosen, and what an app may say about it
Status: open design. An app cannot yet declare the runtimes it needs (§6 to §9 are not built), and the Swarm parts went with the new line (SHC-1092). Six rulings are owed (§10).
Baselines. shc main 0e5621a79, ce main 0796595, both fetched and
read 2026-08-11. Every count in this page was produced by executing code
against those trees, not by reading it; the harness and its raw output are in
docs/proposals/evidence/2026-08-11-runtime-declaration/.
Read first: docs/decisions/2026-08-11-rebalancer-v1-foundations.md. Its
R1 is RULED: runtime: swarm is LEGACY / SECOND-CLASS, and this page is
written to be consistent with it, not to reopen it.
0. The five answers, in one place
Section titled “0. The five answers, in one place”| question | answer | where |
|---|---|---|
How is the runtime chosen at shc install? | Six inputs. The app is not one of them, and three are invisible until they refuse. | §1 |
What enforces requires.runtimes? | Nothing. Zero decoders read the key. requires.runtimes: [banana] validates clean. | §2 |
Legacy runtimes: vs canonical requires.runtimes:? | Both inert. mailcow (the app the owner named) has no working restriction. | §3 |
| Can one estate run compose on one node and swarm on another? | Wrong shape of question. compose and swarm run on the same nodes; the only per-node exclusivity is podman vs docker-class. | §4 |
| What should an app be able to declare? | A HARD capability list (requires.runtimes, finally read) plus placement.mobility (“am I safe to move”) because “preferred runtime” asks the author a question about the operator’s fleet. | §6 |
And one live finding the design does not need but the product does:
★
requires:is unread in its entirety, not just on the runtimes axis.apps/identity/ivatar/app.yaml:23declaresarchitectures: [amd64]with a measured reason (“qemu-user can’t mmap … crashes at Django import”). Thenodetable has no architecture column (ce/migrations/20260727022830_auto.sql:516), so there is nothing to compare it against even if something read it. On an arm64 node ivatar installs and then crashes. MEASURED.
1. The resolution ladder as it actually is
Section titled “1. The resolution ladder as it actually is”1.1 The six inputs, in the order they fire
Section titled “1.1 The six inputs, in the order they fire”MEASURED, ce 0796595:
| # | input | file:line | effect |
|---|---|---|---|
| 1 | --runtime <compose|swarm|podman> | ce/modules/app/commands/install.go:193, sent as body["runtime"] at :348 | the operator’s word; the only stated input |
| 2 | wire enum validation | ce/modules/app/types.go:206 validate:"omitempty,oneof=compose swarm podman" (same tag in stack/types.go:134, clone/types.go:69,127, cluster/types.go:289, logs/types.go:87, backup/types.go:1214) | rejects anything outside the three names; empty is legal |
| 3 | edition + licence gate | ce/modules/app/runtime_gate.go:46 (CE: swarm refuses, X403977SWMEEO) → replaced at package-load by shc/modules/app/runtime_gate.go:20; EE gates swarm on the Pro clustering entitlement (shc/modules/app/runtime_gate.go:42) | in CE, --runtime swarm refuses for every app |
| 4 | cross-ENGINE node guard | ce/modules/app/runtime_guard.go:135 CheckRuntimeMatchesNode; twin at ce/modules/stack/service.go:1018 | refuses only podman↔docker-class (X400955RTMPIN). compose↔swarm cross-pins are explicitly ALLOWED; see runtime_guard.go:9-12 |
| 5 | host-bound --node guard | ce/modules/app/runtime_guard.go:104 CheckNodeTargetPlacement | X400956NDLOCL when --node <foreign> is passed on a non-swarm runtime |
| 6 | prior-evidence fill, only if unset | ce/modules/app/install_runner.go:274-285 → RuntimeFromEvidence (ingress_runtime.go:95) | a manifest sidecar recording swarm re-arms swarm on a bare update; deliberately after the edition gate |
If nothing said anything, the runtime stays the empty string, and empty is
preserved all the way to the column (ce/modules/stack/service.go:906, guarded
by ce/modules/app/runtime_unsaid_is_not_compose_test.go). Empty then behaves
as docker-class compose at ce/core/runtimecmd/runtimecmd.go:48-79 and at the
deploy switch ce/modules/app/install_runner.go:1552.
★ “Unsaid” is a first-class value in this codebase and the design must keep it that way. Two separate defects were fixed by refusing to coerce empty→compose; any new resolver that folds them re-opens both.
1.2 What is NOT an input
Section titled “1.2 What is NOT an input”MEASURED: each of these was searched for and is absent:
- The app. No
yaml:"requires"tag exists in either repo; nodata["requires"]/data["runtimes"]map read exists either. See §2.1. - Any config key. No
runtimekey inshc/default.yaml; nosystem.runtime/install.runtime/default_runtimeanywhere. - The node’s own runtime, on the compose/swarm axis. Input 4 compares
only the podman axis. A node whose row says
composeaccepts a--runtime swarminstall without complaint, by design (§4). - The node’s architecture. No column exists.
1.3 The one thing that does stop a swarm install of an unfit app
Section titled “1.3 The one thing that does stop a swarm install of an unfit app”ce/modules/app/install_runner.go:1552-1559:
if opts.Runtime == string(RuntimeSwarm) { if refusals := SwarmLoaderRefusals(rendered); len(refusals) > 0 { … return X400073SWMXLT(opts.AppName, lines) // "install it with --runtime compose" }}This is real, it is the right check, and it is in the wrong phase.
ce/modules/app/router.go:1425-1454 is explicit: Phase 1 (synchronous) writes
the durable StackModel intent row, Phase 2 (a detached goroutine) runs the
deploy. SwarmLoaderRefusals fires in Phase 2. So an operator who types
shc install mailcow --runtime swarm gets a persisted deployment row and a
failed operation, not a 4xx refusal, and the Phase-1 comment
(router.go:1424-1427) says validation errors are supposed to surface as 4xx
before the caller gets an operation id.
F3 (P3, MEASURED). A swarm-unfit install leaves a deployment row behind. Reading
requires.runtimesin Phase 1 is the cheapest way to close it (§6.4).
2. What enforces requires.runtimes: nothing
Section titled “2. What enforces requires.runtimes: nothing”2.1 The decoder inventory (MEASURED)
Section titled “2.1 The decoder inventory (MEASURED)”Every app.yaml read site in both repos, ce 0796595 / shc 0e5621a79:
| decoder | file:line | keys it decodes |
|---|---|---|
| repo crawler → catalogue row | ce/daemon/services_seams_repo_crawler.go:110-116 | name, version, description, category, homepage, icon, tags |
| bundled manifest | ce/modules/app/bundled.go:33-37 | name, version, description, category, homepage |
| detail view | ce/modules/app/detail.go:62-67 | name, version, description, category, homepage, vars |
| app validator | ce/modules/app/validate.go:135-158 | decodes to map[string]any, then reads only hooks: and crons: |
| everything else | inject_traefik.go, launcher.go, sso_redirect.go, ungated_paths.go, connection_required.go, vars_validate.go, var_types.go, system_app_pin.go, post_install_hooks.go, config_redact.go, login_path_postcheck.go, cert_delivery_wiring.go, secret_var_heal.go, browse_facts.go, test/service.go | one concern each; none touches requires |
The union of every yaml:"…" tag under ce/modules/app/ contains no
requires and no runtimes. Neither does shc’s side. There is no map-key
read either.
The catalogue’s Requires field is a different thing. ce/modules/catalog/types.go:151
and service.go:575 requirementsOf build a human-readable list from
required plugs and whether the app needs typed input. It never sees
app.yaml’s requires:. So an operator cannot even see the restriction in
shc catalog show.
2.2 The executed probe
Section titled “2.2 The executed probe”Not read, run. Three synthetic apps through the real
app.ValidateAppDir (harness + raw output in
docs/proposals/evidence/2026-08-11-runtime-declaration/):
canonical requires.runtimes valid=true errors=[] warnings=[]legacy top-level runtimes valid=true errors=[] warnings=[]nonsense runtime value valid=true errors=[] warnings=[]requires.runtimes: [banana] is accepted silently. The key is not merely
unenforced, it is untyped and unspell-checked.
F1 (P2, MEASURED). Three catalogue apps carry runtime restrictions that do nothing:
apps/identity/ivatar/app.yaml:18[compose, swarm],apps/security/dependency-track/app.yaml:40[compose],apps/email/mailcow/app.yaml:13[compose](legacy spelling).
2.3 Podman
Section titled “2.3 Podman”The owner named it explicitly, so: podman is a third first-class value, not an alias of compose. MEASURED:
ce/modules/node/types.go:38-46:RuntimeCompose | RuntimeSwarm | RuntimePodman.ce/core/runtimecmd/runtimecmd.go:48-79: podman is the only non-docker-class value:podman-compose …/podman …;"compose","swarm"and""all ridedocker.ce/modules/cluster/local_init.go:229-262:shc initdetects it from a live podman socket with no docker endpoint, or frompodmanon PATH withdockerabsent.ce/modules/fabric/types.go:104-106: the swarm fabric excludes podman nodes (“podman cannot join a swarm or attach to overlay networks”).ce/modules/completion/service.go:66: the shell-completion enum is{"compose", "podman", "swarm"}.
3. Legacy vs canonical: both inert, and the doc names a function that does not exist
Section titled “3. Legacy vs canonical: both inert, and the doc names a function that does not exist”docs/app-development/app-definition.md:291-293 says:
Legacy top-level
runtimes:,architectures:,platforms:are merged intorequires:at load time (get_required_runtimesetc.)
get_required_runtimes exists nowhere in either repo at HEAD, not in Go,
and there is no Python left in ce at all (0 .py files; shc has 9, all
app-internal or scripts). The only surviving mention of the symbol is that
sentence. The merge it describes was a Python-era behaviour that did not
survive the Go port, and the doc kept describing it.
★ So mailcow’s restriction is silently inert, and so is the canonical
spelling. The distinction between the two forms is currently a distinction
between two ways of writing nothing. apps/security/dependency-track/tests/tests.bats:344
asserts the legacy form is a defect, correctly, but by hand, in one app’s own
test, because there is no guard.
And the same doc set describes an enforcement model that does not exist.
docs/guide/getting-started/concepts.md:98-111:
One cluster may have a mix: some nodes running
compose, others runningswarm. A stack’s runtime is picked by matching the app’srequires.runtimesagainst what the target node supports. […] This is a hard constraint, not a hint.
and cites X400956NOSWPL for the empty-swarm-pool case. X400956NOSWPL does
not exist in the codebase. The actual guard
(ce/modules/app/runtime_guard.go:9-12) says the opposite of “hard constraint”:
swarm ↔ compose cross-mode pins stay ALLOWED; every SHC node is a swarm-cluster member […] (the documented relaxation of the old strict guard).
F2 (P2, MEASURED). Two doc pages describe a strict per-node runtime model, a merge function, and an error code, none of which exist. This is the
docs_lag_code_stale_premisesclass again; the docs fix is owed regardless of which design below is chosen.
4. The mixed-estate answer, which shapes everything else
Section titled “4. The mixed-estate answer, which shapes everything else”The owner asked whether one estate can genuinely run compose on one node and swarm on another. MEASURED, the answer is that the question has the wrong shape:
shc initnever detectsswarm.ce/modules/cluster/local_init.go:229-262detectRuntimeFromreturns onlycomposeorpodman. A node is onlyruntime=swarmif the operator typed--runtime swarm(ce/modules/cluster/commands/init.go:530).- Every docker-class Linux node is made a swarm member anyway.
ce/modules/cluster/service.go:892-912: with fabric unset orswarm, a non-podman Linux node runsdocker swarm initregardless of its recorded runtime. - So compose and swarm coexist on the same node, and cross-mode pins are deliberately allowed (§1.1 input 4).
- The real per-node exclusivity is podman vs docker-class, and it is
enforced twice: at init (
ce/modules/fabric/types.go:93-109ValidateSelection: theshcfabric excludes the swarm runtime, theswarmfabric excludes podman nodes) and at join (shc/modules/cluster/enroll_handler.go:329-341validates the joiner’s runtime against the leader’s fabric posture).
Conclusion (MEASURED). A mixed estate is real but on a different axis than the docs claim. The topology matrix is:
| fabric | runtimes the estate may contain | multi-node |
|---|---|---|
swarm (or unset) | compose and swarm, on the same docker nodes; no podman | yes |
shc | compose and podman; no swarm | yes |
none | any single node | no |
There is no in-place flip between fabrics; shc clone / shc move --runtime
is the documented conversion path. That is a genuine constraint the design
below has to live inside, not something to design around.
★ Consequence for the owner’s question. “Which runtime does this install get?” is not a question about which node answered. It is a per-deployment choice, made on nodes that can serve either. That is why the app is the right place to constrain it, and why constraining it by node runtime (what the docs describe) would be answering a question nobody asked.
5. The corpus, measured
Section titled “5. The corpus, measured”shc 0e5621a79, apps/ + ce builtin/, rendered through the real jinja
engine with each app’s own vars.yaml, then through the real
app.SwarmLoaderRefusals:
| fact | count |
|---|---|
apps in the catalogue (app.yaml, each with a compose.yaml) | 98 |
| apps declaring anything about runtimes | 3 (2 canonical, 1 legacy) |
| apps the swarm loader REFUSES | 36 |
| …plus ce builtins refused | 2 of 4: builtin/traefik (the system ingress) and builtin/postgres |
apps whose depends_on the loader accepts and the swarm scheduler then ignores | 11 more |
| apps with no start-ordering at all | 51 |
apps declaring x-shc-volumes (the storage binding that makes a volume follow the task) | 0 |
apps declaring replicas: | 0 |
apps declaring x-shc-scale | 64, across 69 services, every one max: 1 (+3 in ce builtins, also max: 1) |
| swarm-runtime stacks on either estate | 0 (per the R1 ruling) |
| swarm installs verified end to end, ever | 0 (per the R1 ruling) |
The 36 refused: affine agent-canvas blockscout ciso-assistant defectdojo defectdojo-classic dify fleet frappe gitlab-runner graphiti greenbone hockeypuck hyperswitch immich jellyfin journiv keygen kubo kutt librechat mailcow matrix medusa midpoint midpoint-classic netbird openreplay plane pmm postiz pulp supabase superset wazuh windmill.
The 11 silently degraded: nextcloud penpot gitlab paperless huly mautic peertube glitchtip dependency-track ethereum minio.
Three notes on the numbers, so nobody re-derives them badly:
- 36 of 98, not 37 of 99. The R1 decision measured 37/99 at an earlier
tree; the catalogue moved by one app.
grep -rl 'service_healthy\|service_completed_successfully' apps --include=compose.yaml | wc -l→ 36 at0e5621a79. The conclusion is unchanged. - The refusal set is identical at default vars and with every integration plugged in. Both passes returned the same 36. That is a property of today’s corpus, not a theorem (§8.3).
SwarmLoaderRefusalsreturns an empty slice on a compose it cannot parse (ce/modules/app/swarm_compat.go:117-119, deliberately). A first pass of this harness rendered 27 apps to nothing, because the render context was missing theurl()/host()/port()callables the daemon injects (ce/modules/app/install_runner.go:995-1008), and every one of those 27 came back “clean”. Any derivation tool that renders differently from the daemon silently certifies apps as swarm-safe. This is the single largest hazard in §8.
★ What the corpus says about swarm, said plainly. Swarm cannot host 37% of
the catalogue or the ingress; it silently drops ordering for 11% more; not one
app has declared the storage binding that would let a rescheduled task find its
data, so the default swarm path (ce/modules/app/install_runner.go:4094)
provisions a fresh per-node volume; a reschedule is a data fork; and every
app in the catalogue is single-writer by its own declaration. This is R1’s
evidence, re-measured independently and agreeing.
6. PROPOSED: what an app may declare
Section titled “6. PROPOSED: what an app may declare”6.1 “Preferred” is the wrong noun, and the owner’s own contract says why
Section titled “6.1 “Preferred” is the wrong noun, and the owner’s own contract says why”The owner’s standing model: the runtime choice IS the placement contract. compose = pinned, moves only by an explicit operator verb. swarm = opted into automatic placement.
If that is true (and this page treats it as settled) then an app that “prefers swarm” is not expressing a preference about container engines. It is asserting “I am safe to move”, and an app that “prefers compose” is asserting “pin me”. Those are claims about the application: does it hold a single-writer volume, does it need start ordering, does it bind a host device, is its licence keyed to a hostname.
“Which runtime do you prefer” asks the app author a question about the
operator’s fleet: whether it is clustered, which fabric it chose, whether
clustering is licensed, whether any node can even schedule swarm. An author
cannot know any of that, and a catalogue of 98 answers to it would be 98
guesses.
★ So the vocabulary should be mobility, and the runtime should be derived
from it. That also survives R1 intact: today movable selects nothing,
because nothing is proven; the day a swarm install is proven end to end,
movable becomes the thing the resolver reads, and no app.yaml changes.
6.2 The schema
Section titled “6.2 The schema”Additive. Every one of the 95 undeclared apps keeps working unchanged.
requires: # HARD capability list: where this app CAN run. Unchanged spelling; # this proposal's contribution is that something finally reads it. # Omitted => derived (§7). runtimes: [compose, podman]
placement: # What the app says about ITSELF. The resolver turns this into a runtime. # pinned: my bytes must not move without an operator verb (DEFAULT) # movable: I am safe for a scheduler to re-place at any time mobility: pinned # REQUIRED when mobility: movable. One line, in the author's words. # An unjustified `movable` is the exact claim this whole page exists # because nobody checked. reason: "stateless; all state in the plugged postgres"Three deliberate properties:
requires.runtimesstays a hard restriction and stays the canonical spelling. It is the key two apps already use correctly, the key dependency-track’s bats already asserts, and the key the docs already describe. Nothing is renamed.placement.mobilityis a claim about the app, never about the fleet. It is answerable by someone who has read only the app’s own compose.reason:is mandatory onmovablefor the same reason SHC makes an author justify every other escape hatch: an unexplained claim is indistinguishable from a default nobody thought about.
6.3 Resolution, with the new inputs folded in
Section titled “6.3 Resolution, with the new inputs folded in”The ladder of §1.1 gains two steps and loses none:
--runtime <x> explicit; wins over everything but the gates ↓ (unset) prior evidence (sidecar / row) only-if-unset; an existing deployment keeps its runtime ↓ (unset, first install) requires.runtimes ∩ estate-capable ∩ licensed ← NEW, HARD ↓ (still more than one candidate) placement.mobility ← NEW, SOFT · pinned → the host-bound runtime the node speaks (compose | podman) · movable → the scheduler-owned runtime, IF AND ONLY IF ruled available (§10 R-L1-6) ↓ "" (unsaid), behaves as docker-class compose, and stays recorded as unsaidAnd --runtime is checked against requires.runtimes in Phase 1, before
the intent row is written, the fix for F3. New coded error, number to be
allocated:
X4000?? APPRTNS app {app} declares requires.runtimes {declared} and cannot run under {requested}; install it with --runtime {suggest}6.4 What the operator sees
Section titled “6.4 What the operator sees”shc catalog show <app>gains aruntimesrow; today the restriction is invisible even to someone who goes looking (§2.1).shc install <app>with no--runtimeprints, once, which runtime it chose and why (declared,derived,inherited from the existing deployment). The install spinner is already synthetic; one honest line costs nothing.- A refused
--runtimefails at the CLI with the app named, not as a failed operation with a deployment row behind it.
7. PROPOSED: the default when nothing is declared
Section titled “7. PROPOSED: the default when nothing is declared”Recommendation: silence means [compose, podman] (swarm excluded) and
mobility: pinned.
Argued against the measurements, not against taste:
- 36 of 98 apps and 2 of 4 system builtins cannot render on swarm at all. The refusal exists and works; a default of “swarm is fine unless the app said otherwise” makes the product answer “yes” for 37% of a catalogue where the code answers “no” one phase later.
builtin/traefikis one of the two. A default that admits swarm for undeclared apps admits it for the system ingress, which cannot deploy that way. The default must not be one the system stack itself fails.- 0 apps declare
x-shc-volumes. On swarm the unbound path (ce/modules/app/install_runner.go:4094-4116) keeps the named-volume reference and swarm provisions it per node. Every catalogue app on swarm today is one reschedule away from an empty volume. A default that opts an app into automatic placement without a bound volume opts it into silent data loss. - Every app is single-replica by its own declaration (69 services,
all
max: 1; 0replicas:). There is no horizontal-scaling benefit on the table to weigh against (1)–(3). - 0 swarm installs have ever been verified end to end, on either estate. A default must be the configuration that is proven, and compose is the only one that is.
- R1 already ruled swarm legacy/second-class. A permissive default would quietly contradict a landed ruling.
And pinned is not a limitation to apologise for. It is the owner’s stated
advantage over Kubernetes: the platform knows exactly where the bytes are, and
they move when a human says shc move. The default should say that
confidently.
The counter-argument, stated fairly: excluding swarm from the default means the
~50 apps that could run on swarm today (the 51 with no start-ordering at all,
minus fusionpbx’s host networking) need an explicit line to reach it. That is
the correct trade: a declaration is one line, a silent wrong default is a data
fork, and none of those ~50 has a bound volume yet anyway (§7, point 3).
8. PROPOSED: the backfill, by derivation
Section titled “8. PROPOSED: the backfill, by derivation”95 apps must acquire a value. Most of it can be derived; the half that matters cannot.
8.1 What derives mechanically
Section titled “8.1 What derives mechanically”Run at publish time (the catalogue archive build,
shc/scripts/build-apps-archives.go) and re-checked at install time on the
real render:
| signal | source | verdict | measured today |
|---|---|---|---|
SwarmLoaderRefusals non-empty | ce/modules/app/swarm_compat.go:119, the same function install already runs | swarm excluded | 36 apps + 2 builtins |
any surviving depends_on | rendered compose | swarm excluded (swarm honours no ordering; the loader accepting it is not the same as it working) | 11 more apps |
network_mode: | rendered compose | swarm excluded, host-coupled | 1 (fusionpbx, host networking for SIP/RTP) |
devices: | rendered compose | swarm excluded, node-coupled | 1 (jellyfin, hardware transcode) |
cap_add: / sysctls: | rendered compose | flag for review, not an automatic exclusion | 3 (mailcow ×2, greenbone) |
platform: | swarm_compat.go already refuses it | swarm excluded | folded into the 36 (blockscout, fleet) |
That derivation reaches 48 of 98 apps as compose-only with no author
involvement (36 refused + 11 ordering-only + fusionpbx; jellyfin’s
devices: is already inside the 36). Which is the whole point: the backfill is
not 95 judgement calls, it is 48 mechanical answers and 50 judgement calls,
and of those 50, the only field a human must actually fill in is
placement.mobility, because requires.runtimes for a swarm-clean app is
exactly what the derivation just computed.
8.2 What cannot be derived, ever
Section titled “8.2 What cannot be derived, ever”mobility. Nothing in a compose file distinguishes “this named volume is my database” from “this named volume is a cache”.x-shc-volumeswould say it, and 0 apps declare it. Mobility must be authored. This is the irreducible half.- Host-keyed licences, fixed-IP requirements, upstream clustering assumptions. Not expressible in compose.
architectures:: derivable from image manifests in principle, but there is no node column to compare against (§0), so it stays inert either way. Separate ruling (§10 R-L1-5).
8.3 The hazard the derivation must be built around
Section titled “8.3 The hazard the derivation must be built around”★ A derivation that renders the compose differently from the daemon will
certify unfit apps as fit, silently. MEASURED in this session: a harness
missing the url() / host() / port() / path() callables the daemon
injects (ce/modules/app/install_runner.go:995-1008) failed to render 27 of 98
apps, and SwarmLoaderRefusals returns empty on an unparseable compose by
design, so all 27 read as clean. The refusal set only became correct once the
harness matched the daemon’s context.
Therefore:
- The derivation must call the same render + the same
SwarmLoaderRefusals, from a package that shares the daemon’s context builder. A standalone script is the wrong shape. - It must fail loudly on an unrenderable app rather than emit a verdict.
- The value written into
app.yamlis a published summary, never the authority.install_runner.go:1552stays exactly where it is; the declaration exists to move the refusal earlier and to make it visible, not to replace the check. - Because the render depends on vars, the derivation is per-render. Both passes of the corpus (default vars, and every integration plugged) returned the same 36, but that is an observation about today’s 98 apps and must be re-run per publish, not assumed.
8.4 Should a guard refuse an app that declares nothing?
Section titled “8.4 Should a guard refuse an app that declares nothing?”Recommendation: no. Refuse a CONTRADICTION instead.
- Refusing undeclared apps breaks 95 packages at once and buys nothing the derivation does not already give.
- The failure mode actually measured is not “nobody declared”; it is
“somebody declared and nothing checked”. ivatar’s
[compose, swarm]is true today by accident, and[banana]would pass too.
So the guard to build is a catalogue fitness function:
G1. For every app, DERIVE the runtime set (§8.1). If the app DECLARES one, the declared set must be a subset of the derived set. A declared
swarmon an app whose render carries a swarm refusal is a build failure, named by app, service and construct.G2.
placement.mobility: movableon an app whose compose declares a named volume with nox-shc-volumesbinding is a build failure.G3. The legacy top-level
runtimes:is a build failure, withapps/email/mailcow/app.yaml:13migrated in the same commit. A silently ignored legacy spelling is precisely the class this page documents; leaving it tolerated re-arms it.★ G0, and do not skip it. Per
fitness_guards_scanned_nothing, each guard asserts a non-empty corpus first. A guard that scans zero apps and reports green is how this whole surface stayed broken.
G1 is what apps/security/dependency-track/tests/tests.bats:326-345 is already
doing by hand for one app. Generalising it is the cheapest real win on this
page.
9. What this proposal deliberately does not do
Section titled “9. What this proposal deliberately does not do”- It does not build a swarm rebalancer. Per the owner’s standing context,
SHC supplies the trigger, the eligibility predicate, the safety envelope and
the audit trail;
docker service update --forcedoes the re-placing. That is lanes 3–4’s subject, not this one. - It does not make
movableselect swarm. R1 stands until a swarm install is proven end to end (§10 R-L1-6). - It does not touch the compose
shc movestory. The atomic mover and the move journal stay wheredocs/decisions/2026-08-11-rebalancer-v1-foundations.mdput them. - It does not add a node-runtime match rule. §4 shows why that model is wrong; the docs that describe it need correcting, not implementing.
10. Rulings owed
Section titled “10. Rulings owed”| id | question | this page’s recommendation |
|---|---|---|
| R-L1-1 | Default for an undeclared app: [compose, podman] (swarm excluded), or all three? | [compose, podman], mobility: pinned, §7 |
| R-L1-2 | Vocabulary: placement.mobility: pinned|movable, or a plain prefers.runtime:? | mobility; it is answerable by the author; a runtime preference is not (§6.1) |
| R-L1-3 | Does a --runtime that violates requires.runtimes refuse at the CLI (Phase 1, no row written) or warn? | Refuse, Phase 1, new coded error (§6.3) |
| R-L1-4 | Legacy top-level runtimes:: hard build failure now, or tolerated for one release? | Hard failure, with mailcow migrated in the same commit (§8.4 G3) |
| R-L1-5 | Does requires.architectures get a node.architecture column so it stops being inert too, or is it deleted from the docs? | Out of this lane’s scope; it must be one or the other; a third live-but-inert key is not an option (§0) |
| R-L1-6 | Does mobility: movable ever auto-select swarm, and what is the gate: a proven end-to-end swarm install, a bound x-shc-volumes, or both? | Both, and not before. Until then movable is declarative and G2 makes it testable |
Related
Section titled “Related”docs/decisions/2026-08-11-rebalancer-v1-foundations.md: R1 RULED; read before this page.docs/architecture/cluster/swarm-contention-map.md§8: where R1 is recorded.docs/proposals/2026-08-11-placement-policy.md,docs/proposals/2026-08-11-placement-ownership-fork.md,docs/proposals/2026-08-11-rebalance-trigger-and-safety.md: the sibling lanes; both carry SUPERSEDED-IN-PART banners.docs/guide/getting-started/concepts.md:78-116anddocs/app-development/app-definition.md:278-293: both wrong at HEAD (§3); the correction is owed whichever design lands.docs/proposals/evidence/2026-08-11-runtime-declaration/: the harness and its raw output.