textus 0.52.0 → 0.53.0

data/lib/textus/read/audit.rb

@@ -1,130 +0,0 @@
-require "json"
-require "time"
-
-module Textus
-  module Read
-    # Queries .textus/.run/audit/audit.log. Filters: key, zone, role, verb, since,
-    # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
-    # rows produce nil and are skipped).
-    class Audit
-      # Value object that carries all filter parameters for an audit query.
-      # `matches?` checks the manifest-independent predicates so the loop body
-      # only needs to handle the zone check (which requires manifest access).
-      Query = Data.define(:key, :zone, :role, :verb, :since, :seq_since, :correlation_id, :limit) do
-        # rubocop:disable Metrics/ParameterLists
-        def self.build(key: nil, zone: nil, role: nil, verb: nil,
-                       since: nil, seq_since: nil, correlation_id: nil, limit: nil)
-          new(key:, zone:, role:, verb:, since:, seq_since:, correlation_id:, limit:)
-        end
-        # rubocop:enable Metrics/ParameterLists
-
-        def matches?(row)
-          return false if key && row["key"] != key
-          return false if role && row["role"] != role
-          return false if verb && row["verb"] != verb
-          return false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
-          return false if seq_since && (row["seq"].nil? || row["seq"] <= seq_since)
-          return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
-
-          true
-        end
-      end
-
-      extend Textus::Contract::DSL
-
-      verb     :audit
-      summary  "Query the audit log with optional filters."
-      surfaces :cli
-      cli      "audit"
-      # #call(**filters) — args map to Query.build keyword params (ADR 0063)
-      arg :key,            String,  required: false, description: "filter to rows for this key"
-      arg :zone,           String,  required: false, description: "filter to keys in this zone"
-      arg :role,           String,  required: false, description: "filter to rows written under this role"
-      arg :verb,           String,  required: false, description: "filter to rows for this verb"
-      arg :since,          String,  required: false,
-                                    coerce: ->(s) { Textus::Read::Audit.parse_since(s, now: Time.now) },
-                                    description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
-      arg :seq_since,      Integer, required: false, description: "return rows with seq > this cursor value"
-      arg :correlation_id, String,  required: false, description: "filter to rows with this correlation_id"
-      arg :limit,          Integer, required: false, description: "maximum number of rows to return"
-      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
-
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest  = container.manifest
-        @root      = container.root
-        @log_path  = Textus::Layout.audit_log(container.root)
-        @audit_log = container.audit_log
-      end
-
-      def call(**filters)
-        query = Query.build(**filters)
-        check_cursor_expiry!(query.seq_since)
-
-        files = all_log_files
-        return [] if files.empty?
-
-        rows = []
-        files.each do |file|
-          File.foreach(file) do |line|
-            parsed = parse_row(line.chomp)
-            next unless parsed
-            next unless query.matches?(parsed)
-            next if query.zone && !key_in_zone?(parsed["key"], query.zone)
-
-            rows << parsed
-            break if limit_reached?(rows, query)
-          end
-          break if limit_reached?(rows, query)
-        end
-        rows
-      end
-
-      # Accepts ISO8601 ("2026-01-15", "2026-01-15T10:00:00Z") or a relative
-      # offset matching /\A(\d+)([smhd])\z/. Returns nil for unparseable input.
-      def self.parse_since(str, now: Time.now.utc)
-        return nil if str.nil? || str.empty?
-        return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
-
-        m = str.match(/\A(\d+)([smhd])\z/) or return nil
-        mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[m[2]]
-        now - (m[1].to_i * mult)
-      end
-
-      private
-
-      def limit_reached?(rows, query) = query.limit && rows.length >= query.limit
-
-      def check_cursor_expiry!(seq_since)
-        return unless seq_since
-
-        log = @audit_log || Textus::Ports::AuditLog.new(@root)
-        min = log.min_available_seq
-        raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
-      end
-
-      def all_log_files
-        rotated = Dir.glob(File.join(Textus::Layout.audit_dir(@root), "audit.log.*"))
-                     .reject { |p| p.end_with?(".meta.json") }
-                     .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
-        active = File.exist?(@log_path) ? [@log_path] : []
-        rotated + active
-      end
-
-      def parse_row(line)
-        return nil if line.empty?
-        return nil unless line.start_with?("{")
-
-        JSON.parse(line)
-      rescue JSON::ParserError
-        nil
-      end
-
-      def key_in_zone?(key, zone)
-        mentry = @manifest.resolver.resolve(key).entry
-        mentry && mentry.zone == zone
-      rescue Textus::Error
-        false
-      end
-    end
-  end
-end

data/lib/textus/read/boot.rb

@@ -1,26 +0,0 @@
-module Textus
-  module Read
-    # Dispatched use case for the `boot` verb. The orientation envelope is
-    # built by the Textus::Boot library module; this class is the uniform
-    # (container:, call:) entry point that Dispatcher::VERBS resolves to.
-    # Boot is role-independent, so `call` is not consulted.
-    class Boot
-      extend Textus::Contract::DSL
-
-      verb     :boot
-      summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
-      surfaces :cli, :mcp
-      arg :lean, :boolean,
-          description: "return only orientation essentials (zones, agent_quickstart, contract_etag) for cheap session-start injection"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(lean: false)
-        Textus::Boot.build(container: @container, lean: lean)
-      end
-    end
-  end
-end

data/lib/textus/read/capabilities.rb

@@ -1,70 +0,0 @@
-module Textus
-  module Read
-    # A machine-readable projection of the contract surface: every verb, the
-    # transports it reaches, and its full argument schema — sourced from the
-    # same Contract DSL the CLI/MCP/boot already project from (ADR 0039/0063).
-    #
-    # Integrators assert their docs against this in CI so they can't drift
-    # (#161 F4 — patrick-nexus docs claimed "MCP exposes 3 verbs" while ~20 are
-    # surfaced). It also makes the per-surface `dry_run` default asymmetry
-    # (#161 F6) self-documenting: each arg carries both `default` (agent wire)
-    # and `cli_default` (CLI), so the divergence is visible, not folklore.
-    #
-    # Pure contract introspection — it reads no store data; `container` is
-    # accepted only for the uniform use-case constructor.
-    class Capabilities
-      extend Textus::Contract::DSL
-
-      verb     :capabilities
-      summary  "Machine-readable contract surface: every verb, its transports, and arg schema."
-      surfaces :cli, :mcp
-      arg :verb, String, required: false, description: "filter to a single verb by name"
-      view { |result, _i| result }
-
-      def initialize(container: nil, call: nil); end
-
-      def call(verb: nil)
-        klasses = Textus::Dispatcher::VERBS.values.select { |k| contract?(k) }
-        rows = klasses.map { |k| project(k.contract) }
-        rows.select! { |r| r["verb"] == verb } if verb
-        { "verbs" => rows.sort_by { |r| r["verb"] } }
-      end
-
-      private
-
-      def contract?(klass)
-        klass.respond_to?(:contract?) && klass.contract?
-      end
-
-      def project(spec)
-        {
-          "verb" => spec.verb.to_s,
-          "summary" => spec.summary,
-          "surfaces" => spec.surfaces.map(&:to_s) + ["ruby"],
-          "cli" => spec.cli? ? spec.cli_path : nil,
-          "args" => spec.args.map { |a| project_arg(a) },
-        }
-      end
-
-      def project_arg(arg)
-        out = {
-          "name" => arg.wire.to_s,
-          "type" => json_type(arg.type),
-          "required" => arg.required,
-          "positional" => arg.positional,
-        }
-        out["description"] = arg.description if arg.description
-        out["default"] = arg.default unless arg.default.nil?
-        out["cli_default"] = arg.cli_default unless arg.cli_default == :__unset
-        out["session_default"] = arg.session_default.to_s if arg.session_default
-        out
-      end
-
-      def json_type(type)
-        Textus::Contract.json_type(type)
-      rescue ArgumentError
-        "string"
-      end
-    end
-  end
-end

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 `drain --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
-      # `drain --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 `drain` (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 `drain` 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 drain + 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/jobs.rb

@@ -1,31 +0,0 @@
-module Textus
-  module Read
-    # Inspect and operate the job queue: list ids by state, retry a dead-lettered
-    # job, or purge a state. The agent's window into deferred convergence work.
-    class Jobs
-      extend Textus::Contract::DSL
-
-      verb     :jobs
-      summary  "List queued jobs by state; retry a dead-lettered job or purge a state."
-      surfaces :cli, :mcp
-      cli      "jobs"
-      arg :state,  String, default: "ready", description: "ready|leased|done|failed"
-      arg :action, String, default: nil, description: "retry|purge (optional)"
-      arg :job_id, String, default: nil, description: "job id (required for action=retry)"
-
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-      end
-
-      def call(state: "ready", action: nil, job_id: nil)
-        queue = Textus::Ports::Queue.new(root: @container.root)
-        case action
-        when "retry" then queue.retry_failed(job_id)
-        when "purge" then queue.purge(state)
-        end
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "state" => state, "jobs" => queue.list(state) }
-      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