ask-session-protocol 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22436fe459ec2c7e91ed8d5c12db05a72d01daaa83794536882d094b084b9b08
-  data.tar.gz: d512c1dea2ebdfbce2ba971d00d4430431b020ee79911fc26585d3ff2aefe0e9
+  metadata.gz: a04df0359177ab5a906a801cf56ea27438cf21eded5616221d01def2fffa68e1
+  data.tar.gz: 3d7b35424187f6662fecc811ea31cd6bcdbc58b8635646a60bbeaab2de77fbe1
 SHA512:
-  metadata.gz: a4f4a7094797aa9acb3293ef0ab96b69dcdc238b93ed378f32090327605931780cfb3a7c96bdca45d4466fe6b2ba3d90214be360eb03204aa4480b3b93b85eca
-  data.tar.gz: 60bfed82e8fd6a6c852e04afa5c0682c0bb2a4a7fd5e790a1d5e51bb204f6f9343e2d9f9de47f6717e4ede694e6410b559c1ebc0e640e9238393aecd3c33aa7a
+  metadata.gz: 30ea7ada3a75105590418634f716a459e88e2b6fdf937bf41e87d4885aa23734211cec9b25d83a6b953fdffc8acbb71566c5316355ee4ed5a38e373ee2bb8811
+  data.tar.gz: aa66d8826cb8c0017f0433feeb6c8ece2826872b6815a41087813c67ac4223cc29540c4ba03de5bbfb1a891707ece4c6ecaac8548e252d4e2c55f3d68c45f225

data/CHANGELOG.md

@@ -5,6 +5,31 @@ the keep-a-changelog format.
 
 ## [Unreleased]
 
+### Changed
+
+- **`turn.failed` payload** — `turnId` is now optional: the host only
+  knows a turn id once `turn.started` has fired, so a run that dies
+  before the turn starts still validates against the registry (matching
+  the host's emitter).
+
+### Fixed
+
+- **Payload key handling** — Symbol payload keys are normalized to the
+  wire's String keys at the boundary (events and interactions), so
+  in-process emitters no longer fail required-field checks or serialize
+  ambiguous duplicate keys. Symbol/String collisions and non-String,
+  non-Symbol keys raise `ArgumentError`.
+- **`from_h` input checks** — `Events.from_h` and `Interactions.from_h`
+  reject non-Hash input with `ArgumentError` before normalizing keys
+  (previously `NoMethodError`).
+
+### Added
+
+- **`Events.filter_snapshot`** — consumes a replayed snapshot
+  (`session/subscribe`'s `snapshot`, `session/events`' `events`):
+  canonical entries rebuild as Events, host-internal or unknown entries
+  are filtered out.
+
 ## [0.2.0] - 2026-08-12
 
 ### Added

data/README.md

@@ -112,6 +112,12 @@ Ask::SessionProtocol::Methods.validate_params!("session/send", { "sessionId" =>
 Unknown payload fields are allowed (forward compatibility); missing required
 fields, wrong types, and out-of-enum values raise `ArgumentError`.
 
+Payloads are string-keyed on the wire. Ruby callers may pass Symbol keys —
+they are normalized to Strings at the boundary, and a Symbol/String
+collision on the same name raises. `Events.filter_snapshot` consumes a
+replayed snapshot (`session/subscribe`, `session/events`): canonical
+entries become Events, host-internal or unknown entries are filtered out.
+
 ## JSON Schema
 
 `docs/ask-session-protocol.schema.json` (draft 2020-12) is generated from the

data/docs/ask-session-protocol.schema.json

@@ -164,7 +164,7 @@
             "type": "object",
             "properties": {
               "turnId": {
-                "description": "The turn identifier.",
+                "description": "The turn identifier, when the failure is attributed to a started turn.",
                 "type": "string"
               },
               "error": {
@@ -173,7 +173,6 @@
               }
             },
             "required": [
-              "turnId",
               "error"
             ]
           }

data/lib/ask/session_protocol/events.rb

@@ -67,7 +67,7 @@ module Ask
           description: "A turn failed; the session remains usable.",
           interaction: false,
           payload: {
-            "turnId" => { type: :string, required: true, description: "The turn identifier." },
+            "turnId" => { type: :string, required: false, description: "The turn identifier, when the failure is attributed to a started turn." },
             "error" => { type: :string, required: true, description: "Human-readable failure reason." }
           }
         },
@@ -232,6 +232,7 @@ module Ask
       # @param payload [Hash] event body; validated against the registry
       # @return [Event]
       def self.event(type:, seq:, payload: {})
+        payload = normalize_payload_keys(payload, "event #{type} payload")
         validate_payload!(type, payload)
         Event.new(type: type, seq: seq, payload: payload)
       end
@@ -241,8 +242,9 @@ module Ask
       # @param hash [Hash] { "type" =>, "seq" =>, "payload" => }
       # @return [Event]
       def self.from_h(hash)
-        hash = hash.transform_keys(&:to_s)
         raise ArgumentError, "event must be a Hash" unless hash.is_a?(Hash)
+
+        hash = hash.transform_keys(&:to_s)
         raise ArgumentError, "event missing type" if hash["type"].nil?
         raise ArgumentError, "event missing seq" if hash["seq"].nil?
 
@@ -250,6 +252,32 @@ module Ask
         event(type: hash["type"], seq: hash["seq"], payload: payload)
       end
 
+      # Rebuild the events of a replayed snapshot (the `snapshot` result of
+      # session/subscribe, the `events` result of session/events).
+      #
+      # Snapshots carry canonical events only: the host filters its
+      # internal detail out of the log before replaying. Entries that are
+      # not canonical — host-internal rows from an older host, foreign
+      # records, non-Hash junk — are dropped rather than raised, matching
+      # the client rule that unknown types are tolerated within a major
+      # protocol version. Entries whose type IS canonical must be
+      # well-formed; a malformed canonical entry raises.
+      #
+      # @param entries [Array<Event, Hash>] the raw snapshot
+      # @return [Array<Event>] canonical events, in order
+      def self.filter_snapshot(entries)
+        raise ArgumentError, "snapshot must be an Array, got: #{entries.class}" unless entries.is_a?(Array)
+
+        entries.filter_map do |entry|
+          case entry
+          when Event then entry
+          when Hash
+            type = entry[:type] || entry["type"]
+            from_h(entry) if known?(type)
+          end
+        end
+      end
+
       # Whether `type` is a canonical event type.
       def self.known?(type)
         TYPES.key?(type)
@@ -279,6 +307,7 @@ module Ask
         raise ArgumentError, "unknown session event type: #{type.inspect}" unless spec
         raise ArgumentError, "payload for #{type} must be a Hash" unless payload.is_a?(Hash)
 
+        payload = normalize_payload_keys(payload, "event #{type} payload")
         spec[:payload].each do |field, field_spec|
           value = payload[field]
           if field_spec[:required] && value.nil?
@@ -291,6 +320,32 @@ module Ask
         true
       end
 
+      # Normalize a payload's keys to the wire form (String). Ruby callers
+      # build payloads with Symbol keys all the time; JSON would stringify
+      # them on the way out anyway, so the contract accepts both at the
+      # boundary and stores String keys. Keys that cannot round-trip — a
+      # Symbol/String collision on the same name, or a key that is neither
+      # — raise, because serializing those would silently drop or
+      # duplicate data on the wire.
+      #
+      # @api private
+      def self.normalize_payload_keys(payload, label)
+        return payload unless payload.is_a?(Hash)
+        return payload if payload.keys.all?(String)
+
+        payload.each_with_object({}) do |(key, value), out|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "#{label} keys must be Strings or Symbols, got #{key.inspect}"
+          end
+
+          name = key.to_s
+          if out.key?(name)
+            raise ArgumentError, "#{label} has duplicate key #{name.inspect} after normalizing Symbols to Strings"
+          end
+          out[name] = value
+        end
+      end
+
       # Shared field validator, used by the events, interactions, and
       # methods registries. Public because sibling modules call it with an
       # explicit receiver.

data/lib/ask/session_protocol/interactions.rb

@@ -92,6 +92,7 @@ module Ask
       # @param payload [Hash] kind-specific body
       # @return [Interaction]
       def self.interaction(id:, kind:, status: "pending", payload: {})
+        payload = Events.normalize_payload_keys(payload, "interaction #{kind} payload")
         validate_payload!(kind, payload)
         Interaction.new(id: id, kind: kind, status: status, payload: payload)
       end
@@ -101,9 +102,9 @@ module Ask
       # @param hash [Hash] { "id" =>, "kind" =>, "status" =>, "payload" => }
       # @return [Interaction]
       def self.from_h(hash)
-        hash = hash.transform_keys(&:to_s)
         raise ArgumentError, "interaction must be a Hash" unless hash.is_a?(Hash)
 
+        hash = hash.transform_keys(&:to_s)
         interaction(
           id: hash["id"],
           kind: hash["kind"],
@@ -123,6 +124,7 @@ module Ask
         raise ArgumentError, "unknown interaction kind: #{kind.inspect}" unless spec
         raise ArgumentError, "payload for #{kind} must be a Hash" unless payload.is_a?(Hash)
 
+        payload = Events.normalize_payload_keys(payload, "interaction #{kind} payload")
         spec.each do |field, field_spec|
           value = payload[field]
           if field_spec[:required] && value.nil?

data/lib/ask/session_protocol/methods.rb

@@ -116,7 +116,7 @@ module Ask
           },
           result: {
             "subscription" => { type: :object, required: true, description: "{sessionId, deliveryKind}." },
-            "snapshot" => { type: :array, required: false, description: "Events after afterSeq, when includeSnapshot." }
+            "snapshot" => { type: :array, required: false, description: "Canonical event envelopes after afterSeq (host-internal events are filtered out), when includeSnapshot." }
           }
         },
         "session/events" => {

data/lib/ask/session_protocol/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module SessionProtocol
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-session-protocol
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto