upkeep-rails 0.1.0

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

@@ -0,0 +1,187 @@
+# Identity And Sharing
+
+Upkeep can share rendered work only when every value that can affect the bytes
+is represented in the graph identity. Rails apps should not declare identity
+dimensions to Upkeep. The runtime derives identity by observing Rails request,
+auth, current-context, and ActionCable surfaces.
+
+## Observed Identity Surfaces
+
+CurrentAttributes:
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :account_id
+end
+```
+
+Reads of `Current.user`, `Current.account_id`, and other
+`ActiveSupport::CurrentAttributes` attributes are recorded as identity
+dependencies for the frame that performed the read.
+
+Warden and Devise:
+
+```ruby
+request.env["warden"].user(:user)
+```
+
+Warden `user` and `authenticate` calls record the requested scope and canonical
+user identity. Devise applications normally route `current_user` through Warden,
+so the same observer covers that path when the rendered code reaches Warden.
+
+Session and cookies:
+
+```ruby
+session[:tenant_id]
+cookies[:theme]
+```
+
+Session and cookie reads record private fingerprints of the values. The values
+are not exposed in delivery reports. Controller page replay keeps the observed
+raw values only when replay needs them; unread session keys and cookies are not
+copied into replay payloads.
+
+Request values:
+
+```ruby
+request.subdomain
+request.params
+request.user_agent
+```
+
+Request reads record the key and a private fingerprint of the value. Host,
+subdomain, path, fullpath, request method, user agent, remote IP, and params are
+covered. Replay copies only the observed request values that map to supported
+Rack env keys, such as `request.user_agent`; unread headers such as
+authorization or CSRF-style headers are not copied.
+
+ActionCable identifiers:
+
+```ruby
+identified_by :current_user
+```
+
+The subscription stream identity is derived from canonical ActionCable
+connection identifiers and, for the request that created the subscription,
+observed recorder identity dependencies.
+
+## 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 `Current.user`, another CurrentAttributes value, Warden/Devise,
+  session, cookie, or request state;
+- two subscribers have different observed identity values;
+- the same DOM target renders different bytes under different identity.
+
+The delivery layer consumes identity signatures. It does not decide whether a
+subscriber is eligible for a payload.
+
+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
+```
+
+The render reads:
+
+- `Current.user`, which partitions the frame by 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 subscriber identity
+bound to that user is selected.
+
+## Ambiguous Identity
+
+Identity is ambiguous when render output depends on values outside the 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: CurrentAttributes, Warden/Devise, session, cookies, request
+values, ActionCable identifiers, or Active Record reads.
+
+## 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.
+
+## No Scope Registry
+
+There is no `identity_attributes`, `tracks :tenant_id`, `declared_inputs`, or
+session-key allow-list. A host-maintained registry would either duplicate what
+the runtime can observe or become a silent data-leak risk when the host forgets
+an input. Upkeep's identity claim depends on structural observation.

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.