rubik 0.1.0

data/lib/rubik/orchestrator/goal_ledger/validator.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module GoalLedger
+      # Atomic validate-then-apply. Op'lar sırayla, ÖNCEKİ op'ların
+      # uygulanmış olduğu working copy üzerinde valide edilir (RFC 6902
+      # semantiği); fail-fast YOK — tüm op'lar teşhis edilir ki tek retry
+      # her şeyi düzeltsin (bounded-retry bütçesi: DEFAULT_MAX_RETRIES;
+      # retry loop'unu feature katmanı yazar). Herhangi bir reason düşerse
+      # working copy ÇÖPE gider ve current_doc HİÇ dokunulmadan döner —
+      # §1.A "atomic failure rollback"in veri-düzlemi ikizi. Kabul edilirse
+      # rev tam olarak bir artar ve sonuç deep-frozen döner (doküman
+      # cap'lidir; validator'u dökümanı sınırsız büyütecek şekilde çağırmak
+      # sözleşme dışıdır).
+      module Validator
+        module_function
+
+        # patch_or_text: String (önce parse edilir) | GoalLedger::Patch
+        # -> [:ok, new_doc, new_rev] | [:rejected, [reason, ...]]
+        # Model girdisinde ASLA raise etmez (her başarısızlık veridir);
+        # yalnız programcı hatası ArgumentError'a düşer.
+        def validate(patch_or_text, schema:, current_doc:)
+          raise ArgumentError, "schema must be a GoalLedger::Schema" unless schema.is_a?(Schema)
+
+          verdict = patch_or_text.is_a?(Patch) ? [:ok, patch_or_text] : Patch.parse(patch_or_text)
+          return verdict unless verdict[0] == :ok
+
+          patch = verdict[1]
+          current_rev = current_doc.is_a?(Hash) ? current_doc["rev"] : nil
+          unless current_rev.is_a?(Integer)
+            return [:rejected, [rejection(:conflict, nil, "", "the current ledger has no integer rev",
+                                          "re-read the ledger — it may not be initialized yet")]]
+          end
+
+          # :conflict — küçük-model taksonomisinin %68'i (premature state
+          # overwrite) burada deterministik olarak durur; ESKİ doküman
+          # korunur, model güncel rev'e karşı yeniden yazmak zorundadır.
+          if patch.rev != current_rev
+            return [:rejected, [rejection(:conflict, nil, "",
+                                          "patch rev #{patch.rev} does not match ledger rev #{current_rev}",
+                                          "re-read the ledger (rev #{current_rev}) and re-emit the patch " \
+                                          "against it — your view is stale")]]
+          end
+
+          working = deep_dup(current_doc)
+          reasons = []
+          patch.ops.each do |op|
+            # Patch.parse op değerlerini deep-frozen taşır (VO sözleşmesi);
+            # working copy'ye SICAK kopyası yerleşir — yoksa sonraki op'lar
+            # frozen Hash'lere yazmaya çalışır (sequential-op semantiği).
+            op = { **op, value: deep_dup(op[:value]) } if op[:value]
+            reasons.concat(apply_op(op, schema, working))
+          end
+          return [:rejected, reasons] unless reasons.empty?
+
+          working["rev"] = current_rev + 1
+          [:ok, deep_freeze(working), working["rev"]]
+        end
+
+        # ---- op dispatch ----
+
+        def apply_op(op, schema, doc)
+          head = op[:tokens][0]
+          section = schema.sections[head]
+          return section_op(op, head, section, doc) if section
+
+          field = schema.root_scalars[head]
+          return root_scalar_op(op, head, field, doc) if field
+
+          patchable = schema.root_scalars.keys.reject { |key| schema.root_scalars[key].managed }
+          [rejection(:schema, op[:index], op[:path], "unknown ledger section '#{head}'",
+                     "known sections: #{schema.sections.keys.join(', ')}; root fields: #{patchable.join(', ')}")]
+        end
+
+        def root_scalar_op(op, name, spec, doc)
+          if spec.managed
+            return [rejection(:schema, op[:index], op[:path], "'#{name}' is runtime-managed",
+                              "send the current rev in the patch header; the runtime writes it")]
+          end
+
+          if op[:op] == :remove
+            return [rejection(:schema, op[:index], op[:path], "the '#{name}' field is required",
+                              "replace it instead of removing it (#{op[:path]} with a new value)")]
+          end
+
+          err = check_value(spec, op[:value], name, op)
+          return [err] if err
+
+          doc[name] = op[:value] # add == replace, RFC 6902 üye semantiği
+          []
+        end
+
+        def section_op(op, name, section, doc)
+          coll = doc[name]
+          unless coll.is_a?(Array)
+            return [rejection(:schema, op[:index], op[:path], "section '#{name}' is not a list in the current ledger",
+                              "the ledger may be corrupted — re-read it before patching")]
+          end
+
+          return [section_head_rejection(op, name)] if op[:tokens].size == 1
+
+          return element_op(op, name, section, coll, op[:tokens][1]) if section.scalar
+
+          item_op(op, name, section.item, coll)
+        end
+
+        # Derinlik 1 (bütünsel section yazımı) — üç fiil de yapısal red.
+        def section_head_rejection(op, name)
+          lead = case op[:op]
+                 when :replace then "wholesale section rewrite is not allowed"
+                 when :add then "cannot add the section '#{name}' itself"
+                 else "sections are structural"
+                 end
+          rejection(:schema, op[:index], op[:path], lead,
+                    "address items individually (/#{name}/3, /#{name}/-) — one op per item")
+        end
+
+        # ---- skalar liste (open_questions) ----
+
+        def element_op(op, name, section, coll, idx_tok)
+          if op[:tokens].size > 2
+            return [rejection(:schema, op[:index], op[:path],
+                              "paths deeper than two levels are not supported in string lists like #{name}",
+                              "address elements directly (/#{name}/0, /#{name}/-)")]
+          end
+
+          spec = FieldSpec.new(type: section.scalar, max_len: section.max_len)
+          if idx_tok == "-"
+            return [append_only_rejection(op, name)] unless op[:op] == :add
+
+            err = check_value(spec, op[:value], name, op)
+            return [err] if err
+
+            coll << op[:value]
+            return []
+          end
+
+          idx = index_token(idx_tok, name, coll, op, insertable: op[:op] == :add)
+          return [idx] unless idx.is_a?(Integer)
+
+          err = op[:op] == :remove ? nil : check_value(spec, op[:value], name, op)
+          return [err] if err
+
+          if op[:op] == :add
+            coll.insert(idx, op[:value])
+          elsif op[:op] == :replace
+            coll[idx] = op[:value]
+          else
+            coll.delete_at(idx)
+          end
+          []
+        end
+
+        # ---- item listesi (tasks/findings/...) ----
+
+        def item_op(op, name, spec, coll)
+          return whole_item_op(op, name, spec, coll, op[:tokens][1]) if op[:tokens].size == 2
+          if op[:tokens].size > 3
+            return [rejection(:schema, op[:index], op[:path],
+                              "paths deeper than three levels are not supported in item lists like #{name}",
+                              "address items and their fields directly (e.g. /tasks/3/status)")]
+          end
+
+          field_op(op, name, spec, coll, op[:tokens][1])
+        end
+
+        def whole_item_op(op, name, spec, coll, idx_tok)
+          if idx_tok == "-"
+            return [append_only_rejection(op, name)] unless op[:op] == :add
+
+            errs = validate_item_object(spec, op[:value], name, op)
+            return errs unless errs.empty?
+
+            coll << op[:value]
+            return dup_id_rejections(coll, spec, name, op)
+          end
+
+          idx = index_token(idx_tok, name, coll, op, insertable: op[:op] == :add)
+          return [idx] unless idx.is_a?(Integer)
+
+          if op[:op] == :remove
+            coll.delete_at(idx)
+            return []
+          end
+
+          errs = validate_item_object(spec, op[:value], name, op)
+          return errs unless errs.empty?
+
+          op[:op] == :add ? coll.insert(idx, op[:value]) : coll[idx] = op[:value]
+          dup_id_rejections(coll, spec, name, op)
+        end
+
+        def field_op(op, name, spec, coll, idx_tok)
+          idx = index_token(idx_tok, name, coll, op, insertable: false)
+          return [idx] unless idx.is_a?(Integer)
+
+          field_name = op[:tokens][2]
+          field = spec.fields[field_name]
+          unless field
+            return [rejection(:schema, op[:index], op[:path], "unknown field '#{field_name}' on #{name} items",
+                              "allowed fields: #{spec.fields.keys.join(', ')}")]
+          end
+
+          if op[:op] == :remove
+            nullable = spec.fields.select { |_, item_field| item_field.allow_null }.keys.join(", ")
+            return [rejection(:schema, op[:index], op[:path], "fields are not removable",
+                              "replace with null where allowed (#{nullable}) or remove the item (/#{name}/#{idx})")]
+          end
+
+          err = check_value(field, op[:value], "#{name}.#{field_name}", op)
+          return [err] if err
+
+          coll[idx][field_name] = op[:value]
+          spec.id_field == field_name ? dup_id_rejections(coll, spec, name, op) : []
+        end
+
+        # ---- değer kontrolü ----
+
+        def check_value(spec, value, where, op)
+          if value.nil? && !spec.allow_null
+            parent = op[:tokens].size >= 3 ? "/#{op[:tokens][0..-2].join('/')}" : op[:path]
+            return rejection(:schema, op[:index], op[:path], "#{where} does not accept null",
+                             "null does not delete; use remove on the item (#{parent})")
+          end
+          return nil if value.nil?
+
+          type_err = check_type(spec, value, where, op)
+          return type_err if type_err
+
+          return nil unless spec.enum && !spec.enum.include?(value)
+
+          rejection(:schema, op[:index], op[:path],
+                    "#{where} must be one of #{spec.enum.join(', ')} (got '#{value}')",
+                    "pick from the allowed vocabulary")
+        end
+
+        def check_type(spec, value, where, op)
+          case spec.type
+          when :string
+            unless value.is_a?(String)
+              return rejection(:schema, op[:index], op[:path],
+                               "#{where}: expected string, got #{GoalLedger.json_type_name(value)}",
+                               "use JSON types — strings are quoted, integers bare")
+            end
+            if spec.max_len && value.length > spec.max_len
+              return rejection(:schema, op[:index], op[:path],
+                               "#{where} is #{value.length} chars; the cap is #{spec.max_len}",
+                               "shorten the value — caps are deterministic (no stripping)")
+            end
+          when :integer
+            unless value.is_a?(Integer)
+              detail = value.is_a?(Float) ? "floats are not integers — send a whole number" : "expected integer"
+              return rejection(:schema, op[:index], op[:path],
+                               "#{where}: #{detail}, got #{GoalLedger.json_type_name(value)}",
+                               "integers are bare numbers without a decimal point")
+            end
+          when :boolean
+            unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+              return rejection(:schema, op[:index], op[:path],
+                               "#{where}: expected boolean, got #{GoalLedger.json_type_name(value)}",
+                               "booleans are the bare literals true and false")
+            end
+          when :object
+            unless value.is_a?(Hash)
+              return rejection(:schema, op[:index], op[:path],
+                               "#{where}: expected object, got #{GoalLedger.json_type_name(value)}",
+                               "objects are brace-delimited key-value maps")
+            end
+          end
+          nil
+        end
+
+        def validate_item_object(spec, value, name, op)
+          unless value.is_a?(Hash)
+            return [rejection(:schema, op[:index], op[:path],
+                              "supply the full #{name} item as a JSON object (got #{GoalLedger.json_type_name(value)})",
+                              "or address the field directly (#{op[:path]}/<field>, e.g. #{op[:path]}/status)")]
+          end
+
+          reasons = []
+          unknown = value.keys - spec.fields.keys
+          unless unknown.empty?
+            reasons << rejection(:schema, op[:index], op[:path],
+                                 "unknown field(s) #{unknown.join(', ')} on #{name} items",
+                                 "allowed fields: #{spec.fields.keys.join(', ')}")
+          end
+          missing = spec.fields.reject { |fname, item_field| item_field.optional || value.key?(fname) }.keys
+          unless missing.empty?
+            reasons << rejection(:schema, op[:index], op[:path],
+                                 "missing required field(s) #{missing.join(', ')}",
+                                 "supply the full item object or address the field directly (/#{name}/3/<field>)")
+          end
+          value.each do |fname, item_value|
+            field = spec.fields[fname]
+            next unless field
+
+            err = check_value(field, item_value, "#{name}.#{fname}", op)
+            reasons << err if err
+          end
+          reasons
+        end
+
+        # ---- ortak yardımcılar ----
+
+        def index_token(tok, name, coll, op, insertable:)
+          unless tok.is_a?(String) && tok.match?(/\A\d+\z/)
+            return rejection(:schema, op[:index], op[:path], "expected an item index in #{name}, got '#{tok}'",
+                             "numeric indices address existing items; '-' appends")
+          end
+          idx = tok.to_i
+          upper = insertable ? coll.size : coll.size - 1
+          return idx if idx <= upper
+
+          message = coll.empty? ? "#{name} is empty — nothing to address yet" : "#{name} has #{coll.size} item(s); valid indices 0-#{coll.size - 1}"
+          rejection(:schema, op[:index], op[:path], message, "append via /#{name}/-")
+        end
+
+        def append_only_rejection(op, name)
+          rejection(:schema, op[:index], op[:path], "'-' appends; it cannot address an existing #{name} item",
+                    "use a numeric index for replace/remove")
+        end
+
+        def dup_id_rejections(coll, spec, name, op)
+          return [] unless spec.id_field
+
+          ids = coll.filter_map { |item| item.is_a?(Hash) ? item[spec.id_field] : nil }
+          dups = ids.tally.select { |_, count| count > 1 }.keys
+          return [] if dups.empty?
+
+          [rejection(:schema, op[:index], op[:path], "duplicate #{name} id '#{dups.first}'; ids must be unique within #{name}",
+                     "pick a fresh id (e.g. a letter prefix plus the step number)")]
+        end
+
+        def rejection(kind, op_index, path, message, hint)
+          GoalLedger.reason(kind, op_index: op_index, path: path, message: message, hint: hint)
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash then value.to_a.to_h { |key, val| [key.dup, deep_dup(val)] }
+          when Array then value.map { |val| deep_dup(val) }
+          else value
+          end
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash then value.each do |key, val|
+            deep_freeze(key)
+            deep_freeze(val)
+          end.freeze
+          when Array then value.each { |val| deep_freeze(val) }.freeze
+          when String then value.dup.freeze
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/goal_ledger/verifier.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "verify_spec"
+
+module Rubik
+  module Orchestrator
+    module GoalLedger
+      # Tri-state FS doğrulaması (goal-ledger planı B). SAF değerlendirme:
+      # ledger'ın Monitor'lu SNAPSHOT'ı üzerinde çalışır, tüm FS IO kilit
+      # DIŞINDADır; flip kararı Drift/apply_internal_drift!'e aittir.
+      #
+      # Tri-state sözleşmesi (exhaustive honesty): ok = containment kanıtlı
+      # + predicate doğru; failed = containment kanıtlı + predicate yanlış
+      # (task → stale, env note → annotate); unknown = KANITLANAMAZ
+      # (workspace dışı, EACCES/EPERM, kesilmiş okumada needle yokluğu,
+      # malformed spec) — status flip YAPMAZ, yalnızca raporlanır.
+      module Verifier
+        module_function
+
+        # Adım sınırı girişi (loop.rb execute_steps hook'u): knob FIRST —
+        # kapalıysa hiç dokunma. goal_mode? guard'ı çağıran taraftadır.
+        def at_step_boundary!(loop_inst)
+          ledger = Rubik::Coeffects.get(loop_inst.runtime_manager&.context, Rubik::Coeffects::GOAL_LEDGER)
+          return nil unless ledger
+
+          verify!(ledger, trigger: :step, root_dir: loop_inst.buffer_manager&.root_dir || Dir.pwd,
+                          config: loop_inst.config)
+        end
+
+        # -> nil (knob off / boş) | {rev:, flipped:, unknowns:, note:}
+        def verify!(ledger, trigger:, root_dir:, config: nil)
+          return nil unless Ledger.verify_enabled?(config)
+
+          snap = ledger.snapshot_doc
+          flips, unknowns = evaluate(snap, root_dir)
+          return nil if flips.empty? && unknowns.empty?
+
+          outcome = flips.empty? ? nil : ledger.apply_internal_drift!(flips)
+          Drift.emit(trigger: trigger, ledger: ledger, flips: flips, unknowns: unknowns, rev: outcome&.dig(:rev))
+          { rev: outcome&.dig(:rev), flipped: flips.size, unknowns: unknowns,
+            note: flips.empty? ? nil : DriftNote.render(snap: ledger.snapshot_doc) }
+        end
+
+        # Kilit dışı: snapshot frozen Hash'lerdir; yalnız disk okunur.
+        def evaluate(snap, root_dir)
+          flips = []
+          unknowns = []
+          collect(snap, "tasks", root_dir, flips, unknowns)
+          collect(snap, "environment_notes", root_dir, flips, unknowns)
+          [flips, unknowns]
+        end
+
+        def collect(snap, collection, root_dir, flips, unknowns)
+          items = snap[collection]
+          return unless items.is_a?(Array)
+
+          if items.size > VerifySpec::MAX_SPECS_PER_COLLECTION * 4
+            # Flood guardı artık sessiz değil (review 2026-10-10): atlanan
+            # inceleme toplu unknown olarak görünür — asla sessiz spec düşme.
+            unknowns << { collection: collection, index: nil, id: "",
+                          reason: "collection exceeds #{VerifySpec::MAX_SPECS_PER_COLLECTION * 4} items — re-verification skipped" }
+            return
+          end
+
+          items.each_with_index do |item, idx|
+            spec = item.is_a?(Hash) ? item["verify"] : nil
+            next if spec.nil?
+
+            verdict, detail = run_spec(spec, root_dir)
+            if verdict == :ok
+              # ok hiçbir şey yapmaz (sessiz) — stale temizliği yalnızca
+              # modelin normal ΔΣ patch'idir; harness asla iyileştirmez.
+            elsif verdict == :failed
+              flips << entry(collection, idx, item, "failed", detail)
+            else
+              unknowns << { collection: collection, index: idx, id: item_id(item), reason: detail }
+            end
+          end
+        end
+
+        # -> [:ok|:failed|:unknown, reason]
+        def run_spec(raw, root_dir)
+          verdict, spec_or_reason = VerifySpec.normalize(raw)
+          return [:unknown, spec_or_reason] unless verdict == :ok
+
+          expanded = File.expand_path(spec_or_reason[:path], root_dir)
+          return [:unknown, "path escapes the workspace (containment failed closed)"] unless Rubik::Platform.resolved_path_under?(expanded, root_dir)
+
+          if spec_or_reason[:type] == "file_exists"
+            File.exist?(expanded) ? [:ok, "file_exists"] : [:failed, "file_exists #{spec_or_reason[:path]}: missing"]
+          else
+            needle_read(spec_or_reason, expanded)
+          end
+        rescue Errno::EACCES, Errno::EPERM => e
+          [:unknown, "#{e.class.name.delete_prefix('Errno::')}: not readable"]
+        rescue StandardError => e
+          [:unknown, "#{e.class}: #{e.message}"]
+        end
+
+        # Kesilmiş okumada needle yokluğu KANITLANAMAZ → unknown (tri-state
+        # dürüstlüğünün kalbi); tam okumada yokluk gerçek yokluktur → failed.
+        def needle_read(spec, expanded)
+          size = File.size(expanded)
+          return [:failed, "file_contains #{spec[:path]}: path is a directory"] if File.directory?(expanded)
+
+          body = File.open(expanded, "rb") { |f| f.read(VerifySpec::READ_CAP_BYTES) }.to_s
+          body = Rubik::Platform.safe_utf8(body)
+          return [:ok, "file_contains"] if body.include?(spec[:needle])
+          return [:unknown, "read truncated at #{VerifySpec::READ_CAP_BYTES} bytes — absence unprovable"] if size > body.bytesize
+
+          [:failed, "file_contains #{spec[:path]}: needle absent"]
+        end
+
+        def stale?(item)
+          item["status"] == "stale"
+        end
+
+        def entry(collection, idx, item, state, reason)
+          { collection: collection, index: idx, id: item_id(item), state: state, reason: reason,
+            from: item["status"], at: Time.now.utc.iso8601 }
+        end
+
+        def item_id(item)
+          item.is_a?(Hash) ? item["id"].to_s : ""
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/goal_ledger/verify_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module GoalLedger
+      # Verify-spec grammar SSOT'u (goal-ledger planı B): tasks[] ve
+      # environment_notes[] girdilerinin opsiyonel `verify` alanının kapalı
+      # tip seti. SAF — FS yok; lexical ön kontroller burada, containment
+      # kanıtı Verifier'dadır. "marker", file_contains'in okunabilir
+      # alias'ıdır (aynı semantiğin sentinel dili) — implementasyon tek
+      # predicate'e iner. Sınırlar sabiteedir (knoba knob eklemeyiz).
+      module VerifySpec
+        TYPES = ["file_exists", "file_contains", "marker"].freeze
+        NEEDLE_FIELD = { "file_contains" => "pattern", "marker" => "marker" }.freeze
+        MAX_SPECS_PER_COLLECTION = 16
+        PATH_MAX_CHARS = 512
+        NEEDLE_MAX_CHARS = 256
+        READ_CAP_BYTES = 262_144 # 256 KiB — kesilmiş okumada yokluk KANITLANAMAZ (unknown)
+
+        module_function
+
+        # -> [:ok, {type:, path:, needle:}] | [:invalid, neden]
+        # Hash girdi; tip kapalı sette; path workspace-relative (absolute
+        # ve ".." segmenti reddedilir — lexical ön kontrol, containment
+        # kanıtı Verifier'ın işi); uzunluk cap'leri.
+        def normalize(raw)
+          return [:invalid, "verify must be a JSON object"] unless raw.is_a?(Hash)
+
+          type = raw["type"]
+          return [:invalid, "unknown verify type #{GoalLedger.json_type_name(type)}"] unless TYPES.include?(type)
+
+          path = raw["path"]
+          return [:invalid, "verify path is required"] unless path.is_a?(String) && !path.empty?
+          return [:invalid, "verify path exceeds #{PATH_MAX_CHARS} chars"] if path.length > PATH_MAX_CHARS
+          return [:invalid, "verify path must be workspace-relative"] if path.start_with?("/", "\\\\")
+          return [:invalid, "verify path must not escape the workspace"] if path.split(%r{[\\/]}).include?("..")
+
+          needle_field = NEEDLE_FIELD[type]
+          if needle_field
+            needle = raw[needle_field]
+            return [:invalid, "verify #{type} requires '#{needle_field}'"] unless needle.is_a?(String) && !needle.empty?
+            return [:invalid, "verify #{needle_field} exceeds #{NEEDLE_MAX_CHARS} chars"] if needle.length > NEEDLE_MAX_CHARS
+          end
+
+          [:ok, { type: type, path: path, needle: needle_field ? raw[needle_field] : nil }.freeze]
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/goal_ledger.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  module Orchestrator
+    # GoalLedger — SKILL.state (arxiv 2608.26263v2) türevi yapılandırılmış
+    # goal durumu (Σ) için patch seam'i. SAF KÜTÜPHANE: I/O yok, thread yok,
+    # config yok, prompt/tool yüzeyi yok — bağlayan katman (goal-ledger
+    # feature planı) erişimi sahiplenir; bu dosya require zincirinde
+    # olmadığından yüklenmeyen kütüphane = davranış farkı yapısal olarak sıfır.
+    #
+    # GoalState'in aksine immutable value object'lerdir: Monitor'suzdur çünkü
+    # paylaşılan mutable durum yoktur; Validator atomic'tir (working-copy-
+    # then-discard) ve kabul edilen doküman deep-frozen çıkar.
+    module GoalLedger
+      # Ret reason'ının sözleşme şekli (beş anahtar HER ZAMAN mevcuttur —
+      # tüketici nil-dalı yazmaz); message/hint model-okunur İngilizce'dir ve
+      # retry feedback'inde birebir yankılanır. Hash bilinçli tercihtir:
+      # `class` üye adı Struct/Data'da yasaklıdır.
+      def reason(kind, op_index:, path:, message:, hint:)
+        { class: kind, op_index: op_index, path: path, message: message, hint: hint }.freeze
+      end
+
+      # JSON tip adları (reason mesajları modelin gösterdiği değeri JSON
+      # dünyasında adlandırır: "expected integer, got float").
+      def json_type_name(value)
+        case value
+        when nil then "null"
+        when true, false then "boolean"
+        when Integer then "integer"
+        when Float then "float"
+        when String then "string"
+        when Array then "array"
+        when Hash then "object"
+        else value.class.name
+        end
+      end
+
+      # Patch body flood guardı: gerçekçi dolu bir ledger ~2-6 KB; 32 KB
+      # ~5x headroom ama dosya-dump flood'unu keser (context_limit 32_768
+      # defaultuyla sayısal simetri — loop.rb).
+      MAX_PATCH_BYTES = 32_768
+      # Tek patch'te op tavanı: gerçek bir adım 3-8 op churn'lar; 64 ~10x
+      # headroom, yine de O(ops×doc) validasyon ve retry-echo boyutunu sınırlar.
+      MAX_OPS = 64
+      # Bounded-retry default'u: ret reason'ları tool-result feedback olarak
+      # yankılanır; bütçe tükenirse ESKİ Σ korunur (dmesg warn; goal loop
+      # asla brick olmaz). Config knob'u (goal.ledger.max_patch_retries)
+      # feature planına aittir.
+      DEFAULT_MAX_RETRIES = 2
+
+      module_function :reason, :json_type_name
+    end
+  end
+end
+
+require_relative "goal_ledger/patch"
+require_relative "goal_ledger/schema"
+require_relative "goal_ledger/validator"
+require_relative "goal_ledger/ledger"
+require_relative "goal_ledger/verify_spec"
+require_relative "goal_ledger/verifier"
+require_relative "goal_ledger/drift"
+require_relative "goal_ledger/observation_projection"