textus 0.51.0 → 0.52.0

data/lib/textus/produce/events.rb

@@ -1,7 +1,7 @@
 module Textus
   module Produce
     # Single home for the fetch lifecycle event vocabulary (ADR 0048 D5).
-    # Produce::Acquire::Intake (the ingest executor driven by reconcile + hook) emits through
+    # Produce::Acquire::Intake (the ingest executor driven by converge + hook) emits through
     # this seam so the event names and payload shapes live in one place with one
     # derived hook context.
     class Events

data/lib/textus/read/freshness.rb

@@ -10,7 +10,7 @@ module Textus
     #   - entries matched by a `retention:` rule: `retention.ttl_seconds` is the
     #     GC age; basis = file mtime. Past ttl ⇒ :expired (:action = drop/archive).
     # Intake cadence wins when both apply (freshness is content currency; GC dueness
-    # shows via `reconcile --dry-run`).
+    # shows via `drain --dry-run`).
     # Status is one of :fresh, :expired, or :no_policy; the row also carries
     # :action (:refresh for intake, :drop/:archive for retention).
     #
@@ -78,7 +78,7 @@ module Textus
       # ADR 0093: staleness comes from the intake re-pull cadence (source.ttl)
       # or a retention GC rule (retention.ttl). Intake cadence wins when an entry
       # has both (freshness is about content currency; GC dueness still shows via
-      # `reconcile --dry-run`). Returns [ttl_seconds, action] or [nil, nil].
+      # `drain --dry-run`). Returns [ttl_seconds, action] or [nil, nil].
       def policy_for(mentry)
         if mentry.intake?
           ttl = mentry.source.ttl_seconds

data/lib/textus/read/get.rb

@@ -2,16 +2,16 @@ module Textus
   module Read
     # The one read path — a pure read (ADR 0089, 0093): the on-disk envelope
     # annotated with a freshness annotation. It NEVER mutates and NEVER ingests.
-    # Quarantine freshness is system-pushed via `reconcile` (scheduled sweep) and
+    # Quarantine freshness is system-pushed via `drain` (scheduled sweep) and
     # `hook run` (event push). Lifecycle is removed from the get path (ADR 0093):
     # intake cadence lives in `source.ttl`; GC lives in `retention:` rules; both
-    # are evaluated exclusively by the `reconcile` sweep, not by a read.
+    # are evaluated exclusively by the `drain` sweep, not by a read.
     class Get
       extend Textus::Contract::DSL
 
       verb     :get
       summary  "Read one entry — a pure on-disk read annotated with a freshness " \
-               "verdict; never ingests (quarantine freshness is reconcile + hook " \
+               "verdict; never ingests (quarantine freshness is drain + hook " \
                "only, ADR 0089). Returns the envelope (uid, etag, _meta, body, " \
                "freshness)."
       surfaces :cli, :mcp

data/lib/textus/read/jobs.rb

@@ -0,0 +1,31 @@
+module Textus
+  module Read
+    # Inspect and operate the job queue: list ids by state, retry a dead-lettered
+    # job, or purge a state. The agent's window into deferred convergence work.
+    class Jobs
+      extend Textus::Contract::DSL
+
+      verb     :jobs
+      summary  "List queued jobs by state; retry a dead-lettered job or purge a state."
+      surfaces :cli, :mcp
+      cli      "jobs"
+      arg :state,  String, default: "ready", description: "ready|leased|done|failed"
+      arg :action, String, default: nil, description: "retry|purge (optional)"
+      arg :job_id, String, default: nil, description: "job id (required for action=retry)"
+
+      def initialize(container:, call:)
+        @container = container
+        @call = call
+      end
+
+      def call(state: "ready", action: nil, job_id: nil)
+        queue = Textus::Ports::Queue.new(root: @container.root)
+        case action
+        when "retry" then queue.retry_failed(job_id)
+        when "purge" then queue.purge(state)
+        end
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "state" => state, "jobs" => queue.list(state) }
+      end
+    end
+  end
+end

data/lib/textus/role.rb

@@ -1,7 +1,7 @@
 module Textus
   module Role
     # The three role archetypes, each string sourced exactly once: human curates
-    # canon, agent proposes, automation reconciles the machine-maintained lanes
+    # canon, agent proposes, automation converges the machine-maintained lanes
     # (refresh + materialize) (explanation/concepts.md).
     # Reference these constants instead of bare literals (ADR 0044).
     HUMAN      = "human".freeze

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.51.0"
+  VERSION = "0.52.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/enqueue.rb

@@ -0,0 +1,50 @@
+module Textus
+  module Write
+    # Push a job of a REGISTERED type onto the convergence queue, to be run by
+    # drain/serve. The closed allow-list (Jobs::Handlers.registry) is the safety
+    # boundary: an unregistered type is refused, so the general runner can never
+    # execute arbitrary code. Authority is checked here (the caller must hold the
+    # type's required_role, if any) and frozen onto the job's `enqueued_by` — the
+    # worker runs it as exactly this role, no escalation via the queue.
+    class Enqueue
+      extend Textus::Contract::DSL
+
+      verb     :enqueue
+      summary  "Push a registered job type onto the convergence queue, to be run by drain/serve."
+      surfaces :cli, :mcp
+      cli      "enqueue"
+      arg :type, String, required: true, positional: true, description: "registered job type (e.g. materialize, re-pull, sweep)"
+      arg :args, Hash, positional: true, default: {}, description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
+
+      def initialize(container:, call:)
+        @container = container
+        @call = call
+      end
+
+      def call(type, args = {})
+        entry = Textus::Jobs::Handlers.registry.lookup(type) # raises UsageError for unregistered types
+        authorize!(entry)
+
+        job = Textus::Domain::Jobs::Job.new(
+          type: type, args: args, enqueued_by: @call.role, max_attempts: entry.max_attempts,
+        )
+        Textus::Ports::Queue.new(root: @container.root).enqueue(job)
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
+      end
+
+      private
+
+      def authorize!(entry)
+        required = entry.required_role
+        return if required.nil? || @call.role == required
+
+        raise Textus::Error.new(
+          "forbidden",
+          "role '#{@call.role}' is not authorized to enqueue this job type (requires '#{required}')",
+          details: { "role" => @call.role, "required_role" => required },
+          exit_code: 77,
+        )
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.51.0
+  version: 0.52.0
 platform: ruby
 authors:
 - Patrick
@@ -132,6 +132,7 @@ files:
 - lib/textus/cli/verb/schema_diff.rb
 - lib/textus/cli/verb/schema_init.rb
 - lib/textus/cli/verb/schema_migrate.rb
+- lib/textus/cli/verb/serve.rb
 - lib/textus/container.rb
 - lib/textus/contract.rb
 - lib/textus/contract/around.rb
@@ -167,6 +168,8 @@ files:
 - lib/textus/domain/freshness.rb
 - lib/textus/domain/freshness/evaluator.rb
 - lib/textus/domain/freshness/verdict.rb
+- lib/textus/domain/jobs/job.rb
+- lib/textus/domain/jobs/registry.rb
 - lib/textus/domain/permission.rb
 - lib/textus/domain/policy/base_guards.rb
 - lib/textus/domain/policy/evaluation.rb
@@ -210,16 +213,22 @@ files:
 - lib/textus/init.rb
 - lib/textus/init/templates/machine_intake.rb
 - lib/textus/init/templates/orientation_reducer.rb
+- lib/textus/jobs/handlers.rb
+- lib/textus/jobs/scheduler.rb
+- lib/textus/jobs/seeder.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/matching.rb
 - lib/textus/key/path.rb
 - lib/textus/layout.rb
 - lib/textus/maintenance.rb
+- lib/textus/maintenance/drain.rb
 - lib/textus/maintenance/key_delete_prefix.rb
 - lib/textus/maintenance/key_mv_prefix.rb
-- lib/textus/maintenance/reconcile.rb
+- lib/textus/maintenance/retention/apply.rb
 - lib/textus/maintenance/rule_lint.rb
+- lib/textus/maintenance/serve.rb
+- lib/textus/maintenance/worker.rb
 - lib/textus/maintenance/zone_mv.rb
 - lib/textus/manifest.rb
 - lib/textus/manifest/capabilities.rb
@@ -263,6 +272,7 @@ files:
 - lib/textus/ports/clock.rb
 - lib/textus/ports/produce_on_write_subscriber.rb
 - lib/textus/ports/publisher.rb
+- lib/textus/ports/queue.rb
 - lib/textus/ports/sentinel_store.rb
 - lib/textus/ports/storage/file_stat.rb
 - lib/textus/ports/storage/file_store.rb
@@ -285,6 +295,7 @@ files:
 - lib/textus/read/doctor.rb
 - lib/textus/read/freshness.rb
 - lib/textus/read/get.rb
+- lib/textus/read/jobs.rb
 - lib/textus/read/list.rb
 - lib/textus/read/published.rb
 - lib/textus/read/pulse.rb
@@ -306,6 +317,7 @@ files:
 - lib/textus/uid.rb
 - lib/textus/version.rb
 - lib/textus/write/accept.rb
+- lib/textus/write/enqueue.rb
 - lib/textus/write/key_delete.rb
 - lib/textus/write/key_mv.rb
 - lib/textus/write/propose.rb

data/lib/textus/maintenance/reconcile.rb

@@ -1,160 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Maintenance
-    # Two-phase convergence pass (ADR 0093). Replaces the old Lifecycle-reporter
-    # sweep.
-    #
-    # Phase 1 — Produce (non-destructive): re-render ALL derived entries (cheap,
-    # idempotent) plus every intake entry past its source.ttl (stale-only, so
-    # external sources are not hammered). Driven by Produce::Engine.
-    #
-    # Phase 2 — Retention sweep (destructive): drop or archive entries past their
-    # retention ttl. Driven by Domain::Retention::Sweep. The old refresh/warn
-    # actions are gone — intake re-pull is now Produce's responsibility.
-    class Reconcile
-      extend Textus::Contract::DSL
-
-      verb     :reconcile
-      summary  "Run the convergence pass: produce derived + stale intake, then drop/archive aged entries; report health."
-      surfaces :cli, :mcp
-      cli      "reconcile"
-      arg :prefix,  String, description: "restrict the sweep to keys under this dotted prefix"
-      arg :zone,    String, description: "restrict the sweep to entries in this zone"
-      arg :dry_run, :boolean, default: false,
-                              description: "when true, report what the pass WOULD do without applying; " \
-                                           "defaults to false, so omitting it produces + drops/archives immediately"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(prefix: nil, zone: nil, dry_run: false)
-        file_stat = Textus::Ports::Storage::FileStat.new
-        retention_rows = Textus::Domain::Retention::Sweep.new(
-          manifest: @container.manifest, file_stat: file_stat, clock: Textus::Ports::Clock.new,
-        ).call(prefix: prefix, zone: zone)
-
-        produce_keys = produce_scope(prefix, zone, file_stat)
-        health = Read::Doctor.new(container: @container, call: @call).call
-        return dry_run_result(produce_keys, retention_rows, health) if dry_run
-
-        # reconcile is the authoritative "make everything current now" pass, so
-        # it subsumes any in-flight reactive produce: drain pending async
-        # produce-on-write threads first, both to fold their work in and to free
-        # the shared maintenance lock (BuildLock is non-blocking — a thread still
-        # holding it would make the acquire below raise BuildInProgress). ADR 0093.
-        Textus::Produce::Engine::AsyncRunner.drain
-
-        Textus::Ports::BuildLock.with(root: @container.root) do
-          produced = Textus::Produce::Engine.new(container: @container, call: @call).call(keys: produce_keys)
-          swept = apply(retention_rows)
-          publish_failed(swept[:failed]) unless swept[:failed].empty?
-          apply_result(produced, swept, health)
-        end
-      end
-
-      private
-
-      # The full produce scope (ADR 0093): every derived entry (always
-      # re-render — cheap, idempotent), every entry that mirrors a publish_tree
-      # (the nested-subtree publishers, ADR 0047 — mirrored each pass so a
-      # removed source leaf is swept from the published tree), every authored
-      # leaf with a `publish.to` target (the single-file canon publishers —
-      # docs/README.md, the architecture index, the root README; ADR 0103 —
-      # converged each pass so a stale published copy is rewritten and the
-      # `reconcile`-is-a-no-op check guards them), plus every intake entry past
-      # its source.ttl (re-pull only when due, so external sources aren't
-      # hammered). Ttl-less intake entries (:no_policy) are skipped — they have
-      # no freshness contract and are never auto-re-pulled (ADR 0099). All are
-      # idempotent: publish writes only when the target's content changed.
-      def produce_scope(prefix, zone, file_stat)
-        publishable = @container.manifest.data.entries
-                                .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
-                                .select { |e| in_scope?(e, prefix, zone) }.map(&:key)
-        stale_intake = Textus::Domain::Freshness::Evaluator.new(
-          manifest: @container.manifest, file_stat: file_stat, clock: Textus::Ports::Clock.new,
-        ).stale_intake_keys(prefix: prefix, zone: zone)
-        (publishable + stale_intake).uniq
-      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
-
-      def dry_run_result(produce_keys, rows, health)
-        {
-          "protocol" => Textus::PROTOCOL, "ok" => true, "dry_run" => true,
-          "would_produce" => produce_keys,
-          "would_drop" => action_keys(rows, "drop"),
-          "would_archive" => action_keys(rows, "archive"),
-          "health" => health
-        }
-      end
-
-      def apply_result(produced, swept, health)
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => produced[:failed].empty? && swept[:failed].empty?,
-          "dry_run" => false,
-          "produced" => produced[:produced],
-          "produce_failed" => produced[:failed],
-          "dropped" => swept[:dropped], "archived" => swept[:archived],
-          "failed" => swept[:failed],
-          "health" => health
-        }
-      end
-
-      def action_keys(rows, action)
-        rows.select { |r| r["action"] == action }.map { |r| r["key"] }
-      end
-
-      def publish_failed(failed)
-        @container.events.publish(
-          :reconcile_failed,
-          ctx: Textus::Hooks::Context.for(container: @container, call: @call),
-          failed: failed,
-        )
-      end
-
-      # Phase 2: destructive retention only (drop/archive). No refresh — intake
-      # re-pull is Produce's job (Phase 1). ADR 0093.
-      def apply(rows)
-        out = { dropped: [], archived: [], failed: [] }
-        delete = Write::KeyDelete.new(container: @container, call: @call)
-        rows.each do |row|
-          key = row["key"]
-          begin
-            case row["action"]
-            when "drop"
-              delete.call(key)
-              out[:dropped] << key
-            when "archive"
-              archive_leaf(row)
-              delete.call(key)
-              out[:archived] << key
-            end
-          rescue Textus::Error => e
-            out[:failed] << { "key" => key, "error" => e.message }
-          end
-        end
-        out
-      end
-
-      # Copy the leaf into <store>/archive/<relative-path> before deletion.
-      # (Lifted from the retired RetentionSweep#archive_leaf.)
-      def archive_leaf(row)
-        src  = row["path"]
-        root = @container.root.to_s
-        rel  = src.delete_prefix("#{root}/")
-        dest = File.join(root, "archive", rel)
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
-      end
-    end
-  end
-end