upkeep-rails 0.1.6

data/docs/single-subscriber-cold-roadmap.md

@@ -0,0 +1,192 @@
+# Single Subscriber And Cold Fixed-Cost Roadmap
+
+This roadmap targets the cases where Upkeep has little or no render sharing
+amortization: one active subscriber, cold page setup, cable activation, and
+short-lived anonymous pages.
+
+Last updated: 2026-05-21.
+
+Current code state:
+
+- Base runtime/docs commit: `474fb9c` (`Instrument capture and document Upkeep Rails`).
+- Current pass adds gated request/action profiling, operation-scoped capture
+  metrics, mutation action/delivery timings, client/server phase correlation,
+  benchmark phase labels, lightweight subscription-shape tracing, static
+  template metadata caching, shared-stream signature memoization, and queued
+  dependency flushing.
+- Latest verification: `bundle exec rake test` passed with `186` runs and
+  `1172` assertions.
+- Latest single-subscriber benchmark data is the 2026-05-21 identity-free
+  report below.
+
+## Environment
+
+From a fresh zsh shell in any worktree:
+
+```sh
+cd /path/to/upkeep-rails
+eval "$(mise activate zsh)"
+ruby -v
+bundle exec rake test
+```
+
+Do not use system Ruby. The repo expects Ruby from mise, currently `3.4.7`.
+
+## Baseline
+
+Latest identity-free 1-subscriber report:
+
+- Report: `benchmark/results/identity-free-feed-compare-20260521114026.md`
+- Upkeep setup p95: `140ms`
+- Turbo setup p95: `104ms`
+- Upkeep page render p95: `91ms`
+- Turbo page render p95: `73ms`
+- Upkeep WebSocket connect p95: `38ms`
+- Turbo WebSocket connect p95: `17ms`
+- Upkeep subscribe call p95: `10ms`
+- Turbo subscribe call p95: `14ms`
+- Upkeep subscribe ack p95: `10ms`
+- Turbo subscribe ack p95: `13ms`
+- Upkeep write POST p95: `38.85ms`
+- Turbo write POST p95: `66.37ms`
+- Upkeep update-settled p95: `90ms`
+- Turbo update-settled p95: `96ms`
+- Subscription shape cache: `1` miss, `0` hits, `0` bypasses
+- Shape miss timing: total `4.221ms`, key `1.743ms`, index template `1.003ms`
+- Setup page server timing: Upkeep p95 `83.88ms`; Turbo p95 `66.02ms`
+- Write request server timing: Upkeep p95 `23.78ms`; Turbo p95 `32.72ms`
+- `GET /feed` request-capture timing: total p95 `82.921ms`; action p95
+  `70.594ms`; view p95 `55.578ms`; template p95 `42.352ms`; collection render
+  p95 `13.226ms`; SQL p95 `1.577ms`; register p95 `12.129ms`
+- `GET /feed` recorder timing: dependency p95 `5.783ms`; frame p95 `2.418ms`;
+  shape trace p95 `4.264ms`
+- Subscribe channel server timing: total `2.085ms`, activation `1.95ms`
+
+With one subscriber there is still no render dedup savings. The latest cold
+report is a one-sample fixed-cost probe and is noisier than the shared report.
+It still shows the right target: the remaining gap is not SQL, shape cache hit
+cost, or server-side channel subscribe. This pass reduced recorder dependency
+and shape tracing substantially, so the dominant cold fixed cost is now the
+first page/action path, especially Action View template and collection capture,
+plus first registration.
+
+## Priorities
+
+1. Decompose cold page/capture setup
+
+   Upkeep page render p95 is now `91ms` versus Turbo `73ms`, while setup p95
+   is `140ms` versus Turbo `104ms`. `GET /feed` request-capture action p95 is
+   `70.594ms`, view p95 is `55.578ms`, and template p95 is `42.352ms`.
+
+   Candidate work:
+
+   - Reduce Action View capture overhead around template and collection render
+     instrumentation. SQL is only `1.735ms` in this run.
+   - Keep ActionCable open/confirmation separate from server-side channel
+     subscribe; latest server-side subscribe total is only `2.085ms`.
+   - Continue reducing Action View template capture overhead; template p95 is
+     `42.352ms` in the latest one-subscriber probe.
+   - Investigate whether page/layout frame capture can be represented with one
+     page boundary without losing layout identity safety.
+   - Keep queued dependency flushing; the recorder shape trace has already
+     dropped from `10.04ms` to `4.264ms`.
+
+   Target outcome:
+
+   - 1-subscriber page render p95 closes the current `18ms` gap to Turbo.
+   - Setup telemetry explains the remaining `36ms` setup gap.
+
+2. Finish shape miss/key cleanup
+
+   Shape keys no longer serialize the full recorder snapshot, and the
+   subscription-shape trace now records normal capture shape terms in
+   DAG/runtime. Shared-hit key p95 is `0.031ms`; the single-subscriber miss path
+   is still `1.743ms` and total miss is `4.221ms`, but it is a first-shape
+   cost.
+
+   Remaining work:
+
+   - Preserve the rolling trace digest for hot hits.
+   - Identify why first-shape key generation still costs `1.743ms`.
+   - Move template digest and manifest fingerprint normalization out of the
+     miss path where possible.
+   - Keep cache misses exact without replay-payload hashing.
+
+   Target outcome:
+
+   - Shape-key generation is sub-millisecond for both miss and hit paths.
+   - Cache misses stay exact, and false misses remain safe.
+
+3. Reduce subscribe ack fixed cost
+
+   Server-side subscribe is no longer the main cost, but client-observed suback
+   can still be noisy. Keep the server/client split visible.
+
+   Candidate work:
+
+   - Keep cable subscribe phase telemetry: fetch, authorization, activation,
+     active-index register, stream attach, confirmation.
+   - Keep benchmark phase labels on WebSocket open, cable open, subscription
+     registration, and confirmation.
+   - Keep durable writer and persistent index work outside the ack critical path.
+   - Preserve strict activation semantics; no compatibility shims for old rows.
+
+   Target outcome:
+
+   - Server-side subscribe p95 stays within a few milliseconds of Turbo in both
+     1- and 200-subscriber identity-free reports.
+
+4. Single-subscriber write fast path
+
+   The latest one-subscriber run recovered on write and update-settled, but the
+   one-sample p95 is noisy. Keep this lane explicit: if planning resolves to
+   exactly one active subscriber, skip shared-group work that only pays off for
+   cohorts.
+
+   Candidate checks:
+
+   - No render dedup accounting on the hot path for a single target unless the
+     runtime already produced the shared group.
+   - No batch fanout structure for one connection.
+   - No persistent index dependency for active, in-process delivery.
+
+   Target outcome:
+
+   - 1-subscriber update-settled returns to at or below Turbo.
+   - Planning/build telemetry shows one lookup, one plan, one render, one
+     transmit.
+
+5. Cold benchmark separation
+
+   Keep cold burst capacity separate from warm update economics.
+
+   Benchmark shapes:
+
+   - Cold burst capacity: simultaneous new users, accepts, page render, cable
+     open, subscribe ack.
+   - Cold ramp setup: staged subscribers without accept queue loss.
+   - Warm single update: subscribers are ready, one mutation settles.
+
+## Success Criteria
+
+- 1-subscriber first-write miss behavior is explained and bounded.
+- `steady_state_setup_leaks` is zero in warm single-subscriber runs.
+- 1-subscriber setup p95 closes most of the current `140ms` versus Turbo
+  `104ms` gap.
+- 1-subscriber page render p95 closes most of the current `91ms` versus Turbo
+  `73ms` gap.
+- Shape miss telemetry shows where first-render cost remains.
+- 1-subscriber update-settled p95 remains at or below Turbo.
+
+## Validation
+
+Use the mise environment in every shell:
+
+```sh
+eval "$(mise activate zsh)"
+bundle exec rake test
+BENCH_FAMILY=render_dedup BENCH_WORKLOAD=identity_free_feed_compare BENCH_TIER=report BENCH_VUS=1 ruby benchmark/bin/run
+```
+
+When changing cold setup behavior, also run the relevant cold benchmark instead
+of using the warm shared report as a proxy.

data/docs/stress-test-findings.md

@@ -0,0 +1,310 @@
+# Stress-test findings, fixes, and remaining decisions
+
+**Gem under test:** `upkeep-rails` v0.1.0 (installed from RubyGems)
+**How found:** end-to-end browser stress test in the companion app at
+`../stress-test-upkeep/stress_app/` (Rails 8 + importmap + propshaft, real Chrome via Ferrum).
+Run instructions and the harness are in that app's `STRESS_TEST.md` and `lib/stress/harness.rb`.
+**Source confirmed against:** this repo (file:line references are relative to the repo root).
+
+All line numbers are from upkeep-rails v0.1.0 (this repo).
+
+---
+
+## 2026-05-21 follow-up on v0.1.1 and v0.1.2
+
+The companion app at
+`/Volumes/FelipeSSD/professional/upkeep/rails/stress-test-upkeep/stress_app`
+verified that 0.1.1 fixed importmap wiring, cold first-paint activation, scalar
+page replay, identity rejection, and token expiry. The remaining correctness
+failure was `shared stream survives remove`: after a rendered member was
+removed, the next shared render-site replay reached the browser but used Turbo
+Stream `replace` against a custom render-site wrapper while the template
+contained only child `<li>` elements. Turbo removed the target container, so
+later streams had no target.
+
+The fix is to emit Turbo Stream `update method="morph"` for render-site replay
+fallbacks and keep `replace method="morph"` only for member/fragment
+replacements. In 0.1.2, render sites are legal existing HTML elements marked
+with `data-upkeep-render-site`; Upkeep no longer emits a custom structural
+wrapper. `update` swaps the render site's children and preserves the real
+container that future streams target. Page-level fallbacks now use Turbo Stream
+`refresh method="morph" scroll="preserve"` so Turbo owns page refresh behavior
+instead of Upkeep replacing `<html>` or calling `document.write`.
+
+Turbo interop was tightened at the client boundary too: the injected marker is
+now a body-scoped `<upkeep-subscription-source data-upkeep-subscription
+data-turbo-temporary>` custom element. The generated browser client registers it
+as a Turbo stream source via `Turbo.session.connectStreamSource`, and DOM
+connect/disconnect handles ActionCable subscribe/unsubscribe.
+
+Two upgrade traps were also confirmed:
+
+- `app/javascript/upkeep/subscription.js` is intentionally vendored, but it must
+  be refreshed when the server-side subscription payload changes. The generated
+  client now logs channel rejection, and the README documents rerunning the
+  installer or comparing the file after gem upgrades.
+- `config.upkeep.*` set from `config/initializers/upkeep.rb` is too late for the
+  Railtie path. The installer now writes `Upkeep::Rails.configure do |config|`
+  in the initializer. `config.upkeep.*` remains appropriate in Rails
+  application or environment config that runs before initializers.
+
+---
+
+## Summary
+
+| # | Finding | Type | Status |
+|---|---------|------|--------|
+| 1 | importmap installer never pins the browser client | Bug (clear fix) | Fixed + test |
+| 2 | member `remove` broadcasts to a shared stream nobody listens on | Bug (clear fix) | Fixed + test |
+| 3 | a delivery error turns an already-committed write into HTTP 500 | Bug (clear fix, safety half) | Fixed + test |
+| 4 | scalar/page-level replay target can't be found → raises | Bug (clear fix) | Fixed + test |
+| P1 | benchmark suite: AR-store `fetch` raises `RecordNotFound`, test expects `KeyError` | Pre-existing failure | Fixed + test |
+| P2 | benchmark suite: identified-user streamed update delivers 0 broadcasts | Pre-existing failure (corroborates A) | Fixed + test |
+| A | identity-bound pages need an explicit request-to-connection bridge | Framework limitation + decision | Implemented + documented |
+| B | first paint should activate without creating an app guest identity | Framework limitation + decision | Fixed + test |
+| C | commit-triggered delivery needs a job boundary | Architecture decision | Implemented + test |
+
+### What already works well (don't regress these)
+- Anonymous-public collection pipeline (capture → commit → invalidate → broadcast → Turbo
+  render) is correct and fast: p50 ~50–60 ms, p95 ~80–130 ms on localhost, **0 cross-board
+  leaks in every run**; append/replace/remove all 100% when a board has a single subscriber.
+- Opaque relations are refused exactly as documented (no marker injected; the page still
+  renders as plain Rails HTML under `refused_boundary_behavior = :warn`).
+
+---
+
+## Part 1 — Unequivocal fixes
+
+These have a single defensible fix and now have regression coverage. This
+section records the diagnosis so the changes can be reviewed.
+
+### Fix 1 — importmap installer never pins the browser client (critical)
+- **Symptom:** in a stock Rails 8 + importmap + propshaft app, after
+  `bin/rails generate upkeep:install`, the cable client asset 404s, no `/cable` WebSocket
+  opens, and **nothing is ever delivered** (0 WebSocket upgrades observed).
+- **Root cause:** `lib/generators/upkeep/install/install_generator.rb` —
+  `append_application_import` writes `import "./upkeep/subscription"` into
+  `app/javascript/application.js`, but `pin_action_cable` only pins
+  `@hotwired/turbo-rails` and `@rails/actioncable`. The `upkeep/subscription` module is
+  never pinned, so under propshaft's digested URLs the relative specifier resolves to
+  `/assets/upkeep/subscription` (no digest) → 404.
+- **Fix:** generator should pin the module (`pin "upkeep/subscription", to:
+  "upkeep/subscription.js"`, or `pin_all_from "app/javascript/upkeep", under: "upkeep"`)
+  and import it by bare specifier.
+- **Impact:** this breaks the *default* Rails 8 stack, i.e. essentially every new adopter.
+
+### Fix 2 — member `remove` not delivered to *shared* (2+) subscribers
+- **Symptom:** with 2+ anonymous subscribers sharing a collection page, deleting a rendered
+  member never reaches them. With 1 subscriber it works. append/replace work in both cases.
+- **Root cause:** subscriptions register shared streams **only for render-site frames** —
+  `lib/upkeep/shared_streams.rb` `names_for_graph` skips frames where
+  `kind != "render_site"`, keying the stream on the render-site target. But delivery computes
+  a remove's shared stream from the operation's **own** target —
+  `lib/upkeep/delivery/turbo_streams.rb:244` `shared_stream_name_for` →
+  `SharedStreams.stream_name(target: planned_target.target, …)`, and for a remove that target
+  is the member (`#card_<id>`), not the render-site. Different `target.kind/id` → different
+  SHA → broadcast to `upkeep:shared:<member-hash>` while subscribers listen on
+  `upkeep:shared:<render-site-hash>`. (append/replace work because they deopt to the
+  render-site target, whose hash matches.)
+- **Fix:** member-level shared delivery should resolve to the enclosing render-site's shared
+  stream (the one the subscription registered).
+- **Repro:** `SUBSCRIBERS=2 BOARDS=1 bin/rails stress:run` → "collection remove" goes 0/2.
+
+### Fix 3 — a delivery error turns an already-committed write into HTTP 500 (safety half)
+- **Symptom:** once a page-replay subscriber exists (see Fix 4), an unrelated `create` that
+  has already **committed** returns 500 because Upkeep's after-commit delivery raises.
+- **Root cause:** delivery runs **inline in the writer's request**. `lib/upkeep/runtime.rb:1005`
+  registers `ActiveRecord::Base.after_commit { ChangeLog.record(...) }`, and
+  `lib/upkeep/rails/controller_runtime.rb:99` calls
+  `Upkeep::Rails.deliver_changes!(changes)` synchronously at the end of the action. Any
+  exception in rendering/targeting propagates out of the committed request → 500. One broken
+  subscriber page poisons unrelated writers.
+- **Fix (unequivocal part):** fault-isolate inline delivery — a render/target error must be
+  rescued and surfaced via instrumentation, never propagate to the committed write; other
+  targets still deliver.
+- **Out of scope here (see Decision C):** moving delivery off the request entirely (async).
+
+### Fix 4 — scalar / page-level replay target can't be found → raises
+- **Symptom:** a page-level (`pluck`/scalar) dependency fails to update and intermittently
+  raises `RuntimeError: target not found in full rerender`.
+- **Root cause:** `lib/upkeep/targeting.rb:92` raises when `node_for` can't locate the target.
+  A page-level dependency yields a page target with the **inner template** id, e.g.
+  `page:rails:boards/stats`, and `node_for` (kind `"page"`, line ~99) looks for
+  `[data-upkeep-page-frame="page:rails:boards/stats"]`. But the rendered HTML only contains
+  `data-upkeep-page-frame="page:rails:layouts/application"` — **the inner template's
+  page-frame marker is never emitted into the DOM** (confirmed: the stats page's only
+  page-frame attribute is the layout's). So the target node never exists.
+- **Fix:** make the emitted DOM page-frame markers consistent with the page targets Upkeep
+  records (emit the inner-template marker), or resolve page targets to the page frame that
+  actually exists.
+
+---
+
+## Part 2 — Decisions / framework limitations
+
+These are the higher-level constraints found by the stress app. Decisions A, B,
+and C are implemented in this worktree.
+
+### Decision A — identity-bound pages need an explicit request-to-connection bridge
+
+**Decision made.** Upkeep does not infer subscriber identity from method names
+such as `Current.user`, `current_user`, or Devise helpers. Runtime heuristics are
+too weak: the gem cannot know whether `user` means the subscriber, an author, an
+impersonator, or unrelated display state.
+
+Instead, identity is now a declared bridge:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, current: ["Current", :user] do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+The declaration has two sides:
+- **capture side** (`current:`, `session:`, `cookie:`, or `warden:`): the value
+  observed while rendering the HTTP response;
+- **subscribe side** (`subscribe { ... }`): the same value resolved from the
+  ActionCable connection when the browser subscribes.
+
+The identity name (`:viewer`, `:account`, `:tenant`, etc.) is part of the
+canonical subscriber id. If a page captures multiple declared identities, the
+ActionCable subscription must match all of them.
+
+Declared identity values can be absent. The default absence rule is `nil`, so a
+logged-out page that checks `Current.user` or `session[:user_id]` can remain
+anonymous-public. Apps that use another sentinel declare it with `absent_if`.
+
+**What changed in the repo.**
+- `Upkeep::Rails.configuration.identify` declares identities.
+- `SubscriberIdentity` derives request identity only from configured mappings.
+- `Upkeep::Rails::Cable::Channel` authorizes an identified subscription against
+  the identity names stored with that subscription.
+- Undeclared non-absent `CurrentAttributes` and Warden identity reads refuse live
+  registration with `identity_setup_required` / `unidentified_identity` instead
+  of silently guessing.
+- The install generator writes identity examples into
+  `config/initializers/upkeep.rb` and prints setup guidance when it detects
+  obvious request-side identity usage.
+- The README and `docs/architecture/identity-and-sharing.md` document the API.
+
+**Why this is better than Devise/Warden-only.** Devise remains easy to wire, but
+the API also supports non-Devise apps, tenant/account identities, session-backed
+apps, cookie-backed partitioning, and multiple identity components without
+runtime name guessing.
+
+### Decision B — first paint should activate without creating an app guest identity
+
+**Decision made.** Upkeep should not solve first-paint activation by inventing a
+global guest cookie or by asking every app to decide whether each session/cookie
+identity can be auto-created. That pushes too much identity design onto
+developers and risks turning public pages private.
+
+The cleaner fix is a transport-level activation token. Every injected marker now
+includes a stateless signed token for that subscription id. The browser sends it
+when subscribing over ActionCable, and the channel verifies it before fetching
+or activating the subscription.
+
+That token answers: "did this browser receive this exact rendered response?"
+It does not answer: "which subscriber boundary is this?" Identified pages still verify
+the declared identity bridge from Decision A after token verification.
+
+This keeps cold first paint live for subscription activation without requiring
+an Upkeep-owned guest cookie. If a page is truly identity-specific, the app
+still declares that identity explicitly.
+
+### Decision C — commit→delivery should use the app's job backend
+
+**Decision made.** Commit-triggered delivery now has an Active Job boundary.
+When a request commits Active Record changes, Upkeep can enqueue
+`Upkeep::Rails::DeliveryJob` instead of planning, rendering, and broadcasting in
+the writer's request.
+
+The default Rails production configuration is
+`config.upkeep.delivery_adapter = :active_job`, with
+`config.upkeep.delivery_queue = :upkeep_realtime`. The job backend is the app's
+normal Active Job backend: Solid Queue, Sidekiq, GoodJob, or another adapter.
+Upkeep does not depend directly on Sidekiq or Solid Queue.
+
+ActionCable remains a separate layer. The job worker still broadcasts through
+`ActionCable.server.broadcast`, so multi-process apps need a shared cable
+adapter such as Redis, Solid Cable, or PostgreSQL. Solid Queue plus Solid Cable
+is the no-Redis path. Sidekiq plus Redis-backed ActionCable is the traditional
+Redis path.
+
+If enqueueing fails after the write commits, Upkeep instruments
+`delivery_enqueue_error.upkeep` and does not turn the committed write into an
+HTTP 500. Once the job is enqueued, job execution failures are left to the
+configured Active Job backend's retry/error policy.
+
+Development and tests can still use `config.upkeep.delivery_adapter = :async`
+for process-local batching or `:inline` for explicit synchronous debugging.
+
+---
+
+## Part 3 — Pre-existing test-suite failures (fixed)
+
+The core unit suite is green: `bundle exec rake test` → **200 runs, 0
+failures**. The benchmark app is green: `benchmark/upkeep-app/bin/rails test` →
+**7 runs, 0 failures**. The broader `bundle exec rake proof` task is also
+green, including both benchmark apps and the proof runner.
+
+### P1 — `UpkeepChannelTest#test_keeps_connection_state_out_of_transport_on_unsubscribe`
+`test/channels/upkeep_channel_test.rb:35`
+```
+[KeyError] exception expected, not
+Class: <ActiveRecord::RecordNotFound>
+Message: Couldn't find Upkeep::Subscriptions::ActiveRecordStore::SubscriptionRecord with 'id'=...
+```
+**What it means:** after unsubscribe the subscription is gone, but `Upkeep::Rails.subscriptions.fetch(id)`
+raises a **different exception class depending on the store backend** — `KeyError` (memory store, what
+the test asserts) vs `ActiveRecord::RecordNotFound` (AR store, what actually runs). The store
+abstraction leaks its backend through the not-found error type. Low severity (production code in
+`cable/channel.rb#unsubscribed` already rescues *both*), but it's a real contract gap.
+**Fix:** both stores now normalize missing subscriptions to
+`Upkeep::Subscriptions::NotFound < KeyError`, and the channel only needs the
+store-level not-found contract.
+
+### P2 — `BenchmarkSurfaceTest#test_delivers_a_streamed_update_through_the_derived_subscriber_stream`
+`test/integration/benchmark_surface_test.rb:85`
+```
+Expected: 1
+  Actual: 0
+```
+**What it means:** a **signed-in user** loads a board, a card is updated, and the test expects exactly
+one Turbo Stream broadcast on that user's derived subscriber stream — but **zero** are captured. This is
+the gem's *own* test for identified-subscriber delivery, and it is red at HEAD. It is direct,
+in-repo corroboration of **Decision A**: identity-bound (per-user) delivery does not currently produce
+the expected broadcast. Treat P2 as the failing acceptance test that Decision A must turn green; it is
+the best regression target for whatever identity approach is chosen.
+**Fix:** the benchmark app declares a subscriber identity with `current: ["Current", :user]`
+and resolves it from `cable.current_user`. The benchmark acceptance test now
+activates the persisted subscription before capturing broadcasts, matching the
+ActiveRecord store's on-subscribe indexing model.
+
+---
+
+## Appendix — reproducing
+
+From the companion stress app:
+
+```sh
+cd ../stress-test-upkeep/stress_app
+bin/rails db:prepare
+bin/rails server -p 3001            # terminal 1
+bin/rails stress:run               # terminal 2 (defaults)
+
+# targeted repros:
+SUBSCRIBERS=2 BOARDS=1 bin/rails stress:run     # Fix 2 (shared remove): "collection remove" 0/2
+SUBSCRIBERS=5 BOARDS=5 bin/rails stress:run     # everything green for the unshared case
+```
+
+Tunables: `URL BOARDS CARDS_PER_BOARD SUBSCRIBERS WRITES WRITE_CONCURRENCY SETTLE
+RECV_TIMEOUT HEADLESS CHROME`. The harness reports delivery completeness, cross-board leaks,
+latency percentiles, and per-boundary correctness.
+
+**Deliberate stress-app choices:** the layout omits `csrf_meta_tags`/`csp_meta_tag` (both read
+the session; with the explicit identity model, non-absent declared values partition delivery while
+absent values remain anonymous-public); writes use `skip_forgery_protection`; single Puma process with the
+async cable adapter (multi-worker needs a shared adapter per the README).

data/docs/testing.md

@@ -0,0 +1,143 @@
+# Testing
+
+The Rails package green bar includes the gem tests, the maintained benchmark
+apps, and the proof runner. The benchmark apps live inside this repo under
+`benchmark/`.
+
+## Commands
+
+Run the gem test suite:
+
+```sh
+mise exec -- ruby -S rake test
+```
+
+Run the full gate:
+
+```sh
+mise exec -- ruby bin/test
+```
+
+`bin/test` runs:
+
+- all tests under `test/`;
+- `benchmark/upkeep-app`'s Rails test suite;
+- `benchmark/turbo-app`'s Rails test suite;
+- `bin/run`, which writes proof reports to `results/`.
+
+Run the proof runner directly:
+
+```sh
+mise exec -- ruby bin/run
+```
+
+## What The Gate Covers
+
+Gem tests cover:
+
+- Action View frame capture and replay;
+- controller request replay;
+- Active Record/Arel query dependency analysis;
+- subscription storage and reverse-index lookups;
+- refused opaque collection boundaries;
+- column-scoped collection lookup keys;
+- invalidation planning;
+- Turbo Stream delivery partitioning;
+- render grouping before replay;
+- ActionCable subscriber identity and channel behavior;
+- transport retry and backpressure behavior.
+
+The Upkeep benchmark app covers:
+
+- authenticated board rendering;
+- room rendering;
+- shared feed rendering;
+- authorization boundaries;
+- helper-hidden render idioms;
+- automatic subscription registration;
+- streamed delivery through canonical subscriber streams.
+
+The Turbo benchmark app remains the comparison app for workload parity.
+
+## Store Choice
+
+Generated apps use the in-process memory subscription store in `test` by
+default. That is deliberate: app tests usually need to prove the public
+behavior of the subscription lifecycle, not database durability.
+
+Use memory-backed tests for the normal request/system suite:
+
+- successful HTML GETs inject the subscription marker;
+- the subscription can be activated;
+- mutations select the right streams;
+- broadcasts contain the expected rendered bytes;
+- unauthorized or unrelated bytes are not delivered.
+
+Keep a smaller ActiveRecord-backed test or CI path for storage-specific
+coverage:
+
+- the generated migration matches the required schema;
+- subscriptions and reverse-index rows persist;
+- lookup survives store reload;
+- pruning removes durable rows;
+- Active Job delivery works with the app's queue adapter.
+
+Avoid asserting a store class in general app behavior tests. The memory and
+ActiveRecord stores share the same public lifecycle contract, so app tests
+should mostly assert markers, activation, streams, broadcasts, and rendered
+bytes. Assert `Upkeep::Subscriptions::ActiveRecordStore` only in tests whose
+purpose is durable storage.
+
+## App-Level Assertions
+
+Maintained Rails apps should assert that successful HTML GETs register a
+subscription:
+
+```ruby
+include Upkeep::Rails::Testing
+
+get board_path(board)
+assert_response :success
+assert_upkeep_subscription_registered
+activate_upkeep_subscription!
+```
+
+They should also assert that unauthorized bytes do not render:
+
+```ruby
+get board_path(private_board)
+assert_response :forbidden
+refute_includes response.body, "Private card"
+```
+
+For streamed delivery, include `ActionCable::TestHelper`, capture the
+registered stream names through `Upkeep::Rails::Testing`, perform a mutation,
+drain delivery through the testing namespace, and assert the broadcast payload:
+
+```ruby
+include ActionCable::TestHelper
+include Upkeep::Rails::Testing
+
+broadcasts = capture_upkeep_broadcasts do
+  patch board_card_path(board, card), params: { card: { title: "Updated" } }
+  assert_response :ok
+  drain_upkeep_delivery!
+end
+
+assert_includes broadcasts.join, "Updated"
+refute_includes broadcasts.join, "Other subscriber secret"
+```
+
+## Result Reports
+
+The proof runner writes:
+
+- `results/herb_surface.json`
+- `results/active_record_surface.json`
+- `results/end_to_end_proof.json`
+- `results/identity_safety_proof.json`
+- `results/auth_surfaces_proof.json`
+
+These reports are debugging artifacts for maintained app work. They are useful
+when a change alters frame coverage, dependency metadata, identity
+partitioning, or target selection.