Implement selective API hardening

Author: ItsMeSamey

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-02-26
+
+- Added debug-time pinned-struct move guards for callback binding invariants (`App`/`Service`).
+- Added typed lifecycle diagnostics for detected move violations:
+  - `lifecycle.pinned_struct_moved.app`
+  - `lifecycle.pinned_struct_moved.service`
+- Added deterministic invariant regression tests for stable path, moved path detection, diagnostic emission, and no-false-positive flow.
+- Added move/pinning safety guidance in `README.md`, `docs/migration.md`, and `MIGRATION.md`.
+- Preserved runtime architecture (no allocation-based pinning rewrite).
+
 ## 2026-02-24
 
 - Replaced active C-backed build/runtime path with Zig-only modules.

MIGRATION.md

@@ -52,8 +52,33 @@ Browser fallback controls:
 
 ```zig
 var app = try webui.App.init(allocator, .{
-    .transport_mode = .native_webview,
-    .browser_fallback_on_native_failure = true,
-    .auto_open_browser = true,
+    .launch_policy = .{
+        .preferred_transport = .native_webview,
+        .fallback_transport = .browser,
+        .browser_open_mode = .on_browser_transport,
+    },
 });
 ```
+
+## Pinned Struct Move Safety
+
+The runtime currently enforces move safety by contract (not by forced heap pinning):
+
+- Do not move/copy an initialized `App` after it owns windows.
+- Do not move/copy an initialized `Service` after `Service.init`.
+
+Unsafe examples:
+- Extra by-value copies of initialized structs.
+- Relocating containers that move initialized `Service`/`App` entries.
+
+Safe examples:
+- Initialize in final storage.
+- Pass pointers (`*Service`, `*App`) across helpers.
+
+Debug guard behavior:
+- With diagnostics enabled via `onDiagnostic(...)`, `Debug`/`ReleaseSafe` emit typed diagnostics and fail fast:
+  - `lifecycle.pinned_struct_moved.app`
+  - `lifecycle.pinned_struct_moved.service`
+- `ReleaseFast`/`ReleaseSmall` compile these checks out.
+
+This is intentionally documented and guarded behavior, not an allocation-based pinning redesign.

README.md

@@ -176,6 +176,33 @@ pub fn main() !void {
 }
 ```
 
+## Pinned Struct Move Safety
+
+`App` and `Service` are move-sensitive once windows are created.
+
+Rules:
+- Once an `App` owns windows, do not move/copy that initialized `App` by value.
+- Once a `Service` is initialized, do not move/copy that initialized `Service` by value.
+
+Unsafe patterns:
+- Returning/stashing an initialized `Service`/`App` through extra by-value copies.
+- Storing initialized `Service` values in relocating containers.
+- Assigning `var moved = service;` (or equivalent copies) after init.
+
+Safe patterns:
+- Initialize `App`/`Service` in its final storage location.
+- Pass pointers (`*App`, `*Service`) through helpers.
+- Keep initialized structs out of relocatable by-value containers.
+
+Debug behavior:
+- In `Debug`/`ReleaseSafe`, when diagnostics are enabled via `onDiagnostic(...)`, the runtime checks callback-binding invariants and emits typed diagnostics:
+  - `lifecycle.pinned_struct_moved.app`
+  - `lifecycle.pinned_struct_moved.service`
+- After emitting the diagnostic, it fails fast to avoid latent crashes.
+- In `ReleaseFast`/`ReleaseSmall`, this guard is compiled out.
+
+This project intentionally documents and guards move-safety instead of forcing allocation-based pinning.
+
 ## Typed RPC + Bridge Generation
 
 Everything starts with a comptime method set:

docs/migration.md

@@ -122,3 +122,24 @@ Typed control APIs:
 
 - Existing warning log strings may still appear, but typed diagnostics are the authoritative integration surface.
 - For Linux packaging, validate helper/runtime presence through `listRuntimeRequirements`.
+
+## Pinned Struct Move Safety
+
+This release keeps the current architecture (no forced allocation pinning), so move-safety is explicit:
+
+- Do not move/copy an initialized `App` after it owns windows.
+- Do not move/copy an initialized `Service` after `Service.init`.
+
+Avoid:
+- By-value hops of initialized values between helper return values/temporaries.
+- Relocating containers that move initialized `Service`/`App` values.
+
+Prefer:
+- Initialize in final storage.
+- Pass pointers (`*Service`, `*App`) across function boundaries.
+
+Debug guard behavior:
+- With diagnostics enabled via `onDiagnostic(...)`, `Debug` and `ReleaseSafe` emit typed diagnostics then fail fast:
+  - `lifecycle.pinned_struct_moved.app`
+  - `lifecycle.pinned_struct_moved.service`
+- `ReleaseFast` and `ReleaseSmall` compile these checks out.