textus 0.55.1 → 0.55.2

data/lib/textus/core/retention/sweep.rb

@@ -1,57 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Retention
-      # Retention sweep reporter (ADR 0093/0099). Which entries are past their
-      # `retention:` ttl and the destructive action that applies. Age basis: file
-      # mtime. Only drop/archive. Renamed off the Core::Retention vs
-      # Manifest::Policy::Retention collision (ADR 0099).
-      class Sweep
-        def self.expired?(ttl_seconds:, mtime:, now:)
-          return false if ttl_seconds.nil? || mtime.nil?
-
-          (now - mtime).to_i > ttl_seconds
-        end
-
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest = manifest
-          @file_stat = file_stat
-          @clock = clock
-        end
-
-        def call(prefix: nil, lane: nil)
-          @manifest.data.entries
-                   .select { |m| matches?(m, prefix: prefix, lane: lane) }
-                   .flat_map { |m| rows_for(m) }
-        end
-
-        private
-
-        def matches?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !Textus::Key::Matching.matches_prefix?(
-            mentry.key, prefix, nested: mentry.is_a?(Textus::Manifest::Entry::Nested)
-          )
-
-          true
-        end
-
-        def rows_for(mentry)
-          policy = @manifest.rules.for(mentry.key).retention
-          return [] if policy.nil?
-
-          @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
-            path = row[:path]
-            next unless @file_stat.exists?(path)
-            next unless self.class.expired?(
-              ttl_seconds: policy.ttl_seconds, mtime: @file_stat.mtime(path), now: @clock.now,
-            )
-
-            { "key" => row[:key], "path" => path, "action" => policy.action.to_s }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/retention.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Retention — "is the entry old enough to retire?" (Q2, ADR 0093/0099).
-    # GC dueness, orthogonal to Freshness (content currency). The reporter is
-    # Core::Retention::Sweep; the manifest rule policy is Manifest::Policy::Retention.
-    module Retention
-    end
-  end
-end

data/lib/textus/format/shared.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Format
-    module Shared
-      ENFORCE_NAME_RE = /\.(md|json|yaml|yml|txt)\z/i
-
-      def self.enforce_name_match!(path, meta, extensions)
-        return unless meta.is_a?(Hash) && meta["name"]
-
-        ext = extensions.first
-        basename = File.basename(path, ext)
-        return if meta["name"] == basename
-
-        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
-      end
-    end
-  end
-end

data/lib/textus/gate/auth.rb

@@ -1,212 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  class Gate
-    class Auth
-      FLOOR = {
-        put: %w[lane_writable_by raw_lane_ingest_only],
-        key_delete: %w[lane_deletable_by],
-        key_mv: %w[lane_writable_by raw_lane_ingest_only],
-        accept: %w[author_held],
-        reject: %w[author_held],
-        propose: %w[lane_writable_by raw_lane_ingest_only],
-        key_mv_prefix: %w[lane_writable_by raw_lane_ingest_only],
-        key_delete_prefix: %w[lane_writable_by raw_lane_ingest_only],
-        ingest: %w[lane_writable_by raw_write_once],
-      }.freeze
-
-      AuthContext = Struct.new(
-        :actor, :actor_caps, :lane_verb,
-        :action, :target, :envelope,
-        :mentry, :manifest,
-        keyword_init: true
-      )
-
-      def initialize(container)
-        @manifest = container.manifest
-        @schemas = container.schemas
-      end
-
-      def check!(cmd)
-        key = extract_key(cmd)
-        return unless key
-
-        evaluate_predicates(
-          action: cmd.verb,
-          actor: cmd.role.to_s,
-          key: key,
-          envelope: nil,
-          extra: {},
-        )
-      end
-
-      # Backward-compatible check for inline action auth (accept, put, etc.).
-      def check_action!(action:, actor:, key:, envelope: nil, extra: {})
-        evaluate_predicates(
-          action: action.to_sym,
-          actor: actor,
-          key: key,
-          envelope: envelope,
-          extra: extra,
-        )
-      end
-
-      private
-
-      def evaluate_predicates(action:, actor:, key:, envelope:, extra:)
-        mentry = @manifest.resolver.resolve(key).entry
-        lane_verb = @manifest.policy.verb_for_lane(mentry.lane.to_s)
-        actor_caps = Set.new(@manifest.data.role_caps.fetch(actor, []))
-
-        ctx = AuthContext.new(
-          actor:, actor_caps:, lane_verb:,
-          action:, target: key, envelope:,
-          mentry:, manifest: @manifest
-        )
-
-        failures = []
-        floor_preds = FLOOR.fetch(action, [])
-        rule_preds = rule_declared_predicates(action, key)
-        (floor_preds + rule_preds).uniq.each do |pred|
-          result = evaluate(pred, ctx, extra)
-          next if result[:pass]
-          raise result[:error] if result[:error]
-
-          failures << [pred, result[:reason]]
-        end
-        raise Textus::GuardFailed.new(failures) unless failures.empty?
-      end
-
-      def extract_key(cmd)
-        cmd.params.key?(:pending_key) ? cmd.pending_key : cmd.key
-      end
-
-      def rule_declared_predicates(action, key)
-        guard_map = @manifest.rules.for(key).guard
-        return [] if guard_map.nil?
-
-        Array(guard_map[action.to_s])
-      end
-
-      def evaluate(pred_name, ctx, extra)
-        case pred_name
-        when "lane_writable_by"      then evaluate_lane_writable_by(ctx)
-        when "author_held"           then evaluate_author_held(ctx)
-        when "target_is_canon"       then evaluate_target_is_canon(ctx)
-        when "etag_match"            then evaluate_etag_match(ctx, extra)
-        when "schema_valid"          then evaluate_schema_valid(ctx)
-        when "fresh_within"          then { pass: true }
-        when "raw_lane_ingest_only"  then evaluate_raw_lane_ingest_only(ctx)
-        when "raw_write_once"        then evaluate_raw_write_once(ctx)
-        when "lane_deletable_by"     then evaluate_lane_deletable_by(ctx)
-        else raise Textus::UsageError.new("unknown predicate '#{pred_name}'")
-        end
-      end
-
-      def evaluate_lane_writable_by(ctx)
-        pass = ctx.actor_caps.include?(ctx.lane_verb.to_s)
-        return { pass: true } if pass
-
-        holders = @manifest.policy.roles_with_capability(ctx.lane_verb.to_s)
-        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane, verb: ctx.lane_verb, holders:) }
-      end
-
-      def evaluate_author_held(ctx)
-        holders = @manifest.policy.roles_with_capability("author")
-        pass = holders.include?(ctx.actor.to_s)
-        reason = if pass
-                   nil
-                 elsif holders.empty?
-                   "no role holds the 'author' capability; #{ctx.action} is disabled"
-                 else
-                   "role '#{ctx.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
-                 end
-        { pass:, reason: }
-      end
-
-      def evaluate_target_is_canon(ctx)
-        kind = @manifest.policy.declared_kind(ctx.mentry.lane.to_s)
-        pass = kind == :canon
-        { pass:, reason: pass ? nil : "target lane '#{ctx.mentry.lane}' is not canon (kind: #{kind})" }
-      end
-
-      def evaluate_etag_match(ctx, extra)
-        if_etag = extra[:if_etag]
-        return { pass: true } if if_etag.nil?
-
-        current = ctx.envelope&.etag
-        pass = current.nil? || current == if_etag
-        { pass:, error: pass ? nil : Textus::EtagMismatch.new(ctx.target, if_etag, current) }
-      end
-
-      def evaluate_schema_valid(ctx)
-        return { pass: true } unless ctx.envelope
-
-        schema_ref = ctx.mentry.schema
-        return { pass: true } unless schema_ref
-
-        schema = @schemas.fetch_or_nil(schema_ref)
-        return { pass: true } unless schema
-
-        frontmatter = ctx.envelope.meta&.dig("_meta") || ctx.envelope.meta || {}
-        begin
-          schema.validate!(frontmatter)
-          { pass: true }
-        rescue Textus::SchemaViolation => e
-          { pass: false, reason: schema_reason(e) }
-        end
-      end
-
-      def evaluate_raw_lane_ingest_only(ctx)
-        return { pass: true } unless @manifest.policy.declared_kind(ctx.mentry.lane.to_s) == :raw
-        return { pass: true } if ctx.action == :ingest
-
-        { pass: false, error: Textus::Error.new(
-          :raw_lane_ingest_only,
-          "raw lane '#{ctx.mentry.lane}' only accepts `textus ingest` — " \
-          "use that verb instead of '#{ctx.action}'",
-        ) }
-      end
-
-      def evaluate_raw_write_once(ctx)
-        path = @manifest.resolver.resolve(ctx.target).path
-        return { pass: true } unless File.exist?(path)
-
-        { pass: false, error: Textus::Error.new(
-          :raw_write_once,
-          "raw entry '#{ctx.target}' already exists; " \
-          "delete it first (`textus key-delete #{ctx.target}`), then re-ingest",
-        ) }
-      end
-
-      # Deletion authority: the lane's write capability OR the author capability.
-      # On raw-kind lanes only the author capability grants deletion (correction
-      # escape hatch); the lane's own verb (ingest) is write-only. On all other
-      # lane kinds the behaviour matches lane_writable_by — the lane's writer
-      # can delete as before.
-      def evaluate_lane_deletable_by(ctx)
-        is_raw = @manifest.policy.declared_kind(ctx.mentry.lane.to_s) == :raw
-        pass = if is_raw
-                 ctx.actor_caps.include?("author")
-               else
-                 ctx.actor_caps.include?(ctx.lane_verb.to_s) || ctx.actor_caps.include?("author")
-               end
-        return { pass: true } if pass
-
-        extra_holders = is_raw ? ["author"] : [ctx.lane_verb.to_s, "author"]
-        holders = extra_holders.flat_map { |v| @manifest.policy.roles_with_capability(v) }.uniq
-        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane,
-                                                         verb: ctx.lane_verb, holders:) }
-      end
-
-      def schema_reason(err)
-        d = err.details
-        return err.message.dup unless d.is_a?(Hash)
-        return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
-        return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
-
-        err.message.dup
-      end
-    end
-  end
-end

data/lib/textus/gate.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  class Gate
-    def initialize(container)
-      @container = container
-    end
-
-    def dispatch(spec:, inputs:, role:, correlation_id: nil, session: nil, surface: nil)
-      resolved = Binder.bind(spec, inputs, session: session)
-      cmd = Value::Command.new(verb: spec.verb, params: resolved.freeze, role: role)
-
-      cmd = normalize_propose_key(cmd) if cmd.verb == :propose
-      action_class = Textus::Action::VERBS.fetch(cmd.verb) do
-        raise Textus::UsageError.new("unknown command verb: #{cmd.verb}")
-      end
-
-      auth = Gate::Auth.new(@container)
-      auth.check!(cmd)
-      check_dispatch_auth(cmd, resolved, auth)
-      call_obj = build_call(cmd, correlation_id: correlation_id)
-      result = run_action(action_class, resolved, call_obj)
-      cascade(cmd, result, call_obj) if CASCADE_VERBS.include?(cmd.verb) && !call_obj.dry_run
-      return result unless surface
-
-      spec.view(surface).call(result, resolved)
-    end
-
-    CASCADE_VERBS = %i[put propose accept reject key_mv key_delete].freeze
-
-    AUTH_KEYS = {
-      key_mv: ->(params) { [params[:old_key], params[:new_key]] },
-      ingest: ->(params) { Textus::Action::Ingest.dispatch_key(**params) },
-    }.freeze
-
-    private
-
-    def check_dispatch_auth(cmd, resolved, auth)
-      return unless (resolver = AUTH_KEYS[cmd.verb])
-
-      keys = Array(resolver.call(resolved))
-      keys.each { |k| auth.check_action!(action: cmd.verb, actor: cmd.role, key: k) }
-    end
-
-    def normalize_propose_key(cmd)
-      return cmd if cmd.pending_key
-
-      zone = @container.manifest.policy.propose_lane_for(cmd.role.to_s)
-      key = zone ? "#{zone}.#{cmd.key}" : nil
-      cmd.with(params: cmd.params.merge(pending_key: key))
-    end
-
-    def run_action(klass, params, call_obj)
-      result = klass.call(container: @container, call: call_obj, **params)
-      Value::Result.unwrap(result)
-    end
-
-    def build_call(cmd, correlation_id: nil)
-      dry_run = cmd.params.key?(:dry_run) ? !cmd.params[:dry_run].nil? : false
-      Textus::Value::Call.build(role: cmd.role, dry_run:, correlation_id: correlation_id)
-    end
-
-    def cascade(cmd, result, call)
-      key = result.is_a?(Hash) ? result["cascade_key"] : nil
-      key ||= cascade_key_from_params(cmd)
-      return unless key
-
-      rdeps_result = Textus::Action::Rdeps.call(container: @container, call: call, key: key)
-      rdeps = Value::Result.unwrap(rdeps_result).fetch("rdeps", [])
-      producible = rdeps.select { |dep_key| producible?(dep_key) }
-      producible.each do |dep_key|
-        Textus::Store::Jobs::Materialize.call(container: @container, call: call, key: dep_key)
-      end
-    end
-
-    def cascade_key_from_params(cmd)
-      case cmd.verb
-      when :put, :key_delete then cmd.params[:key]
-      when :key_mv           then cmd.params[:new_key]
-      when :propose, :reject then cmd.params[:pending_key]
-      when :accept           then nil
-      end
-    end
-
-    def producible?(key)
-      entry = @container.manifest.resolver.resolve(key).entry
-      !entry.publish_tree.nil?
-    rescue Textus::Error
-      false
-    end
-  end
-end

data/lib/textus/meta.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Textus
-  module Meta
-    NO_META_FORMATS = %w[text].freeze
-
-    FIELDS = {
-      "uid" => {
-        inject: lambda { |meta, content, existing_meta|
-          m = meta.is_a?(Hash) ? meta.dup : {}
-          existing = existing_meta.is_a?(Hash) ? existing_meta["uid"] : nil
-          m["uid"] = existing || Textus::Value::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
-          [m, content]
-        },
-      },
-      "sources" => {
-        inject: lambda { |meta, content, existing_meta|
-          m = meta.is_a?(Hash) ? meta.dup : {}
-          existing = existing_meta.is_a?(Hash) ? existing_meta["sources"] : nil
-
-          if m.key?("sources")
-            raise Textus::BadContent.new(nil, "_meta.sources must be an array") unless m["sources"].is_a?(Array)
-
-            m["sources"] = m["sources"].map { |s| validate_source_shape!(s) }
-          elsif existing.is_a?(Array) && !existing.empty?
-            m["sources"] = existing
-          end
-
-          [m, content]
-        },
-      },
-    }.freeze
-
-    def self.inject_all(meta, content, existing_meta = {}, format: nil)
-      return [meta, content] if NO_META_FORMATS.include?(format)
-
-      FIELDS.each_value do |field|
-        meta, content = field[:inject].call(meta, content, existing_meta)
-      end
-
-      [meta, content]
-    end
-
-    def self.validate_source_shape!(src)
-      raise Textus::BadContent.new(nil, "each source must be a string") unless src.is_a?(String)
-
-      raise Textus::BadContent.new(nil, "each source must start with 'raw.', got #{src.inspect}") unless src.match?(/\Araw\./)
-
-      src
-    end
-  end
-end

data/lib/textus/schemas.rb

@@ -1,54 +0,0 @@
-module Textus
-  # Eager-loading schema cache. Loads every *.yaml under +dir+ at construction.
-  # A missing directory is treated as "no schemas" (does not raise) to mirror
-  # the lazy behavior previously embedded in Store#schema_for.
-  class Schemas
-    def initialize(dir)
-      @dir = dir
-      @schemas = {}
-      load_all
-    end
-
-    def fetch(name)
-      @schemas[name] || raise(IoError.new("schema not found: #{File.join(@dir, "#{name}.yaml")}"))
-    end
-
-    # Only nil short-circuits. A missing-but-named schema still raises IoError.
-    def fetch_or_nil(name)
-      return nil if name.nil?
-
-      fetch(name)
-    end
-
-    def all
-      @schemas.values
-    end
-
-    # Name-keyed view: { canonical_name => Schema }. The key is the schema's
-    # file stem, which is authoritative even when a schema file carries no
-    # top-level `name:` (Schema#name reads the body and may be nil). Symmetric
-    # with #all (values); use this when you need the names too.
-    def by_name
-      @schemas.dup
-    end
-
-    private
-
-    def load_all
-      return unless File.directory?(@dir)
-
-      Dir.glob(File.join(@dir, "*.yaml")).each do |path|
-        name = File.basename(path, ".yaml")
-        begin
-          @schemas[name] = Schema.load(path)
-        rescue StandardError
-          # Tolerate broken schema files at construction time so the rest of
-          # the store remains loadable. Surfacing the failure is the job of
-          # Doctor::Check::SchemaParseError. Lookups via #fetch still raise
-          # IoError for the missing-but-named schema.
-          next
-        end
-      end
-    end
-  end
-end

data/lib/textus/store/compositor.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  class Store
-    class Compositor
-      def initialize(container)
-        @container = container
-      end
-
-      def write(key, mentry:, payload:, call:, if_etag: nil)
-        Textus::Store::Envelope::Writer.from(container: @container, call: call)
-                                       .put(key, mentry: mentry, payload: payload, if_etag: if_etag)
-      end
-
-      def read(key)
-        Textus::Store::Envelope::Reader.from(container: @container).read(key)
-      end
-
-      def delete(key, call:, mentry: nil, if_etag: nil)
-        Textus::Store::Envelope::Writer.from(container: @container, call: call)
-                                       .delete(key, mentry: mentry, if_etag: if_etag)
-      end
-
-      def move(from_key:, to_key:, new_mentry:, call:, if_etag: nil)
-        Textus::Store::Envelope::Writer.from(container: @container, call: call)
-                                       .move(from_key: from_key, to_key: to_key, new_mentry: new_mentry, if_etag: if_etag)
-      end
-
-      def exists?(key)
-        Textus::Store::Envelope::Reader.from(container: @container).exists?(key)
-      end
-    end
-  end
-end

data/lib/textus/store/session.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require "dry-struct"
-
-module Textus
-  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
-  # (Ruby) orientation state — the audit cursor plus the contract etag and
-  # propose_lane captured at boot. Immutable Dry::Struct::Value; advance_cursor
-  # and with return new instances. ADR 0036; contract_etag widened in ADR 0074.
-  class Store
-    class Session < Dry::Struct
-      attribute :role,          Value::Types::RoleName
-      attribute :cursor,        Value::Types::Cursor
-      attribute :propose_lane,  Value::Types::String.optional
-      attribute :contract_etag, Value::Types::String
-
-      def with(**attrs) = self.class.new(to_h.merge(attrs))
-
-      def advance_cursor(new_cursor) = with(cursor: new_cursor)
-
-      def check_etag!(observed_etag)
-        return if observed_etag == contract_etag
-
-        raise Textus::ContractDrift.new(
-          "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
-          "now #{short_etag(observed_etag)}); re-run boot",
-        )
-      end
-
-      private
-
-      # First 8 hex chars after the "sha256:" prefix — a stable short id for
-      # the drift diagnostic.
-      def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
-    end
-  end
-end

data/lib/textus/surface/projector.rb

@@ -1,27 +0,0 @@
-module Textus
-  module Surface
-    class Projector
-      def initialize(view_key: :default, binder_method: :inputs_from_wire)
-        @view_key = view_key
-        @binder_method = binder_method
-      end
-
-      def verbs(action_verbs = Textus::Action::VERBS)
-        action_verbs.select do |_verb, klass|
-          klass.respond_to?(:contract?) && klass.contract?
-        end
-      end
-
-      def names(action_verbs = Textus::Action::VERBS)
-        verbs(action_verbs).keys.map(&:to_s)
-      end
-
-      def dispatch(verb_name, inputs:, store:, role:, session: nil)
-        klass = Textus::Action::VERBS.fetch(verb_name.to_sym)
-        spec = klass.contract
-        bound = Textus::Gate::Binder.public_send(@binder_method, spec, inputs)
-        store.gate.dispatch(spec:, inputs: bound, role:, session:, surface: @view_key)
-      end
-    end
-  end
-end

data/lib/textus/surface/role_scope.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Surface
-    # Role-scoped identity carrier. Holds the acting identity (role,
-    # correlation_id, dry_run) bound to a container. All verb methods
-    # (put, get, accept, ...) are injected by textus.rb's define_method
-    # loop, which dispatches directly through Gate.
-    class RoleScope
-      attr_reader :container, :role, :correlation_id
-
-      def initialize(container:, role:, dry_run: false, correlation_id: nil)
-        @container      = container
-        @role           = role.to_s
-        @dry_run        = dry_run
-        @correlation_id = correlation_id || SecureRandom.uuid
-      end
-
-      def dry_run? = !!@dry_run
-
-      def with_role(role)
-        self.class.new(container: @container, 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 with_dry_run
-        self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
-      end
-    end
-  end
-end