textus 0.53.0 → 0.54.1

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

@@ -5,7 +5,7 @@ module Textus
         module FormatMatrix
           def self.call(entry, policy:) # rubocop:disable Lint/UnusedMethodArgument
             begin
-              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
+              Textus::Format.for(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
               raise UsageError.new("entry '#{entry.key}': #{e.message}")
             end

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

@@ -3,7 +3,6 @@ module Textus
     class Entry
       module Validators
         REGISTERED = [
-          Events,
           Publish,
           Ignore,
           FormatMatrix,

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

@@ -1,77 +1,29 @@
 module Textus
   class Manifest
     class Policy
-      # An entry's data-acquisition declaration (ADR 0094). `source:` says HOW the
-      # entry's data is acquired; rendering is a publish concern, so there are no
-      # template/render fields here. `from` is the acquire + staleness axis:
-      #   from: derive -> derived   (internal projection; observable -> rdeps staleness)
-      #   from: fetch -> intake     (external fetch; unobservable -> ttl staleness)
-      #   from: external -> external (out-of-band runner; staleness only, textus never runs it)
-      # Materialization is async-only (job-queue model): a write enqueues a
-      # `materialize` job, converged by a worker. There is no per-entry write
-      # trigger knob.
+      # 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
-        FROMS = %w[fetch derive external].freeze
-
-        attr_reader :from, :handler, :config, :command, :sources
+        attr_reader :command, :sources
 
         def initialize(raw)
-          @from = raw["from"].to_s
-          unless FROMS.include?(@from)
-            raise Textus::BadManifest.new("source.from must be one of #{FROMS.join("|")}, got #{raw["from"].inspect}")
+          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
 
-          @ttl = raw["ttl"]
-          @projection = {}
-
-          case @from
-          when "fetch" then init_fetch(raw)
-          when "derive" then init_derive(raw)
-          when "external" then init_external(raw)
-          end
-        end
-
-        def kind
-          { "fetch" => :intake, "derive" => :derived, "external" => :external }.fetch(@from)
-        end
-
-        def fetch?      = @from == "fetch"
-        def derive?     = @from == "derive"
-        def external?   = @from == "external"
-        def projection? = derive?
-        def ttl_seconds = @ttl.nil? ? nil : Textus::Core::Duration.seconds(@ttl)
-
-        # Flattened projection accessors (ADR 0094) — read directly off the source
-        # block; nil when absent or not a projection source.
-        def select    = @projection["select"]
-        def pluck     = @projection["pluck"]
-        def sort_by   = @projection["sort_by"]
-        def transform = @projection["transform"]
-
-        # The projection spec hash fed to Textus::Projection (string keys, only the
-        # present fields). {} when not a projection.
-        def projection_spec = @projection.dup
-
-        private
-
-        def init_derive(raw)
-          %w[select pluck sort_by transform].each { |f| @projection[f] = raw[f] if raw.key?(f) }
-          return unless @projection["select"].nil? && @projection["transform"].nil?
-
-          raise Textus::BadManifest.new("source (from: derive) requires `select:` and/or `transform:`")
-        end
-
-        def init_fetch(raw)
-          @handler = raw["handler"] or
-            raise Textus::BadManifest.new("source (from: fetch) requires a `handler:` field")
-          @config = raw["config"] || {}
-        end
-
-        def init_external(raw)
           @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

data/lib/textus/manifest/policy.rb

@@ -62,11 +62,8 @@ module Textus
       # 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)
-        return false if @data.entries.nil?
-
-        entry = @data.entries.find { |e| e.key == key } or return false
-        entry.derived?
+      def derived_entry?(_key)
+        false
       end
 
       # The single lane declaring kind: machine, or nil.

data/lib/textus/manifest/resolver.rb

@@ -53,7 +53,7 @@ module Textus
         else
           raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless nested_entry?(entry)
 
-          primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+          primary_ext = Textus::Format.for(entry.format).extensions.first
           base = Textus::Key::Path.normalize_relative_path(entry.path)
           path = File.join(@data.root, base, *remaining) + primary_ext
           Resolution.new(entry: entry, path: path, remaining: remaining)
@@ -111,7 +111,7 @@ module Textus
       end
 
       def nested_glob(format)
-        Textus::Entry.for_format(format).nested_glob
+        Textus::Format.for(format).nested_glob
       end
     end
   end

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

@@ -0,0 +1,61 @@
+# 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

@@ -9,23 +9,16 @@ module Textus
         LANE_KEYS  = %w[name kind owner desc].freeze
         ENTRY_KEYS = %w[
           key path lane kind schema owner nested format
-          source publish
-          events ignore tracked
+          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
-        # ADR 0093/0094: entry-level acquisition block. `from: project` sources
-        # expose flat projection fields (select/pluck/sort_by/transform) directly
-        # on the source block (ADR 0094). Render fields (template/inject_boot/
-        # provenance) that were formerly on the source are retired — they live on
-        # publish targets. The legacy `project:` free hash and `template`/
-        # `inject_boot`/`provenance` fields are kept here so the schema walk can
-        # still emit the migration hint rather than a bare "unknown key".
-        SOURCE_KEYS = %w[
-          from handler config template project command sources ttl inject_boot provenance
-          select pluck sort_by transform
-        ].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
 
@@ -60,13 +53,6 @@ module Textus
         # Key order here fixes the order of RULE_KEYS (after match), the slots,
         # the RuleSet members, and the doctor SLOTS.
         FIELD_REGISTRY = {
-          handler_permit: {
-            yaml_key: "handler_permit",
-            policy_class: Textus::Manifest::Policy::HandlerPermit,
-            validation: :immediate, sub_keys: nil, arg_key: :handlers,
-            in_pick: true, in_ambiguity: true,
-            in_rule_list: true, in_rule_explain: %i[detail]
-          },
           guard: {
             yaml_key: "guard",
             policy_class: nil,

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+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
+        module_function
+
+        def check!(raw)
+          check_roles!(raw["roles"])
+          check_lanes!(raw["lanes"])
+          check_entries!(raw["entries"])
+          check_owners!(raw["lanes"], raw["entries"])
+          check_rules!(raw["rules"])
+          check_single_queue!(raw)
+          check_single_machine!(raw)
+          check_lane_kind_consistency!(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::Role::NAMES.include?(name)
+              raise BadManifest.new(
+                "unknown role name '#{name}' at '#{path}' (allowed: #{Textus::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}]"
+            check_retired_publish_keys!(e, path)
+            check_retired_render_keys!(e, path)
+            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_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_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_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::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::Role::NAMES.include?(archetype)
+          return true if subject.nil?
+
+          OWNER_SUBJECT_PATTERN.match?(subject)
+        end
+
+        def check_rules!(rules)
+          Array(rules).each_with_index do |r, i|
+            path = "$.rules[#{i}]"
+            # Check retired keys BEFORE the generic walk so specific hints fire first.
+            { "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
+            if 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
+            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_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 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
+
+        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