feat(#461): select callback-lifecycle shape from manifest data, not the backend enum

[apotema]

What

The generated main.zig's callback-lifecycle shape (runner / cleanup / allocator / gui-event / imgui-dispatch / preview / Android-register) was chosen by cfg.backend == .sokol / is_bgfx_android enum branches in lifecycle/render.zig — the last per-backend codegen keyed off the closed Backend enum. This moves the selection to manifest data, so the enum stops driving codegen.

This is PR 1 of the "make the Backend enum stop driving codegen" follow-on to the completed v2-manifest cutover (#461 steps 1–11). It lands the mechanism and proves it byte-identical in isolation; production behavior is unchanged (the external backend manifests don't declare .lifecycle yet — that's the next PR).

Changes

• Schema (manifest_v2.zig): extend PlatformEntry.Lifecycle with imgui_dispatch, preview (none/callback_basic/sokol_readback), android_register (none/bgfx_shell). Additive + defaulted → every existing manifest parses unchanged; an undeclared callback backend keeps the safe third-party shape.
• Selection (render.zig): build LifecycleShape from the manifest lifecycle_ovr first; the cfg.backend == .sokol / is_bgfx_android literals remain only as a byte-identical fallback for a built-in whose (older) manifest predates these fields — deleted in the final Epic: build-graph manifest v2 + build hook (#453 item 3) #461 step.
• Privilege gate: preview = .sokol_readback and android_register = .bgfx_shell emit backend-private Zig, so they're privileged — a new backend_registry.assertLifecyclePrivilege (wired into v2 validation in root.zig) rejects any non-labelle.* provider that declares them, preserving the third-party foot-gun protection the enum implicitly gave.
• Fixtures: declare the full shape in backends/sokol (all 4 callback platforms) + backends/bgfx_v2 (android) so codegen tests exercise the manifest path, not the fallback.

Proof

• Differential tests (main_zig_tests.zig): generate sokol-desktop and bgfx-android main.zig twice, varying ONLY lifecycle_override (null → enum branch; the decl → manifest branch), assert byte-identical.
• Mutation-verified: temporarily corrupting the enum fallback makes the differential test fail — confirming the two paths are genuinely distinct and the manifest path is live (not silently falling back).
• Gate tests: a third-party (someone.vulkan) declaring a privileged block is rejected; a labelle.* provider is accepted.
• Existing goldens/anchors unchanged. zig build + zig build test green.

Not in this PR (the cascade)

2. add the .lifecycle shape to the external labelle-sokol/labelle-bgfx v2 manifests + release → 3. bump the assembler pins (production built-ins now declare their shape) → 4. delete the enum fallback branches. Refs Epic: build-graph manifest v2 + build hook (#453 item 3) #461.

https://claude.ai/code/session_01P7B7UzgrWEbBYLT3YBrAog

Summary by CodeRabbit

• New Features

  • Added manifest-driven lifecycle settings for multiple platforms, including GUI dispatch, preview/readback handling, and Android callback registration.
  • Expanded support for platform-specific callback behavior in generated output.

• Bug Fixes

  • Lifecycle overrides now take precedence over built-in fallback behavior, so generated app code matches the manifest more reliably.
  • Added validation to block privileged lifecycle options unless they come from an approved backend namespace.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces manifest-declared privileged lifecycle configuration for backend callback shapes (preview readback, Android registration). It extends the v2 manifest schema, updates bgfx/sokol manifests with lifecycle data, modifies codegen render logic to prefer manifest-declared shapes, and adds namespace-based validation restricting privileged declarations to labelle.*-owned backends.

Changes

Privileged manifest lifecycle declarations

Layer / File(s)	Summary
Lifecycle schema and privilege detection src/codegen/manifest_v2.zig	Adds imgui_dispatch, preview, android_register fields with Preview/AndroidRegister enums to Lifecycle, and adds declaresPrivilegedLifecycle() to detect privileged selections across platforms.
Backend manifest data declarations backends/bgfx_v2/backend.manifest.v2.zon, backends/sokol/backend.manifest.v2.zon	Adds .lifecycle blocks to bgfx Android and sokol desktop/ios/android/wasm platforms declaring runner, cleanup, allocator, GUI, imgui dispatch, and preview/android_register settings.
Codegen render precedence src/codegen/lifecycle/render.zig	Reorders callback lifecycle shape selection so manifest-declared lifecycle_ovr data takes precedence over built-in sokol/bgfx-android enum branches, mapping preview/android/imgui_dispatch directly from manifest fields.
Privilege validation and wiring src/backend_registry.zig, src/root.zig	Adds assertLifecyclePrivilege enforcing that privileged lifecycle declarations require a canonical .id under the labelle.* namespace, wires it into validateProviderContracts, and adds unit tests.
Regression fixtures and generation tests test/helpers.zig, test/main_zig_tests.zig	Adds lifecycle declaration fixtures and #461 regression tests verifying byte-identical generated output between enum-path and manifest-declared lifecycle for sokol and bgfx Android.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
    participant Root as root.zig
    participant Registry as backend_registry.zig
    participant Manifest as manifest_v2.zig
    participant Render as render.zig

    Root->>Manifest: parse backend.manifest.v2.zon
    Manifest-->>Root: declaresPrivilegedLifecycle() result
    Root->>Registry: assertLifecyclePrivilege(cfg, declares_privileged, manifest_id)
    alt declares_privileged and id not under labelle.*
        Registry-->>Root: error.PrivilegedLifecycleRequiresReservedNamespace
    else allowed or bundled backend
        Registry-->>Root: ok
        Root->>Render: generate main.zig using lifecycle_ovr
        Render-->>Root: LifecycleShape (runner, preview, android, imgui_dispatch)
    end

Loading

Possibly related issues

• Epic: build-graph manifest v2 + build hook (#453 item 3) #461: This PR implements the lifecycle-manifest migration (schema, render precedence, regression tests) referenced by this issue.

Possibly related PRs

• labelle-toolkit/labelle-assembler#455: Both PRs modify callback-lifecycle shape selection logic and sokol-desktop tests in src/codegen/lifecycle/render.zig.
• labelle-toolkit/labelle-assembler#457: Both PRs extend src/backend_registry.zig with labelle.*-namespace validation logic.
• labelle-toolkit/labelle-assembler#462: This PR builds on PR462's v2 manifest foundation by adding lifecycle fields and privileged-lifecycle validation in src/root.zig.

Poem

A rabbit hopped through manifest glades,
Found lifecycle blocks in tidy shades,
"labelle.* only!" the registry cheers,
Privileged previews, no more fears. 🐇
Byte-for-byte, the tests agree —
Same main.zig, new pedigree! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: lifecycle shape selection now comes from manifest data instead of backend enum branches.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/461-lifecycle-shape-manifest

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (3)

test/main_zig_tests.zig (1)

255-300: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Differential tests look correct; consider extending coverage to other sokol platforms.

Both tests correctly isolate the lifecycle_override threadlocal with defer, and the byte-identity assertions plus sanity substring checks (_sokol_preview, android_app.setInitCallback(&gameInit)) are appropriate anchors for the enum→manifest migration.

Per the PR objectives, the sokol manifest additions cover desktop/iOS/Android/wasm platforms, but this differential guard only exercises sokol desktop. If the other sokol platform lifecycle declarations (mobile/wasm) diverge from their enum-path shape, that regression wouldn't be caught here.

Example extension sketch (sokol Android, mirroring the desktop test)

+    test "sokol android: manifest-declared lifecycle == enum-path main (byte-identical, `#461`)" {
+        const enum_main = try generate.generateMainZigFromTemplate(std.testing.allocator, engine_template, .{ .y_axis = .up,
+            .name = "test-game",
+            .backend = .sokol,
+            .platform = .android,
+            .ecs = .mock,
+        }, sokol_mobile_lifecycle, empty_entries, empty_names, empty_names, empty_scene_manifests, empty_names, empty_names, empty_names, empty_names, empty_names, empty_names, empty_names, empty_plugin_events, empty_plugin_flow_nodes, empty_plugin_pin_styles, empty_plugin_coercions);
+        defer std.testing.allocator.free(enum_main);
+
+        generate.main_template.lifecycle_override = h.sokol_android_lifecycle_decl; // new fixture
+        defer generate.main_template.lifecycle_override = null;
+        const manifest_main = try generate.generateMainZigFromTemplate(std.testing.allocator, engine_template, .{ .y_axis = .up,
+            .name = "test-game",
+            .backend = .sokol,
+            .platform = .android,
+            .ecs = .mock,
+        }, sokol_mobile_lifecycle, empty_entries, empty_names, empty_names, empty_scene_manifests, empty_names, empty_names, empty_names, empty_names, empty_names, empty_names, empty_names, empty_plugin_events, empty_plugin_flow_nodes, empty_plugin_pin_styles, empty_plugin_coercions);
+        defer std.testing.allocator.free(manifest_main);
+
+        try std.testing.expectEqualStrings(enum_main, manifest_main);
+    }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/main_zig_tests.zig` around lines 255 - 300, The differential coverage
only verifies sokol desktop, so extend the same byte-identical enum-path vs
manifest-declared lifecycle check in main_zig_tests.zig to the other sokol
platform cases covered by the PR (especially mobile/wasm variants). Reuse
generate.generateMainZigFromTemplate and the lifecycle_override threadlocal
pattern, and add platform-specific sanity anchors alongside the existing
sokol_lifecycle test so regressions in those lifecycle declarations are also
caught.

src/codegen/manifest_v2.zig (1)

288-339: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

LGTM overall; consider adding direct test coverage for the new fields.

The new imgui_dispatch, preview, android_register fields and their defaults are consistent with the documented privilege model. However, synthetic_v2 (the fixture exercised by this file's own tests) is not updated to include these fields, so declaresPrivilegedLifecycle() and the new enum fields have no direct unit test within this file — coverage currently relies entirely on downstream backend_registry.zig tests and the real fixture manifests.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/codegen/manifest_v2.zig` around lines 288 - 339, Add direct unit-test
coverage for the new Lifecycle fields in manifest_v2.zig by updating the
synthetic_v2 fixture so it declares imgui_dispatch, preview, and
android_register with the documented defaults and privilege combinations. Then
extend the tests around declaresPrivilegedLifecycle() and the Lifecycle enum
handling to assert the fixture exercises both privileged and unprivileged cases,
instead of relying only on backend_registry.zig and external manifests.

src/codegen/lifecycle/render.zig (1)

306-315: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Stale comment: lifecycle_ovr is now matched first, not sokol/bgfx-android.

This block still states "Sokol/bgfx-android are matched FIRST, so the declared branch only ever covers a genuine non-enum-tag callback backend." After this change the if (lifecycle_ovr) |decl| branch (Line 316) is evaluated before the cfg.backend == .sokol / is_bgfx_android branches, so a built-in whose v2 manifest declares its lifecycle now takes the declared branch too. The inline comment at Lines 317-327 already describes the new precedence correctly, so this header contradicts it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/codegen/lifecycle/render.zig` around lines 306 - 315, Update the stale
block comment in render.zig so it matches the actual precedence in the callback
lifecycle selection logic: the `lifecycle_ovr` declared branch is now checked
before the `cfg.backend == .sokol` and `is_bgfx_android` branches. Adjust the
wording near `use_callback_lifecycle` to reflect that built-ins with a v2
manifest lifecycle can also take the declared branch, and remove the outdated
claim that Sokol/bgfx-android are matched first.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/codegen/lifecycle/render.zig`:
- Around line 306-315: Update the stale block comment in render.zig so it
matches the actual precedence in the callback lifecycle selection logic: the
`lifecycle_ovr` declared branch is now checked before the `cfg.backend ==
.sokol` and `is_bgfx_android` branches. Adjust the wording near
`use_callback_lifecycle` to reflect that built-ins with a v2 manifest lifecycle
can also take the declared branch, and remove the outdated claim that
Sokol/bgfx-android are matched first.

In `@src/codegen/manifest_v2.zig`:
- Around line 288-339: Add direct unit-test coverage for the new Lifecycle
fields in manifest_v2.zig by updating the synthetic_v2 fixture so it declares
imgui_dispatch, preview, and android_register with the documented defaults and
privilege combinations. Then extend the tests around
declaresPrivilegedLifecycle() and the Lifecycle enum handling to assert the
fixture exercises both privileged and unprivileged cases, instead of relying
only on backend_registry.zig and external manifests.

In `@test/main_zig_tests.zig`:
- Around line 255-300: The differential coverage only verifies sokol desktop, so
extend the same byte-identical enum-path vs manifest-declared lifecycle check in
main_zig_tests.zig to the other sokol platform cases covered by the PR
(especially mobile/wasm variants). Reuse generate.generateMainZigFromTemplate
and the lifecycle_override threadlocal pattern, and add platform-specific sanity
anchors alongside the existing sokol_lifecycle test so regressions in those
lifecycle declarations are also caught.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6c88b9a8-513b-4b5b-b64a-331c169e7fb6

📥 Commits

Reviewing files that changed from the base of the PR and between 5c0f216 and 8637d8e.

📒 Files selected for processing (8)

• backends/bgfx_v2/backend.manifest.v2.zon
• backends/sokol/backend.manifest.v2.zon
• src/backend_registry.zig
• src/codegen/lifecycle/render.zig
• src/codegen/manifest_v2.zig
• src/root.zig
• test/helpers.zig
• test/main_zig_tests.zig