upkeep-rails 0.1.6

data/docs/architecture/identity-and-sharing.md

@@ -0,0 +1,306 @@
+# Identity And Sharing
+
+Upkeep can share rendered work only when it can prove that every value affecting
+the bytes is safe to share. It observes Rails ambient state during render, but
+it does not infer subscriber identity from names such as `Current.user` or
+`current_user`.
+
+Subscriber identity is an explicit bridge:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, current: ["Current", :user] do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+The capture side names the render-time value Upkeep should treat as identity.
+The subscribe side resolves the same identity from the ActionCable connection.
+Both sides are canonicalized before comparison.
+
+The arguments have different responsibilities:
+
+| Part | Responsibility |
+| --- | --- |
+| `:viewer` | Names the identity component inside Upkeep. Use a domain role such as `:viewer`, `:account`, `:tenant`, `:organization`, `:locale`, or `:impersonator`. |
+| `current: ["Current", :user]` | Names the render-side source. This example says a render that reads `Current.user` captures that value as `:viewer`. |
+| `subscribe { |connection| connection.current_user }` | Names the ActionCable-side proof. It must resolve the same logical identity when the browser subscribes. |
+
+The `subscribe` block receives an Upkeep connection context. It delegates public
+methods such as `current_user` to the ActionCable connection and exposes
+`session` and `cookies` directly. It does not expose the raw ActionCable
+`request` object as a supported API.
+
+An identity value may also be absent. By default only `nil` is absent. That
+allows logged-out pages to stay anonymous-public even when they check
+`Current.user`, `warden.user`, or `session[:user_id]`. If an app uses another
+sentinel, the declaration owns that rule:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, session: :user_id do
+    absent_if { |value| value.nil? || value == false }
+    subscribe { |connection| connection.session[:user_id] }
+  end
+end
+```
+
+Upkeep evaluates absence while the raw value is in memory. For session and
+cookie identities, the stored dependency still contains a fingerprint, not the
+raw token.
+
+## Activation Tokens
+
+Every injected `<upkeep-subscription-source>` includes a stateless signed
+activation token for that subscription id. When the browser subscribes, the
+channel verifies the token before it fetches or activates the server
+subscription record.
+
+The token answers a transport question: "is this browser activating the exact
+rendered response that received this source?" It is not application identity
+and does not replace the explicit identity bridge below.
+
+This keeps first-paint subscription activation independent of Rails session
+creation. Upkeep does not need to create a guest cookie just to let the browser
+activate the subscription it already received in the HTML response.
+
+Identified pages still require both checks:
+
+- the activation token must match the subscription id;
+- the declared identity must match the ActionCable connection.
+
+## Common Identity Shapes
+
+Choose the source keyword from the API the render path actually reads.
+
+CurrentAttributes, for apps that set and read `Current.user`:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, current: ["Current", :user] do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+Devise/Warden, for apps whose controllers, helpers, or views call Devise
+`current_user`, `user_signed_in?`, or raw `warden.user(:user)`:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, warden: :user do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+```ruby
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = env["warden"]&.user(:user)
+    end
+  end
+end
+```
+
+Use the matching Warden scope for the Devise model being read, such as
+`warden: :admin` for admin pages. The subscribe block can return
+`connection.current_admin` if that is what the cable connection exposes; it
+does not need to call Warden directly as long as it returns the same logical
+admin.
+
+If a Devise app copies the authenticated user into `Current.user`, declare the
+source the page actually reads. A page that reads only `Current.user` should use
+`current:`. A page that also calls Devise helpers should either declare the
+Warden source as well or avoid the duplicate render-time identity read.
+
+Session, for apps that render directly from `session[:user_id]`:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, session: :user_id do
+    subscribe { |connection| connection.session[:user_id] }
+  end
+end
+```
+
+Cookie, for apps that render directly from a cookie-backed account or tenant:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :account, cookie: :account_id do
+    subscribe { |connection| connection.cookies[:account_id] }
+  end
+end
+```
+
+The identity name, such as `:viewer` or `:account`, becomes part of the canonical
+identity tuple. If a page captures both `:viewer` and `:account`, the cable
+subscription must match both before live updates are authorized.
+
+## What Still Gets Observed
+
+Upkeep still observes these ambient surfaces for replay and sharing:
+
+- `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.
+
+Observed ambient values remain attached to the render graph. They can partition
+render sharing and provide replay inputs, but they do not become subscriber
+identity unless they match a `config.identify` declaration.
+
+This distinction matters for Rails layouts. CSRF helpers, flash, preferences,
+or layout code can read session/cookie values incidentally. Those reads should
+not silently turn every page into an authenticated identity boundary.
+
+## Failure Rules
+
+If a page reads undeclared non-absent `CurrentAttributes` or Warden identity,
+Upkeep refuses live registration instead of guessing:
+
+```text
+subscription has identity dependencies but no declared Upkeep identity mapping
+```
+
+That refusal is intentional. A user-specific page that cannot be matched on the
+ActionCable side should behave like ordinary Rails HTML, not register an unsafe
+live subscription.
+
+If the cable subscription resolves a different value, the channel rejects the
+subscription:
+
+```text
+captured :viewer = User#123
+subscribe :viewer = User#456
+```
+
+If an identity block returns an unsupported object, Upkeep rejects it. Identity
+values should be stable values: Active Record records, GlobalID-capable values,
+strings, symbols, numbers, booleans, or arrays/hashes of those.
+
+## Sharing Rules
+
+Public render output can share when:
+
+- the selected target is the same page, fragment, or render site;
+- the identity signature is `public`;
+- the replay recipe and sharing inputs are equivalent.
+
+Equivalent public targets are grouped before replay, so one render can serve
+multiple subscribers. Delivery still merges identical payload bytes after
+rendering when separate groups converge on the same output.
+
+Identity-bound output is partitioned when:
+
+- a frame reads declared identity such as `:viewer` or `:account`;
+- a frame reads ambient state that changes its identity signature;
+- two subscribers have different observed identity values;
+- the same DOM target renders different bytes under different identity.
+
+Identity dependencies remain attached to the graph for replay and sharing. They
+do not create lifecycle reverse-index rows, because Active Record commits cannot
+select request, session, cookie, Warden, CurrentAttributes, or ActionCable
+identity reads directly.
+
+## Authorization Example
+
+If a card value is visible only when it is under the current user's limit:
+
+```ruby
+class CardPresenter
+  def initialize(card)
+    @card = card
+  end
+
+  def value_content
+    return "Hidden" unless @card.value <= Current.user.value_limit
+
+    "$#{@card.value}"
+  end
+end
+```
+
+Declare the identity bridge:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, current: ["Current", :user] do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+The render reads:
+
+- declared identity `:viewer` from `Current.user`;
+- `Current.user.value_limit`, which records an Active Record attribute
+  dependency for the user row;
+- `card.value`, which records an Active Record attribute dependency for the
+  card row.
+
+When the card changes, each subscriber gets the payload rendered under their
+own identity. When a user's `value_limit` changes, only the subscription bound
+to that user is selected.
+
+## Ambiguous Identity
+
+Identity is ambiguous when render output depends on values outside declared or
+observed Rails surfaces, such as:
+
+- a plain global singleton;
+- an unobserved thread-local;
+- a closure that captured a user or tenant but does not read Current, request,
+  Warden, session, or cookies during render;
+- external process state with no observed request or data dependency.
+
+The correct shape is to make identity visible through Rails-owned surfaces that
+Upkeep observes, then declare the ActionCable subscribe bridge with
+`config.identify`.
+
+## Refused Boundaries
+
+Development and test raise for reactive boundaries that would otherwise become
+unsafe or broad. Production-style warning mode records a refused boundary and
+skips subscription registration.
+
+Opaque collection predicates:
+
+```ruby
+Card.where("status = ?", "open")
+```
+
+Refactor to structural Active Record or Arel:
+
+```ruby
+Card.where(status: "open")
+```
+
+Opaque pluck expressions:
+
+```ruby
+Tag.pluck("LOWER(name)")
+```
+
+Refactor to a structural column read or render outside Upkeep reactivity:
+
+```ruby
+Tag.pluck(:name).map(&:downcase)
+```
+
+Hidden controller state is not a dependency by itself:
+
+```ruby
+@cards = Card.where(status: "open").to_a
+@cards.count
+```
+
+If the materialized relation is rendered as a collection, Upkeep attaches the
+relation dependency to that render site. If scalar query output affects the
+page, use structural `pluck`. If record attributes affect output, read the
+attributes so Active Record attribute dependencies can select the page.

data/docs/architecture/query-dependencies.md

@@ -0,0 +1,230 @@
+# Query Dependencies
+
+Active Record collection dependencies are derived from relation shape. Upkeep
+does not ask the app to register queries, predicates, params, or invalidation
+keys.
+
+## Capture Point
+
+When Rails renders an Active Record relation as a collection, Upkeep analyzes
+the relation before creating the collection dependency:
+
+```erb
+<%= render partial: "cards/card", collection: @board.cards.order(:position), as: :card %>
+```
+
+The dependency stores:
+
+- the primary model table;
+- the relation SQL digest;
+- table and column coverage derived from Arel;
+- proven column coverage;
+- replay inputs for the render-site recipe.
+
+If a controller materializes the relation first, the materialized collection
+retains relation provenance:
+
+```ruby
+def index
+  @cards = Card.where(status: params.fetch(:status)).order(:position).to_a
+end
+```
+
+```erb
+<%= render partial: "cards/card", collection: @cards, as: :card %>
+```
+
+The render-site consumes that provenance and records the collection dependency
+at the rendered collection boundary. `Relation#exec_queries` does not register
+an Active Record collection dependency by itself.
+
+If a controller materializes a relation and never renders that relation-backed
+collection, the materialization is not a lifecycle dependency. Upkeep relies on
+the surfaces that actually affect output: rendered relation collections,
+scalar query dependencies, and record attribute reads.
+
+Scalar relation queries are page-level query dependencies, not collection
+dependencies:
+
+```ruby
+def index
+  @tag_names = Tag.where(active: true).pluck(:name)
+end
+```
+
+This records an `active_record_query` dependency. A matching commit can replay
+the page because scalar query output may affect the page, but the dependency is
+not eligible for collection append/remove/prepend/member-replace planning.
+Simple plucked columns are included in the query dependency. Opaque pluck
+expressions, such as raw SQL expressions, are refused instead of becoming broad
+collection dependencies.
+
+## Collection Coverage
+
+Upkeep records a collection dependency only when it can see the involved tables
+and columns:
+
+```ruby
+Card.where(board_id: board.id, status: "open").order(:position)
+```
+
+This records the `cards` table with the primary key plus the predicate and
+ordering columns. Updates to unrelated columns do not select the collection
+dependency.
+
+Opaque predicates are not registered as broad collection dependencies:
+
+```ruby
+Card.where("status = ?", "open").order(:position)
+```
+
+In development/test this raises `Upkeep::ActiveRecordQuery::OpaqueRelationError`
+while capturing the reactive render. In production-style warning mode, Upkeep
+warns, marks the boundary refused, and skips subscription registration instead
+of broadening to the whole `cards` table.
+
+Preferred refactor:
+
+```ruby
+Card.where(status: "open").order(:position)
+```
+
+Opaque table sources are not reactive:
+
+```ruby
+Card
+  .joins("INNER JOIN authors ON authors.id = cards.author_id")
+  .where("authors.name = ?", "Ada")
+```
+
+This raises `Upkeep::ActiveRecordQuery::OpaqueRelationError` while capturing
+the reactive render. Upkeep does not create a dependency for a relation whose
+table sources cannot be structurally proven.
+
+Preferred refactor:
+
+```ruby
+Card.joins(:author).where(authors: { name: "Ada" })
+```
+
+## Reverse Index Shape
+
+Collection dependencies enter the invalidation reverse index through concrete
+table and column lookup keys:
+
+```ruby
+Card.where(status: "open").order(:position)
+```
+
+This registers collection lookup keys for the proven `cards` columns, such as
+`status`, `id`, and `position`. A lifecycle event for `cards.title` does not
+select this collection unless `title` was part of the proven relation shape.
+
+`active_record_query` dependencies use the same table and column lookup shape,
+but target the nearest page frame. They intentionally do not unlock collection
+operation planning, because scalar query output has no rendered collection
+membership boundary.
+
+Record-specific attribute reads index the exact table, id, and attribute:
+
+```erb
+<%= card.title %>
+```
+
+Bulk or otherwise id-less attribute changes use an any-id attribute lookup key
+for the changed column. Record-specific reads no longer also register an any-id
+lookup row.
+
+Request, session, cookie, CurrentAttributes, Warden, and ActionCable identity
+dependencies are graph inputs, not lifecycle invalidation keys. They partition
+replay and sharing, but an Active Record commit cannot select them directly, so
+they do not occupy reverse-index lookup rows.
+
+## Joins And Aliases
+
+Association joins are structural:
+
+```ruby
+Card.joins(:author).where(authors: { name: "Ada" }).order(:position)
+```
+
+Upkeep records columns from both the `cards` table and the `authors` table.
+Aliased self-joins map alias columns back to the underlying table so committed
+changes use real table names from Active Record callbacks.
+
+## Bulk Writes
+
+Bulk writes are observed through Active Record relation methods:
+
+```ruby
+Card.where(board_id: board.id).update_all(status: "done")
+Card.where(status: "archived").delete_all
+```
+
+For hash updates, Upkeep records the changed keys. For string updates, Upkeep
+records all columns on the model table because parsing assignment SQL would not
+be a structural proof. Relation predicate coverage is derived through the same
+Arel analyzer used for collection reads. Bulk write events may carry table
+coverage for opaque write predicates, but that coverage describes the write
+event; it is not a collection subscription fallback.
+
+## Provable Collection Operations
+
+Collection changes can sometimes be delivered as narrow Turbo Stream operations
+instead of replacing the whole render site. These operations are optimizations,
+not the correctness path.
+
+Operation proofs currently cover:
+
+- `append` for creates when replay proves the new record appears after all
+  previously rendered member ids;
+- `prepend` for creates when replay proves the new record appears before all
+  previously rendered member ids;
+- `remove` for destroys when the prior rendered member target is known;
+- stable member `replace` for updates when the row remains in the relation and
+  replay proves the rendered member order did not change.
+
+Each operation requires a collection render-site recipe, an Active Record
+relation snapshot, a primary key, proven column-level relation coverage, and a
+relation shape without limit, offset, distinct, group, or having. If any
+requirement fails, delivery deoptimizes to the canonical render-site
+replacement recipe and reports the reason.
+
+## Debugging Surface
+
+Collection dependency metadata reports:
+
+```ruby
+{
+  primary_table: "cards",
+  table_columns: { "cards" => ["board_id", "id", "position"] },
+  coverage: "columns",
+  sql: "SELECT ..."
+}
+```
+
+The important debugging question is the coverage level. `columns` is narrow and
+accepted for collection dependencies. Opaque predicates or table sources raise
+a guided error in development/test or become refused boundaries in
+production-style warning mode instead of registering a broad invalidation
+dependency.
+
+Operation planning also reports whether a narrow collection operation was
+proved or deoptimized to replacement. These diagnostics explain implementation
+choices; benchmark summaries remain responsible for comparing runtime cost
+against Turbo refresh and manually written Turbo Stream operations.
+
+## No Query Catalog
+
+There is no Rails-side equivalent of:
+
+```ruby
+tracks_query :open_cards
+declared_inputs :board_id, :status
+config.identity_attributes = [...]
+```
+
+The runtime derives what it can from Active Record and Arel. When it cannot
+prove the table sources for a relation, it rejects the reactive boundary with
+guidance to rewrite the query through structural Active Record/Arel joins or
+move the render outside Upkeep reactivity.

data/docs/architecture/subscription-store-contract.md

@@ -0,0 +1,66 @@
+# Subscription Store Contract
+
+`Upkeep::Subscriptions` uses duck typing for subscription storage. Callers
+should depend on the store protocol below, not on whether the implementation is
+in-memory or Active Record backed.
+
+The contract is enforced by `test/support/subscription_store_contract.rb`.
+Implementation-specific tests may add storage behavior, but they should not
+weaken these lifecycle rules.
+
+## Lifecycle
+
+- `register(subscriber_id:, recorder:, metadata: {}, entries: nil)` creates a
+  pending subscription and returns it. The subscription is fetchable immediately.
+- `activate(id)` makes the subscription lookup-visible and returns `true`.
+  Missing ids return `false`.
+- `fetch(id)` returns a subscription or raises
+  `Upkeep::Subscriptions::NotFound`.
+- `unregister(ids)` removes subscriptions from fetch and lookup state. It is
+  idempotent for callers and returns the number of ids requested for removal.
+- `touch(id, now:)` updates liveness metadata and raises `NotFound` for missing
+  ids.
+- `prune_stale!(older_than:)` removes subscriptions whose liveness timestamp is
+  older than the threshold and returns the number removed.
+
+Registration and lookup visibility are intentionally separate. A rendered HTML
+response can register a durable subscription before the browser proves that it
+opened the matching ActionCable stream. Delivery planning should see only
+activated subscriptions.
+
+## Lookup Surface
+
+- `reverse_index.entries_for(changes)` is the only lookup surface used by the
+  invalidation planner.
+- Active subscriptions are visible to lookup.
+- Pending subscriptions are observable in diagnostics but not returned for
+  delivery.
+- Identity-free subscriptions may be represented as cohort entries, where one
+  dependency entry can represent many subscriber ids.
+
+## Durability Hooks
+
+- `drain` flushes durable work. It is meaningful for Active Record and a no-op
+  success for memory.
+- `shutdown` stops durable resources. It is meaningful for Active Record and a
+  no-op success for memory.
+- `reset` clears all store state.
+- `summary` reports subscription counts and reverse-index diagnostics. Active
+  Record summaries split active, pending, direct persistent, and shape
+  persistent index state.
+
+## Implementation Boundaries
+
+The memory store is an in-process contract implementation. It should stay small
+and deterministic.
+
+The Active Record store adds:
+
+- durable subscription rows,
+- durable direct and shape index rows,
+- async writes,
+- reload and cross-process lookup,
+- schema validation and production suitability.
+
+Those storage mechanics are implementation details. The lifecycle contract above
+is the shared behavior callers can rely on.