upkeep-rails 0.2.5-aarch64-linux-gnu

data/docs/how-it-works.md

@@ -0,0 +1,329 @@
+# How Upkeep Works
+
+This document explains the runtime model behind Upkeep Rails. It intentionally
+does not cover installation or common configuration; use the
+[README](../README.md) for that public API surface.
+
+## Rendered Pages
+
+A rendered page is a successful HTML GET that Upkeep can keep fresh. The
+request runs normally through Rails. Upkeep observes the controller, Action View
+rendering, Active Record reads, request inputs, and identity inputs used by the
+response.
+
+Upkeep only captures successful HTML responses. Non-HTML responses, redirects,
+failed responses, and explicit non-page interactions continue to behave like
+ordinary Rails responses.
+
+## Frames
+
+A frame is a rendered page, template, partial, collection render site, or
+fragment with a stable delivery target.
+
+Frames let Upkeep refresh a specific part of the page instead of replaying the
+whole response when a narrower update is proven safe. A page frame is the broad
+fallback. A render-site or fragment frame is narrower.
+
+Upkeep instruments Action View templates and adds internal `data-upkeep-*`
+markers for page roots, fragment roots, and safe collection render-site
+containers. Normal templates do not need to call helper APIs directly.
+
+The `upkeep_frame` helper is an advanced escape hatch for generated or
+helper-built boundaries that cannot be derived from template source. Ordinary
+ERB and partial collections should not need it.
+
+### Controller Work and Render Regions
+
+Dependencies inherit the frame that is active when the read occurs. A query
+inside a partial or `upkeep_frame` belongs to that render region. A query in a
+controller callback or action runs before rendering, so its narrowest sound
+boundary is the page:
+
+```ruby
+before_action do
+  @show_reminder = !current_user.time_logs.where(log_date: Date.current).exists?
+end
+```
+
+Rails does not record which later template expression consumes an instance
+variable. Ruby may also pass or access that value dynamically, so Upkeep cannot
+reliably infer that `@show_reminder` affects only one element. A matching
+`TimeLog` change can therefore select a page replay.
+
+When controller work exists only to render one section, execute it inside that
+section instead:
+
+```erb
+<%= upkeep_frame "layout/time-log-reminder" do %>
+  <div data-upkeep-render-site="layout/time-log-reminder">
+    <% if time_log_reminder_data %>
+      <%= render "shared/time_log_reminder" %>
+    <% end %>
+  </div>
+<% end %>
+```
+
+The helper or partial can perform the query while this frame is active. Upkeep
+then associates the dependency with the reminder region instead of the page.
+The region must always render a stable target, including when its conditional
+content is empty, so it can transition in either direction.
+
+This is a granularity rule, not a refusal: controller-level reads remain live
+through a conservative page replay. Use an explicit region only when that
+broader replay is undesirable and the application knows the true presentation
+boundary.
+
+## Surfaces
+
+A surface is the set of facts about future writes that would make a frame
+stale.
+
+For Active Record, Upkeep derives surfaces from observed record attributes,
+rendered collections, and relation shape where Rails exposes structural Arel
+queries. A rendered collection of open cards ordered by position produces a
+surface tied to the cards table, the columns that decide membership and order,
+and the records rendered in that collection.
+
+When a write commits, Upkeep compares the write facts with registered surfaces.
+Only frames whose surfaces can be affected are selected for delivery.
+
+Controller requests and Active Job executions both establish a change-capture
+boundary. After the boundary completes, Upkeep plans and delivers updates for
+the committed Active Record changes. Sidekiq jobs using the Active Job adapter
+are covered by this lifecycle; direct Sidekiq workers are not.
+
+## Identity Boundaries
+
+An identity boundary is state that decides who may receive a live update.
+
+Upkeep records observed CurrentAttributes, Warden, session, cookie, and request
+reads for replay and sharing. It does not infer subscriber identity by naming
+convention. The app declares which render-time value maps to which
+subscribe-time ActionCable value.
+
+The safety rule is simple: if rendered output depends on a non-public identity,
+only subscribers proving the same identity may receive that output. If Upkeep
+cannot identify the boundary, it refuses live registration rather than sending
+viewer-specific HTML to the wrong browser.
+
+Absent identities are public. For example, if a logged-out page reads a nil
+viewer, that nil value can be treated as anonymous-public instead of
+subscriber-specific.
+
+## Subscriptions
+
+A subscription is the browser's live connection back to the captured page.
+
+Upkeep injects a body-scoped `<upkeep-subscription-source>` marker into
+successful HTML responses. The generated browser bootstrap upgrades that marker
+into a Turbo stream source, subscribes over ActionCable, and lets Turbo process
+received stream payloads.
+
+The server stores a replayable subscription graph for the rendered page. The
+graph contains frames, dependencies, target metadata, replay recipes, request
+inputs, and identity information needed to plan later updates.
+
+Turbo Frames are graph scopes inside that page subscription. A frame response
+replaces the matching scope while the shell and sibling scopes remain intact.
+The browser connects the composed subscription before disconnecting the
+previous one, so a frame visit never leaves the visible page without its full
+dependency graph.
+
+## Proven Delivery
+
+Proven delivery means Upkeep only emits the narrowest Turbo operation it can
+justify.
+
+Depending on the proof available, delivery may use:
+
+- `append`
+- `prepend`
+- `remove`
+- `replace`
+- `update`
+- Turbo page `refresh`
+
+Render-site replays use Turbo Stream `update method="morph"` against the real
+HTML element Upkeep marked as the render site. The stream template is the
+render site's children, so `update` preserves the legal container element and
+swaps its contents.
+
+Page-level fallbacks use Turbo Stream `refresh method="morph"
+scroll="preserve"` instead of replacing `<html>` or writing a new document from
+JavaScript.
+
+When a change was committed while handling a GET or HEAD request, the refresh
+tag also carries that request's Turbo id as `request-id` (from
+`Turbo.current_request_id` or the `X-Turbo-Request-Id` header). Turbo 8's client
+ignores refreshes for its own recent requests, so view tracking cannot refresh
+the viewer who caused it into a self-refresh loop. Mutations omit the request id
+so the originating tab still refreshes when its response does not render every
+affected region. Writes from jobs or the console also refresh everyone.
+
+## Deoptimization
+
+A deoptimization means Upkeep can still prove correctness, but not the cheapest
+operation.
+
+For example, a collection member update might not have enough proof for a
+single member `replace`, but the enclosing render site might still be safe to
+rerender. In that case, the page remains live and Upkeep falls back to the
+broader proven target.
+
+Planning and delivery telemetry record deoptimization reasons so benchmarks and
+tests can separate safety fallbacks from true refusals.
+
+## Refused Boundaries
+
+A refused boundary means Upkeep cannot prove correctness.
+
+If Upkeep cannot answer which future write facts can make a rendered result
+stale, which target can be replayed or patched, or which identity inputs decide
+sharing, it refuses the live boundary.
+
+This is intentional. A boundary that cannot be proven should behave like
+ordinary Rails HTML instead of registering a broad or unsafe live dependency.
+
+Refusal is different from deoptimization:
+
+- refusal: Upkeep cannot prove correctness, so the boundary is not live
+- deoptimization: Upkeep can prove correctness through a broader target, so the
+  boundary remains live
+
+## What Upkeep Observes
+
+Render structure:
+
+- Rails-resolved page templates
+- partial and object partial renders
+- Action View-instrumented collection render sites and child fragments
+- polymorphic `render @records` collection shorthand when runtime rendering
+  confirms a collection
+- `tag.*` and `content_tag` containers lowered by Herb into ordinary template
+  structure
+- single-root fragment targets and legal render-site container targets
+
+Template parsing:
+
+- Upkeep plans narrow source-derived targets only from templates that pass
+  Herb's strict parser.
+- If strict parsing fails but Herb can recover with `strict: false`, Upkeep
+  reports the strict parser diagnostics as warnings and may still add broad
+  page or fragment root markers.
+- Recovered render sites are diagnostic only. Fix strict warnings before
+  expecting narrow collection updates from that template.
+
+Data dependencies:
+
+- Active Record attribute reads
+- Active Record relation collection renders
+- Active Record callback writes
+- supported bulk `update_all` and `delete_all` writes
+- relation table and column coverage derived from Arel where Rails exposes a
+  structural query shape
+
+Identity and ambient inputs:
+
+- `ActiveSupport::CurrentAttributes` reads
+- Warden and Devise user reads through Warden
+- session and cookie reads
+- request values such as host, path, params, user agent, and remote IP
+- declared Upkeep identities that map observed render-time values to
+  ActionCable subscribe-time values
+
+## What Upkeep Cannot Capture
+
+Upkeep captures reactive facts, not arbitrary Ruby execution. A boundary is
+capturable only when Upkeep can prove the future write facts that affect it,
+the target that can be replayed or patched, and the identity inputs that decide
+whether it can be shared.
+
+These surfaces are not capturable today:
+
+| Surface | Why it is not capturable | Runtime behavior |
+| --- | --- | --- |
+| Opaque Active Record relations: raw SQL predicates, raw joins, raw `from` sources, unknown table aliases, opaque order expressions, or opaque pluck columns. | Rails no longer exposes enough structure to prove table, column, predicate, and lifecycle coverage. | Upkeep refuses the live boundary instead of widening to an unsafe dependency. |
+| Controller queries that are never rendered as a collection boundary. | There is no DOM collection surface where membership can be appended, removed, prepended, or replaced. | The page can still render normally. Scalar relation output may be tracked as a page-level dependency, but it does not unlock collection stream planning. |
+| Reads from external stores or process state: Redis, HTTP APIs, files, global variables, class variables, singleton caches, background thread state, or service memoization. | Active Record commit facts cannot select these reads, and Upkeep has no source adapter for their lifecycle. | They are not live dependencies. If another observed dependency causes a replay, normal Rails code may read the new value during that replay. |
+| Writes outside observed Active Record paths: direct connection SQL, writes in another datastore, or side effects that do not emit Upkeep change facts. | Upkeep cannot match a future change to an existing surface without a write fact. | No refresh is scheduled from that write. |
+| Replay inputs that cannot be rebuilt: arbitrary objects, procs, IO handles, open clients, or values that only exist in one Ruby process. | A captured target must be replayable later, often in a different request context. | Non-replayable values block the narrow replay path until represented as stable data. |
+| Patch targets Upkeep cannot identify in rendered HTML. | Delivery needs a stable page, render-site, fragment, or member target. | Upkeep uses the narrowest proven target. If no safe target exists, the boundary is refused. |
+
+## Query Shapes
+
+Collection dependencies are accepted only with proven column coverage. Opaque
+predicates or table-only sources are refused instead of widening into broad
+invalidation.
+
+Controller materialization is supported when the rendered value keeps a
+structural relation proof:
+
+```ruby
+def index
+  @cards = Card.where(status: "open").order(:position).to_a
+end
+```
+
+```erb
+<%= render partial: "cards/card", collection: @cards, as: :card %>
+```
+
+Upkeep attaches the collection dependency to the rendered collection boundary,
+not to every controller query. A materialized relation that is never rendered as
+a collection is not a lifecycle dependency by itself.
+
+Scalar relation output is tracked as a page-level query dependency:
+
+```ruby
+@tag_names = Tag.where(active: true).pluck(:name)
+```
+
+Simple plucked columns are live and can select a page replay when they change.
+They are not collection dependencies, so they do not participate in
+append/remove/prepend planning.
+
+## Testing Model
+
+Use `Upkeep::Rails::Testing` for app-level assertions around subscription
+registration and delivery.
+
+Structure tests around behavior, not store internals:
+
+- Most request and system tests can run against the memory store. Memory has
+  the same public lifecycle as ActiveRecord: registration is fetchable
+  immediately, lookup visibility starts on activation, touch updates liveness,
+  unregister and prune remove lookup entries, and delivery uses the same
+  planner surface.
+- Keep a smaller ActiveRecord-backed integration slice for production-only
+  concerns: generated migration shape, schema validation, durable rows,
+  reload and rehydration, async persistence, and cross-process lookup.
+- Do not assert implementation details that are unique to one store unless the
+  test is explicitly about that implementation. For app behavior, assert the
+  marker, activation, streams, broadcasts, and rendered bytes.
+
+Useful helpers:
+
+- `assert_upkeep_subscription_registered`
+- `upkeep_subscription`
+- `upkeep_stream_names`
+- `activate_upkeep_subscription!`
+- `capture_upkeep_broadcasts`
+- `drain_upkeep_delivery!`
+- `capture_upkeep_change_facts`
+- `upkeep_match_report`
+
+Use `capture_upkeep_broadcasts` when an app test needs to assert rendered
+Turbo Stream payloads without depending on the host app's Action Cable test
+adapter. The helper captures Upkeep delivery after planning and rendering, but
+before the transport broadcasts.
+
+Use `capture_upkeep_change_facts` and `upkeep_match_report` when debugging an
+invalidation miss. Capture the committed facts produced by the request, then
+dry-run them against the current subscription store. The report returns the
+candidate count, matched count, miss reason, and render targets without
+broadcasting.
+
+For structural subscription debugging, call `subscription.explain` or
+`Upkeep::Rails.subscriptions.explain(subscription.id)`. Explanations summarize
+the dependency tables and attributes, identity, frame count, lookup keys, and
+metadata without requiring store-specific instance-variable inspection.

data/docs/plans/sqlglot-active-record-migration.md

@@ -0,0 +1,211 @@
+# SQLGlot Active Record query-analysis migration
+
+## Goal
+
+Make SQLGlot the only production decoder for Active Record relation
+dependencies in the next Upkeep release. Use the former Arel oracle to freeze a
+parity corpus, then delete the oracle once the SQLGlot, raw-SQL, and adapter
+corpora prove the same dependencies.
+
+“Drop Arel” means Upkeep production code does not call `Relation#arel`, inspect
+Arel nodes, or select a structured/unstructured policy. Active Record may still
+use Arel internally to generate `Relation#to_sql`.
+
+## API boundary
+
+Upkeep owns a small Ruby wrapper over the released `sql-glot-rust` C ABI. Its
+names, arguments, and result shapes follow the native API:
+
+1. Wrap the existing parse and generation API:
+   - `Upkeep::SQLGlot.parse(sql, dialect:)`
+   - `Upkeep::SQLGlot.generate(statement, dialect:)`
+   - `Upkeep::SQLGlot.transpile(sql, from:, to:)`
+2. Project the released semantic API:
+   - `MappingSchema`
+   - `qualify_columns(statement, schema)`
+   - `build_scope(statement)`
+   - `lineage(column, statement, schema, config)`
+3. Preserve Rust/Python scope and lineage fields. Do not flatten child scope
+   collections or introduce an Upkeep-shaped SQLGlot response.
+
+There is deliberately no combined `Upkeep::SQLGlot.analyze` API.
+
+Upkeep-specific lowering remains separate from the sibling API:
+
+```text
+Upkeep::SQLGlot.parse + SQL schema
+            │
+            ▼
+Upkeep::SQLGlot::MappingSchema
+Upkeep::SQLGlot.qualify_columns
+Upkeep::SQLGlot.build_scope
+            │
+            ▼
+Upkeep::SQLDependencyAnalysis
+            │
+            ▼
+Upkeep::ActiveRecordQuery::Result
+```
+
+`SQLDependencyAnalysis` owns physical dependency sources, referenced columns,
+simple predicate DNF, equality edges, query shape, and conservative warnings.
+`ActiveRecordQuery` owns model table, primary key, adapter dialect, schema
+extraction, and the internal result contract.
+
+This release is intentionally breaking. There are no existing users to migrate,
+so no compatibility decoder, cache migration, top-level `Sqlglot` namespace,
+or mixed installation is supported. Installing the release requires a full
+bundle/gem reinstall so Bundler selects the matching Upkeep platform gem.
+
+## Native SQLGlot packaging
+
+`upkeep-rails` depends on `ffi` and binds `sql-glot-rust` v0.10.26 directly.
+The Ruby boundary lives under `Upkeep::SQLGlot`; there is no external
+`sqlglot` Ruby gem dependency and no Upkeep-specific Rust crate or C ABI.
+
+There is one logical gem. Each
+release consists of five platform-specific `upkeep-rails` artifacts:
+
+- `x86_64-linux-gnu`;
+- `aarch64-linux-gnu`;
+- `x86_64-darwin`;
+- `arm64-darwin`; and
+- `x64-mingw-ucrt`.
+
+The released v0.10.26 tag is built in release CI and its unmodified shared
+library is included in each artifact. Rust sources are build inputs and are not
+shipped in the gem, so installation never requires Rust. There is deliberately
+no generic source artifact.
+
+The v0.10.26 scope builder preserves CTE references as scope sources. Upkeep
+does not treat a scope source as a physical table; the AST lowerer resolves the
+logical CTE to its physical child and scope validation checks every
+schema-backed source.
+
+Active Record SQL types remain available in the Ruby `MappingSchema`. The
+native dependency schema represents every column type as `UNKNOWN` because
+qualification and lineage inspect table and column identity, not column type.
+Database-specific types therefore cannot prevent dependency extraction, and
+Upkeep does not maintain a parallel SQL type catalog.
+
+`qualify_columns` expands wildcards by design. Upkeep restores wildcard
+projection nodes before dependency lowering so `SELECT table.*` does not add
+every model attribute to collection invalidation. Qualification in predicates,
+joins, grouping, ordering, and explicit projections is retained.
+
+## Implementation stages
+
+### 1. Establish SQLGlot as an internal runtime boundary
+
+- Bind the released Rust library through `ffi`.
+- Add adapter-to-dialect mapping.
+- Convert Active Record schema metadata into SQLGlot-compatible table/column
+  metadata, retaining SQL types where available.
+- Fail closed with an actionable SQL analysis error; never silently subscribe
+  only to the primary table after an unknown joined source.
+
+### 2. Productize dependency lowering
+
+- Move the SQL-first spike into `Upkeep::SQLDependencyAnalysis`.
+- Accept SQL AST, dialect, and schema only—no relation or model objects.
+- Keep SQL constructs inside this decoder and lower them into a generic graph:
+  physical tables, columns, equality edges, predicate groups, and query shape.
+- Treat CTEs and derived sources as logical sources backed by physical tables.
+- Record ambiguity as conservative coverage or an unsupported analysis, never
+  as a missing dependency.
+
+### 3. Switch the Active Record runtime path
+
+- Make `ActiveRecordQuery.analyze` parse `relation.to_sql` with SQLGlot.
+- Preserve `ActiveRecordQuery::Result` so invalidation/replay consumers do not
+  need a simultaneous rewrite.
+- Give write observation a separate `analyze_for_write` entry point. It may
+  conservatively describe the model table when semantic predicate analysis
+  fails; this is not a collection-query decoder or runtime fallback.
+- Update opaque-query guidance so it no longer asks users to rewrite SQL as
+  Arel.
+
+### 4. Move Arel to an oracle
+
+- Move the current collector to test support and rename it
+  `ArelQueryAnalysisOracle`.
+- Production `lib/` must contain no Arel node dispatch and no
+  `Relation#arel` call.
+- Compare the oracle with SQLGlot for relations the oracle can prove.
+- SQLGlot may report additional safe dependencies. It must not omit any table,
+  column, predicate, or query-shape restriction proven by the oracle.
+- Raw SQL cases that the oracle rejects are asserted directly against SQLGlot.
+
+### 5. Verification and release hardening
+
+- Cover existing query-analysis tests and Pulse #1802 edge cases.
+- Add raw predicate, raw join, alias/self-join, correlated subquery, CTE,
+  function/operator, `IN`, null, negation, OR-DNF, group/having/distinct,
+  limit/offset, and parse-error cases.
+- Run the full Upkeep suite.
+- Benchmark parsing separately from invalidation fan-out. This milestone does
+  not add an Upkeep-owned analysis or schema cache.
+- Package the released native library for every supported platform.
+
+## Oracle exit criteria
+
+Arel can be deleted after:
+
+- the supported adapter corpus has no known dependency false negatives;
+- SQLGlot covers every relation the oracle proves;
+- raw SQL coverage has dedicated assertions;
+- unsupported SQL fails with query, dialect, and parser diagnostics;
+- production code has no oracle switch or fallback;
+- analysis stays outside invalidation fan-out and meets the agreed performance
+  budget.
+
+## Current milestone
+
+This milestone is complete in the 0.2.0 release branch: `Upkeep::SQLGlot` is
+the only production SQL decoder, the former oracle outputs are frozen as
+ordinary expected values, and the Arel collector has been deleted. Remaining
+Arel usage in tests constructs Active Record input queries only; no Upkeep
+analyzer inspects Arel.
+
+## Execution status
+
+Completed:
+
+- [x] Added `Upkeep::SQLGlot` as the production runtime parser.
+- [x] Added generic SQL AST dependency lowering in
+  `Upkeep::SQLDependencyAnalysis`.
+- [x] Switched `ActiveRecordQuery.analyze` from `Relation#arel` to
+  `Upkeep::SQLGlot.parse(relation.to_sql, dialect:)`.
+- [x] Kept schema access on Active Record's existing schema cache; Upkeep owns
+  no analysis or schema cache.
+- [x] Added a separate conservative write-analysis path without introducing a
+  collection-query fallback.
+- [x] Used `ArelQueryAnalysisOracle` to freeze the parity corpus, then deleted
+  the collector and its test-support require.
+- [x] Added direct raw-SQL coverage, including correlated subqueries, CTEs,
+  set operations, PostgreSQL operators, and MySQL/SQLite functions.
+- [x] Bound parse, generate, transpile, `MappingSchema`, qualification, scope,
+  and lineage directly to `sql-glot-rust` v0.10.26.
+- [x] Decoupled dependency schemas from database type parsing while retaining
+  the original SQL types at the Ruby boundary.
+- [x] Preserved Rust scope and lineage fields and locked the corrected CTE
+  scope-source behavior in a binding test.
+- [x] Added five platform-specific `upkeep-rails` artifacts for macOS, Linux,
+  and Windows, with no source gem or install-time Cargo build.
+- [x] Added an adapter corpus for PostgreSQL, MySQL, and SQLite.
+- [x] Added a warm semantic-analysis performance gate with a 2 ms CI budget;
+  the local 10,000-iteration mean is approximately 146 µs.
+- [x] Verified the full suite and the focused performance gate.
+- [x] Removed compatibility and mixed-installation handling; this release
+  requires a full reinstall.
+
+Upstream and ecosystem follow-up:
+
+- [x] Open the semantic Ruby bindings in `sql-glot-ruby`.
+- [x] Merge the CTE source-overwrite fix in `sql-glot-rust`; it shipped in
+      v0.10.24 through
+      [`protegrity/sql-glot-rust#26`](https://github.com/protegrity/sql-glot-rust/pull/26).
+- [x] Merge and release the Rust semantic C ABI in v0.10.25.
+- [x] Delete the Upkeep-specific Rust bridge and external Ruby SQLGlot
+      dependency.
+- [ ] Continue the Ruby wrapper PRs as optional ecosystem contributions.

data/docs/plans/turbo-frame-subscription-composition.md

@@ -0,0 +1,90 @@
+# Turbo Frame subscription composition
+
+## Goal
+
+Keep one authoritative Upkeep subscription for the visible page across Turbo
+Frame navigation.
+
+A frame response is not a page response. Turbo extracts only the matching
+`<turbo-frame>`, and frame endpoints may omit the application shell and sibling
+frames. Replacing the page subscription with the response capture would
+therefore lose dependencies that are still visible. Keeping both captures would
+retain stale dependencies and duplicate invalidation fan-out.
+
+## Model
+
+`turbo_frame_tag` establishes a generic render scope in the dependency graph:
+
+```text
+page
+├── shell
+├── turbo_frame:filters
+│   └── current frame dependencies
+└── turbo_frame:details
+    └── current frame dependencies
+```
+
+For a Turbo Frame GET, the browser sends the current subscription identity and
+Turbo's target frame id. Upkeep captures the response, finds the matching render
+scope in both graphs, and creates a new pending subscription from:
+
+```text
+old page graph - old target subtree + response target subtree
+```
+
+The old subscription remains active while Action Cable connects the candidate.
+After `connected`, the client installs the candidate as current and
+unsubscribes the old subscription. Rejected or superseded candidates never
+replace the active page graph.
+
+## Invariants
+
+- There is one current page subscription per browser document.
+- A page with no reactive full render keeps a dormant coordinator; its first
+  reactive frame establishes the subscription.
+- A frame transition changes only the matching render scope.
+- Shell and sibling dependencies survive frame navigation.
+- Replaced dependencies leave the reverse index when the old cable subscription
+  disconnects.
+- The server accepts a base subscription only with a valid activation token and
+  the same derived subscriber identity.
+- A response cannot become current unless its Action Cable subscription
+  connects.
+- Concurrent frame responses are ordered by the browser transition generation;
+  a late response cannot restore an older graph.
+- Expired or structurally incompatible base graphs request a full Turbo render
+  instead of discarding already-active scopes.
+
+## Protocol
+
+Before a frame fetch, the client adds these headers when a current subscription
+exists:
+
+- `X-Upkeep-Subscription-Id`
+- `X-Upkeep-Subscription-Token`
+
+After composing and registering the replacement, the response adds:
+
+- `X-Upkeep-Subscription-Id`
+- `X-Upkeep-Subscription-Token`
+- `X-Upkeep-Subscription-Channel`
+- `X-Upkeep-Subscription-Stream`
+
+`turbo:frame-render` is the commit point. The custom subscription source reads
+the response headers and starts the atomic cable transition. Full-page Turbo
+Drive visits continue to replace the body-scoped source element normally.
+
+## Implementation
+
+- [x] Capture `turbo_frame_tag` blocks as `turbo_frame` graph nodes with
+  controller replay recipes.
+- [x] Add generic DAG subtree replacement and recorder composition.
+- [x] Validate and compose frame registrations against the active page
+  subscription.
+- [x] Return candidate subscription metadata in response headers.
+- [x] Keep the body source stable during frame visits and atomically switch its
+  Action Cable subscription.
+- [x] Cover graph composition, replay/targeting, request protocol, race/rejection
+  behavior, and a real Turbo Frame navigation followed by live invalidation.
+- [x] Regenerate Pulse's installed client, run the full Upkeep proof suite, and
+  repeat the Pulse browser scenario without a page reload.