textus 0.55.1 → 0.56.0

data/lib/textus/manifest/rules.rb

@@ -1,86 +0,0 @@
-module Textus
-  class Manifest
-    class Rules
-      # Every structural member here derives from Schema::FIELD_REGISTRY (WS3),
-      # so a new rule field is added in one place. `in_pick` selects the fields
-      # that participate in the most-specific `for(key)` resolution.
-      PICK_FIELDS = Schema::FIELD_REGISTRY.select { |_, m| m[:in_pick] }.keys.freeze
-
-      RuleSet = ::Data.define(*PICK_FIELDS)
-      EMPTY_SET = RuleSet.new(**PICK_FIELDS.to_h { |f| [f, nil] })
-
-      def self.parse(raw)
-        new(Array(raw).map { |b| Block.new(b) })
-      end
-
-      def initialize(blocks)
-        @blocks = blocks
-      end
-
-      attr_reader :blocks
-
-      def for(key)
-        slots = PICK_FIELDS.to_h { |f| [f, []] }
-        @blocks.each do |b|
-          next unless Textus::Manifest::Policy::Matcher.matches?(b.match, key)
-
-          slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
-        end
-        RuleSet.new(**slots.to_h { |slot, blocks| [slot, pick(blocks, slot, key)] })
-      end
-
-      def explain(key)
-        @blocks.select { |b| Textus::Manifest::Policy::Matcher.matches?(b.match, key) }
-      end
-
-      private
-
-      def pick(blocks, slot, key)
-        return nil if blocks.empty?
-
-        globs = blocks.map(&:match)
-        winning = Textus::Manifest::Policy::Matcher.pick_most_specific(globs, key: key)
-        blocks.find { |b| b.match == winning }&.public_send(slot)
-      end
-
-      class Block
-        attr_reader :match, *Schema::FIELD_REGISTRY.keys
-
-        def initialize(raw)
-          @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
-          Schema::FIELD_REGISTRY.each do |field, meta|
-            instance_variable_set("@#{field}", parse_field(meta, raw[meta[:yaml_key]]))
-          end
-        end
-
-        private
-
-        # One dispatch over the registry, replacing the four bespoke parse_*
-        # methods. :deferred carries the raw Hash after a shape check (its
-        # contents validate later — guard predicates at Dispatch::Auth check time,
-        # ADR 0031); :immediate instantiates the policy class now. :tagged passes
-        # the raw Hash straight to a policy class that is a tagged union and
-        # dispatches on its discriminator field (e.g. upkeep's on:). A mapping
-        # field (sub_keys) splats its nested keys as kwargs; a scalar/array
-        # field passes its raw value under arg_key.
-        def parse_field(meta, value)
-          return nil if value.nil?
-
-          if meta[:validation] == :deferred
-            raise Textus::BadManifest.new("#{meta[:yaml_key]}: must be a map of transition => [predicates]") unless value.is_a?(Hash)
-
-            return value
-          end
-
-          return meta[:policy_class].new(value) if meta[:validation] == :tagged
-
-          if meta[:sub_keys]
-            meta[:policy_class].new(**meta[:sub_keys].to_h { |k| [k.to_sym, value[k]] })
-          else
-            meta[:policy_class].new(meta[:arg_key] => value)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/contract.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/schema"
-
-module Textus
-  class Manifest
-    module Schema
-      # rubocop:disable Metrics/BlockLength
-      Contract = Dry::Schema.JSON do
-        required(:lanes).value(:array).each do
-          hash do
-            required(:name).value(:string)
-            required(:kind).value(included_in?: Vocabulary::LANE_KINDS)
-            optional(:owner).value(:string)
-            optional(:desc).value(:string)
-          end
-        end
-
-        optional(:roles).value(:array).each do
-          hash do
-            required(:name).value(:string)
-            optional(:can).value(:array).each(:string)
-          end
-        end
-
-        optional(:entries).value(:array).each do
-          hash do
-            required(:key).value(:string)
-            required(:lane).value(:string)
-            optional(:path).value(:string)
-            optional(:owner).value(:string)
-            optional(:format).value(:string)
-            optional(:schema).maybe(:string)
-            optional(:kind).value(:string)
-            optional(:nested).value(:bool)
-            optional(:tracked).value(:bool)
-            optional(:ignore)
-            optional(:source)
-            optional(:publish).value(:array)
-          end
-        end
-
-        optional(:rules).value(:array).each do
-          hash do
-            optional(:match).value(:string)
-            optional(:guard)
-            optional(:retention)
-            optional(:react)
-          end
-        end
-
-        optional(:audit).hash do
-          optional(:max_size).value(:integer)
-          optional(:keep).value(:integer)
-        end
-        optional(:version).value(:string)
-      end
-      # rubocop:enable Metrics/BlockLength
-    end
-  end
-end

data/lib/textus/manifest/schema/keys.rb

@@ -1,90 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      # The manifest's key whitelists and the rule-field registry — the schema's
-      # data tables (ADR 0109; the vocabulary lives in Schema::Vocabulary).
-      module Keys
-        ROOT_KEYS  = %w[version roles lanes entries rules audit].freeze
-        ROLE_KEYS  = %w[name can].freeze
-        LANE_KEYS  = %w[name kind owner desc].freeze
-        ENTRY_KEYS = %w[
-          key path lane kind schema owner nested format
-          source publish tracked ignore
-        ].freeze
-        # ADR 0052: the typed publish block — `publish: { to: [...] }` (file
-        # fan-out) xor `publish: { tree: "dir" }` (subtree mirror).
-        PUBLISH_KEYS = %w[to tree].freeze
-        # entry-level external-generator block — only `from: external` is valid.
-        # `from: fetch` and `from: derive` and their specific fields (handler,
-        # config, ttl, select, pluck, sort_by, transform) were removed in the
-        # workflow redesign.
-        SOURCE_KEYS = %w[from command sources].freeze
-        # ADR 0093: rule-level GC slot. drop/archive only (refresh gone).
-        RETENTION_KEYS = %w[ttl action].freeze
-
-        # The ONE source of truth for the rule-block field set (WS3). Adding a
-        # rule field means adding one entry here; everything downstream derives
-        # from it so the ~9 enumeration sites the audit found can't drift:
-        #   - Schema::RULE_KEYS and the per-field sub-key walk (Schema::Validator)
-        #   - Rules: the RuleSet members, EMPTY_SET, the `for` slots accumulator,
-        #     Block's attr_readers, and the parse dispatch
-        #   - Doctor::Check::RuleAmbiguity SLOTS (in_ambiguity)
-        #   - Read::RuleList / Read::RuleExplain field membership
-        #     (in_rule_list / in_rule_explain)
-        #
-        # Per field:
-        #   yaml_key     manifest key used in a rule block
-        #   policy_class the Manifest::Policy backing the field (nil = raw value)
-        #   validation   :immediate (instantiate the policy at parse, surfacing
-        #                shape errors eagerly), :deferred (shape-check + carry
-        #                the raw Hash; guard predicates validate at Dispatch::Auth
-        #                build time, ADR 0031), or :tagged (pass the raw Hash to a
-        #                tagged-union policy that dispatches on its discriminator
-        #                field, e.g. upkeep's on:)
-        #   sub_keys     allowed nested keys for a mapping field (drives both the
-        #                schema sub-key walk and the kwargs splat into policy_class)
-        #   arg_key      for an immediate non-mapping field, the single kwarg the
-        #                raw value is passed under
-        #   in_pick      participates in the most-specific `for(key)` resolution
-        #   in_ambiguity linted by doctor's same-specificity tie check
-        #   in_rule_list shown in the whole-manifest rule_list view
-        #   in_rule_explain depths the field shows at: :lean and/or :detail
-        #
-        # Key order here fixes the order of RULE_KEYS (after match), the slots,
-        # the RuleSet members, and the doctor SLOTS.
-        FIELD_REGISTRY = {
-          guard: {
-            yaml_key: "guard",
-            policy_class: nil,
-            validation: :deferred, sub_keys: nil, arg_key: nil,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-          retention: {
-            yaml_key: "retention",
-            policy_class: Textus::Manifest::Policy::Retention,
-            validation: :tagged, sub_keys: RETENTION_KEYS, arg_key: nil,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-          react: {
-            yaml_key: "react",
-            policy_class: Textus::Manifest::Policy::React,
-            validation: :immediate, sub_keys: nil, arg_key: :raw,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[lean detail]
-          },
-        }.freeze
-
-        RULE_KEYS = (["match"] + FIELD_REGISTRY.values.map { |m| m[:yaml_key] }).freeze
-        AUDIT_KEYS = %w[max_size keep].freeze
-        # Syntactic shape of an `owner:` subject token (the `patrick` in
-        # `human:patrick`) — the subject half of the owner-validation rule below.
-        # Role supplies the archetype set (Role::NAMES); this pattern is the
-        # owner-specific part, so it lives with the rule that composes them
-        # (ADR 0045 D1). Acting-role *names* are gated by Role::NAMES, not a regex.
-        OWNER_SUBJECT_PATTERN = /\A[a-z][a-z0-9_-]*\z/
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics/cross_field.rb

@@ -1,53 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module CrossField
-          def check_cross_field!(raw)
-            check_owners!(raw["lanes"], raw["entries"])
-            check_lane_kind_consistency!(raw)
-          end
-
-          def check_owners!(lanes, entries)
-            Array(lanes).each_with_index { |z, i| check_owner!(z["owner"], "$.lanes[#{i}]") }
-            Array(entries).each_with_index { |e, i| check_owner!(e["owner"], "$.entries[#{i}]") }
-          end
-
-          def check_owner!(owner, path)
-            return if owner.nil?
-            return if valid_owner?(owner)
-
-            raise BadManifest.new(
-              "invalid owner '#{owner}' at '#{path}' " \
-              "(expected <archetype> or <archetype>:<subject>, archetype one of: #{Textus::Value::Role::NAMES.join(", ")})",
-            )
-          end
-
-          def valid_owner?(token)
-            return false unless token.is_a?(String) && !token.empty?
-
-            archetype, subject = token.split(":", 2)
-            return false unless Textus::Value::Role::NAMES.include?(archetype)
-            return true if subject.nil?
-
-            OWNER_SUBJECT_PATTERN.match?(subject)
-          end
-
-          def check_lane_kind_consistency!(raw)
-            held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
-
-            Array(raw["lanes"]).each_with_index do |z, i|
-              verb = KIND_REQUIRES_VERB[z["kind"]]
-              next if verb.nil? || held.include?(verb)
-
-              raise BadManifest.new(
-                "lane '#{z["name"]}' (#{z["kind"]}) at '$.lanes[#{i}]' " \
-                "needs a role with capability '#{verb}'; none declared",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics/invariants.rb

@@ -1,125 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module Invariants
-          def check_invariants!(raw)
-            check_roles!(raw["roles"])
-            check_lanes!(raw["lanes"])
-            check_entries!(raw["entries"])
-            check_rules!(raw["rules"])
-            check_single_queue!(raw)
-            check_single_machine!(raw)
-            walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
-          end
-
-          def check_roles!(roles)
-            return if roles.nil?
-
-            roles.each_with_index do |r, i|
-              path = "$.roles[#{i}]"
-              name = r["name"]
-              unless Textus::Value::Role::NAMES.include?(name)
-                raise BadManifest.new(
-                  "unknown role name '#{name}' at '#{path}' (allowed: #{Textus::Value::Role::NAMES.join(", ")})",
-                )
-              end
-              Array(r["can"]).each do |verb|
-                next if CAPABILITIES.include?(verb)
-
-                hint = %w[ingest fetch].include?(verb) ? " — the quarantine capability folded into 'converge' (ADR 0090)" : ""
-                raise BadManifest.new(
-                  "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
-                  "(known: #{CAPABILITIES.join(", ")})#{hint}",
-                )
-              end
-            end
-
-            author_holders = roles.count { |r| Array(r["can"]).include?("author") }
-            return if author_holders <= 1
-
-            raise BadManifest.new(
-              "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
-            )
-          end
-
-          def check_lanes!(lanes)
-            Array(lanes).each_with_index do |z, i|
-              walk(z, LANE_KEYS, "$.lanes[#{i}]")
-              next unless %w[quarantine derived].include?(z["kind"])
-
-              raise BadManifest.new(
-                "lane kind '#{z["kind"]}' at '$.lanes[#{i}]' was folded into 'machine' (ADR 0091) — " \
-                "use `kind: machine`",
-              )
-            end
-          end
-
-          def check_entries!(entries)
-            Array(entries).each_with_index do |e, i|
-              path = "$.entries[#{i}]"
-              walk(e, ENTRY_KEYS, path)
-              check_publish_block!(e, path)
-              walk(e["source"], SOURCE_KEYS, "#{path}.source") if e.is_a?(Hash) && e["source"].is_a?(Hash)
-            end
-          end
-
-          def check_rules!(rules)
-            Array(rules).each_with_index do |r, i|
-              path = "$.rules[#{i}]"
-              walk(r, RULE_KEYS, path)
-              FIELD_REGISTRY.each_value do |meta|
-                next unless meta[:sub_keys]
-
-                value = r.is_a?(Hash) ? r[meta[:yaml_key]] : nil
-                walk(value, meta[:sub_keys], "#{path}.#{meta[:yaml_key]}") if value.is_a?(Hash)
-              end
-            end
-          end
-
-          def check_publish_block!(entry, path)
-            return unless entry.is_a?(Hash) && entry.key?("publish")
-
-            block = entry["publish"]
-            if block.is_a?(Hash)
-              raise BadManifest.new(
-                "publish: at '#{path}.publish' must be a list of targets (ADR 0094); the map form was retired.",
-              )
-            end
-            raise BadManifest.new("publish: must be a list of targets at '#{path}.publish'") unless block.is_a?(Array)
-
-            block.each_with_index do |t, i|
-              raise BadManifest.new("publish target ##{i} must be a mapping at '#{path}.publish'") unless t.is_a?(Hash)
-
-              walk(t, %w[to tree template inject_boot], "#{path}.publish[#{i}]")
-            end
-          end
-
-          def check_single_queue!(raw)
-            queues = Array(raw["lanes"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
-            return if queues.size <= 1
-
-            raise BadManifest.new("at most one lane may declare kind: queue (found: #{queues.join(", ")})")
-          end
-
-          def check_single_machine!(raw)
-            machines = Array(raw["lanes"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
-            return if machines.size <= 1
-
-            raise BadManifest.new("at most one lane may declare kind: machine (found: #{machines.join(", ")})")
-          end
-
-          def walk(hash, allowed, path)
-            return unless hash.is_a?(Hash)
-
-            hash.each_key do |k|
-              next if allowed.include?(k)
-
-              raise BadManifest.new("unknown key '#{k}' at '#{path}'")
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics/migration.rb

@@ -1,83 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      module Semantics
-        module Migration
-          def check_migration!(raw)
-            Array(raw["entries"]).each_with_index do |e, i|
-              path = "$.entries[#{i}]"
-              check_retired_publish_keys!(e, path)
-              check_retired_render_keys!(e, path)
-            end
-            check_rules_retired_keys!(raw["rules"])
-          end
-
-          def check_retired_publish_keys!(entry, path)
-            return unless entry.is_a?(Hash)
-
-            if entry.key?("publish_each")
-              raise BadManifest.new(
-                "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-                "mirror the subtree with `publish: { tree: \"...\" }`.",
-              )
-            end
-            if entry.key?("publish_to")
-              raise BadManifest.new(
-                "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-                "use `publish: { to: [...] }`.",
-              )
-            end
-            if entry.key?("publish_tree")
-              raise BadManifest.new(
-                "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-                "use `publish: { tree: \"...\" }`.",
-              )
-            end
-            return unless entry.key?("index_filename")
-
-            raise BadManifest.new(
-              "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}'.",
-            )
-          end
-
-          def check_retired_render_keys!(entry, path)
-            return unless entry.is_a?(Hash)
-
-            if entry.key?("template")
-              raise BadManifest.new(
-                "entry-level `template:` was removed at '#{path}' (ADR 0094): rendering is a " \
-                "publish concern — `publish: [{ to:, template: }]`.",
-              )
-            end
-            if entry.key?("inject_boot")
-              raise BadManifest.new(
-                "entry-level `inject_boot:` was removed at '#{path}' (ADR 0094).",
-              )
-            end
-            return unless entry.key?("provenance")
-
-            raise BadManifest.new("entry-level `provenance:` was removed at '#{path}' (ADR 0094).")
-          end
-
-          def check_rules_retired_keys!(rules)
-            Array(rules).each_with_index do |r, i|
-              path = "$.rules[#{i}]"
-              { "lifecycle" => "age GC moved to `retention:` rule", "materialize" => "removed (ADR 0093)" }
-                .each do |old, hint|
-                  next unless r.is_a?(Hash) && r.key?(old)
-
-                  raise BadManifest.new("`#{old}:` was removed at '#{path}' (ADR 0093) — #{hint}.")
-                end
-              next unless r.is_a?(Hash) && r.key?("upkeep")
-
-              raise BadManifest.new(
-                "rule key `upkeep:` was removed (ADR 0093): move age-GC to `retention:` " \
-                "and production to the entry's `source:`",
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/semantics.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "semantics/invariants"
-require_relative "semantics/migration"
-require_relative "semantics/cross_field"
-
-module Textus
-  class Manifest
-    module Schema
-      # Cross-field rules and ADR migration hints. Called by Validator.validate!
-      # AFTER the structural dry-schema Contract passes. Operates on the raw hash.
-      module Semantics
-        extend Invariants
-        extend Migration
-        extend CrossField
-
-        module_function
-
-        def check!(raw)
-          check_migration!(raw)
-          check_invariants!(raw)
-          check_cross_field!(raw)
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/validator.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  class Manifest
-    module Schema
-      # Orchestrates structural validation (dry-schema Contract) then cross-field
-      # semantic checks (Semantics). Public interface unchanged: Validator.validate!(raw).
-      module Validator
-        module_function
-
-        def validate!(raw)
-          raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
-
-          # Root unknown-key check before Contract so it fires even when lanes: is empty.
-          Semantics.walk(raw, ROOT_KEYS, "$")
-
-          result = Contract.call(raw)
-          raise BadManifest.new(format_first_error(result.errors.messages)) unless result.success?
-
-          raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
-
-          Semantics.check!(raw)
-        end
-
-        # Format the first dry-schema error to match the legacy path-prefixed style:
-        # "unknown key 'x' at '$.lanes[0]'" for extra-key errors;
-        # "manifest structure error at <path>: <msg>" for type/value errors.
-        def format_first_error(messages)
-          msg = messages.first
-          return "manifest structure error: unknown" unless msg
-
-          parent = format_path(msg.path[0..-2])
-          key    = msg.path.last
-
-          if msg.text == "is not allowed"
-            "unknown key '#{key}' at '#{parent}'"
-          else
-            "manifest structure error at #{format_path(msg.path)}: #{msg.text}"
-          end
-        end
-
-        def format_path(parts)
-          "$" + Array(parts).map { |p| p.is_a?(Integer) ? "[#{p}]" : ".#{p}" }.join
-        end
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema/vocabulary.rb

@@ -1,25 +0,0 @@
-module Textus
-  class Manifest
-    module Schema
-      # The closed coordination vocabulary (ADR 0028; five in 0033; unified in
-      # 0034; the quarantine + derived ZONE-KINDS folded into one `machine` kind
-      # in ADR 0091). Each kind pairs with the capability that authorizes
-      # originating bytes in it. ONE source of truth; the derived constants below
-      # cannot drift. A BIJECTION again (0090 had two kinds → the converge capability; 0091
-      # collapses them, so kind ↔ capability is 1:1).
-      module Vocabulary
-        LANES = {
-          "canon" => "author",
-          "workspace" => "keep",
-          "machine" => "converge",
-          "queue" => "propose",
-          "raw" => "ingest",
-        }.freeze
-
-        LANE_KINDS         = LANES.keys.freeze
-        CAPABILITIES       = LANES.values.uniq.freeze
-        KIND_REQUIRES_VERB = LANES
-      end
-    end
-  end
-end

data/lib/textus/manifest/schema.rb

@@ -1,30 +0,0 @@
-module Textus
-  class Manifest
-    # The manifest schema. Its data is split across Schema::Vocabulary (the
-    # coordination vocabulary) and Schema::Keys (key whitelists + FIELD_REGISTRY)
-    # as of ADR 0109; the validation walk lives in Schema::Validator (ADR 0107).
-    # The constants are re-exported here so callers keep saying `Schema::LANES`.
-    module Schema
-      # Re-export the vocabulary.
-      LANES              = Vocabulary::LANES
-      LANE_KINDS         = Vocabulary::LANE_KINDS
-      CAPABILITIES       = Vocabulary::CAPABILITIES
-      KIND_REQUIRES_VERB = Vocabulary::KIND_REQUIRES_VERB
-      # Re-export the keys + registry.
-      ROOT_KEYS             = Keys::ROOT_KEYS
-      ROLE_KEYS             = Keys::ROLE_KEYS
-      LANE_KEYS             = Keys::LANE_KEYS
-      ENTRY_KEYS            = Keys::ENTRY_KEYS
-      PUBLISH_KEYS          = Keys::PUBLISH_KEYS
-      SOURCE_KEYS           = Keys::SOURCE_KEYS
-      RETENTION_KEYS        = Keys::RETENTION_KEYS
-      AUDIT_KEYS            = Keys::AUDIT_KEYS
-      FIELD_REGISTRY        = Keys::FIELD_REGISTRY
-      RULE_KEYS             = Keys::RULE_KEYS
-      OWNER_SUBJECT_PATTERN = Keys::OWNER_SUBJECT_PATTERN
-
-      # Public entry point — the validation walk lives in Schema::Validator (ADR 0107).
-      def self.validate!(raw) = Validator.validate!(raw)
-    end
-  end
-end