insika 0.1.0 → 0.2.0

data/lib/insika/testing/store_contract.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Contract suite for Insika::Store (doc 01 §7), exported for third-party
-# backends (RFC-0018 A4) — a gem like `insika-pg` writes its spec against THIS
+# Contract suite for Insika::Store, exported for third-party
+# backends — a gem like `insika-pg` writes its spec against THIS
 # file, not against a read of stores/sqlite.rb:
 #
 #   require "insika/testing/store_contract"
@@ -11,7 +11,7 @@
 #     it_behaves_like "an Insika store"
 #   end
 #
-# Two groups, on purpose (RFC-0018 §4 item 4):
+# Two groups, on purpose:
 #
 # - "an Insika store" — universal; every backend passes EXACTLY it (L2: the
 #   suite is honest — a test that passes on Memory passes on SQLite). The
@@ -27,89 +27,89 @@
 # races) — those belong to the backend's own spec.
 RSpec.shared_examples "an Insika store" do
   describe "#get / #set (round-trip)" do
-    it "C1 preserves Hash with string keys" do # C1
+    it " preserves Hash with string keys" do #
       store.set("s", "k", { "a" => 1, "b" => [1, 2] })
       expect(store.get("s", "k")).to eq({ "a" => 1, "b" => [1, 2] })
     end
 
-    it "C2 preserves Array" do # C2
+    it " preserves Array" do #
       store.set("s", "k", [1, "x", true, nil])
       expect(store.get("s", "k")).to eq([1, "x", true, nil])
     end
 
-    it "C3 preserves String" do # C3
+    it " preserves String" do #
       store.set("s", "k", "texto")
       expect(store.get("s", "k")).to eq("texto")
     end
 
-    it "C4 preserves Integer" do # C4
+    it " preserves Integer" do #
       store.set("s", "k", 42)
       value = store.get("s", "k")
       expect(value).to eq(42)
       expect(value).to be_a(Integer)
     end
 
-    it "C5 preserves Float" do # C5
+    it " preserves Float" do #
       store.set("s", "k", 3.14)
       value = store.get("s", "k")
       expect(value).to eq(3.14)
       expect(value).to be_a(Float)
     end
 
-    it "C6 preserves booleans" do # C6
+    it " preserves booleans" do #
       store.set("s", "t", true)
       store.set("s", "f", false)
       expect(store.get("s", "t")).to be(true)
       expect(store.get("s", "f")).to be(false)
     end
 
-    it "C7 preserves nil written without exception" do # C7
+    it " preserves nil written without exception" do #
       store.set("s", "k", nil)
       expect(store.get("s", "k")).to be_nil
     end
 
-    it "C8 converts Symbols (keys and values) to Strings" do # C8
+    it " converts Symbols (keys and values) to Strings" do #
       store.set("s", "k", { chave: :valor })
       expect(store.get("s", "k")).to eq({ "chave" => "valor" })
     end
 
-    it "C9 returns nil for an absent key, never an exception" do # C9
+    it " returns nil for an absent key, never an exception" do #
       expect(store.get("s", "nao-existe")).to be_nil
     end
 
-    it "C10 overwrites silently (last-write-wins)" do # C10
+    it " overwrites silently (last-write-wins)" do #
       store.set("s", "k", "primeiro")
       store.set("s", "k", "segundo")
       expect(store.get("s", "k")).to eq("segundo")
     end
 
-    it "C11 set returns the same object passed in (not the round-trip)" do # C11
+    it " set returns the same object passed in (not the round-trip)" do #
       obj = { "a" => 1 }
       expect(store.set("s", "k", obj)).to equal(obj)
     end
   end
 
   describe "#delete" do
-    it "C12 removes existing and returns true" do # C12
+    it " removes existing and returns true" do #
       store.set("s", "k", 1)
       expect(store.delete("s", "k")).to be(true)
       expect(store.get("s", "k")).to be_nil
     end
 
-    it "C13 returns false for a nonexistent key" do # C13
+    it " returns false for a nonexistent key" do #
       expect(store.delete("s", "k")).to be(false)
     end
   end
 
   describe "#list" do
-    it "C14 returns scope keys sorted lexicographically" do # C14
+    it " returns scope keys sorted lexicographically" do #
       store.set("s", "b", 1)
       store.set("s", "a", 1)
       store.set("s", "c", 1)
       expect(store.list("s")).to eq(%w[a b c])
     end
 
-    it "C15 filters by prefix with start_with? (not include?)" do # C15
+    it " filters by prefix with start_with? (not include?)" do #
       store.set("s", "task:1", 1)
       store.set("s", "task:2", 1)
       store.set("s", "checkpoint:1", 1)
@@ -117,7 +117,7 @@ RSpec.shared_examples "an Insika store" do
       expect(store.list("s", "task:")).to eq(%w[task:1 task:2])
     end
 
-    it "C16 returns [] for an empty scope" do # C16
+    it " returns [] for an empty scope" do #
       expect(store.list("s")).to eq([])
     end
 
@@ -129,7 +129,7 @@ RSpec.shared_examples "an Insika store" do
   end
 
   describe "scope isolation" do
-    it "C17 keeps scopes independent in get/list/delete" do # C17
+    it " keeps scopes independent in get/list/delete" do #
       store.set("s1", "k", 1)
       store.set("s2", "k", 2)
 
@@ -143,16 +143,16 @@ RSpec.shared_examples "an Insika store" do
   end
 
   describe "#transaction" do
-    it "C18 returns the block's value" do # C18
+    it " returns the block's value" do #
       expect(store.transaction { 42 }).to eq(42)
     end
 
-    it "C19 commits the block's writes" do # C19
+    it " commits the block's writes" do #
       store.transaction { store.set("s", "k", "commitado") }
       expect(store.get("s", "k")).to eq("commitado")
     end
 
-    it "C20 does a real rollback of set AND delete when the block raises" do # C20
+    it " does a real rollback of set AND delete when the block raises" do #
       store.set("s", "manter", "antigo")
       store.set("s", "apagar", "existe")
 
@@ -169,7 +169,7 @@ RSpec.shared_examples "an Insika store" do
       expect(store.get("s", "apagar")).to eq("existe")
     end
 
-    it "C21 reuses the outer transaction when nested" do # C21
+    it " reuses the outer transaction when nested" do #
       store.set("s", "k", "antigo")
 
       expect do
@@ -185,7 +185,7 @@ RSpec.shared_examples "an Insika store" do
   end
 
   describe "serialization errors" do
-    it "C22 raises StoreError and does not write a non-serializable value" do # C22
+    it " raises StoreError and does not write a non-serializable value" do #
       expect do
         store.set("s", "k", Object.new)
       end.to raise_error(Insika::StoreError)
@@ -194,7 +194,7 @@ RSpec.shared_examples "an Insika store" do
   end
 end
 
-# Multi-worker safety (RFC-0018 A3). Every RFC-0016 A1 claim (outbox, delegation
+# Multi-worker safety. Every claim (outbox, delegation
 # sweep, recovery) is a read-check-write inside `transaction` — on SQLite that is
 # atomic because the backend opens BEGIN IMMEDIATE; a backend whose transaction
 # only yields passes all 22 cases above and still double-claims under two
@@ -204,7 +204,7 @@ end
 # The `sleep` inside each transaction is deliberate: it holds the read state
 # open long enough that a backend without isolation ALWAYS lets a second
 # connection through, while a correct backend serializes the writers. Without
-# it a wrong backend could pass by scheduling luck — the failure E2 relies on.
+# it a wrong backend could pass by scheduling luck — the failure relies on.
 RSpec.shared_examples "an Insika store safe for N workers" do
   # Starts N threads, each holding its OWN connection to the same backend,
   # releases them together, and returns each block's value. Connections are

data/lib/insika/tick.rb

@@ -0,0 +1,122 @@
+# 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)
+      @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)
+    end
+
+    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: [] }
+      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,7 +30,7 @@ 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,
@@ -49,7 +49,7 @@ module Insika
     EXTRACTS = %w[body_raw status json_path].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),
@@ -108,7 +108,7 @@ module Insika
       )
     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 +145,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

data/lib/insika/tool_envelope.rb

@@ -69,7 +69,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

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,7 +73,7 @@ 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.
@@ -83,7 +83,7 @@ module Insika
 
     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)