textus 0.51.0 → 0.53.0

data/lib/textus/read/deps.rb

@@ -1,38 +0,0 @@
-module Textus
-  module Read
-    class Deps
-      extend Textus::Contract::DSL
-
-      verb     :deps
-      summary  "List the keys a derived entry depends on (its projection/external sources)."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted key of the derived entry whose source keys you want"
-
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(key)
-        { "key" => key, "deps" => sources_for(key) }
-      end
-
-      private
-
-      def sources_for(key)
-        entry = @manifest.data.entries.find { |e| e.key == key }
-        return [] unless entry&.derived?
-
-        src = entry.source
-        result = if src.projection?
-                   Array(src.select).compact
-                 elsif src.external?
-                   Array(src.sources).compact
-                 else
-                   []
-                 end
-        result.uniq
-      end
-    end
-  end
-end

data/lib/textus/read/doctor.rb

@@ -1,27 +0,0 @@
-module Textus
-  module Read
-    # Dispatched use case for the `doctor` verb. The health-check report is
-    # built by the Textus::Doctor library module; this class is the uniform
-    # (container:, call:) entry point that Dispatcher::VERBS resolves to.
-    # The acting role is irrelevant to a read-only health check, so `call`
-    # is not consulted.
-    class Doctor
-      extend Textus::Contract::DSL
-
-      verb     :doctor
-      summary  "Run health checks on the textus store and report any issues."
-      surfaces :cli
-      cli      "doctor"
-      arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(checks: nil)
-        Textus::Doctor.build(container: @container, checks: checks)
-      end
-    end
-  end
-end

data/lib/textus/read/freshness.rb

@@ -1,152 +0,0 @@
-require "time"
-
-module Textus
-  module Read
-    # Per-entry staleness scan (ADR 0079, 0085, 0093). Walks every entry declared
-    # in the manifest and reports a staleness verdict sourced from the two new
-    # policy slots (ADR 0093):
-    #   - intake entries: `entry.source.ttl_seconds` is the re-pull cadence;
-    #     basis = `_meta.last_fetched_at` (else file mtime). Past ttl ⇒ :expired.
-    #   - entries matched by a `retention:` rule: `retention.ttl_seconds` is the
-    #     GC age; basis = file mtime. Past ttl ⇒ :expired (:action = drop/archive).
-    # Intake cadence wins when both apply (freshness is content currency; GC dueness
-    # shows via `reconcile --dry-run`).
-    # Status is one of :fresh, :expired, or :no_policy; the row also carries
-    # :action (:refresh for intake, :drop/:archive for retention).
-    #
-    # ADR 0085 removed the public `freshness` verb: there is no `:cli`/`:mcp`
-    # surface. This is now a Ruby-only internal scan consumed by `pulse` (which
-    # derives `stale` + `next_due_at` from it) and the hook `Context`. Humans drill
-    # into per-entry staleness detail via `get` (last_fetched_at) + `rule_explain`
-    # (the ttl / action policy) instead of a dedicated verb.
-    class Freshness
-      extend Textus::Contract::DSL
-
-      verb     :freshness
-      summary  "Internal per-entry lifecycle scan (status, age, ttl, action); backs pulse + hook context. No public surface (ADR 0085)."
-      arg :prefix, String, required: false, description: "filter to keys with this prefix"
-      arg :zone,   String, required: false, description: "filter to entries in this zone"
-
-      def initialize(container:, call:)
-        @container  = container
-        @call       = call
-        @manifest   = container.manifest
-        @file_store = container.file_store
-      end
-
-      # Returns the soonest `next_due_at` across all entries with a fetch
-      # policy, as an ISO-8601 string, or nil if none.
-      def soonest_due(prefix: nil, zone: nil)
-        times = call(prefix: prefix, zone: zone)
-                .map { |r| r[:next_due_at] }
-                .compact
-                .map { |t| Time.parse(t) }
-        return nil if times.empty?
-
-        times.min.utc.iso8601
-      end
-
-      def call(prefix: nil, zone: nil)
-        rows = []
-        @manifest.data.entries.each do |mentry|
-          next if prefix && !mentry.key.start_with?(prefix)
-          next if zone && mentry.zone != zone
-
-          rows << row_for(mentry)
-        end
-        rows
-      end
-
-      private
-
-      def row_for(mentry)
-        envelope = safe_get(mentry.key)
-        last = envelope&.meta&.dig("last_fetched_at")
-        ttl, action = policy_for(mentry)
-        return base_row(mentry, last).merge(status: :no_policy) if ttl.nil?
-
-        basis = basis_for(mentry)
-        expired = expired?(mentry, basis, ttl)
-        base_row(mentry, last).merge(
-          ttl_seconds: ttl,
-          action: action,
-          status: expired ? :expired : :fresh,
-          next_due_at: basis.nil? ? nil : (basis + ttl).utc.iso8601,
-        )
-      end
-
-      # ADR 0093: staleness comes from the intake re-pull cadence (source.ttl)
-      # or a retention GC rule (retention.ttl). Intake cadence wins when an entry
-      # has both (freshness is about content currency; GC dueness still shows via
-      # `reconcile --dry-run`). Returns [ttl_seconds, action] or [nil, nil].
-      def policy_for(mentry)
-        if mentry.intake?
-          ttl = mentry.source.ttl_seconds
-          return [ttl, :refresh] unless ttl.nil?
-        end
-        ret = @manifest.rules.for(mentry.key).retention
-        return [ret.ttl_seconds, ret.action] unless ret.nil?
-
-        [nil, nil]
-      end
-
-      # Intake currency basis comes from the evaluator (single definition);
-      # retention dueness is keyed off file mtime.
-      def basis_for(mentry)
-        return evaluator.intake_basis(mentry) if mentry.intake? && mentry.source.ttl_seconds
-
-        mtime_for(mentry.key)
-      end
-
-      def expired?(mentry, basis, ttl)
-        if mentry.intake? && mentry.source.ttl_seconds
-          evaluator.verdict(mentry).stale
-        else
-          # Preserve pre-0099 pulse semantics: a never-recorded retention entry
-          # (no file => nil basis) is past due. Retention::Sweep.expired? alone
-          # returns false on nil mtime (it runs post-exists? in the sweep).
-          basis.nil? || Textus::Domain::Retention::Sweep.expired?(ttl_seconds: ttl, mtime: basis, now: @call.now)
-        end
-      end
-
-      def evaluator
-        @evaluator ||= Textus::Domain::Freshness::Evaluator.new(
-          manifest: @manifest, file_stat: Textus::Ports::Storage::FileStat.new, clock: @call,
-        )
-      end
-
-      def mtime_for(key)
-        path = @manifest.resolver.resolve(key).path
-        @file_store.exists?(path) ? Textus::Ports::Storage::FileStat.new.mtime(path) : nil
-      rescue Textus::Error
-        nil
-      end
-
-      def base_row(mentry, last)
-        {
-          key: mentry.key,
-          zone: mentry.zone,
-          last_fetched_at: last,
-          age_seconds: last ? (@call.now - Time.parse(last)).to_i : nil,
-        }
-      end
-
-      # Returns the raw envelope or nil. Nested entries (mentry.key is a
-      # prefix, not a leaf) and missing files both resolve to nil.
-      def safe_get(key)
-        res = @manifest.resolver.resolve(key)
-        return nil unless @file_store.exists?(res.path)
-
-        raw = @file_store.read(res.path)
-        parsed = Entry.for_format(res.entry.format).parse(raw, path: res.path)
-        Textus::Envelope.build(
-          key: key, mentry: res.entry, path: res.path,
-          meta: parsed["_meta"], body: parsed["body"],
-          etag: Etag.for_bytes(raw), content: parsed["content"]
-        )
-      rescue Textus::Error
-        nil
-      end
-    end
-  end
-end

data/lib/textus/read/get.rb

@@ -1,73 +0,0 @@
-module Textus
-  module Read
-    # The one read path — a pure read (ADR 0089, 0093): the on-disk envelope
-    # annotated with a freshness annotation. It NEVER mutates and NEVER ingests.
-    # Quarantine freshness is system-pushed via `reconcile` (scheduled sweep) and
-    # `hook run` (event push). Lifecycle is removed from the get path (ADR 0093):
-    # intake cadence lives in `source.ttl`; GC lives in `retention:` rules; both
-    # are evaluated exclusively by the `reconcile` sweep, not by a read.
-    class Get
-      extend Textus::Contract::DSL
-
-      verb     :get
-      summary  "Read one entry — a pure on-disk read annotated with a freshness " \
-               "verdict; never ingests (quarantine freshness is reconcile + hook " \
-               "only, ADR 0089). Returns the envelope (uid, etag, _meta, body, " \
-               "freshness)."
-      surfaces :cli, :mcp
-      arg :key, String, required: true, positional: true,
-                        description: "dotted entry key to read, e.g. 'knowledge.project'"
-      view { |v, _i| v.to_h_for_wire }
-
-      def initialize(container:, call:, file_stat: Textus::Ports::Storage::FileStat.new)
-        @container  = container
-        @call       = call
-        @manifest   = container.manifest
-        @file_store = container.file_store
-        @file_stat  = file_stat
-      end
-
-      def call(key)
-        annotated_envelope(key)
-      end
-
-      # Strict variant: raises UnknownKey when the entry is missing.
-      # Used by consumers (e.g. uid, Validator) that distinguish absence.
-      def get(key)
-        call(key) ||
-          raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
-      end
-
-      private
-
-      def annotated_envelope(key)
-        envelope = read_raw_envelope(key)
-        return nil if envelope.nil?
-
-        entry = @manifest.resolver.resolve(key).entry
-        envelope.with(freshness: evaluator.verdict(entry))
-      end
-
-      def evaluator
-        @evaluator ||= Textus::Domain::Freshness::Evaluator.new(
-          manifest: @manifest, file_stat: @file_stat, clock: @call,
-        )
-      end
-
-      def read_raw_envelope(key)
-        res = @manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        return nil unless @file_store.exists?(path)
-
-        raw = @file_store.read(path)
-        parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-        Textus::Envelope.build(
-          key: key, mentry: mentry, path: path,
-          meta: parsed["_meta"], body: parsed["body"],
-          etag: Etag.for_bytes(raw), content: parsed["content"]
-        )
-      end
-    end
-  end
-end

data/lib/textus/read/list.rb

@@ -1,24 +0,0 @@
-module Textus
-  module Read
-    class List
-      extend Textus::Contract::DSL
-
-      verb     :list
-      summary  "List keys filtered by zone and/or prefix."
-      surfaces :cli, :mcp
-      arg :prefix, String, description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.runbooks'"
-      arg :zone,   String, description: "restrict to one zone by name (see `boot` zones); combine with prefix to narrow further"
-      view(:cli) { |rows| { "entries" => rows } }
-
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(prefix: nil, zone: nil)
-        rows = @manifest.resolver.enumerate(prefix: prefix)
-        rows = rows.select { |r| r[:manifest_entry].zone == zone } if zone
-        rows.map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
-      end
-    end
-  end
-end

data/lib/textus/read/published.rb

@@ -1,22 +0,0 @@
-module Textus
-  module Read
-    class Published
-      extend Textus::Contract::DSL
-
-      verb     :published
-      summary  "List all entries that declare a publish_to target."
-      surfaces :cli
-      cli      "published"
-
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call
-        @manifest.data.entries.reject { |e| e.publish_to.empty? }.map do |e|
-          { "key" => e.key, "publish_to" => e.publish_to }
-        end
-      end
-    end
-  end
-end

data/lib/textus/read/pulse.rb

@@ -1,98 +0,0 @@
-require "time"
-
-module Textus
-  module Read
-    # Aggregator over audit + freshness + review + doctor. One round-trip
-    # for an agent's per-turn heartbeat. All component reads are existing
-    # APIs; pulse is sugar with a stable envelope shape and a monotonic
-    # cursor (seq).
-    class Pulse
-      extend Textus::Contract::DSL
-
-      verb     :pulse
-      summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
-      surfaces :cli, :mcp
-      around   :cursor
-      arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
-
-      def initialize(container:, call:)
-        @container  = container
-        @call       = call
-        @manifest   = container.manifest
-        @file_store = container.file_store
-        @audit_log  = container.audit_log
-        @root       = container.root
-        @events     = container.events
-      end
-
-      def call(since: 0)
-        freshness_rows = freshness.call
-        {
-          "cursor" => @audit_log.latest_seq,
-          "changed" => audit_changes_since(since),
-          "stale" => freshness_rows.select { |r| r[:status] == :expired }.map { |r| r[:key] },
-          "pending_review" => review_keys,
-          "doctor" => doctor_summary,
-          "contract_etag" => contract_etag,
-          "next_due_at" => soonest_due(freshness_rows),
-          "hook_errors" => hook_errors_since(since),
-        }
-      end
-
-      private
-
-      def audit_changes_since(seq)
-        Read::Audit.new(container: @container).call(seq_since: seq)
-      end
-
-      def freshness
-        @freshness ||= Read::Freshness.new(container: @container, call: @call)
-      end
-
-      def soonest_due(rows)
-        times = rows.map { |r| r[:next_due_at] }.compact.map { |t| Time.parse(t) }
-        return nil if times.empty?
-
-        times.min.utc.iso8601
-      end
-
-      def review_keys
-        # The single queue zone (kind: queue; schema guarantees ≤1), derived
-        # from the manifest rather than a hardcoded zone name (ADR 0034 / D1).
-        queue = @manifest.policy.queue_zone
-        return [] unless queue
-
-        rows = Read::List.new(container: @container).call(zone: queue)
-        rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
-      end
-
-      def doctor_summary
-        result  = Textus::Doctor.build(container: @container)
-        issues  = result["issues"] || []
-        {
-          "ok" => result["ok"],
-          "warn" => issues.count { |i| i["level"] == "warning" },
-          "fail" => issues.count { |i| i["level"] == "error" },
-        }
-      end
-
-      def contract_etag
-        Textus::Etag.for_contract(@root)
-      end
-
-      def hook_errors_since(seq)
-        @events.error_log.since(seq).map do |r|
-          {
-            "seq" => r[:seq],
-            "event" => r[:event].to_s,
-            "hook" => r[:hook].to_s,
-            "key" => r[:key],
-            "error_class" => r[:error_class],
-            "error_message" => r[:error_message],
-            "at" => r[:at],
-          }
-        end
-      end
-    end
-  end
-end

data/lib/textus/read/rdeps.rb

@@ -1,39 +0,0 @@
-module Textus
-  module Read
-    class Rdeps
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(key)
-        { "key" => key, "rdeps" => dependents_of(key) }
-      end
-
-      private
-
-      def dependents_of(key)
-        @manifest.data.entries.each_with_object([]) do |e, acc|
-          next unless e.derived?
-
-          src = e.source
-          sources = if src.projection?
-                      Array(src.select).compact
-                    elsif src.external?
-                      Array(src.sources).compact
-                    else
-                      []
-                    end
-          acc << e.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
-        end
-      end
-    end
-  end
-end

data/lib/textus/read/rule_explain.rb

@@ -1,96 +0,0 @@
-module Textus
-  module Read
-    # Effective rules for a key, at two depths (ADR 0059). Lean by default —
-    # `{ lifecycle, guard }`, the agent-cheap read that was the `rules` verb. With
-    # `detail: true` it returns the verbose explanation — every matching policy
-    # block plus the per-transition guard predicate names — that was
-    # `policy_explain`. One verb, one name across CLI/MCP/method; the audience
-    # split is a parameter, not two tools.
-    class RuleExplain
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-        @schemas  = container.schemas
-      end
-
-      REGISTRY = Textus::Manifest::Schema::FIELD_REGISTRY
-      # Field membership is registry-driven (WS3). Lean shows the fields tagged
-      # for :lean; detail's matched_blocks flag every :detail field. The
-      # `effective` value-block shows the instantiated-policy fields (those with
-      # a policy_class) — guard, being a raw deferred field, is surfaced through
-      # the dedicated `guards:` predicate section instead.
-      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 call(key, detail: false)
-        detail ? explain(key) : effective(key)
-      end
-
-      private
-
-      # Lean: the effective winners only (formerly Read::Rules / the `rules` verb).
-      def effective(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 lean_value(field, value)
-        case field
-        when :retention then retention_hash(value, string_keys: true)
-        else value
-        end
-      end
-
-      # Verbose: every matching block, per-slot effective value, and the
-      # effective guard predicate names for each write transition (formerly
-      # Read::PolicyExplain, ADR 0031).
-      def explain(key)
-        matching = @manifest.rules.explain(key)
-        winners  = @manifest.rules.for(key)
-        factory  = Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
-
-        {
-          key: key,
-          matched_blocks: matching.map do |b|
-            { match: b.match }.merge(DETAIL_FIELDS.to_h { |f| [f, !b.public_send(f).nil?] })
-          end,
-          effective: EFFECTIVE_FIELDS.to_h { |f| [f, effective_value(f, winners.public_send(f))] },
-          guards: Textus::Domain::Policy::BaseGuards::BASE.keys.to_h do |transition|
-            [transition, factory.for(transition, key).predicates.map(&:name)]
-          end,
-        }
-      end
-
-      def effective_value(field, value)
-        return nil if value.nil?
-
-        case field
-        when :retention         then retention_hash(value, string_keys: false)
-        when :handler_allowlist then value.handlers
-        else value
-        end
-      end
-
-      # ADR 0093: retention is a flat GC policy (ttl + drop/archive action).
-      def 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/read/rule_list.rb

@@ -1,54 +0,0 @@
-module Textus
-  module Read
-    # Enumerate every declared rule block in the manifest, in order. This is
-    # the whole-manifest view; `rule_explain` is the for-key view. Extracted
-    # from the CLI verb so the rule family is fully use-case-backed (ADR 0059);
-    # CLI-only (no MCP contract) — an agent reasons per-key via rule_explain.
-    class RuleList
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      # Fields shown here are driven by FIELD_REGISTRY (in_rule_list); only the
-      # per-field serialization below is field-specific.
-      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
-
-      def call
-        @manifest.rules.blocks.map do |b|
-          row = { "match" => b.match }
-          LIST_FIELDS.each do |field|
-            value = b.public_send(field)
-            row[field.to_s] = serialize(field, value) unless value.nil?
-          end
-          row
-        end
-      end
-
-      private
-
-      def serialize(field, value)
-        case field
-        when :retention
-          serialize_retention(value)
-        when :handler_allowlist
-          value.handlers
-        else
-          value
-        end
-      end
-
-      # ADR 0093: retention is a flat GC policy.
-      def serialize_retention(retention)
-        { "ttl_seconds" => retention.ttl_seconds, "action" => retention.action.to_s }
-      end
-    end
-  end
-end

data/lib/textus/read/schema_envelope.rb

@@ -1,25 +0,0 @@
-module Textus
-  module Read
-    class SchemaEnvelope
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-        @schemas  = container.schemas
-      end
-
-      def call(key)
-        mentry = @manifest.resolver.resolve(key).entry
-        schema = @schemas.fetch_or_nil(mentry.schema)
-        { "protocol" => PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
-      end
-    end
-  end
-end

data/lib/textus/read/uid.rb

@@ -1,29 +0,0 @@
-module Textus
-  module Read
-    class Uid
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(key)
-        get.get(key).uid
-      end
-
-      private
-
-      def get
-        @get ||= Get.new(container: @container, call: @call)
-      end
-    end
-  end
-end