insika 0.1.0 → 0.3.0

data/lib/insika/tick.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The periodic tick: durability stops waiting for a reboot. One
+  # pass does two things, in this order:
+  #
+  #   1. DRAIN the outbox (`ChannelDelivery#sweep`) — replies a previous pass
+  #      (or process) recorded and never claimed. Ungated: every record carries
+  #      its own transactional claim, so N workers draining is safe.
+  #   2. SWEEP stale orphaned tasks (`Recovery#run(stale_after:)`) — gated by a
+  #      bucketed claim (`Recovery.claim_sweep` on "tick:<epoch/interval>"), so
+  #      exactly one worker per window sweeps. The staleness threshold is the
+  #      liveness gate: a live :running turn is bounded by turn_timeout, so
+  #      anything untouched past it cannot be alive.
+  #
+  # It is NOT a job queue: no schedules, no priorities, no fan-out. The
+  # refinement hook once pictured here is dropped by merit —
+  # docs/REFINEMENT.md's "no scheduler in the engine" stands.
+  class Tick
+    # 60s: a customer waiting on WhatsApp is the deadline. 900s = 3x the
+    # default turn_timeout (300s) — the rule, not the number: the threshold
+    # must exceed the deployment's largest turn_timeout, or the sweep would
+    # judge live turns orphaned.
+    DEFAULT_INTERVAL = 60
+    DEFAULT_STALE_AFTER = 900
+
+    SCOPE = "tick"
+    KEY = "claim"
+
+    def initialize(store:, recovery:, channel_delivery:, logger: nil,
+                   interval: DEFAULT_INTERVAL, stale_after: DEFAULT_STALE_AFTER,
+                   sleeper: nil, retention: nil, funnel: nil, followup: nil)
+      @store = store
+      @recovery = recovery
+      @channel_delivery = channel_delivery
+      @logger = logger
+      @interval = interval.to_i
+      @stale_after = stale_after.to_i
+      @sleeper = sleeper || method(:default_sleep)
+      @retention = retention # WS8: the daily age-based sweep; nil = none
+      @funnel = funnel # the tick-driven outcome fold; nil = none
+      @followup = followup # the tick-driven follow-up firer; nil = none
+    end
+
+    # the fold is wired after the Tick is built (the graph passes
+    # it to `executor.tick.funnel =` — the outcome/funnel stores come from the
+    # spine). Setter + kwarg: same shape as `retention`.
+    attr_accessor :funnel
+
+    # the follow-up firer, wired after the Tick is built (same
+    # shape as `funnel` — the stores come from the spine).
+    attr_accessor :followup
+
+    def enabled? = @interval.positive?
+
+    # One pass, pure (no reactor needed): the serving loop calls it on a timer,
+    # specs call it directly. A StoreError propagates to the loop, which logs
+    # and keeps ticking.
+    def run_once
+      drained = @channel_delivery ? @channel_delivery.sweep : { dispatched: [] }
+      summary = { dispatched: drained[:dispatched], resumed: [], failed: [] }
+      # WS8 retention: cheap when not claimed (its own daily window) — the
+      # O(n) scans never ride the 60 s loop.
+      retention_summary = @retention&.run
+      summary[:retention] = retention_summary if retention_summary
+      # the outcome fold — one pass per claim window, cheap
+      # when another worker holds it. Sits next to retention, on the same tick.
+      funnel_summary = @funnel&.run
+      summary[:funnel] = funnel_summary if funnel_summary
+      # the follow-up firer — the tick's third duty, gated by its
+      # OWN claim window so the O(n) scans never ride the 60 s loop.
+      followup_summary = @followup&.run
+      summary[:followup] = followup_summary if followup_summary
+      return summary unless claim_window
+
+      result = @recovery.run(stale_after: @stale_after)
+      summary.merge(resumed: result[:resumed], failed: result[:failed])
+    end
+
+    # The loop, spawned as a child of the turn supervisor (the
+    # tick lives on the supervisor fiber — every serving arm gets it the moment
+    # `supervised = true` matters, with no arm edits). A failing pass logs and
+    # the loop continues: a sweeper that dies silently is the outage it exists
+    # to prevent. Restartable: when the supervisor is recreated its children
+    # died with it, so a stopped task is not a running one.
+    def start(parent:)
+      return false unless enabled?
+      return true if @task&.running?
+
+      @task = parent.async do |t|
+        t.annotate("insika-tick")
+        loop do
+          @sleeper.call(@interval)
+          run_once
+        rescue StandardError => e
+          log(:warn, "tick failed: #{e.class}: #{e.message}")
+        end
+      end
+      true
+    end
+
+    private
+
+    # One sweeper per window across N workers. Unlike the boot
+    # claim (one key per generation), the tick reuses a SINGLE key with a
+    # timestamp — a key per minute would be a slow leak in the store. The
+    # read-check-write rides Store#transaction like every claim:
+    # two workers racing the window serialize on the backend's lock and exactly
+    # one sweeps.
+    def claim_window
+      now = Time.now.utc
+      @store.transaction do
+        current = @store.get(SCOPE, KEY)
+        last = current && begin
+          Time.iso8601(current["claimed_at"].to_s)
+        rescue ArgumentError
+          nil # a corrupted claim is not a claim — take the window
+        end
+        if last.nil? || (now - last) >= @interval
+          @store.set(SCOPE, KEY, { "claimed_at" => now.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Async when there is a reactor (production: the interval must not block
+    # the worker), plain sleep otherwise (specs driving the loop by hand use an
+    # injected sleeper anyway).
+    def default_sleep(seconds)
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      task ? task.sleep(seconds) : sleep(seconds)
+    end
+
+    # Same contract as Recovery's: logging is pure observability and must never
+    # alter the flow.
+    def log(level, message)
+      @logger&.public_send(level, "[tick] #{message}")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/insika/token_store.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "time"
+
+module Insika
+  # Multi-tenant credentials (WS1): per-tenant tokens plus the operator token,
+  # stored ONLY as SHA-256 hashes — the plaintext is returned once at issue time
+  # and is never persisted, logged or evented. Every resolution is a hash lookup,
+  # so reading the store yields nothing usable. Behind any Insika::Store, like
+  # the other domain stores.
+  #
+  # A record describes ONE principal the edge can resolve a Bearer to:
+  #   role:      "operator" (tenant_id nil — the historical single credential)
+  #              "tenant"   (scoped to tenant_id)
+  #   status:    "active" | "revoked"
+  # A revoked record stops resolving immediately; a tenant's rotation is
+  # revoke-all + issue (the spec's rule — revoking one tenant's token never
+  # touches another tenant's: every cell is (id)- or (hash)-scoped cells).
+  class TokenStore
+    SCOPE = "tenant_tokens"
+
+    Record = Data.define(:id, :token_hash, :role, :tenant_id, :label,
+                         :status, :created_at, :revoked_at) do
+      def active? = status.to_s == "active"
+      def tenant? = role.to_s == "tenant"
+      def to_h
+        { id: id, role: role, tenant_id: tenant_id, label: label,
+          status: status, created_at: created_at, revoked_at: revoked_at }
+      end
+    end
+
+    # The token a caller receives from a successful issue/rotate — the ONLY
+    # moment the plaintext exists in the process. `token` is never stored.
+    Issue = Data.define(:id, :token)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Issues a token for tenant_id (nil = an OPERATOR token). -> Issue. The
+    # token is shown exactly once; there is no `get_token` — lost = rotate.
+    def issue(tenant_id: nil, label: "default")
+      validate_tenant_id!(tenant_id)
+      token = SecureRandom.hex(32)
+      hash = digest(token)
+      id = SecureRandom.uuid
+      @store.transaction do
+        @store.set(SCOPE, record_key(id), {
+                     "id" => id, "token_hash" => hash,
+                     "role" => tenant_id ? "tenant" : "operator",
+                     "tenant_id" => tenant_id, "label" => label.to_s,
+                     "status" => "active",
+                     "created_at" => Time.now.utc.iso8601, "revoked_at" => nil
+                   })
+        @store.set(SCOPE, hash_key(hash), id)
+      end
+      Issue.new(id: id, token: token)
+    end
+
+    # Active-token record for token_id; a revoked one reads WHO it was but not
+    # as resolvable. -> Record | nil.
+    def find(id)
+      return nil if id.to_s.empty?
+
+      record = @store.get(SCOPE, record_key(id.to_s))
+      record && to_record(record)
+    end
+
+    # The edge resolution: -> Record (active) | nil. A revoked token is
+    # indistinguishable from a missing one (fail-closed: the Bearer just 401s).
+    def resolve(token)
+      return nil if token.to_s.empty?
+
+      id = @store.get(SCOPE, hash_key(digest(token)))
+      return nil if id.nil?
+
+      record = to_record(@store.get(SCOPE, record_key(id)))
+      record&.active? ? record : nil
+    end
+
+    # -> bool: true only for an ACTIVE record (revoking an already-revoked/unknown
+    # id is false — a no-op, never an error). The read-modify-write rides
+    # `@store.transaction` (the repo's rule — WS1): `next false`, NOT `return
+    # false`, or the non-local return would skip the COMMIT and leak the open
+    # transaction (the same trap as the budget ledger's mark_alert).
+    def revoke(id)
+      @store.transaction do
+        record = find(id)
+        next false unless record&.active?
+
+        flipped = record.to_h.merge(status: "revoked", revoked_at: Time.now.utc.iso8601)
+        @store.set(SCOPE, record_key(id), stringify(flipped))
+        true
+      end
+    end
+
+    # Revokes every ACTIVE token of a tenant; the hash-index cells stay (they
+    # resolve to a revoked record -> nil). -> count of records revoked. Does NOT
+    # touch the operator token or any other tenant.
+    def revoke_all(tenant_id:)
+      ids = active_token_ids.select do |id|
+        record = to_record(@store.get(SCOPE, record_key(id)))
+        record&.tenant? && record.tenant_id.to_s == tenant_id.to_s
+      end
+      ids.count { |id| revoke(id) }
+    end
+
+    # Rotation: revoke the tenant's active tokens, issue a fresh one. Both in
+    # one transaction -> a crashed half-rotation never leaves the tenant with
+    # NOTHING valid. -> { revoked: n, issue: Issue }.
+    def rotate(tenant_id:, label: "default", now: Time.now)
+      @store.transaction do
+        revoked = revoke_all(tenant_id: tenant_id)
+        { revoked: revoked, issue: issue(tenant_id: tenant_id, label: label) }
+      end
+    end
+
+    # Every active token id (used by revoke_all). Reads the id-keyed cells.
+    def active_token_ids
+      @store.list(SCOPE, RECORD_PREFIX).filter_map do |key|
+        id = key.delete_prefix(RECORD_PREFIX)
+        record = @store.get(SCOPE, record_key(id))
+        record && record["status"] == "active" ? id : nil
+      end
+    end
+
+    private
+
+    # The tenant id IS the session/task namespace prefix ("<tenant>:<id>" — WS1).
+    # A ":" lets a second tenant forge an id that lands on the FIRST tenant's
+    # namespace: T1="loja" + session id "adma:x" => "loja:adma:x", which is the
+    # cell T2="loja:adma" would claim with id "x" (WS1). Guarded at the single
+    # chokepoint both issue and rotate flow through.
+    def validate_tenant_id!(tenant_id)
+      return if tenant_id.nil?
+
+      raise Insika::ValidationError, "tenant_id is required" if Insika::Coercion.blank?(tenant_id)
+      raise Insika::ValidationError, "tenant_id must not contain ':'" if tenant_id.to_s.include?(":")
+    end
+
+    def digest(token)
+      Digest::SHA256.hexdigest(token)
+    end
+
+    RECORD_PREFIX = "r:"
+    HASH_PREFIX = "h:"
+
+    def record_key(id) = "#{RECORD_PREFIX}#{id}"
+    def hash_key(hash) = "#{HASH_PREFIX}#{hash}"
+
+    def to_record(record)
+      return nil if record.nil?
+
+      Record.new(
+        id: record["id"], token_hash: record["token_hash"],
+        role: record["role"], tenant_id: record["tenant_id"],
+        label: record["label"], status: record["status"],
+        created_at: record["created_at"], revoked_at: record["revoked_at"]
+      )
+    end
+
+    def stringify(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+  end
+end

data/lib/insika/tool_assembly.rb

@@ -6,10 +6,10 @@ require "async/semaphore"
 module Insika
   # Turn-scoped assembly of the agent's tool instances (pipeline stage 3 tail):
   # capability resolution, instantiation (Entry#factory | ready instance),
-  # turn-context (D2) injection, the capability<->direct dedup join, and the
+  # turn-context injection, the capability<->direct dedup join, and the
   # ToolEnvelope wrap (stage 7 seam: per-call timeout + side-effect recording).
   #
-  # Extracted from the Executor (§11 B5) to keep the hot-path file smaller. It is
+  # Extracted from the Executor to keep the hot-path file smaller. It is
   # a pure collaborator — it holds only the injected registries/stores and no
   # per-turn state; everything turn-specific arrives via `state`/`turn_context`.
   # The Executor keeps thin delegators (resolve_capabilities/assemble_tool_instances/
@@ -84,7 +84,7 @@ module Insika
 
     private
 
-    # D4 (item 30): the model decides the fan-out, so without a cap a batch of 15
+    # the model decides the fan-out, so without a cap a batch of 15
     # data-tools is 15 simultaneous requests to the same upstream — which is how
     # one turn earns a 429 for every other turn in the process. Note the contrast
     # with the primitives that already shipped: `spawn_subagents` caps at 8
@@ -103,7 +103,7 @@ module Insika
     end
 
     # Real Engine -> Entries (respond to factory); fakes -> ready instances.
-    # `turn_context` (D2) is deposited into the instances that expose it
+    # `turn_context` is deposited into the instances that expose it
     # (data-tools); the rest ignore it (parity).
     def instantiate_tools(allowed, turn_context = nil)
       Array(allowed).map do |t|
@@ -113,7 +113,7 @@ module Insika
       end
     end
 
-    # D2/G3 seam: deposits the turn context into the freshly created instance
+    # seam: deposits the turn context into the freshly created instance
     # (same idea as `remember`, which receives tenant/state) BEFORE the
     # ToolEnvelope. Duck-typed: only what exposes `turn_context=` (DataDefinedTool)
     # receives it. nil (a state with no turn_context, e.g. a test stub) -> no-op.

data/lib/insika/tool_definition.rb

@@ -7,8 +7,8 @@ module Insika
   # Definition of a DATA-DEFINED TOOL (no Ruby code): name, description, parameters
   # and an HTTP call. Immutable value object, persisted by ToolStore and
   # materialized at runtime by Tools::DataDefinedTool (one class, N instances —
-  # the same pattern as A2ARemote). Phase 5, Step A; parameters migrated to JSON
-  # Schema in Phase 7, Step A.
+  # the same pattern as A2ARemote).,; parameters migrated to JSON
+  # Schema in,.
   #
   # Persisted form (JSON-serializable Hash; ConfigStore stringifies the keys):
   #   { "name", "description",
@@ -17,9 +17,9 @@ module Insika
   #     "response"   => { "extract","path" },
   #     "secret_headers" => [ "Authorization", ... ],
   #     "side_effect" => bool, "timeout" => int|nil,
-  #     "group" => string|nil, "tags" => [ "b2b", ... ] }  # Phase 7/D4/F5 (Step C)
+  #     "group" => string|nil, "tags" => ["b2b",...] }  #//
   #
-  # `parameters` is **JSON Schema** (the interlingua of OpenAI/Anthropic/MCP; Phase 7/D1):
+  # `parameters` is **JSON Schema** (the interlingua of OpenAI/Anthropic/MCP):
   # a nestable object, fed straight into RubyLLM's `params_schema` (provider-
   # agnostic). The **flat array** (`[{name,type,required}]`) is SUGAR for the simple
   # case: it is lifted to JSON Schema at build time. The sugar covers scalars and
@@ -30,11 +30,12 @@ module Insika
   # Validation lives HERE (single source): `build`/`from_h` raise ValidationError
   # on malformed input. Name uniqueness and collision with a code tool are NOT
   # validated here (the value object does not know the registry) — that belongs to the
-  # overlay (Step B). Secrets (credential headers) are the ToolStore's responsibility
+  # overlay. Secrets (credential headers) are the ToolStore's responsibility
   # (masks/reconciles); the definition itself is agnostic to masking.
   ToolDefinition = Data.define(
     :name, :description, :parameters, :request, :response,
-    :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when
+    :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when,
+    :evidence                       # Insika::Evidence::Spec | nil
   )
 
   class ToolDefinition
@@ -46,17 +47,17 @@ module Insika
     ARRAY_SUGAR = PARAM_TYPES.map { |t| "array:#{t}" }.freeze
     HTTP_METHODS = %w[GET HEAD POST PUT PATCH DELETE].freeze
     IDEMPOTENT = %w[GET HEAD].freeze              # side_effect default = false
-    EXTRACTS = %w[body_raw status json_path].freeze
+    EXTRACTS = %w[body_raw status json_path evidence_envelope].freeze
     NAME_RE = /\A[a-z][a-z0-9_]*\z/               # identifier for the model
     # A `.` in the placeholder enables the turn-context namespace `{{ctx.*}}`
-    # (Phase 6/D2), separate from the model's `{{param}}`. Params follow NAME_RE (no
+    # separate from the model's `{{param}}`. Params follow NAME_RE (no
     # dot) -> a placeholder with a dot can only be a ctx ref.
     PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/
     # Turn-context namespace: values coming from the TURN (not the model),
     # resolved by DataDefinedTool. Closed allowlist (a typo becomes a validation
     # error, not a silently empty header).
     CTX_PREFIX = "ctx."
-    CTX_FIELDS = %w[chat_id store_id agent_id tenant].freeze
+    CTX_FIELDS = %w[chat_id store_id agent_id tenant image_url].freeze
 
     # ---- safe subset of JSON Schema (R1) --------------------------------------
     # Types supported by EVERY provider (OpenAI/Anthropic/Gemini/DeepSeek/Bedrock).
@@ -74,7 +75,7 @@ module Insika
     # `parameters` accepts JSON Schema (Hash) OR the legacy flat array.
     def self.build(name:, description:, request:, parameters: nil, response: nil,
                    secret_headers: nil, side_effect: nil, timeout: nil, group: nil, tags: nil,
-                   halt_when: nil)
+                   halt_when: nil, evidence: nil)
       name = name.to_s
       raise Insika::ValidationError, "name must match #{NAME_RE.inspect}" unless NAME_RE.match?(name)
 
@@ -84,6 +85,10 @@ module Insika
       schema = normalize_params(parameters)
       req = normalize_request(request, top_level_names(schema))
       resp = normalize_response(response)
+      if resp[:extract] == "evidence_envelope" && evidence.nil?
+        raise Insika::ValidationError,
+              "extract 'evidence_envelope' requires an 'evidence' declaration"
+      end
 
       method = req[:method]
       effect = side_effect.nil? ? !IDEMPOTENT.include?(method) : (side_effect ? true : false)
@@ -93,7 +98,8 @@ module Insika
         secret_headers: Array(secret_headers).map(&:to_s), side_effect: effect,
         timeout: timeout.nil? ? nil : Integer(timeout),
         group: normalize_group(group), tags: normalize_tags(tags),
-        halt_when: normalize_halt_when(halt_when)
+        halt_when: normalize_halt_when(halt_when),
+        evidence: Insika::Evidence::Spec.parse(evidence)
       )
     end
 
@@ -104,11 +110,11 @@ module Insika
         name: h[:name], description: h[:description], parameters: h[:parameters],
         request: h[:request] || {}, response: h[:response],
         secret_headers: h[:secret_headers], side_effect: h[:side_effect], timeout: h[:timeout],
-        group: h[:group], tags: h[:tags], halt_when: h[:halt_when]
+        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence]
       )
     end
 
-    # Group (Phase 7/D4/F5): enablement label by DATA (not name convention),
+    # Group: enablement label by DATA (not name convention),
     # target of AgentProfile's `tools_allow_groups`. Trimmed; empty/nil -> nil.
     def self.normalize_group(group)
       g = group.to_s.strip
@@ -145,7 +151,7 @@ module Insika
     def self.empty_schema = { "type" => "object", "properties" => {}, "required" => [] }
     private_class_method :empty_schema
 
-    # Flat sugar -> JSON Schema. Preserves Phase 5 validation (NAME_RE, duplicates,
+    # Flat sugar -> JSON Schema. Preserves validation (NAME_RE, duplicates,
     # PARAM_TYPES) and lifts `array:<scalar>` into proper `items`.
     #
     # A bare `array` is REFUSED. It used to lift to `items: {type:"string"}` — the
@@ -405,7 +411,7 @@ module Insika
     # String-keyed Hash for persistence (ConfigStore stringifies again, but we
     # normalize here so the record is stable across backends).
     def to_h
-      {
+      h = {
         "name" => name, "description" => description,
         "parameters" => parameters,
         "request" => request.transform_keys(&:to_s),
@@ -415,6 +421,10 @@ module Insika
         "group" => group, "tags" => tags,
         "halt_when" => halt_when&.transform_keys(&:to_s)
       }
+      # present only when declared — a tool without evidence is byte-identical
+      # to today (no declaration, no envelope processing).
+      h["evidence"] = evidence.to_h if evidence
+      h
     end
 
     # -> true when this response ENDS the turn (no further model call). `body` is the

data/lib/insika/tool_envelope.rb

@@ -56,6 +56,11 @@ module Insika
 
       started = monotonic
       result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { __getobj__.call(args) } }
+      # the ONE seam every tool result passes on its way to the model.
+      # For a declared-evidence tool: reshape to the lean envelope, record the ids
+      # on the ledger, hoard the attachments. No evidence = the result passes
+      # through untouched (one nil-check — parity).
+      result = process_evidence(result)
       record_side_effect!(call_id) if side_effect?
       trace(call_id, args, result, started)
       result
@@ -69,7 +74,7 @@ module Insika
 
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-    # D4 (item 30): with parallel tool calls on, the turn's shared semaphore
+    # with parallel tool calls on, the turn's shared semaphore
     # (TurnState#tool_gate, sized by `limits[:tool_concurrency]`) caps how many run
     # at once. Wraps the REAL call ONLY — the approval wait and the skip check are
     # outside it, so a call blocked on a human never holds a slot, and the per-call
@@ -136,5 +141,69 @@ module Insika
       @checkpoint_store.record_side_effect(@state.task.id, turn: @state.turn,
                                                            tool_call_id: call_id)
     end
+
+    # ----   evidence ---------------------------------------------
+
+    # The evidence spec for the wrapped tool (D4). Resolution order:
+    #   1. the wrapped tool responds to `evidence` -> its spec (the data-tool
+    #      path — DataDefinedTool exposes its definition's evidence);
+    #   2. otherwise the tool_registry entry's metadata carries an `evidence`
+    #      spec (the code-tool path — a registry tool opts in at registration).
+    # No spec = pass the result through untouched (parity, byte-identical).
+    def evidence_spec
+      tool = __getobj__
+      if tool.respond_to?(:evidence)
+        raw = tool.evidence
+        return raw && Insika::Evidence::Spec.parse(raw)
+      end
+
+      entry = @tool_registry.respond_to?(:entries) ? registry_entry(real_name) : nil
+      metadata = entry&.respond_to?(:metadata) ? entry.metadata : nil
+      raw = metadata && (metadata[:evidence] || metadata["evidence"])
+      raw && Insika::Evidence::Spec.parse(raw)
+    end
+
+    def registry_entry(name)
+      @tool_registry.entries.find { |e| e.name == name.to_s }
+    end
+
+    # -> result (possibly reshaped). NEVER raises out: a broken evidence result
+    # becomes the envelope error the model can act on, exactly like a malformed
+    # CALL is today. A tool ERROR result is never reshaped (an error must reach
+    # the model verbatim — the DataDefinedTool rule).
+    def process_evidence(result)
+      spec = evidence_spec
+      return result unless spec
+      return result if result.is_a?(Hash) && (result[:error] || result["error"])
+
+      raw = Insika::Evidence::Processor.raw(spec, result)
+      bad = Insika::SchemaGuard.violation_output(spec, raw)
+      return { error: bad } if bad
+
+      lean, attachments = Insika::Evidence::Processor.build(spec, raw)
+      record_evidence!(spec, lean)
+      hoard_attachments!(attachments)
+      lean
+    rescue StandardError => e
+      { error: "evidence processing failed: #{e.message}" }
+    end
+
+    # Ledger write + attachment hoarding, both via the state (duck-typed — the
+    # envelope's existing specs construct state stubs without these readers).
+    def record_evidence!(_spec, lean)
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      return unless ledger
+
+      ids = Array(lean["items"]).map { |i| i["id"] }
+      ledger.record(ids) unless ids.empty?
+    end
+
+    def hoard_attachments!(attachments)
+      return if attachments.empty?
+      return unless @state.respond_to?(:evidence_attachments)
+
+      @state.evidence_attachments ||= []
+      @state.evidence_attachments.concat(attachments)
+    end
   end
 end

data/lib/insika/tool_manifest.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 module Insika
-  # Tool manifest (Phase 7, Step B): the BATCH, DATA-driven, industry-STANDARD
+  # Tool manifest: the BATCH, DATA-driven, industry-STANDARD
   # (JSON Schema) form of the data-tools. A `defaults` (common binding:
   # base_url/path_template/method/headers/secret_headers/response) + a list of
   # `tools`. Each tool is normalized — inheriting the defaults, applying the envelope
   # adapter (OpenAI/MCP/raw) and resolving `endpoint`→url + `{{secret.*}}`/
   # `{{env.*}}` — into a ToolDefinition Hash consumable by the ToolStore.
   #
-  # GENERIC (NF1): nothing here mentions achei/openclaw — the manifest IS the contract. It
+  # GENERIC: nothing here mentions a consumer/gateway — the manifest IS the contract. It
   # only NORMALIZES/RESOLVES; the final validation (method/url/types, model placeholders
   # `{{param}}`/turn `{{ctx.*}}`, safe subset of JSON Schema) belongs to
   # ToolDefinition (single source). The batch upsert + hot reload belongs to the
@@ -18,12 +18,12 @@ module Insika
   #   - `{{param}}`/`{{ctx.*}}` : resolved AT THE TURN (by DataDefinedTool) —
   #     they stay INTACT here; ToolDefinition validates them.
   #   - `{{secret.*}}`/`{{env.*}}` : resolved AT INGESTION (here) — from the deployment,
-  #     never from the manifest (D6/R3). `{{env.*}}` is non-secret config (any
+  #     never from the manifest (R3). `{{env.*}}` is non-secret config (any
   #     template); `{{secret.*}}` is a credential and is ONLY allowed in a header
   #     declared in `secret_headers`, with value === `{{secret.X}}` (nothing literal,
   #     nothing outside a header — otherwise the secret would leak without masking).
   #
-  # Interface envelope (what the model sees), by adapter (D3):
+  # Interface envelope (what the model sees), by adapter:
   #   - `parameters` (raw JSON Schema), OR
   #   - `{ "function": { name, description, parameters } }` (OpenAI/Anthropic), OR
   #   - `{ "inputSchema": {...} }` (MCP).
@@ -73,17 +73,21 @@ module Insika
         "response" => binding[:response],
         "secret_headers" => binding[:secret_headers],
         "side_effect" => t["side_effect"],
-        "group" => t["group"] || defaults["group"],       # Phase 7/D4/F5 (Step C):
+        "group" => t["group"] || defaults["group"],       # per-group allowlist:
         "tags" => (Array(defaults["tags"]) | Array(t["tags"])), # inherited default; tags unioned
         # Per-tool only: "this result ends the turn" is a property of THIS backend's
         # response, never something a manifest default should hand to its siblings.
-        "halt_when" => t["halt_when"]
+        "halt_when" => t["halt_when"],
+        # the evidence declaration (lean envelope + ledger feed are the
+        # SAME data contract — D1). Normalized here; a malformed declaration is a
+        # ValidationError at ingestion, isolable per tool (R4).
+        "evidence" => t["evidence"] && Insika::Evidence::Spec.parse(t["evidence"]).to_h
       }.compact
     end
 
     private
 
-    # Envelope adapter (D3): extracts the INTERFACE (name/description/parameters) from
+    # Envelope adapter: extracts the INTERFACE (name/description/parameters) from
     # any standard form. name/description fall back to the tool's top level when the
     # envelope does not carry them.
     def extract_interface(t)