insika 0.0.1 → 0.1.0

data/lib/insika/server/boot.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "async"
+
+module Insika
+  module Server
+    # Turns the components into a service.
+    # MANDATORY order, no parallelism: plugins → stores → recovery → (app
+    # for the listen). "Never accepts a request before recovery" is guaranteed BY
+    # CONSTRUCTION: the listen (Falcon) only runs after `#call` returns the app, and
+    # `#call` only returns after `Recovery.run` finishes.
+    class Boot
+      # wiring: object with the named steps (load_plugins/build_stores/
+      # recovery/app) — the config/wiring.rb. logger: simple IO (default $stdout;
+      # nil silences). app: overrides the wiring's `app` step — for a serving arm
+      # (config.ru) that assembles its own Rack app around the wiring; the
+      # "recovery before the listen" guarantee is unchanged (#call still only
+      # returns after recovery).
+      def initialize(wiring, logger: $stdout, app: nil)
+        @wiring = wiring
+        @logger = logger
+        @app = app
+      end
+
+      # -> Rack app ready for the `run`. A store failure at boot (corrupted
+      # file → StoreError) PROPAGATES and aborts the process (coming up
+      # without durability is worse than not coming up); an unrecoverable task does NOT
+      # bring down the boot (Recovery already marks it :failed).
+      def call
+        @wiring.load_plugins
+        @wiring.build_stores
+        warn_if_ephemeral
+        summary = run_recovery
+        log("boot: recovery complete — #{summary[:resumed].size} resumed, " \
+            "#{summary[:failed].size} failed")
+        @app || @wiring.app
+      end
+
+      private
+
+      # Recovery dispatches resume_task, which creates task fibers — needs a
+      # current reactor. At config.ru load (Falcon) there is NO reactor: the Sync { }
+      # creates one and, by structured concurrency, only returns when the resume
+      # fibers FINISH (recovery + turns completed before the listen — slower
+      # boot, semantically safe). Under an already-current reactor (tests
+      # inside Async), it runs directly: returns after the resume DISPATCH, with
+      # the turns still in flight — also correct: "recovery before the listen" =
+      # dispatch before the listen, not turn completion.
+      def run_recovery
+        return do_recovery if Async::Task.current?
+
+        Sync { do_recovery }
+      end
+
+      # Task recovery THEN delegation recovery (RFC-0010 Fase 2): the delegation
+      # sweep re-delivers completed-but-undelivered async delegations, and depends
+      # on the task sweep having re-dispatched any in-flight children first. Both
+      # create task fibers, so both must run inside the reactor scope of run_recovery.
+      #
+      # The TASK sweep is additionally gated per boot generation (RFC-0016 E2):
+      # its "orphaned :running" test cannot see a sibling worker's live fiber, so
+      # only the worker that claims the generation sweeps — the others would steal
+      # in-flight turns. The delegation and channel sweeps stay ungated: each of
+      # their records carries its own transactional claim (at-most-once holds
+      # however many workers sweep). Duck-typed: a wiring without the claim (test
+      # doubles, single-process arms) sweeps unconditionally.
+      def do_recovery
+        summary =
+          if skip_task_sweep?
+            log("boot: task sweep skipped — another worker claimed this boot generation")
+            { resumed: [], failed: [] }
+          else
+            @wiring.recovery.run
+          end
+        recover_delegations
+        recover_channel_deliveries
+        summary
+      end
+
+      def skip_task_sweep?
+        @wiring.respond_to?(:claim_recovery_sweep) && !@wiring.claim_recovery_sweep
+      end
+
+      # Duck-typed (like durable?): a wiring without async delegation just omits it.
+      def recover_delegations
+        return unless @wiring.respond_to?(:recover_delegations)
+
+        result = @wiring.recover_delegations
+        log("boot: delegations re-delivered — #{Array(result && result[:delivered]).size}")
+      end
+
+      # RFC-0011 §6.5: replies a previous process committed but never handed to the
+      # channel. Runs AFTER the task recovery for the same reason the delegation
+      # sweep does — a resumed turn writes its own outbox record at its terminal, and
+      # sweeping first would miss it.
+      def recover_channel_deliveries
+        return unless @wiring.respond_to?(:recover_channel_deliveries)
+
+        result = @wiring.recover_channel_deliveries
+        log("boot: channel replies re-dispatched — #{Array(result && result[:dispatched]).size}")
+      end
+
+      # Durability: without a durable backend, nothing is resumed after a
+      # restart — warns loudly at boot so we don't come up "without a net" by mistake. The
+      # test wiring (double) may not expose `durable?`; in that case, silence.
+      def warn_if_ephemeral
+        return unless @wiring.respond_to?(:durable?)
+        return if @wiring.durable?
+
+        log("boot: WARNING — EPHEMERAL backend (no INSIKA_DB): recovery will " \
+            "not resume anything after a restart (doc 02 §6).")
+      end
+
+      def log(message)
+        @logger&.puts(message)
+      end
+    end
+  end
+end

data/lib/insika/server/rack_app.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# RFC-0017 A3 — the /v1 transport as a VALUE the host app mounts, instead of a
+# server the engine starts.
+#
+#   mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
+#
+# The assembly used to live inline in DSL::ServerBoot#run, welded to
+# `Async::HTTP::Server.new(...).run` on the next line: a host that already owns a
+# reactor and a router could not reach it. Nothing here is new behavior — the
+# server boot now calls this instead of inlining it, which is what keeps the two
+# from drifting.
+#
+# The Studio is deliberately NOT part of this (the embed contract, item 4): it is
+# a class-level singleton, so it is one per process, and a host that wants the
+# operator UI mounts `Studio::App` itself and accepts that limitation.
+
+require_relative "app"
+
+module Insika
+  module Server
+    # `handle` is anything that answers #runtime (a DSL Definition/System) or a
+    # DSL::Runtime itself. -> a Rack app (`#call(env)`).
+    #
+    # It is mount-safe: routing reads `path_info`, so `Rack::URLMap`/Rails' `mount`
+    # moving the prefix into SCRIPT_NAME leaves every route intact.
+    def self.rack_app(handle, token: nil, **config)
+      AppBuilder.new(handle, token: token, **config).app
+    end
+
+    # Assembles Server::App from a graph. Also answers the two questions the boot
+    # banner asks (`workflows?`/`channels?`), so registering the env channels
+    # happens exactly once and in one place.
+    class AppBuilder
+      # Fixed local token: gates /v1 (Bearer) — and, under `serve`, logs into the
+      # Studio (cookie). Never a real secret; override with `token:`/ADMIN_TOKEN.
+      def initialize(handle, token: nil, **config)
+        @rt = handle.respond_to?(:runtime) ? handle.runtime : handle
+        @graph = @rt.graph
+        @token = token || ENV.fetch("ADMIN_TOKEN", "local-demo")
+        @config = config
+      end
+
+      attr_reader :token
+
+      def app
+        @app ||= Insika::Server::App.new(
+          command_bus: @graph.bus, event_stream: @graph.event_stream,
+          session_store: @graph.session_store, task_store: @graph.task_store,
+          pending_action_store: @graph.pending_action_store,
+          provisioner: Insika::PackImporter.new(bus: @graph.bus, profiles: @graph.profiles),
+          # GET /v1/agents/:id — the read-only capability view a case's `requires`
+          # resolves against (RFC-0014 §3.2).
+          profiles: @graph.profiles,
+          # Item 20 / §5.6: the OSS onboarding surface (start.md + models.json + docs).
+          # This is the primary "build my first agent" target — models.json reports the
+          # DSL's stores + the agents this process serves (each id IS the `model`).
+          onboarding: build_onboarding,
+          # Item 22: GET /v1/workflows + POST /v1/workflows/:name, opt-in by
+          # injection like every other edge — nil when the system declares none,
+          # so the routes simply do not exist (404, parity).
+          workflow_registry: (@graph.workflow_registry if workflows?),
+          # RFC-0011: the bundled relay, when the env turns it on. Same rule as the
+          # OTEL bridge — a feature only `config.ru` can reach is a feature the
+          # docs are half-true about.
+          channels: (@graph.channel_registry if channels?),
+          config: { gateway_token: @token }.merge(@config)
+        )
+      end
+
+      def workflows? = !@graph.workflow_registry.names.empty?
+
+      # Registers the env-configured channels once, and reports whether any exist.
+      def channels?
+        unless defined?(@channels_ready)
+          @channels_ready = true
+          relay = Insika::Channels::Relay.from_env(
+            http: Insika::HttpClient.new,
+            allow_http: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_HTTP"]),
+            allow_private: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_PRIVATE"])
+          )
+          @graph.channel_registry.register(relay.id, relay) if relay
+
+          widget = Insika::Channels::Web.from_env(
+            chat_rate_limit: Insika::Channels::Web.limit_resolver(
+              profiles: @graph.profiles, settings_store: @rt.component(:settings_store)
+            )
+          )
+          @graph.channel_registry.register(widget.id, widget) if widget
+        end
+        !@graph.channel_registry.names.empty?
+      end
+
+      private
+
+      def build_onboarding
+        configs = @rt.packs.map(&:config)
+        Insika::Onboarding.standard(
+          root: File.expand_path("../../..", __dir__),
+          settings_store: @rt.component(:settings_store),
+          provider_store: @rt.component(:provider_store),
+          # EVERY agent this process serves — each id IS a `model` on
+          # /v1/responses, so a coding agent reading models.json sees the whole
+          # system, not just the first one.
+          agents: -> { configs.map { |c| { id: c[:id], model: c[:model], provider: c[:provider] } } }
+        )
+      end
+    end
+  end
+end

data/lib/insika/server/responses.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Server
+    # OpenAI Responses edge adapter (`/v1/responses`) — the contract that the
+    # OpenClaw gateway consumers already speak (see achei-b2b
+    # `CoreServices::OpenclawDispatcher`). Phase 6, Step A.
+    #
+    # PURE module (no state, no framework): (a) translates the OpenAI
+    # Responses request → `:send_message` payload; (b) maps each turn Event →
+    # OpenAI Responses SSE frame (or nil for events with no counterpart). Follows the
+    # constitutional rule: no business logic, no store access here.
+    #
+    # Request: { model: "openclaw:<agent>", user: "<chat.id>", stream: true,
+    #            input: "<string with already-composed blocks>" } + header
+    # X-Openclaw-Agent (agent fallback). The `input` enters VERBATIM as the
+    # turn's message — the blocks (<memoria>/<dados_conhecidos>/directives) already come
+    # composed by the consumer (the engine does not interpret them).
+    module Responses
+      module_function
+
+      # -> { agent:, user:, message:, origin? } | raise ValidationError.
+      #
+      # `origin` is the consumer declaring WHO wrote the input it is sending. It
+      # matters here more than anywhere: this adapter's `input` is a STRING the
+      # consumer already composed out of context blocks plus the customer's text
+      # (`<memoria> …`, `<cacau_cep_obrigatorio> …`), so a transcript reader cannot
+      # tell the two apart — the first refinement run over real traffic reported 219
+      # "the customer repeated themselves" that were the engine reading its own
+      # fragment back. A consumer that sends `origin: "engine"` on a composed turn
+      # gets that filtered structurally instead of by a regex on the leading tag.
+      # Omitted = a customer typed it, which is what every turn meant before.
+      def parse_request(body, req)
+        agent = body[:model].to_s.sub(/\Aopenclaw:/, "")
+        agent = req.get_header("HTTP_X_OPENCLAW_AGENT").to_s if agent.empty?
+        raise Insika::ValidationError, "model/agent missing" if agent.strip.empty?
+
+        user = body[:user].to_s
+        raise Insika::ValidationError, "user missing" if user.strip.empty?
+
+        message = extract_input(body[:input])
+        raise Insika::ValidationError, "input empty" if message.strip.empty?
+
+        out = { agent: agent.strip, user: user, message: message }
+        (origin = Insika::MessageOrigin.parse!(body[:origin])) && (out[:origin] = origin)
+        out
+      end
+
+      # V1: `input` is a STRING (the dispatcher composes the blocks + user text). Tolerates
+      # an array of parts (OpenAI multimodal shape) by joining the texts.
+      def extract_input(input)
+        case input
+        when String then input
+        when Array
+          input.flat_map { |part| part.is_a?(Hash) ? (part[:text] || part["text"]) : part }
+               .compact.join("\n")
+        else input.to_s
+        end
+      end
+
+      # Turn Event -> OpenAI Responses SSE frame | nil (event with no
+      # counterpart: :task_started, :tool_result, :skill_activated, ...).
+      # Terminal events emit the final frame + `[DONE]` (close the stream).
+      def frame_for(event)
+        case event.type
+        when :content
+          sse("response.output_text.delta",
+              { type: "response.output_text.delta", delta: event.data[:delta].to_s })
+        when :tool_call
+          sse("response.output_item.added",
+              { type: "response.output_item.added",
+                item: { type: "function_call", name: event.data[:name].to_s } })
+        when :task_completed
+          completed(event) + done
+        when :task_failed
+          failed(event.data[:message] || "task failed") + done
+        when :task_cancelled
+          failed("task cancelled") + done
+        when :error
+          failed(event.data[:message] || "error") + done
+        when :thinking
+          # The provider's reasoning. Internal unless the AGENT opted in
+          # (`edge_stream thinking: true`), which tags the event. Even then it does
+          # NOT become answer text: it gets the Responses reasoning frame, so a
+          # consumer that only accumulates `output_text` deltas — achei-b2b's
+          # dispatcher, which turns them into one WhatsApp message — is unaffected,
+          # and one that renders reasoning has something to render.
+          if public_delta(event)
+            sse("response.reasoning_summary_text.delta",
+                { type: "response.reasoning_summary_text.delta", delta: event.data[:delta].to_s })
+          end
+        when :intermediate
+          # The model's own prose that did not turn out to be the answer — the
+          # narration of a message that also called a tool, or the reasoning-in-content
+          # a model emits when it has no tool to call. A real store's prompt sent 132
+          # deltas of an English monologue this way before TurnOutput held them back.
+          #
+          # NAMESPACED on purpose when published. There is no `response.*` event for
+          # "text the assistant said that is not the answer": in the real protocol that
+          # text IS `output_text.delta`, told apart only by an output-item index this
+          # adapter does not carry. So a `response.*` type here would be a lie a strict
+          # client would believe. `insika.*` is obviously ours and unknown types are
+          # ignored — which is the safe failure.
+          if public_delta(event)
+            sse("insika.intermediate.delta",
+                { type: "insika.intermediate.delta", delta: event.data[:delta].to_s })
+          end
+        when :guardrail_blocked, :guardrail_flagged
+          # RFC-0009: audit events with no OpenAI Responses counterpart. On a BLOCK
+          # the safe reply still reaches the consumer through the normal :content
+          # deltas + :task_completed path (the turn completes gracefully), so there
+          # is nothing extra to translate here — the events live in /v1/events + the
+          # Studio + the trace. Explicit (not a fall-through) to keep the closed
+          # catalog honest.
+          nil
+        end
+      end
+
+      # Did the AGENT opt this channel in? The Executor tags the event (`edge_stream`)
+      # because this mapper is pure and static — no agent, no stores, no state. An
+      # untagged event is internal, which is the default and the safe reading — and
+      # "not published" must be nil, like every other unmapped event in the catalog.
+      def public_delta(event) = event.data[:public] == true
+
+      def completed(event)
+        response = {}
+        if (usage = event.data[:usage])
+          # `model` travels alongside usage in the event; in the OpenAI shape it is a sibling of
+          # usage (pure tokens in usage).
+          model = usage[:model] || usage["model"]
+          response[:usage] = usage.reject { |k, _| k.to_s == "model" }
+          response[:model] = model if model
+        end
+        # Opt-in per-turn latency breakdown (INSIKA_TURN_TIMING; item 34). Absent
+        # by default — a non-standard sibling used only for TTFB diagnostics.
+        (timing = event.data[:timing]) && (response[:timing] = timing)
+        sse("response.completed", { type: "response.completed", response: response })
+      end
+
+      def failed(message)
+        sse("response.failed",
+            { type: "response.failed", response: { error: { message: message.to_s } } })
+      end
+
+      # event: + data: (the dispatcher reads both: `event:` and `type` in the JSON).
+      def sse(event_name, data)
+        "event: #{event_name}\ndata: #{JSON.generate(data)}\n\n"
+      end
+
+      def done = "data: [DONE]\n\n"
+    end
+  end
+end

data/lib/insika/server/sse_body.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require "async"
+require "async/queue"
+
+module Insika
+  module Server
+    # SSE response body (evolves `SSEStream`). `SSEStream`
+    # received a producer block (the Runner wrote into it); `SSEBody` DRAINS a
+    # `Subscription` from the EventStream: each subscriber has its
+    # own queue; `#each` blocks the CONSUMER's fiber until the subscription
+    # closes. The wire is EXACTLY `Event#to_h`.
+    class SSEBody
+      PING = ": ping\n\n" # SSE comment — doesn't pollute the consumer
+
+      # serialize: maps an Event -> String (SSE frame) OR nil (discarded
+      # event, no frame). Default = the canonical wire `data: <Event#to_h>`.
+      # The /v1/responses adapter injects a serializer that produces OpenAI
+      # Responses events (and skips those with no counterpart).
+      DEFAULT_SERIALIZE = ->(event) { "data: #{JSON.generate(event.to_h)}\n\n" }
+
+      # subscription: any object with #each (yields Events) and #close.
+      # heartbeat: seconds of silence before emitting a ping (15s
+      # clears 60s ALB/nginx idle timeouts with room to spare).
+      def initialize(subscription:, heartbeat: 15, serialize: nil)
+        @subscription = subscription
+        @heartbeat = heartbeat
+        @serialize = serialize || DEFAULT_SERIALIZE
+      end
+
+      # Rack 3 STREAMING BODY (`#call(stream)`), NOT `#each`. Under
+      # protocol-rack/protocol-http1 (the stack of Async::HTTP::Server AND Falcon),
+      # a body that responds to `#each` is routed to Body::Enumerable, whose
+      # `read` runs the `#each` in a PLAIN Enumerator Fiber (not an Async::Task) —
+      # there `Async::Task.current` raises "No async task available", the loop died
+      # swallowed in the rescue and the body came out EMPTY. By exposing `#call` (and NOT `#each`),
+      # the body is routed to Body::Streaming, which schedules the block via
+      # Fiber.schedule under the reactor's scheduler — so the subscription drains and the
+      # frames actually reach the socket (incrementally).
+      #
+      # The `stream` (Protocol::HTTP::Body::Stream) responds to #write/#close. Drains the
+      # subscription DIRECTLY (no Async::Task.current): when this fiber blocks
+      # waiting for the next event, the scheduler runs the writer, which pushes the
+      # already-written frame to the socket. Heartbeat via Timeout.timeout (scheduler hook),
+      # which works in the scheduled fiber — keeps the connection alive while idle (L4).
+      def call(stream)
+        drain(stream)
+      rescue StandardError
+        # Client disconnected: `stream.write` raises when the socket closes.
+        # No exception escapes; the turn's task is NEVER cancelled here — the
+        # execution belongs to the runtime, not the connection (reconnect at /v1/events).
+        nil
+      ensure
+        @subscription.close
+        stream.close
+      end
+
+      private
+
+      def drain(stream)
+        internal = Async::Queue.new
+        closed = Object.new # end-of-subscription sentinel
+
+        # Child fiber (scheduled on the reactor's scheduler): drains the subscription
+        # into an internal queue and, on close, pushes the sentinel. Isolates the
+        # subscription's blocking from the heartbeat loop. Ends on its own when
+        # `@subscription.close` (in #call's ensure) makes the `each` finish — no
+        # need to kill the fiber by hand.
+        Fiber.schedule do
+          @subscription.each { |event| internal.enqueue(event) }
+        ensure
+          internal.enqueue(closed)
+        end
+
+        loop do
+          event =
+            begin
+              Timeout.timeout(@heartbeat) { internal.dequeue }
+            rescue Timeout::Error
+              :heartbeat # no event within `heartbeat`s -> ping
+            end
+
+          if event.equal?(:heartbeat)
+            stream.write(PING)
+          elsif event.equal?(closed)
+            break
+          elsif (frame = @serialize.call(event))
+            stream.write(frame)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insika/session_actor.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require "time" # Time#iso8601 for the arrival record on :turn_coalesced
+
+module Insika
+  # Sessions as Actors: one fiber per session with a FIFO queue
+  # of turns, executed ONE AT A TIME. Restores the "one owner at a time"
+  # invariant of the transcript that two concurrent `send_message` calls on the
+  # same `session_id` would break (read-modify-write on the Session Store). Turns
+  # from distinct sessions stay concurrent; one-shot/history (no session_id) do
+  # not go through here.
+  #
+  # Lives in the SUPERVISED scope: the loop is a child of the supervisor, not of
+  # the request — it outlives the connection. The turn itself (spawned by the
+  # Executor) is also born on the supervisor; the SessionActor only AWAITS it to
+  # serialize.
+  #
+  # RFC-0015: it is also where an inbound message for a BUSY session is routed.
+  # That decision belongs here and nowhere else — this is already the object that
+  # owns "one turn at a time for this session". Putting it in the HTTP handler
+  # would duplicate the invariant; putting it in the Executor would mix turn
+  # execution with queue policy.
+  class SessionActor
+    def initialize(session_id:, executor:, parent: Async::Task.current)
+      @session_id = session_id
+      @executor = executor
+      @queue = Async::Queue.new
+      @running = false
+      # The turn currently sitting at the door: created and :queued, but not yet
+      # released to run. `collect` merges into THIS one. nil whenever there is
+      # nothing mergeable — which is the common case and the safe default.
+      @pending = nil
+      @loop = parent.async { |t| t.annotate("session:#{session_id}"); run_loop }
+    end
+
+    # Enqueues a turn (FIFO). Non-blocking: the handler responds with an
+    # immediate {task_id:} even if the turn stays :queued behind another. -> task.id.
+    #
+    # `policy` (a QueuePolicy) opens the debounce window for this turn; nil or a
+    # policy without a window behaves exactly as before — dequeued and run at once.
+    def enqueue(task, profile:, resume_from: nil, policy: nil)
+      @queue.enqueue([task, profile, resume_from, policy])
+      task.id
+    end
+
+    # RFC-0015 §5.3 — merge a fragment into the turn waiting at the door.
+    # -> the task id it joined, or nil when there is nothing to merge into (no
+    # pending turn, the window has closed, or the turn already started). nil is
+    # the caller's signal to create a task of its own.
+    #
+    # Runs on the REQUEST's fiber, not the loop's; both are on the same reactor
+    # and neither yields between the check and the write below, so the "is it
+    # still mergeable" test and the append cannot interleave.
+    def collect(text)
+      pending = @pending
+      return nil if pending.nil?
+
+      @executor.task_store.append_message(pending[:task_id], text)
+      pending[:count] += 1
+      # A merged fragment leaves NO task of its own (see #hold_at_the_door), so this
+      # is the only record that it arrived as a separate message. Kept as arrival
+      # times — never the text — and shipped on :turn_coalesced, so "the customer
+      # says they sent the order number" is answerable without the store carrying an
+      # orphan task per fragment.
+      pending[:arrivals] << Time.now.utc.iso8601
+      pending[:version] += 1 # tells a sleeping debounce window that more arrived
+      pending[:task_id]
+    rescue ArgumentError
+      # The turn left :queued between the read of @pending and the append (it was
+      # released while we were deciding). Not an error: the caller falls back to
+      # creating its own task, which is exactly `followup`.
+      nil
+    end
+
+    def running? = @running
+    def depth = @queue.size
+
+    # The turn this session is running RIGHT NOW, or nil when idle or still at the
+    # door. `steer` needs the Task itself and not just its id: whether a turn can
+    # absorb a message at all depends on what kind of turn it is (a workflow has no
+    # chat), and reading that off the object avoids a store round-trip on the
+    # request's path.
+    attr_reader :current_task
+
+    # Is there a turn at the door that `collect` could still merge into?
+    def collecting? = !@pending.nil?
+
+    # Is the loop still alive? (the Executor revalidates before reusing from the
+    # cache — a dead loop would black-hole queued turns).
+    def alive? = !!@loop&.running?
+
+    # Shuts down the loop (server shutdown / tests — the loop blocks forever on
+    # dequeue when idle).
+    def stop = @loop&.stop
+
+    private
+
+    def run_loop
+      loop do
+        task, profile, resume_from, policy = @queue.dequeue # blocks when empty
+        task = hold_at_the_door(task, policy)
+        @running = true
+        @current_task = task
+        begin
+          @executor.run_serial(task, profile: profile, resume_from: resume_from)
+        rescue StandardError
+          # run_serial already maps turn errors; this rescue is defense: an
+          # unexpected error must NEVER bring down the session loop (Async::Stop <
+          # Exception is not captured -> #stop ends the loop normally).
+          nil
+        ensure
+          @running = false
+          @current_task = nil
+        end
+      end
+    end
+
+    # RFC-0015 §5.3 — the debounce window. Sleeps on the LOOP's fiber, never on the
+    # request's, so the POST is acked immediately and the platform does not retry.
+    # Returns the task to run (re-read from the store when fragments merged into it,
+    # since the in-memory Task is a frozen snapshot of an older message).
+    def hold_at_the_door(task, policy)
+      return task unless policy&.debounce?
+
+      @pending = { task_id: task.id, count: 1, version: 0, arrivals: [Time.now.utc.iso8601] }
+      begin
+        wait_for_quiet(policy)
+        merged = @pending[:count]
+        arrivals = @pending[:arrivals]
+      ensure
+        # The window is closed BEFORE the turn runs, under every exit path: a
+        # `collect` that slipped in here would append to a task about to be read.
+        @pending = nil
+      end
+
+      return task if merged == 1
+
+      @executor.emit_coalesced(task, merged: merged, arrivals: arrivals)
+      @executor.task_store.find(task.id) || task
+    end
+
+    # Sleeps in `debounce_ms` slices, restarting whenever a fragment arrives
+    # (`version` moved), until either a slice passes in silence or the total
+    # deferral reaches `debounce_max_ms` — the ceiling that stops a customer who
+    # keeps typing from postponing their own answer forever.
+    def wait_for_quiet(policy)
+      quiet = policy.debounce_ms / 1000.0
+      deadline = monotonic + (policy.debounce_max_ms / 1000.0)
+
+      loop do
+        mark = @pending[:version]
+        Async::Task.current.sleep(quiet)
+        break if @pending[:version] == mark # a full slice of silence
+        break if monotonic >= deadline
+      end
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end