fix: Type the portable telemetry contracts

Observer blocks, diagnostics, telemetry helpers, and message results
used untyped, so Steep accepted a consumer that read the wrong field.

sig/public/telemetry.rbs now publishes portable_event, metric_sample,
event_observer, diagnostic_summary, and actor_diagnostics. A json_value
type covers message results and actor state. A strict packaged type
test checks a consumer and five invalid versions of it. With the old
untyped observer block, the invalid observer consumer type-checked.

authorization_context stays untyped, as on main, because it holds the
application's own subject.

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Publish RBS types for portable events, metric samples, actor diagnostics, and
+  event observers in `sig/public/telemetry.rbs`, and a `json_value` type for
+  message results and actor state. Observer blocks, diagnostics, and results now
+  type-check against these contracts instead of `untyped`.
 - `solid_objects.activation.started` now fires before the actor's `activate`
   hook. Before, it fired after a successful hook. The new
   `solid_objects.activation.completed` event takes that meaning, and

app/models/solid_objects/message.rb

@@ -47,7 +47,7 @@ def dead?
       dead_letter.present?
     end
 
-    # @rbs () -> untyped
+    # @rbs () -> json_value
     def result!
       if rejected?
         raise Rejected.new(

docs/observability.md

@@ -23,6 +23,9 @@ Every event has `schemaVersion`, `name` (prefixed with `solid_objects.`),
 `occurredAt` (UTC ISO 8601), `adapter`, `actorType`, `actorId`, `incarnation`,
 `revision`, `messageId`, `attempt`, `attributes`, and `metrics`.
 Unavailable identifiers are null; `attempt` is zero outside a message attempt.
+Ruby publishes the RBS types `SolidObjects::portable_event`,
+`SolidObjects::actor_diagnostics`, and `SolidObjects::event_observer`. JavaScript
+exports `InstrumentationEvent`, `ActorDiagnostics`, and `EventObserver`.
 An incarnation identifies a persisted actor instance, independently of its lease
 generation. Revisions and IDs are strings. Process-wide events have null actor
 identity. A message ID or revision correlates actor work where applicable.

lib/solid_objects/actor.rb

@@ -545,7 +545,7 @@ def intent_count
         reminder_intents.length + outbound_message_intents.length
     end
 
-    # @rbs (String) { () -> untyped } -> untyped
+    # @rbs [Result] (String) { () -> Result } -> Result
     def read_projection(operation)
       state_before = state.to_h
       intents_before = intent_snapshot
@@ -565,7 +565,7 @@ def read_projection(operation)
       :reminder_intents,
       :outbound_message_intents
 
-    # @rbs () -> Array[Array[Hash[Symbol, untyped]]]
+    # @rbs () -> Array[Array[Hash[Symbol, Object]]]
     def intent_snapshot
       [ effect_intents, effect_recovery_intents, commit_action_intents, reminder_intents, outbound_message_intents ].map do |intents|
         intents.map { |intent| intent.to_h.deep_dup }

lib/solid_objects/actor_snapshot.rb

@@ -7,7 +7,7 @@ class ActorSnapshot
     # @rbs @actor: Actor
     # @rbs @instance_id: Integer
     # @rbs @revision: Integer
-    # @rbs @state_data: Hash[String, untyped]
+    # @rbs @state_data: Hash[String, json_value]
     # @rbs @observable_values: Hash[String, untyped]?
     # @rbs @observable_value_cache: Hash[String, untyped]
 
@@ -58,7 +58,7 @@ def build_actor
 
     attr_reader :instance
 
-    # @rbs () -> Hash[String, untyped]
+    # @rbs () -> Hash[String, json_value]
     def migrated_state
       state_version = instance&.state_version || actor_class.state_version
       ApplicationWriteGuard.call(

lib/solid_objects/configuration.rb

@@ -40,7 +40,7 @@ class Configuration
     # @rbs @broadcast_worker_count: Integer
     # @rbs @reminder_scheduler_count: Integer
     # @rbs @connects_to: Hash[Symbol, untyped]?
-    # @rbs @instrumentation: Proc?
+    # @rbs @instrumentation: event_observer?
     # @rbs @logger: untyped
     # @rbs @stream_signing_secret: String?
     # @rbs @broadcast_adapter: Proc?
@@ -96,7 +96,6 @@ class Configuration
       :reminder_scheduler_count,
       :connects_to,
       :logger,
-      :instrumentation,
       :stream_signing_secret,
       :broadcast_adapter,
       :wake_up_adapter,
@@ -112,6 +111,8 @@ class Configuration
       :administration_identity,
       :transmission_actor_type_resolver
 
+    attr_accessor :instrumentation #: event_observer?
+
     # @rbs @additional_components: Array[untyped]
     attr_reader :additional_components
 

lib/solid_objects/diagnostics.rb

@@ -8,7 +8,7 @@ def initialize(reference)
       @reference = reference
     end
 
-    # @rbs (?limit: Integer, ?authorization_context: untyped) -> Hash[String, untyped]
+    # @rbs (?limit: Integer, ?authorization_context: untyped) -> actor_diagnostics
     def summary(limit: 100, authorization_context: nil)
       authorize!(:inspect, authorization_context:)
       raise ArgumentError, "diagnostic limit must be an integer between 1 and 100" unless limit.is_a?(Integer) && limit.between?(1, 100)
@@ -42,7 +42,7 @@ def summary(limit: 100, authorization_context: nil)
       Serialization.readonly_copy(result)
     end
 
-    # @rbs (?authorization_context: untyped) { (Hash[String, untyped]) -> untyped } -> Proc
+    # @rbs (?authorization_context: untyped) { (portable_event) -> void } -> Proc
     def observe(authorization_context: nil, &block)
       raise ArgumentError, "an actor observer requires a block" unless block
 
@@ -57,7 +57,7 @@ def observe(authorization_context: nil, &block)
 
     private
 
-    attr_reader :reference
+    attr_reader :reference #: Reference
 
     # @rbs (Symbol, ?authorization_context: untyped) -> void
     def authorize!(action, authorization_context: nil)
@@ -70,7 +70,7 @@ def authorize!(action, authorization_context: nil)
       raise Unauthorized, "actor diagnostics are not authorized" unless allowed
     end
 
-    # @rbs (Array[Time?], now: Time, limit: Integer) -> Hash[String, untyped]
+    # @rbs (Array[Time?], now: Time, limit: Integer) -> diagnostic_summary
     def summarize(timestamps, now:, limit:)
       oldest = timestamps.compact.min
       {

lib/solid_objects/executor.rb

@@ -69,7 +69,7 @@ def invoke_actor(message_context)
       end
     end
 
-    # @rbs (Hash[String, untyped], Hash[String, untyped]) -> void
+    # @rbs (Hash[String, json_value], Hash[String, json_value]) -> void
     def ensure_query_is_read_only!(state_before, state_after)
       return unless actor.class.definition.queries.key?(message.operation.to_sym)
 

lib/solid_objects/message_reference.rb

@@ -38,7 +38,7 @@ def status(authorization_context: nil)
       status_of(SolidObjects.client.read_message(self, authorization_context:))
     end
 
-    # @rbs (?authorization_context: untyped) -> untyped
+    # @rbs (?authorization_context: untyped) -> json_value
     def result(authorization_context: nil)
       SolidObjects.client.read_message(self, authorization_context:).result!
     end

lib/solid_objects/payload_broadcast.rb

@@ -71,7 +71,7 @@ def evaluated_payload(handler)
     # Distinguishes a block that relied on the old class-level receiver from an
     # ordinary typo, so the one behaviour change reports itself instead of
     # surfacing as an unexplained NameError.
-    # @rbs (NameError[untyped], Actor?) -> bool
+    # @rbs (NameError[BasicObject], Actor?) -> bool
     def class_level_receiver?(error, actor)
       error.receiver.equal?(actor) &&
         snapshot.actor_class.respond_to?(error.name)