textus 0.50.0 → 0.51.0

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

@@ -0,0 +1,56 @@
+module Textus
+  class Manifest
+    class Entry
+      # A produced entry (ADR 0095) — anything with a `source:`. The produce
+      # method (intake/derived/external) is read from source.from; there is no
+      # separate kind for it. Merges the former Derived + Intake classes.
+      class Produced < Base
+        attr_reader :source, :events
+
+        def initialize(source:, events: {}, **rest)
+          super(**rest)
+          @source = source
+          @events = events || {}
+        end
+
+        def intake?     = @source.kind == :intake
+        def derived?    = @source.kind == :derived
+        def external?   = @source.external?
+        def projection? = @source.projection?
+        def nested?     = !!@raw["nested"]
+        def handler     = @source.handler
+        def config      = @source.config
+
+        KIND = :produced
+
+        # ADR 0094/0095: projection (from: project) sources build their DATA
+        # artifact here, then publish via the ONE shared mode (Publish::ToPaths).
+        # Intake bytes come from Produce::Acquire::Intake and command (external) bytes from the
+        # out-of-band runner — neither builds, but both still publish their
+        # existing store bytes through the same mode. A projection entry with no
+        # targets is a terminal data node: it produced data, so report :built
+        # even though nothing was emitted.
+        def publish_via(pctx, prefix: nil)
+          built = false
+          if projection?
+            Textus::Produce::Acquire::Projection.new(container: pctx.container, call: pctx.call).run(self)
+            built = true
+            pctx.emit(:entry_produced, key: @key, envelope: pctx.reader.call(@key), sources: Array(@source.select).compact)
+          end
+
+          emitted = publish_mode.publish(pctx, prefix: prefix)
+          return emitted if emitted
+          return nil unless built
+
+          { kind: :built, value: { "key" => @key, "path" => Key::Path.resolve(pctx.manifest.data, self), "published_to" => [] } }
+        end
+
+        def self.from_raw(common, raw)
+          new(source: Parser.parse_source(raw, common[:key]), events: raw["events"] || {}, **common)
+        end
+
+        Entry::REGISTRY[KIND] = self
+      end
+    end
+  end
+end

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

@@ -9,9 +9,10 @@ module Textus
         # shared shape — Tree always walks at `base` and honors `ignore` in the
         # prune (ADR 0047 D4, so a derived index in the mirrored dir survives).
         class SubtreeMirror
-          def initialize(entry, pctx)
-            @entry = entry
-            @pctx  = pctx
+          def initialize(entry, pctx, publisher: Textus::Ports::Publisher.new)
+            @entry     = entry
+            @pctx      = pctx
+            @publisher = publisher
           end
 
           # base:       store dir the entry owns — the root `ignored?` globs are
@@ -40,8 +41,8 @@ module Textus
               next nil if @entry.ignored?(relative(src, base))
 
               dst = File.join(target_dir, relative(src, walk_root))
-              Textus::Ports::Publisher.publish(source: src, target: dst, store_root: @pctx.root)
-              @pctx.emit(:file_published, key: key, envelope: envelope, source: src, target: dst)
+              @publisher.publish(source: src, target: dst, store_root: @pctx.root)
+              @pctx.emit(:entry_published, key: key, envelope: envelope, source: src, target: dst)
               { "key" => key, "source" => src, "target" => dst }
             end
           end
@@ -57,7 +58,7 @@ module Textus
               next nil if kept.include?(abs)
               next nil if honor_ignore && @entry.ignored?(relative(abs, target_dir))
 
-              Textus::Ports::Publisher.unpublish(target: managed, store_root: @pctx.root)
+              @publisher.unpublish(target: managed, store_root: @pctx.root)
               managed
             end
           end

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

@@ -1,24 +1,75 @@
+require "tempfile"
+
 module Textus
   class Manifest
     class Entry
       module Publish
-        # publish.to: copy the entry's one stored file to each fixed repo path.
-        # The behaviour of any entry that declares `publish: { to: [...] }`.
+        # publish.to: render or copy the entry's stored data to each fixed repo path.
+        # The behaviour of any entry that declares `publish: [{ to: ... }, ...]`.
+        # ADR 0094: iterates publish_targets (to-targets), rendering through a
+        # template when the target declares one, or copying verbatim otherwise.
         class ToPaths < Mode
-          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-            targets = Array(entry.publish_to)
+          def initialize(entry, publisher: Textus::Ports::Publisher.new)
+            super(entry)
+            @publisher = publisher
+          end
+
+          def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument,Metrics/AbcSize
+            targets = entry.publish_targets.select(&:to_target?)
             return nil if targets.empty?
 
-            source_path = pctx.manifest.resolver.resolve(entry.key).path
-            envelope = pctx.reader.call(entry.key)
+            data_path = pctx.manifest.resolver.resolve(entry.key).path
+            envelope  = pctx.reader.call(entry.key)
+            renderer  = Textus::Produce::Render.new(template_loader: ->(n) { pctx.read_template(n) })
+            content = nil # parsed lazily; the data's `content` (always _meta-free)
 
-            targets.each do |rel|
-              target_abs = File.join(pctx.repo_root, rel)
-              Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
-              pctx.emit(:file_published, key: entry.key, envelope: envelope, source: source_path, target: target_abs)
+            targets.each do |t|
+              if t.renders?
+                content ||= Textus::Entry.for_format(entry.format).parse(File.read(data_path), path: data_path)["content"]
+                publish_bytes(render_bytes(t, content, renderer, pctx), entry.key, t, pctx, data_path, envelope)
+              elsif strip_meta?(entry)
+                content ||= Textus::Entry.for_format(entry.format).parse(File.read(data_path), path: data_path)["content"]
+                bytes = Textus::Entry.for_format(entry.format).serialize(meta: {}, body: "", content: content)
+                publish_bytes(bytes, entry.key, t, pctx, data_path, envelope)
+              else
+                # opaque / command / non-structured — publish the stored file as-is
+                target_abs = File.join(pctx.repo_root, t.to)
+                @publisher.publish(source: data_path, target: target_abs, store_root: pctx.root)
+                pctx.emit(:entry_published, key: entry.key, envelope: envelope, source: data_path, target: target_abs)
+              end
             end
 
-            { kind: :built, value: { "key" => entry.key, "path" => source_path, "published_to" => targets } }
+            { kind: :built, value: { "key" => entry.key, "path" => data_path, "published_to" => targets.map(&:to) } }
+          end
+
+          private
+
+          # A structured-data entry that textus owns: its `_meta` stays in the
+          # store, so the published file is the re-serialized meta-free content.
+          # An external (command) entry is opaque — never parse/re-serialize it.
+          def strip_meta?(entry)
+            !entry.external? && %w[json yaml].include?(entry.format.to_s)
+          end
+
+          def render_bytes(target, content, renderer, pctx)
+            boot = target.inject_boot ? Textus::Boot.build(container: pctx.container) : nil
+            renderer.bytes_for(target: target, data: content, boot: boot)
+          end
+
+          # Write bytes to a system temp, publish (recording the persistent data
+          # file as the sentinel source), then remove the temp — the store is
+          # never polluted with render artifacts.
+          def publish_bytes(bytes, key, target, pctx, data_path, envelope)
+            target_abs = File.join(pctx.repo_root, target.to)
+            Tempfile.create(["textus-publish", File.extname(target.to)]) do |f|
+              f.binmode
+              f.write(bytes)
+              f.flush
+              @publisher.publish(
+                source: f.path, target: target_abs, store_root: pctx.root, provenance_source: data_path,
+              )
+            end
+            pctx.emit(:entry_published, key: key, envelope: envelope, source: data_path, target: target_abs)
           end
         end
       end

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

@@ -3,24 +3,16 @@ module Textus
     class Entry
       module Validators
         module FormatMatrix
-          def self.call(entry, policy:)
+          def self.call(entry, policy:) # rubocop:disable Lint/UnusedMethodArgument
             begin
               Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
               raise UsageError.new("entry '#{entry.key}': #{e.message}")
             end
 
-            if entry.format == "text" && !entry.schema.nil?
-              raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
-            end
-
-            has_template = !entry.template.nil?
-            is_external  = entry.derived? && entry.external?
-            is_intake    = entry.intake?
-            return unless entry.in_generator_zone?(policy) && !has_template && !is_external && !is_intake &&
-                          %w[markdown text].include?(entry.format) && !entry.nested?
+            return unless entry.format == "text" && !entry.schema.nil?
 
-            raise UsageError.new("entry '#{entry.key}': #{entry.format} entries in a generator zone require a template")
+            raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
           end
         end
       end

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

@@ -14,7 +14,9 @@ module Textus
         module Publish
           def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             unless entry.nested?
-              raise UsageError.new("entry '#{entry.key}': publish.tree requires nested: true") if entry.raw.dig("publish", "tree")
+              # 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

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

@@ -5,7 +5,6 @@ module Textus
         REGISTERED = [
           Events,
           Publish,
-          InjectBoot,
           Ignore,
           FormatMatrix,
         ].freeze

data/lib/textus/manifest/policy.rb

@@ -7,7 +7,7 @@ module Textus
     # (Schema::KIND_REQUIRES_VERB) and a role may write a zone iff its caps
     # include that verb (verb_for_zone, roles_with_capability). Derived /
     # proposal-queue status is authoritative via the declared-kind family
-    # (declared_kind, derived_zone?, queue_zone?, queue_zone).
+    # (declared_kind, derived_entry?, queue_zone?, queue_zone).
     class Policy
       def initialize(data)
         @data = data
@@ -72,9 +72,21 @@ module Textus
         @data.declared_zone_kinds.key(:queue)
       end
 
-      # A zone is derived iff it declares kind: derived.
-      def derived_zone?(zone_name)
-        declared_kind(zone_name) == :derived
+      # ADR 0091: derived-ness is a property of the ENTRY, not its zone (one
+      # machine zone 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)
+        return false if @data.entries.nil?
+
+        entry = @data.entries.find { |e| e.key == key } or return false
+        entry.derived?
+      end
+
+      # The single zone declaring kind: machine, or nil.
+      def machine_zone
+        @data.declared_zone_kinds.key(:machine)
       end
 
       # A zone is a proposal queue iff it declares kind: queue.

data/lib/textus/manifest/resolver.rb

@@ -30,8 +30,10 @@ module Textus
         []
       end
 
-      def enumerate(prefix: nil)
-        out = @data.entries.flat_map { |entry| nested_entry?(entry) ? enumerate_nested(entry) : enumerate_leaf(entry) }
+      def enumerate(prefix: nil, include_keyless: false)
+        out = @data.entries.flat_map do |entry|
+          nested_entry?(entry) ? enumerate_nested(entry, include_keyless: include_keyless) : enumerate_leaf(entry)
+        end
         out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
         out.sort_by { |row| row[:key] }
       end
@@ -62,10 +64,14 @@ module Textus
         File.exist?(fp) ? [{ key: entry.key, path: fp, manifest_entry: entry }] : []
       end
 
-      def enumerate_nested(entry)
+      def enumerate_nested(entry, include_keyless: false)
         # publish_tree mirrors opaque payload by path — its files are never
         # enumerated as keys (ADR 0047). Ask the resolved mode, not the path.
-        return [] if entry.publish_mode.keyless?
+        # The `include_keyless:` override is used only by the projection lister
+        # so that `from: project` selects can read source data from keyless
+        # nested entries (e.g. knowledge.decisions) without exposing them as
+        # addressable store keys in the public `list` surface.
+        return [] if entry.publish_mode.keyless? && !include_keyless
 
         base = File.join(@data.root, "zones", entry.path)
         return [] unless File.directory?(base)

data/lib/textus/manifest/rules.rb

@@ -1,8 +1,13 @@
 module Textus
   class Manifest
     class Rules
-      RuleSet = ::Data.define(:handler_allowlist, :guard, :lifecycle)
-      EMPTY_SET = RuleSet.new(handler_allowlist: nil, guard: nil, lifecycle: nil)
+      # 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) })
@@ -15,17 +20,13 @@ module Textus
       attr_reader :blocks
 
       def for(key)
-        slots = { handler_allowlist: [], guard: [], lifecycle: [] }
+        slots = PICK_FIELDS.to_h { |f| [f, []] }
         @blocks.each do |b|
           next unless Textus::Domain::Policy::Matcher.matches?(b.match, key)
 
           slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
         end
-        RuleSet.new(
-          handler_allowlist: pick(slots[:handler_allowlist], :handler_allowlist, key),
-          guard: pick(slots[:guard], :guard, key),
-          lifecycle: pick(slots[:lifecycle], :lifecycle, key),
-        )
+        RuleSet.new(**slots.to_h { |slot, blocks| [slot, pick(blocks, slot, key)] })
       end
 
       def explain(key)
@@ -43,41 +44,41 @@ module Textus
       end
 
       class Block
-        attr_reader :match, :handler_allowlist, :guard, :lifecycle
+        attr_reader :match, *Schema::FIELD_REGISTRY.keys
 
         def initialize(raw)
           @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
-          @handler_allowlist = parse_handler_allowlist(raw["intake_handler_allowlist"])
-          @guard = parse_guard(raw["guard"])
-          @lifecycle = parse_lifecycle(raw["lifecycle"])
+          Schema::FIELD_REGISTRY.each do |field, meta|
+            instance_variable_set("@#{field}", parse_field(meta, raw[meta[:yaml_key]]))
+          end
         end
 
         private
 
-        def parse_handler_allowlist(arr)
-          return nil if arr.nil?
-
-          Textus::Domain::Policy::HandlerAllowlist.new(handlers: arr)
-        end
-
-        # A guard: block is a map of transition => [predicate specs]. Predicate
-        # names are validated at GuardFactory build time via Predicates::Registry
-        # (ADR 0031); here we only assert the structural shape.
-        def parse_guard(h)
-          return nil if h.nil?
-          raise Textus::BadManifest.new("guard: must be a map of transition => [predicates]") unless h.is_a?(Hash)
-
-          h
-        end
-
-        def parse_lifecycle(h)
-          return nil if h.nil?
-
-          Textus::Domain::Policy::Lifecycle.new(
-            ttl: h["ttl"],
-            on_expire: h["on_expire"],
-            budget_ms: h["budget_ms"],
-          )
+        # 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 GuardFactory build 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

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

@@ -0,0 +1,98 @@
+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 zones entries rules audit].freeze
+        ROLE_KEYS  = %w[name can].freeze
+        ZONE_KEYS  = %w[name kind owner desc].freeze
+        ENTRY_KEYS = %w[
+          key path zone kind schema owner nested format
+          source publish
+          events ignore tracked
+        ].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 on_write inject_boot provenance
+          select pluck sort_by transform
+        ].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 (handler_allowlist's intake_ prefix
+        #                disambiguates from entry-level intake:, ADR 0059)
+        #   policy_class the Domain::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 GuardFactory
+        #                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 = {
+          handler_allowlist: {
+            yaml_key: "intake_handler_allowlist",
+            policy_class: Textus::Domain::Policy::HandlerAllowlist,
+            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,
+            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::Domain::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]
+          },
+        }.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