refactor(livewire): decompose the mount delta — it's the model trait

The 50% on a "simple" Livewire mount looked too good, so decompose it across
four corners (vanilla / +model only / +foundation only / full). The result:
the model trait alone is ~-45 to -50%; the container/view/event tiers add
~0-5% on a single-component mount. The win isn't "the stack" — it's HasGrease.

Why one trait halves a mount: the model tier kills per-instance overhead
(reflection, class-attribute resolution, initialize* booters) — a fixed cost
per `new Model()` that dominates for small rows — and a `with('posts')` mount
hydrates nine models (user + 8 posts), so it's paid nine times.

Checked against the macOS-distortion reflex: this reproduces at the SAME
magnitude on Linux+JIT via benchmarks/docker (x86_64 image), so it is not a
macOS artifact — the earlier "Linux will deflate it" hunch was wrong.

- livewire_ab.php: four-corner decomposition + per-tier attribution in the
  report; parity gate now asserts both greased arms match the vanilla baseline.
- docs/guide/livewire.md: replace the full-stack headline with the decomposition
  table; land the "just put HasGrease on your models" conclusion the data backs.
- CLAUDE.md: record the decomposition + the corrected macOS-vs-Linux finding.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serpentblade

benchmarks/livewire_ab.php

@@ -8,12 +8,14 @@
  * a stack of exactly the tiers Grease accelerates — hydration, casting, date serialization,
  * `toArray()`, and the Blade compiler — fired on every round-trip rather than once per request.
  *
- * This sizes what the full greased stack buys on a Livewire initial render: a fully-configured
- * Testbench app boots vanilla vs greased (greased container + view + event providers + a greased
- * model), and `Livewire::mount()` is timed — the path that hydrates the model from the DB,
- * renders the component, dehydrates the `toArray()` payload (ISO dates, the loaded relation),
- * generates the checksum, and embeds it. The component is the UserCard fixture, whose state
- * is a serialized model — so the date/`toArray` tiers actually land in the measured work.
+ * This sizes — and *attributes* — what Grease buys on a Livewire initial render. A fully-
+ * configured Testbench app times `Livewire::mount()` (hydrate the model from the DB, render the
+ * component, dehydrate the `toArray()` payload — ISO dates, the loaded relation — to a checksummed
+ * snapshot) across four corners: vanilla, +model trait only, +foundation tiers only, and the full
+ * stack. The decomposition is the point: it shows the win is almost entirely the model trait, not
+ * the container/view/event tiers (a single component resolve is a thin slice of a request). The
+ * component is the UserCard fixture, whose state is a serialized model — so the date/`toArray`
+ * tiers land squarely in the measured work.
  *
  * Each arm runs in its own subprocess (two full apps in one process collide on facade / static
  * state, and a greased-container arm needs a different Application class — same reason as
@@ -176,26 +178,47 @@ function snapshot_data(string $html): string
     return ['us' => $us[intdiv(count($us), 2)], 'data' => $data];
 };
 
-echo "Booting Testbench + Livewire, vanilla vs greased ($rounds rounds × $iterations mounts)...\n\n";
-
-$vanilla = $runArm(VanillaLivewireResolver::class, VanillaUserCard::class);
-$greased = $runArm(GreasedLivewireResolver::class, GreasedUserCard::class);
-
-// ---- Parity gate: the dehydrated snapshot must be byte-identical ----------------
-
-if ($vanilla['data'] !== $greased['data']) {
-    echo "PARITY FAILED — dehydrated snapshot data differs:\n  vanilla: {$vanilla['data']}\n  greased: {$greased['data']}\n";
-    exit(1);
+echo "Booting Testbench + Livewire, four corners ($rounds rounds × $iterations mounts each)...\n\n";
+
+// The resolver controls the foundation tiers (container/view/events); the component class
+// controls the model tier (Greased vs Plain). The four corners isolate which tier the win
+// actually comes from — the surprise being that on a single-component mount it's almost all
+// the model trait, with the foundation tiers a thin slice on top (one component resolve is a
+// small fraction of a request — see the container guide).
+$baseline = $runArm(VanillaLivewireResolver::class, VanillaUserCard::class);   // nothing greased
+$model = $runArm(VanillaLivewireResolver::class, GreasedUserCard::class);      // + model trait only
+$foundation = $runArm(GreasedLivewireResolver::class, VanillaUserCard::class); // + container/view/events only
+$full = $runArm(GreasedLivewireResolver::class, GreasedUserCard::class);       // everything
+
+// ---- Parity gate: the greased snapshot must be byte-identical to vanilla ---------
+// This is the contract: a greased model serialized through Livewire must dehydrate exactly
+// like a vanilla one (same ISO dates, same decimal string, same relation), or the checksum
+// breaks. The model-only and full arms both carry the greased model, so both must match the
+// vanilla baseline byte-for-byte.
+
+foreach (['model' => $model, 'full' => $full] as $label => $arm) {
+    if ($baseline['data'] !== $arm['data']) {
+        echo "PARITY FAILED ($label) — dehydrated snapshot data differs from vanilla:\n";
+        echo "  vanilla: {$baseline['data']}\n  greased: {$arm['data']}\n";
+        exit(1);
+    }
 }
-echo "Parity: OK (dehydrated snapshot data byte-identical)\n\n";
+echo "Parity: OK (greased snapshot data byte-identical to vanilla)\n\n";
+
+// ---- Report: each tier's contribution, baseline-relative ------------------------
 
-// ---- Report --------------------------------------------------------------------
+$delta = fn (array $arm) => ($arm['us'] - $baseline['us']) / $baseline['us'] * 100;
 
-$delta = ($greased['us'] - $vanilla['us']) / $vanilla['us'] * 100;
-printf("%-28s %12s %12s %8s\n", '', 'vanilla', 'greased', 'delta');
-printf("%-28s %10.2f µs %10.2f µs %+7.1f%%\n", 'Livewire::mount (render)', $vanilla['us'], $greased['us'], $delta);
+printf("%-34s %12s %8s\n", 'Livewire::mount', 'median', 'vs base');
+printf("%-34s %10.2f µs %8s\n", 'vanilla (baseline)', $baseline['us'], '—');
+printf("%-34s %10.2f µs %+7.1f%%\n", '+ HasGrease on the model only', $model['us'], $delta($model));
+printf("%-34s %10.2f µs %+7.1f%%\n", '+ container/view/events only', $foundation['us'], $delta($foundation));
+printf("%-34s %10.2f µs %+7.1f%%\n", 'full greased stack', $full['us'], $delta($full));
 
-echo "\nThe initial mount hydrates the model, renders the component, and dehydrates its\n";
-echo "toArray() payload into a checksummed snapshot — the model, view, and serialization\n";
-echo "tiers stacked. A subsequent update re-runs the same path, so this delta recurs on\n";
-echo "every interaction, not just first paint. macOS figures — confirm on Linux/docker.\n";
+echo "\nThe mount hydrates the model (+ its loaded relation) and dehydrates the toArray()\n";
+echo "payload into a checksummed snapshot — and the model trait alone carries nearly the\n";
+echo "whole delta, because Grease's per-instance overhead kill (reflection, class-attribute\n";
+echo "resolution, the initialize* booters) is a FIXED cost per `new Model()` that dominates\n";
+echo "for small rows. A Livewire update re-runs this path every interaction, so the delta\n";
+echo "recurs — not just on first paint. Confirm on your own stack (NOTES: macOS distorts;\n";
+echo "this also reproduces on Linux+JIT via benchmarks/docker).\n";

docs/guide/livewire.md

@@ -58,34 +58,49 @@ checks, across mount → action → update:
 Because the snapshots are identical, a mixed greased/vanilla fleet is safe: there's no
 boundary for a checksum to straddle.
 
-## What it's worth
+## What it's worth — and where the win actually is
 
 The same `benchmarks/livewire_ab.php` that gates the parity above then times a
-`Livewire::mount()` — the path that hydrates the model, renders the component, and
-dehydrates its `toArray()` payload into a checksummed snapshot — on the full greased stack
-(greased [container](/guide/container), [view](/guide/blade), and
-[event](/guide/events) tiers plus a greased model) versus vanilla.
-
-On a Mac that lands around **−48%** on the mount path. Trust the direction, not the digits:
-as everywhere in these docs, [macOS distorts the magnitude](/guide/benchmarks) — reproduce
-it on your own stack:
+`Livewire::mount()` — hydrate the model, render the component, dehydrate its `toArray()`
+payload into a checksummed snapshot — across four corners, so you can see *which* tier the
+saving comes from rather than just a headline:
+
+| | vs vanilla |
+|---|---|
+| `+ HasGrease` on the model **only** | **≈ −45 to −50%** |
+| `+` container / view / event tiers only | ≈ −0 to −5% |
+| full greased stack | ≈ −48 to −50% |
+
+The surprise is that **the model trait alone carries nearly the whole delta** — the
+foundation tiers are a thin slice on top, because a single component resolve is a small
+fraction of the work (the [container tier](/guide/container) shaves a request elsewhere,
+not here). Why is one trait worth half a mount? Because Grease's model tier kills
+*per-instance* overhead — reflection, the [class-attribute resolution](/guide/how-it-works),
+the `initialize*` booters — which is a **fixed cost per `new Model()`** that doesn't shrink
+when the row is small. A Livewire mount hydrates the component's model **and its loaded
+relations** (the bench's fixture is one user + eight posts — nine models), so that fixed
+overhead is paid nine times and greasing it lands hard. It's the same mechanism behind the
+[`index_users` macro](/guide/benchmarks).
+
+Trust the direction, not the digits. This reproduces at the same magnitude on both macOS and
+Linux+JIT (`benchmarks/docker`), but — in the spirit of the
+[Octane page](/guide/octane#why-there-s-no-benchmark-table-on-this-page) — the honest number
+is the one you measure on your own components and database:
 
 ```bash
 php benchmarks/livewire_ab.php
 ```
 
-And, in the spirit of the [Octane page](/guide/octane#why-there-s-no-benchmark-table-on-this-page):
-the honest number is the one you measure on your own components, against your own database,
-with your own worker model. A Livewire update re-runs this whole path on every interaction,
-so whatever delta you measure on mount recurs for the life of the page — not just on first
-paint.
+A Livewire update re-runs this whole path on every interaction, so whatever delta you measure
+on mount recurs for the life of the page — not just on first paint.
 
 ## Getting started
 
 There's nothing Livewire-specific to install or configure. Add `HasGrease` to the
-[Eloquent models](/guide/getting-started) your components use, and — if you want the view
-and foundation tiers too — opt into the [Blade](/guide/blade),
-[container](/guide/container), and [event](/guide/events) tiers exactly as you would for a
-classic app. Livewire renders Blade and resolves through the container like everything else,
-so those tiers apply unchanged. The model trait alone is enough to justify the experiment on
-a component-heavy page; the rest is compounding upside.
+[Eloquent models](/guide/getting-started) your components use — that's it. The
+[Blade](/guide/blade), [container](/guide/container), and [event](/guide/events) tiers all
+apply unchanged (Livewire renders Blade and resolves through the container like everything
+else), and they're worth turning on — but the four-corner number above is unambiguous about
+the priority: **if you take nothing else from this package, put `HasGrease` on the models your
+components touch.** On a component-heavy page that single trait is where the request goes; the
+rest is compounding upside.