Skip to content
SHC Docs

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.


questionanswerwhere
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:23 declares architectures: [amd64] with a measured reason (“qemu-user can’t mmap … crashes at Django import”). The node table 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:

#inputfile:lineeffect
1--runtime <compose|swarm|podman>ce/modules/app/commands/install.go:193, sent as body["runtime"] at :348the operator’s word; the only stated input
2wire enum validationce/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
3edition + licence gatece/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
4cross-ENGINE node guardce/modules/app/runtime_guard.go:135 CheckRuntimeMatchesNode; twin at ce/modules/stack/service.go:1018refuses only podman↔docker-class (X400955RTMPIN). compose↔swarm cross-pins are explicitly ALLOWED; see runtime_guard.go:9-12
5host-bound --node guardce/modules/app/runtime_guard.go:104 CheckNodeTargetPlacementX400956NDLOCL when --node <foreign> is passed on a non-swarm runtime
6prior-evidence fill, only if unsetce/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.

MEASURED: each of these was searched for and is absent:

  • The app. No yaml:"requires" tag exists in either repo; no data["requires"] / data["runtimes"] map read exists either. See §2.1.
  • Any config key. No runtime key in shc/default.yaml; no system.runtime / install.runtime / default_runtime anywhere.
  • The node’s own runtime, on the compose/swarm axis. Input 4 compares only the podman axis. A node whose row says compose accepts a --runtime swarm install 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.runtimes in 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”

Every app.yaml read site in both repos, ce 0796595 / shc 0e5621a79:

decoderfile:linekeys it decodes
repo crawler → catalogue rowce/daemon/services_seams_repo_crawler.go:110-116name, version, description, category, homepage, icon, tags
bundled manifestce/modules/app/bundled.go:33-37name, version, description, category, homepage
detail viewce/modules/app/detail.go:62-67name, version, description, category, homepage, vars
app validatorce/modules/app/validate.go:135-158decodes to map[string]any, then reads only hooks: and crons:
everything elseinject_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.goone 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.

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).

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 ride docker.
  • ce/modules/cluster/local_init.go:229-262: shc init detects it from a live podman socket with no docker endpoint, or from podman on PATH with docker absent.
  • 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 into requires: at load time (get_required_runtimes etc.)

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 running swarm. A stack’s runtime is picked by matching the app’s requires.runtimes against 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_premises class 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:

  1. shc init never detects swarm. ce/modules/cluster/local_init.go:229-262 detectRuntimeFrom returns only compose or podman. A node is only runtime=swarm if the operator typed --runtime swarm (ce/modules/cluster/commands/init.go:530).
  2. Every docker-class Linux node is made a swarm member anyway. ce/modules/cluster/service.go:892-912: with fabric unset or swarm, a non-podman Linux node runs docker swarm init regardless of its recorded runtime.
  3. So compose and swarm coexist on the same node, and cross-mode pins are deliberately allowed (§1.1 input 4).
  4. The real per-node exclusivity is podman vs docker-class, and it is enforced twice: at init (ce/modules/fabric/types.go:93-109 ValidateSelection: the shc fabric excludes the swarm runtime, the swarm fabric excludes podman nodes) and at join (shc/modules/cluster/enroll_handler.go:329-341 validates 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:

fabricruntimes the estate may containmulti-node
swarm (or unset)compose and swarm, on the same docker nodes; no podmanyes
shccompose and podman; no swarmyes
noneany single nodeno

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.


shc 0e5621a79, apps/ + ce builtin/, rendered through the real jinja engine with each app’s own vars.yaml, then through the real app.SwarmLoaderRefusals:

factcount
apps in the catalogue (app.yaml, each with a compose.yaml)98
apps declaring anything about runtimes3 (2 canonical, 1 legacy)
apps the swarm loader REFUSES36
…plus ce builtins refused2 of 4: builtin/traefik (the system ingress) and builtin/postgres
apps whose depends_on the loader accepts and the swarm scheduler then ignores11 more
apps with no start-ordering at all51
apps declaring x-shc-volumes (the storage binding that makes a volume follow the task)0
apps declaring replicas:0
apps declaring x-shc-scale64, across 69 services, every one max: 1 (+3 in ce builtins, also max: 1)
swarm-runtime stacks on either estate0 (per the R1 ruling)
swarm installs verified end to end, ever0 (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 at 0e5621a79. 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).
  • SwarmLoaderRefusals returns 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 the url()/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.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.

Additive. Every one of the 95 undeclared apps keeps working unchanged.

app.yaml
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:

  1. requires.runtimes stays 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.
  2. placement.mobility is a claim about the app, never about the fleet. It is answerable by someone who has read only the app’s own compose.
  3. reason: is mandatory on movable for 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 unsaid

And --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}
  • shc catalog show <app> gains a runtimes row; today the restriction is invisible even to someone who goes looking (§2.1).
  • shc install <app> with no --runtime prints, 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 --runtime fails 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:

  1. 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.
  2. builtin/traefik is 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.
  3. 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.
  4. Every app is single-replica by its own declaration (69 services, all max: 1; 0 replicas:). There is no horizontal-scaling benefit on the table to weigh against (1)–(3).
  5. 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.
  6. 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).


95 apps must acquire a value. Most of it can be derived; the half that matters cannot.

Run at publish time (the catalogue archive build, shc/scripts/build-apps-archives.go) and re-checked at install time on the real render:

signalsourceverdictmeasured today
SwarmLoaderRefusals non-emptyce/modules/app/swarm_compat.go:119, the same function install already runsswarm excluded36 apps + 2 builtins
any surviving depends_onrendered composeswarm excluded (swarm honours no ordering; the loader accepting it is not the same as it working)11 more apps
network_mode:rendered composeswarm excluded, host-coupled1 (fusionpbx, host networking for SIP/RTP)
devices:rendered composeswarm excluded, node-coupled1 (jellyfin, hardware transcode)
cap_add: / sysctls:rendered composeflag for review, not an automatic exclusion3 (mailcow ×2, greenbone)
platform:swarm_compat.go already refuses itswarm excludedfolded 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.

  • mobility. Nothing in a compose file distinguishes “this named volume is my database” from “this named volume is a cache”. x-shc-volumes would 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:

  1. 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.
  2. It must fail loudly on an unrenderable app rather than emit a verdict.
  3. The value written into app.yaml is a published summary, never the authority. install_runner.go:1552 stays exactly where it is; the declaration exists to move the refusal earlier and to make it visible, not to replace the check.
  4. 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 swarm on an app whose render carries a swarm refusal is a build failure, named by app, service and construct.

G2. placement.mobility: movable on an app whose compose declares a named volume with no x-shc-volumes binding is a build failure.

G3. The legacy top-level runtimes: is a build failure, with apps/email/mailcow/app.yaml:13 migrated 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 --force does the re-placing. That is lanes 3–4’s subject, not this one.
  • It does not make movable select swarm. R1 stands until a swarm install is proven end to end (§10 R-L1-6).
  • It does not touch the compose shc move story. The atomic mover and the move journal stay where docs/decisions/2026-08-11-rebalancer-v1-foundations.md put 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.

idquestionthis page’s recommendation
R-L1-1Default for an undeclared app: [compose, podman] (swarm excluded), or all three?[compose, podman], mobility: pinned, §7
R-L1-2Vocabulary: 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-3Does 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-4Legacy 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-5Does 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-6Does 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

  • 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-116 and docs/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.