insika 0.0.1 → 0.2.0

data/lib/insika/wiring/graph.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Insika
+  module Wiring
+    # SHARED composition core for both roots: the minimal wiring
+    # (config/wiring.rb) and the concrete deployment (config/deployment.rb) were two
+    # near-identical composition roots. The duplication — backend→stores, event
+    # stream, registries + policy builtins, capability registry, hooks, the Executor,
+    # and the core Command Bus — lives here now; each root only layers on what
+    # legitimately differs (profiles, plain-vs-overlay tool registry, catalogs,
+    # guardrails config, context providers, and the root-specific bus commands).
+    #
+    # Two phases, no magic (a block would hit dynamic-constant assignment in the
+    # roots, which promote everything to public constants):
+    #   1. `spine(backend:)` — the parameter-free infra spine.
+    #   2. `build(spine:, ...)` — assembles the Executor + Command Bus on top, given
+    #      the root's divergent collaborators. This is where the 6 CORE commands
+    #      (incl. pause_task/approve_action) are registered — which is what removes
+    #      the config.ru / serve_real.rb patch that used to bolt them on afterwards.
+    module Graph
+      module_function
+
+      # Backend by config: INSIKA_DB set → durable SQLite (survives restart, the
+      # prerequisite for Recovery); missing → ephemeral Memory (dev/demo). The same
+      # rule lived verbatim in both roots. Dual-read honors the legacy HARNESS_DB alias.
+      def backend_from_env(env = ENV)
+        db = Insika::EnvSchema.read("INSIKA_DB", env)
+        db && !db.empty? ? Insika::Stores::SQLite.new(path: db) : Insika::Stores::Memory.new
+      end
+
+      # an integer tick knob from the env, nil when unset (the caller's
+      # default wins). Dual-read honors the deprecated HARNESS_* alias.
+      def tick_env(name, env = ENV)
+        value = Insika::EnvSchema.read(name, env)
+        value&.to_i
+      end
+
+      # the infra spine that is IDENTICAL across roots. `extra_policy_
+      # builtins` covers the one real divergence (the minimal wiring also registers
+      # :workflow_allowlist; the deployment does not expose workflows).
+      def spine(backend:, extra_policy_builtins: {})
+        session_store        = Insika::SessionStore.new(store: backend)
+        task_store           = Insika::TaskStore.new(store: backend)
+        checkpoint_store     = Insika::CheckpointStore.new(store: backend)
+        pending_action_store = Insika::PendingActionStore.new(store: backend)
+        delegation_store     = Insika::DelegationStore.new(store: backend)
+        memory_store         = Insika::MemoryStore.new(store: backend)
+        token_store          = Insika::TokenStore.new(store: backend)
+        budget_ledger        = Insika::BudgetLedger.new(store: backend)
+        circuit_state        = Insika::CircuitState.new(store: backend)
+        # the two durable halves of a Shape B channel — the
+        # replies still owed to a platform, and the retry window that stops a
+        # redelivered webhook from becoming a second turn. Built unconditionally
+        # (they are empty and free when no channel is registered) so a deployment
+        # that turns a channel on later finds its state already durable.
+        outbox_store         = Insika::OutboxStore.new(store: backend)
+        inbound_log          = Insika::InboundLog.new(store: backend)
+        # refinement RUNS (reports over real traffic). Runtime data,
+        # same backend as sessions/tasks — the collector and the command that write it
+        # are the root's business (deployment-only, like the memory commands).
+        refinement_store     = Insika::RefinementStore.new(store: backend)
+
+        code_tool_registry = Insika::ToolRegistry.new
+        workflow_registry  = Insika::WorkflowRegistry.new
+
+        policy_registry = Insika::PolicyRegistry.new
+        policy_registry.register(:tool_allowlist, Insika::Policy::Builtin::ToolAllowlist)
+        policy_registry.register(:skill_allowlist, Insika::Policy::Builtin::SkillAllowlist)
+        policy_registry.register(:approval_required, Insika::Policy::Builtin::ApprovalRequired)
+        extra_policy_builtins.each { |name, klass| policy_registry.register(name, klass) }
+
+        Spine.new(
+          backend: backend, event_stream: Insika::EventStream.new,
+          session_store: session_store, task_store: task_store,
+          checkpoint_store: checkpoint_store, pending_action_store: pending_action_store,
+          delegation_store: delegation_store,
+          memory_store: memory_store, refinement_store: refinement_store,
+          token_store: token_store, budget_ledger: budget_ledger, circuit_state: circuit_state,
+          outbox_store: outbox_store, inbound_log: inbound_log,
+          code_tool_registry: code_tool_registry,
+          workflow_registry: workflow_registry, policy_registry: policy_registry,
+          capability_registry: Insika::CapabilityRegistry.new, hooks: Insika::Hooks.new,
+          channel_registry: Insika::ChannelRegistry.new
+        )
+      end
+
+      # assemble the graph on top of a spine.
+      #
+      # tool_registry:     effective registry the Executor uses (plain REGISTRY at the
+      #                    base; OverlayToolRegistry in the deployment).
+      # guardrails:        a Safety::Factory — its input_guardrail becomes the single
+      #                    middleware and its output_validator the after-task hook, so
+      #                    both wirings compose identically.
+      # executor_extra:    optional Executor kwargs a root adds (deployment passes
+      #                    settings_store + tool_trace_store; the base passes none).
+      # edge_limiter:      optional EdgeLimiter. It goes BEFORE
+      #                    the InputGuardrail so a flood can't spend the LLM
+      #                    moderator; nil = no edge (parity).
+      def build(spine:, profiles:, tool_registry:, tool_catalog:, skill_catalog:,
+                prompt_catalog:, guardrails:, context_providers:, edge_limiter: nil,
+                executor_extra: {})
+        spine.hooks.register(:task, after: guardrails.output_validator)
+        middleware = Insika::MiddlewareStack.new([edge_limiter, guardrails.input_guardrail].compact)
+
+        context_builder = Insika::ContextBuilder.new(
+          providers: context_providers, event_stream: spine.event_stream, hooks: spine.hooks
+        )
+        policy_engine = Insika::Policy::Engine.new(
+          policy_registry: spine.policy_registry, event_stream: spine.event_stream
+        )
+
+        # Always built: the registry starts empty, so `record` finds no
+        # channel and returns nil on every turn — the cost of wiring it is one nil
+        # check per completed turn, and the alternative is a second wiring path that
+        # only production exercises.
+        channel_delivery = Insika::ChannelDelivery.new(
+          channels: spine.channel_registry, outbox: spine.outbox_store,
+          session_store: spine.session_store, event_stream: spine.event_stream
+        )
+
+# WS3 provider reliability (retries/backoff/fallback/breaker) is ALWAYS wired —
+      # the profile's `reliability` data gates it, so the bare wiring is unchanged.
+      reliability = Insika::Reliability.new(circuit_store: spine.circuit_state,
+                                            event_stream: spine.event_stream)
+      executor = Insika::Executor.new(
+        context_builder: context_builder, policy_engine: policy_engine,
+        middleware: middleware, hooks: spine.hooks,
+        tool_registry: tool_registry, skill_catalog: skill_catalog, profiles: profiles,
+        session_store: spine.session_store, task_store: spine.task_store,
+        checkpoint_store: spine.checkpoint_store, event_stream: spine.event_stream,
+        workflow_registry: spine.workflow_registry, pending_action_store: spine.pending_action_store,
+        capability_registry: spine.capability_registry, tool_catalog: tool_catalog,
+        memory_store: spine.memory_store,
+        content_filter_factory: guardrails.content_filter_factory, # stream redaction
+        delegation_store: spine.delegation_store, # async delegation durability
+        channel_delivery: channel_delivery, # out-of-band reply delivery
+        reliability: reliability, # WS3: retries/fallback/breaker (data-gated)
+        **executor_extra
+      )
+
+        bus = build_core_bus(spine: spine, profiles: profiles, executor: executor)
+
+        # the periodic tick (outbox drain + stale recovery sweep). Built
+        # here, after the bus, because its recovery half dispatches resume_task
+        # through it; handed to the Executor, which starts it as a child of the
+        # turn supervisor in serving mode. `INSIKA_TICK_INTERVAL=0` disables.
+        executor.tick = Insika::Tick.new(
+          store: spine.backend, channel_delivery: channel_delivery,
+          recovery: Insika::Recovery.new(
+            task_store: spine.task_store, checkpoint_store: spine.checkpoint_store, command_bus: bus
+          ),
+          interval: tick_env("INSIKA_TICK_INTERVAL") || Insika::Tick::DEFAULT_INTERVAL,
+          stale_after: tick_env("INSIKA_TICK_STALE_AFTER") || Insika::Tick::DEFAULT_STALE_AFTER
+        )
+        # WS6 operator alerts: answers budget_warning / breaker_open /
+        # delivery_failed per agent (`alerts.webhook`) via the outbox+claim
+        # pipeline. Always wired — the per-agent data gates it (parity).
+        executor.alert_dispatcher = Insika::AlertDispatcher.new(
+          event_stream: spine.event_stream, outbox: spine.outbox_store,
+          channels: spine.channel_registry, profiles: profiles,
+          task_store: spine.task_store, http: Insika::HttpClient.new
+        )
+
+        Graph::Result.new(
+          backend: spine.backend, event_stream: spine.event_stream,
+          session_store: spine.session_store, task_store: spine.task_store,
+          checkpoint_store: spine.checkpoint_store, pending_action_store: spine.pending_action_store,
+          delegation_store: spine.delegation_store,
+          memory_store: spine.memory_store, refinement_store: spine.refinement_store,
+          outbox_store: spine.outbox_store, inbound_log: spine.inbound_log,
+          token_store: spine.token_store, budget_ledger: spine.budget_ledger,
+          circuit_state: spine.circuit_state,
+          channel_registry: spine.channel_registry, channel_delivery: channel_delivery,
+          code_tool_registry: spine.code_tool_registry,
+          tool_registry: tool_registry, workflow_registry: spine.workflow_registry,
+          policy_registry: spine.policy_registry, capability_registry: spine.capability_registry,
+          tool_catalog: tool_catalog, skill_catalog: skill_catalog, prompt_catalog: prompt_catalog,
+          hooks: spine.hooks, guardrails: guardrails, middleware: middleware,
+          context_providers: context_providers, context_builder: context_builder,
+          policy_engine: policy_engine, profiles: profiles, executor: executor, bus: bus
+        )
+      end
+
+      # The CORE command surface every root needs — turn essentials + the operator
+      # controls (pause/approve) the Studio dispatches. Registering pause_task/
+      # approve_action HERE is the crux of: it retires the config.ru:28-34 patch.
+      def build_core_bus(spine:, profiles:, executor:)
+        bus = Insika::CommandBus.new
+        bus.register(:create_session,
+                     Insika::Commands::CreateSession.new(session_store: spine.session_store, event_stream: spine.event_stream))
+        bus.register(:cancel_task,
+                     Insika::Commands::CancelTask.new(task_store: spine.task_store, executor: executor))
+        bus.register(:pause_task,
+                     Insika::Commands::PauseTask.new(task_store: spine.task_store, executor: executor))
+        bus.register(:approve_action,
+                     Insika::Commands::ApproveAction.new(pending_action_store: spine.pending_action_store,
+                                                          executor: executor, event_stream: spine.event_stream))
+        bus.register(:send_message,
+                     Insika::Commands::SendMessage.new(profiles: profiles, session_store: spine.session_store,
+                                                        task_store: spine.task_store, executor: executor,
+                                                        inbound_log: spine.inbound_log))
+        bus.register(:resume_task,
+                     Insika::Commands::ResumeTask.new(profiles: profiles, task_store: spine.task_store,
+                                                       checkpoint_store: spine.checkpoint_store, executor: executor))
+        # WS1 multi-tenant credentials: per-tenant + operator tokens, stored as
+        # hashes. Operator-only BY CONSTRUCTION — the edge refuses a tenant
+        # principal on POST /v1/commands, and the handlers re-check meta.
+        bus.register(:issue_tenant_token,
+                     Insika::Commands::IssueTenantToken.new(token_store: spine.token_store,
+                                                            event_stream: spine.event_stream))
+        bus.register(:revoke_token,
+                     Insika::Commands::RevokeToken.new(token_store: spine.token_store,
+                                                       event_stream: spine.event_stream))
+        bus.register(:rotate_tenant_token,
+                     Insika::Commands::RotateTenantToken.new(token_store: spine.token_store,
+                                                             event_stream: spine.event_stream))
+        bus
+      end
+
+      # Infra spine (phase 1 output). Value object — the roots read these to promote
+      # them to their historic public constants (SESSION_STORE, REGISTRY, ...).
+      Spine = Struct.new(
+        :backend, :event_stream, :session_store, :task_store, :checkpoint_store,
+        :pending_action_store, :delegation_store, :memory_store, :refinement_store,
+        :token_store, :budget_ledger, :circuit_state, :outbox_store, :inbound_log, :code_tool_registry,
+        :workflow_registry, :policy_registry, :capability_registry, :hooks,
+        :channel_registry, keyword_init: true
+      )
+
+      # Full graph (phase 2 output). `code_tool_registry` is the plain code registry
+      # (REGISTRY); `tool_registry` is the effective one the Executor uses (the
+      # deployment's overlay, or the same code registry at the base).
+      Result = Struct.new(
+        :backend, :event_stream,
+        :session_store, :task_store, :checkpoint_store, :pending_action_store, :delegation_store,
+        :memory_store, :refinement_store, :outbox_store, :inbound_log, :token_store,
+        :budget_ledger, :circuit_state, :channel_registry, :channel_delivery,
+        :code_tool_registry, :tool_registry, :workflow_registry, :policy_registry, :capability_registry,
+        :tool_catalog, :skill_catalog, :prompt_catalog,
+        :hooks, :guardrails, :middleware,
+        :context_providers, :context_builder, :policy_engine,
+        :profiles, :executor, :bus,
+        keyword_init: true
+      ) do
+        def durable? = backend.is_a?(Insika::Stores::SQLite)
+      end
+    end
+  end
+end

data/lib/insika/workflow.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Insika
+  # Workflow surface (COMPETITIVE-ANALYSIS). A workflow is a Ruby
+  # callable orchestrating RubyLLM Agents/Workflows FROM WITHIN (RubyLLM First);
+  # its durable RUN is a Task (checkpointed, recoverable — stronger than Flue's
+  # at-most-once run record). This module adds the EXPOSED surface the consumer
+  # asked for, matching the honest Flue scope (not Temporal):
+  #   · runId          — the run id (== task id; the Task IS the run record).
+  #   · event stream   — :workflow_started / :workflow_completed on the task stream.
+  #   · I/O by schema  — optional input_schema / output_schema validated at the edges.
+  #
+  # A schema is any dry-schema-compatible validator: `#call(value)` returning a
+  # result that responds to `#success?` and `#errors` (dry-schema's own contract).
+  # As a batteries-included default, a plain JSON Schema Hash (the interlingua the
+  # ToolDefinition already speaks) is accepted and validated by the zero-dependency
+  # Schema below — "config over convention": bring dry-schema for richer contracts,
+  # or hand a JSON Schema for the common case.
+  module Workflow
+    # Bundles a registered workflow's callable factory with its metadata (schemas +
+    # description). Built lazily by WorkflowRegistry#definition — it does NOT resolve
+    # the factory (the Executor resolves inside the fiber; the contract forbids
+    # instantiating outside it). Schema validation touches only the schemas.
+    Definition = Data.define(:name, :description, :input_schema, :output_schema, :factory) do
+      # Raises WorkflowSchemaError (< ValidationError) when the input does not
+      # conform. No-op without an input_schema (parity). Called synchronously by
+      # TriggerWorkflow -> a bad input is a 422 with no run created.
+      def validate_input!(input) = enforce!(input_schema, input, :input)
+
+      # Raises WorkflowSchemaError when the RETURN does not conform. No-op without an
+      # output_schema. Called inside the fiber after the workflow returns -> a bad
+      # output fails the run at the :workflow_schema stage.
+      def validate_output!(output) = enforce!(output_schema, output, :output)
+
+      # Resolves the factory (INSIDE the fiber) and invokes the orchestrator with the
+      # canonical signature `#call(input, context:, tools:)`.
+      def call(input, context:, tools:)
+        factory.call.call(input, context: context, tools: tools)
+      end
+
+      # Discovery view (GET /v1/workflows): name + description + the I/O contract.
+      # A JSON-Schema-backed schema exposes its schema Hash; a duck-typed validator
+      # (dry-schema etc.) is opaque to introspection -> "opaque".
+      def catalog_entry
+        {
+          "name" => name,
+          "description" => description,
+          "input_schema" => schema_view(input_schema),
+          "output_schema" => schema_view(output_schema)
+        }
+      end
+
+      private
+
+      def enforce!(schema, value, phase)
+        return if schema.nil?
+
+        result = schema.call(value)
+        return if result.success?
+
+        raise Insika::WorkflowSchemaError.new(
+          "workflow '#{name}' #{phase}", phase: phase, errors: normalize_errors(result.errors)
+        )
+      end
+
+      # dry-schema returns a MessageSet (responds to #to_h); the built-in Schema
+      # already returns a Hash.
+      def normalize_errors(errors) = errors.respond_to?(:to_h) ? errors.to_h : errors
+
+      def schema_view(schema)
+        return nil if schema.nil?
+
+        schema.respond_to?(:json_schema) ? schema.json_schema : "opaque"
+      end
+    end
+
+    # Zero-dependency instance validator for a plain JSON Schema Hash, speaking the
+    # same safe subset (object/array/string/number/integer/boolean + enum) the
+    # ToolDefinition validates its parameters against. It implements the SAME
+    # `#call(value) -> result{#success?, #errors}` contract as dry-schema, so the
+    # Definition treats both uniformly. Not a full JSON Schema engine (no
+    # composition/$ref — the subset the insika supports everywhere); permissive on
+    # unknown keys (JSON Schema's additionalProperties default).
+    class Schema
+      # dry-schema-compatible result. `errors` is { "field.path" => ["message", …] }.
+      Result = Data.define(:errors) do
+        def success? = errors.empty?
+      end
+
+      # nil -> nil; a callable (dry-schema / proc) -> as-is; a JSON Schema Hash ->
+      # wrapped. Idempotent for an existing Schema (it is callable).
+      def self.coerce(schema)
+        return nil if schema.nil?
+        return schema if schema.respond_to?(:call)
+
+        new(schema)
+      end
+
+      attr_reader :json_schema
+
+      def initialize(json_schema)
+        unless json_schema.is_a?(Hash)
+          raise Insika::ValidationError, "workflow schema must be a JSON Schema object or a #call-able validator"
+        end
+
+        @json_schema = Insika::Coercion.deep_stringify(json_schema)
+      end
+
+      def call(value)
+        Result.new(errors: collect(@json_schema, value, "").freeze)
+      end
+
+      private
+
+      # -> { path => [messages] }. Empty = valid.
+      def collect(schema, value, path)
+        type = schema["type"].to_s
+        return { key(path) => ["must be #{type}, got #{ruby_type(value)}"] } unless type.empty? || matches?(type, value)
+
+        errors = {}
+        case type
+        when "object" then check_object(schema, value, path, errors)
+        when "array"  then check_array(schema, value, path, errors)
+        end
+        check_enum(schema, value, path, errors)
+        errors
+      end
+
+      def check_object(schema, value, path, errors)
+        props = schema["properties"] || {}
+        Array(schema["required"]).each do |name|
+          errors[key(join(path, name))] = ["is required"] unless value.key?(name.to_s) || value.key?(name.to_sym)
+        end
+        props.each do |name, subschema|
+          next unless value.key?(name.to_s) || value.key?(name.to_sym)
+
+          sub = value[name.to_s] || value[name.to_sym]
+          errors.merge!(collect(subschema || {}, sub, join(path, name)))
+        end
+      end
+
+      def check_array(schema, value, path, errors)
+        items = schema["items"]
+        return if items.nil?
+
+        value.each_with_index { |el, i| errors.merge!(collect(items, el, "#{join(path, i)}")) }
+      end
+
+      def check_enum(schema, value, path, errors)
+        return unless schema.key?("enum")
+
+        allowed = Array(schema["enum"])
+        errors[key(path)] = ["must be one of #{allowed.inspect}"] unless allowed.include?(value)
+      end
+
+      def matches?(type, value)
+        case type
+        when "object"  then value.is_a?(Hash)
+        when "array"   then value.is_a?(Array)
+        when "string"  then value.is_a?(String)
+        when "integer" then value.is_a?(Integer) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+        when "number"  then value.is_a?(Numeric) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+        when "boolean" then value == true || value == false
+        else true # unknown type in the schema -> do not block (permissive)
+        end
+      end
+
+      def ruby_type(value)
+        case value
+        when Hash then "object"
+        when Array then "array"
+        when String then "string"
+        when Integer then "integer"
+        when Numeric then "number"
+        when true, false then "boolean"
+        when nil then "null"
+        else value.class.name.downcase
+        end
+      end
+
+      def join(path, segment) = path.empty? ? segment.to_s : "#{path}.#{segment}"
+      def key(path) = path.empty? ? "(root)" : path
+    end
+  end
+end

data/lib/insika/workflow_registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Insika
+  # Workflow registry. A workflow is a Ruby callable with the signature
+  # `#call(input, context:, tools:)` that orchestrates RubyLLM Agents/Workflows FROM
+  # WITHIN (RubyLLM First): `context:` is the ContextPackage, `tools:` are
+  # instances already filtered by the Resolution. Execution = one logical turn;
+  # checkpoint at the end. Nothing is validated at registration (the callable may come
+  # via a factory block). Consumed by the TriggerWorkflow handler.
+  #
+  # — the EXPOSED surface: a registration may carry `input_schema:` /
+  # `output_schema:` (a JSON Schema Hash or any dry-schema-compatible validator) and a
+  # `description:` in its metadata. `definition` bundles them with the factory into a
+  # Workflow::Definition (schemas resolved, factory left lazy); `catalog` is the
+  # discovery view (GET /v1/workflows).
+  class WorkflowRegistry < Registry
+    # -> Workflow::Definition (does NOT resolve the factory — the Executor resolves
+    # inside the fiber). Raises NotFoundError for an unregistered name.
+    def definition(name)
+      e = entry(name)
+      Insika::Workflow::Definition.new(
+        name: e.name,
+        description: e.metadata[:description],
+        input_schema: Insika::Workflow::Schema.coerce(e.metadata[:input_schema]),
+        output_schema: Insika::Workflow::Schema.coerce(e.metadata[:output_schema]),
+        factory: e.factory
+      )
+    end
+
+    # Discovery: [{ "name", "description", "input_schema", "output_schema" }, …].
+    def catalog = entries.map { |e| definition(e.name).catalog_entry }
+  end
+end