solid_objects 0.15.2 → 0.16.0

data/docs/realtime.md

@@ -140,46 +140,52 @@ explicitly serve the module. Turbo's normal morph rules still apply; use
 
 ## Cross-process wake-up
 
-Runtime roles poll for work and are woken early by an in-process signal. That
-signal cannot cross process boundaries, so a commit in a Puma process does not
-wake a broadcast executor in a worker process, and delivery waits out
+Runtime roles poll for work and are woken early by a signal. An in-process
+signal cannot cross process boundaries, so a commit in a Puma process would not
+wake a broadcast executor in a worker process, and delivery would wait out
 `polling_interval`, 100 ms by default.
 
-On PostgreSQL, install the notification adapter to remove that delay:
+Solid Objects selects the adapter for you. `wake_up_adapter` defaults to
+`:automatic`, which prefers a configured Redis URL, then PostgreSQL
+notifications, then polling:
 
 ```ruby
 # config/initializers/solid_objects.rb
-configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
+configuration.wake_up_adapter = :automatic     # the default
+configuration.wake_up_adapter = :in_process    # opt out
+configuration.wake_up_adapter = :postgresql    # force one
+configuration.wake_up_adapter = MyAdapter.new  # your own
 ```
 
-`WakeUpAdapters.for` returns notifications on PostgreSQL and the in-process
-default on SQLite and MySQL, so the same line is safe across adapters. Name
-`SolidObjects::WakeUpAdapters::Postgresql.new` directly to require it.
-
-MySQL has no notification primitive. MySQL applications either keep polling and
-tune `polling_interval`, or configure the Redis adapter:
-
-```ruby
-configuration.wake_up_adapter = SolidObjects::WakeUpAdapters::Redis.new(
-  url: ENV["REDIS_URL"]
-)
-```
-
-Measured latency for a cross-process wake-up drops from 103.8 ms to 5.7 ms at
-p50. The `redis` gem is not a dependency of this gem, so applications add it
-themselves. One background subscription per process fans out to every waiting
-role in memory, rather than one connection per thread, and `WakeUpAdapters.for`
-does not select it: Redis is infrastructure this gem otherwise does not require,
-so choosing it is explicit.
+`SolidObjects.wake_up.capability` reports what was installed, whether it crosses
+processes, its measured floor, and why. `bin/rails solid_objects:doctor` reports
+the same record.
 
+On PostgreSQL, selection proves the path before it chooses it. It listens on a
+probe channel, sends one `NOTIFY` from a second connection, and waits for it to
+arrive, because `LISTEN` does not survive a transaction pooler such as
+PgBouncer. A probe that does not deliver falls back to polling and warns once.
 Measured latency for a cross-process wake-up drops from 103.7 ms to 2.9 ms at
 p50. The adapter keeps `polling_interval` as the upper bound: a missed or failed
 notification costs latency, never correctness, and signalling never raises into
 the caller that committed. `LISTEN` needs its own connection, so the adapter
 opens one outside the pool and releases it on `stop`.
 
-Applications on SQLite or MySQL, or that do not configure the adapter, keep the
-existing polling behaviour.
+MySQL has no notification primitive, so MySQL applications either keep polling
+and tune `polling_interval`, or set `SOLID_OBJECTS_REDIS_URL`, which selects
+Redis on any database:
+
+```bash
+SOLID_OBJECTS_REDIS_URL=redis://localhost:6379/0
+```
+
+Measured latency for a cross-process wake-up drops from 103.8 ms to 5.7 ms at
+p50. The `redis` gem is not a dependency of this gem, so applications add it
+themselves, and selection polls and says so when the gem is missing. One
+background subscription per process fans out to every waiting role in memory,
+rather than one connection per thread. Name
+`SolidObjects::WakeUpAdapters::Redis.new(url:)` directly for a URL that does not
+come from the environment.
 
 ## Batched component refreshes
 

data/docs/roadmap.md

@@ -36,6 +36,14 @@
   listed here while broken in that worker: the scheduler reached a constant the
   caller path happened to load, so reminders never fired in production and
   every in-process test still passed
+- Reminder cancellation and reading. `schedule` returns a durable handle,
+  `unschedule` and `unschedule_all` cancel by name, key, or handle, and
+  `reminder` and `reminders` read the schedule. A cancel is an intent, so it
+  commits with the state change that decided it. A read applies the intents
+  staged so far, so it agrees with what the commit will leave behind. A cancel
+  cannot recall an occurrence the scheduler already turned into a message. It
+  does pre-empt one the scheduler claimed but has not yet enqueued, and the
+  scheduler treats that as ordinary work rather than a failure
 - Durable invalidation-only observable broadcasts by default, explicit
   `broadcast: :value` scalar Turbo replacement, keyed ERB components, signed
   component locals, and authorized replace or morph refresh. Default
@@ -50,7 +58,9 @@
   cannot reject the subscription or stop its siblings
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
-  migration cookbook
+  migration cookbook. The doctor names every column that a migration after the
+  first adds, so a half-applied migration fails the schema check rather than
+  reaching a worker. A test holds the list to that rule
 - Database server verification: each adapter reports its version against a
   tested minimum, MySQL confirms Solid Objects tables use InnoDB, and the
   doctor warns rather than refusing to run on an untested server
@@ -109,26 +119,37 @@
   batched and unbatched components, an inert replay of an applied revision,
   cancellation of the request left in flight by the drop, incarnation ordering
   after a destroy and recreate, and payload delivery exactly once per revision
+- Result lookup by request ID and by idempotency key, authorized with the hook
+  the original call ran and against the stored operation and arguments. An
+  actor remembers the idempotency keys of its own last `retained_idempotency_keys`
+  finished turns, written in the instance row the executor updates anyway, so a
+  lookup by key raises `MessagePruned` for a message that retention removed and
+  answers `nil` for a message that never existed. A lookup by request ID cannot
+  make that distinction, because the runtime generates a request ID and no
+  actor remembers one. Pruned lookups retain the original arguments for authorization
+  within the byte limit; older entries without arguments answer `nil`
 
 ## Partially implemented
 
 - Wake-up strategy: in-process signaling, durable polling, injection, and
   cross-process adapters for PostgreSQL and Redis are implemented and tested.
-  What is not done is making any of them automatic. In-process signaling cannot
-  cross process boundaries, so by default a commit in a web process does not
-  wake a broadcast executor in a worker process and that delivery waits up to
-  the current adaptive polling interval, up to the one-second
-  `idle_polling_interval` default. The runtime warns once when it observes this
-  topology without an adapter. An adapter removes that floor, measured before
-  adaptive polling at 103.7 ms to 2.9 ms at p50 on PostgreSQL and 103.8 ms to
-  5.7 ms on Redis, but each stays opt-in for a reason: the PostgreSQL adapter
-  opens a connection per waiting thread outside the pool and `LISTEN` does not
-  survive a transaction-pooling proxy such as PgBouncer, and Redis is not a
-  dependency of this gem.
-  `WakeUpAdapters.for` selects notifications on PostgreSQL and the in-process
-  default elsewhere; it never selects Redis. An application that configures
-  nothing keeps polling, and MySQL applications keep polling unless they
-  configure Redis explicitly.
+  Selection is automatic. `config.wake_up_adapter` defaults to `:automatic` and
+  prefers a configured Redis URL, then PostgreSQL notifications, then polling,
+  so an application that configures nothing no longer polls on PostgreSQL. An
+  adapter removes the one-second floor, measured before adaptive polling at
+  103.7 ms to 2.9 ms at p50 on PostgreSQL and 103.8 ms to 5.7 ms on Redis. Each
+  carries a cost that selection now states rather than hides: the PostgreSQL
+  adapter opens a connection per waiting thread outside the pool and adds one
+  `NOTIFY` per enqueue, and Redis is not a dependency of this gem.
+  `LISTEN` does not survive a transaction-pooling proxy such as PgBouncer, so
+  selection listens, sends one `NOTIFY` from a second connection, and waits for
+  it to arrive. A probe that does not deliver falls back to polling and warns
+  once, as does a requested adapter the environment cannot provide, so a
+  downgrade is recorded rather than hidden.
+  `SolidObjects.wake_up.capability` reports the adapter, whether it crosses
+  processes, its floor, and why, and the doctor shows the same record.
+  MySQL still polls. It has no notification channel, and no MySQL notifier has
+  been measured against polling on the same hardware, so none is shipped.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
   reconnect convergence, batched refreshes, and personalized state payloads are
@@ -150,7 +171,11 @@
   loads them in every process, and a rejected subscription reports which
   condition caused it instead of closing the socket silently.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
-  distributed per-actor rate limits and global admission control do not. The
+  distributed per-actor rate limits, global admission control, and
+  cache-capacity eviction are not planned here. They are hot, request-path, and
+  loss-tolerant, so one durable ordered message per check is the wrong shape,
+  which [fit](fit.md) already says. Solid Objects Pro answers them with grouped
+  and ephemeral operations. The
   state cap is a limit rather than an operating point. `max_state_bytes`
   defaults to 5 MB, and committed throughput measured on SQLite falls about 53
   times between an empty state and 1 MB of state, which `docs/benchmarks.md`
@@ -168,15 +193,18 @@
   or turn off. Every route declares its
   own administration policy and a route declared without one raises at load
   time, so the deny-by-default posture is enforced by construction rather than
-  by remembering to add a check. It changes only two things: an idempotent dead
-  letter retry and instance pause/resume. What does not exist is audit records
-  of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
-  because `DeadLetterManager` exposes no bulk operation. Pause is an operator
-  brake and not a stop, since a pass already in flight finishes its turn and a
-  synchronous caller waiting on a paused instance times out. Retry also only
-  exists for message dead letters: a dead effect or broadcast has no retry
-  API, which matters for transmit effects because a dead one is a lost
-  replay until an operator returns its row to pending. The page cost was
+  by remembering to add a check. It changes only three things: an idempotent dead
+  letter retry, a redrive, and instance pause/resume. Retry covers all three
+  kinds. `SolidObjects.dead_letters` keeps its message meaning and answers
+  `effects` and `broadcasts`, so a dead effect or broadcast returns to pending
+  through an API rather than an operator's `UPDATE`, and a dead transmit effect
+  is no longer a lost replay. `redrive` moves a whole scope as a durable task
+  that is idempotent over its filters, cancellable, and advanced in bounded
+  batches by the supervisor. Every retry and task transition writes one row to
+  `solid_objects_administration_events`, so who pressed what is recorded. Pause
+  is an operator brake and not a stop, since a pass already in flight finishes
+  its turn and a synchronous caller waiting on a paused instance times out. The
+  dashboard does not yet surface the scopes or redrive; the API does. The page cost was
   reasoned about rather than measured: the summary bar issues a fixed set of
   indexed aggregate queries per page, which is why `HEAD /` exists for uptime
   monitors, but no dashboard latency has been benchmarked against a large
@@ -184,13 +212,13 @@
 
 ## Next milestones
 
-1. Add result lookup by request ID and broader deadlock retry classification.
-2. Add Turbo append intents.
-3. Add distributed rate limits, global admission hooks, and cache-capacity
-   eviction.
-4. Expand security scanning beyond the Brakeman scan, such as dependency
+1. Broaden deadlock retry classification.
+2. Add Turbo append intents. The renderer already emits the `append` action for
+   batch refreshes and payload delivery, so what remains is letting an
+   application direct one.
+3. Expand security scanning beyond the Brakeman scan, such as dependency
    auditing and secret scanning.
-5. Benchmark all workloads under documented hardware/database settings and
+4. Benchmark all workloads under documented hardware/database settings and
    publish adapter-specific adoption measurements. Throughput, synchronous
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.

data/examples/at_least_once/boot.rb

@@ -37,13 +37,7 @@ module AtLeastOnceBoot
 
   # @rbs () -> void
   def self.migrate
-    require File.join(ROOT, "db/migrate/20260805000000_create_solid_objects_tables")
-    require File.join(ROOT, "db/migrate/20260806000000_add_state_revision_to_solid_objects_instances")
-    require File.join(ROOT, "db/migrate/20260813000000_rename_message_dispatch_columns")
-    require File.join(ROOT, "db/migrate/20260915000000_add_solid_objects_effect_recoveries")
-    CreateSolidObjectsTables.new.migrate(:up)
-    AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
-    RenameMessageDispatchColumns.new.migrate(:up)
-    AddSolidObjectsEffectRecoveries.new.migrate(:up)
+    require "solid_objects/schema_bootstrap"
+    SolidObjects::SchemaBootstrap.install
   end
 end

data/lib/solid_objects/activation.rb

@@ -3,6 +3,8 @@
 module SolidObjects
   class Activation
     # @rbs @lease: Lease
+    # @rbs @actor_id: String
+    # @rbs @instance_id: Integer
     # @rbs @actor_class: Class
     # @rbs @actor: Actor
     # @rbs @last_used_at: Float
@@ -17,6 +19,8 @@ module SolidObjects
         Instance.find(lease.instance_id)
       end
       @actor_class = SolidObjects.registry.fetch(instance.actor_type)
+      @actor_id = instance.actor_id
+      @instance_id = instance.id
       @actor = build_actor(instance)
       @last_used_at = monotonic_now
       @pass_exhausted = false
@@ -86,10 +90,7 @@ module SolidObjects
 
     # @rbs (Hash[String, untyped]) -> void
     def restore_state(state_data)
-      @actor = actor_class.new(
-        actor_id: actor.actor_id,
-        state: State.new(actor_class.definition.state_definition, state_data)
-      )
+      @actor = new_actor(state_data)
     end
 
     # @rbs () -> void
@@ -156,9 +157,15 @@ module SolidObjects
       ) do
         actor_class.definition.migrate_state(instance.state_version, instance.state)
       end
+      new_actor(state_data)
+    end
+
+    # @rbs (Hash[String, untyped]) -> Actor
+    def new_actor(state_data)
       actor_class.new(
-        actor_id: instance.actor_id,
-        state: State.new(actor_class.definition.state_definition, state_data)
+        actor_id: @actor_id,
+        state: State.new(actor_class.definition.state_definition, state_data),
+        instance_id: @instance_id
       )
     end
 

data/lib/solid_objects/actor.rb

@@ -10,7 +10,13 @@ module SolidObjects
     REMINDER_NAME_LIMIT = 191
     REMINDER_KEY_SEPARATOR = ":"
 
+    REMINDER_HANDLE_KEY = "reminder_name"
+
     ReminderIntent = Data.define(:name, :operation, :at, :arguments, :interval_seconds, :missed_policy)
+    UnscheduleIntent = Data.define(:name)
+    UnscheduleAllIntent = Data.define(:operation)
+    ReminderStatus = Data.define(:name, :operation, :key, :next_run_at, :interval_seconds,
+      :missed_policy, :occurrence, :status, :handle)
     OutboundMessageIntent = Data.define(:actor_type, :actor_id, :operation, :arguments, :available_at, :idempotency_key)
 
     class << self
@@ -152,10 +158,11 @@ module SolidObjects
 
     attr_reader :actor_id, :state
 
-    # @rbs (actor_id: String, state: State) -> void
-    def initialize(actor_id:, state:)
+    # @rbs (actor_id: String, state: State, ?instance_id: Integer?) -> void
+    def initialize(actor_id:, state:, instance_id: nil)
       @actor_id = actor_id
       @state = state
+      @instance_id = instance_id
       @effect_intents = []
       @effect_recovery_intents = []
       @commit_action_intents = []
@@ -255,20 +262,139 @@ module SolidObjects
         actor_type: self.class.actor_type,
         handlers: self.class.definition.messages
       ) do |operation, arguments|
-        ReminderIntent.new(
-          name: reminder_name(operation:, key: reminder_key),
+        name = reminder_name(operation:, key: reminder_key)
+        reminder_intents << ReminderIntent.new(
+          name:,
           operation: operation.to_s,
           at:,
           arguments: Serialization.dump(arguments),
           interval_seconds:,
           missed_policy:
-        ).tap do |intent|
-          reminder_intents << intent
-        end
-        nil
+        )
+        { REMINDER_HANDLE_KEY => name }
       end
     end
 
+    # @rbs (Symbol | String | reminder_handle, ?key: (String | Symbol | Integer)?) -> nil
+    def unschedule(operation_or_handle, key: nil)
+      return unschedule_name(handle_name(operation_or_handle, key:)) if operation_or_handle.is_a?(Hash)
+
+      validated_reminder_operation(operation_or_handle)
+      unschedule_name(reminder_name(operation: operation_or_handle, key: validated_reminder_key(key)))
+    end
+
+    # @rbs (Symbol | String) -> nil
+    def unschedule_all(operation)
+      reminder_intents << UnscheduleAllIntent.new(operation: validated_reminder_operation(operation))
+      nil
+    end
+
+    # @rbs (Symbol | String | reminder_handle, ?key: (String | Symbol | Integer)?) -> ReminderStatus?
+    def reminder(operation_or_handle, key: nil)
+      return reminder_view[handle_name(operation_or_handle, key:)] if operation_or_handle.is_a?(Hash)
+
+      validated_reminder_operation(operation_or_handle)
+      reminder_view[reminder_name(operation: operation_or_handle, key: validated_reminder_key(key))]
+    end
+
+    # @rbs (Symbol | String) -> Array[ReminderStatus]
+    def reminders(operation)
+      wanted = validated_reminder_operation(operation)
+      reminder_view.each_value.select { |status| status.operation == wanted }
+    end
+
+    attr_reader :instance_id
+
+    # @rbs (Symbol | String) -> String
+    def validated_reminder_operation(operation)
+      name = operation.to_s
+      return name if self.class.definition.messages.key?(name.to_sym)
+
+      raise UnknownMessage, "unknown message #{name.inspect} for #{self.class.actor_type}"
+    end
+
+    # @rbs (String) -> nil
+    def unschedule_name(name)
+      reminder_intents << UnscheduleIntent.new(name:)
+      nil
+    end
+
+    # @rbs (reminder_handle, key: untyped) -> String
+    def handle_name(handle, key:)
+      raise ArgumentError, "a reminder handle already names its key" unless key.nil?
+
+      name = handle[REMINDER_HANDLE_KEY]
+      unless name.is_a?(String) && !name.empty?
+        raise InvalidPayload, "expected a reminder handle returned by schedule"
+      end
+
+      name
+    end
+
+    # The view is the committed schedule with this turn's staged intents applied
+    # in order, so a read agrees with what the commit will leave behind.
+    # @rbs () -> Hash[String, ReminderStatus]
+    def reminder_view
+      reminder_intents.each_with_object(committed_reminders) do |intent, view|
+        apply_reminder_intent(view, intent)
+      end
+    end
+
+    # @rbs () -> Hash[String, ReminderStatus]
+    def committed_reminders
+      return {} unless instance_id
+
+      Reminder.where(instance_id:).where.not(status: "completed").each_with_object({}) do |row, view|
+        view[row.name] = reminder_status(
+          name: row.name,
+          operation: row.operation,
+          next_run_at: row.next_run_at,
+          interval_seconds: row.interval_seconds,
+          missed_policy: row.missed_policy,
+          occurrence: row.occurrence,
+          status: row.status
+        )
+      end
+    end
+
+    # @rbs (Hash[String, ReminderStatus], untyped) -> void
+    def apply_reminder_intent(view, intent)
+      return view.delete_if { |_name, status| status.operation == intent.operation } if intent.is_a?(UnscheduleAllIntent)
+      return view.delete(intent.name) if intent.is_a?(UnscheduleIntent)
+
+      view[intent.name] = reminder_status(
+        name: intent.name,
+        operation: intent.operation,
+        next_run_at: intent.at,
+        interval_seconds: intent.interval_seconds,
+        missed_policy: intent.missed_policy,
+        occurrence: view[intent.name]&.occurrence || 0,
+        status: "scheduled"
+      )
+    end
+
+    # @rbs (name: String, operation: String, next_run_at: Time?, interval_seconds: untyped, missed_policy: String, occurrence: Integer, status: String) -> ReminderStatus
+    def reminder_status(name:, operation:, next_run_at:, interval_seconds:, missed_policy:, occurrence:, status:)
+      ReminderStatus.new(
+        name:,
+        operation:,
+        key: reminder_key_of(name:, operation:),
+        next_run_at:,
+        interval_seconds: interval_seconds&.to_f,
+        missed_policy:,
+        occurrence:,
+        status:,
+        handle: { REMINDER_HANDLE_KEY => name }
+      )
+    end
+
+    # @rbs (name: String, operation: String) -> String?
+    def reminder_key_of(name:, operation:)
+      return nil if name == operation
+
+      name.delete_prefix("#{operation}#{REMINDER_KEY_SEPARATOR}")
+    end
+
     # @rbs ((String | Symbol | Integer)?) -> String?
     def validated_reminder_key(key)
       return nil if key.nil?

data/lib/solid_objects/actor_snapshot.rb

@@ -16,10 +16,12 @@ module SolidObjects
     def initialize(reference)
       @reference = reference
       @actor_class = SolidObjects.registry.fetch(reference.actor_type)
-      @instance = Instance.find_by(
-        actor_type: reference.actor_type,
-        actor_id: reference.actor_id
-      )
+      @instance = Instance.uncached do
+        Instance.find_by(
+          actor_type: reference.actor_type,
+          actor_id: reference.actor_id
+        )
+      end
       @instance_id = @instance&.id || 0
       @revision = @instance&.state_revision || 0
       @actor = build_actor
@@ -60,7 +62,8 @@ module SolidObjects
       end
       actor_class.new(
         actor_id: reference.actor_id,
-        state: State.new(actor_class.definition.state_definition, state_data)
+        state: State.new(actor_class.definition.state_definition, state_data),
+        instance_id: @instance&.id
       )
     end
   end

data/lib/solid_objects/administration_audit.rb

@@ -0,0 +1,30 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module AdministrationAudit
+    module_function
+
+    # @rbs (action: String, kind: String, ?subject_id: untyped, ?filters: Hash[Symbol | String, untyped]?, ?actor: String?) -> void
+    def record(action:, kind:, subject_id: nil, filters: nil, actor: nil)
+      AdministrationEvent.create!(
+        action:,
+        kind:,
+        subject_id: subject_id&.to_s,
+        filters:,
+        actor:,
+        occurred_at: SolidObjects.database_adapter.database_now
+      )
+      nil
+    end
+
+    # @rbs (untyped) -> String?
+    def identity(authorization_context)
+      return nil if authorization_context.nil?
+
+      SolidObjects.configuration.administration_identity
+        .call(authorization_context)
+        &.to_s
+        &.byteslice(0, 255)
+    end
+  end
+end

data/lib/solid_objects/client.rb

@@ -94,6 +94,45 @@ module SolidObjects
       raise SyncDiagnostics.new.database_contention_for(message_reference, timeout:)
     end
 
+    # @rbs (?reference: Reference?, ?request_id: String?, ?idempotency_key: String?, ?authorization_context: untyped) -> MessageReference?
+    def find_by(reference: nil, request_id: nil, idempotency_key: nil, authorization_context: nil)
+      unless [ request_id, idempotency_key ].compact.one?
+        raise ArgumentError, "find_by expects exactly one of request_id: or idempotency_key:"
+      end
+      if idempotency_key && reference.nil?
+        raise ArgumentError, "find_by with idempotency_key: requires reference:"
+      end
+
+      if request_id
+        return readable_message(
+          Message.uncached { Message.find_by(request_id:) },
+          authorization_context:
+        )
+      end
+
+      instance = Instance.find_by(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      return nil unless instance
+
+      message = Message.uncached { Message.find_by(instance_id: instance.id, idempotency_key:) }
+      return readable_message(message, authorization_context:) if message
+
+      remembered = Array(instance.completed_idempotency_keys)
+        .find { |entry| entry["key"] == idempotency_key }
+      return nil unless remembered && remembered["arguments"].is_a?(Hash)
+      return nil unless authorized_to_invoke?(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        operation: remembered["operation"],
+        arguments: remembered["arguments"],
+        authorization_context:
+      )
+
+      raise MessagePruned, idempotency_key
+    end
+
     # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
     def snapshot(reference, authorization_context: nil)
       SolidObjects.registry.fetch(reference.actor_type)
@@ -164,6 +203,48 @@ module SolidObjects
       )
     end
 
+    # @rbs (Message?, authorization_context: untyped) -> MessageReference?
+    def readable_message(message, authorization_context:)
+      return nil unless message
+      return nil unless authorized_to_read?(message, authorization_context:)
+
+      MessageReference.from_message(message)
+    end
+
+    # @rbs (Message, authorization_context: untyped) -> bool
+    def authorized_to_read?(message, authorization_context:)
+      authorized_to_invoke?(
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        operation: message.operation,
+        arguments: message.arguments,
+        authorization_context:
+      )
+    end
+
+    # @rbs (actor_type: String, actor_id: String, operation: String, arguments: Hash[String, untyped], authorization_context: untyped) -> bool
+    def authorized_to_invoke?(actor_type:, actor_id:, operation:, arguments:, authorization_context:)
+      actor_class = SolidObjects.registry.fetch(actor_type)
+      operation_symbol = operation.to_sym
+      query = actor_class.definition.queries.key?(operation_symbol)
+      return false unless query || actor_class.definition.messages.key?(operation_symbol)
+
+      hook = if query
+        SolidObjects.configuration.authorize_query
+      else
+        SolidObjects.configuration.authorize_message
+      end
+      hook.call(
+        actor_type:,
+        actor_id:,
+        operation: operation.to_s,
+        arguments:,
+        authorization_context:
+      )
+    rescue UnknownActorType
+      false
+    end
+
     # @rbs (MessageReference, Message) -> void
     def validate_message_reference!(message_reference, message)
       valid = message_reference.request_id == message.request_id &&