RFC: full agnostic CLI core — iOS to labelle-ios, backend identity, target names, SDL (RFC #406 final phase) #471

Status: draft, awaiting the owner's decisions (§6). This is the final phase of RFC #406: a CLI core with no platform, store or backend knowledge. It makes RFC #466 §9 concrete.

Owner decisions already taken (2026-09-27):

• iOS is extracted into a new provider, labelle-ios, the way Android went to labelle-android.
• This phase starts in parallel with the web phase (RFC: web/wasm leaves the CLI core (RFC #406, web phase) #466). Items marked NOW touch no file that A2 (feat: browser-watch supervision for labelle run --watch (RFC #466 PR A2) #470) or B edit.

The research is read-only, against origin/main:

A2 is the open PR cli#470.

0. Findings that shape the plan

1. iOS already depends on a provider, and none exists.
   • labelle ios … and --platform=ios both go through target resolution, which refuses a target with no pinned owner (pipeline/args_resolve.zig:28-40, provider_targets.zig:53-83).
   • The registry has owners only for android and wasm.
   • So today iOS works only with a hand-made provider that owns ios. There are no iOS users to break.
   • A provider's replace run already takes precedence over the core iOS branch (pipeline/run.zig:188-192 runs before the .ios branch at :327).
   • So labelle-ios can be built and used against today's CLI main (contract 1.3) with no CLI change.
2. Only sokol builds iOS.
   • sokol declares .capabilities .ios, .platforms.ios and .frameworks.ios (backend.manifest.v2.zon:29-38,95,118-127). Its hook finds the SDK with xcrun and reads -Ddevice.
   • bgfx, raylib, sdl and wgpu declare no iOS.
   • No repo has iOS CI, so the path has never run end to end on this toolchain line. The first iOS task is a spike, not a port.
   • The legacy code also assumes zig-out/bin/game (ios.zig:15), but the assembler names the exe after the project (assembler#362).
3. The assembler has already opened backend resolution.
   • .backend_package accepts any package (config.zig:1216-1228), and third-party backends go through the manifest (isEnumTagBacked, :1640-1660).
   • The enum is only a shorthand for first-party packages (builtinProvider, :1430-1510), with default_backend = .bgfx (:1533).
   • What's missing is a way for the CLI to ask the assembler what a project resolves to.
4. Latent bug that shows why that query is needed.
   • The CLI names the target dir @tagName(parsed.backend)_<target> (pipeline.zig:162).
   • The assembler uses backendName()_<platform> (main.zig:270, root.zig:427), which is the package name.
   • A third-party .backend_package = .{ .name = "acme" } project with no .backend gets .labelle/bgfx_desktop from the CLI and .labelle/acme_desktop from the assembler.
5. The assembler already validates backend × target: it derives .wasm/.android/.ios requirements from the platform (capabilities.zig:69-77) and checks them against the manifest (root/provider_contracts.zig). This is RFC: web/wasm leaves the CLI core (RFC #406, web phase) #466's D13 verification. The CLI needs no table.
6. Platform names are deep in the assembler; the CLI needs them only through the shared schema.
   • The assembler has a Platform enum (config.zig:72), Capability.{wasm,android,ios}, AssetCompression{desktop,android,ios,web}, and IosConfig (parsed, but never read by codegen).
   • It also has about 40 cfg.platform branches in codegen and the manifest splices.
   • The CLI can go agnostic without rewriting the assembler's codegen. Making the codegen target-generic is a separate assembler RFC (D8).
7. The SDL move has a discovery gap.
   • Hooks come only from .plugins (provider_dispatch.zig:150). The resolved backend package isn't discovered as a provider.
   • SDL2 is needed by the sdl backend and by the gamepad source that raylib, sokol and bgfx use.
   • bgfx, raylib and sokol read LABELLE_SDL2_LIB. labelle-sdl doesn't (it uses Homebrew or -Dsdl-prefix) and has no Windows CI.
   • FP sets .gamepad = .none, so the SDL work cannot break FP.
8. Two allowlist entries are free. stb_image_impl.c is flagged only by a comment naming bgfx, and stb_image.h by one upstream comment. Many other entries are test fixtures or comments only (§1e).
9. Allowlist count: 50 on main. feat: browser-watch supervision for labelle run --watch (RFC #466 PR A2) #470 (A2) brings it to 44. RFC: web/wasm leaves the CLI core (RFC #406, web phase) #466 §9 expects 32 after B.

1. Inventory (cli e2e0e85 unless noted)

1a. iOS

1b. Backend identity (cli#432)

The assembler stays the registry of first-party backends: the Backend enum, builtinProvider, effectiveGamepad, parseBackend.

1c. Platform enum and shared schema

• CLI:
  • project_config.zig:37-66 (Platform, AssetCompression.formatFor);
  • provider_targets.zig:26-56 (legacy: ?Platform);
  • the chore: pin labelle-assembler 0.105.0 #378 gate at pipeline/install.zig:207-217;
  • the ASTC prepass;
  • parsed.platform checks in pipeline.zig, build.zig, install.zig, run.zig and docker.zig.
• Assembler: ProjectConfig.platform, .asset_compression, .ios, .android (codegen keys), and --platform parsed into the enum.
• FP uses:
  • .backend = .bgfx;
  • .backend_package bgfx 0.30.0;
  • .gamepad = .none;
  • .asset_compression = .{ .android = .astc, .web = .astc };
  • .assembler_version;
  • an .android block.

1d. SDL, docker, stb and help

• sdl_provision.zig (329 lines): MinGW SDL2 2.30.11 download into ~/.labelle/sdl2, autoWireEnv, stageSdl2DllBesideExe, sdl2LibDir.
• Callers:
  • pipeline/install.zig:80-98 (wants_sdl2);
  • pipeline/build.zig:104-117 (DLL staging from the merged compile_env);
  • doctor.zig (--fix, lib/dll/headers/mixer);
  • cli.zig:63.
• config.zig:264-267: LABELLE_SDL2_LIB is deliberately unreserved (A1).
• Also: docker.zig (only the macOS xcode-frameworks snippet after B); stb_image.* (finding 8); help text (help.zig:35, :117-118); comments in astc/cmd.zig and the Os.Tag list at :605.

1e. Allowlist after B (32 per #466 §9, to be recounted) and which PR removes each

2. Target architecture

labelle build  --platform=ios -> core resolve (ios owner = labelle-ios)
                               -> assembler describe --target ios  (backend pkg, target dir, asset format; refuses unsupported pairs)
                               -> [before build ios/device: env_file build_options {device=true}]   (v0.2)
                               -> core zig build (sokol hook resolves the SDK via xcrun)
                               -> after build ios/app: <target_dir>/zig-out/ios/<Name>.app (Info.plist, LaunchScreen, icon, signing)
labelle run    --platform=ios -> ... -> replace run ios/launch: simctl boot|install|launch --console-pty (or devicectl)
labelle bundle --platform=ios -> ... -> replace bundle ios/bundle: .app/.ipa
labelle ios doctor|devices|xcode|run   (namespace unreserved in 4.0)
labelle build  (desktop, gamepad, Windows) -> before generate sdl2/env: LABELLE_SDL2_LIB (cache_dir) -> after build sdl2/stage: SDL2.dll

Core keeps (generic):

• the desktop core target and host launch;
• target resolution from strings;
• hook orchestration, the contract, env_file and cache_dir;
• ASTC and bake;
• the macOS desktop bundler;
• labelle-assembler describe as the single source of backend and target facts;
• install python;
• the watch supervisor (A2).

Moves out:

• iOS → labelle-ios;
• SDL2 provisioning, doctor rows and DLL staging → an SDL provider (D2);
• backend identity, shorthand, bgfx↔gfx pairing and target validity → assembler;
• IosConfig → providers/ios.json.

Deleted:

• labelle ios;
• the Backend, Platform and AssetCompression mirrors;
• versions.zon .bgfx;
• doctor --fix SDL provisioning;
• --docker macOS cross (D6);
• the labelle astc --backend enum (becomes --target).

3. Contract and schema changes

The assembler's internal Platform, Capability.{wasm,android,ios} and the manifest .platforms stay; making them string-keyed is AS5, a separate assembler RFC (D8).

4. PR sequence

NOW means it can start immediately and touches no file that A2 (#470) or B edits. after X names the dependency.

Track X (CLI scrubs)

Track I (iOS)

I1, labelle-ios v0.1.0:

• Manifest: .name="ios", contract >=1.3.0 <1.4.0, .targets={"ios"}, no namespace yet (ios is reserved until I5).
• Hooks:
  • app (after build): finds the single exe in target_dir/zig-out/bin and writes zig-out/ios/<Name>.app (Info.plist, LaunchScreen, AppIcon);
  • launch (replace run): xcrun simctl list/boot/install/launch --console-pty, blocking so after-run semantics hold; run.args --device=<udid>;
  • bundle (replace bundle): zips the simulator .app.
• Settings v1: {schema_version:1, app_name, bundle_id, team_id, minimum_ios:"15.0", orientation, device_family:"1,2", simulator:{device:null}, destination:"simulator"}.
• Tests:
  • host unit tests;
  • a fake-xcrun e2e on ubuntu, macOS and Windows;
  • a real-simulator job on macos-latest: clean HOME, a sokol fixture pinned local:, then labelle build/run --platform=ios --timeout, asserting a log line and a non-blank simctl io screenshot.
• The first commit is the spike: does sokol iOS still build on Zig 0.16 with assembler 0.117?

I5, remove iOS from the core:

• Delete: ios.zig, ios_cmd, the legacy branch, the forced sokol, the ios Bypass arms, legacyRunBranch, the simulator branch, crossTargetLaunchSkipped platforms, IosConfig/Orientation, and "ios" in reserved.
• Tests: labelle ios gives the unknown-command diagnostic with nothing generated; run --platform=ios without a replacement gives NoRunReplacement.

I6, labelle-ios v0.2.0:

• Commands: doctor (Xcode, license, runtimes, backend capability), devices, xcode (pbxproj port) and run.
• Device builds: the 1.4 build_options {device:true} from a before build hook when destination="device".
• Signing: settings signing.{identity,profile}, then codesign plus xcrun devicectl; bundle produces an .ipa.

Track D (backend identity) and track P (platform enum)

Track S (SDL)

S1, the SDL provider:

• Manifest: .name="sdl2", namespace sdl2, contract >=1.3.0 <1.4.0, no targets.
• Hooks:
  • env (before generate, desktop): when the project needs SDL2 on a Windows host, provision into cache_dir (lock plus atomic rename) and write LABELLE_SDL2_LIB;
  • stage (after build): copies SDL2.dll next to the exe.
• Commands: doctor (lib, dll, headers, mixer; --fix) and install.
• Tests: a clean-HOME windows-latest gamepad build asserting the DLL sits beside the exe.

Final allowlist

agnostic_guard_test.zig only. Vendored stb lives outside src/.

5. Versioning and release train (recommended)

1. CLI 2.1.0 (A1 + A2) and 3.0.0 (B): unchanged. Keep 3.0 frozen (D1).
2. In parallel now:
   • X1 and X2 (CLI patches);
   • I0, I1 and I2 (labelle-ios 0.1.0 works on 2.1/3.0);
   • S0 to S3;
   • D1, D2 and P1, then assembler R-A;
   • I3 right after A2.
3. CLI 3.1.0 (additive): D3, D3a, contract 1.4, doctor --fix forwarding, and deprecation lines for labelle ios and core SDL provisioning. Then labelle-ios 0.2 and the registry record.
4. FP F, committed and green on 3.1 with the R-A pin.
5. CLI 4.0.0 (breaking, "full agnostic"): I5, S4, D4, P3, X3, X4, plus docs/migrating-to-4.0.md.

Why 4.0 rather than folding into 3.0: 3.0 is already gated on web 0.3 and FP, and mixing in the assembler floor and iOS would widen FP's breakage window.

6. Decisions for the owner (recommendation in bold)

7. Risks and acceptance

• FP (bgfx on desktop, Android and web):
  • SDL: no impact (.gamepad = .none). iOS: none.
  • The only exposure is the 4.0 assembler floor and schema, closed by F landing before 4.0 is published (FP installs "latest").
  • P1 keeps .web parsing, and 4.0 keeps .backend = .bgfx.
  • FP CI is Linux-only, so its Android and web jobs gate D3.
• Windows blind spot: the CLI's Windows CI never builds a game, and labelle-sdl has no Windows job.
  • Acceptance needs S0/S1's windows-latest clean-HOME gamepad build.
  • Plus a 4.0 Windows desktop acceptance: bgfx .gamepad = .auto with the sdl2 provider, the DLL staged, and the case-insensitive merge of LABELLE_SDL2_LIB/Path.
• project.labelle compatibility:
  • Old assembler pins keep old behaviour.
  • 4.0 refuses assemblers below protocol 7 with one line naming labelle upgrade assembler.
  • A .ios block gets the "moved" hint only after assembler_version is bumped.
• iOS signing and devices: no CI can sign.
  • Automate the simulator on macos-latest plus compile-only device builds.
  • Device run and store bundles need manual acceptance with a real device and team.
• Rot risk: iOS has never run end to end on Zig 0.16, so I1 opens with the spike.
• Local verification on the owner's Mac: Xcode 27.0 is installed, but the active developer directory is the Command Line Tools and the Xcode license isn't accepted. Before local simulator tests, run sudo xcodebuild -license accept and sudo xcode-select -s /Applications/Xcode.app, then install an iOS simulator runtime.
• Clean-clone and clean-HOME acceptance (4.0):
  • Fresh FP clone, empty HOME, no siblings: desktop, android and wasm all build, and .labelle/bgfx_* names come from describe.
  • A third-party backend_package fixture generates into .labelle/<pkg>_desktop.
  • labelle ios and legacy SDL --fix give their diagnostics.
  • The guard passes with a single entry.
  • A sokol iOS fixture runs in the simulator via local: labelle-ios and then via the registry pin.
• Review budget (3 bot rounds): I5, S4 and D4/P3 are separate PRs.

Critical files

• labelle-cli: src/agnostic_guard_test.zig, src/cli/ios.zig (with pipeline/install.zig, pipeline/run.zig), src/cli/project_config.zig (with pipeline.zig:162), src/cli/sdl_provision.zig (with doctor.zig).
• labelle-assembler: src/config.zig, src/main.zig:205-321 (describe / --target).

https://claude.ai/code/session_01R2K5sJDL5Msn1uRTkybiDP