rubik 0.1.0

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Mühimme küratörlüğü: memory kartlarının yazma disiplini (record),
+      # emeklilik politikası (forget — K2 supersede/purge) ve kaçak ham
+      # storage put'ların süpürülmesi (K9 tek-yol disiplininin son savunma
+      # hattı). Yazmaların hepsi Vakanuvis.upsert'ten geçer: ref minting,
+      # get-then-put ve hash-değişmediyse-skip bedava gelir.
+      module MemorySteward
+        module_function
+
+        # Deterministik Keywords onarımı (issue #99 P1): Keywords: satırı
+        # olmayan kart sessizce gömülür — hata yazım anında, bedava olan
+        # yerde yakalanır. Ret red değil onarımdır: gövdeye katlama-
+        # tokenize'dan çıkan en sık terimler eklenir. Onarım upsert'ten
+        # ÖNCE uygulanır: replay skip'i (content_unchanged?) onarılmış
+        # gövdeyi kıyaslar, idempotency bozulmaz.
+        KEYWORDS_LINE = /\Akeywords?:/i
+        KEYWORDS_MAX = 6
+        MIN_TERM_LENGTH = 3
+        # Katlanmış (Folding.fold) ve [a-z0-9]+ tokenize uzayında durur.
+        # DİAKRİKTİLİ TR sözcükler (ç/ğ/ö/ş/ü) tokenize'da parçalanır ve
+        # ≥3'lük parçalar süzülebilir (review CR#6: "kütüphane"→"phane"
+        # sınıfı) — onarım kalite hedefidir, recall doğruluğunu etkilemez:
+        # gövde metni zaten arama samanlığının parçasıdır. Ciddi TR kartlar
+        # için gerçek güvence eliciden yazılan Keywords: satırıdır.
+        STOPWORDS = [
+          "the", "and", "for", "are", "but", "not", "you", "your", "with", "from", "this", "that",
+          "have", "has", "had", "was", "were", "will", "would", "can", "could", "should", "into",
+          "onto", "over", "under", "then", "than", "when", "what", "which", "while", "where", "why",
+          "how", "all", "any", "some", "such", "only", "just", "also", "very", "more", "most",
+          "per", "via", "its", "does", "did", "done", "been", "being", "same", "other", "because",
+          "however", "without", "again", "both", "each", "between", "through", "during", "before",
+          "after", "above", "below", "out", "off", "use", "used", "uses", "using", "new", "old",
+          "get", "got", "set", "one", "two", "three", "first", "second", "third", "next", "last",
+          "may", "might", "must", "shall",
+          "ve", "ile", "ama", "fakat", "eger", "ancak", "daha", "bir", "bu", "su", "ne", "gibi",
+          "kadar", "sonra", "once", "var", "yok", "degil", "olan", "olur", "oldu", "ise", "cok",
+          "az", "hem", "ya", "nasil", "neden"
+        ].freeze
+
+        # Maestro talebiyle memory kartı (K7: authorship maestro'nun,
+        # yazma disiplini Düzlem 1'in). ref = mem.<slug(topic)>; aynı
+        # konuya ikinci record aynı satırı günceller (version ancak içerik
+        # değişince artar). tags (issue #99 P1): kullanıcı etiketleri
+        # Vocabulary ile birleşir — recall haystack'i etiketleri de tarar.
+        def record(store, topic:, body:, links: {}, tags: [])
+          clean_topic = topic.to_s.strip
+          raise ArgumentError, "record: 'topic' is required" if clean_topic.empty?
+          raise ArgumentError, "record: 'body' is required" if body.to_s.strip.empty?
+
+          user_tags = validate_tags(tags)
+          repaired, state = ensure_keywords(body.to_s, title: clean_topic)
+          ref = Vocabulary.memory_ref(clean_topic)
+          rec = Vakanuvis.upsert(store, type: "memory", ref: ref,
+                                        title: AnnalWriter.one_line(clean_topic, 120),
+                                        body: repaired,
+                                        tags: (Vocabulary::MEMORY_TAGS + user_tags).uniq,
+                                        links: links)
+          { "ref" => ref, "id" => rec["id"], "version" => rec["version"], "skipped" => rec["skipped"],
+            "keywords_extracted" => state == :extracted, "keywords_state" => state.to_s }
+        end
+
+        # issue #100 P1'in ret ailesi: kullanıcı etiketleri dizgi olmalı —
+        # boolean/sayı burada, record kapısında kesilir (Store#put'tan önce).
+        def validate_tags(tags)
+          list = Array(tags)
+          list.each do |tag|
+            next if tag.is_a?(String)
+
+            raise ArgumentError,
+                  "record tags must be strings — got #{tag.class} (#{tag.inspect}). " \
+                  "Pass an array of strings."
+          end
+          list
+        end
+
+        # Gövde Keywords: satırı taşıyor mu (case-insensitive)? Taşımıyorsa
+        # deterministik terimlerden bir tane ekler. Dönüş: [gövde, durum] —
+        # durum :present (satır vardı), :extracted (eklendi) ya da :none
+        # (satır yok VE terim çıkmadı — review M4: bu düşüş sessiz
+        # kalmaz, makbuz "none" taşır ve kart yüzü uyarır).
+        def ensure_keywords(body, title: "")
+          return [body, :present] if body.lines.any? { |line| line.match?(KEYWORDS_LINE) }
+
+          terms = extract_terms("#{title}\n#{body}")
+          return [body, :none] if terms.empty?
+
+          ["#{body.rstrip}\n\nKeywords: #{terms.join('; ')}", :extracted]
+        end
+
+        # Deterministik terim çıkarımı: katlama üzerinden tokenize,
+        # stopwords ve kısa öbekler dışarı, sıra [-sıklık, ilk geçme yeri] —
+        # aynı gövde her zaman aynı satırı üretir.
+        def extract_terms(text)
+          tokens = Folding.fold(text).scan(/[a-z0-9]+/).reject do |token|
+            token.size < MIN_TERM_LENGTH || STOPWORDS.include?(token)
+          end
+          counts = Hash.new(0)
+          first_seen = {}
+          tokens.each_with_index do |token, index|
+            counts[token] += 1
+            first_seen[token] = index unless first_seen.key?(token)
+          end
+          counts.keys.sort_by { |token| [-counts[token], first_seen[token]] }.first(KEYWORDS_MAX)
+        end
+
+        # K2: retention=supersede (default) iz bırakır — status + halef
+        # link'i; retention=purge satırı sert siler (refs de düşer).
+        # Not refs'i de çözümlenir (issue #100 follow-up: notlerin yaşam
+        # döngüsü — "note yalnız birikir" gözlemi): önce memory, yoksa
+        # note; stub dizisi memory yolunda değişmez.
+        def forget(store, ref:, retention: "supersede")
+          type = "memory"
+          rec = store.get(type: type, id: ref)
+          if rec.nil?
+            type = "note"
+            rec = store.get(type: type, id: ref)
+          end
+          return { "ref" => ref.to_s, "forgot" => false } unless rec
+
+          if retention.to_s == "purge"
+            deleted = store.delete(type: type, id: rec["id"])
+            return { "ref" => ref.to_s, "forgot" => false } unless deleted
+
+            { "ref" => ref.to_s, "id" => rec["id"], "forgot" => true, "mode" => "purge", "type" => type }
+          else
+            Vakanuvis.supersede_record(store, rec, by: "forget")
+            { "ref" => ref.to_s, "id" => rec["id"], "forgot" => true, "mode" => "supersede", "type" => type }
+          end
+        end
+
+        # K9 süpürme: hiçbir mem.* alias'ına bağlı olmayan (yani ham
+        # `storage put type=memory` ile açılmış) satırları disipline
+        # sokar — başlıktan slug türet, en yeni satıra mem.<slug> ref'i
+        # bağla (bir sonraki record() artık O satırı günceller), aynı
+        # slug'a düşen eski kopyaları supersede et. Deterministik: sıra
+        # ve seçim yalnızca [row] üzerinden.
+        def sweep_rogue_memory(store)
+          bound_ids = store.refs.select { |ref, _id| Vocabulary.memory_ref?(ref) }.values
+          rows = store.list(type: "memory").reject do |s|
+            bound_ids.include?(s.id) || s.status == Vocabulary::STATUS_SUPERSEDED
+          end
+          return 0 if rows.empty?
+
+          swept = 0
+          rows.group_by { |s| Vocabulary.slug(s.title) }.each do |slug, group|
+            winner = group.max_by(&:row)
+            store.set_ref(Vocabulary.memory_ref(slug), winner.id)
+            group.reject { |s| s.id == winner.id }.each do |s|
+              rogue = store.get(type: "memory", id: s.id)
+              Vakanuvis.supersede_record(store, rogue, by: winner.id) if rogue
+            end
+            swept += group.size
+          end
+          swept
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../layout"
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Kompozisyon kökü kancası (repl/lifecycle.rb Phase 4, Storage::
+      # Service.register'dan hemen sonra — STORE coeffect'i çözülebilir
+      # olmalı): kronikçi açıksa Harness kurulur, kendi child ctx'inde
+      # yaşar (abonelik + worker geri alımları orada), VAKANUIS coeffect'i
+      # köke sağlanır (talep düzlemi aracı buradan çözer). Kapalıysa
+      # (subagents.vakanuvis.enabled=false) nil döner — kronikçi yok,
+      # aracı REQUIRES karşılanmaz ve model yüzünde görünmez.
+      module Service
+        module_function
+
+        # Test zırhı: RUBIK_TEST=1 ortamında (tüm test süiti) kronikçi
+        # varsayılan KAPALI bağlanır — gerçek shell'lerle koşan scripted
+        # provider testlerinde arka plan damıtıcı doğumları yarış açar.
+        # RUBIK_VAKANUIS_FORCE=1 zırhı devre dışı bırakır (kronikçinin
+        # kendi bağlama testleri); üretimde zırh yok, K1 gereği AÇIK.
+        def enabled?(config = nil)
+          return false if ENV["RUBIK_TEST"] == "1" && ENV["RUBIK_VAKANUIS_FORCE"] != "1"
+
+          Layout.config_get(config, "subagents.vakanuvis.enabled", true)
+        end
+
+        def bind(context_or_manager, config: nil, event_bus: nil)
+          return nil unless enabled?(config)
+
+          ctx = context_or_manager.respond_to?(:context) ? context_or_manager.context : context_or_manager
+          return nil unless ctx.respond_to?(:provide)
+
+          store = Rubik::Coeffects.get(ctx, Rubik::Coeffects::STORAGE_STORE)
+          unless store
+            Rubik::Log.warn(:storage, "vakanuvis not bound: STORAGE_STORE coeffect unsatisfied " \
+                                      "(storage.enabled=false or boot-order gap)")
+            return nil
+          end
+
+          child = ctx.respond_to?(:extend) ? ctx.extend : nil
+          unless child
+            Rubik::Log.warn(:storage, "vakanuvis bound without a disposable child ctx — worker and " \
+                                      "subscriptions live for the process lifetime")
+          end
+          unless event_bus.respond_to?(:subscribe)
+            Rubik::Log.warn(:storage, "vakanuvis bound without an event bus — the distiller stays " \
+                                      "dormant (digests queue, no harvest path)")
+          end
+
+          harness = Harness.new(
+            store: store, config: config, event_bus: event_bus,
+            supervisor: Rubik::Coeffects.get(ctx, Rubik::Coeffects::SUBAGENT_SUPERVISOR),
+            dmesg: Rubik::Coeffects.get(ctx, Rubik::Coeffects::DMESG),
+            context: child, session_slug: nil
+          )
+          # Ö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 }
+          harness.start!
+          ctx.provide(Rubik::Coeffects::VAKANUIS, harness)
+          context_or_manager.reconcile_all if context_or_manager.respond_to?(:reconcile_all)
+          harness
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Kronikçinin kelime hazinesi: ref grameri (mint + parse), etiket
+      # dağarcığı, status sözlüğü ve rakam-slug koruması — TEK ev.
+      # Store mekanik kalır: type.row çözümü alias'tan ÖNCE gelir
+      # (store.rb resolve_record), bu yüzden mint edilen HİÇBİR ref
+      # /\A[a-z]+\.\d+\z/ şekline düşmez (rakam koruması).
+      module Vocabulary
+        SLUG_MAX = 40
+        BASE_TAG = "vakanuvis"
+
+        # Etiket dağarcığı (yazar modüllerin sabitleri tek evden alınır).
+        ANNAL_TAGS  = [BASE_TAG, "annal"].freeze
+        MEMORY_TAGS = [BASE_TAG, "memory"].freeze
+        WIKI_TAGS   = [BASE_TAG, "wiki"].freeze
+        GOAL_TAG    = "goal"        # goal kayıtlarının annal etiketi üstündeki ekstrası
+        GAP_TAG     = "recall-gap"  # recall smoke iska notlarının etiketi
+
+        # Status sözlüğü — kronikçinin yazdığı/okuduğu depolama düzlemi
+        # değerleri (transcript durumları kronikçinin AYNALADIĞI subagent
+        # yaşam-döngüsü değeridir; lifecycle durumları bunun dışındadır).
+        STATUS_ACTIVE        = "active"
+        STATUS_SUPERSEDED    = "superseded"
+        TRANSCRIPT_COMPLETED = "completed"
+
+        # Store çözümleyicisinin tip.satır çarpışma biçimi: resolve_record
+        # bu şekli alias'tan ÖNCE dener — mint edilen ref bu şekle ASLA
+        # düşmez (tek Garantör: rakam koruması, aşağıda #slug).
+        TYPE_ROW_PATTERN = /\A[a-z]+\.\d+\z/
+        # Store id biçimi ("plan.3.<hash16>"; store.rb ID_PATTERN ile aynı
+        # şekil — self-contained kopya, Store'a bağımlılık açmamak için).
+        ID_SHAPE = /\A([a-z]+)\.\d+\.[0-9a-f]{16}\z/
+
+        module_function
+
+        # Deterministik slug: aynı metin ⇒ aynı slug ⇒ aynı ref (digest
+        # makbuzlarının ve mem./wiki. ref'lerin yeniden oynatılabilirliği
+        # buna dayanır). Yalnızca-rakam slug'a "n" öneki zorunlu: Store'un
+        # çözümleyicisi "wiki.42" gibi iki parçalı tip.satır formlarını ref
+        # alias'tan ÖNCE dener — çarpışma yanlış satırı ezmesi demekti.
+        def slug(text)
+          s = text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+          s = s[0, SLUG_MAX].to_s.gsub(/\A-+|-+\z/, "")
+          s = "n#{s}" if s.match?(/\A\d+\z/)
+          s.empty? ? "untitled" : s
+        end
+
+        # ---- mint ------------------------------------------------------------
+
+        def session_ref(slug) = "annal.session.#{slug}"
+
+        def goal_ref(ordinal) = "annal.goal.#{ordinal}"
+
+        def memory_ref(topic) = "mem.#{slug(topic)}"
+
+        # digest hedefi de bu
+        def wiki_ref(topic) = "wiki.#{slug(topic)}"
+
+        # Recall-gap not kartının ref'i: sayfa ref'inden türetilir. wiki
+        # olmayan bir sayfa ref'i sessizce bozuk bir alias basmamak için
+        # sınırda patlar (fail-fast — split('.') körlemesine bölme değildi).
+        def recall_gap_ref(page_ref)
+          page_slug = wiki_slug(page_ref)
+          raise ArgumentError, "recall_gap_ref: '#{page_ref}' is not a wiki.<slug> ref" if page_slug.nil?
+
+          "annal.recallgap.#{page_slug}"
+        end
+
+        HOME_REF = "wiki.home"
+
+        # ---- parse -----------------------------------------------------------
+
+        def goal_ordinal(ref)
+          m = ref.to_s.match(/\Aannal\.goal\.(\d+)\z/)
+          m && m[1].to_i
+        end
+
+        def wiki_ref?(ref) = /\Awiki\.[a-z0-9][a-z0-9-]*\z/.match?(ref.to_s)
+
+        def wiki_slug(ref)
+          m = ref.to_s.match(/\Awiki\.([a-z0-9][a-z0-9-]*)\z/)
+          m && m[1]
+        end
+
+        def memory_ref?(ref) = ref.to_s.start_with?("mem.")
+
+        def type_row_shaped?(selector) = TYPE_ROW_PATTERN.match?(selector.to_s)
+
+        def id_type(id)
+          m = id.to_s.match(ID_SHAPE)
+          m && m[1]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Ta'rih iskeleti: wiki.home indeks sayfasını deterministik yeniden
+      # hesaplar (Karpathy "compilation over retrieval" — derlenmiş sayfa
+      # seti tek bakışta görünür; home kendisi bir wiki satırıdır ama
+      # listeye asla girmez). Sıralama Store#list'in [type,row] sırası —
+      # aynı depo ⇒ aynı home gövdesi. v2 §4-V3: her satır tek satırlık
+      # ÖZET taşır (başlık+blockquote atlanır, ≤120 karakter) — LLM home'a
+      # tek bakışla hangi sayfayı çekeceğine karar verir (≤2 adım erişim).
+      module WikiSkeleton
+        module_function
+
+        SUMMARY_MAX = 120
+
+        def rebuild_home(store)
+          home = store.get(type: "wiki", id: Vocabulary::HOME_REF)
+          pages = store.list(type: "wiki").reject do |s|
+            s.status == Vocabulary::STATUS_SUPERSEDED || (home && s.id == home["id"])
+          end
+          body = pages.empty? ? "_(no compiled pages yet)_" : pages.map { |s| page_line(store, s) }.join("\n")
+          Vakanuvis.upsert(store, type: "wiki", ref: Vocabulary::HOME_REF,
+                                  title: "Compiled knowledge (wiki home)",
+                                  body: body, tags: Vocabulary::WIKI_TAGS, links: {})
+        end
+
+        # Derleme dedup adayları (issue #100 P1b): aynı başlık ya da
+        # birebir aynı gövdeyi taşıyan AKTİF sayfalar — süpersede
+        # edilenler, home ve kendisi (excluding_id) aday değildir. Sıra
+        # Store#list'in [type,row] sırası: eskisi önce, süpersede de
+        # daima eskisini bastırır. Uzun gövde kıyası örneklemli değil
+        # birebirdir — derleme çıktısı zaten sayfa boyutu sınırlıdır.
+        def find_duplicate_pages(store, title:, body:, excluding_id: nil)
+          home = store.get(type: "wiki", id: Vocabulary::HOME_REF)
+          candidates = store.list(type: "wiki").reject do |s|
+            s.status == Vocabulary::STATUS_SUPERSEDED ||
+              (home && s.id == home["id"]) ||
+              (excluding_id && s.id == excluding_id)
+          end
+          candidates.filter_map do |s|
+            record = store.get(type: "wiki", id: s.id)
+            next unless record
+
+            record if record["title"] == title || record["body"] == body
+          end
+        end
+
+        def page_line(store, summary)
+          record = store.get(type: "wiki", id: summary.id)
+          "- #{summary.title} — #{page_summary(record ? record['body'].to_s : '')} — #{store.uri_for('wiki', summary.id)}"
+        end
+
+        # Sayfanın açılış özeti: başlık/blok-alıntı atlanır, ilk dolu satır
+        # tek satıra indirilir (AnnalWriter disiplini). Özet yoksa dürüst
+        # yer tutucu — home satırı asla düşmez.
+        def page_summary(body)
+          line = body.lines.map(&:strip).reject(&:empty?)
+                     .reject { |l| l.start_with?("#", ">") }.first.to_s
+          cleaned = AnnalWriter.one_line(line, SUMMARY_MAX)
+          cleaned == "(none)" ? "(no summary yet)" : cleaned
+        end
+      end
+    end
+  end
+end

data/lib/rubik/storage/vakanuvis.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    # Vakanüvis — arka plan kronikçisi (plan 2026-10-04, kararlar K1-K9).
+    # Saray kronikcisi metaforu: maestro'nun (padişah) turn'ünü ASLA
+    # uyarmaz (re-uyandırma kümesinin tamamen dışında; yalnız dmesg/stderr),
+    # olay sınırlarında deterministik annal yazar (Düzlem 1, LLM'siz),
+    # gerektiğinde sınırlı otonomlu damıtıcı subagent doğurur (Düzlem 2,
+    # LLM'li — öneri üretir, yazmayı daima Düzlem 1 yapar).
+    #
+    #   ref grammar : annal.session.<slug> / annal.goal.<n>  (note tipi)
+    #                mem.<topic-slug>                        (memory tipi)
+    #                wiki.home / wiki.<slug>                 (wiki tipi)
+    #   konfig     : subagents.vakanuvis.* (operatör-only; K1 defaults ON)
+    #
+    # Determinizm garantileri (§4.2): kararlarda duvar saati YOK (sadece
+    # olay sırası), sabit ref grammar, her yazım ref-bazlı gerçek upsert
+    # (içerik hash'i değişmediyse put atlanır — version sabit), tek worker
+    # + FIFO kuyruk, taşmada drop-oldest + warn.
+    #
+    # Ref gramerinin, etiket dağarcığının ve status sözlüğünün TEK evi
+    # Vocabulary'dir (vakanuvis/vocabulary.rb).
+    module Vakanuvis
+      module_function
+
+      # Ref-bazlı GERÇEK upsert (Store'da ref ile ikinci put yeni satır
+      # açtığı için — store.rb §2.3 bulgusu): ref üzerinden mevcut kaydı
+      # bulur; içerik değişmediyse DOKUNMAZ (version/updated_at sabit —
+      # replay idempotent), değiştiyse AYNI id ile günceller (refs/linkler
+      # kopmaz). Dönen kayda "skipped" tanıklığı eklenir.
+      def upsert(store, type:, ref:, title:, body: "", tags: [], links: {}, status: Vocabulary::STATUS_ACTIVE)
+        existing = store.get(type: type, id: ref)
+        return existing.merge("skipped" => true) if existing && content_unchanged?(existing, title, body, tags, links, status)
+
+        store.put(type: type, title: title, body: body, tags: tags, links: links,
+                  status: status, id: existing&.[]("id"), ref: ref)
+             .merge("skipped" => false)
+      end
+
+      # K2 supersede: iz bırak — status "superseded" + superseded_by
+      # link'i (halefi kim: yeni kayıt id'si ya da "forget").
+      def supersede_record(store, record, by:)
+        links = record["links"].to_h.merge("superseded_by" => by.to_s)
+        store.put(type: record["type"], title: record["title"], body: record["body"],
+                  tags: record["tags"], links: links, status: Vocabulary::STATUS_SUPERSEDED, id: record["id"])
+      end
+
+      # Vakanüvis'in kendi dmesg etiketi (K6): sessizlik sözleşmesi
+      # gereği notice YOK — sadece dmesg/stderr düzlemi.
+      SUBSYSTEM = :storage
+
+      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)
+      end
+
+      def content_unchanged?(existing, title, body, tags, links, status)
+        existing["title"] == title.to_s &&
+          existing["body"] == body.to_s &&
+          existing["tags"] == Array(tags).map(&:to_s).reject { |t| t.strip.empty? }.uniq.sort &&
+          existing["links"] == links.to_h { |k, v| [k.to_s, v.to_s] }.sort.to_h &&
+          existing["status"] == status.to_s
+      end
+    end
+  end
+end
+
+require_relative "vakanuvis/vocabulary"
+require_relative "vakanuvis/annal_writer"
+require_relative "vakanuvis/memory_steward"
+require_relative "vakanuvis/wiki_skeleton"
+require_relative "vakanuvis/distill_gate"
+require_relative "vakanuvis/gate"
+require_relative "vakanuvis/harness"
+require_relative "vakanuvis/service"

data/lib/rubik/storage.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Rubik
+  # rubik:// URI-adreslenebilir sanal FS-DB (RubikFS): hedef, plan, bellek,
+  # wiki, transcript, inceleme ve not varlıkları için merkezi depo.
+  #
+  #   rubik://storage/index                       — merkezi indeks
+  #   rubik://storage/<project>                   — proje özeti
+  #   rubik://storage/<project>/<type>            — tip listesi
+  #   rubik://storage/<project>/<type>/<id>       — varlık (satır/karma/alias)
+  #   rubik://storage/<project>/refs/<alias>      — alias çözümü
+  #
+  # Fiziki yerleşim ~/.rubik/rubikstorage/<project>/ (Layout SSOT); varlık
+  # kimliği tip + satır + içerik karması ("plan.3.9f86d081884c7d21" — Store).
+  # Okuma düzlemi read_file URI rotaları + Render; yazma düzlemi `storage`
+  # aracı ve otomatik transcript indekslemesi (supervisor). Worktree'yi
+  # temiz tutma görevi: absorb_artifacts açıkken yeni oturum dosyaları ve
+  # subagent transcriptları aynı proje köküne yazılır (Layout).
+  module Storage
+  end
+end
+
+require_relative "storage/layout"
+require_relative "storage/store"
+require_relative "storage/render"
+require_relative "storage/service"
+require_relative "storage/uri_reader"
+require_relative "storage/transcript_indexer"
+require_relative "storage/vakanuvis"

data/lib/rubik/tools/base.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "declaration"
+
+module Rubik
+  module Tools
+    class BaseTool
+      attr_reader :name, :description, :risk, :params_schema, :aliases, :allow_additional_properties, :declaration
+
+      # Builtins pass their class-level DECLARATION constant; dynamic tools
+      # (synthesis, overlay rehydration, MCP proxies, test doubles) keep the
+      # kwargs path — both produce the same frozen Declaration. New builtins
+      # must use DECLARATION (single-source invariant).
+      def initialize(declaration_or_kwargs = {})
+        d = declaration_or_kwargs.is_a?(Declaration) ? declaration_or_kwargs : Declaration.new(**declaration_or_kwargs)
+        @declaration = d
+        @name = d.name
+        @description = d.description
+        @risk = d.risk
+        @params_schema = d.params_schema
+        @aliases = d.aliases
+        @allow_additional_properties = d.allow_additional_properties
+      end
+
+      # Policy readers project through the declaration for consumers that
+      # hold a tool instance (they never enter to_h — LLM surface stays
+      # name/description/risk/parameters).
+      def archetypes = @declaration.archetypes
+
+      def maestro_blocked? = @declaration.maestro_blocked?
+
+      def spawn? = @declaration.spawn?
+
+      def write_grant? = @declaration.write_grant?
+
+      # Executes the tool with the given arguments. Must be implemented by subclasses.
+      #
+      # @param args [Hash] keyword arguments for the tool execution
+      # @return [Rubik::Tools::Result] the result of the tool execution
+      def execute(args = {})
+        raise NotImplementedError
+      end
+
+      # Normalizes a model-supplied path filter against the tool's root
+      # directory: backslashes become slashes, "./" is stripped, and ABSOLUTE
+      # paths (C:/…, /…) are relativized when they sit inside the root.
+      # Models habitually pass absolute paths (read_file accepts them), so
+      # filters must not silently fail on them.
+      #
+      # @return [Array(String, String, nil)] [filter, error] — filter "" means
+      #   no filter (the root itself); error is a user-facing message for a
+      #   path outside the workspace, in which case filter is nil.
+      def self.normalize_path_filter(raw, root_dir)
+        filter = raw.to_s.strip.tr("\\", "/").sub(%r{^\./}, "")
+        return ["", nil] if filter.empty? || filter == "." || filter == "/"
+
+        norm_root = root_dir.to_s.tr("\\", "/").sub(%r{/+\z}, "")
+        if filter.downcase == norm_root.downcase
+          return ["", nil]
+        elsif filter.downcase.start_with?("#{norm_root.downcase}/")
+          sub_path = filter[(norm_root.length + 1)..]
+          return [sub_path, nil]
+        end
+
+        return [filter, nil] unless filter =~ %r{\A([A-Za-z]:/|/)}
+
+        rel = begin
+          Pathname.new(File.expand_path(filter)).relative_path_from(Pathname.new(File.expand_path(root_dir))).to_s.tr("\\", "/")
+        rescue ArgumentError
+          nil
+        end
+        outside = rel.nil? || rel == ".." || rel.start_with?("../")
+        if outside
+          return [nil, "Path '#{raw}' is outside the project workspace (#{root_dir}). " \
+                       "Use a path relative to the project root, e.g. 'lib'."]
+        end
+        return ["", nil] if rel == "."
+
+        [rel, nil]
+      end
+
+      # Friendly no-match message that echoes the filter and states the
+      # relative-path convention, so the model corrects itself instead of
+      # retrying the same failing call.
+      def self.no_match_message(filter)
+        hint = " Tip: 'path' is relative to the project root (e.g. 'lib', 'src/main.go'); " \
+               "absolute paths are converted automatically."
+        "No matching files found for '#{filter}'.#{hint}"
+      end
+
+      def to_h
+        schema = @params_schema
+        if !@allow_additional_properties && schema.is_a?(Hash)
+          schema = schema.dup
+          schema[:additionalProperties] = false unless schema.key?(:additionalProperties) || schema.key?("additionalProperties")
+        end
+        {
+          name: @name,
+          description: @description,
+          risk: @risk,
+          parameters: schema
+        }
+      end
+    end
+  end
+end