rubik 0.4.2 → 0.5.0

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

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "../layout"
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Soğuk-başlangıç ve sıkıştırma sonrası yönelim enjeksiyonu (issue #340):
+      # Sistem istemi (system prompt) hiç şişirilmeden, oturumun ilk model
+      # çağrısından önce ve her bağlam sıkıştırması / budaması tamamlandığında
+      # kök konuşma geçmişine kısa, deterministik bir `role: "user"` yönelim
+      # iletisi eklenir. Kart yoksa (N == 0), kronikçi kapalıysa veya
+      # `subagents.vakanuvis.orientation == false` ise hiçbir şey enjekte
+      # edilmez. Kanca `ctx` içine tersiyle (`on_dispose`) kaydedilir (§1A).
+      module Orientation
+        DEFAULT_MAX_TOPICS = 10
+        HOOK_KEY = :vakanuvis_orientation_hook
+        TAG_OPEN = "<vakanuvis_orientation>"
+        TAG_CLOSE = "</vakanuvis_orientation>"
+        DEPTH_HINT = "Ask `vakanuvis(action: 'recall', query: '<2-3 terms>')` for depth."
+
+        # Oturum-içi durum ve terslenebilir kanca taşıyıcısı.
+        class Hook
+          attr_reader :harness
+
+          def initialize(harness, config: nil)
+            @harness = harness
+            @config = config
+            @session_oriented = false
+            @disposed = false
+          end
+
+          def dispose!
+            @disposed = true
+            @session_oriented = false
+          end
+
+          def disposed?
+            @disposed
+          end
+
+          def reset_session!
+            @session_oriented = false
+          end
+
+          def enabled?(override_config = nil)
+            return false if @disposed || @harness.nil? || @harness.stopped?
+
+            cfg = override_config || @config || @harness.config
+            return false unless Service.enabled?(cfg)
+
+            Layout.config_get(cfg, "subagents.vakanuvis.orientation", true) != false
+          end
+
+          def max_topics(override_config = nil)
+            cfg = override_config || @config || @harness.config
+            raw = Layout.config_get(cfg, "subagents.vakanuvis.orientation_max_topics", DEFAULT_MAX_TOPICS)
+            val = raw.to_i
+            val.positive? ? val : DEFAULT_MAX_TOPICS
+          end
+
+          def build_message(override_config = nil)
+            return nil unless enabled?(override_config)
+
+            excerpt = Orientation.format_excerpt(@harness, limit: max_topics(override_config))
+            return nil unless excerpt
+
+            { role: "user", content: excerpt }
+          end
+
+          def inject_session_start!(history, config: nil)
+            return nil unless history.is_a?(Array)
+
+            if history.any? { |m| Orientation.orientation_message?(m) }
+              @session_oriented = true
+              return nil
+            end
+            return nil if @session_oriented
+            return nil unless enabled?(config)
+
+            msg = build_message(config)
+            return nil unless msg
+
+            @session_oriented = true
+            Orientation.deduplicate_and_insert_start!(history, msg)
+          end
+
+          def inject_after_compaction!(history, config: nil)
+            return nil unless history.is_a?(Array)
+
+            Orientation.strip_orientation_messages!(history)
+            return nil unless enabled?(config)
+
+            msg = build_message(config)
+            return nil unless msg
+
+            @session_oriented = true
+            Orientation.insert_after_compaction!(history, msg)
+          end
+        end
+
+        module_function
+
+        # Kancayı `ctx` (veya child sub-context) içine tersiyle kaydeder (§1A).
+        # Kronikçi devre dışı bırakıldığında veya child dispose edildiğinde
+        # kanca otomatik olarak sökülür; reload döngülerinde yetim kanca kalmaz.
+        def register_hook(ctx, harness, config: nil, inverse_ctx: nil)
+          return nil unless ctx.respond_to?(:provide) && harness
+
+          cfg = config || harness.config
+          hook = Hook.new(harness, config: cfg)
+          ctx.provide(HOOK_KEY, hook)
+          target_ctx = inverse_ctx || ctx
+          cfg_inverse = wire_config_observer(ctx, hook, cfg)
+          if target_ctx.respond_to?(:on_dispose)
+            target_ctx.on_dispose do
+              cfg_inverse&.call
+              hook.dispose!
+              ctx.unprovide(HOOK_KEY) if ctx.respond_to?(:unprovide) && ctx.get(HOOK_KEY).equal?(hook)
+            end
+          end
+          hook
+        end
+
+        def wire_config_observer(ctx, hook, cfg)
+          return nil unless cfg.respond_to?(:on_change)
+
+          cfg.on_change("subagents.vakanuvis") do |_key, _val, _old|
+            next if hook.disposed?
+
+            if hook.enabled?(cfg)
+              ctx.provide(HOOK_KEY, hook) unless ctx.get(HOOK_KEY).equal?(hook)
+            elsif ctx.respond_to?(:unprovide) && ctx.get(HOOK_KEY).equal?(hook)
+              ctx.unprovide(HOOK_KEY)
+            end
+          end
+        end
+
+        # Coeffect üzerinden kancayı veya doğrudan VAKANUIS harness'ini çözer.
+        # VAKANUIS coeffect'i karşılanmamışsa nil döner.
+        def resolve_hook(context_or_manager, config: nil)
+          ctx = extract_context(context_or_manager)
+          return nil unless ctx
+
+          harness = Rubik::Coeffects.get(ctx, Rubik::Coeffects::VAKANUIS)
+          return nil unless harness.is_a?(Harness) && !harness.stopped?
+
+          cfg = config || harness.config
+          return nil unless Service.enabled?(cfg)
+          return nil if Layout.config_get(cfg, "subagents.vakanuvis.orientation", true) == false
+
+          hook = Rubik::Coeffects.get(ctx, HOOK_KEY)
+          return hook if hook.is_a?(Hook) && !hook.disposed? && hook.harness.equal?(harness)
+
+          register_hook(ctx, harness, config: cfg)
+        end
+
+        def reset_session!(context_or_manager)
+          ctx = extract_context(context_or_manager)
+          return false unless ctx
+
+          hook = Rubik::Coeffects.get(ctx, HOOK_KEY)
+          hook.reset_session! if hook.is_a?(Hook)
+          true
+        end
+
+        def inject_session_start!(history, context_or_manager, config: nil)
+          hook = resolve_hook(context_or_manager, config: config)
+          return nil unless hook
+
+          hook.inject_session_start!(history, config: config)
+        end
+
+        def inject_after_compaction!(history, context_or_manager, config: nil)
+          strip_orientation_messages!(history) if history.is_a?(Array)
+          hook = resolve_hook(context_or_manager, config: config)
+          return nil unless hook
+
+          hook.inject_after_compaction!(history, config: config)
+        end
+
+        # Aktif mem.* kartlarını [ref, row] sırasıyla listeler.
+        # Dönen çift: [lines_array, total_active_cards_count].
+        def topic_lines(store, limit: nil)
+          return [[], 0] unless store
+
+          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
+          return [[], 0] if cards.empty?
+
+          all_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
+          total = all_lines.size
+          shown = limit ? all_lines.first(limit.to_i) : all_lines
+          [shown, total]
+        end
+
+        def first_body_line(record)
+          slice = record["body"].to_s.lines.map(&:strip).reject(&:empty?).first.to_s.slice(0, Harness::RECALL_BODY_SLICE)
+          slice.empty? ? "(no body)" : slice
+        end
+
+        # Aktif mem.* kartlarından deterministik [ref, row] sırasıyla en fazla
+        # `limit` satır üretir. Aktif kart yoksa (N == 0) nil döner.
+        def format_excerpt(harness, limit: DEFAULT_MAX_TOPICS)
+          store = harness.respond_to?(:store) ? harness.store : nil
+          lines, total = topic_lines(store, limit: limit)
+          return nil if lines.empty?
+
+          count_label = total > lines.size ? "#{lines.size} of #{total}" : lines.size.to_s
+          "#{TAG_OPEN}\nRecorded topics (#{count_label}):\n#{lines.join("\n")}\n#{DEPTH_HINT}\n#{TAG_CLOSE}"
+        end
+
+        def orientation_message?(msg)
+          return false unless msg.is_a?(Hash)
+
+          role = (msg[:role] || msg["role"]).to_s
+          return false unless role == "user"
+
+          content = (msg[:content] || msg["content"]).to_s
+          content.include?(TAG_OPEN) && content.include?(DEPTH_HINT)
+        end
+
+        def strip_orientation_messages!(history)
+          return history unless history.is_a?(Array)
+
+          history.reject! { |msg| orientation_message?(msg) }
+          history
+        end
+
+        # Oturum başında: sistem mesajı varsa hemen ardına (ilk user mesajından
+        # önce), yoksa dizinin başına yerleştirir. Eski kopyaları temizler.
+        def deduplicate_and_insert_start!(history, msg)
+          strip_orientation_messages!(history)
+          idx = first_non_system_index(history)
+          history.insert(idx, msg)
+          msg
+        end
+
+        # Sıkıştırma sonrasında: eski yönelim iletilerini siler ve yeni yönelim
+        # iletisini sistem mesajlarının hemen ardına deterministik olarak ekler.
+        def insert_after_compaction!(history, msg)
+          strip_orientation_messages!(history)
+          idx = first_non_system_index(history)
+          history.insert(idx, msg)
+          msg
+        end
+
+        def first_non_system_index(history)
+          idx = history.index do |m|
+            role = m.is_a?(Hash) ? (m[:role] || m["role"]).to_s : ""
+            role != "system"
+          end
+          idx || history.size
+        end
+
+        def extract_context(context_or_manager)
+          return nil unless context_or_manager
+
+          if context_or_manager.respond_to?(:context)
+            context_or_manager.context
+          elsif context_or_manager.respond_to?(:runtime_manager) && context_or_manager.runtime_manager.respond_to?(:context)
+            context_or_manager.runtime_manager.context
+          else
+            context_or_manager
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -57,7 +57,11 @@ module Rubik
           )
           # Ömür (§2.7): child ctx'in cascade inverse'i worker'ı kapatır;
           # kuyruk FIFO'su drain olur, yarım kronik kalmaz.
-          child&.on_dispose { harness.shutdown }
+          child&.on_dispose do
+            harness.shutdown
+            ctx.unprovide(Rubik::Coeffects::VAKANUIS) if ctx.respond_to?(:unprovide) && ctx.get(Rubik::Coeffects::VAKANUIS).equal?(harness)
+          end
+          Orientation.register_hook(ctx, harness, config: config, inverse_ctx: child)
           harness.start!
           ctx.provide(Rubik::Coeffects::VAKANUIS, harness)
           context_or_manager.reconcile_all if context_or_manager.respond_to?(:reconcile_all)

data/lib/rubik/storage/vakanuvis.rb

@@ -50,10 +50,16 @@ module Rubik
       # gereği notice YOK — sadece dmesg/stderr düzlemi.
       SUBSYSTEM = :storage
 
+      # Konu-adlı uyarıların SON İZİ buradır: iki havuz da patlarsa bile
+      # mesaj stderr'e düşer — kayıp iz yok (review #346 F2).
       def log_via(dmesg, level, message)
         dmesg.respond_to?(:log) ? dmesg.log(SUBSYSTEM, level, message) : Rubik::Log.send(level, SUBSYSTEM, message)
       rescue StandardError
-        Rubik::Log.warn(SUBSYSTEM, message)
+        begin
+          Rubik::Log.warn(SUBSYSTEM, message)
+        rescue StandardError
+          warn("[vakanuvis] #{message}")
+        end
       end
 
       def content_unchanged?(existing, title, body, tags, links, status)
@@ -74,4 +80,5 @@ require_relative "vakanuvis/wiki_skeleton"
 require_relative "vakanuvis/distill_gate"
 require_relative "vakanuvis/gate"
 require_relative "vakanuvis/harness"
+require_relative "vakanuvis/orientation"
 require_relative "vakanuvis/service"

data/lib/rubik/tools/builtins/vakanuvis.rb

@@ -24,15 +24,12 @@ module Rubik
       DECLARATION = Declaration.new(
         name: "vakanuvis", aliases: ["chronicler"],
         description: "Ask the background chronicler (compiled knowledge in rubik://storage): " \
-                     "'recall' (deterministic digest over memory+wiki with source links — ask at task start " \
-                     "and after compaction), 'record' (persist durable knowledge as a memory card; the ONE " \
-                     "path for memory writes), 'forget' (supersede/purge a mem.* card or a note), 'digest' (queue an " \
-                     "async wiki compilation; returns a deterministic receipt, never blocks on the LLM), " \
-                     "'topics' (list recorded memory topics — orient before the first query), 'digest_status' " \
-                     "(is my queued digest pending, in flight, or done?). Notes (annal.*) are the chronicler's " \
-                     "evidence layer; memory cards are the durable conclusions you want recalled by default. " \
-                     "Hygiene: same topic, same session = one note — update it (or retire it with forget; " \
-                     "superseded rows keep a trace).",
+                     "'recall' (deterministic digest over memory+wiki with source links — ask at task start), " \
+                     "'record' (persist durable knowledge as a memory card; the ONE path for memory writes), " \
+                     "'forget' (supersede/purge a mem.* card or a note), 'digest' (queue an async wiki compilation; " \
+                     "returns a deterministic receipt, never blocks on the LLM), 'topics' (list recorded memory topics " \
+                     "— orient before the first query), 'digest_status' (is my queued digest pending, in flight, or done?). " \
+                     "Notes (annal.*) are the chronicler's evidence layer; memory cards are the durable conclusions you want recalled by default.",
         risk: :write, archetypes: [], write_grant: false,
         maestro_blocked: false, # storage emsali: kronikçi düzlemi kökte doğrudan
         params_schema: {
@@ -42,9 +39,11 @@ module Rubik
               type: "string", enum: ["recall", "record", "forget", "digest", "topics", "digest_status"],
               description: "Operation (default: 'recall')."
             },
-            query: { type: "string",
-                     description: "recall/digest: knowledge query. Recall is keyword-AND — every space-separated " \
-                                  "term must literally appear; retry with other-language synonyms when empty." },
+            query: {
+              type: "string",
+              description: "recall/digest: knowledge query. Recall is keyword-AND — use 2-3 core terms (every " \
+                           "space-separated term must literally appear); retry with other-language synonyms when empty."
+            },
             types: {
               type: "array", items: { type: "string", enum: ["memory", "wiki", "note"] },
               description: "recall: entity scopes to search (default: memory + wiki)."
@@ -52,9 +51,8 @@ module Rubik
             topic: { type: "string", description: "record: card topic — mints ref mem.<topic-slug> (upsert by topic)." },
             body: {
               type: "string",
-              description: "record: card body (markdown; end it with a Keywords: line of 5-10 TR+EN synonyms so " \
-                           "keyword-AND recall can find the card — a missing Keywords: line is auto-extracted " \
-                           "from the body at write time)."
+              description: "record: card body (markdown; end it with a Keywords: line of 5-10 TR+EN synonyms if you " \
+                           "can — a missing Keywords: line is auto-extracted from the body at write time)."
             },
             tags: {
               type: "array", items: { type: "string" },

data/lib/rubik/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubik
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubik
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Özgür Ulukır
@@ -721,6 +721,7 @@ files:
 - lib/rubik/storage/vakanuvis/gate.rb
 - lib/rubik/storage/vakanuvis/harness.rb
 - lib/rubik/storage/vakanuvis/memory_steward.rb
+- lib/rubik/storage/vakanuvis/orientation.rb
 - lib/rubik/storage/vakanuvis/service.rb
 - lib/rubik/storage/vakanuvis/vocabulary.rb
 - lib/rubik/storage/vakanuvis/wiki_skeleton.rb