solid_objects 0.4.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e027a73cc399aa779d8a60acae69f3f379ce505e060123ad49d5d64dcda4809
-  data.tar.gz: 5eb1be4b51649c2c8e6056f0138f130f4f1a8cf2e55e46f86061fc82849658aa
+  metadata.gz: 9e251e3648db71bc5e325e1d8a20be55f927ca08208052acebd973eb78e15497
+  data.tar.gz: 9362cf7145cb58c02273411dc619a775d7693d238d3f2212d7c4f6336abc30cb
 SHA512:
-  metadata.gz: 7f36f021e2707bbd67fcca022a88a4aa70b5cc35f8175c0ee526defcfb66fb1d3113434d8f700aad1f813ca9ccf49bc6a7e59e8d7c95717f007a660ca7535bd4
-  data.tar.gz: 246e46e83aae40b366992c7c5e763dc65e00945d57b0c0e724595d2f6af0a66ea5c09d5d4dbc5f4c4bdc1ed4de6766d217560e6b376832a98afab158f82e16ea
+  metadata.gz: de728511cbd174ba841030f3e29e3dd4245ccd4dd8168523bf132100a8e4ee0c14f02781bf0b29c08a184f3688708f01d8227662068e6a25ebac1ea2b948c72e
+  data.tar.gz: a9d34e2ae1defd4288bd9322b3d717ae1fbcc99836f96d76ae2a09d62355e17349089e4b53d9febcefe98aa788c5753b5abcbeee1c9dce08e6968b38297f336e

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.5.1 - 2026-08-07
+
+- Restore the SQLite busy wait that a synchronous invocation suspends for its
+  deadline. Rails installs the busy wait as a Ruby busy handler through the
+  sqlite3 `timeout` configuration, which `PRAGMA busy_timeout` reports as zero
+  and silently replaces, so the previous save and restore left pooled
+  connections with no busy handler at all. Every later writer on that
+  connection, inside or outside Solid Objects, then failed immediately with
+  `SQLite3::BusyException` instead of waiting for the lock. Suspend the busy
+  wait only when the adapter can identify how to restore it, so an Active
+  Record release that stops exposing the configured timeout loosens
+  synchronous deadline bounds instead of stripping lock waiting from a shared
+  pooled connection.
+
+- Run the doctor round-trip probe on a dedicated caller process, and accept an
+  explicit process registry in `SynchronousInvocation`, so the probe can no
+  longer stop and delete a shared application caller process, release its
+  activations, and unclaim its messages.
+- Report doctor probe cleanup failures as a failed or warned check instead of
+  raising a database lock error out of the command and leaking the probe
+  caller process.
+- Instrument component refreshes with actor identity, component name, key,
+  dependencies, refresh method, revision, and outcome, excluding locals.
+
+## 0.5.0 - 2026-08-07
+
+- Add repeatable reactive components with signed string or integer keys and
+  JSON-compatible partial locals.
+- Add opt-in Turbo morph refreshes with superseded-request cancellation and
+  browser-side actor revision fencing.
+- Pass signed component keys and locals through request-time query
+  authorization without broadcasting personalized HTML.
+
 ## 0.4.3 - 2026-08-07
 
 - Bound SQLite caller-process registration, reuse, heartbeat, and synchronous

data/README.md

@@ -205,9 +205,42 @@ dependencies changes:
 <% end %>
 ```
 
+Component names can repeat when each instance has a stable key. Signed
+JSON-compatible locals let one conventional partial render the matching
+projection:
+
+```erb
+<%= solid_object @room, authorization_context: current_user do |room| %>
+  <% @players.each do |player| %>
+    <%= room.component :player,
+      key: player.id,
+      observes: %i[players life_totals],
+      locals: { player_id: player.id },
+      refresh: :morph %>
+  <% end %>
+<% end %>
+```
+
+The host partial still resolves only to `actors/chat_room/_player`. It receives
+`actor`, `authorization_context`, `component_key`, and the declared locals:
+
+```erb
+<article id="player_<%= player_id %>">
+  Life: <%= actor.life_totals.fetch(player_id.to_s) %>
+</article>
+```
+
+The default refresh strategy is `:replace`. `refresh: :morph` loads the
+authorized component HTML through a gem-owned browser element, rejects stale
+responses by actor revision, and applies the result using Turbo's scoped
+`replace method="morph"`. Superseded requests for the same keyed target are
+aborted. This preserves unchanged DOM nodes where Turbo's morphing rules allow
+it, including focus and `data-turbo-permanent` content.
+
 `room.component(:messages)` resolves only
 `actors/chat_room/_messages`. Its partial receives `actor` and
-`authorization_context` locals:
+`authorization_context` locals, plus a `component_key` of `nil` when the
+component is unkeyed:
 
 ```erb
 <ul>
@@ -221,7 +254,14 @@ Declared observables are deeply frozen ordinary Ruby values inside a
 component. Arrays support loops, hashes support ordinary lookup, conditionals
 work normally, and ERB still escapes user strings. A reactive component cannot
 read `actor.state`, access an undeclared observable, or choose a dynamic
-partial path.
+partial path. A component name and key pair must be unique within its
+`solid_object` scope.
+
+Component keys and locals are signed into the refresh token and cannot be
+modified without invalidating it, but they are visible to the browser and are
+not secrets. Every initial render and refresh passes the signed locals and
+`component_key` to `authorize_query` as `arguments`. Authorization must still
+bind them to the authenticated request context.
 
 That template provides initial server rendering, stable opaque DOM targets,
 and live updates after committed actor turns. One `solid_object` block makes
@@ -254,20 +294,27 @@ for the same actor without sharing either projection.
 Reconnect compares the component's signed initial revision with the latest
 actor incarnation and state revision, then refreshes stale components. Cable
 coalesces several dependency changes from one actor turn into one component
-refresh and ignores older out-of-order invalidations. A newer invalidation
-replaces an in-flight frame, so its detached older response cannot overwrite
-newer state.
+refresh and ignores older out-of-order invalidations. Replace refreshes detach
+an older in-flight frame. Morph refreshes abort the older request and compare
+the returned revision with the current target before applying HTML.
 
 Reactive components add no HTML to durable rows, but each affected component
 causes an authorized HTTP render. One actor turn still inserts one broadcast
 row per changed observable; several dependencies from that turn coalesce at
 the subscriber. Keep components bounded, declare only necessary dependencies,
-and use scalar observables for inexpensive single-value replacement.
+keep signed locals small, and use scalar observables for inexpensive
+single-value replacement. Each keyed component counts toward the 50-component
+subscription limit and carries its own signed token.
 
 Reactive views require `turbo-rails` and a working Action Cable adapter in the
 host application. The Solid Objects engine must be mounted so its signed
 component endpoint is reachable. Reactive views are optional; the actor
-runtime itself does not depend on Turbo.
+runtime itself does not depend on Turbo. Morph components automatically include
+the engine's `solid_objects/component_refresh` JavaScript module; the host does
+not need a Stimulus controller or custom stream action. The default Rails
+Propshaft and Sprockets setups discover namespaced engine assets automatically.
+An application created with `--skip-asset-pipeline` should use replace refreshes
+unless it explicitly serves that module.
 
 ```ruby
 # config/routes.rb

data/app/assets/javascripts/solid_objects/component_refresh.js

@@ -0,0 +1,124 @@
+const activeRefreshes = new Map()
+
+class SolidObjectsRefreshElement extends HTMLElement {
+  connectedCallback() {
+    if (this.dataset.started === "true") return
+
+    this.dataset.started = "true"
+    this.refresh()
+  }
+
+  disconnectedCallback() {
+    this.refreshController?.abort()
+  }
+
+  async refresh() {
+    const targetName = this.dataset.target
+    const source = this.dataset.source
+    if (!targetName || !document.getElementById(targetName) || !source) {
+      return this.remove()
+    }
+
+    const previousRefresh = activeRefreshes.get(targetName)
+    previousRefresh?.abort()
+
+    const refresh = new AbortController()
+    this.refreshController = refresh
+    activeRefreshes.set(targetName, refresh)
+
+    try {
+      const sourceUrl = this.sourceUrl(source)
+      const response = await fetch(sourceUrl, {
+        credentials: "same-origin",
+        headers: {
+          Accept: "text/html",
+          "Turbo-Frame": targetName
+        },
+        redirect: "error",
+        signal: refresh.signal
+      })
+      if (!response.ok) {
+        this.dispatchRefreshError(`http_${response.status}`)
+        return
+      }
+
+      const responseDocument = new DOMParser().parseFromString(
+        await response.text(),
+        "text/html"
+      )
+      const replacement = responseDocument.getElementById(targetName)
+      if (!replacement || replacement.tagName !== "TURBO-FRAME") {
+        this.dispatchRefreshError("missing_frame")
+        return
+      }
+      const currentTarget = document.getElementById(targetName)
+      if (!currentTarget || !newerRevision(replacement, currentTarget)) return
+
+      renderMorph(targetName, replacement)
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        this.dispatchRefreshError("request_failed")
+      }
+    } finally {
+      if (activeRefreshes.get(targetName) === refresh) {
+        activeRefreshes.delete(targetName)
+      }
+      this.remove()
+    }
+  }
+
+  sourceUrl(source) {
+    const sourceUrl = new URL(source, window.location.href)
+    if (sourceUrl.origin === window.location.origin) return sourceUrl
+
+    throw new Error("cross_origin_source")
+  }
+
+  dispatchRefreshError(reason) {
+    this.dispatchEvent(
+      new CustomEvent("solid-objects:component-refresh-error", {
+        bubbles: true,
+        detail: { reason }
+      })
+    )
+  }
+}
+
+function newerRevision(candidate, current) {
+  const candidateRevision = revisionFor(candidate)
+  const currentRevision = revisionFor(current)
+  if (!candidateRevision || !currentRevision) return false
+
+  return candidateRevision[0] > currentRevision[0] ||
+    (candidateRevision[0] === currentRevision[0] &&
+      candidateRevision[1] > currentRevision[1])
+}
+
+function revisionFor(element) {
+  const revision = element.dataset.solidObjectsRevision
+  if (!revision) return
+
+  const values = revision.split(":").map(Number)
+  if (
+    values.length !== 2 ||
+    values.some((value) => !Number.isSafeInteger(value) || value < 0)
+  ) return
+
+  return values
+}
+
+function renderMorph(targetName, replacement) {
+  const stream = document.createElement("turbo-stream")
+  stream.setAttribute("action", "replace")
+  stream.setAttribute("method", "morph")
+  stream.setAttribute("target", targetName)
+
+  const template = document.createElement("template")
+  template.content.append(document.importNode(replacement, true))
+  stream.append(template)
+  document.documentElement.append(stream)
+}
+
+if (!customElements.get("solid-objects-refresh")) {
+  customElements.define("solid-objects-refresh", SolidObjectsRefreshElement)
+}

data/app/controllers/solid_objects/components_controller.rb

@@ -8,12 +8,25 @@ module SolidObjects
 
     # @rbs () -> void
     def show
+      SolidObjects.instrument(:"component.refreshed") { |payload| refresh(payload) }
+    end
+
+    private
+
+    # @rbs (Hash[Symbol, untyped]) -> void
+    def refresh(payload)
       registration = ComponentRegistration.from_token(
         params.require(:token)
       )
+      payload.merge!(registration_payload(registration))
       requested_revision = requested_revision_key
       snapshot = ActorSnapshot.new(registration.reference)
-      return head :conflict if newer_than_snapshot?(requested_revision, snapshot)
+      payload[:instance_id] = snapshot.instance_id
+      payload[:revision] = snapshot.revision
+      if newer_than_snapshot?(requested_revision, snapshot)
+        payload[:outcome] = "conflict"
+        return head :conflict
+      end
 
       authorization_context = SolidObjects
         .configuration
@@ -21,24 +34,37 @@ module SolidObjects
         .call(controller: self)
       rendered = ComponentRenderer.new(
         snapshot:,
-        component_name: registration.component_name,
-        dependencies: registration.dependencies,
+        registration:,
         view_context: component_view_context,
         authorization_context:
       ).call
       response.headers["Cache-Control"] = "private, no-store"
+      payload[:outcome] = "rendered"
       render html: component_frame(registration, snapshot, rendered)
     rescue Unauthorized
+      payload[:outcome] = "unauthorized"
       head :forbidden
     rescue UnknownComponent
+      payload[:outcome] = "unknown_component"
       head :not_found
     rescue ActionController::ParameterMissing,
       ArgumentError,
       InvalidComponentToken
+      payload[:outcome] = "invalid_token"
       head :bad_request
     end
 
-    private
+    # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
+    def registration_payload(registration)
+      {
+        actor_type: registration.reference.actor_type,
+        actor_id: registration.reference.actor_id,
+        component_name: registration.component_name,
+        component_key: registration.component_key,
+        dependencies: registration.dependencies,
+        refresh_method: registration.refresh_method
+      }
+    end
 
     # @rbs () -> Array[Integer]
     def requested_revision_key
@@ -67,12 +93,8 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, ActorSnapshot, untyped) -> String
     def component_frame(registration, snapshot, rendered)
-      target = DomIdentity.component(
-        registration.reference,
-        registration.component_name
-      )
       revision = "#{snapshot.instance_id}:#{snapshot.revision}"
-      %(<turbo-frame id="#{target}" data-solid-objects-revision="#{revision}">#{rendered}</turbo-frame>).html_safe
+      %(<turbo-frame id="#{registration.dom_id}" data-solid-objects-revision="#{revision}" data-solid-objects-refresh="#{registration.refresh_method}">#{rendered}</turbo-frame>).html_safe
     end
   end
 end

data/app/helpers/solid_objects/actor_helper.rb

@@ -23,10 +23,17 @@ module SolidObjects
         channel: "SolidObjects::ActorChannel",
         data: subscription_data
       )
+      refresh_client = if actor.morph_components?
+        javascript_include_tag(
+          "solid_objects/component_refresh",
+          type: "module",
+          data: { turbo_track: "reload" }
+        )
+      end
 
       content_tag(
         :div,
-        safe_join([ subscription, content ]),
+        safe_join([ refresh_client, subscription, content ].compact),
         id: DomIdentity.scope(reference)
       )
     end

data/docs/adr/0009-realtime-updates.md

@@ -11,11 +11,28 @@ Action Cable broadcasts are online-only. A transaction can roll back, a broadcas
 
 The executor evaluates declared observables before and after a successful message. Changed values create broadcast outbox records inside the message commit. A broadcast worker delivers Turbo Stream replacements after commit.
 
-One `solid_object` block creates one signed Action Cable subscription and contains stable targets for multiple observables and components. Subscription authorization runs after token verification and before streaming. Reconnect refresh reads current actor state; the broadcast stream is an optimization, not state.
+One `solid_object` block creates one signed Action Cable subscription and
+contains stable targets for multiple observables and components. Component
+names may repeat behind signed string or integer keys. Small JSON locals,
+dependencies, refresh strategy, and initial revision are signed into each
+component registration.
+
+Subscription authorization runs after token verification and before streaming.
+Every initial or request-time component render separately authorizes the
+component name and dependencies with its signed key and locals. Personalized
+HTML is never stored or broadcast.
+
+Replace refreshes use Turbo Frames. Optional morph refreshes use a gem-owned
+browser element to fetch the same authorized endpoint, abort superseded
+requests, reject stale revisions, and apply Turbo's scoped morph operation.
+Reconnect refresh reads current actor state; the broadcast stream is an
+optimization, not state.
 
 ## Consequences
 
 - Disconnected clients may miss individual broadcasts but can converge by refresh.
 - Broadcast delivery is at least once and replacements must be idempotent.
 - Actor IDs and signed stream names are identifiers, not authorization.
+- Component keys and locals are visible integrity-protected inputs, not
+  secrets or capabilities.
 - Realtime support is optional and loaded only when Action Cable and Turbo are present.

data/docs/architecture.md

@@ -473,13 +473,20 @@ emits:
 - Stable child target IDs for values and components
 - A signed actor token used by the channel subscription
 - Signed component registrations containing a conventional component name,
-  explicit observable dependencies, the initial actor incarnation/revision,
-  and a same-origin engine refresh path
+  optional string or integer key, JSON locals, explicit observable
+  dependencies, refresh strategy, the initial actor incarnation/revision, and
+  a same-origin engine refresh path
 
 ```erb
-<%= solid_object current_cart do |cart| %>
-  Cart items: <%= cart.items_count %>
-  <%= cart.component :summary, observes: %i[items checkout_status] %>
+<%= solid_object @room do |room| %>
+  Present: <%= room.presence %>
+  <% @players.each do |player| %>
+    <%= room.component :player,
+      key: player.id,
+      observes: :players,
+      locals: { player_id: player.id },
+      refresh: :morph %>
+  <% end %>
 <% end %>
 ```
 
@@ -487,9 +494,11 @@ The signed token proves integrity, not authorization. `ActorChannel#subscribed`
 
 Scalar observable calls remain direct escaped Turbo replacements. A reactive
 component resolves only `actors/<actor_class>/_<component>`, receives its
-declared observables as frozen Ruby values, and cannot read raw state or a
-dependency it did not declare. A static initial-only component can still use a
-server-selected explicit partial; a reactive component cannot.
+declared observables and signed locals as frozen Ruby values, and cannot read
+raw state or a dependency it did not declare. Repeated component names use a
+keyed digest in the DOM identity, subscription revision map, and duplicate
+check. A static initial-only component can still use a server-selected
+explicit partial; a reactive component cannot.
 
 Broadcast replacements happen after the actor transaction commits because only
 a committed broadcast outbox row can be delivered. Multiple scalar values and
@@ -502,24 +511,29 @@ dependencies do not send their values to the browser, and the stream never
 contains personalized component HTML. For each subscription, `ActorChannel`
 matches the changed observable to registered component dependencies. It
 coalesces multiple dependencies at the same message sequence and drops older
-revision pairs. A component invalidation replaces its stable target with a
-Turbo Frame whose source is the signed engine endpoint.
+revision pairs independently for every component name and key pair. A default
+component invalidation replaces its stable target with a Turbo Frame whose
+source is the signed engine endpoint. A morph invalidation appends a temporary
+gem-owned refresh element carrying the same signed URL.
 
 The browser then makes an ordinary cookie-bearing HTTP request. The engine
 controller derives a request-specific context through
 `component_authorization_context`, calls `authorize_query` for the component
-name and every declared dependency, renders the host partial from a new
-committed snapshot, and returns `private, no-store` HTML. Subscribers to the
-same actor can therefore receive different HTML without sharing it through
-Cable or the database.
+name and every declared dependency with the signed key and locals as
+authorization arguments, renders the host partial from a new committed
+snapshot, and returns `private, no-store` HTML. Subscribers to the same actor
+can therefore receive different HTML without sharing it through Cable or the
+database.
 
 Each channel subscription transmits current scalar replacements and compares
 each component's signed initial revision against the latest committed
 `(instance_id, state_revision)` pair, including after reconnect. Missing a
 broadcast therefore creates temporary staleness, not permanent divergence.
 The instance primary key distinguishes destroy-and-recreate incarnations.
-Replacing the full frame on each newer invalidation detaches an older in-flight
-frame, preventing its slower response from replacing the current generation.
+Replace refreshes detach an older in-flight frame. Morph refreshes abort a
+superseded fetch for the same target, re-read the current DOM target after the
+response arrives, compare monotonic revision pairs, and apply authorized HTML
+through Turbo's scoped morph operation only when it is newer.
 
 ## Authorization
 
@@ -540,8 +554,10 @@ No controller, channel, or administrative command treats an actor ID, message ID
 
 Initial component rendering, Cable subscription, and request-time component
 refresh deliberately use different authorization contexts. Signed component
-tokens constrain actor identity, component convention, dependencies, revision,
-and same-origin refresh path but never grant access.
+tokens constrain actor identity, component convention, optional key and
+locals, dependencies, refresh method, revision, and same-origin refresh path
+but never grant access. Keys and locals are browser-visible integrity-protected
+inputs, not encrypted capabilities.
 
 Actor IDs are bounded UTF-8 strings and never become constant names, SQL identifiers, file paths, or raw stream names.
 

data/docs/authorization.md

@@ -57,6 +57,30 @@ The stream token also signs the scalar observable targets rendered into that
 specific scope. Component-only dependencies send invalidation metadata but not
 their state value to the browser.
 
+Keyed components sign their `component_key` and declared JSON-compatible
+locals into the component token. Initial rendering and every refresh pass those
+values to `authorize_query` as `arguments`; unkeyed components without locals
+retain an empty arguments hash. This lets a policy authorize a projection such
+as one seat or player:
+
+```ruby
+configuration.authorize_query = lambda do |actor_type:, actor_id:, message_name:, arguments:, authorization_context:|
+  user = authorization_context
+  player_id = arguments["player_id"]
+
+  actor_type == "PlaymatRoom" &&
+    user.present? &&
+    user.can_view_room?(actor_id) &&
+    (player_id.nil? || user.can_view_player?(player_id))
+end
+```
+
+The values are signed but not encrypted. They are present in server-rendered
+HTML and the Cable subscription identifier, so they must not contain secrets
+or sensitive state. A valid signature proves that the server issued the
+registration; it does not prove the current user may still read it. Always
+reauthorize against the current request context.
+
 ## A tenant-aware policy
 
 Pass the authenticated user as the call context:

data/docs/correctness.md

@@ -137,10 +137,18 @@ its name and revision over Cable, not its serialized value.
 
 Cable compares `(instance_id, state_revision)` pairs, coalesces dependencies
 changed by the same turn, and ignores an older pair after a newer one. A new
-invalidation replaces the whole Turbo Frame generation. A response owned by
-the detached older frame cannot overwrite the current frame. Reconnect
-compares the component's signed initial pair with the current instance row and
-requests the latest committed snapshot when stale.
+invalidation advances each keyed component registration independently. Replace
+refreshes replace the whole Turbo Frame generation, so a response owned by the
+detached older frame cannot overwrite the current frame. Morph refreshes abort
+a superseded request for the same target and compare the response revision
+with the current DOM revision immediately before applying Turbo's scoped
+morph. Reconnect compares every component's signed initial pair with the
+current instance row and requests the latest committed snapshot when stale.
+
+Component keys, JSON locals, dependencies, and refresh strategy are covered by
+the signed registration. Keys and locals are visible to the browser and are
+passed back to `authorize_query` on every render; integrity never substitutes
+for request-specific authorization.
 
 ## Synchronous invocation
 
@@ -159,7 +167,21 @@ result. Adapter lock/query deadlines cover the durable enqueue, caller-process
 registration and heartbeat, activation coordination, and result observation.
 SQLite retries busy coordination operations only within the original call
 deadline and reports `waiting_on=database_contention` when the database cannot
-be inspected at timeout. If enqueue cannot commit, `SyncEnqueueTimeout` is
+be inspected at timeout. To keep those retries in Ruby, the SQLite adapter
+suspends the connection's busy wait for the duration of each deadline-bound
+transaction and restores it afterwards. Restoration reinstalls the Ruby busy
+handler Rails configures from the sqlite3 `timeout` setting, which
+`PRAGMA busy_timeout` neither reports nor preserves, so a synchronous call
+leaves the connection's lock waiting behaviour exactly as it found it for
+later writers inside and outside Solid Objects.
+
+The adapter suspends the busy wait only when it can identify how to restore
+it. When a future Active Record release stops exposing the configured
+timeout, the adapter leaves the connection untouched: synchronous deadlines
+lose their tight bound and wait as long as the configured busy wait allows,
+rather than stripping lock waiting from a pooled connection the rest of the
+application shares. A test asserts the timeout stays discoverable so the
+looser bound cannot be adopted silently. If enqueue cannot commit, `SyncEnqueueTimeout` is
 raised and no message reference exists. MySQL lock waits have one-second InnoDB
 granularity. Ruby handlers that already started are not preempted.
 

data/docs/operations.md

@@ -15,6 +15,14 @@ so the schema check compares the required shape instead of a fixed timestamp.
 Warnings such as an all-deny neutral policy do not fail the command because a
 context-aware production policy may correctly deny the probe.
 
+The round-trip probe runs on its own dedicated caller process rather than the
+shared application caller process, and removes that record together with its
+temporary actor when it finishes. Running the doctor inside a process that
+already serves synchronous calls therefore leaves the application caller
+process, its activations, and its claimed messages untouched, including when an
+application call overlaps the probe. A database busy enough to block cleanup
+reports a failed or warned check rather than raising out of the command.
+
 ## Runtime
 
 Start all configured roles:
@@ -147,10 +155,20 @@ transaction rejection, commit-action start/completion/failure, effect and
 broadcast enqueue/completion, reminder enqueue, actor destruction/expiration,
 retention pruning, process cleanup, and supervisor lifecycle.
 
+`solid_objects.component.refreshed` covers every authorized component refresh
+request. Its payload carries the actor identity, `component_name`,
+`component_key`, declared `dependencies`, `refresh_method`, the rendered
+`instance_id` and `revision`, and an `outcome` of `rendered`, `conflict`,
+`unauthorized`, `unknown_component`, or `invalid_token`. Use it to watch
+refresh rate per key, authorization denials, superseded requests, and render
+duration. A rejected token reports only the outcome, since no signed identity
+was recovered.
+
 Payloads contain stable runtime identifiers, actor identity, sequence,
 attempts, ownership generations, and safe exception summaries where relevant.
-Arguments, actor state, results, and outbox payloads are excluded. The bundled
-log subscriber turns the same notifications into structured logger hashes.
+Arguments, component locals, actor state, results, and outbox payloads are
+excluded. The bundled log subscriber turns the same notifications into
+structured logger hashes.
 
 ## Retention and backups