textus 0.51.0 → 0.52.0

data/docs/reference/conventions.md

@@ -51,7 +51,7 @@ Tooling around `git blame` or audit logs may filter on owner; the gem itself onl
 
 A derived entry declares a `source:` block with a `from:` discriminator (ADR 0093/0094). A `source:` acquires **data** — it never renders; rendering is a publish concern (below). Two `from:` values for derived entries:
 
-**`source: { from: project }`** — textus computes the entry's data on `textus reconcile` from other store entries. Declarative; nothing shells out. Projection fields are flat under `source:`.
+**`source: { from: project }`** — textus computes the entry's data on `textus drain` from other store entries. Declarative; nothing shells out. Projection fields are flat under `source:`.
 
 ```yaml
 - key: artifacts.derived.people
@@ -69,7 +69,7 @@ A derived entry declares a `source:` block with a `from:` discriminator (ADR 009
     - { to: docs/people.md, template: people.mustache }   # render the data through a template
 ```
 
-**`source: { from: command }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `reconcile` (default: `automation`).
+**`source: { from: command }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `converge` (default: `automation`).
 
 ```yaml
 - key: artifacts.derived.skills
@@ -88,11 +88,11 @@ Full contract for both shapes is in [`../../SPEC.md` §5.2.1 and §5.2.2](../../
 
 ## Intake and freshness
 
-External inputs land via `:resolve_handler` hooks, not shell commands. Each intake entry declares `source: { from: handler, handler: <name>, ttl: <dur> }`; re-pull is system-pushed via `reconcile` (scheduled sweep) and `hook run` (event push) — a `get` never refreshes (ADR 0089):
+External inputs land via `:resolve_handler` hooks, not shell commands. Each intake entry declares `source: { from: handler, handler: <name>, ttl: <dur> }`; re-pull is system-pushed via `drain` (scheduled sweep) and `hook run` (event push) — a `get` never refreshes (ADR 0089):
 
 ```sh
 textus pulse --output=json                             # `stale` lists expired entries; `next_due_at` is the soonest deadline
-textus reconcile --as=automation                       # re-pulls every intake entry past its source.ttl
+textus drain --as=automation                       # re-pulls every intake entry past its source.ttl
 ```
 
 The re-pull cadence is the entry's own `source.ttl`. Age-based garbage collection is the orthogonal `retention:` rule slot in the top-level `rules:` block, matched by glob (`{ ttl, action: drop | archive }`); the two compose — re-pull hourly *and* archive at 90 days:
@@ -108,11 +108,11 @@ rules:
     retention: { ttl: 90d, action: archive }
 ```
 
-A typical scheduled integration runs `reconcile` on a cron to re-pull every
+A typical scheduled integration runs `drain` on a cron to re-pull every
 expired feed:
 
 ```sh
-textus reconcile --as=automation   # in cron / CI — re-pulls all stale feeds
+textus drain --as=automation   # in cron / CI — re-pulls all stale feeds
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
@@ -123,9 +123,9 @@ There is one public read operation, and it is pure (ADR 0089):
 
 | Operation | Behaviour | Use for |
 |-----------|-----------|---------|
-| `ops.get` | A pure on-disk read annotated with a freshness verdict — it NEVER ingests, regardless of the entry's `action`. A stale `refresh` entry reads back stale until the next `reconcile`. | every caller — interactive reads, dashboards, scripts, and internal pipelines (materializer, projection, schema tooling, accept/reject/publish, uid, validator) |
+| `ops.get` | A pure on-disk read annotated with a freshness verdict — it NEVER ingests, regardless of the entry's `action`. A stale `refresh` entry reads back stale until the next `drain`. | every caller — interactive reads, dashboards, scripts, and internal pipelines (materializer, projection, schema tooling, accept/reject/publish, uid, validator) |
 
-Refreshing a stale entry is `reconcile`'s job (or a `hook run` event), never a read's — so no caller can accidentally trigger network I/O by reading.
+Refreshing a stale entry is `drain`'s job (or a `hook run` event), never a read's — so no caller can accidentally trigger network I/O by reading.
 
 ## Body content
 

data/lib/textus/boot.rb

@@ -26,9 +26,9 @@ module Textus
         "propose changes by writing #{manifest.policy.queue_zone}.* entries with --as=#{name} " \
           "and a 'proposal:' frontmatter block; the #{authority} role runs 'textus accept' to apply"
       end,
-      reconcile: lambda do |_name, manifest|
+      converge: lambda do |_name, manifest|
         machine = zone_label(manifest, :machine, "machine")
-        "'textus reconcile' materializes derived #{machine} entries from their sources and " \
+        "'textus drain' materializes derived #{machine} entries from their sources and " \
           "refreshes stale intake #{machine} entries from their declared source; " \
           "derived files are never hand-edited (reactive on canon writes, or a full pass on demand)"
       end,
@@ -84,13 +84,15 @@ module Textus
       { "name" => "put" },
       { "name" => "propose" },
       { "name" => "accept" },
+      { "name" => "enqueue" },
       { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
-      { "name" => "reconcile" },
+      { "name" => "drain" },
       { "name" => "audit" },
       { "name" => "blame" },
       { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
       { "name" => "doctor" },
       { "name" => "hook", "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "jobs" },
       { "name" => "pulse" },
       { "name" => "capabilities" },
     ].freeze
@@ -172,11 +174,11 @@ module Textus
             "accept #{queue}.KEY — promotes the proposal into its target zone",
           ],
         },
-        "reconcile" => {
+        "drain" => {
           "purpose" => "keep the machine-maintained lanes fresh — re-pull stale intake entries from their declared source",
           "steps" => [
             "pulse — its `stale` list names entries past their ttl",
-            "reconcile (zone: #{feeds}) — re-pull the stale entries",
+            "drain (zone: #{feeds}) — re-pull the stale entries",
           ],
         },
       }

data/lib/textus/cli/runner.rb

@@ -132,7 +132,7 @@ module Textus
       #           affordance; the agent surface deliberately returns nil)
       #   put   — reads the entry JSON from --stdin (ADR 0089: just stores bytes,
       #           no --fetch transform)
-      # (build removed in ADR 0087: materialization is system-pushed via reconcile)
+      # (build removed in ADR 0087: materialization is system-pushed via drain/serve)
       BEHAVIORAL_HATCHES = %i[get put].freeze
 
       # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
@@ -144,7 +144,7 @@ module Textus
       # the exit_code: res["ok"] ? 0 : 1 behavior — two things the generic
       # projection cannot yet express; kept in ADR 0101 pending a future pass.)
       # (fetch/fetch_all were removed in ADR 0079: Produce::Acquire::Intake is now internal,
-      # driven by the reconcile sweep and hook run — ADR 0089 removed the
+      # driven by the converge sweep (drain/serve) and hook run — ADR 0089 removed the
       # read-through that once also drove it.)
       NON_PROJECTED_CLI = %i[doctor].freeze
 

data/lib/textus/cli/verb/put.rb

@@ -14,7 +14,7 @@ module Textus
           role = resolved_role(store)
 
           # put only stores the stdin JSON (ADR 0089): no transform-on-write.
-          # Ingest (running a handler over bytes) is system-pushed via reconcile
+          # Ingest (running a handler over bytes) is system-pushed via drain/serve
           # and hook run, never a put flag.
           payload = JSON.parse(@stdin.read)
 

data/lib/textus/cli/verb/serve.rb

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class Verb
+      # Launches the convergence daemon in the current process. Blocks forever;
+      # reclaims crashed leases and drains the queue each tick (Phase 3 adds
+      # scheduled TTL re-pull/sweep). CLI-only — agents enqueue work, they do not
+      # run daemons. Acts as the automation role (the build authority).
+      class Serve < Verb
+        command_name "serve"
+
+        def call(store)
+          call = Textus::Call.build(role: Textus::Role::AUTOMATION)
+          Textus::Maintenance::Serve.new(container: store.container, call: call).run
+          0
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatcher.rb

@@ -11,6 +11,7 @@ module Textus
       key_mv: Textus::Write::KeyMv,
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
+      enqueue: Textus::Write::Enqueue,
       # Read
       get: Textus::Read::Get,
       list: Textus::Read::List,
@@ -30,12 +31,13 @@ module Textus
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       capabilities: Textus::Read::Capabilities,
+      jobs: Textus::Read::Jobs,
 
       # Maintenance
       zone_mv: Textus::Maintenance::ZoneMv,
       key_mv_prefix: Textus::Maintenance::KeyMvPrefix,
       key_delete_prefix: Textus::Maintenance::KeyDeletePrefix,
-      reconcile: Textus::Maintenance::Reconcile,
+      drain: Textus::Maintenance::Drain,
       rule_lint: Textus::Maintenance::RuleLint,
     }.freeze
 

data/lib/textus/doctor/check/generator_drift.rb

@@ -19,7 +19,7 @@ module Textus
               "level" => "warning",
               "subject" => row["key"],
               "message" => row["reason"],
-              "fix" => "rematerialize the entry: `textus reconcile`",
+              "fix" => "rematerialize the entry: `textus drain`",
             }
           end
         end

data/lib/textus/doctor/check/sentinels.rb

@@ -31,7 +31,7 @@ module Textus
             "level" => "warning",
             "subject" => sentinel_path,
             "message" => "sentinel is not valid JSON",
-            "fix" => "delete #{sentinel_path} and re-run 'textus reconcile' to regenerate",
+            "fix" => "delete #{sentinel_path} and re-run 'textus drain' to regenerate",
           }
         end
 
@@ -51,7 +51,7 @@ module Textus
             "level" => "warning",
             "subject" => sentinel.target,
             "message" => "published file at #{sentinel.target} was modified out-of-band",
-            "fix" => "re-run 'textus reconcile' to overwrite, or copy the manual edit back into the store source",
+            "fix" => "re-run 'textus drain' to overwrite, or copy the manual edit back into the store source",
           }
         end
       end

data/lib/textus/domain/freshness/evaluator.rb

@@ -10,7 +10,7 @@ module Textus
       #     (skipped — a cadence-less handler is not auto-re-pulled).
       #   - derived/external -> DRIFT signal: a source changed since generated.at
       #     (surfaced by the doctor generator_drift check; derived entries annotate
-      #     fresh at read time because reconcile converges them reactively).
+      #     fresh at read time because converge runs them reactively).
       # Replaces Domain::IntakeStaleness and Domain::Staleness::GeneratorCheck and
       # the inline copies in Read::Get / Read::Freshness.
       class Evaluator
@@ -32,7 +32,7 @@ module Textus
           Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
         end
 
-        # Keys of intake entries past their source.ttl — the reconcile produce
+        # Keys of intake entries past their source.ttl — the converge produce
         # scope (replaces Domain::IntakeStaleness#call). A ttl-less intake entry
         # is :no_policy and skipped; a never-recorded one (with a ttl) is stale.
         def stale_intake_keys(prefix: nil, zone: nil)

data/lib/textus/domain/jobs/job.rb

@@ -0,0 +1,58 @@
+require "digest"
+require "json"
+
+module Textus
+  module Domain
+    module Jobs
+      # A unit of deferred work. Pure data. The id is `<type>:<digest>` where the
+      # digest is over the args with sorted keys, so logically-identical enqueues
+      # collide on the same id — which is how the Queue dedups (the file already
+      # exists). At-least-once delivery means handlers must be idempotent.
+      class Job
+        DIGEST_BYTES = 16
+
+        attr_reader :type, :args, :enqueued_by, :max_attempts
+        attr_accessor :attempts, :last_error
+
+        def initialize(type:, args:, enqueued_by: nil, attempts: 0, max_attempts: 3, last_error: nil)
+          @type = type.to_s
+          @args = stringify(args)
+          @enqueued_by = enqueued_by
+          @attempts = attempts
+          @max_attempts = max_attempts
+          @last_error = last_error
+        end
+
+        def id
+          "#{@type}:#{digest}"
+        end
+
+        def to_h
+          {
+            "type" => @type, "args" => @args, "enqueued_by" => @enqueued_by,
+            "attempts" => @attempts, "max_attempts" => @max_attempts, "last_error" => @last_error
+          }
+        end
+
+        def self.from_h(hash)
+          new(
+            type: hash["type"], args: hash["args"] || {}, enqueued_by: hash["enqueued_by"],
+            attempts: hash["attempts"] || 0, max_attempts: hash["max_attempts"] || 3,
+            last_error: hash["last_error"]
+          )
+        end
+
+        private
+
+        def digest
+          canonical = JSON.dump(@args.sort.to_h)
+          Digest::SHA256.hexdigest(canonical)[0, DIGEST_BYTES]
+        end
+
+        def stringify(hash)
+          hash.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/jobs/registry.rb

@@ -0,0 +1,37 @@
+module Textus
+  module Domain
+    module Jobs
+      # Closed allow-list of runnable job types. The general `enqueue` surface
+      # (a later phase) can only push types registered here — that is the safety
+      # boundary that stops the "general runner" from running arbitrary code.
+      class Registry
+        Entry = Struct.new(:handler, :max_attempts, :required_role, keyword_init: true)
+
+        def initialize
+          @entries = {}
+        end
+
+        # required_role: a role the caller must hold to enqueue this type via the
+        # general `enqueue` surface (nil = any caller). The closed allow-list is
+        # the primary safety boundary; this is defence-in-depth for destructive
+        # types.
+        def register(type, handler:, max_attempts: 3, required_role: nil)
+          @entries[type.to_s] = Entry.new(handler: handler, max_attempts: max_attempts, required_role: required_role)
+        end
+
+        def registered?(type)
+          @entries.key?(type.to_s)
+        end
+
+        def lookup(type)
+          @entries.fetch(type.to_s) do
+            raise Textus::UsageError.new(
+              "unregistered job type '#{type}'",
+              hint: "register the type in Domain::Jobs::Registry before enqueueing it",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/base_guards.rb

@@ -15,7 +15,7 @@ module Textus
           key_mv: %w[zone_writable_by],
           accept: %w[author_held target_is_canon],
           reject: %w[author_held],
-          reconcile: %w[zone_writable_by],
+          converge: %w[zone_writable_by],
         }.freeze
 
         def self.for(transition) = BASE.fetch(transition, [])

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

@@ -3,7 +3,7 @@ module Textus
     module Policy
       # Garbage collection (ADR 0093). A glob-matched rule slot: when an entry
       # ages past `ttl`, retire it. Destructive only — runs on the full
-      # `reconcile` pass, never on a write (ADR 0079's invariant). Orthogonal to
+      # `converge` pass, never on a write (ADR 0079's invariant). Orthogonal to
       # production (`source:`): an intake entry can re-pull hourly AND archive
       # after 90 days. `warn`/`refresh` are gone (refresh is implied by an
       # intake source; warn never fired after ADR 0089's pure-read get).

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

@@ -7,11 +7,11 @@ module Textus
       #   from: project -> derived  (internal projection; observable -> rdeps staleness)
       #   from: handler -> intake   (external fetch; unobservable -> ttl staleness)
       #   from: command -> external (out-of-band runner; staleness only, textus never runs it)
-      # `on_write` (sync|async, default async) is the write-trigger strategy for
-      # observable (project) sources; meaningless for intake/command.
+      # 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.
       class Source
-        FROMS      = %w[project handler command].freeze
-        STRATEGIES = %w[async sync].freeze
+        FROMS = %w[project handler command].freeze
 
         attr_reader :from, :handler, :config, :command, :sources
 
@@ -21,11 +21,6 @@ module Textus
             raise Textus::BadManifest.new("source.from must be one of #{FROMS.join("|")}, got #{raw["from"].inspect}")
           end
 
-          @on_write = (raw["on_write"] || "async").to_s
-          unless STRATEGIES.include?(@on_write)
-            raise Textus::BadManifest.new("source.on_write must be one of #{STRATEGIES.join("/")}, got #{@on_write.inspect}")
-          end
-
           @ttl = raw["ttl"]
           @projection = {}
 
@@ -39,7 +34,6 @@ module Textus
         def kind        = @from == "handler" ? :intake : :derived
         def external?   = @from == "command"
         def projection? = @from == "project"
-        def sync?       = @on_write == "sync"
         def ttl_seconds = @ttl.nil? ? nil : Textus::Domain::Duration.seconds(@ttl)
 
         # Flattened projection accessors (ADR 0094) — read directly off the source

data/lib/textus/errors.rb

@@ -166,9 +166,9 @@ module Textus
     def initialize(m, format: nil)
       hint =
         if format
-          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running reconcile"
+          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running drain"
         else
-          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running reconcile"
+          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running drain"
         end
       super("bad_render", m, hint: hint)
     end

data/lib/textus/hooks/catalog.rb

@@ -17,7 +17,6 @@ module Textus
         entry_renamed: %i[ctx key from_key to_key envelope],
         entry_produced: %i[ctx key envelope sources],
         produce_failed: %i[ctx keys error],
-        reconcile_failed: %i[ctx failed],
         proposal_accepted: %i[ctx key target_key],
         proposal_rejected: %i[ctx key target_key],
         entry_published: %i[ctx key envelope source target],

data/lib/textus/init/templates/machine_intake.rb

@@ -1,7 +1,7 @@
 # .textus/hooks/machine_intake.rb
 # Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
 # entry from manifest.yaml if you don't want it.
-# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus reconcile`
+# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus drain`
 # (never on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
 # `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
 # (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an

data/lib/textus/init.rb

@@ -10,7 +10,7 @@ module Textus
       roles:
         - { name: human,      can: [author, propose] }
         - { name: agent,      can: [propose, keep] }
-        - { name: automation, can: [reconcile] }
+        - { name: automation, can: [converge] }
       zones:
         - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
         - { name: notebook,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
@@ -21,7 +21,7 @@ module Textus
         - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
         - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
         - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
-        # A per-host snapshot, refreshed from its declared intake by `textus reconcile` (scheduled, or on demand).
+        # A per-host snapshot, refreshed from its declared intake by `textus drain` (scheduled, or on demand).
         # Nested so it grows to a fleet — add artifacts.feeds.machines.<host> leaves over SSH
         # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
         # gitignored (machine info can be sensitive/noisy) but still protocol-readable
@@ -95,7 +95,7 @@ module Textus
 
       Events: :resolve_handler, :transform_rows, :validate (rpc — return value used)
               :entry_written, :entry_deleted, :entry_fetched, :entry_renamed,
-              :entry_produced, :produce_failed, :reconcile_failed,
+              :entry_produced, :produce_failed,
               :proposal_accepted, :proposal_rejected,
               :entry_published, :store_loaded, :session_opened,
               :entry_fetch_started, :entry_fetch_failed (pub-sub — return discarded)
@@ -105,7 +105,7 @@ module Textus
 
     AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
       # --with-agent profile: project facts + runbooks feed the orientation
-      # projection below, which `textus reconcile` renders to CLAUDE.md/AGENTS.md.
+      # projection below, which `textus drain` renders to CLAUDE.md/AGENTS.md.
       - { key: knowledge.project, path: knowledge/project.md, zone: knowledge, schema: project, owner: human:self, kind: leaf }
       - { key: knowledge.runbooks, path: knowledge/runbooks, zone: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
       - key: artifacts.derived.orientation

data/lib/textus/jobs/handlers.rb

@@ -0,0 +1,62 @@
+module Textus
+  module Jobs
+    # Wires the closed allow-list of convergence job types to the existing
+    # convergence code. Authority is read from the job's frozen `enqueued_by`
+    # and turned into the Call the handler runs under: produce self-elevates
+    # inside Produce::Engine regardless; destructive sweep runs AS the caller.
+    module Handlers
+      module_function
+
+      def registry
+        reg = Textus::Domain::Jobs::Registry.new
+        # produce is pure (self-elevates) — any caller may request a rematerialize.
+        reg.register("materialize", handler: method(:produce))
+        reg.register("re-pull",     handler: method(:produce))
+        # sweep is destructive — gate ad-hoc enqueue to the automation authority.
+        reg.register("sweep",       handler: method(:sweep), required_role: Textus::Role::AUTOMATION)
+        reg
+      end
+
+      # produce: render derived / re-pull intake for a single key. Engine
+      # self-elevates to the build actor internally; the passed call carries
+      # only correlation/dry_run plus the stamped role for audit. Engine#call
+      # isolates per-key produce errors into its result hash rather than raising,
+      # so surface them as :produce_failed events (the converge result hash used
+      # to carry them; the worker drops the return, so re-publish here).
+      def produce(job:, container:)
+        call = call_for(job)
+        result = Textus::Produce::Engine.converge(container: container, call: call, keys: [job.args["key"]])
+        return unless result.is_a?(Hash)
+
+        Array(result[:failed]).each do |failure|
+          container.events.publish(
+            :produce_failed,
+            ctx: Textus::Hooks::Context.for(container: container, call: call),
+            keys: [failure["key"]], error: failure["error"]
+          )
+        end
+      end
+
+      # sweep: compute retention rows for the scope, then apply destructively AS
+      # the job's role (no self-elevation).
+      def sweep(job:, container:)
+        call = call_for(job)
+        scope = job.args["scope"]
+        rows = Textus::Domain::Retention::Sweep.new(
+          manifest: container.manifest,
+          file_stat: Textus::Ports::Storage::FileStat.new,
+          clock: Textus::Ports::Clock.new,
+        ).call(prefix: scope_prefix(scope), zone: scope_zone(scope))
+        Textus::Maintenance::Retention::Apply.new(container: container, call: call).call(rows)
+      end
+
+      def call_for(job)
+        Textus::Call.build(role: job.enqueued_by || Textus::Role::AUTOMATION)
+      end
+
+      # A scope is `{ "prefix" => ..., "zone" => ... }` or nil (whole store).
+      def scope_prefix(scope) = scope.is_a?(Hash) ? scope["prefix"] : nil
+      def scope_zone(scope)   = scope.is_a?(Hash) ? scope["zone"]   : nil
+    end
+  end
+end

data/lib/textus/jobs/scheduler.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Jobs
+    # Time-based seeding for the daemon: at each tick, enqueue a re-pull job for
+    # every intake key past its source.ttl and a sweep job to GC entries past
+    # retention.ttl. Dedup means a job already queued from a prior tick is a
+    # no-op. Both are stamped automation (the daemon's own authority); the sweep
+    # handler runs retention as that role.
+    class Scheduler
+      def initialize(container:, queue:)
+        @container = container
+        @queue = queue
+      end
+
+      def run_once
+        stale_intake.each do |key|
+          @queue.enqueue(job("re-pull", { "key" => key }))
+        end
+        @queue.enqueue(job("sweep", { "scope" => { "prefix" => nil, "zone" => nil } }))
+      end
+
+      private
+
+      def stale_intake
+        Textus::Domain::Freshness::Evaluator.new(
+          manifest: @container.manifest,
+          file_stat: Textus::Ports::Storage::FileStat.new,
+          clock: Textus::Ports::Clock.new,
+        ).stale_intake_keys(prefix: nil, zone: nil)
+      end
+
+      def job(type, args)
+        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: Textus::Role::AUTOMATION)
+      end
+    end
+  end
+end

data/lib/textus/jobs/seeder.rb

@@ -0,0 +1,57 @@
+module Textus
+  module Jobs
+    # Enqueues the full convergence set for a scope: a produce job per derived /
+    # publish_tree / publish.to entry, a re-pull job per stale intake key, and a
+    # single sweep job for the scope. The scope logic mirrors
+    # the converge scope (Produce::Engine) so `drain` and `serve` converge identically.
+    # Produce jobs self-elevate (stamped automation); the sweep job carries the
+    # caller's role (destructive runs as caller).
+    class Seeder
+      def initialize(container:, queue:, call:)
+        @container = container
+        @queue = queue
+        @call = call
+        @manifest = container.manifest
+      end
+
+      def seed(prefix:, zone:)
+        file_stat = Textus::Ports::Storage::FileStat.new
+
+        producible_keys(prefix, zone).each do |key|
+          @queue.enqueue(job("materialize", { "key" => key }, Textus::Role::AUTOMATION))
+        end
+        stale_intake_keys(prefix, zone, file_stat).each do |key|
+          @queue.enqueue(job("re-pull", { "key" => key }, Textus::Role::AUTOMATION))
+        end
+        @queue.enqueue(job("sweep", { "scope" => { "prefix" => prefix, "zone" => zone } }, @call.role))
+      end
+
+      private
+
+      def job(type, args, role)
+        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: role)
+      end
+
+      # Mirrors the converge scope (the publishable arm).
+      def producible_keys(prefix, zone)
+        @manifest.data.entries
+                 .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
+                 .select { |e| in_scope?(e, prefix, zone) }
+                 .map(&:key)
+      end
+
+      def stale_intake_keys(prefix, zone, file_stat)
+        Textus::Domain::Freshness::Evaluator.new(
+          manifest: @manifest, file_stat: file_stat, clock: Textus::Ports::Clock.new,
+        ).stale_intake_keys(prefix: prefix, zone: zone)
+      end
+
+      def in_scope?(entry, prefix, zone)
+        return false if zone && entry.zone != zone
+        return false if prefix && !entry.key.start_with?(prefix)
+
+        true
+      end
+    end
+  end
+end

data/lib/textus/layout.rb

@@ -25,6 +25,14 @@ module Textus
       File.join(run(root), "build.lock")
     end
 
+    def self.queue(root)
+      File.join(run(root), "queue")
+    end
+
+    def self.queue_state(root, state)
+      File.join(queue(root), state.to_s)
+    end
+
     def self.audit_dir(root)
       File.join(run(root), "audit")
     end