textus 0.52.0 → 0.53.0

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

data/lib/textus/read/validate_all.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Read
-    # Store-wide schema + role-authority validation: walks every entry and runs
-    # the Validator over it. Consumed internally by `doctor`'s schema_violations
-    # check and exposed as a Ruby store method (`store.validate_all`).
-    #
-    # Ruby-only, like `Read::Freshness`: it declares a contract (so it round-trips
-    # through the routing<->contract bijection, ADR 0105) but omits `surfaces`, so
-    # it gets no CLI or MCP projection. The public `validate-all` CLI verb was
-    # removed in v0.5 (`doctor --check=schema_violations` replaces it).
-    class ValidateAll
-      extend Textus::Contract::DSL
-
-      verb    :validate_all
-      summary "Internal store-wide schema + role-authority validation; backs " \
-              "doctor's schema_violations check. No public surface (ADR 0105)."
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-        @schemas   = container.schemas
-        @audit_log = container.audit_log
-      end
-
-      def call
-        Validator.new(
-          reader: Get.new(container: @container, call: @call),
-          manifest: @manifest,
-          audit_log: @audit_log,
-          schema_for: ->(name) { @schemas.fetch_or_nil(name) },
-        ).call
-      end
-    end
-  end
-end

data/lib/textus/read/where.rb

@@ -1,24 +0,0 @@
-module Textus
-  module Read
-    class Where
-      extend Textus::Contract::DSL
-
-      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 initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(key)
-        res = @manifest.resolver.resolve(key)
-        mentry = res.entry
-        path = res.path
-        { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
-      end
-    end
-  end
-end

data/lib/textus/role_scope.rb

@@ -1,78 +0,0 @@
-module Textus
-  # Thin role-scoped facade over a Container. Closes over a role default
-  # and a dry_run flag, then forwards every verb in Dispatcher::VERBS to
-  # the corresponding use case.
-  #
-  # Replaces the per-call Session under the 0.27.0 architecture: a Store
-  # exposes #as(role) to get a RoleScope, and Store#put / Store#get / etc
-  # delegate to RoleScope under the default role.
-  class RoleScope
-    attr_reader :container, :role, :correlation_id
-
-    def dry_run?
-      @dry_run
-    end
-
-    def initialize(container:, role:, dry_run: false, correlation_id: nil)
-      @container = container
-      @role      = role.to_s
-      @dry_run   = dry_run
-      @correlation_id = correlation_id
-    end
-
-    def with_role(role)
-      self.class.new(container: @container, role: role, dry_run: @dry_run, correlation_id: @correlation_id)
-    end
-
-    def with_correlation_id(cid)
-      self.class.new(container: @container, role: @role, dry_run: @dry_run, correlation_id: cid)
-    end
-
-    def hook_context
-      @hook_context ||= Textus::Hooks::Context.new(scope: self)
-    end
-
-    def with_dry_run
-      self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
-    end
-
-    # Single bind + invoke site for every surface. `inputs` is the uniform
-    # by-name hash (the binder's currency). MCP/CLI build it from their raw
-    # transport shape and call this directly; the per-verb Ruby methods below
-    # normalize positional+keyword Ruby args into `inputs` and delegate here.
-    def dispatch_bound(verb, inputs, session: nil)
-      klass = Textus::Dispatcher::VERBS[verb]
-      spec = (klass.contract if klass.respond_to?(:contract?) && klass.contract?)
-
-      invoke = lambda do |effective_inputs|
-        args, kwargs =
-          if spec
-            Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
-          else
-            [[], effective_inputs]
-          end
-        call_value = Textus::Call.build(role: @role, correlation_id: @correlation_id, dry_run: @dry_run)
-        Textus::Dispatcher.invoke(verb, container: @container, call: call_value, args: args, kwargs: kwargs)
-      end
-
-      if spec&.around
-        Textus::Contract::Around.with(spec.around, scope: self, inputs: inputs, session: session, &invoke)
-      else
-        invoke.call(inputs)
-      end
-    end
-
-    Textus::Dispatcher::VERBS.each_key do |verb|
-      define_method(verb) do |*args, **kwargs|
-        klass = Textus::Dispatcher::VERBS[verb]
-        inputs =
-          if klass.respond_to?(:contract?) && klass.contract?
-            Textus::Contract::Binder.inputs_from_ordered(klass.contract, args, kwargs)
-          else
-            kwargs
-          end
-        dispatch_bound(verb, inputs)
-      end
-    end
-  end
-end

data/lib/textus/write/accept.rb

@@ -1,58 +0,0 @@
-module Textus
-  module Write
-    class Accept
-      extend Textus::Contract::DSL
-
-      verb :accept
-      summary "apply a queued proposal to its target zone; requires the author capability"
-      surfaces :cli, :mcp
-      cli "accept"
-      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-        @schemas   = container.schemas
-        @events    = container.events
-      end
-
-      def call(pending_key)
-        env = Textus::Read::Get.new(container: @container, call: @call).call(pending_key)
-        proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
-        target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
-        action = proposal["action"] || "put"
-
-        guard.for(:accept, target).check!(
-          Textus::Domain::Policy::Evaluation.new(
-            actor: @call.role, transition: :accept, origin: pending_key,
-            target: target, envelope: env, manifest: @manifest
-          ),
-        )
-
-        case action
-        when "put"
-          put_op.call(target, meta: env.meta["frontmatter"] || {}, body: env.body)
-        when "delete"
-          delete_op.call(target)
-        else
-          raise ProposalError.new("unknown action: #{action}")
-        end
-
-        delete_op.call(pending_key)
-        @events.publish(:proposal_accepted, ctx: hook_context, key: pending_key, target_key: target)
-        { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
-      end
-
-      private
-
-      def guard
-        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
-      end
-
-      def hook_context = @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      def put_op       = @put_op ||= Textus::Write::Put.new(container: @container, call: @call)
-      def delete_op    = @delete_op ||= Textus::Write::KeyDelete.new(container: @container, call: @call)
-    end
-  end
-end

data/lib/textus/write/enqueue.rb

@@ -1,50 +0,0 @@
-module Textus
-  module Write
-    # Push a job of a REGISTERED type onto the convergence queue, to be run by
-    # drain/serve. The closed allow-list (Jobs::Handlers.registry) is the safety
-    # boundary: an unregistered type is refused, so the general runner can never
-    # execute arbitrary code. Authority is checked here (the caller must hold the
-    # type's required_role, if any) and frozen onto the job's `enqueued_by` — the
-    # worker runs it as exactly this role, no escalation via the queue.
-    class Enqueue
-      extend Textus::Contract::DSL
-
-      verb     :enqueue
-      summary  "Push a registered job type onto the convergence queue, to be run by drain/serve."
-      surfaces :cli, :mcp
-      cli      "enqueue"
-      arg :type, String, required: true, positional: true, description: "registered job type (e.g. materialize, re-pull, sweep)"
-      arg :args, Hash, positional: true, default: {}, description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
-
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-      end
-
-      def call(type, args = {})
-        entry = Textus::Jobs::Handlers.registry.lookup(type) # raises UsageError for unregistered types
-        authorize!(entry)
-
-        job = Textus::Domain::Jobs::Job.new(
-          type: type, args: args, enqueued_by: @call.role, max_attempts: entry.max_attempts,
-        )
-        Textus::Ports::Queue.new(root: @container.root).enqueue(job)
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
-      end
-
-      private
-
-      def authorize!(entry)
-        required = entry.required_role
-        return if required.nil? || @call.role == required
-
-        raise Textus::Error.new(
-          "forbidden",
-          "role '#{@call.role}' is not authorized to enqueue this job type (requires '#{required}')",
-          details: { "role" => @call.role, "required_role" => required },
-          exit_code: 77,
-        )
-      end
-    end
-  end
-end

data/lib/textus/write/key_delete.rb

@@ -1,65 +0,0 @@
-module Textus
-  module Write
-    class KeyDelete
-      extend Textus::Contract::DSL
-
-      verb     :key_delete
-      summary  "Delete one entry by key. Single-key, lower blast radius than " \
-               "key_delete_prefix; guarded by an optional optimistic-concurrency etag. Returns {ok, key, deleted}."
-      surfaces :cli, :mcp
-      cli      "key delete"
-      arg :key, String, required: true, positional: true,
-                        description: "dotted entry key to delete"
-      arg :if_etag, String,
-          description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
-      # `call` already returns a wire hash {protocol, ok, key, deleted}; identity response.
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-        @manifest     = container.manifest
-        @events       = container.events
-      end
-
-      def call(key, if_etag: nil, suppress_events: false)
-        Textus::Manifest::Data.validate_key!(key)
-        mentry = @manifest.resolver.resolve(key).entry
-
-        guard_for(:key_delete, key, if_etag: if_etag).check!(eval_for(:key_delete, target_key: key))
-
-        writer.delete(key, mentry: mentry, if_etag: if_etag)
-
-        unless suppress_events
-          @events.publish(:entry_deleted,
-                          ctx: hook_context,
-                          key: key)
-        end
-
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
-      end
-
-      private
-
-      def guard_for(transition, key, if_etag: nil)
-        Textus::Domain::Policy::GuardFactory.new(
-          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
-        ).for(transition, key)
-      end
-
-      def eval_for(transition, target_key:, envelope: nil)
-        Textus::Domain::Policy::Evaluation.new(
-          actor: @call.role, transition: transition, origin: nil,
-          target: target_key, envelope: envelope, manifest: @manifest
-        )
-      end
-
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def writer
-        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-      end
-    end
-  end
-end