textus 0.55.2 → 0.56.0

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -1,21 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module FormatMatrix
-          def self.call(entry, policy:) # rubocop:disable Lint/UnusedMethodArgument
-            begin
-              Textus::Format.for(entry.format).validate_path_extension(entry.path, entry.nested?)
-            rescue UsageError => e
-              raise UsageError.new("entry '#{entry.key}': #{e.message}")
-            end
-
-            return unless entry.format == "text" && !entry.schema.nil?
-
-            raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/validators/ignore.rb

@@ -1,28 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        # Validates the per-entry `ignore:` field (ADR 0042): a list of
-        # non-empty glob strings, allowed only on nested entries.
-        module Ignore
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            patterns = entry.raw["ignore"]
-            return if patterns.nil?
-
-            raise UsageError.new("entry '#{entry.key}': ignore requires nested: true") unless entry.nested?
-
-            raise UsageError.new("entry '#{entry.key}': ignore must be a list of glob strings") unless patterns.is_a?(Array)
-
-            patterns.each do |pat|
-              next if pat.is_a?(String) && !pat.empty?
-
-              raise UsageError.new(
-                "entry '#{entry.key}': each ignore pattern must be a non-empty string (got #{pat.inspect})",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/validators/publish.rb

@@ -1,30 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        # ADR 0049: one publish validator. Exclusivity among the publish keys is
-        # enforced structurally by Publish.resolve (reached via #publish_mode),
-        # and each mode's shape rules run *because that mode resolved* — replacing
-        # the scattered pairwise "not-both" guards of the old PublishEach +
-        # PublishTree validators. Misuse on a non-nested entry is still caught
-        # here from raw, since the typed attrs stub nil on Base. (publish_each was
-        # removed in 0.42.0 — ADR 0051; the publish_to/publish_tree keys were folded
-        # into the `publish:` block in 0.43.0 — ADR 0052; Schema rejects the retired
-        # flat keys at load.)
-        module Publish
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            unless entry.nested?
-              # ADR 0094: publish: is now a list; use publish_tree (derived reader)
-              # rather than raw.dig("publish", "tree") which breaks on an Array.
-              raise UsageError.new("entry '#{entry.key}': publish.tree requires nested: true") if entry.publish_tree
-
-              return
-            end
-
-            entry.publish_mode.validate!
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/validators.rb

@@ -1,18 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        REGISTERED = [
-          Publish,
-          Ignore,
-          FormatMatrix,
-        ].freeze
-
-        def self.run_all(entry, policy:)
-          REGISTERED.each { |v| v.call(entry, policy: policy) }
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry.rb

@@ -1,8 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      # Populated by each Entry::* subclass at load time.
-      REGISTRY = {}
-    end
-  end
-end

data/lib/textus/manifest/policy/matcher.rb

@@ -1,51 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Matcher
-        module_function
-
-        def matches?(glob, key)
-          glob_segs = glob.split(".")
-          key_segs  = key.split(".")
-          consume(glob_segs, key_segs)
-        end
-
-        def specificity(glob)
-          glob.split(".").reduce(0) do |s, seg|
-            s + case seg
-                when "**" then 0
-                when "*"  then 1
-                else 10
-                end
-          end
-        end
-
-        def pick_most_specific(globs, key:)
-          matching = globs.select { |g| matches?(g, key) }
-          return nil if matching.empty?
-
-          matching.max_by { |g| [specificity(g), -g.length, g] }
-        end
-
-        def self.consume(glob_segs, key_segs)
-          return key_segs.empty? if glob_segs.empty?
-
-          head = glob_segs.first
-          rest = glob_segs[1..]
-
-          if head == "**"
-            return true if rest.empty?
-
-            (0..key_segs.length).any? { |i| consume(rest, key_segs[i..]) }
-          elsif key_segs.empty?
-            false
-          elsif head == "*" || head == key_segs.first
-            consume(rest, key_segs[1..])
-          else
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/author_held.rb

@@ -1,22 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class AuthorHeld
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            holders = manifest.policy.roles_with_capability("author")
-            pass = holders.include?(actor.to_s)
-            reason = if pass
-                       nil
-                     elsif holders.empty?
-                       "no role holds the 'author' capability; #{action} is disabled"
-                     else
-                       "role '#{actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
-                     end
-            { pass:, reason: }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/etag_match.rb

@@ -1,18 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class EtagMatch
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            if_etag = extra[:if_etag]
-            return { pass: true } if if_etag.nil?
-
-            current = envelope&.etag
-            pass = current.nil? || current == if_etag
-            { pass:, error: pass ? nil : Textus::EtagMismatch.new(key, if_etag, current) }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/fresh_within.rb

@@ -1,13 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class FreshWithin
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/lane_deletable_by.rb

@@ -1,31 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class LaneDeletableBy
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } if key.nil?
-
-            mentry = manifest.resolver.resolve(key).entry
-            is_raw = manifest.policy.declared_kind(mentry.lane.to_s) == :raw
-            lane_verb = manifest.policy.verb_for_lane(mentry.lane.to_s)
-            caps = Set.new(manifest.data.role_caps.fetch(actor.to_s, []))
-
-            pass = if is_raw
-                     caps.include?("author")
-                   else
-                     caps.include?(lane_verb.to_s) || caps.include?("author")
-                   end
-            return { pass: true } if pass
-
-            extra_holders = is_raw ? ["author"] : [lane_verb.to_s, "author"]
-            holders = extra_holders.flat_map { |v| manifest.policy.roles_with_capability(v) }.uniq
-            { pass: false, error: Textus::WriteForbidden.new(mentry.key, mentry.lane, verb: lane_verb, holders:) }
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/lane_writable_by.rb

@@ -1,23 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class LaneWritableBy
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } if key.nil?
-
-            mentry = manifest.resolver.resolve(key).entry
-            lane_verb = manifest.policy.verb_for_lane(mentry.lane.to_s)
-            caps = Set.new(manifest.data.role_caps.fetch(actor.to_s, []))
-            return { pass: true } if caps.include?(lane_verb.to_s)
-
-            holders = manifest.policy.roles_with_capability(lane_verb.to_s)
-            { pass: false, error: Textus::WriteForbidden.new(mentry.key, mentry.lane, verb: lane_verb, holders:) }
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/raw_lane_ingest_only.rb

@@ -1,25 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class RawLaneIngestOnly
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } if key.nil?
-
-            mentry = manifest.resolver.resolve(key).entry
-            return { pass: true } unless manifest.policy.declared_kind(mentry.lane.to_s) == :raw
-            return { pass: true } if action == :ingest
-
-            { pass: false, error: Textus::Error.new(
-              :raw_lane_ingest_only,
-              "raw lane '#{mentry.lane}' only accepts `textus ingest` — " \
-              "use that verb instead of '#{action}'",
-            ) }
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/raw_write_once.rb

@@ -1,24 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class RawWriteOnce
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } if key.nil?
-
-            path = manifest.resolver.resolve(key).path
-            return { pass: true } unless File.exist?(path)
-
-            { pass: false, error: Textus::Error.new(
-              :raw_write_once,
-              "raw entry '#{key}' already exists; " \
-              "delete it first (`textus key-delete #{key}`), then re-ingest",
-            ) }
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates/schema_valid.rb

@@ -1,41 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class SchemaValid
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } unless envelope
-            return { pass: true } if key.nil?
-
-            mentry = manifest.resolver.resolve(key).entry
-            schema_ref = mentry.schema
-            return { pass: true } unless schema_ref
-            return { pass: true } unless schemas
-
-            schema = schemas.fetch_or_nil(schema_ref)
-            return { pass: true } unless schema
-
-            frontmatter = envelope.meta&.dig("_meta") || envelope.meta || {}
-            begin
-              schema.validate!(frontmatter)
-              { pass: true }
-            rescue Textus::SchemaViolation => e
-              { pass: false, reason: schema_reason(e) }
-            end
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-
-          def self.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
-  end
-end

data/lib/textus/manifest/policy/predicates/target_is_canon.rb

@@ -1,20 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        class TargetIsCanon
-          def self.call(manifest:, actor:, action:, key:, schemas: nil, envelope: nil, extra: {})
-            return { pass: true } if key.nil?
-
-            mentry = manifest.resolver.resolve(key).entry
-            kind = manifest.policy.declared_kind(mentry.lane.to_s)
-            pass = kind == :canon
-            { pass:, reason: pass ? nil : "target lane '#{mentry.lane}' is not canon (kind: #{kind})" }
-          rescue Textus::UnknownKey
-            { pass: true }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/predicates.rb

@@ -1,54 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      module Predicates
-        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
-
-        CLASSES = {
-          "lane_writable_by" => "LaneWritableBy",
-          "author_held" => "AuthorHeld",
-          "target_is_canon" => "TargetIsCanon",
-          "etag_match" => "EtagMatch",
-          "schema_valid" => "SchemaValid",
-          "fresh_within" => "FreshWithin",
-          "raw_lane_ingest_only" => "RawLaneIngestOnly",
-          "raw_write_once" => "RawWriteOnce",
-          "lane_deletable_by" => "LaneDeletableBy",
-        }.freeze
-
-        module_function
-
-        def by_name(name)
-          short = CLASSES.fetch(name.to_s) do
-            raise Textus::UsageError.new("unknown predicate '#{name}'")
-          end
-          const_get(short)
-        end
-
-        def evaluate(manifest:, action:, actor:, key:, schemas: nil, envelope: nil, extra: {}, rule_predicates: [])
-          failures = []
-          (FLOOR.fetch(action, []) + rule_predicates).uniq.each do |pred_name|
-            result = by_name(pred_name).call(
-              manifest:, schemas:, actor:, action:, key:, envelope:, extra:,
-            )
-            next if result[:pass]
-            raise result[:error] if result[:error]
-
-            failures << [pred_name, result[:reason]]
-          end
-          raise Textus::GuardFailed.new(failures) unless failures.empty?
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/publish_target.rb

@@ -1,34 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      # One publish destination (ADR 0094). Exactly one of:
-      #   to-target   { to:, template:?, inject_boot:? }  — render data through a
-      #               template, or copy verbatim when no template
-      #   tree-target { tree: }                           — ADR 0052 subtree mirror
-      # Provenance is NOT a publish flag — it lives in the data's `_meta`.
-      class PublishTarget
-        attr_reader :to, :tree, :template, :inject_boot
-
-        def initialize(raw)
-          if raw.key?("provenance")
-            raise Textus::BadManifest.new("publish `provenance:` was removed (ADR 0094): provenance lives in the data's `_meta`")
-          end
-
-          @to   = raw["to"]
-          @tree = raw["tree"]
-          raise Textus::BadManifest.new("a publish target needs exactly one of `to:` or `tree:`") unless @to.nil? ^ @tree.nil?
-
-          @template    = raw["template"]
-          @inject_boot = raw["inject_boot"] == true
-          return unless tree_target? && (@template || @inject_boot)
-
-          raise Textus::BadManifest.new("a tree target takes no template/inject_boot (ADR 0094)")
-        end
-
-        def to_target?   = !@to.nil?
-        def tree_target? = !@tree.nil?
-        def renders?     = to_target? && !@template.nil?
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/react.rb

@@ -1,30 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      class React
-        ALLOWED_KEYS = %w[on when do scope budget idempotency observe priority].freeze
-
-        attr_reader :raw
-
-        def initialize(raw:)
-          raise Textus::BadManifest.new("react: must be a map") unless raw.is_a?(Hash)
-
-          raw = raw.each_with_object({}) do |(key, value), out|
-            normalized = key == true ? "on" : key.to_s
-            out[normalized] = value
-          end
-          raise Textus::BadManifest.new("react.ttl is invalid; ttl belongs only to source.ttl or retention.ttl") if raw.key?("ttl")
-
-          unknown = raw.keys - ALLOWED_KEYS
-          raise Textus::BadManifest.new("react: unknown key(s): #{unknown.join(", ")}") unless unknown.empty?
-
-          @raw = raw
-        end
-
-        def to_h
-          @raw
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/retention.rb

@@ -1,29 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      # Garbage collection (ADR 0093). A glob-matched rule slot: when an entry
-      # ages past `ttl`, retire it. Destructive only — runs on the full
-      # `converge` pass, never on a write (ADR 0079's invariant). Orthogonal to
-      # production (`source:`): an intake entry can re-pull hourly AND archive
-      # after 90 days. `warn`/`refresh` are gone (refresh is implied by an
-      # intake source; warn never fired after ADR 0089's pure-read get).
-      class Retention
-        ACTIONS = %i[drop archive].freeze
-
-        attr_reader :action
-
-        def initialize(raw)
-          @ttl = raw["ttl"] or
-            raise Textus::BadManifest.new("retention requires a 'ttl:'")
-          @action = (raw["action"] || "").to_s.to_sym
-          return if ACTIONS.include?(@action)
-
-          raise Textus::BadManifest.new("retention action must be one of #{ACTIONS.join("|")}, got #{raw["action"].inspect}")
-        end
-
-        def ttl_seconds = Textus::Value::Duration.seconds(@ttl)
-        def destructive? = true
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy/source.rb

@@ -1,30 +0,0 @@
-module Textus
-  class Manifest
-    class Policy
-      # An entry's external-generator declaration. `source:` now means ONLY
-      # `from: external` — out-of-band runner; textus never invokes it, only
-      # detects drift (doctor generator_drift check).
-      # `from: fetch` and `from: derive` are removed; those concerns now live
-      # in workflow files under .textus/workflows/.
-      class Source
-        attr_reader :command, :sources
-
-        def initialize(raw)
-          from = raw["from"].to_s
-          unless from == "external"
-            raise Textus::BadManifest.new(
-              "from: #{from} is removed — use a workflow file under .textus/workflows/ instead",
-            )
-          end
-
-          @command = raw["command"] or
-            raise Textus::BadManifest.new("source (from: external) requires a `command:` field")
-          @sources = raw["sources"] || []
-        end
-
-        def external? = true
-        def kind      = :external
-      end
-    end
-  end
-end

data/lib/textus/manifest/policy.rb

@@ -1,95 +0,0 @@
-module Textus
-  class Manifest
-    # Authority over lanes and roles derived from a Manifest::Data snapshot.
-    # Encapsulates the lookups previously living on Manifest itself
-    # (lane_writers, permission_for). Write authority is derived from
-    # capabilities x lane-kind (ADR 0030): each lane-kind requires one verb
-    # (Schema::KIND_REQUIRES_VERB) and a role may write a lane iff its caps
-    # include that verb (verb_for_lane, roles_with_capability). Derived /
-    # proposal-queue status is authoritative via the declared-kind family
-    # (declared_kind, derived_entry?, queue_lane?, queue_lane).
-    class Policy
-      def initialize(data)
-        @data = data
-      end
-
-      # The capability a lane's kind requires to be written, or nil if the
-      # lane declares no kind. declared_kind returns a Symbol; the table is
-      # keyed by String.
-      def verb_for_lane(lane_name)
-        kind = declared_kind(lane_name)
-        kind && Schema::KIND_REQUIRES_VERB[kind.to_s]
-      end
-
-      # Names of roles whose declared caps include `verb`.
-      def roles_with_capability(verb)
-        @data.role_caps.select { |_name, caps| caps.include?(verb) }.keys
-      end
-
-      # The conventional automated proposer: a role that can propose but is not
-      # the author-anchor (so it resolves to `agent`, not `human`, under the
-      # default mapping). Falls back to the first proposer, then nil.
-      def proposer_role
-        proposers = roles_with_capability("propose")
-        (proposers - roles_with_capability("author")).first || proposers.first
-      end
-
-      # The role textus acts AS for a system-initiated operation requiring
-      # `verb` (no human passed --as). Capability-derived — a role name that
-      # exists in the manifest, or nil. Never a hardcoded literal (ADR 0044).
-      def actor_for(verb)
-        roles_with_capability(verb).first
-      end
-
-      # The kind declared on a lane in the manifest, or nil if undeclared.
-      def declared_kind(lane_name)
-        @data.declared_lane_kinds[lane_name]
-      end
-
-      # Lane names declaring `kind` (a Symbol), in manifest order. Lets callers
-      # (boot) name a kind's live lane instance(s) instead of hardcoding names.
-      def lanes_of_kind(kind)
-        @data.declared_lane_kinds.select { |_name, k| k == kind }.keys
-      end
-
-      # The single lane declaring `kind: queue`, or nil. Schema guarantees <=1.
-      def queue_lane
-        @data.declared_lane_kinds.key(:queue)
-      end
-
-      # ADR 0091: derived-ness is a property of the ENTRY, not its lane (one
-      # machine lane holds both intake and derived entries). Resolve the entry
-      # and ask it directly. Returns false if entries are not yet built
-      # (validator phase during Data#initialize) — validators must not rely on
-      # cross-entry state during construction.
-      def derived_entry?(_key)
-        false
-      end
-
-      # The single lane declaring kind: machine, or nil.
-      def machine_lane
-        @data.declared_lane_kinds.key(:machine)
-      end
-
-      # A lane is a proposal queue iff it declares kind: queue.
-      def queue_lane?(lane_name)
-        declared_kind(lane_name) == :queue
-      end
-
-      # The lane a proposer role writes proposals into: the single lane that
-      # declares kind: queue, when the role can write it. Returns nil if there
-      # is no queue lane or the role cannot write it.
-      def propose_lane_for(role)
-        return nil if role.nil?
-
-        q = queue_lane
-        return nil unless q
-
-        q_verb = verb_for_lane(q)
-        return nil unless roles_with_capability(q_verb).include?(role)
-
-        q
-      end
-    end
-  end
-end