From bda00688dc1b2fa0934afb4e53c1b8ad92ef8e50 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Sat, 9 May 2026 14:36:23 +0000
Subject: [PATCH] =?UTF-8?q?feat(recipes):=20add=20/recipes/counter=20?=
 =?UTF-8?q?=E2=80=94=20first=20docs-native=20recipe?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First migration in the Phase 3 "drop examples mirroring, build
recipes" wave. Establishes the canonical recipe shape and proves
end-to-end: literate index.md + co-located _app/ deployable + cmd/site
internal mount + tinkerdown's site-wide include resolver from v0.2.2.

What this PR delivers

  /recipes/counter/                    NEW recipe — "Counter, deeper"
                                       ~145 lines covering broadcast
                                       routing, AnonymousAuthenticator
                                       choice, session-group lifecycle,
                                       and where the pattern stops
                                       scaling.
  /recipes/counter/_app/               Moved from getting-started/_app/
                                       counter/. Mounted by cmd/site
                                       at /apps/counter/ (unchanged
                                       from PR-A).

Cross-references

  /getting-started/your-first-app      include= paths repointed to
                                       ../recipes/counter/_app/...
                                       (works because tinkerdown
                                       v0.2.2's ParseFileInSite widens
                                       the include root to the site
                                       directory). Fixed PR-A drift:
                                       sharedAuth → AnonymousAuthenti-
                                       cator narrative; the wire-up
                                       main.go is now hand-pasted
                                       (handler.go isn't tutorial-
                                       shaped main); sidebar quote
                                       links to /recipes/counter for
                                       the deeper architecture story.

  /                                    landing include= paths
                                       repointed; "Read the full
                                       walkthrough → ... or jump to
                                       Counter, deeper" link added.

Plumbing

  Dockerfile                           TINKERDOWN_REF v0.2.0 → v0.2.2
                                       (v0.2.1 added ParseFileInSite,
                                       v0.2.2 added page-toc !important
                                       sidebar fix).
  cmd/site/main.go                     import path
                                       getting-started/_app/counter →
                                       recipes/counter/_app.
  content/tinkerdown.yaml              navigation entry for the new
                                       Recipes > Counter, deeper page.
  go.mod / go.sum                      go mod tidy reclassified
                                       livetemplate as direct dep
                                       (was indirect — Copilot
                                       feedback from PR #8).

Verified end-to-end locally

  - /recipes/counter/                  HTTP 200, embed-lvt + 26
                                       literate-include matches
  - /getting-started/your-first-app    HTTP 200, 3 cross-page-include
                                       matches (was: rejected with
                                       "escapes the page root" before
                                       v0.2.2)
  - /apps/counter/                     HTTP 200, counter handler
                                       responds via cmd/site
  - Six embed-lvt blocks render across the recipe page
  - Zero "escapes" warnings in tinkerdown serve log
  - iPhone manual signoff: side-by-side broadcast pair tick in
    lockstep within a single browser; fresh incognito tab starts at 0
  - Sidebar TOC items stack vertically (the v0.2.2 page-toc fix)

Path-X-as-promised

  This is the first concrete migration of Phase 3 (revised). Examples
  repo is unchanged. Future recipes follow the same shape: mkdir
  recipes/<slug>/, move/author code into _app/, write literate
  index.md, mount in cmd/site, add nav entry. No cross-repo
  coordination required.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Dockerfile                                    |   2 +-
 cmd/site/main.go                              |   2 +-
 content/getting-started/your-first-app.md     |  40 ++++--
 content/index.md                              |  11 +-
 .../counter/_app}/counter.go                  |   0
 .../counter/_app}/counter.tmpl                |   0
 .../counter/_app}/handler.go                  |   0
 content/recipes/counter/index.md              | 123 ++++++++++++++++++
 content/tinkerdown.yaml                       |   2 +
 go.mod                                        |   6 +-
 go.sum                                        | 111 ++++++++++++++++
 11 files changed, 272 insertions(+), 25 deletions(-)
 rename content/{getting-started/_app/counter => recipes/counter/_app}/counter.go (100%)
 rename content/{getting-started/_app/counter => recipes/counter/_app}/counter.tmpl (100%)
 rename content/{getting-started/_app/counter => recipes/counter/_app}/handler.go (100%)
 create mode 100644 content/recipes/counter/index.md

diff --git a/Dockerfile b/Dockerfile
index 3a1fc46..23b5b5f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,7 +7,7 @@
 # until upstream fixes the vendored asset embed (Phase 0 finding T0-1).
 # `TINKERDOWN_REF` selects which branch/tag to clone and is overridable.
 
-ARG TINKERDOWN_REF=v0.2.0
+ARG TINKERDOWN_REF=v0.2.2
 
 # ---- Stage 1: Build TypeScript client assets for tinkerdown ----
 FROM node:20-alpine AS client-builder
diff --git a/cmd/site/main.go b/cmd/site/main.go
index 1334e77..8422c64 100644
--- a/cmd/site/main.go
+++ b/cmd/site/main.go
@@ -18,7 +18,7 @@ import (
 	"net/http"
 	"os"
 
-	counter "github.com/livetemplate/docs/content/getting-started/_app/counter"
+	counter "github.com/livetemplate/docs/content/recipes/counter/_app"
 )
 
 func main() {
diff --git a/content/getting-started/your-first-app.md b/content/getting-started/your-first-app.md
index 182a2d0..7e586e6 100644
--- a/content/getting-started/your-first-app.md
+++ b/content/getting-started/your-first-app.md
@@ -25,32 +25,51 @@ You'll have a `go.mod` and an empty directory. We'll add three files: `counter.g
 
 Create `counter.go`. First the state:
 
-```go include="./_app/counter/counter.go" lines="5-11"
+```go include="../recipes/counter/_app/counter.go" lines="5-11"
 ```
 
 State is a value type, not a pointer — controllers receive a copy and return a (possibly modified) copy. The framework manages the swap.
 
 Then a controller and two action methods:
 
-```go include="./_app/counter/counter.go" lines="13-33"
+```go include="../recipes/counter/_app/counter.go" lines="13-33"
 ```
 
 Action methods are exported on the controller, and their names ARE the action names — `Increment` and `Decrement` are what the template will reference. The `BroadcastAction` calls are how multi-tab sync works (Step 6).
 
 Now wire it up in `main.go`:
 
-```go include="./_app/counter/main.go" lines="25-52"
+```go
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/livetemplate/livetemplate"
+)
+
+func main() {
+	tmpl := livetemplate.Must(livetemplate.New("counter",
+		livetemplate.WithParseFiles("counter.tmpl"),
+	))
+	handler := tmpl.Handle(&CounterController{}, livetemplate.AsState(&CounterState{}))
+
+	mux := http.NewServeMux()
+	mux.Handle("/", handler)
+	log.Fatal(http.ListenAndServe(":9090", mux))
+}
 ```
 
 `livetemplate.New("counter")` parses `counter.tmpl` from the same directory. `tmpl.Handle(controller, AsState(initial))` is the standard wiring — controller for actions, initial state for new sessions.
 
-The `WithAuthenticator(sharedAuth{})` option uses a constant-groupID authenticator so all connections share state — Step 6 has the why and the `sharedAuth` definition.
+By default LiveTemplate uses `AnonymousAuthenticator`, which gives each browser a stable session group via cookie. Two consequences worth knowing about now: each browser gets its own state (no cross-user leaks), and tabs from the same browser share state — that's what makes the broadcast demo at Step 6 work.
 
 ## Step 3 — Write the template
 
 Create `counter.tmpl`:
 
-```html include="./_app/counter/counter.tmpl"
+```html include="../recipes/counter/_app/counter.tmpl"
 ```
 
 The `<button name="increment">` attribute is the routing trigger — clicking that button posts the form and the framework calls `Increment()` on the controller.
@@ -89,10 +108,10 @@ Same Go code. Same template. Two lines of HTML promote the experience from serve
 
 Look at the handlers from Step 2 — note the highlighted lines:
 
-```go include="./_app/counter/counter.go" lines="22-33" highlight="24,31"
+```go include="../recipes/counter/_app/counter.go" lines="22-33" highlight="24,31"
 ```
 
-`ctx.BroadcastAction("Increment", nil)` (and the matching `Decrement`) tells LiveTemplate to apply the same action on every other connected client — multiple tabs, multiple embeds, multiple users. Without it, each session has its own count; with it, they stay in lockstep.
+`ctx.BroadcastAction("Increment", nil)` (and the matching `Decrement`) tells LiveTemplate to apply the same action on every other connection in the same session group — multiple tabs and embeds within your browser. Without it, each tab has its own count; with it, they stay in lockstep.
 
 To prove it, here are two embeds against the same counter, side by side:
 
@@ -108,12 +127,7 @@ To prove it, here are two embeds against the same counter, side by side:
 
 Click `+1` in one — watch the other update in real time. They're talking to the same upstream session, and `BroadcastAction` is what makes them stay synced. (On a narrow viewport the embeds stack vertically — the broadcast still works.)
 
-> **Why constant-groupID auth?** Here's the `sharedAuth` referenced in `main.go`:
->
-> ```go include="./_app/counter/main.go" lines="11-23"
-> ```
->
-> Every connection lands in the same session group, so `BroadcastAction` from any one client reaches all the others. A real app uses a per-user authenticator; for a tutorial counter served alongside the docs, putting everyone in one group is what makes the side-by-side demo visible to every reader.
+> **Why does this stay scoped to your browser?** LiveTemplate's default authenticator (`AnonymousAuthenticator`) uses a cookie to assign each browser a stable session group. Tabs from the same browser share that group — that's why the two embeds above sync. Different browsers — or an incognito window in the same browser — get different cookies, different groups, and isolated state. For a public docs site this is the right default: every visitor gets a clean slate, and the broadcast demo still proves the feature within their own browser. See [Recipes/Counter, deeper](/recipes/counter) for the full session-group + scaling story.
 
 ## What you just built
 
diff --git a/content/index.md b/content/index.md
index 6680e26..92f4d3f 100644
--- a/content/index.md
+++ b/content/index.md
@@ -24,22 +24,17 @@ The widget above is a real, deployed LiveTemplate app — the same code as the [
 
 The state and handlers — `counter.go`:
 
-```go include="./getting-started/_app/counter/counter.go" lines="5-33"
+```go include="./recipes/counter/_app/counter.go" lines="9-33"
 ```
 
 The template — `counter.tmpl`:
 
-```html include="./getting-started/_app/counter/counter.tmpl"
-```
-
-The wire-up (the heart of `main.go`):
-
-```go include="./getting-started/_app/counter/main.go" lines="26-41"
+```html include="./recipes/counter/_app/counter.tmpl"
 ```
 
 A button's `name` attribute IS the routing key — `<button name="increment">` posts `increment` and LiveTemplate dispatches to the `Increment` method on the controller. The protocol between HTML and Go is just the form data the browser already sends.
 
-[Read the full walkthrough →](/getting-started/your-first-app)
+[Read the full walkthrough →](/getting-started/your-first-app) — or jump to [Counter, deeper](/recipes/counter) for the production-shaped story (broadcast routing, session models, scaling).
 
 ## What happens between a click and a DOM update
 
diff --git a/content/getting-started/_app/counter/counter.go b/content/recipes/counter/_app/counter.go
similarity index 100%
rename from content/getting-started/_app/counter/counter.go
rename to content/recipes/counter/_app/counter.go
diff --git a/content/getting-started/_app/counter/counter.tmpl b/content/recipes/counter/_app/counter.tmpl
similarity index 100%
rename from content/getting-started/_app/counter/counter.tmpl
rename to content/recipes/counter/_app/counter.tmpl
diff --git a/content/getting-started/_app/counter/handler.go b/content/recipes/counter/_app/handler.go
similarity index 100%
rename from content/getting-started/_app/counter/handler.go
rename to content/recipes/counter/_app/handler.go
diff --git a/content/recipes/counter/index.md b/content/recipes/counter/index.md
new file mode 100644
index 0000000..8c7b277
--- /dev/null
+++ b/content/recipes/counter/index.md
@@ -0,0 +1,123 @@
+---
+title: "Counter, deeper"
+description: "Past the +1 button: how BroadcastAction routes between sessions, why AnonymousAuthenticator is the right default for public demos, and where this pattern stops scaling."
+source_repo: https://github.com/livetemplate/docs
+source_path: content/recipes/counter/index.md
+---
+
+# Counter, deeper
+
+Most "counter" demos stop at "click +1, see number tick." Useful for proving the framework works; not so useful when you actually have to ship one. This recipe goes past the demo into the production-shaped questions: how `BroadcastAction` routes between sessions, why the cookie-bound session group matters for "multi-tab sync without leaking to other users," and what breaks first when this pattern meets real load.
+
+The code is the same counter from [Your First App](/getting-started/your-first-app) — but the framing is different. Where that walkthrough builds the counter from scratch, this one stares at the four lines that do the actual work and unpacks them.
+
+```embed-lvt path="/apps/counter/" upstream="http://localhost:9091" height="180px"
+```
+
+## Anatomy of the handler
+
+The whole thing fits in three files. State + controller in one (the part you'd write):
+
+```go include="./_app/counter.go" lines="9-33"
+```
+
+And a wiring file that exposes an `http.Handler`:
+
+```go include="./_app/handler.go" lines="49-66"
+```
+
+There's not much to it. The choices that matter for production are the two `livetemplate.With*` options. Everything else is mechanical.
+
+## Why `AnonymousAuthenticator` is the production default
+
+LiveTemplate's `Authenticator` interface answers a single question on every HTTP and WebSocket request: *"who is this client, and which session group do they belong to?"* The session group is what `BroadcastAction` routes between. Two requests with the same group ID share state; different group IDs don't.
+
+`AnonymousAuthenticator` (the framework's default, what this recipe uses) issues a cookie-bound group ID on first contact:
+
+- Same browser, multiple tabs → same cookie → same group → broadcast works
+- Different browser → different cookie → different group → isolated state
+- Incognito window → its own cookie → its own group → clean slate
+
+For a public docs site, that's the right shape. Every reader gets their own private counter on first visit, can prove broadcast within their own browser, and the demo can't be polluted by a stranger's clicks.
+
+The alternative — a constant-group authenticator that puts every visitor in one shared group — is a demo-flavored shortcut. It makes a global ticker visible to all visitors, which is punchy on a marketing page but fails the "clean slate for thousands of users" test. We used it briefly during early development; the production switch to `AnonymousAuthenticator` was a one-line change with no other code impact:
+
+```go
+// Before — every visitor saw the same global counter
+livetemplate.WithAuthenticator(sharedAuth{})
+
+// After — each browser gets its own session group
+livetemplate.WithAuthenticator(&livetemplate.AnonymousAuthenticator{})
+```
+
+The `BroadcastAction` calls didn't change. The state struct didn't change. Only the routing rule for "who counts as the same session" changed, and that one swap converted a demo into a production-shaped widget.
+
+## How `BroadcastAction` routes
+
+The two action methods do the obvious thing — bump the counter, return the new state — and then call `ctx.BroadcastAction`:
+
+```go include="./_app/counter.go" lines="22-33" highlight="24,31"
+```
+
+`BroadcastAction("Increment", nil)` adds an action to the broadcast queue. It does **not** apply the action immediately to other connections; it queues it. After the current request's response is sent, the framework drains the queue: for every other connection in the same session group, run `Increment` against that connection's local state.
+
+Two consequences worth knowing:
+
+- **Each connection still has its own state copy.** Broadcast doesn't share state — it replays actions. A connection that's been disconnected for a while doesn't get a magical state update; it gets the actions it missed when it reconnects, applied in order.
+- **The broadcast is fire-and-forget within a request.** The current request's caller doesn't wait for the broadcast to finish. If you broadcast and then return, the response goes to the originating client immediately; the other clients see the update milliseconds later as the queue drains.
+
+To prove the routing, here are two embeds against the same recipe app, side by side:
+
+<div class="recipe-side-by-side" style="display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;">
+
+```embed-lvt path="/apps/counter/" upstream="http://localhost:9091" session="recipe-counter-deeper" height="200px"
+```
+
+```embed-lvt path="/apps/counter/" upstream="http://localhost:9091" session="recipe-counter-deeper" height="200px"
+```
+
+</div>
+
+Click `+1` on one. The other ticks too — same browser, same cookie, same group, broadcast routes between them. Open this page in an incognito window: that incognito counter starts at zero and won't see your normal-window clicks. Different cookie, different group.
+
+## Session group lifecycle
+
+Worth pausing on what "session group" actually means in time.
+
+1. **First visit**: the browser has no cookie. `AnonymousAuthenticator.GetSessionGroup` issues a fresh group ID and sets it as a cookie. The connection joins that group.
+2. **Subsequent requests** (next tab, page refresh, WebSocket reconnect): the cookie is sent, the same group ID is returned, the connection joins the existing group.
+3. **Cookie cleared / different browser**: a new group ID is issued. Old state is unreachable from the new group.
+4. **Server restart**: cookies persist but in-memory session state is gone. New connections start fresh; broadcast queue is empty until clients reconnect and trigger new actions.
+
+The group ID is the *only* thing tying a connection to its peers. Two browsers that somehow had the same cookie value would be in the same group. Two tabs from one browser are in the same group not because of the same TCP connection or anything similar — purely because of the shared cookie.
+
+## When this pattern scales — and when it doesn't
+
+This recipe is a deliberately small slice. The scaling story behind it is real:
+
+| Scenario | Works? | Notes |
+|---|---|---|
+| One user, multiple tabs, single instance | ✅ Trivially. The broadcast queue runs in-process, the cost is one `Increment` call per connected tab. |
+| Multiple users, single instance | ✅ Each user has their own session group; broadcasts stay scoped. |
+| Multiple users, multiple instances (Fly machines, Kubernetes replicas) | ⚠️ Needs `WithPubSubBroadcaster` — by default a broadcast only reaches connections on the *same* instance. With Redis-backed broadcasting the broadcast fans out across instances. See [PubSub Reference](/reference/pubsub). |
+| One group with thousands of connections (everyone broadcasting at high frequency) | ❌ Broadcast cost is O(N) per action; thousand-connection groups broadcasting at 100Hz mean 100k+ in-process calls per second. Either shard the group or use a different sync primitive. |
+| Cross-user shared state (everyone sees everyone) | ⚠️ Possible — write a custom `Authenticator` that returns a constant group ID — but you've now built a write-amplification machine that any visitor can poke. Production examples need rate limiting, read-only modes, or moderation. |
+
+`AnonymousAuthenticator` keeps you on the easy side of every row: per-user groups bound the fan-out, and the multi-instance question only matters once you've outgrown a single Fly machine.
+
+## What the wiring file actually does
+
+The full handler in `handler.go` is just the constructor expressed as a function. It exists because this recipe is mounted by the docs site's `cmd/site` aggregator — there's no standalone `main()`. In your own app you'd write a `main()` that does the same thing inline (`livetemplate.Must(...)` → `tmpl.Handle(...)` → `http.ListenAndServe`) and call it a day. Exposing it as a `Handler()` constructor is just so it can be mounted inside another binary's HTTP server.
+
+```go include="./_app/handler.go" lines="14-46"
+```
+
+The `embed.FS` + temp-file dance at the top is a workaround for `livetemplate.WithParseFiles` taking filesystem paths — when the template ships inside the binary, we extract it once at first use. If you're running the standard "ship a directory of templates next to the binary" shape, you skip all this and pass the relative path directly.
+
+## What next?
+
+- [Reference — Authentication](/reference/authentication) — the full `Authenticator` interface, beyond the anonymous default.
+- [Reference — PubSub & Broadcasting](/reference/pubsub) — multi-instance broadcasting via Redis.
+- [Reference — Server Actions](/reference/server-actions) — the action lifecycle, including `BroadcastAction` ordering rules and gotchas.
+- [Sync, Broadcast & Multi-User Sessions](/recipes/sync-and-broadcast) — when `Sync()` is enough and when you need broadcast.
+- [Your First App](/getting-started/your-first-app) — if you arrived here cold, the from-scratch walkthrough is the better starting point.
diff --git a/content/tinkerdown.yaml b/content/tinkerdown.yaml
index 125fbd6..9f428ac 100644
--- a/content/tinkerdown.yaml
+++ b/content/tinkerdown.yaml
@@ -96,6 +96,8 @@ navigation:
     path: "recipes"
     collapsed: false
     pages:
+      - title: "Counter, deeper"
+        path: "recipes/counter/index.md"
       - title: "Live Patterns Catalog"
         path: "patterns/index.md"
       - title: "How a LiveTemplate Update Flows"
diff --git a/go.mod b/go.mod
index 88ca158..3f4c445 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,10 @@ module github.com/livetemplate/docs
 
 go 1.26.1
 
-require gopkg.in/yaml.v3 v3.0.1
+require (
+	github.com/livetemplate/livetemplate v0.8.23
+	gopkg.in/yaml.v3 v3.0.1
+)
 
 require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -15,7 +18,6 @@ require (
 	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
-	github.com/livetemplate/livetemplate v0.8.23 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/redis/go-redis/v9 v9.17.2 // indirect
diff --git a/go.sum b/go.sum
index 54aa001..13ec189 100644
--- a/go.sum
+++ b/go.sum
@@ -1,17 +1,66 @@
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
+github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v28.3.3+incompatible h1:Dypm25kh4rmk49v1eiVbsAtpAsYURjYkaKubwuBdxEI=
+github.com/docker/docker v28.3.3+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
+github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0omw=
+github.com/ebitengine/purego v0.8.4/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
 github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
+github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
 github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
 github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
 github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
+github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
@@ -19,24 +68,84 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/livetemplate/livetemplate v0.8.23 h1:80/Lwa2iPqKhnJIHvPKWnRObMM2YoRxtAyZ9gE9tN+E=
 github.com/livetemplate/livetemplate v0.8.23/go.mod h1:GMvZKyPUq8LSGfgD3pftKOHa6v+I+RDYyff2mNjeAYs=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
+github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
+github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/go-archive v0.1.0 h1:Kk/5rdW/g+H8NHdJW2gsXyZ7UnzvJNOy6VKJqueWdcQ=
+github.com/moby/go-archive v0.1.0/go.mod h1:G9B+YoujNohJmrIYFBpSd54GTUB4lt9S+xVQvsJyFuo=
+github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
+github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
+github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
+github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
+github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 h1:ZqeYNhU3OHLH3mGKHDcjJRFFRrJa6eAM5H+CtDdOsPc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI=
 github.com/redis/go-redis/v9 v9.17.2/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
+github.com/shirou/gopsutil/v4 v4.25.6 h1:kLysI2JsKorfaFPcYmcJqbzROzsBWEOAtw6A7dIfqXs=
+github.com/shirou/gopsutil/v4 v4.25.6/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
+github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.11.0 h1:ib4sjIrwZKxE5u/Japgo/7SJV3PvgjGiRNAvTVGqQl8=
+github.com/stretchr/testify v1.11.0/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/tdewolff/minify/v2 v2.24.8 h1:58/VjsbevI4d5FGV0ZSuBrHMSSkH4MCH0sIz/eKIauE=
 github.com/tdewolff/minify/v2 v2.24.8/go.mod h1:0Ukj0CRpo/sW/nd8uZ4ccXaV1rEVIWA3dj8U7+Shhfw=
 github.com/tdewolff/parse/v2 v2.8.5 h1:ZmBiA/8Do5Rpk7bDye0jbbDUpXXbCdc3iah4VeUvwYU=
 github.com/tdewolff/parse/v2 v2.8.5/go.mod h1:Hwlni2tiVNKyzR1o6nUs4FOF07URA+JLBLd6dlIXYqo=
+github.com/tdewolff/test v1.0.11 h1:FdLbwQVHxqG16SlkGveC0JVyrJN62COWTRyUFzfbtBE=
 github.com/tdewolff/test v1.0.11/go.mod h1:XPuWBzvdUzhCuxWO1ojpXsyzsA5bFoS3tO/Q3kFuTG8=
+github.com/testcontainers/testcontainers-go v0.39.0 h1:uCUJ5tA+fcxbFAB0uP3pIK3EJ2IjjDUHFSZ1H1UxAts=
+github.com/testcontainers/testcontainers-go v0.39.0/go.mod h1:qmHpkG7H5uPf/EvOORKvS6EuDkBUPE3zpVGaH9NL7f8=
+github.com/testcontainers/testcontainers-go/modules/redis v0.39.0 h1:p54qELdCx4Gftkxzf44k9RJRRhaO/S5ehP9zo8SUTLM=
+github.com/testcontainers/testcontainers-go/modules/redis v0.39.0/go.mod h1:P1mTbHruHqAU2I26y0RADz1BitF59FLbQr7ceqN9bt4=
+github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
+github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
+github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
+github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
+go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
+go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ=
+go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I=
+go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE=
+go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E=
+go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
+go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
 golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
 golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
 golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
@@ -51,3 +160,5 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
+pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=