insika 0.0.1 → 0.2.0

data/lib/insika/testing/store_contract.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# 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"
+#
+#   RSpec.describe Insika::Stores::PG do
+#     subject(:store) { described_class.new(url:) }
+#     it_behaves_like "an Insika store"
+#   end
+#
+# 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
+#   including group defines `store` (an empty, ready backend).
+# - "an Insika store safe for N workers" — OPT-IN; the multi-worker half. The
+#   including group ALSO defines `store_factory`, a callable returning ANOTHER
+#   connection to the SAME underlying backend. A backend that cannot serialize
+#   transactions across connections must not include it — Memory is the
+#   canonical example, and a single-connection backend has nothing to prove.
+#   Anything that wants to sit under `WEB_CONCURRENCY > 1` has to.
+#
+# Do not include backend-specific cases here (file durability, WAL, boot
+# races) — those belong to the backend's own spec.
+RSpec.shared_examples "an Insika store" do
+  describe "#get / #set (round-trip)" do
+    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 " preserves Array" do #
+      store.set("s", "k", [1, "x", true, nil])
+      expect(store.get("s", "k")).to eq([1, "x", true, nil])
+    end
+
+    it " preserves String" do #
+      store.set("s", "k", "texto")
+      expect(store.get("s", "k")).to eq("texto")
+    end
+
+    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 " 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 " 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 " preserves nil written without exception" do #
+      store.set("s", "k", nil)
+      expect(store.get("s", "k")).to be_nil
+    end
+
+    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 " returns nil for an absent key, never an exception" do #
+      expect(store.get("s", "nao-existe")).to be_nil
+    end
+
+    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 " 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 " 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 " returns false for a nonexistent key" do #
+      expect(store.delete("s", "k")).to be(false)
+    end
+  end
+
+  describe "#list" do
+    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 " 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)
+      store.set("s", "my-task:1", 1) # trap: contains "task:" but does not start with it
+      expect(store.list("s", "task:")).to eq(%w[task:1 task:2])
+    end
+
+    it " returns [] for an empty scope" do #
+      expect(store.list("s")).to eq([])
+    end
+
+    it "sorts lexicographically, not numerically" do # edge case 2
+      store.set("s", "task:10", 1)
+      store.set("s", "task:2", 1)
+      expect(store.list("s", "task:")).to eq(%w[task:10 task:2])
+    end
+  end
+
+  describe "scope isolation" do
+    it " keeps scopes independent in get/list/delete" do #
+      store.set("s1", "k", 1)
+      store.set("s2", "k", 2)
+
+      expect(store.get("s1", "k")).to eq(1)
+      expect(store.get("s2", "k")).to eq(2)
+      expect(store.list("s1")).to eq(%w[k])
+
+      store.delete("s1", "k")
+      expect(store.get("s2", "k")).to eq(2)
+    end
+  end
+
+  describe "#transaction" do
+    it " returns the block's value" do #
+      expect(store.transaction { 42 }).to eq(42)
+    end
+
+    it " commits the block's writes" do #
+      store.transaction { store.set("s", "k", "commitado") }
+      expect(store.get("s", "k")).to eq("commitado")
+    end
+
+    it " does a real rollback of set AND delete when the block raises" do #
+      store.set("s", "manter", "antigo")
+      store.set("s", "apagar", "existe")
+
+      expect do
+        store.transaction do
+          store.set("s", "manter", "novo")
+          store.delete("s", "apagar")
+          raise "boom"
+        end
+      end.to raise_error("boom")
+
+      # all the block's effects undone
+      expect(store.get("s", "manter")).to eq("antigo")
+      expect(store.get("s", "apagar")).to eq("existe")
+    end
+
+    it " reuses the outer transaction when nested" do #
+      store.set("s", "k", "antigo")
+
+      expect do
+        store.transaction do
+          store.transaction { store.set("s", "k", "novo") }
+          raise "boom"
+        end
+      end.to raise_error("boom")
+
+      # outer rollback undoes the inner set (no nesting error)
+      expect(store.get("s", "k")).to eq("antigo")
+    end
+  end
+
+  describe "serialization errors" do
+    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)
+      expect(store.get("s", "k")).to be_nil
+    end
+  end
+end
+
+# 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
+# workers, silently. These cases close that hole, across REAL concurrent
+# connections (threads, each on its own handle from `store_factory`).
+#
+# 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 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
+  # closed on the way out when the backend has a #close.
+  def with_concurrent_connections(n, &blk)
+    ready = Queue.new
+    go = Queue.new
+    threads = n.times.map do
+      Thread.new do
+        conn = store_factory.call
+        ready << true
+        go.pop # hold every connection at the line, then release them together
+        blk.call(conn)
+      ensure
+        conn.close if conn.respond_to?(:close)
+      end
+    end
+    n.times { ready.pop }
+    go.close # a closed queue pops nil immediately: the starting gun
+    threads.map(&:value)
+  end
+
+  # The outbox/delegation claim, verbatim in shape: read the status, and only
+  # the connection that still sees "pending" may flip it. A correct backend
+  # serializes the transactions, so exactly ONE of the 8 observes "pending".
+  it "claims a pending key exactly once across concurrent connections" do
+    store.set("jobs", "job:1", "pending")
+
+    claims = with_concurrent_connections(8) do |conn|
+      conn.transaction do
+        next unless conn.get("jobs", "job:1") == "pending"
+
+        sleep 0.01 # hold the read open: a wrong backend lets everyone through
+        conn.set("jobs", "job:1", "claimed")
+        true
+      end
+    end.count(true)
+
+    expect(claims).to eq(1)
+    expect(store.get("jobs", "job:1")).to eq("claimed")
+  end
+
+  # The lost-update shape the claim generalizes from: read-modify-write of a
+  # counter. A backend whose transaction yields without isolation drops
+  # increments whenever two connections overlap.
+  it "does not lose updates across concurrent connections" do
+    store.set("meters", "hits", 0)
+    connections = 4
+    increments = 10
+
+    with_concurrent_connections(connections) do |conn|
+      increments.times do
+        conn.transaction do
+          current = conn.get("meters", "hits")
+          sleep 0.001 # widen the window a wrong backend loses updates through
+          conn.set("meters", "hits", current + 1)
+        end
+      end
+    end
+
+    expect(store.get("meters", "hits")).to eq(connections * increments)
+  end
+end

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_estimator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Insika
+  # Cheap token estimate behind an interface.
+  # Default: text.length / 4 (off by ~±15%, absorbed by the budget margin).
+  # Swappable for a real tokenizer without touching the Builder: any object that
+  # responds to #estimate(text) -> Integer works as a replacement (injected at the
+  # composition root).
+  module TokenEstimator
+    module_function
+
+    def estimate(text)
+      text.to_s.length.ceildiv(4)
+    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