textus 0.55.1 → 0.55.2

data/lib/textus/action/put.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Put < Base
-      verb :put
-      summary "Create or update an entry. Schema-validated. Returns {uid, etag}."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted entry key, e.g. 'knowledge.project'; must resolve to a zone the role may write"
-      arg :meta, Hash, required: false, wire_name: :_meta,
-                       description: "frontmatter; reads back as `_meta` from `get`. Schema-validated — call `schema KEY` first"
-      arg :body, String,
-          description: "markdown/text payload for markdown-format entries; omit (use `content`) for json/yaml entries. Do not send both"
-      arg :content, Hash,
-          description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
-      arg :if_etag, String,
-          description: "optimistic-concurrency guard: the etag you last read; the write is rejected if the entry changed since"
-      view { |env| { "uid" => env.uid, "etag" => env.etag } }
-
-      def self.call(container:, call:, key:, meta: nil, body: nil, content: nil, if_etag: nil) # rubocop:disable Metrics/ParameterLists
-        Textus::Manifest::Data.validate_key!(key)
-        mentry = container.manifest.resolver.resolve(key).entry
-        Success(container.compositor.write(
-                  key,
-                  mentry: mentry,
-                  payload: Textus::Store::Envelope::Writer::Payload.new(
-                    meta: meta,
-                    body: body,
-                    content: content,
-                  ),
-                  if_etag: if_etag,
-                  call: call,
-                ))
-      end
-    end
-  end
-end

data/lib/textus/action/rdeps.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Rdeps < Base
-      verb :rdeps
-      summary "List the derived entries that depend on a key (reverse deps / impact set)."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted key whose dependents (what would be stranded if it moved) you want"
-
-      def self.call(container:, key:, **)
-        manifest = container.manifest
-        rdeps = manifest.data.entries.each_with_object([]) do |entry, acc|
-          next unless entry.external?
-
-          sources = Array(entry.source&.sources).compact
-          acc << entry.key if sources.any? { |source| source == key || key.start_with?("#{source}.") }
-        end
-        Success({ "key" => key, "rdeps" => rdeps })
-      end
-    end
-  end
-end

data/lib/textus/action/reject.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Reject < Base
-      verb :reject
-      summary "discard a queued proposal without applying it"
-      surfaces :cli, :mcp
-      cli "reject"
-      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
-
-      def self.call(container:, call:, pending_key:)
-        mentry = container.manifest.resolver.resolve(pending_key).entry
-        unless mentry.in_proposal_lane?(container.manifest.policy)
-          return Failure(code: :proposal_error, message: "reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
-        end
-
-        env = container.compositor.read(pending_key)
-        parsed = proposal_from(env, key: pending_key)
-        return parsed if parsed.is_a?(Dry::Monads::Result::Failure)
-
-        target_key = parsed[:target_key]
-        container.compositor.delete(pending_key, mentry: mentry, call: call)
-        Success("protocol" => Textus::PROTOCOL, "rejected" => pending_key, "target_key" => target_key)
-      end
-    end
-  end
-end

data/lib/textus/action/rule_explain.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class RuleExplain < Base
-      verb :rule_explain
-      summary "Effective rules for a key. Lean {lifecycle, guard} by default; detail: true adds matched blocks + guard predicates."
-      surfaces :cli, :mcp
-      cli "rule explain"
-      arg :key, String, required: true, positional: true,
-                        description: "dotted key whose effective rules you want (lifecycle ttl/action, write guard, ...)"
-      arg :detail, :boolean,
-          description: "defaults false: lean {lifecycle, guard}. detail: true adds matched blocks + guard predicates per transition."
-      view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
-
-      def self.call(container:, call:, key:, detail: nil) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        Success(detail ? explain(manifest, key) : effective(manifest, key))
-      end
-
-      REGISTRY = Textus::Manifest::Schema::FIELD_REGISTRY
-      LEAN_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:lean) }.keys.freeze
-      DETAIL_FIELDS = REGISTRY.select { |_, m| m[:in_rule_explain].include?(:detail) }.keys.freeze
-      EFFECTIVE_FIELDS = DETAIL_FIELDS.select { |f| REGISTRY[f][:policy_class] }.freeze
-
-      def self.effective(manifest, key)
-        set = manifest.rules.for(key)
-        LEAN_FIELDS.each_with_object({}) do |field, out|
-          value = set.public_send(field)
-          out[field.to_s] = lean_value(field, value) unless value.nil?
-        end
-      end
-
-      def self.lean_value(field, value)
-        case field
-        when :retention
-          retention_hash(value, string_keys: true)
-        when :react
-          value.to_h
-        else
-          value
-        end
-      end
-
-      def self.explain(manifest, key)
-        matching = manifest.rules.explain(key)
-        winners = manifest.rules.for(key)
-        {
-          key: key,
-          matched_blocks: matching.map do |block|
-            { match: block.match }.merge(DETAIL_FIELDS.to_h { |f| [f, !block.public_send(f).nil?] })
-          end,
-          effective: EFFECTIVE_FIELDS.to_h { |f| [f, effective_value(f, winners.public_send(f))] },
-          guards: Textus::Gate::Auth::FLOOR.keys.to_h do |action|
-            floor = Textus::Gate::Auth::FLOOR.fetch(action, [])
-            rule = Array(manifest.rules.for(key).guard&.dig(action.to_s))
-            [action, { floor: floor, rule: rule }]
-          end,
-        }
-      end
-
-      def self.effective_value(field, value)
-        return nil if value.nil?
-
-        case field
-        when :retention
-          retention_hash(value, string_keys: false)
-        when :react
-          value.to_h
-        else
-          value
-        end
-      end
-
-      def self.retention_hash(retention, string_keys:)
-        h = { ttl_seconds: retention.ttl_seconds, action: retention.action }
-        string_keys ? h.transform_keys(&:to_s) : h
-      end
-    end
-  end
-end

data/lib/textus/action/rule_lint.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Textus
-  module Action
-    class RuleLint < Base
-      verb :rule_lint
-      summary "Diff candidate manifest YAML's rules against the live manifest. No writes."
-      surfaces :cli, :mcp
-      cli "rule lint"
-      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
-                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
-      view { |v, _i| v.to_h }
-
-      def self.call(container:, call:, candidate_yaml:) # rubocop:disable Lint/UnusedMethodArgument
-        root = container.root
-        live_rules = current_rules(root)
-        candidate_result = parse_candidate(candidate_yaml)
-        return candidate_result if candidate_result.is_a?(Dry::Monads::Result::Failure)
-
-        candidate_rules = candidate_result
-
-        live_by_match = live_rules.to_h { |rule| [rule["match"], rule] }
-        candidate_by_match = candidate_rules.to_h { |rule| [rule["match"], rule] }
-
-        steps = (candidate_by_match.keys - live_by_match.keys).map do |match|
-          { "op" => "add_rule", "match" => match, "rule" => candidate_by_match[match] }
-        end
-        (live_by_match.keys - candidate_by_match.keys).each do |match|
-          steps << { "op" => "remove_rule", "match" => match }
-        end
-        (live_by_match.keys & candidate_by_match.keys).each do |match|
-          next if live_by_match[match] == candidate_by_match[match]
-
-          steps << {
-            "op" => "change_rule",
-            "match" => match,
-            "from" => live_by_match[match],
-            "to" => candidate_by_match[match],
-          }
-        end
-
-        Success(Textus::Store::Jobs::Plan.new(steps: steps, warnings: []))
-      end
-
-      def self.current_rules(root)
-        raw = YAML.safe_load_file(File.join(root, "manifest.yaml"), permitted_classes: [Symbol], aliases: false)
-        Array(raw["rules"])
-      end
-
-      def self.parse_candidate(yaml_text)
-        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
-        return Failure(code: :usage_error, message: "candidate is not a YAML mapping") unless raw.is_a?(Hash)
-
-        Array(raw["rules"])
-      rescue Psych::Exception => e
-        Failure(code: :usage_error, message: "candidate YAML parse error: #{e.message}")
-      end
-    end
-  end
-end

data/lib/textus/action/rule_list.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class RuleList < Base
-      verb :rule_list
-      summary "List every rule block in the manifest."
-      surfaces :cli
-      cli "rule list"
-      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
-
-      def self.call(container:, call:, **_options) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        Success(manifest.rules.blocks.map do |block|
-          row = { "match" => block.match }
-          LIST_FIELDS.each do |field|
-            value = block.public_send(field)
-            row[field.to_s] = serialize(field, value) unless value.nil?
-          end
-          row
-        end)
-      end
-
-      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
-
-      def self.serialize(field, value)
-        case field
-        when :retention
-          { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
-        when :react
-          value.to_h
-        else
-          value
-        end
-      end
-    end
-  end
-end

data/lib/textus/action/schema_envelope.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class SchemaEnvelope < Base
-      verb :schema_show
-      summary "Return the schema (field shape) for an entry's family, by key."
-      surfaces :cli, :mcp
-      cli "schema show"
-      arg :key, String, required: true, positional: true,
-                        description: "any key in the family whose schema you want; returns required/optional fields and their types"
-
-      def self.call(container:, key:, **)
-        manifest = container.manifest
-        schemas = container.schemas
-        mentry = manifest.resolver.resolve(key).entry
-        schema = schemas.fetch_or_nil(mentry.schema)
-        Success({ "protocol" => Textus::PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h })
-      end
-    end
-  end
-end

data/lib/textus/action/uid.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Uid < Base
-      verb :uid
-      summary "Return the stable UID of an entry without reading its body."
-      surfaces :cli
-      cli "key uid"
-      arg :key, String, required: true, positional: true, description: "entry key"
-      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
-
-      def self.call(container:, call:, key:)
-        envelope = Value::Result.unwrap(Textus::Action::Get.call(container: container, call: call, key: key))
-        Success(envelope.uid)
-      end
-    end
-  end
-end

data/lib/textus/action/where.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Action
-    class Where < Base
-      verb :where
-      summary "Resolve a key to its zone, owner, and path without reading the body."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
-
-      def self.call(container:, key:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        manifest = container.manifest
-        res = manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        Success({ "protocol" => Textus::PROTOCOL, "key" => key, "lane" => mentry.lane, "owner" => mentry.owner, "path" => path })
-      end
-    end
-  end
-end

data/lib/textus/contract/arg.rb

@@ -1,10 +0,0 @@
-module Textus
-  module Contract
-    Arg = Data.define(
-      :name, :type, :required, :positional, :session_default,
-      :description, :wire_name, :default, :source, :coerce, :cli_default
-    ) do
-      def wire = wire_name || name
-    end
-  end
-end

data/lib/textus/contract/dsl.rb

@@ -1,88 +0,0 @@
-module Textus
-  module Contract
-    module DSL
-      def verb(name = nil)
-        if name
-          raise "contract already built; declare verb before reading .contract" if defined?(@contract) && @contract
-
-          @__verb = name
-        else
-          @__verb
-        end
-      end
-
-      def summary(text = nil)
-        if text
-          raise "contract already built; declare summary before reading .contract" if defined?(@contract) && @contract
-
-          @__summary = text
-        else
-          @__summary
-        end
-      end
-
-      def surfaces(*list)
-        if list.empty?
-          @__surfaces ||= []
-        else
-          raise "contract already built; declare surfaces before reading .contract" if defined?(@contract) && @contract
-
-          @__surfaces = list
-        end
-      end
-
-      def cli(path = nil)
-        if path
-          raise "contract already built; declare cli before reading .contract" if defined?(@contract) && @contract
-
-          @__cli = path.to_s
-        else
-          @__cli
-        end
-      end
-
-      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil, default: nil, source: nil, coerce: nil, cli_default: :__unset) # rubocop:disable Metrics/ParameterLists,Layout/LineLength
-        raise "contract already built; declare args before reading .contract" if defined?(@contract) && @contract
-
-        (@__args ||= []) << Arg.new(
-          name: name, type: type, required: required,
-          positional: positional, session_default: session_default,
-          description: description, wire_name: wire_name, default: default,
-          source: source, coerce: coerce, cli_default: cli_default
-        )
-      end
-
-      def cli_stdin(mode = :__read)
-        return @__cli_stdin if mode == :__read
-
-        raise "contract already built; declare cli_stdin before reading .contract" if defined?(@contract) && @contract
-
-        @__cli_stdin = mode
-      end
-
-      def view(surface = :default, &blk)
-        return (@__views ||= {})[surface] unless blk
-
-        raise "contract already built; declare view before reading .contract" if defined?(@contract) && @contract
-
-        (@__views ||= {})[surface] = blk
-      end
-
-      def contract?
-        !@__verb.nil?
-      end
-
-      def contract
-        @contract ||= Spec.new(
-          verb: @__verb,
-          summary: @__summary,
-          args: (@__args || []).freeze,
-          surfaces: (@__surfaces || []).freeze,
-          views: ((@__views ||= {})[:default] ||= ->(v, _i) { v }) && @__views,
-          cli: @__cli,
-          cli_stdin: @__cli_stdin,
-        )
-      end
-    end
-  end
-end

data/lib/textus/contract/spec.rb

@@ -1,25 +0,0 @@
-module Textus
-  module Contract
-    Spec = Data.define(:verb, :summary, :args, :surfaces, :views, :cli, :cli_stdin) do
-      def mcp? = surfaces.include?(:mcp)
-      def cli? = surfaces.include?(:cli)
-
-      def view(surface = :default) = views[surface] || views.fetch(:default)
-      def cli_path = cli || verb.to_s
-      def cli_words = cli_path.split
-      def cli_group = cli_words.size > 1 ? cli_words.first : nil
-      def cli_leaf  = cli_words.last
-
-      def required_args = args.select(&:required)
-
-      def input_schema
-        props = args.to_h do |a|
-          h = { "type" => Contract.json_type(a.type) }
-          h["description"] = a.description if a.description
-          [a.wire.to_s, h]
-        end
-        { type: "object", properties: props, required: required_args.map { |a| a.wire.to_s } }
-      end
-    end
-  end
-end

data/lib/textus/contract.rb

@@ -1,12 +0,0 @@
-module Textus
-  module Contract
-    JSON_TYPES = {
-      String => "string", Integer => "integer", Hash => "object",
-      Array => "array", :boolean => "boolean"
-    }.freeze
-
-    def self.json_type(type)
-      JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
-    end
-  end
-end

data/lib/textus/core/freshness/evaluator.rb

@@ -1,150 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Freshness
-      # The single currency evaluator (ADR 0099). Answers "is the stored data
-      # stale relative to its retention rule?" and detects generator drift for
-      # external entries.
-      #   - retention rule TTL -> AGE signal: now - file_basis > ttl_seconds
-      #   - external -> DRIFT signal: a source changed since generated.at
-      #     (surfaced by the doctor generator_drift check).
-      class Evaluator
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest  = manifest
-          @file_stat = file_stat
-          @clock     = clock
-        end
-
-        # Per-entry currency Verdict driven by the retention rule TTL (if any).
-        def verdict(mentry)
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return fresh if ttl.nil?
-
-          stale = age_stale?(file_basis(mentry), ttl)
-          Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
-        end
-
-        # Keys of entries past their retention rule TTL — the refresh produce scope.
-        def stale_keys(prefix: nil, lane: nil)
-          @manifest.data.entries.select { |m| due?(m, prefix: prefix, lane: lane) }.map(&:key)
-        end
-
-        alias stale_intake_keys stale_keys
-
-        # File basis as a Time (or nil): file mtime when present, else nil.
-        def file_basis(mentry)
-          path = @manifest.resolver.resolve(mentry.key).path
-          return nil unless @file_stat.exists?(path)
-
-          @file_stat.mtime(path)
-        end
-
-        # Generator-drift rows for one entry (replaces Staleness::GeneratorCheck#
-        # rows_for) — consumed by the doctor generator_drift check.
-        def drift_rows(mentry)
-          return [] unless drift_applicable?(mentry)
-
-          path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          reason = drift_reason(mentry, path)
-          reason ? [drift_row(mentry, path, reason)] : []
-        end
-
-        private
-
-        def fresh = Verdict.build(stale: false, reason: nil, fetching: false)
-
-        def due?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !mentry.key.start_with?(prefix)
-
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return false if ttl.nil?
-
-          path = @manifest.resolver.resolve(mentry.key).path
-          return true unless @file_stat.exists?(path)
-
-          age_stale?(file_basis(mentry), ttl)
-        end
-
-        # The one age comparison. A never-recorded entry (nil basis) is stale.
-        def age_stale?(basis, ttl)
-          return true if basis.nil?
-
-          (@clock.now - basis).to_i > ttl
-        end
-
-        # --- generator drift (lifted from Staleness::GeneratorCheck) ---
-
-        def drift_applicable?(mentry) = mentry.external?
-
-        def drift_reason(mentry, path)
-          return "derived entry has never been generated" unless @file_stat.exists?(path)
-
-          generated_at = generated_at_of(mentry, path)
-          return "missing generated.at frontmatter" unless generated_at
-
-          gen_time = parse_time(generated_at)
-          return "unparseable generated.at: #{generated_at.inspect}" unless gen_time
-
-          offender = newest_source_after(mentry.source, gen_time)
-          "source '#{offender}' modified after generated.at" if offender
-        end
-
-        def generated_at_of(mentry, path)
-          Format.for(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
-        end
-
-        def parse_time(str)
-          Time.parse(str.to_s)
-        rescue StandardError
-          nil
-        end
-
-        def newest_source_after(external_src, gen_time)
-          Array(external_src.sources).each do |src|
-            offender = check_source(src, gen_time)
-            return offender if offender
-          end
-          nil
-        end
-
-        def check_source(src, gen_time)
-          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
-            @manifest.resolver.enumerate(prefix: src).each do |row|
-              return src if @file_stat.mtime(row[:path]) > gen_time
-            end
-            nil
-          else
-            check_filesystem_source(src, gen_time)
-          end
-        end
-
-        def check_filesystem_source(src, gen_time)
-          abs = absolutize_source(src)
-          if @file_stat.directory?(abs)
-            dir_has_newer_file?(abs, gen_time) ? src : nil
-          elsif @file_stat.exists?(abs) && @file_stat.mtime(abs) > gen_time
-            src
-          end
-        end
-
-        def absolutize_source(src)
-          File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
-        end
-
-        def dir_has_newer_file?(abs, gen_time)
-          @file_stat.glob(File.join(abs, "**", "*")).any? do |fpath|
-            file?(fpath) && @file_stat.mtime(fpath) > gen_time
-          end
-        end
-
-        def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
-
-        def drift_row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "generator" => mentry.source.command, "reason" => reason }
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/freshness.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Currency — "is the stored data stale relative to its source?" (ADR 0099).
-    # The home of the single Freshness evaluator and its Verdict value object.
-    # Distinct from Core::Retention (GC dueness, Q2).
-    module Freshness
-    end
-  end
-end