textus 0.50.0 → 0.52.0

data/lib/textus/manifest/schema.rb

@@ -1,253 +1,33 @@
 module Textus
   class Manifest
+    # The manifest schema. Its data is split across Schema::Vocabulary (the
+    # coordination vocabulary) and Schema::Keys (key whitelists + FIELD_REGISTRY)
+    # as of ADR 0109; the validation walk lives in Schema::Validator (ADR 0107).
+    # The constants are re-exported here so callers keep saying `Schema::LANES`.
     module Schema
-      ROOT_KEYS    = %w[version roles zones entries rules audit].freeze
-      ROLE_KEYS    = %w[name can].freeze
-      ZONE_KEYS    = %w[name kind owner desc].freeze
-      # The closed coordination vocabulary (ADR 0028; completed at five in ADR
-      # 0033; unified here in ADR 0034). Each lane pairs a zone-kind with the
-      # single capability that authorizes originating bytes in it — a total
-      # bijection. This table is the ONE source of truth; the three legacy
-      # constants below are derived from it so a zone-kind and its required
-      # capability cannot drift. Key order is canon-first so the unknown-kind
-      # error message reads canon, workspace, quarantine, queue, derived.
-      LANES = {
-        "canon" => "author",
-        "workspace" => "keep",
-        "quarantine" => "fetch",
-        "queue" => "propose",
-        "derived" => "build",
-      }.freeze
-
-      ZONE_KINDS         = LANES.keys.freeze
-      CAPABILITIES       = LANES.values.freeze
-      KIND_REQUIRES_VERB = LANES
-      ENTRY_KEYS = %w[
-        key path zone kind schema owner nested format
-        compute template publish
-        intake events inject_boot provenance 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
-      COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
-      INTAKE_KEYS  = %w[handler config].freeze
-      RULE_KEYS    = %w[match intake_handler_allowlist guard lifecycle].freeze
-      LIFECYCLE_KEYS = %w[ttl on_expire budget_ms].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/
-
-      def self.validate!(raw)
-        raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
-
-        walk(raw, ROOT_KEYS, "$")
-        validate_roles!(raw["roles"])
-        validate_zones!(raw["zones"])
-        validate_entries!(raw["entries"])
-        validate_owners!(raw["zones"], raw["entries"])
-        validate_rules!(raw["rules"])
-        walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
-        validate_single_queue!(raw)
-        validate_zone_kind_consistency!(raw)
-      end
-
-      def self.validate_zones!(zones)
-        Array(zones).each_with_index do |z, i|
-          walk(z, ZONE_KEYS, "$.zones[#{i}]")
-          if z["kind"].nil?
-            raise BadManifest.new("zone '#{z["name"]}' at '$.zones[#{i}]' must declare a kind (one of: #{ZONE_KINDS.join(", ")})")
-          end
-          next if ZONE_KINDS.include?(z["kind"])
-
-          raise BadManifest.new(
-            "unknown zone kind '#{z["kind"]}' at '$.zones[#{i}]' (known: #{ZONE_KINDS.join(", ")})",
-          )
-        end
-      end
-
-      def self.validate_entries!(entries)
-        Array(entries).each_with_index do |e, i|
-          path = "$.entries[#{i}]"
-          reject_retired_publish_keys!(e, path)
-          walk(e, ENTRY_KEYS, path)
-          validate_publish_block!(e, path)
-          walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
-          walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
-        end
-      end
-
-      # Retired keys are no longer allowed, so `walk` would reject them as merely
-      # "unknown"; intercept first with the migration path so a pre-0.43 manifest
-      # gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/
-      # `publish_tree` were folded into the `publish:` block (ADR 0052);
-      # `index_filename` was removed (ADR 0053).
-      def self.reject_retired_publish_keys!(entry, path)
-        return unless entry.is_a?(Hash)
-
-        if entry.key?("publish_each")
-          raise BadManifest.new(
-            "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-            "mirror the subtree with `publish: { tree: \"...\" }`.",
-          )
-        end
-
-        if entry.key?("publish_to")
-          raise BadManifest.new(
-            "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-            "use `publish: { to: [...] }`.",
-          )
-        end
-
-        if entry.key?("publish_tree")
-          raise BadManifest.new(
-            "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
-            "use `publish: { tree: \"...\" }`.",
-          )
-        end
-
-        return unless entry.key?("index_filename")
-
-        raise BadManifest.new(
-          "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
-          "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
-        )
-      end
-
-      # Shape of the ADR 0052 publish block: a Hash whose only keys are to/tree.
-      # Exclusivity (both set) and per-mode rules stay in Publish.resolve (ADR 0049).
-      def self.validate_publish_block!(entry, path)
-        return unless entry.is_a?(Hash) && entry.key?("publish")
-
-        block = entry["publish"]
-        raise BadManifest.new("publish: must be a mapping with `to:` or `tree:` at '#{path}.publish'") unless block.is_a?(Hash)
-
-        walk(block, PUBLISH_KEYS, "#{path}.publish")
-      end
-
-      def self.validate_rules!(rules)
-        Array(rules).each_with_index do |r, i|
-          path = "$.rules[#{i}]"
-          walk(r, RULE_KEYS, path)
-          walk(r["lifecycle"], LIFECYCLE_KEYS, "#{path}.lifecycle") if r["lifecycle"].is_a?(Hash)
-        end
-      end
-
-      def self.validate_roles!(roles)
-        return if roles.nil?
-        raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)
-
-        roles.each_with_index do |r, i|
-          path = "$.roles[#{i}]"
-          walk(r, ROLE_KEYS, path)
-          name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
-          unless Textus::Role::NAMES.include?(name)
-            raise BadManifest.new(
-              "unknown role name '#{name}' at '#{path}' " \
-              "(allowed: #{Textus::Role::NAMES.join(", ")})",
-            )
-          end
-          Array(r["can"]).each do |verb|
-            next if CAPABILITIES.include?(verb)
-
-            raise BadManifest.new(
-              "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
-              "(known: #{CAPABILITIES.join(", ")})",
-            )
-          end
-        end
-
-        author_holders = roles.count { |r| Array(r["can"]).include?("author") }
-        return if author_holders <= 1
-
-        raise BadManifest.new(
-          "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
-        )
-      end
-
-      # Owners are validated against the SAME closed archetype set as role names
-      # (ADR 0045 D1) so attribution can't bypass the closed-name guarantee.
-      # Applies to both zone owners and entry owners; owner is optional, so a
-      # nil owner is not an error.
-      def self.validate_owners!(zones, entries)
-        Array(zones).each_with_index do |z, i|
-          check_owner!(z["owner"], "$.zones[#{i}]")
-        end
-        Array(entries).each_with_index do |e, i|
-          check_owner!(e["owner"], "$.entries[#{i}]")
-        end
-      end
-
-      def self.check_owner!(owner, path)
-        return if owner.nil?
-        return if valid_owner?(owner)
-
-        raise BadManifest.new(
-          "invalid owner '#{owner}' at '#{path}' " \
-          "(expected <archetype> or <archetype>:<subject>, " \
-          "archetype one of: #{Textus::Role::NAMES.join(", ")})",
-        )
-      end
-
-      # The owner-validation rule: an `owner:` token is either a bare archetype
-      # (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is
-      # gated against the closed Role::NAMES set (so attribution can't smuggle in
-      # a name the role side rejects, ADR 0045 D1); the subject is the free-form
-      # principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ':'
-      # only — a subject may not itself contain ':' (the pattern excludes it), so
-      # `human:a:b` is rejected.
-      def self.valid_owner?(token)
-        return false unless token.is_a?(String) && !token.empty?
-
-        archetype, subject = token.split(":", 2)
-        return false unless Textus::Role::NAMES.include?(archetype)
-        return true if subject.nil?
-
-        OWNER_SUBJECT_PATTERN.match?(subject)
-      end
-
-      def self.walk(hash, allowed, path)
-        return unless hash.is_a?(Hash)
-
-        hash.each_key do |k|
-          next if allowed.include?(k)
-
-          raise BadManifest.new("unknown key '#{k}' at '#{path}'")
-        end
-      end
-
-      def self.validate_single_queue!(raw)
-        queues = Array(raw["zones"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
-        return if queues.size <= 1
-
-        raise BadManifest.new(
-          "at most one zone may declare kind: queue (found: #{queues.join(", ")})",
-        )
-      end
-
-      # Write authority is derived from capabilities (ADR 0030): a zone of a
-      # given kind can only be written by a role that holds the kind's required
-      # verb. Reject a manifest declaring a zone whose required verb is held by
-      # no role. Capabilities.resolve returns the defaults when `roles:` is nil,
-      # so the capability union is all four verbs and every kind is satisfied.
-      def self.validate_zone_kind_consistency!(raw)
-        held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
-
-        Array(raw["zones"]).each_with_index do |z, i|
-          verb = KIND_REQUIRES_VERB[z["kind"]]
-          next if verb.nil? || held.include?(verb)
-
-          raise BadManifest.new(
-            "zone '#{z["name"]}' (#{z["kind"]}) at '$.zones[#{i}]' " \
-            "needs a role with capability '#{verb}'; none declared",
-          )
-        end
-      end
+      # Re-export the vocabulary.
+      LANES              = Vocabulary::LANES
+      ZONE_KINDS         = Vocabulary::ZONE_KINDS
+      CAPABILITIES       = Vocabulary::CAPABILITIES
+      KIND_REQUIRES_VERB = Vocabulary::KIND_REQUIRES_VERB
+      # Re-export the keys + registry.
+      ROOT_KEYS             = Keys::ROOT_KEYS
+      ROLE_KEYS             = Keys::ROLE_KEYS
+      ZONE_KEYS             = Keys::ZONE_KEYS
+      ENTRY_KEYS            = Keys::ENTRY_KEYS
+      PUBLISH_KEYS          = Keys::PUBLISH_KEYS
+      SOURCE_KEYS           = Keys::SOURCE_KEYS
+      RETENTION_KEYS        = Keys::RETENTION_KEYS
+      AUDIT_KEYS            = Keys::AUDIT_KEYS
+      FIELD_REGISTRY        = Keys::FIELD_REGISTRY
+      RULE_KEYS             = Keys::RULE_KEYS
+      OWNER_SUBJECT_PATTERN = Keys::OWNER_SUBJECT_PATTERN
+
+      # Public entry points — the validation walk lives in Schema::Validator
+      # (ADR 0107). Kept here so callers keep speaking to `Schema`.
+      def self.validate!(raw) = Validator.validate!(raw)
+
+      def self.validate_source_and_retention!(manifest) = Validator.validate_source_and_retention!(manifest)
     end
   end
 end

data/lib/textus/manifest.rb

@@ -6,9 +6,9 @@ module Textus
   #
   #   * data     — frozen value: raw, root, zones, entries, audit_config, role_caps
   #   * resolver — resolves keys → entry + path
-  #   * policy   — zone/role authority (zone_writers, declared_kind/derived_zone?/
+  #   * policy   — zone/role authority (zone_writers, declared_kind, derived_entry?,
   #     queue_zone?, permission_for, …)
-  #   * rules    — match-block rule engine (fetch, handler allowlist, promotion, …)
+  #   * rules    — match-block rule engine (lifecycle, handler allowlist, materialize, …)
   #
   # Use `manifest.data.entries`, `manifest.policy.declared_kind(z)`, etc.
   Manifest = Data.define(:data, :resolver, :policy, :rules)
@@ -44,12 +44,14 @@ module Textus # rubocop:disable Style/OneClassPerFile
 
       def build(raw, root)
         data = Manifest::Data.parse(raw, root: root)
-        new(
+        manifest = new(
           data: data,
           resolver: Manifest::Resolver.new(data),
           policy: data.policy,
           rules: Manifest::Rules.parse(raw["rules"] || []),
         )
+        Manifest::Schema.validate_source_and_retention!(manifest) # ADR 0093
+        manifest
       end
 
       def check_version!(raw, source)

data/lib/textus/mcp/server.rb

@@ -94,7 +94,7 @@ module Textus
 
         # ADR 0083: the contract-drift guard gates mutating verbs — every MCP
         # verb that is NOT a pure read (Write:: + the destructive Maintenance::
-        # verbs tend/zone_mv/key_*_prefix). Reads and boot bypass it (a stale
+        # verbs drain/zone_mv/key_*_prefix). Reads and boot bypass it (a stale
         # read returns on-disk truth; boot re-orients). Keying on read_verbs
         # (not write_verbs) keeps the destructive Maintenance:: verbs gated.
         @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)

data/lib/textus/ports/audit_log.rb

@@ -4,6 +4,12 @@ require "time"
 
 module Textus
   module Ports
+    # Append-only audit log adapter: writes and rotates the on-disk audit JSONL
+    # under the store root. An instantiable class — it holds collaborators (the
+    # root path + size/keep config), so each store binds its own instance. It
+    # already satisfied ADR 0109's single-shape rule (every port is an
+    # instantiable class) before that ADR's Clock/Publisher conversions, so it
+    # was unchanged by them.
     class AuditLog
       DEFAULT_MAX_SIZE = 10_485_760
       DEFAULT_KEEP = 5

data/lib/textus/ports/build_lock.rb

@@ -4,6 +4,12 @@ require "time"
 
 module Textus
   module Ports
+    # Cross-process build lock: a pid/host-stamped lockfile under the store root
+    # that serializes converge's produce/sweep. An instantiable class — it holds
+    # the root and lock state; `self.with(root:)` is a convenience that constructs
+    # one and runs the block under the held lock. It already satisfied ADR 0109's
+    # single-shape rule (every port is an instantiable class) before that ADR's
+    # Clock/Publisher conversions, so it was unchanged by them.
     class BuildLock
       MAX_HOLDER_BYTES = 512
 

data/lib/textus/ports/clock.rb

@@ -1,8 +1,9 @@
 module Textus
   module Ports
-    module Clock
-      module_function
-
+    # The wall clock. An instantiable class (ADR 0109) — uniform with the other
+    # ports; `now` reads the system time. Callers that need a fixed time still
+    # pass it as data via `Call#now`.
+    class Clock
       def now = Time.now
     end
   end

data/lib/textus/ports/produce_on_write_subscriber.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Textus
+  module Ports
+    # ADR 0093 / job-queue model: on a canon write, enqueue a `materialize` job
+    # for each derived entry that depends on the written key (rdeps ∩ producible).
+    # Async-only — the write returns immediately; a worker (drain/serve) converges
+    # the jobs. There is no inline `sync` path and no in-process thread: freshness
+    # is re-homed to drain (at the commit/CI gate) and the daemon. A write INTO a
+    # derived entry does not fan out (recursion guard). Produce self-elevates, so
+    # the job is stamped automation. Attached at Store boot, alongside
+    # AuditSubscriber.
+    class ProduceOnWriteSubscriber
+      def initialize(container)
+        @container = container
+      end
+
+      def attach(bus)
+        bus.on(:entry_written, :produce_on_write) do |key:, **|
+          on_write(key: key)
+        end
+        # Closes the ADR 0087 gap: a delete/rename of a source must re-materialize
+        # its orphaned dependents too, not just a write. These fire distinct
+        # events (:entry_deleted / :entry_renamed), so subscribe to each.
+        bus.on(:entry_deleted, :produce_on_delete) do |key:, **|
+          on_write(key: key)
+        end
+        bus.on(:entry_renamed, :produce_on_rename) do |from_key:, to_key:, **|
+          on_write(key: from_key)
+          on_write(key: to_key)
+        end
+        self
+      end
+
+      def on_write(key:)
+        return if derived_write?(key) # recursion guard: produce output is not a source change
+
+        affected = Textus::Read::Rdeps.new(container: @container).call(key)["rdeps"]
+        producible = affected.select { |k| producible?(k) }
+        return if producible.empty?
+
+        queue = Textus::Ports::Queue.new(root: @container.root)
+        producible.each do |k|
+          queue.enqueue(
+            Textus::Domain::Jobs::Job.new(
+              type: "materialize", args: { "key" => k }, enqueued_by: Textus::Role::AUTOMATION,
+            ),
+          )
+        end
+      end
+
+      private
+
+      def derived_write?(key)
+        @container.manifest.resolver.resolve(key).entry.derived?
+      rescue Textus::Error
+        false
+      end
+
+      # The producible scope mirrors Produce::Engine#produce_one: derived
+      # entries render+publish, and nested publish_tree entries mirror their
+      # source subtree (ADR 0047). Including the latter restores reactive
+      # re-mirroring on a write into a tree's source — dropped when the scope
+      # narrowed to `derived?` only.
+      def producible?(key)
+        entry = @container.manifest.resolver.resolve(key).entry
+        entry.derived? || !entry.publish_tree.nil?
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end

data/lib/textus/ports/publisher.rb

@@ -10,18 +10,20 @@ module Textus
     # under `<store_root>/.run/sentinels/` (runtime, git-ignored — ADR 0070) and
     # mirror the target's repo-relative layout so consumer directories aren't
     # polluted with `.textus-managed.json` siblings.
-    module Publisher
-      def self.publish(source:, target:, store_root:)
+    #
+    # An instantiable class (ADR 0109).
+    class Publisher
+      def publish(source:, target:, store_root:, provenance_source: source)
         FileUtils.mkdir_p(File.dirname(target))
         guard_clobber(source, target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        Textus::Ports::SentinelStore.new.write!(target: target, source: source, store_root: store_root)
+        Textus::Ports::SentinelStore.new.write!(target: target, source: provenance_source, store_root: store_root)
       end
 
       # Removes a previously-published file and its sentinel. No-op unless the
       # target is textus-managed — never deletes an unmanaged file.
-      def self.unpublish(target:, store_root:)
+      def unpublish(target:, store_root:)
         return unless managed?(target, store_root)
 
         FileUtils.rm_f(target)
@@ -29,6 +31,8 @@ module Textus
         FileUtils.rm_f(sentinel)
       end
 
+      private
+
       # Refuse to clobber an unmanaged target — EXCEPT adopt one whose bytes
       # already equal the source (ADR 0050: a migration copies files into the
       # store and publishes them back to where they already live, so the target
@@ -36,7 +40,7 @@ module Textus
       # here; the normal publish path below does, and the cp is a content no-op.
       # An unmanaged target whose content DIFFERS, or any unmanaged symlink, is
       # still refused — that is the guard's real job.
-      def self.guard_clobber(source, target, store_root)
+      def guard_clobber(source, target, store_root)
         return unless File.exist?(target) || File.symlink?(target)
         return if managed?(target, store_root)
         return if adoptable?(source, target)
@@ -44,11 +48,11 @@ module Textus
         raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
       end
 
-      def self.adoptable?(source, target)
+      def adoptable?(source, target)
         !File.symlink?(target) && File.file?(target) && FileUtils.identical?(source, target)
       end
 
-      def self.managed?(target, store_root)
+      def managed?(target, store_root)
         File.exist?(Textus::Ports::SentinelStore.new.sentinel_path(target, store_root))
       end
     end

data/lib/textus/ports/queue.rb

@@ -0,0 +1,130 @@
+require "fileutils"
+require "json"
+require "time"
+
+module Textus
+  module Ports
+    # File-backed durable job queue under `<root>/.run/queue/`. Each job state
+    # is a directory; a job is one `<id>.json` file. Claiming is an atomic
+    # `rename(2)` from ready/ to leased/ — the rename winner owns the job, so a
+    # worker pool needs no central lock. Dedup falls out of the id-as-filename:
+    # enqueueing an id that already exists is a no-op. ADR 0038 (runtime subtree),
+    # ADR 0108 (instantiable port).
+    class Queue
+      STATES = %i[ready leased done failed].freeze
+
+      def initialize(root:)
+        @root = root
+        STATES.each { |s| FileUtils.mkdir_p(Textus::Layout.queue_state(root, s)) }
+      end
+
+      def enqueue(job)
+        dest = path(:ready, job.id)
+        return if File.exist?(dest) # dedup: identical work already queued
+
+        write_atomic(dest, job.to_h)
+      end
+
+      def ready_ids
+        Dir.children(Textus::Layout.queue_state(@root, :ready)).map { |f| File.basename(f, ".json") }
+      end
+
+      # A claimed job plus the path it lives at, so ack/fail act on this copy.
+      Leased = Struct.new(:job, :leased_path, keyword_init: true)
+
+      def lease(worker_id:, lease_ttl:)
+        ready_dir = Textus::Layout.queue_state(@root, :ready)
+        Dir.children(ready_dir).each do |name|
+          src = File.join(ready_dir, name)
+          dst = File.join(Textus::Layout.queue_state(@root, :leased), name)
+          begin
+            File.rename(src, dst) # atomic claim; loser's rename raises ENOENT
+          rescue Errno::ENOENT
+            next # another worker won this one
+          end
+          job = Textus::Domain::Jobs::Job.from_h(JSON.parse(File.read(dst)))
+          stamp_lease(dst, worker_id: worker_id, expires_at: Time.now.utc + lease_ttl)
+          return Leased.new(job: job, leased_path: dst)
+        end
+        nil
+      end
+
+      def ack(leased)
+        dest = File.join(Textus::Layout.queue_state(@root, :done), File.basename(leased.leased_path))
+        File.rename(leased.leased_path, dest)
+      end
+
+      # Increment attempts and either requeue (transient) or dead-letter (attempts
+      # exhausted). Returns :requeued or :dead_lettered so the worker can count
+      # terminal failures distinctly from retries.
+      def fail(leased, error:)
+        job = leased.job
+        job.attempts += 1
+        job.last_error = error
+        dead = job.attempts >= job.max_attempts
+        write_atomic(path(dead ? :failed : :ready, job.id), job.to_h)
+        File.delete(leased.leased_path)
+        dead ? :dead_lettered : :requeued
+      end
+
+      # Return expired leases to ready/ (the holding worker crashed). Returns the
+      # count reclaimed. At-least-once delivery: a job whose handler actually
+      # finished but whose ack was lost will re-run — handlers must be idempotent.
+      def reclaim(now:)
+        leased_dir = Textus::Layout.queue_state(@root, :leased)
+        count = 0
+        Dir.children(leased_dir).each do |name|
+          src = File.join(leased_dir, name)
+          data = JSON.parse(File.read(src))
+          expires = data.dig("lease", "expires_at")
+          next if expires && Time.parse(expires) > now
+
+          dst = File.join(Textus::Layout.queue_state(@root, :ready), name)
+          data.delete("lease")
+          File.write(src, JSON.pretty_generate(data))
+          File.rename(src, dst)
+          count += 1
+        rescue Errno::ENOENT
+          next # raced with another reclaimer / the worker's ack
+        end
+        count
+      end
+
+      def list(state)
+        Dir.children(Textus::Layout.queue_state(@root, state.to_sym)).map { |f| File.basename(f, ".json") }
+      end
+
+      def retry_failed(job_id)
+        src = path(:failed, job_id)
+        data = JSON.parse(File.read(src))
+        data["attempts"] = 0
+        data["last_error"] = nil
+        write_atomic(path(:ready, job_id), data)
+        File.delete(src)
+      end
+
+      def purge(state)
+        dir = Textus::Layout.queue_state(@root, state.to_sym)
+        Dir.children(dir).each { |f| File.delete(File.join(dir, f)) }
+      end
+
+      private
+
+      def stamp_lease(leased_path, worker_id:, expires_at:)
+        data = JSON.parse(File.read(leased_path))
+        data["lease"] = { "worker_id" => worker_id, "expires_at" => expires_at.iso8601 }
+        File.write(leased_path, JSON.pretty_generate(data))
+      end
+
+      def path(state, job_id)
+        File.join(Textus::Layout.queue_state(@root, state), "#{job_id}.json")
+      end
+
+      def write_atomic(dest, hash)
+        tmp = "#{dest}.#{Process.pid}.tmp"
+        File.write(tmp, JSON.pretty_generate(hash))
+        File.rename(tmp, dest) # atomic on same filesystem
+      end
+    end
+  end
+end

data/lib/textus/produce/acquire/handler.rb

@@ -0,0 +1,29 @@
+require "timeout"
+
+module Textus
+  module Produce
+    module Acquire
+      # Invokes a :resolve_handler hook handler by name under a timeout — the single
+      # home for "call the intake handler under a deadline" (ADR 0048 D1). Shared by
+      # Produce::Acquire::Intake (the internal ingest mechanism — no public verb since ADR 0079)
+      # as driven by the converge sweep (drain/serve) and `textus hook run` (ADR 0089 made
+      # ingest system-pushed; there is no read or put trigger).
+      # Always passes a Container as `caps:` so the hook contract (ADR 0027) is
+      # uniform across every entry point. Maps Timeout::Error to a UsageError;
+      # leaves any other error to the caller (call sites differ in how they wrap).
+      module Handler
+        FETCH_TIMEOUT_SECONDS = 30
+
+        module_function
+
+        def invoke(caps:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
+          Timeout.timeout(timeout) do
+            caps.rpc.invoke(:resolve_handler, handler, caps: caps, config: config, args: args)
+          end
+        rescue Timeout::Error
+          raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")
+        end
+      end
+    end
+  end
+end