feat(runtime): unpin the studio platform, retire the Rosetta machinery, and fix a native-build regression

[duplo-darren]

Follow-up to #18 — this is blocker 4 of that review, split out as it suggested: "land the runtime abstraction first and stack this on top … but it has to go in before we ship." #18 is now merged, so this goes up on its own against dev: 3 commits, 10 files.

What this changes

docker-compose.yml pinned the studio image to linux/amd64. That was correct when the image was amd64-only. It no longer is, and the pin is now actively harmful: on Apple Silicon it forces QEMU emulation when a native arm64 layer is already in the manifest — and QEMU cannot run the studio's .NET runtime, which is the failure the Rosetta preflight exists to diagnose. The pin was manufacturing the problem the machinery reports.

The premise, verified

Not forward-looking. The studio tag this kit pins today already carries both arches:

$ docker manifest inspect quay.io/duplocloud/backend:dev-1.0.6-45708c38 | grep -E '"architecture"'
              "architecture": "amd64",
              "architecture": "arm64",

(podman manifest inspect is identical.) So every Apple Silicon user on this tag has been emulating an image they could have run natively.

Four coupled parts — one commit, deliberately

Any subset is broken, which is why they land together:

	Change	Why it cannot land alone
1	platform: ${STUDIO_PLATFORM:-}	The idiom BUILDER_PLATFORM already uses two lines down. Not linux/arm64 — a hard arm64 value breaks amd64 Linux.
2	.env.example pin → commented	Alone, existing users keep linux/amd64 forever: the adoption pass skips keys the example ships blank (run.sh, [ -z "$ex" ] && continue).
3	_runtime.sh unset → return 0	The check treated unset as amd64 to match the old compose default. Left alone, dropping the pin hard-exits every Apple Silicon podman user on a false positive.
4	One-time .env migration	The mechanism in 2 cannot propagate a blank, so the stale pin has to be removed explicitly.

The migration

runtime_migrate_studio_platform removes STUDIO_PLATFORM from a user's .env, and only when it is provably untouched:

.env holds linux/amd64  AND  .env.defaults agrees that was the last-applied default  →  remove
anything else                                                                        →  leave alone

A hand-pinned value is never overridden. When the migration declines, runtime_rosetta_check explains the situation instead — so nobody is silently stuck. It is idempotent, silent unless it changes something, and takes its paths as arguments so the policy is testable without a real .env. Verified against a real 193-line .env: one line removed, remainder byte-identical, second run silent.

What is deleted

_runtime_rosetta_conf_state, _runtime_machine_vmtype, _runtime_machine_conf_provider, _runtime_machine_provider, and the six-branch remediation with its libkrun/applehv diagnosis. scripts/_runtime.sh goes 671 → 540 lines. troubleshooting.md's Apple Silicon entry goes 206 → 71 lines, and its Rosetta/libkrun mentions 45 → 4.

Kept: _runtime_host_arch and runtime_rosetta_active — the two impure seams that let the policy be tested without a VM. runtime_rosetta_check survives at ~25 lines, firing only on an explicit amd64 pin, and says two things: remove the stale pin (nearly every case), and — because unsetting cannot help someone whose registry genuinely carries one arch — that such a tag does still need Rosetta, via Docker Desktop or an applehv machine. That second branch is why the check survives rather than going with the machinery.

Untouched: runtime_machine_check, the undersized-VM preflight. Unrelated to any of this.

Blast radius

• .env is written — the only user-data change here. Guarded as above; the pre-migration value is recoverable from .env.defaults.
• STUDIO_PLATFORM semantics invert: unset now means native, where it used to mean amd64. Anyone with tooling that reads it should know.
• Docs: the sweep was wider than the review listed — faq.md, configuration.md and upgrading.md carried the same stale "amd64-only" claim. Four tests fail if any of it returns.
• .env.example: STUDIO_PLATFORM stays in DEFAULT_KEYS but ships no value, so it is skipped while blank. A future release can re-pin it with no code change; upgrading.md records this.

Testing

65 runtime tests, 135 across the suite, all passing on top of current dev. The 16 conf-state, provider and remediation-message cases go with the code they covered; new ones pin the retained check's two branches, the compose default, the .env.example state, and six migration cases.

Both migration guards are mutation-tested — loosening the value check or the lock check each makes a specific test fail, so neither passes by accident.

Verified on real hardware: a libkrun podman machine, which the old code hard-failed with a recreate-the-VM instruction, now passes silently because the arm64 image needs no translation.

Note for reviewers

This deletes the function fixed by "match a [machine] header that carries a trailing comment" in #18. That fix is not wasted — #18 shipped first and covers anyone who hits it in the interim — but reviewers of both PRs will notice the add-then-delete.

🤖 Generated with Claude Code

[duplo-darren]

Also includes a fourth commit, 7b18fe7: a fix combined in here from #24 (closed as a duplicate of this PR) — builder_dispatch() was calling runtime_resolve unconditionally, before checking DUPLO_BUILD_NATIVE, so RUNTIME=podman in .env broke every containerized extension build regardless of extension (the builder container bind-mounts the whole repo, so the re-entrant build re-reads the host's .env and fatals on a runtime it never needed). Unrelated to the platform-unpin work above it, but zero file overlap with it and no review activity on either PR yet, so combining avoided a second PR for no real benefit. Full details in #24's original description.