rubik 0.1.0

data/lib/rubik/storage/vakanuvis/gate.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Düzlem 2'nin durumlu yarısı: digest iş kuyruğu, doğum sicili ve
+      # kirli işaret — DistillGate kurallarının (doğrulayıcı, brif,
+      # makbuz) biriktirici Ω'su. ctx servisi DEĞİLDİR, kendi thread'i
+      # YOKTUR (worker Harness'te kalır); ömrü sahibi Harness'in ömrüdür
+      # (kompozisyon) — o yüzden ctx.on_dispose tersi gerekmez.
+      #
+      # Tek kilit (@lock) kuyruk + sicil + kirli işareti SAHİPLENİR ve
+      # kilit sıralaması kendiliğinden tekyönlüdür: @lock altında yalnız
+      # store/supervisor çağrılır (store monitoru asla geri çağırmadığı
+      # için @lock → store TEK yuvalanmadır); Harness'in @monitor'u @lock
+      # altında ASLA alınmaz. Eski with_gate → @monitor dansı silindi,
+      # taşınmadı — gate durumu ile harness durumu artık aynı kod yolunu
+      # paylaşmaz.
+      module DistillGate
+        # Doğum kapısı + iş defteri. Kurucu enjeksiyonuyla çalışır: store,
+        # supervisor, event_bus ve sözlü girdiler dışarıdan verilir —
+        # Harness'e ASLA geri dokunmaz.
+        class Gate
+          attr_reader :store, :supervisor, :dmesg, :session_slug, :max_steps, :model
+
+          def initialize(store:, max_steps:, session_slug:, supervisor: nil, dmesg: nil,
+                         event_bus: nil, enabled: true, model: nil)
+            @store = store
+            @supervisor = supervisor
+            @dmesg = dmesg
+            @event_bus = event_bus
+            @enabled = enabled
+            @max_steps = max_steps
+            @model = model
+            @session_slug = session_slug
+            @pending_digests = []
+            @distillers = {}
+            @lock = Mutex.new
+            # v2 §4-V5: kirli işareti — son başarılı derlemeden bu yana KALICI
+            # içerik (memory+wiki+note satır ayak izi) değişmediyse toplu
+            # damıtıcı doğmaz. Turn satırları ayak izini değiştirmez: saf
+            # turn akışında derleme boşa yakılmaz.
+            @compile_footprint = nil
+          end
+
+          # ---- Seam 1: maestro tool thread'i (Harness#digest delege eder) --
+
+          # Hedef için dedupe denetimi + itme TEK @lock kritik bölümünde;
+          # hemen ardından doğum denemesi AYRI bir @lock penceresinde
+          # (iki fazlı — tek büyük kritik bölüm İÇİNE ALMA). Doğum
+          # başarısızsa iş kuyrukta kalır: yarım durum birikmez.
+          # Dönen makbuz dizgesi bayt-bayt eski Harness#digest çıktısıdır.
+          def submit(query)
+            target = Vocabulary.wiki_ref(query)
+            # v2 §4-V5: aynı hedefli iş zaten kuyrukta ya da uçuştaysa makbuz
+            # 'already queued' varyantına düşer — çift doğum yok.
+            in_flight = @lock.synchronize do
+              busy = @pending_digests.any? { |j| j[:target] == target } ||
+                     @distillers.any? { |_id, j| j[:target] == target }
+              unless busy
+                @pending_digests << { query: query, target: target,
+                                      transcript_uris: source_transcript_uris }
+              end
+              busy
+            end
+            if in_flight
+              return "Digest already queued for '#{target}' (#{AnnalWriter.one_line(query, 60)}): the chronicler is " \
+                     "compiling it — recall it later with vakanuvis(action: 'recall', query: '...')."
+            end
+
+            spawned = spawn_job!(batch: false)
+            DistillGate.receipt(query: query, target: target, spawned: !spawned.nil?)
+          end
+
+          # ---- Seam 2: worker thread'i (Harness#handle_subagent çağırır) ---
+
+          # Ham subagent tamamlanma olayı. İş sicilden @lock altında
+          # silinir, KİLİT BIRAKILIR, sonra supervisor.get + hasat TEK
+          # kurtarma bölgesinde koşar: get/inst.result (hedeflenmemiş
+          # double, kayıp kayıt) ve DistillGate.harvest (disk hatası, bozuk
+          # satır) raise ederse iş kaybolmaz — hedefli iş kuyruğa geri
+          # konur (review: sessiz-yutma sınıfı), toplu iş dürüstçe düşer.
+          # Dönen değer: :compiled | :incomplete | :crashed | :rejected | nil.
+          def completion_event(payload)
+            job = @lock.synchronize { @distillers.delete(payload[:id].to_s) }
+            return unless job
+
+            outcome = begin
+              inst = @supervisor.respond_to?(:get) ? @supervisor.get(payload[:id].to_s) : nil
+              finish_body = inst.respond_to?(:result) ? inst.result : nil
+              if payload[:state].to_s != "completed" || finish_body.nil?
+                :incomplete
+              else
+                DistillGate.harvest(self, job, finish_body)
+              end
+            rescue StandardError => e
+              if job[:target]
+                @lock.synchronize { @pending_digests << job }
+                Vakanuvis.log_via(@dmesg, :warn,
+                                  "harvest crashed for #{job[:target]} (#{e.class}: #{e.message}) — digest requeued")
+              else
+                Vakanuvis.log_via(@dmesg, :warn,
+                                  "harvest crashed for batch compile (#{e.class}: #{e.message}) — compile dropped")
+              end
+              :crashed
+            end
+
+            case outcome
+            when :compiled
+              Vakanuvis.log_via(@dmesg, :info, "distiller compiled #{job[:target] || 'a wiki page'}")
+            when :incomplete
+              if job[:target]
+                @lock.synchronize { @pending_digests << job }
+                Vakanuvis.log_via(@dmesg, :warn,
+                                  "distiller for #{job[:target]} ended state=#{payload[:state]} — digest requeued")
+              else
+                Vakanuvis.log_via(@dmesg, :warn, "batch distiller ended state=#{payload[:state]} — compile dropped")
+              end
+            when :crashed, :rejected then nil # kendi dalında detay loglandı (crash requeue/drop; B6 ret sebebi + trim)
+            else
+              # Beklenmedik outcome — yanlış "schema ret" etiketi yerine
+              # gerçek değeri yaz (future harvest sembolleri sessiz kalmasın).
+              Vakanuvis.log_via(@dmesg, :warn, "distiller ended with unexpected outcome=#{outcome.inspect} — dropped, store untouched")
+            end
+            outcome
+          end
+
+          # ---- Seam 3: worker thread'inin flush noktası (Harness#maintain) --
+
+          # Toplu doğum kararı, kirli işarete bağlıdır (v2 §4-V5): kalıcı
+          # içerik değişmediyse damıtıcı yakılmaz.
+          def flush_tick
+            spawn_job!(batch: true) if dirty?
+          end
+
+          # Salt-okunuma peeki (test/kurcalama yüzeyi): kuyruğun başını
+          # gösterir — tüketmez. Üretim görünürlüğü aşağıdaki job_targets'tır.
+          def peek_job(batch: false)
+            @lock.synchronize { @pending_digests.first || (batch ? { batch: true } : nil) }
+          end
+
+          # İş defteri görünümü (issue #100 P2b): kuyruktaki + uçuştaki
+          # hedefler. @lock altında YALNIZ kuyruk/sicil okunur — store'a
+          # dokunulmaz (kilit sırası tekyönlü kalır).
+          def job_targets
+            @lock.synchronize do
+              { queued: @pending_digests.map { |j| j[:target] || "batch compile" },
+                in_flight: @distillers.values.map { |j| j[:target] || "batch compile" } }
+            end
+          end
+
+          # Başarılı derlemenin hemen ardından DistillGate çağırır — ayak izi
+          # o anki hale snapshot'lanır; sonraki flush ancak YENİ kalıcı
+          # içerikte doğum kararı verir. Snapshot'ın kendisi patlarsa sayfa
+          # zaten başarılı yazılmıştır: gate kirli kalır (bir sonraki
+          # flush'ta yeniden snapshot denenir) — ekonomi kaybı, doğruluk değil.
+          def mark_compiled!
+            @lock.synchronize { @compile_footprint = footprint }
+          end
+
+          # Oturum annal'ının rubik:// URI'si (DistillGate.brief kaynak
+          # listesi için okur). Annal yoksa nil — brif o kaynağı listelemez.
+          def session_annal_uri
+            rec = @store.get(type: "note", id: Vocabulary.session_ref(@session_slug))
+            rec && @store.uri_for("note", rec["id"])
+          end
+
+          private
+
+          # Doğum kararı: digest kuyruğu önceliklidir. İş claim→spawn→confirm
+          # dizisiyle TEK kapıdan (@lock) alınır: maestro thread'i (submit)
+          # ile worker'ın flush'u aynı iş için çift doğum yarışamaz; doğum
+          # başarısızsa iş kuyruğa geri konur, sonraki flush'ta yeniden
+          # denenir.
+          def spawn_job!(batch:)
+            return unless spawn_allowed?
+
+            @lock.synchronize do
+              job = claim_job(batch: batch)
+              next unless job
+
+              begin
+                inst = @supervisor.spawn(
+                  role: DISTILLER_ROLE, prompt: DistillGate.brief(self, job), type_name: TYPE_NAME,
+                  # parent_id omitted — the root plane is spawn's default
+                  # (ConversationId::ROOT_ID); storage stays plane-blind.
+                  max_steps: @max_steps, model: @model || "inherit"
+                )
+                confirm(inst.id, job)
+                Vakanuvis.log_via(@dmesg, :info, "distiller spawned for #{DistillGate.job_description(job)}")
+                inst
+              rescue StandardError => e
+                restore_job(job)
+                Vakanuvis.log_via(@dmesg, :warn,
+                                  "distiller spawn failed (#{DistillGate.job_description(job)}): #{e.class}: #{e.message}")
+                nil
+              end
+            end
+          end
+
+          # Bus yoksa hasat da olamaz (damıtıcının tamamlanma olayı gelmez):
+          # doğum kapısı kapalı kalır, makbuz dürüst kalır.
+          def spawn_allowed?
+            @enabled && @event_bus.respond_to?(:subscribe) &&
+              @supervisor.respond_to?(:spawn) &&
+              @supervisor.respond_to?(:type_registry) && @supervisor.type_registry.get(TYPE_NAME)
+          end
+
+          # Aşağısı YALNIZ @lock altından çağrılır (çağıran: submit /
+          # spawn_job! / completion_event) — kendi kilidi almaz.
+          def claim_job(batch: false)
+            @pending_digests.shift || (batch ? { batch: true, transcript_uris: source_transcript_uris } : nil)
+          end
+
+          def restore_job(job)
+            @pending_digests.unshift(job) if job[:target]
+          end
+
+          def confirm(inst_id, job)
+            @distillers[inst_id.to_s] = job
+          end
+
+          def dirty?
+            @lock.synchronize { @compile_footprint.nil? || @compile_footprint != footprint }
+          end
+
+          # Kalıcı içerik ayak izi: kart + sayfa + not (annal dahil) satır
+          # sayıları. Turn satırları mevcut annal notuna satır ekler, ayak
+          # izini değiştirmez — saf turn akışında derleme boşa yakılmaz.
+          def footprint
+            ["memory", "wiki", "note"].sum { |t| @store.list(type: t).size }
+          end
+
+          # Kaynak disiplini (v2 §4-V4): yalnız status=completed transcript
+          # satırları; kronikçinin kendi etiketlileri hariç — özyinelemeli
+          # kaynak kirliliği. En yeni N satır (updated_at, sonra row) —
+          # deterministik sıra.
+          def source_transcript_uris
+            summaries = @store.list(type: "transcript").reject do |s|
+              s.status != Vocabulary::TRANSCRIPT_COMPLETED || Array(s.tags).include?(Vocabulary::BASE_TAG)
+            end
+            summaries.sort_by { |s| [s.updated_at.to_s, s.row.to_i] }
+                     .last(Harness::SOURCE_TRANSCRIPT_LIMIT)
+                     .map { |s| @store.uri_for("transcript", s.id) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/storage/vakanuvis/harness.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Düzlem 1 — Deterministik Çekirdek: tek worker thread + sınırlı
+      # FIFO kuyruk. Olay kapıları mevcut bus abonelikleridir (subagent
+      # tamamlanma + goal bitişi — K3); NE ZAMAN, NEREYE, NASIL yazılacağı
+      # burada kural tabanlıdır. Sessizlik sözleşmesi (§4.3): WAKE_KINDS
+      # dışında kalır, notice yaymaz — sadece dmesg/stderr. Ömür: ctx
+      # dispose'u LIFO ile kapatır (worker kill + abonelik geri alımı).
+      class Harness
+        STOP = :__vakanuvis_stop__
+        MAX_QUEUE = 200
+        RECALL_LIMIT = 5
+        RECALL_FALLBACK_LIMIT = 3
+        RECALL_BODY_SLICE = 140
+        RECALL_TYPES = ["memory", "wiki"].freeze
+        # v2 §4-V4: damıtıcı kaynak disiplini — yalnız TAMAMLANMIŞ
+        # transcript'ler, damıtıcının kendisi Hariç (özyineleme kirliliği:
+        # canlı depoda transcript satırları 'vakanuvis' etiketi taşır).
+        SOURCE_TRANSCRIPT_LIMIT = 8
+        # Literaller, depolama katmanını orchestrator require'larından
+        # uzak tutar; test ikizleri her ikisini de sabitlere pinler:
+        # Notices::COMPLETED_EVENT ve GoalState::FINISH_EVENT. TURN_EVENT
+        # REPL TurnRecorder#emit_turn_finished kapısıdır (root-turn planı
+        # 2026-10-04).
+        SUBAGENT_EVENT = :subagent_completed
+        GOAL_EVENT = :goal_finished
+        TURN_EVENT = :turn_finished
+
+        attr_reader :store, :supervisor, :dmesg, :session_slug, :gate
+
+        def initialize(store:, config: nil, event_bus: nil, supervisor: nil, dmesg: nil,
+                       context: nil, session_slug: nil, max_queue: MAX_QUEUE)
+          @store = store
+          @config = config
+          @event_bus = event_bus
+          @supervisor = supervisor
+          @dmesg = dmesg
+          @context = context
+          @session_slug = session_slug || self.class.mint_session_slug
+          @flush_events = fetch_cfg("subagents.vakanuvis.flush_events", 10).to_i
+          @max_steps = fetch_cfg("subagents.vakanuvis.max_steps", 8).to_i
+          @model = fetch_cfg("subagents.vakanuvis.model", nil)
+          @retention = fetch_cfg("subagents.vakanuvis.retention", "supersede").to_s
+          @distiller_enabled = fetch_cfg("subagents.vakanuvis.distiller", true) != false
+          @root_turns = fetch_cfg("subagents.vakanuvis.root_turns", true) != false
+          @max_queue = max_queue.to_i
+          @queue = Thread::Queue.new
+          @monitor = Monitor.new
+          @seq = 0
+          @goal_ordinal = 0
+          @turn_ordinal = 0
+          @events_since_distill = 0
+          @dropped = 0
+          @stopped = false
+          @busy = 0
+          @worker = nil
+          # Damıtıcı doğum kapısı: kuyruk + sicil + kirli işaret Gate'de
+          # (kurucu enjeksiyonu — gate Harness'e geri dokunmaz).
+          @gate = DistillGate::Gate.new(store: @store, supervisor: @supervisor, dmesg: @dmesg,
+                                        event_bus: @event_bus, enabled: @distiller_enabled,
+                                        max_steps: @max_steps, model: @model, session_slug: @session_slug)
+        end
+
+        class << self
+          # Oturum slug'ı: tek süreçte deterministik, süreçler arasında
+          # ayrışır. Replay testleri sabit slug enjekte eder.
+          def mint_session_slug
+            "#{Time.now.utc.strftime('%Y%m%d-%H%M%S')}-#{Process.pid}"
+          end
+        end
+
+        # ---- yaşam döngüsü -------------------------------------------------
+
+        def start!
+          subscribe_events
+          @worker = Thread.new { run_worker }
+          @worker.name = "rubik-vakanuvis" if @worker.respond_to?(:name=)
+          self
+        end
+
+        def stopped? = @monitor.synchronize { @stopped }
+
+        # Dispose yolu: FIFO'daki her şey (STOP dahil öncesindeki olaylar)
+        # işlenir, sonra thread sonlanır. Kalan olay yarımda kalmaz; thread
+        # 2 saniyede durmazsa (yavaş bir flush/spawn içinde) kill gelir ve
+        # işlenemeyen olay sayısı dmesg'e düşer — sessiz kayıp yok.
+        def shutdown
+          @monitor.synchronize { @stopped = true }
+          @monitor.synchronize { @busy += 1 } # STOP işaretinin de işleniş sayılır
+          @queue.push(STOP)
+          @worker&.join(2)
+          if @worker&.alive?
+            Vakanuvis.log_via(@dmesg, :warn, "worker did not stop in 2s — killing with #{queue_size} event(s) unprocessed")
+            @worker.kill
+          end
+          @worker = nil
+        end
+
+        def wait_idle(timeout: 2.0)
+          deadline = Time.now + timeout
+          sleep 0.01 while busy? && Time.now < deadline
+          !busy?
+        end
+
+        # Kuyrukta + uçuştaki olay sayısı (push'ta artar, işlenince/düşürülünce
+        # azalır) — pop ile işaretleme arasındaki yarış penceresini kapatır.
+        def busy? = @monitor.synchronize { @busy.positive? }
+
+        # ---- olay giriş kapıları (kworker thread'inde çağrılır) -----------
+
+        def enqueue_event(kind, payload)
+          return false if stopped?
+
+          unless payload.is_a?(Hash)
+            Vakanuvis.log_via(@dmesg, :warn, "discarded non-hash #{kind} event (#{payload.class})")
+            return false
+          end
+
+          drop_oldest! if @queue.size >= @max_queue
+          @monitor.synchronize { @busy += 1 }
+          @queue.push([kind, payload])
+          true
+        end
+
+        def queue_size = @queue.size
+
+        # ---- talep düzlemi (maestro aracı buraya delege eder; K7) ---------
+
+        # Tam deterministik, LLM'siz: Store#search_ranked BM25-lite sırası +
+        # RECALL_TYPES kısıtı + ilk RECALL_LIMIT kayıt ⇒ aynı depo ⇒ aynı
+        # digest. type: dizisi (v2 §4-V8) transcript/note gibi arama dışı
+        # tipleri hiç parse etmez; sıralama politika kararına aittir —
+        # Store#search'in [type,row] sözleşmesi değişmez.
+        def recall(query, types: RECALL_TYPES)
+          q = query.to_s.strip
+          raise ArgumentError, "recall: 'query' is required" if q.empty?
+
+          allowed = Array(types).map(&:to_s)
+          allowed = RECALL_TYPES if allowed.empty?
+          hits = @store.search_ranked(query: q, type: allowed).first(RECALL_LIMIT)
+          unless hits.empty?
+            lines = hits.map { |r| recall_line(r) }
+            header = "Recalled #{hits.size} entit#{hits.size == 1 ? 'y' : 'ies'} for '#{AnnalWriter.one_line(q, 80)}':"
+            return "#{header}\n#{lines.join("\n")}\nRead a full record with read_file(path: '<uri above>')."
+          end
+
+          relaxed_digest(q, allowed)
+        end
+
+        # record tool thread'inden, sweep worker'dan koşar — get-then-put
+        # dansını tek kilide alınca çift satır açma yarışı kapanır (store
+        # monitoru asla geri çağırmadığı için kilit sırası tekyönlü).
+        def record(topic:, body:, links: {}, tags: [])
+          @monitor.synchronize { MemorySteward.record(@store, topic: topic, body: body, links: links, tags: tags) }
+        end
+
+        def forget(ref:)
+          raise ArgumentError, "forget: 'ref' is required" if ref.to_s.strip.empty?
+
+          MemorySteward.forget(@store, ref: ref, retention: @retention)
+        end
+
+        # Asenkron (K9): istek kuyruğa yazılır, maestro'ya deterministik
+        # makbuz döner — turn'ü asla LLM bekletilmez. Sınır nöbetçisi:
+        # boş sorgu burada patlar (tool katmanı yakalar), gerisi Gate'e
+        # delege (dedupe + doğum + makbuz orada).
+        def digest(query)
+          q = query.to_s.strip
+          raise ArgumentError, "digest: 'query' is required" if q.empty?
+
+          @gate.submit(q)
+        end
+
+        # İş kuyruğu görünürlüğü (issue #100 P2b): "yavaş kuyruk mu, düşen
+        # iş mi" ayırt edilemezdi — makbuzdan sonra recall, derleme inene
+        # dek hiçbir şey göstermiyordu. Deterministik dizgi.
+        def digest_status
+          targets = @gate.job_targets
+          if targets[:queued].empty? && targets[:in_flight].empty?
+            return "Digest queue: nothing queued, nothing in flight. " \
+                   "recall shows compiled pages; a submitted digest appears here until it compiles."
+          end
+
+          "Digest queue: #{targets[:queued].size} queued (#{targets[:queued].join(', ')}), " \
+            "#{targets[:in_flight].size} in flight (#{targets[:in_flight].join(', ')})."
+        end
+
+        # Soğuk-başlangıç yönelimi (issue #99 P2): ilk sorgu sözcük dağı
+        # tahmin etmek zorunda kalmadan hangi konular var? Aktif ve mem.*
+        # bağlı kartlar [ref, row] sırasıyla — deterministik.
+        def topics
+          bound = @store.refs.select { |ref, _| Vocabulary.memory_ref?(ref) }
+          cards = @store.list(type: "memory").select do |s|
+            s.status == Vocabulary::STATUS_ACTIVE && bound.value?(s.id)
+          end
+          if cards.empty?
+            return "No memory topics recorded yet — teach the chronicler with " \
+                   "vakanuvis(action: 'record', topic: ..., body: ...)."
+          end
+
+          lines = cards.sort_by { |s| [bound.key(s.id), s.row] }.filter_map do |s|
+            record = @store.get(type: "memory", id: s.id)
+            next unless record # list→get arası silme yarışı (review L2)
+
+            "- #{bound.key(s.id)} — #{s.title} — #{first_body_line(record)} — #{@store.uri_for('memory', s.id)}"
+          end
+          "Recorded topics (#{lines.size}):\n#{lines.join("\n")}"
+        end
+
+        private
+
+        # v2 §4-V2 + issue #99 P2: AND boşluğu tek tip körlük değil — en
+        # yakın kısmi eşleşmeler dürüstçe "(fallback)" damgasıyla sunulur
+        # (gerçek eşleşme değildir), transcript izleri kapsam ipucu olarak
+        # sayılır. Ne fallback ne transcript izi varsa bugünkü dil/terim
+        # yönlendirmesi birebir döner (keyword-AND'da en sık neden TR
+        # sorgu ↔ EN gövde uyuşmazlığıdır; yanlış "hemen yeniden kaydet"
+        # yönlendirmesi burada kesilir).
+        def relaxed_digest(query, allowed)
+          q = query.to_s.strip
+          # Süpersede edilmiş sayılar "en yakın kısmi eşleşme" olarak
+          # sunulmaz (review M1) — emekli bir sayfayı okumaya davet etmek,
+          # issue #100'ün "iki kopya, biri bozuk" bulgusunun aynısıdır.
+          relaxed = @store.search_ranked(query: q, type: allowed, require_all: false)
+                          .reject { |r| r["status"] == Vocabulary::STATUS_SUPERSEDED }
+                          .first(RECALL_FALLBACK_LIMIT)
+          transcripts = @store.search(query: q, type: "transcript")
+          if relaxed.empty? && transcripts.empty?
+            return "No chronicled knowledge matches '#{AnnalWriter.one_line(q, 80)}'. Recall is keyword-AND: retry with " \
+                   "fewer or other-language terms first (e.g. the TR/EN Keywords: lines). If the knowledge is genuinely " \
+                   "missing, record it (vakanuvis action 'record') or queue a digest."
+          end
+
+          parts = []
+          # Başlık + read_file ayağı yalnız gerçek fallback izi varken
+          # basılır (review CR#1: "yukarıdaki uri" diyecek uri yokken
+          # olmayan bir talimat modele verilmesin).
+          unless relaxed.empty?
+            parts << "No exact keyword-AND match for '#{AnnalWriter.one_line(q, 80)}' — closest partial matches (fallback, not true matches):"
+            parts.concat(relaxed.map { |r| "- (fallback) #{recall_line(r)}" })
+          end
+          unless transcripts.empty?
+            parts << "#{transcripts.size} transcript entr#{transcripts.size == 1 ? 'y' : 'ies'} mention these terms — " \
+                     "the raw session logs may hold it; queue a digest to compile them."
+          end
+          parts << "If none of these help, retry with fewer or other-language terms (the TR/EN Keywords: lines), " \
+                   "record the knowledge, or queue a digest."
+          parts << "Read a full record with read_file(path: '<uri above>')." unless relaxed.empty?
+          parts.join("\n")
+        end
+
+        def first_body_line(record)
+          slice = record["body"].to_s.lines.map(&:strip).reject(&:empty?).first.to_s.slice(0, RECALL_BODY_SLICE)
+          slice.empty? ? "(no body)" : slice
+        end
+
+        def recall_line(record)
+          "- #{record['title']} [#{record['id']}] #{first_body_line(record)} — #{@store.uri_for(record['type'], record['id'])}"
+        end
+
+        def subscribe_events
+          return unless @event_bus.respond_to?(:subscribe)
+
+          # Aboneliğin geri alımı ctx.on_dispose ile aynı nefeste (§1A):
+          # dispatcher subscribe'a verilen context'e unregister inverse'i
+          # kendisi bağlar.
+          @event_bus.subscribe(SUBAGENT_EVENT, context: @context) { |p| enqueue_event(:subagent, p) }
+          @event_bus.subscribe(GOAL_EVENT, context: @context) { |p| enqueue_event(:goal, p) }
+          return unless @root_turns
+
+          # Kök-turn kapısı knob arkasında (R7): kapalıyken abonelik hiç
+          # kurulmaz, :turn_finished olayı kronikçiye akmaz.
+          @event_bus.subscribe(TURN_EVENT, context: @context) { |p| enqueue_event(:turn, p) }
+        end
+
+        # Taşma düşürmesi asla STOP işaretini yutamaz (yutsa worker hiç
+        # sonlanamazdı): STOP geldiyse kuyruğun sonuna geri konur.
+        def drop_oldest!
+          item = @queue.pop(true)
+          if item == STOP
+            @queue.push(STOP)
+          else
+            @monitor.synchronize do
+              @dropped += 1
+              @busy -= 1
+            end
+            Vakanuvis.log_via(@dmesg, :warn, "event queue overflow — dropped oldest (total: #{@dropped})")
+          end
+        rescue ThreadError
+          nil
+        end
+
+        def run_worker
+          loop do
+            kind, payload = @queue.pop
+            break if kind == STOP
+
+            handle_event(kind, payload)
+          ensure
+            @monitor.synchronize { @busy -= 1 }
+          end
+        end
+
+        # TranscriptIndexer disiplini: kronikçinin kendi hatası akışı
+        # asla bozmaz — uyarı düşer, sonraki olay işlenir.
+        def handle_event(kind, payload)
+          case kind
+          when :subagent then handle_subagent(payload)
+          when :goal then handle_goal(payload)
+          when :turn then handle_turn(payload)
+          end
+        rescue StandardError => e
+          Vakanuvis.log_via(@dmesg, :warn, "event handling failed (#{kind}): #{e.class}: #{e.message}")
+        end
+
+        def handle_subagent(payload)
+          # Önce kronik (Düzlem 1 garantisi), sonra hasat (Düzlem 2): hasat
+          # patlarsa bile olayın annal satırı yazılmış olur — deterministik
+          # katman LLM katmanının hatasından zarar görmez.
+          seq = next_seq
+          line = AnnalWriter.subagent_line(seq, payload)
+          append_session([[event_key(payload), line]])
+          @gate.completion_event(payload)
+          maintain if flush_due?
+        end
+
+        # Kök-turn kroniği: ordinal session-slug süreç-başına mint
+        # edildiğinden harness-lokal sayaç yeterli (yeni süreç = yeni
+        # session annal; goal sırasındaki mağazadan-türetme burada
+        # gereksiz). Turn olayı flush sayacına sayılır ama koşulsuz
+        # maintain tetiklemez — turn sıklığı yüksek (R8).
+        def handle_turn(payload)
+          ordinal = @monitor.synchronize { @turn_ordinal += 1 }
+          seq = next_seq
+          append_session([AnnalWriter.turn_line(seq, ordinal, payload)])
+          maintain if flush_due?
+        end
+
+        def handle_goal(payload)
+          ordinal = next_goal_ordinal
+          enriched = payload.merge(goal_ordinal: ordinal)
+          seq = next_seq
+          goal_body = [AnnalWriter.goal_header_line(enriched[:goal])] +
+                      AnnalWriter.goal_lines(seq, enriched).map { |_k, l| l }
+          Vakanuvis.upsert(@store, type: "note", ref: Vocabulary.goal_ref(ordinal),
+                                   title: AnnalWriter.goal_title(ordinal, enriched[:goal]),
+                                   body: goal_body.join("\n"), tags: Vocabulary::ANNAL_TAGS + [Vocabulary::GOAL_TAG],
+                                   links: { "session" => Vocabulary.session_ref(@session_slug) })
+          append_session(AnnalWriter.goal_lines(seq, enriched))
+          maintain
+        end
+
+        # Goal sırası mağazadan türetilir (refs'teki en büyük annal.goal.<n>
+        # + 1): süreç yeniden başlasa bile aynı depoda numara çakışmaz —
+        # determinizm depo durumundan, saatlerden değil.
+        def next_goal_ordinal
+          @monitor.synchronize do
+            max_ref = @store.refs.keys.filter_map { |k| Vocabulary.goal_ordinal(k) }.max.to_i
+            @goal_ordinal = [@goal_ordinal, max_ref].max + 1
+          end
+        end
+
+        # Flush sayacı (R8): subagent ve turn olayları aynı ölçüde sayılır;
+        # flush_events eşiği aşılınca true döner ve sayaç sıfırlanır.
+        def flush_due?
+          @monitor.synchronize do
+            @events_since_distill += 1
+            crossed = @events_since_distill >= @flush_events
+            @events_since_distill = 0 if crossed
+            crossed
+          end
+        end
+
+        # Flush bakımı (yalnızca flush noktalarında — flush_events eşiği
+        # aşımı veya goal bitişi): kaçak memory süpürme (K9) + wiki home
+        # yeniden hesap + damıtıcı doğum kararı. v2 §4-V5: toplu doğum
+        # yalnızca kirli işaretle — kalıcı içerik değişmediyse (yalnızca
+        # turn satırları biriktiyse) damıtıcı yakılmaz.
+        def maintain
+          # Sweep record() ile aynı kilide koşar (tek-yazar disiplini):
+          # get-then-put dansı çift satır açamaz.
+          swept = @monitor.synchronize { MemorySteward.sweep_rogue_memory(@store) }
+          Vakanuvis.log_via(@dmesg, :info, "steward swept #{swept} rogue memory row(s)") if swept.positive?
+          WikiSkeleton.rebuild_home(@store)
+          @gate.flush_tick
+        end
+
+        def append_session(lines)
+          overflow = nil
+          @monitor.synchronize do
+            if @dropped.positive?
+              seq = @seq += 1
+              overflow = [["dropped.#{seq}", "- [#{seq}] #{@dropped} event(s) dropped — queue overflow (event=dropped.#{seq})"]]
+              @dropped = 0
+            end
+          end
+          AnnalWriter.append(@store, ref: Vocabulary.session_ref(@session_slug),
+                                     title: AnnalWriter.session_title(@session_slug),
+                                     lines: lines + overflow.to_a)
+        end
+
+        def next_seq = @monitor.synchronize { @seq += 1 }
+
+        def event_key(payload)
+          sid = payload[:storage_id].to_s
+          sid = payload[:id].to_s if sid.empty?
+          "subagent.#{sid}.#{payload[:state]}"
+        end
+
+        def fetch_cfg(key, default)
+          @config.respond_to?(:fetch) ? @config.fetch(key, default) : default
+        end
+      end
+    end
+  end
+end