flezha 0.1.0-x86_64-linux

data/lib/flezha/state.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "codec"
+
+module Flezha
+  # Declared state: how it is built and how it is restored.
+  #
+  # Declared state is mutated only through declared changes, because the change
+  # log IS how the state is rebuilt: a field assigned directly is live in this
+  # process and gone after a restart, and nothing would report the difference
+  # until the restart. Ruby has no cheap deep read-only view — the Node SDK's
+  # guard is a `Proxy`, which has no counterpart here that does not cost an
+  # allocation per field read — so the rule is documented and `ctx.change` is
+  # the path, rather than paid for on every access.
+  module State
+    module_function
+
+    # Decode one durable body, choosing between the three things it could be:
+    # a payload from an older schema version, one the tasklet declared its
+    # own codec for, or the MessagePack default.
+    #
+    # One function rather than the same three-way choice written at each of the
+    # places a body is decoded — the two halves of a restore fold, on the
+    # dispatch path and in the test harness.
+    def decode_body(definition, which, body, tasklet)
+      from_version = body[:from_version]
+      bytes = body[:bytes] || "".b
+      if from_version
+        migration = :"migrate_#{which}"
+        unless definition.declares?(migration)
+          raise Error.new("runtime.hook_missing",
+                          tasklet: tasklet,
+                          action: "was handed a #{which} record written at schema version #{from_version}",
+                          hook: migration.to_s)
+        end
+
+        return definition.instance.public_send(migration, from_version, bytes)
+      end
+
+      codec = which == :state ? definition.state_codec : definition.change_codec
+      codec ? codec.decode(bytes) : Codec.decode(bytes)
+    end
+
+    # Rebuild a cell's state: the declared starting value, the snapshot
+    # baseline when there is one, then every change folded on top in order.
+    #
+    # This IS the restore, and both callers are the real thing — the dispatcher
+    # answering a restore fold, and the test harness constructing from a
+    # payload — which is why the harness proves what a warm restart does rather
+    # than a second implementation that agrees with it.
+    def fold_restore(definition, payload, cell_key, tasklet)
+      state = definition.build_initial_state(cell_key)
+      snapshot = payload[:snapshot]
+      state = decode_body(definition, :state, snapshot, tasklet) if snapshot
+
+      Array(payload[:changes]).each do |body|
+        unless definition.apply_change?
+          raise Error.new("runtime.change_without_apply_change", tasklet: tasklet)
+        end
+
+        definition.fold_change(state, decode_body(definition, :change, body, tasklet))
+      end
+      state
+    end
+  end
+end

data/lib/flezha/tasklet.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative "codec"
+require_relative "declarative"
+require_relative "errors"
+
+module Flezha
+  # The codec for an author-declared State or Change class.
+  #
+  # `to_h` on the way out and `.from_h` on the way back, over MessagePack —
+  # never `Marshal`, which embeds the class name and the instance-variable
+  # layout, so a rename would break the restore of every record written before
+  # it. Encoding the Hash instead is what makes the rename survivable.
+  #
+  # Built on the same `state_codec` / `change_codec` seam a hand-written codec
+  # uses, rather than beside it: the dispatcher and the restore fold already
+  # ask that seam, and a second one would be a second answer to one question.
+  class TypeCodec
+    attr_reader :type
+
+    def initialize(type, which)
+      unless type.method_defined?(:to_h)
+        raise Codec.unrepresentable(type, which.to_s, "it declares no `to_h`; a durable #{which} is encoded as the " \
+                                                      "Hash it answers")
+      end
+      unless type.respond_to?(:from_h)
+        raise Codec.unrepresentable(type, which.to_s,
+                                    "it declares no `.from_h`; a durable #{which} is rebuilt from the Hash it " \
+                                    "was encoded as")
+      end
+
+      @type = type
+    end
+
+    def encode(value) = Codec.encode(value.to_h)
+    def decode(bytes) = @type.from_h(Codec.decode(bytes))
+  end
+
+  # What a declared tasklet resolves to: the scalar declarations, and the one
+  # instance whose methods the dispatcher calls.
+  #
+  # Tasklets hold no state of their own — a cell's state lives in the
+  # registry and is handed to each invocation — so one instance per class is
+  # enough, and the dispatcher never allocates per activation.
+  class Definition
+    attr_reader :name, :cell_keys, :idle_ttl_ms, :max_cells, :clock,
+                :mailbox_capacity, :max_timers_per_cell, :schema_version, :min_readable_schema_version,
+                :compact_after_bytes,
+                :state_type, :state_codec, :change_codec, :instance
+
+    # Read straight off the class rather than through a mirrored option hash:
+    # the hash was the declaration written twice, and a field added to one half
+    # and not the other is a declaration that silently does not reach the core.
+    # Captured here rather than delegated, because the dispatcher reads these
+    # on the hot path.
+    def initialize(klass)
+      @body = klass.body
+      @name = klass.tasklet_name
+      @cell_keys = klass.cell_keys
+      @idle_ttl_ms = klass.idle_ttl_seconds&.*(1000)
+      @max_cells = klass.max_cells
+      @mailbox_capacity = klass.mailbox_capacity
+      @max_timers_per_cell = klass.max_timers_per_cell
+      @schema_version = klass.schema_version
+      @min_readable_schema_version = klass.min_readable_schema_version
+      @compact_after_bytes = klass.compact_after_bytes
+      @state_type = klass.state_type
+      @state_codec = klass.state_codec
+      @change_codec = klass.change_codec
+      @instance = @body.new
+      @clock = if event_time? then :event_time
+               elsif klass.logical_clock? then :logical
+               else :wall
+               end
+    end
+
+    def declares?(method) = @body.method_defined?(method) || @body.private_method_defined?(method)
+
+    def init_state? = declares?(:init_state)
+    def apply_change? = declares?(:apply_change)
+    def cells_for? = declares?(:cells_for)
+    def event_time? = declares?(:event_time)
+    def on_timer? = declares?(:on_timer)
+    def compensate? = declares?(:compensate)
+    def migrate_state? = declares?(:migrate_state)
+    def migrate_change? = declares?(:migrate_change)
+
+    # Whether a Cell of this tasklet holds a state at all.
+    def stateful? = init_state? || !@state_type.nil?
+
+    def build_initial_state(cell_key)
+      if init_state? then @instance.init_state(cell_key)
+      elsif @state_type then @state_type.new
+      end
+    end
+
+    def fold_change(state, change) = @instance.apply_change(state, change)
+    def cells_for(input) = Array(@instance.cells_for(input))
+    def event_time_of(input) = Integer(@instance.event_time(input))
+  end
+
+  # A tasklet's class-level declarations. A tasklet class carries them,
+  # and so does a short-form relay class, which hands them to the
+  # tasklet it generates.
+  module TaskletSettings
+    # The scalar declarations. Each is read by its bare name and written by
+    # naming a value: `max_cells` answers, `max_cells 100` declares.
+    SCALARS = %i[mailbox_capacity schema_version min_readable_schema_version
+                 state_codec change_codec max_cells max_timers_per_cell
+                 compact_after_bytes].freeze
+    # Written by the declarations below, which check their value or write
+    # more than one variable; named so a subclass inherits them.
+    WRITTEN = %i[cell_keys idle_ttl_seconds state_type change_type].freeze
+    # Declared by a bare mention in the class body.
+    FLAGS = %i[logical_clock].freeze
+    NAMES = (SCALARS + WRITTEN + FLAGS).freeze
+
+    # Class-body declarations that no longer exist, with what replaced each.
+    RETIRED = {
+      dynamic_cells: "a tasklet fed by `key_by` has one Cell per key; write `idle_ttl_seconds` " \
+                     "and `max_cells` on their own",
+      clock: "defining `event_time` makes the clock event time and `logical_clock` makes it " \
+             "logical; otherwise it is the wall clock",
+      idle_ttl_ms: "write `idle_ttl_seconds`, a whole number of seconds",
+      migrate_state: "define `migrate_state(from_version, bytes)` as an instance method",
+      migrate_change: "define `migrate_change(from_version, bytes)` as an instance method"
+    }.freeze
+
+    def self.extended(base)
+      base.setting(*SCALARS)
+      FLAGS.each { |name| base.flag(name) }
+      base.declares(*WRITTEN)
+    end
+
+    RETIRED.each do |retired, instead|
+      define_method(retired) do |*, **|
+        raise NoMethodError.new("`#{retired}` is not a tasklet declaration any more: #{instead}",
+                                retired)
+      end
+    end
+
+    def cell_keys(*keys)
+      return @cell_keys if keys.empty?
+
+      @cell_keys = keys.flatten.map(&:to_s)
+    end
+
+    # How long a keyed Cell may sit idle before it is evicted, in whole
+    # seconds. Unset, a Cell is never evicted for being idle.
+    def idle_ttl_seconds(seconds = nil)
+      return @idle_ttl_seconds if seconds.nil?
+
+      unless seconds.is_a?(Integer) && seconds.positive?
+        raise Error.new("topology.invalid_setting", declaration: "tasklet '#{self}'", setting: "idle_ttl_seconds",
+                                                    value: seconds.inspect,
+                                                    expected: "a positive whole number of seconds")
+      end
+
+      @idle_ttl_seconds = seconds
+    end
+
+    # Whether the class body declared the logical clock.
+    def logical_clock? = @logical_clock || false
+
+    # Declare the class a cell's State is. Its `to_h` is what is encoded
+    # and its `.from_h` is what rebuilds it, so a rename of the class does
+    # not break the restore of records written before it: the durable form
+    # is the Hash, not the class. A tasklet that defines no `init_state`
+    # starts each Cell from `type.new`.
+    def state_type(type = nil)
+      return @state_type if type.nil?
+
+      @state_type = type
+      @state_codec = TypeCodec.new(type, "state")
+    end
+
+    # Declare the class a recorded Change is. Same contract as `state_type`.
+    def change_type(type = nil)
+      return @change_type if type.nil?
+
+      @change_type = type
+      @change_codec = TypeCodec.new(type, "change")
+    end
+  end
+
+  # The base every authored tasklet subclasses.
+  #
+  # The class body carries the `tasklet_name` and the scalar declarations; the
+  # instance methods carry the behaviour. Which optional hooks a tasklet
+  # declares is read from the methods it defines — `apply_change` present means
+  # it folds changes, `event_time` present means its clock is event time — so a
+  # declaration and its implementation cannot disagree. A value leaves only
+  # through `ctx.emit`; what `run` answers is not output.
+  class Tasklet
+    extend Declarative
+    extend TaskletSettings
+
+    # `tasklet_name` is deliberately NOT inherited: a node identity is per
+    # class, and a subclass silently taking its parent's would make two
+    # tasklets claim one node — which the builder refuses, at the far end of
+    # the declaration rather than here.
+
+    class << self
+      # The node identity within its relay, and the name every Cell's
+      # saved state is kept under. Written on every concrete tasklet, never
+      # derived: a derived name would move the saved state when the class is
+      # renamed. Not `name`, which is `Class#name`.
+      def tasklet_name(name = nil)
+        return @tasklet_name if name.nil?
+
+        @tasklet_name = name.to_s
+      end
+
+      # The class whose instance methods run for this tasklet: the tasklet
+      # itself, or the short-form relay whose `run` body it was generated
+      # from.
+      def body = self
+
+      # A tasklet has no output: the one-tasklet short form is a relay,
+      # and its output is written there.
+      def output(*, **)
+        raise Error.new("topology.relay_field_on_tasklet",
+                        tasklet: to_s, fields: ["`output`"],
+                        instead: "a Flezha::Relay subclass with a `run` body")
+      end
+
+      # The resolved declaration. Built once: it instantiates the tasklet,
+      # and the dispatcher reads it on the hot path.
+      def definition
+        @definition ||= build_definition
+      end
+
+      private
+
+      def build_definition
+        check_name
+        definition = Definition.new(self)
+        check_hooks(definition)
+        if @cell_keys&.empty?
+          raise Error.new("topology.static_tasklet_without_cell_keys", tasklet: @tasklet_name)
+        end
+        raise Error.new("topology.two_clocks", tasklet: @tasklet_name) if definition.event_time? && logical_clock?
+
+        check_state(definition)
+      end
+
+      def check_name
+        return unless @tasklet_name.to_s.empty?
+
+        raise Error.new("topology.tasklet_name_missing", tasklet: name || "an anonymous tasklet class")
+      end
+
+      def check_hooks(definition)
+        unless body.method_defined?(:run)
+          raise Error.new("topology.missing_body", declaration: "tasklet '#{@tasklet_name}'", body: "`run`")
+        end
+        return unless definition.declares?(:initial_state)
+
+        raise Error.new("topology.retired_callback", tasklet: @tasklet_name, callback: "`initial_state`",
+                                                     instead: "`init_state(cell_key)`")
+      end
+
+      # State without a fold is legitimate: a value seeded at start and read
+      # but never mutated has nothing to journal, and `ctx.change` already
+      # refuses at the point of use. A fold with no state to fold into is not.
+      def check_state(definition)
+        if definition.apply_change? && !definition.stateful?
+          raise Error.new("topology.change_without_state", tasklet: @tasklet_name)
+        end
+
+        # A state that cannot be built or encoded fails at the first Cell or
+        # the first restart. Build the starting state now instead.
+        if definition.init_state? && !state_codec
+          Codec.assert_representable("#{@tasklet_name}.state", definition.build_initial_state(nil))
+        elsif !definition.init_state? && state_type
+          check_state_type
+        end
+        definition
+      end
+
+      def check_state_type
+        state_type.new
+      rescue StandardError
+        raise Error.new("topology.state_not_constructible", tasklet: @tasklet_name, state: state_type.to_s)
+      end
+    end
+  end
+end

data/lib/flezha/testing.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+require_relative "builder"
+require_relative "codec"
+require_relative "dispatch"
+require_relative "state"
+
+module Flezha
+  # Driving one tasklet without a controller, for the author's own tests.
+  #
+  # The harness is not a second implementation of the dispatcher: it drives
+  # `Dispatch.invoke` — the same function every activation kind that reaches a
+  # handler goes through — over a one-tasklet `RegisteredClass`, and
+  # `replay_equals` folds through `State.fold_restore`, the function a real
+  # restore calls. So what it proves is what the runner does, rather than
+  # something that agrees with it.
+  module Testing
+    # The recorded change log and the live state disagree: the harness's own
+    # assertion about the tasklet under test, not a refusal.
+    class ReplayMismatch < StandardError
+      def initialize(tasklet, live, replayed)
+        super(
+          "#{tasklet}: replaying the recorded change log against a fresh initial state " \
+          "produced #{replayed.inspect}, but the live state is #{live.inspect}. Either a " \
+          "handler mutated the state without recording a change, or apply_change is not a " \
+          "pure fold — both are lost on restart and reported nowhere until then."
+        )
+      end
+    end
+
+    # A replayed input made an outside call its live run kept through
+    # `ctx.effect` some other way: its block ran again, or the kept result was
+    # never asked for.
+    class EffectReplayMismatch < StandardError
+      attr_reader :name
+
+      def initialize(tasklet, name, what)
+        @name = name
+        super(
+          "#{tasklet}: on the replay, effect '#{name}' #{what}. A re-run reads an outside " \
+          "call's result only through ctx.effect, with the same name in the same order."
+        )
+      end
+    end
+
+    # The longest effect name, in bytes, as the core refuses it.
+    MAX_EFFECT_NAME = 255
+
+    # One input's effect results, by `[name, ordinal]`, and the invocation's
+    # count of each name and the call whose block is running.
+    Effects = Struct.new(:kept, :replaying, :ordinals, :running)
+    private_constant :Effects
+
+    # What one invocation produced.
+    Outcome = Struct.new(:outputs, :changes, :timers, keyword_init: true)
+
+    # The core bridge a `Ctx` asks, answered as the core would for one
+    # tasklet with no controller behind it.
+    class FakeCore
+      BASE32 = [*"a".."z", *"2".."7"].freeze
+
+      # Answers by handle, until the invocation that made them ends, as the
+      # core releases them.
+      attr_reader :spawns
+
+      def initialize(tasklet)
+        @tasklet = tasklet
+        @spawns = {}
+        @spawn_count = 0
+        # Each live input's effect results, in order, and how many replays ran.
+        @kept = []
+        @replays = 0
+        @effects = Effects.new({}, false, {}, nil)
+      end
+
+      # Serve the next input: a live one keeps its results, the n-th replay
+      # reads what the n-th live input kept.
+      def begin_input(replay)
+        if replay
+          @effects = Effects.new(@kept[@replays] || {}, true, {}, nil)
+          @replays += 1
+        else
+          @effects = Effects.new({}, false, {}, nil)
+          @kept << @effects.kept
+        end
+      end
+
+      # A replay must ask for every result its live input kept.
+      def finish_input
+        unasked = @effects.kept.each_key.find { |name, ordinal| ordinal >= @effects.ordinals.fetch(name, 0) }
+        raise EffectReplayMismatch.new(@tasklet, unasked.first, "was never asked for") if @effects.replaying && unasked
+      end
+
+      # A harness has no controller, so a spawn resolves at once to what one
+      # would have answered: spawned under the given id or a generated-looking
+      # one, or skipped on a replay.
+      def spawn_request(_token, factory_id, id, _payload, _if_running, replay, _offset)
+        id = generated_id(factory_id) if id.empty? && !replay
+        outcome = replay ? "skipped_on_replay" : "spawned"
+        handle = @spawn_count += 1
+        @spawns[handle] = JSON.generate({ "id" => id, "outcome" => outcome })
+        handle
+      end
+
+      def spawn_result(handle, _timeout_ms)
+        @spawns.fetch(handle) { raise Error.new("runtime.spawn_handle_released", handle: handle) }
+      end
+
+      # No controller and no listener, so the part, already encoded, goes
+      # nowhere.
+      def part(_token, _item, _payload) = nil
+
+      # The core's answer to a begun `ctx.effect`, over this input's results:
+      # the kept one, or run the block (on a live input only).
+      def effect_begin(_token, _item, name)
+        raise Error.new("effect.bad_name", name: name.inspect) if name.empty? || name.bytesize > MAX_EFFECT_NAME
+
+        effects = @effects
+        raise Error.new("effect.nested", name: name) if effects.running
+
+        ordinal = effects.ordinals.fetch(name, 0)
+        effects.ordinals[name] = ordinal + 1
+        key = [name, ordinal]
+        return [:kept, effects.kept[key]] if effects.kept.key?(key)
+        raise EffectReplayMismatch.new(@tasklet, name, "ran its block") if effects.replaying
+
+        effects.running = key
+        [:run, nil]
+      end
+
+      # Keep a live input's result, as the controller does.
+      def effect_end(_token, _item, payload)
+        effects = @effects
+        raise "an end follows a begin that runs" unless effects.running
+
+        effects.kept[effects.running] = payload.b
+        effects.running = nil
+        nil
+      end
+
+      def effect_release(_token, _item)
+        @effects.running = nil
+      end
+
+      private
+
+      # The controller's shape: the factory id trimmed so the whole id fits the
+      # 32-byte limit, then 16 base32 characters.
+      def generated_id(factory_id)
+        prefix = factory_id.byteslice(0, 15).scrub("").sub(/[-_]+\z/, "")
+        "#{prefix}-#{SecureRandom.alphanumeric(16, chars: BASE32)}"
+      end
+    end
+    private_constant :FakeCore
+
+    # A `ctx.effect` keeps its result on a live `feed`; the n-th
+    # `feed(..., replay: true)` replays the n-th live input and is served what
+    # it kept, and raises `EffectReplayMismatch` when a block runs there or a
+    # kept result is never asked for.
+    class TaskletTestHarness
+      attr_reader :log
+
+      def initialize(tasklet_class, cell_key: nil, relay: "harness")
+        @definition = tasklet_class.definition
+        @cell_key = cell_key
+        # What every invocation's activation names: the cell this harness drives.
+        @target = { relay: relay, cell_key: cell_key }.freeze
+        # The real channel builder, not a hand-written spec: one entry channel
+        # into the tasklet, and one plugin output so `ctx.emit` has somewhere
+        # to go. A tasklet under test emits to be observed, not to be routed,
+        # and the output names MessagePack so `outputs` reports exactly the value
+        # a handler emitted.
+        builder = ChannelBuilder.new("<harness>")
+        builder.input("in").into(tasklet_class).output("out", codec: :msgpack)
+        @node = builder.tasklets.first
+        @spec = ClassSpec.new(factory_id: "<harness>", tasklets: builder.tasklets, channels: builder.channels)
+        # The dispatcher's own cell store, so the state this harness reports
+        # is the state a runner would hold.
+        @registered = RegisteredClass.new(@spec)
+        @address = RegisteredClass.address(@target, @node)
+        # No core runs here, so the harness names the cell's identity itself.
+        @registered.keep_identity(@address, "#{relay}/#{@node.name}/#{cell_key}".b)
+        @core = FakeCore.new(@definition.name)
+        @deps = DispatchDeps.new(registry: nil, bridge: @core)
+        @log = []
+        @change_seq = 0
+      end
+
+      # The cell's live state, as the dispatcher left it.
+      def state = @registered.state_of(@node, @address)
+
+      # Run the tasklet against one input; `replay` replays the next live
+      # input, in order.
+      def feed(input, now: 0, replay: false)
+        @core.begin_input(replay)
+        outcome = run(now, replay) { |ctx| @definition.instance.run(input, ctx) }
+        @core.finish_input
+        outcome
+      end
+
+      # Fire a per-cell timer. `now` IS the scheduled time, as it is live.
+      def fire_timer(kind, scheduled_at)
+        run(scheduled_at, false) do |ctx|
+          @definition.instance.on_timer({ kind: kind, scheduled_at: scheduled_at }, ctx)
+        end
+      end
+
+      # Run the declared compensation over recorded forward outputs.
+      def compensate(outputs)
+        run(0, false) { |ctx| @definition.instance.compensate(outputs, ctx) }
+      end
+
+      # Rebuild the state the way a restore does, from a snapshot and a change
+      # log — the same call the dispatcher answers `restore_fold` with.
+      def restore(snapshot: nil, changes: [])
+        @registered.set_state(@address, fold(snapshot, changes))
+      end
+
+      # Fold every recorded change into a fresh initial state and require the
+      # answer to equal the live one.
+      #
+      # In this SDK that catches both failures at once: a handler that mutated
+      # the state without recording a change, and an `apply_change` that is not
+      # a pure fold. The SDKs whose state is guarded can only catch the second.
+      def replay_equals
+        replayed = fold(nil, @log)
+        raise ReplayMismatch.new(@definition.name, state, replayed) unless replayed == state
+
+        true
+      end
+
+      private
+
+      # What the body answers is dropped, as the dispatcher drops it.
+      def run(now, replay)
+        activation = @target.merge(change_seq: @change_seq)
+        ctx = begin
+          Dispatch.invoke(activation, @registered, @node, @deps, now, replay) { |c| yield(c) }
+        ensure
+          @core.spawns.clear
+        end
+        record = ctx.send(:effect_record, nil)
+        @log.concat(record[:changes])
+        @change_seq += record[:changes].size
+        Outcome.new(
+          outputs: record[:outputs].map { |o| Codec.decode(o[:payload]) },
+          changes: record[:changes].map { |bytes| decode_change(bytes) },
+          timers: record[:timers]
+        )
+      end
+
+      def fold(snapshot, changes)
+        State.fold_restore(
+          @definition,
+          { snapshot: snapshot && { bytes: snapshot }, changes: changes.map { |bytes| { bytes: bytes } } },
+          @cell_key, @definition.name
+        )
+      end
+
+      def decode_change(bytes)
+        codec = @definition.change_codec
+        codec ? codec.decode(bytes) : Codec.decode(bytes)
+      end
+    end
+  end
+end

data/lib/flezha/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Flezha
+  VERSION = "0.1.0"
+
+  # The activation schema this gem was built against. Passed at context
+  # creation and compared with the native library's, so a skewed pair fails
+  # naming both versions before any controller connection is attempted.
+  ACTIVATION_SCHEMA_VERSION = 8
+end

data/lib/flezha.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# The Flezha Ruby SDK: a poll host over `flz_core`.
+#
+# The SDK contains no kernel code. Transport, framing, ordering, per-cell
+# exclusivity, durability, retries, the retry-to-park ladder, timers, credit,
+# routing, the steps driver and reconnect all live in the core; this gem
+# brings the authoring surface, the codec for user types, the threading host
+# and idiomatic errors.
+#
+#   class Echo < Flezha::Tasklet
+#     tasklet_name "echo"
+#     def run(input, ctx) = ctx.emit(input)
+#   end
+#
+#   class EchoRelay < Flezha::Relay
+#     factory_id "echo"
+#     channels { |c| c.input("input", codec: :text).into(Echo).output("out") }
+#   end
+#
+#   Flezha.create_runner("default").register_factory(EchoRelay).run
+
+require_relative "flezha/version"
+require_relative "flezha/errors"
+require_relative "flezha/logger"
+require_relative "flezha/identity"
+require_relative "flezha/codec"
+require_relative "flezha/response"
+require_relative "flezha/state"
+require_relative "flezha/builder"
+require_relative "flezha/tasklet"
+require_relative "flezha/route_latest"
+require_relative "flezha/relay"
+require_relative "flezha/graph"
+require_relative "flezha/ctx"
+require_relative "flezha/dispatch"
+require_relative "flezha/native"
+require_relative "flezha/control"
+require_relative "flezha/executor"
+require_relative "flezha/runner"
+require_relative "flezha/local"
+require_relative "flezha/testing"