textus 0.50.0 → 0.52.0

data/lib/textus/maintenance/worker.rb

@@ -0,0 +1,74 @@
+module Textus
+  module Maintenance
+    # Drains the job queue: lease a job, look up its handler in the registry, run
+    # it (as the job's stamped authority — wired in a later phase), then ack on
+    # success or fail (requeue/dead-letter) on a raise. `drain` runs until the
+    # queue is empty and returns a summary. Delivery is at-least-once.
+    class Worker
+      Summary = Struct.new(:completed, :failed, keyword_init: true)
+
+      # The standard convergence worker: the closed handler allow-list plus the
+      # lease TTL from worker_config. Both `drain` and `serve` build it this way.
+      def self.for(container:, queue:)
+        new(
+          queue: queue, registry: Textus::Jobs::Handlers.registry,
+          container: container, lease_ttl: container.manifest.data.worker_config[:lease_ttl]
+        )
+      end
+
+      def initialize(queue:, registry:, container:, lease_ttl: 60)
+        @queue = queue
+        @registry = registry
+        @container = container
+        @lease_ttl = lease_ttl
+      end
+
+      def drain(worker_id: "drain-#{Process.pid}")
+        completed = 0
+        failed = 0
+        loop do
+          leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
+          break unless leased
+
+          case run_one(leased)
+          when :completed     then completed += 1
+          when :dead_lettered then failed += 1
+            # :requeued -> a transient failure; it re-leases on a later iteration
+          end
+        end
+        Summary.new(completed: completed, failed: failed)
+      end
+
+      def drain_pool(pool: 4)
+        summaries = []
+        mutex = Mutex.new
+        threads = Array.new(pool) do |i|
+          Thread.new do
+            s = drain(worker_id: "pool-#{Process.pid}-#{i}")
+            mutex.synchronize { summaries << s }
+          end
+        end
+        threads.each(&:join)
+        Summary.new(
+          completed: summaries.sum(&:completed),
+          failed: summaries.sum(&:failed),
+        )
+      end
+
+      private
+
+      # Returns :completed on ack, or the queue's failure verdict (:requeued |
+      # :dead_lettered) on a raise. A requeued job re-leases on the next loop
+      # iteration, so a transient failure still drains; only a dead-letter is a
+      # terminal failure that counts toward the summary.
+      def run_one(leased)
+        entry = @registry.lookup(leased.job.type)
+        entry.handler.call(job: leased.job, container: @container)
+        @queue.ack(leased)
+        :completed
+      rescue StandardError => e
+        @queue.fail(leased, error: e.message)
+      end
+    end
+  end
+end

data/lib/textus/manifest/capabilities.rb

@@ -13,7 +13,7 @@ module Textus
       DEFAULT_MAPPING = {
         Textus::Role::HUMAN => %w[author propose].freeze,
         Textus::Role::AGENT => %w[propose].freeze,
-        Textus::Role::AUTOMATION => %w[fetch build].freeze,
+        Textus::Role::AUTOMATION => %w[converge].freeze,
       }.freeze
 
       # Returns { role_name => [verbs] }. When `roles:` is declared we use

data/lib/textus/manifest/data.rb

@@ -10,10 +10,11 @@ module Textus
     # resolution, rules) lives on Manifest::Policy / Resolver / Rules.
     class Data
       AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
+      WORKER_DEFAULTS = { pool: 4, poll: 5, lease_ttl: 60, max_attempts: 3 }.freeze
 
       attr_reader :raw, :root, :entries, :declared_zone_kinds,
                   :zone_descs, :zone_owners,
-                  :audit_config, :role_caps, :policy
+                  :audit_config, :worker_config, :role_caps, :policy
 
       def self.validate_key!(key)
         raise UsageError.new("empty key") if key.nil? || key.empty?
@@ -47,10 +48,11 @@ module Textus
         # future `zone_owners.key?(name)` means "owner declared", not "zone exists".
         @zone_owners = Array(raw["zones"]).to_h { |z| [z["name"], z["owner"]] }.compact
         @audit_config = build_audit_config(raw)
+        @worker_config = build_worker_config(raw)
         @role_caps = Capabilities.resolve(raw["roles"])
         # Policy is constructed before entries because Entry validators
-        # call `entry.in_generator_zone?(policy)` and similar helpers
-        # that take Policy as an argument.
+        # use the entry's own `derived?` and similar helpers that call into
+        # Policy; Policy must exist before entries are built.
         @policy = Policy.new(self)
         @entries = build_entries(raw)
         validate_declared_keys!
@@ -67,6 +69,19 @@ module Textus
         }.freeze
       end
 
+      # Worker/queue tunables (ADR: job-queue execution model). All optional;
+      # the daemon (serve) and batch drain read these, falling back to defaults
+      # so a manifest with no `worker:` block runs the queue out of the box.
+      def build_worker_config(raw)
+        w = raw["worker"] || {}
+        {
+          pool: w["pool"] || WORKER_DEFAULTS[:pool],
+          poll: w["poll"] || WORKER_DEFAULTS[:poll],
+          lease_ttl: w["lease_ttl"] || WORKER_DEFAULTS[:lease_ttl],
+          max_attempts: w["max_attempts"] || WORKER_DEFAULTS[:max_attempts],
+        }.freeze
+      end
+
       def build_entries(raw)
         Array(raw["entries"]).map do |e|
           entry = Manifest::Entry::Parser.call(e)

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

@@ -2,10 +2,10 @@ module Textus
   class Manifest
     class Entry
       class Base < Entry
-        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :publish_to
+        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :publish_targets
 
         # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
-        def initialize(raw:, key:, path:, zone:, schema:, owner:, format:, publish_to: [])
+        def initialize(raw:, key:, path:, zone:, schema:, owner:, format:, publish_targets: [])
           @raw = raw
           @key = key
           @path = path
@@ -13,7 +13,7 @@ module Textus
           @schema = schema
           @owner = owner
           @format = format
-          @publish_to = Array(publish_to)
+          @publish_targets = Array(publish_targets)
         end
         # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
 
@@ -23,28 +23,34 @@ module Textus
           raise UsageError.new("entry '#{@key}': #{e.message}")
         end
 
-        def in_generator_zone?(policy) = policy.derived_zone?(@zone)
-        def in_proposal_zone?(policy)  = policy.queue_zone?(@zone)
+        def in_proposal_zone?(policy) = policy.queue_zone?(@zone)
 
         def nested?  = false
         def derived? = false
         def intake?  = false
         def leaf?    = false
 
+        # Production traits. Default false on Base (a leaf/intake entry is neither
+        # an out-of-band command nor a projection); Produced overrides both from
+        # its source. Lets publish modes call these without a `respond_to?` guard.
+        def external?   = false
+        def projection? = false
+
         # Whether git should track this entry's file. Default true; an entry
         # marked `tracked: false` in the manifest stays protocol-readable but is
         # listed in the generated `.gitignore` (ADR 0043). Cross-cutting, so it
         # reads from raw here rather than threading through every constructor.
         def tracked? = @raw["tracked"] != false
 
+        # Single source of truth is @publish_targets (ADR 0094). These
+        # derive the ADR-0049/0052 views the publish modes consume.
+        def publish_to   = @publish_targets.select(&:to_target?).map(&:to)
+        def publish_tree = @publish_targets.find(&:tree_target?)&.tree
+
         # Nil stubs for cross-cutting optional attrs. Subclasses override the
         # ones they own. Validators and serializers can call these directly
         # without `respond_to?` guards.
-        def template       = nil
-        def inject_boot    = false # rubocop:disable Naming/PredicateMethod
-        def provenance     = true  # rubocop:disable Naming/PredicateMethod
         def events         = {}
-        def publish_tree   = nil
         def ignore         = []
 
         # Per-entry ignore (ADR 0042). Base entries enumerate no tree, so
@@ -69,6 +75,19 @@ module Textus
             events.publish(event, ctx: hook_context, **payload)
           end
 
+          # Read a named template from the store's templates/ directory.
+          # Raises TemplateError when the file doesn't exist.
+          def read_template(name)
+            path = File.join(container.root.to_s, "templates", name)
+            unless File.exist?(path)
+              raise Textus::TemplateError.new(
+                "template '#{name}' not found",
+                template_name: name,
+              )
+            end
+            File.read(path)
+          end
+
           private
 
           def scope_for_hooks

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

@@ -6,11 +6,10 @@ module Textus
       # Entry::Publish::* — Nested is just the value (attributes + ignore
       # predicate) those modes read.
       class Nested < Base
-        attr_reader :publish_tree, :ignore
+        attr_reader :ignore
 
-        def initialize(publish_tree: nil, ignore: nil, **rest)
+        def initialize(ignore: nil, **rest)
           super(**rest)
-          @publish_tree = publish_tree
           @ignore = Array(ignore)
         end
 
@@ -24,8 +23,8 @@ module Textus
         KIND = :nested
 
         def self.from_raw(common, raw)
+          # publish_tree is derived from publish_targets (ADR 0094) via Base#publish_tree
           new(
-            publish_tree: raw.dig("publish", "tree"), # ADR 0052: typed publish block
             ignore: raw["ignore"],
             **common,
           )

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

@@ -2,8 +2,6 @@ module Textus
   class Manifest
     class Entry
       module Parser
-        COMPUTE_KINDS = %w[projection external].freeze
-
         def self.call(raw)
           key = raw["key"] or raise UsageError.new("manifest entry missing key")
           path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
@@ -11,6 +9,12 @@ module Textus
 
           raw_kind = raw["kind"] or raise BadManifest.new("entry '#{key}' missing required `kind:` (#{Entry::REGISTRY.keys.join("|")})")
           kind = raw_kind.to_sym
+          if %i[derived intake].include?(kind)
+            raise BadManifest.new(
+              "entry '#{key}': kind: #{kind} was collapsed into `kind: produced` (ADR 0095) — " \
+              "the produce method is `source.from` (#{kind == :intake ? "handler" : "project|command"})",
+            )
+          end
           format = resolve_format(raw, path)
 
           common = {
@@ -18,10 +22,7 @@ module Textus
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
             format: format,
-            # ADR 0052: publish config is one typed block; the internal
-            # publish_to/publish_tree readers (the ADR 0049 modes) are sourced
-            # from it (publish_to <- publish.to, publish_tree <- publish.tree).
-            publish_to: raw.dig("publish", "to")
+            publish_targets: publish_targets(raw)
           }
 
           klass = Entry::REGISTRY[kind] or
@@ -29,26 +30,29 @@ module Textus
           klass.from_raw(common, raw)
         end
 
+        # ADR 0093: an entry's production block is the unified `source:`. Returns a
+        # Domain::Policy::Source; kind (intake/derived) is read from source.from.
         def self.parse_source(raw, key)
-          compute = raw["compute"]
-          raise BadManifest.new("derived entry '#{key}' requires compute: { kind: projection|external } or template:") if compute.nil?
+          block = raw["source"] or
+            raise BadManifest.new("entry '#{key}' requires a source: { from: project|handler|command, ... }")
 
-          unless COMPUTE_KINDS.include?(compute["kind"])
-            raise BadManifest.new(
-              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{compute["kind"].inspect})",
-            )
-          end
+          Textus::Domain::Policy::Source.new(block)
+        end
 
-          if compute["kind"] == "projection"
-            Entry::Derived::Projection.new(
-              select: compute["select"],
-              pluck: compute["pluck"],
-              sort_by: compute["sort_by"],
-              transform: compute["transform"],
+        # ADR 0094: `publish:` is a LIST of target objects — to-targets
+        # [{to, template?, inject_boot?}] and/or a tree-target [{tree}]. The
+        # ADR-0052 map forms ({to: […]} / {tree: …}) are retired.
+        def self.publish_targets(raw)
+          block = raw["publish"]
+          return [] if block.nil?
+
+          unless block.is_a?(Array)
+            raise BadManifest.new(
+              "entry '#{raw["key"]}': `publish:` must be a list of targets " \
+              "[{to:, template:?} | {tree:}] (ADR 0094); the `publish: { … }` map form was retired",
             )
-          else
-            Entry::Derived::External.new(sources: compute["sources"], command: compute["command"])
           end
+          block.map { |t| Textus::Domain::Policy::PublishTarget.new(t) }
         end
 
         def self.resolve_format(raw, path)

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)