flezha 0.1.0-x86_64-linux

data/lib/flezha/codec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "json"
+require "msgpack"
+require "set"
+
+module Flezha
+  # The MessagePack codec for durable `State` and `Change` bodies, and the Ruby
+  # type mapping that goes with it. The payload formats a channel names on
+  # `input` and `output` are here too, as `CHANNEL_CODECS`.
+  #
+  # The mapping is specified here rather than inherited from a library default,
+  # because the defaults are wrong for a format that has to survive a restart:
+  #
+  # | Ruby      | MessagePack            | Why not the default                    |
+  # | --------- | ---------------------- | -------------------------------------- |
+  # | `Symbol`  | extension 0            | otherwise it decodes back as a String, and `apply_change` reads a different value on replay than it did live |
+  # | `Time`    | timestamp extension    | a string or a number loses the type     |
+  # | Hash key  | symbolized on decode   | `{count: 1}` must fold back as `{count: 1}`, not `{"count" => 1}` |
+  # | binary `String` | `bin`            | so a byte string survives as bytes rather than as invalid UTF-8 |
+  #
+  # Ruby's integers are arbitrary-precision, so the u64 offsets, seqs and
+  # timestamps in the schema need no width policy: the hazard other SDKs carry
+  # (a `number` losing precision above 2^53, a `PHP_INT_MAX` ceiling) has no
+  # analogue here. Past `2^64 - 1` MessagePack itself has no integer, and it
+  # raises rather than narrowing — which is the outcome that matters.
+  #
+  # `Marshal` appears nowhere on this path, or on the wire path. It embeds
+  # class names and instance-variable layout, so renaming a State class breaks
+  # the restore of every record written before the rename, and the first anyone
+  # would learn of it is a restart.
+  module Codec
+    # Extension id for a Symbol. Ruby-side only: it rides inside a body whose
+    # header already carries `sdk_lang`, so no other SDK ever decodes it.
+    EXT_SYMBOL = 0x00
+
+    FACTORY = MessagePack::Factory.new
+    FACTORY.register_type(EXT_SYMBOL, Symbol)
+    FACTORY.register_type(
+      MessagePack::Timestamp::TYPE, Time,
+      packer: MessagePack::Time::Packer, unpacker: MessagePack::Time::Unpacker
+    )
+    FACTORY.freeze
+
+    module_function
+
+    def encode(value)
+      FACTORY.dump(value)
+    end
+
+    def decode(bytes)
+      return nil if bytes.nil? || bytes.empty?
+
+      FACTORY.load(bytes.b, symbolize_keys: true)
+    end
+
+    # The payload formats a channel names on `input` and `output`. A payload
+    # between two tasklets names none: it stays in the MessagePack above.
+    CHANNEL_CODECS = %i[bytes text json msgpack].freeze
+
+    # How `input` reads a channel's payload: the named codec, or JSON when the
+    # channel names none. JSON keys are symbolized, as the MessagePack decode
+    # symbolizes them, so a handler reads `value[:a]` under either.
+    def channel_decoder(codec, channel)
+      case codec
+      when :bytes then ->(bytes) { bytes.b }
+      when :text then ->(bytes) { utf8_text(bytes, channel) }
+      when :msgpack then method(:decode)
+      else ->(bytes) { bytes.empty? ? nil : JSON.parse(utf8_text(bytes, channel), symbolize_names: true) }
+      end
+    end
+
+    # How `output` writes a channel's payload: the named codec, or
+    # `plain_payload` when the channel names none.
+    def channel_encoder(codec, channel)
+      case codec
+      when :bytes then ->(value) { value.is_a?(String) ? value : refuse_payload(channel, codec, value) }
+      when :text then ->(value) { value.is_a?(String) ? utf8_text(value, channel) : refuse_payload(channel, codec, value) }
+      when :json then ->(value) { json_payload("channel '#{channel.name}'", value) }
+      when :msgpack then method(:encode)
+      else ->(value) { plain_payload(value, "channel '#{channel.name}'") }
+      end
+    end
+
+    # A String as its bytes and anything else as JSON: what an output naming no
+    # codec sends, and what a steps completion carries. `owner` is the
+    # channel or tasklet a refusal names.
+    def plain_payload(value, owner)
+      value.is_a?(String) ? value : json_payload(owner, value)
+    end
+
+    # What `plain_payload` wrote, read back: JSON, else UTF-8 text, else the
+    # bytes. A String that reads as JSON comes back as that JSON value.
+    def plain_value(bytes)
+      JSON.parse(bytes)
+    rescue JSON::ParserError, EncodingError
+      text = bytes.dup.force_encoding(Encoding::UTF_8)
+      text.valid_encoding? ? text : bytes.b
+    end
+
+    def utf8_text(bytes, channel)
+      text = bytes.dup.force_encoding(Encoding::UTF_8)
+      return text if text.valid_encoding?
+
+      raise EncodingError, "channel `#{channel.name}`: the payload is not valid UTF-8"
+    end
+
+    def json_payload(owner, value)
+      JSON.generate(value)
+    rescue JSON::GeneratorError => e
+      raise Error.new("runtime.value_not_json", owner: owner, type: value.class.to_s, reason: e.message)
+    end
+
+    def refuse_payload(channel, codec, value)
+      raise Error.new("runtime.value_wrong_for_codec", channel: channel.name, codec: codec.to_s, type: value.class.to_s)
+    end
+
+    def unrepresentable(type_name, path, reason)
+      Error.new("topology.state_unrepresentable", path: "#{type_name}.#{path.empty? ? '<root>' : path}", reason: reason)
+    end
+
+    # A value the codec cannot carry, named by the declaring type and the path
+    # to the offending field.
+    #
+    # Walked once at registration against what `init_state` produces, so an
+    # author learns at startup rather than at the first restore that their
+    # state does not survive one.
+    def assert_representable(type_name, sample)
+      walk(type_name, sample, "", {})
+    end
+
+    def walk(type_name, value, path, seen)
+      reason = unrepresentable_reason(value)
+      raise unrepresentable(type_name, path, reason) if reason
+      return unless value.is_a?(Hash) || value.is_a?(Array)
+
+      if seen.key?(value.object_id)
+        raise unrepresentable(type_name, path,
+                              "the value refers back to itself; MessagePack has no representation for a cycle")
+      end
+      seen[value.object_id] = true
+      if value.is_a?(Array)
+        value.each_with_index { |item, index| walk(type_name, item, "#{path}[#{index}]", seen) }
+      else
+        value.each do |key, item|
+          unless key.is_a?(Symbol) || key.is_a?(String)
+            raise unrepresentable(type_name, path,
+                                  "a Hash key of #{key.class} decodes as a String; declare Symbol or String keys")
+          end
+          walk(type_name, item, path.empty? ? key.to_s : "#{path}.#{key}", seen)
+        end
+      end
+      seen.delete(value.object_id)
+    end
+
+    def unrepresentable_reason(value)
+      case value
+      when nil, true, false, Integer, Float, String, Symbol, Time, Hash, Array then nil
+      when Proc, Method
+        "a callable has no durable form; hold the data it closes over instead"
+      when Set
+        "a Set decodes as a Hash, losing its identity; declare an Array, or supply a " \
+        "hand-written codec"
+      else
+        "an instance of #{value.class} decodes as a plain Hash, losing its class; declare a " \
+        "Hash or an Array, or supply a hand-written codec"
+      end
+    end
+
+    # The JSON form of a state value, for a live read and a migration handover.
+    #
+    # JSON has no form for three things this codec carries, so each is marked
+    # rather than lost: a Symbol would come back a String, a Time a number, and
+    # a binary String would be mangled by UTF-8 validation.
+    def to_state_json(value)
+      JSON.generate(json_safe(value))
+    end
+
+    def from_state_json(bytes)
+      return nil if bytes.nil? || bytes.empty?
+
+      json_revive(JSON.parse(bytes.b.force_encoding(Encoding::UTF_8)))
+    end
+
+    def json_safe(value)
+      case value
+      when Symbol then { "$sym" => value.to_s }
+      when Time then { "$time" => [value.to_i, value.nsec] }
+      when String then binary?(value) ? { "$bytes" => [value].pack("m0") } : value
+      when Hash then value.to_h { |k, v| [k.to_s, json_safe(v)] }
+      when Array then value.map { |item| json_safe(item) }
+      else value
+      end
+    end
+
+    def json_revive(value)
+      case value
+      when Hash
+        marked = value.size == 1 ? value.keys.first : nil
+        case marked
+        when "$sym" then return value[marked].to_sym
+        when "$bytes" then return value[marked].unpack1("m0").b
+        when "$time"
+          seconds, nsec = value[marked]
+          return Time.at(seconds, nsec, :nanosecond)
+        end
+        value.to_h { |k, v| [k.to_sym, json_revive(v)] }
+      when Array then value.map { |item| json_revive(item) }
+      else value
+      end
+    end
+
+    def binary?(value)
+      value.encoding == Encoding::BINARY && !value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+    end
+  end
+end

data/lib/flezha/control.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flezha
+  # What a start answered: the id the relay runs under, the generated one
+  # when the start named none, and `:started` or `:already_running`.
+  StartResult = Struct.new(:id, :outcome, keyword_init: true)
+
+  # Administering the namespace this runner's connection proved, from ordinary
+  # application code. Sending is the runner's own, `Runner#send_to`.
+  #
+  # No tasklet has to be running and the application holds no credential of
+  # its own: the controller judges every call as the identity the connection
+  # already established, so nothing an unattended process holds expires. An
+  # user grants a namespace's applications the authority once and revokes
+  # it the same way, and a revocation takes effect on the next call:
+  #
+  #     flz role bind runner@team-orders app team-orders
+  #
+  # Every method here is one line over a single native entry point, because the
+  # verb travels as data. Adding a verb costs a method and no native work.
+  class Control
+    def initialize(core)
+      @core = core
+    end
+
+    # Start a relay of `factory_id`, on the specification
+    # `flz relay start` takes, answering a `StartResult`.
+    #
+    # Without an `id` the controller generates one, so a start retried after a
+    # lost answer starts a second relay, and a second stream runs until it
+    # is stopped. With an `id`, a start of a running one leaves it untouched
+    # and answers `:already_running`.
+    def start_relay(factory_id, id: nil, init_values: nil, opts: nil)
+      answer = call("Relay.start", given(factory_id:, id:, init_values:, opts:))
+      StartResult.new(id: answer.fetch("id"), outcome: answer.fetch("outcome").to_sym)
+    end
+
+    # Stop a relay, or the whole partition group it names.
+    def stop_relay(relay_id) = call("Relay.stop", relay_id)
+
+    # Enable the plugin `name` in this namespace, of the provider `provider`
+    # (for example `"relay_websocket"`), on its `opts`. `single: true` runs
+    # one copy in the whole cluster; `relay_id` with `hooks` binds that
+    # relay in the same call.
+    def enable_plugin(name, provider, opts: {}, single: nil, relay_id: nil, hooks: nil)
+      call("PluginManager.enable", name, given(provider:, opts:, single:, relay_id:, hooks:))
+    end
+
+    # Bind the relay `relay_id` to the enabled plugin `name`, with the
+    # optional `hooks` and `channel`.
+    def bind_plugin(name, relay_id, hooks: nil, channel: nil)
+      call("PluginManager.bind", name, given(relay_id:, hooks:, channel:))
+    end
+
+    # Unbind the relay `relay_id` from the plugin `name`, which stays enabled.
+    def unbind_plugin(name, relay_id) = call("PluginManager.unbind", name, { "relay_id" => relay_id })
+
+    # Disable the plugin `name`, stopping it wherever it runs.
+    def disable_plugin(name) = call("PluginManager.disable", name, {})
+
+    # The relays in this namespace across the cluster: `rows`, one row each
+    # (its id, health, runner and node, and a partition group's width and
+    # members), and `unreachable`, the controllers that did not answer.
+    def list_relays = call("Relay.list")
+
+    # The plugins enabled in this namespace, one row each: name, provider,
+    # single, bound relays and where it runs.
+    def list_plugins = call("PluginManager.enabled")
+
+    # A relay's live state, and the change sequence it was read at. `cell` is
+    # `<tasklet>[/<cell_key>]`: a tasklet's Cells, or one of them; nil reads
+    # every Cell of the relay.
+    def cell_state(relay_id, cell = nil) = call("Relay.cell_state", relay_id, cell)
+
+    # Any published function, by name. What succeeds follows from the role the
+    # namespace is bound to, never from a list kept here. The arguments are the
+    # call's own other than the namespace, which the controller fills from the
+    # connection.
+    def call(verb, *args)
+      JSON.parse(@core.admin_call(verb, JSON.generate(args)))
+    end
+
+    private
+
+    # The named parameters a call was given, leaving out every one it was not.
+    def given(**fields) = fields.compact.transform_keys(&:to_s)
+  end
+end

data/lib/flezha/ctx.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "builder"
+require_relative "codec"
+require_relative "errors"
+require_relative "identity"
+
+module Flezha
+  # The invocation context: every deterministic effect a handler is allowed.
+  #
+  # The context accumulates one item's effects (recorded changes, outputs,
+  # timer operations, the checkpoint flag, a completion request) and the
+  # dispatcher turns them into the item effect the core folds. Nothing here
+  # reaches the wire on its own; an emit is a value in a list until the
+  # completion carries it.
+  class Ctx
+    # Metadata keys the runtime owns. A handler that sets one is refused.
+    RESERVED_PREFIX = "flz."
+
+    attr_reader :cell_key, :replay
+
+    def initialize(spec:, node:, outgoing:, registered:, address:, cell_key:, change_seq:,
+                   now:, replay:, state:, bridge:, token:, offset: nil, item: nil, compensating: false)
+      @token = token
+      # The index of the work item this invocation runs within its activation,
+      # which the core numbers and stamps a part by. A compensation has none.
+      @item = item
+      # The input-log offset of the item this invocation runs: a spawn carries
+      # it so a crash re-run of the same input resolves to the worker the first
+      # run spawned.
+      @offset = offset
+      @compensating = compensating
+      @spec = spec
+      @node = node
+      @outgoing = outgoing
+      # Where the identity bytes the core handed for this cell are kept.
+      @registered = registered
+      @address = address
+      @cell_key = cell_key
+      @change_seq = change_seq
+      @now = now
+      @replay = replay
+      @state = state
+      @bridge = bridge
+      @changes = []
+      @outputs = []
+      @timers = []
+      @checkpointed = false
+      @completion = nil
+      @ordinal = 0
+      @identity = nil
+    end
+
+    # The cell's state. Mutated only through `change`: a field assigned
+    # directly is live in this process and gone after a restart.
+    attr_reader :state
+
+    # The core-evaluated declared clock for this item. Never ambient time.
+    def now = @now
+
+    # A replay-stable identifier, distinct per invocation within the cell.
+    def stable_id
+      @identity ||= @registered.identity_of(@address)
+      id = Identity.stable_id(@identity, @change_seq, @ordinal)
+      @ordinal += 1
+      id
+    end
+
+    # Record one declared change: journaled, then folded into the state.
+    def change(change)
+      definition = @node.definition
+      unless definition.apply_change?
+        raise Error.new("runtime.change_without_apply_change", tasklet: @node.name)
+      end
+
+      codec = definition.change_codec
+      @changes << (codec ? codec.encode(change).b : Codec.encode(change))
+      # Fold it live through the same method the restore fold uses, so the live
+      # path and the replay path cannot drift. `apply_change` mutates the state
+      # in place and its answer is ignored — the same contract Rust's
+      # `&mut S` and the other SDKs carry, so a scalar state is declared as a
+      # Hash rather than reassigned here.
+      definition.fold_change(@state, change)
+    end
+
+    # Emit one output value on the tasklet's declared output.
+    def emit(value, key: nil, channel: nil, metadata: nil)
+      targets = channel ? @outgoing.select { |c| c.name == channel } : @outgoing
+      if targets.empty?
+        raise Error.new("runtime.channel_not_produced", tasklet: @node.name, channel: channel) if channel
+
+        raise Error.new("runtime.no_output_channel", tasklet: @node.name)
+      end
+
+      targets.each { |target| release(target, value, key, metadata) }
+      nil
+    end
+
+    # Send `value` as a part: a preview of the output this invocation is
+    # producing, which leaves the runner now rather than when the handler
+    # returns. It previews the tasklet's own output channel and is encoded as
+    # an emit of the same value there would be. The relay's listeners
+    # receive it before the output; an output never does, and it is never durable
+    # or replayed. Parts are numbered from 0 within each attempt, so a retry
+    # starts its preview again.
+    #
+    # It never waits: a part that cannot leave at once (no connection, a local
+    # run, a stream that would block, a frame over the size limit) is dropped,
+    # and a replayed input sends none. Raises a `Flezha::Error` coded
+    # `part.no_output` when the output channel does not end in an output (it only
+    # feeds another tasklet, or ends in `call`), and `part.outside_invocation`
+    # through a context whose invocation has returned.
+    def part(value)
+      channel = @outgoing.first
+      # A channel with no plugin end has no encoding; the core refuses its part
+      # before reading a byte.
+      payload = channel&.sink ? channel.sink_encode.call(value).b : "".b
+      # A compensation holds no work item, which the core answers as outside
+      # any invocation, whatever the index.
+      @bridge.part(@token, @item || 0, payload)
+      nil
+    end
+
+    # Register a processing-time timer `ms` from `now`. Answers its time.
+    # Inside a `compensate` hook each timer call raises `runtime.timers_unavailable`.
+    def timer_after(milliseconds)
+      # Anchored on `now`, never an ambient read: that is what makes a replayed
+      # invocation register the timestamp the live one did.
+      at = @now + Integer(milliseconds)
+      timer(kind: "processing_time", scheduled_at: at, register: true)
+      at
+    end
+
+    # Register an event-time timer at an absolute time. Answers it.
+    def timer_at_event_time(at)
+      at = Integer(at)
+      timer(kind: "event_time", scheduled_at: at, register: true)
+      at
+    end
+
+    # Cancel a registered timer by the value its registration answered.
+    def cancel_timer(kind, at)
+      timer(kind: kind.to_s, scheduled_at: Integer(at), register: false)
+      nil
+    end
+
+    # Close the open checkpoint interval (checkpoint ack-granularity classes).
+    def checkpoint
+      @checkpointed = true
+      nil
+    end
+
+    # End the instance this tasklet runs in, with `result`.
+    #
+    # The rest of the iteration still runs and commits; the instance then ends
+    # instead of waiting for its next input, a flow instance once every Cell is
+    # idle. In a `once` steps relay it sets the result the pass ends with.
+    # `result` is encoded as an output naming no codec encodes a value: a String as
+    # its bytes and anything else as JSON; nil carries an empty result. A later
+    # call in the same invocation replaces an earlier one.
+    def complete(result = nil)
+      @completion = result.nil? ? "".b : Codec.plain_payload(result, "tasklet '#{@node.name}'").b
+      nil
+    end
+
+    # Spawn a steps instance of `factory_id` with `payload` as its first
+    # message, answering a `SpawnHandle` at once. The payload is encoded as an
+    # output naming no codec encodes a value, the rule `complete` applies: a
+    # String as its bytes and anything else as JSON, so the instance's `text`
+    # or `json` entry channel reads it as it reads a send. With an `id` already
+    # running, `if_running: "deliver"` (the default) hands it `payload` instead,
+    # and `"error"` resolves to a `Flezha::Error` coded `relay.already_running`. A replayed
+    # invocation sends nothing and resolves to `:skipped_on_replay`.
+    #
+    # Without an `id` the controller generates one and always starts a new
+    # instance, so a spawn reissued after a lost or timed-out answer starts a
+    # second one, and a replayed invocation answers an empty id. Pass an id to
+    # start at most one instance, or to get the id back on replay.
+    def spawn_steps(factory_id, payload, id: nil, if_running: nil)
+      handle = @bridge.spawn_request(@token, factory_id, id.to_s,
+                                     Codec.plain_payload(payload, "tasklet '#{@node.name}'").b,
+                                     if_running.to_s, @replay, @offset)
+      SpawnHandle.new(@bridge, handle)
+    end
+
+    # Run the block, a call to anything outside the instance (a model, a tool,
+    # a service), and keep its result: when this invocation runs again (a
+    # crash re-run, a replay, a wake, a move), the call answers the kept result
+    # and the block does not run.
+    #
+    # The result is kept, synced on the controller, before this answers. A
+    # crash between the block finishing and that point runs it again, so give
+    # the outside service `stable_id` as an idempotency key where it takes
+    # one. `name` names the call: a non-empty String of at most 255 bytes,
+    # counted per invocation, so a call of another name added before this one
+    # leaves its kept result where it was. One call runs at a time; a
+    # concurrent one is refused.
+    #
+    # The result is encoded as an output naming no codec encodes a value (a
+    # String as its bytes, anything else as JSON) and read back as JSON, else
+    # text, else bytes; `codec` (an object answering `encode` and `decode`, as
+    # a change codec does) encodes and decodes it instead. The call answers the
+    # result as it reads back, on a first run and a re-run alike.
+    #
+    # An invocation that took no input-log offset (local mode, a relay with no
+    # input log) runs the block each time and keeps nothing. The block's own
+    # error propagates and nothing is kept. Raises a `Flezha::Error` coded
+    # `effect.bad_name`, `effect.nested`, `effect.outside_invocation`,
+    # `effect.too_large` or `effect.not_recorded` (the only one retried).
+    def effect(name, codec: nil)
+      item = @item || 0
+      status, kept = effect_refusals { @bridge.effect_begin(@token, item, name) }
+      return effect_decode(kept, codec) if status == :kept
+
+      begin
+        value = yield
+        encoded = (codec ? codec.encode(value) : Codec.plain_payload(value, "effect '#{name}'")).b
+        first = effect_refusals { @bridge.effect_end(@token, item, encoded) } if status == :run
+        effect_decode(first || encoded, codec)
+      ensure
+        # A no-op once the end has kept the result.
+        @bridge.effect_release(@token, item)
+      end
+    end
+
+    private
+
+    # The effect record for this item, as the core folds it. The dispatcher
+    # and the test harness read it through `send`, as friends of the context.
+    def effect_record(consumed_offset)
+      {
+        verdict: "ok",
+        changes: @changes,
+        outputs: @outputs,
+        consumed_offset: consumed_offset,
+        event_time: @now,
+        timers: @timers,
+        checkpoint: @checkpointed,
+        complete: @completion
+      }
+    end
+
+    # An `effect.*` refusal is non-retryable, but for `effect.not_recorded`: a
+    # call that could not be kept is the one worth running again.
+    def effect_refusals
+      yield
+    rescue Error => e
+      e.define_singleton_method(:non_retryable?) { true } if e.code.start_with?("effect.") && e.code != "effect.not_recorded"
+      raise
+    end
+
+    def effect_decode(body, codec) = codec ? codec.decode(body) : Codec.plain_value(body)
+
+    def timer(operation)
+      # A rollback is no place to arm a deadline.
+      raise Error.new("runtime.timers_unavailable") if @compensating
+
+      @timers << operation
+    end
+
+    def release(channel, value, key, metadata)
+      # In steps a value rides the edge path to its first consumer, and a
+      # terminal the core derived inter-tasklet hands it to the core as the
+      # pass's handoff (a chained loop's carry); any other releases nothing.
+      if @spec.runs_in_steps?
+        consumer = channel.consumers.first&.tasklet
+        consumer ||= channel.producer if channel.derived_kind == "inter_task"
+        @outputs << steps_output(channel, consumer, value) if consumer
+      else
+        channel.consumers.each do |edge|
+          @outputs.concat(edge_outputs(channel, edge, value, key, metadata))
+        end
+      end
+      @outputs << plugin_output(channel, value, key, metadata) if channel.sink
+      @outputs.concat(call_outputs(channel, value, metadata)) if channel.call
+    end
+
+    # The requests a call end sends, with the call chain's transforms and key
+    # applied here as an edge's are; the core stamps the call onto each.
+    def call_outputs(channel, value, metadata)
+      call = channel.call
+      Flezha.apply_transforms(call.transforms, value).map do |request|
+        {
+          target: "plugin", channel: nil, consumer: nil, plugin_channel: channel.name,
+          key: call.key_by&.call(request), event_time: nil, metadata: meta_list(metadata),
+          payload: call.encode.call(request).b
+        }
+      end
+    end
+
+    def steps_output(channel, consumer, value)
+      payload = Codec.encode(value)
+      {
+        target: "edge", channel: channel.index, consumer: consumer,
+        plugin_channel: nil, key: nil, event_time: nil, metadata: [], payload: payload
+      }
+    end
+
+    # One consumer's frames, with its own transforms, key and clock: none when
+    # a filter dropped the value, one per value when a flat_map fanned it.
+    def edge_outputs(channel, edge, value, key, metadata)
+      definition = @spec.tasklets[edge.tasklet].definition
+      # Producer-side, in declaration order: the core routes on `(edge, key)`
+      # and never evaluates a host closure.
+      Flezha.apply_transforms(edge.transforms, value).map do |transformed|
+        {
+          target: "edge",
+          channel: channel.index,
+          consumer: edge.tasklet,
+          plugin_channel: nil,
+          key: key || (edge.key_by && edge.key_by.call(transformed)) || @cell_key,
+          event_time: definition.event_time? ? definition.event_time_of(transformed) : nil,
+          metadata: meta_list(metadata),
+          payload: Codec.encode(transformed)
+        }
+      end
+    end
+
+    # The plugin frame, serialized once from the value as emitted: an edge's
+    # transforms belong to that edge, so they never reach the output.
+    def plugin_output(channel, value, key, metadata)
+      resolved = key || @cell_key
+      if channel.keyed && resolved.nil?
+        raise Error.new("runtime.key_required_on_keyed_channel", channel: channel.name)
+      end
+
+      pairs = meta_list(metadata)
+      # An encoder's string carries whatever encoding it was built in, so it is
+      # copied into bytes; `String#b` copies even when the encoding matches.
+      payload = channel.sink_encode.call(value).b
+      {
+        target: "plugin", channel: nil, consumer: nil, plugin_channel: channel.name,
+        key: resolved, event_time: nil, metadata: pairs, payload: payload
+      }
+    end
+
+    def meta_list(metadata)
+      return [] unless metadata
+
+      metadata.map do |key, value|
+        raise Error.new("runtime.reserved_metadata_key", key: key.to_s) if key.to_s.start_with?(RESERVED_PREFIX)
+
+        [key.to_s, value.to_s]
+      end
+    end
+  end
+
+  # A spawn that reached an instance: the id it resolved to, the caller's or
+  # the generated one, and `:spawned`, `:delivered` or `:skipped_on_replay`.
+  SpawnResult = Struct.new(:id, :outcome, keyword_init: true)
+
+  # The answer to one spawn request, read inside the invocation that made it:
+  # a resolved handle answers every read the same until its invocation ends,
+  # when the core releases it and logs once a failure no read collected.
+  class SpawnHandle
+    def initialize(bridge, handle)
+      @bridge = bridge
+      @handle = handle
+    end
+
+    # Wait for the answer: a `SpawnResult`, or raises the `Flezha::Error`
+    # naming why the spawn failed, its code the controller's (such as
+    # `relay.already_running`) or the core's (`spawn.timeout`,
+    # `spawn.unavailable`).
+    #
+    # The wait is in the core with the GVL released, as every waiting core
+    # call is, so under the fiber executor it holds the dispatch thread, and
+    # every other handler fiber with it, until the answer arrives.
+    def wait
+      Core.load_extension
+      read(Native::WAIT_CORE_BOUND)
+    end
+
+    # The answer if it has arrived, without waiting: `nil` while pending, and
+    # otherwise what `wait` answers or raises.
+    def try_result = read(0)
+
+    private
+
+    def read(timeout_ms)
+      return unless (json = @bridge.spawn_result(@handle, timeout_ms))
+
+      answer = JSON.parse(json)
+      SpawnResult.new(id: answer["id"], outcome: answer["outcome"].to_sym)
+    end
+  end
+end