textus 0.52.0 → 0.54.0

data/lib/textus/{domain/jobs → ports/job_store}/job.rb

@@ -2,12 +2,12 @@ require "digest"
 require "json"
 
 module Textus
-  module Domain
-    module Jobs
+  module Ports
+    class JobStore
       # 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.
+      # collide on the same id — which is how Queue dedups (file already exists).
+      # At-least-once delivery means handlers must be idempotent.
       class Job
         DIGEST_BYTES = 16
 
@@ -15,10 +15,10 @@ module Textus
         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)
+          @type        = type.to_s
+          @args        = stringify(args)
           @enqueued_by = enqueued_by
-          @attempts = attempts
+          @attempts    = attempts
           @max_attempts = max_attempts
           @last_error = last_error
         end
@@ -29,16 +29,23 @@ module Textus
 
         def to_h
           {
-            "type" => @type, "args" => @args, "enqueued_by" => @enqueued_by,
-            "attempts" => @attempts, "max_attempts" => @max_attempts, "last_error" => @last_error
+            "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"]
+            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
 

data/lib/textus/ports/{queue.rb → job_store.rb}

@@ -10,7 +10,7 @@ module Textus
     # 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
+    class JobStore
       STATES = %i[ready leased done failed].freeze
 
       def initialize(root:)
@@ -20,7 +20,7 @@ module Textus
 
       def enqueue(job)
         dest = path(:ready, job.id)
-        return if File.exist?(dest) # dedup: identical work already queued
+        return if File.exist?(dest)
 
         write_atomic(dest, job.to_h)
       end
@@ -29,7 +29,6 @@ module Textus
         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:)
@@ -38,11 +37,11 @@ module Textus
           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
+            File.rename(src, dst)
           rescue Errno::ENOENT
-            next # another worker won this one
+            next
           end
-          job = Textus::Domain::Jobs::Job.from_h(JSON.parse(File.read(dst)))
+          job = 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
@@ -54,9 +53,6 @@ module Textus
         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
@@ -67,9 +63,6 @@ module Textus
         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
@@ -85,7 +78,7 @@ module Textus
           File.rename(src, dst)
           count += 1
         rescue Errno::ENOENT
-          next # raced with another reclaimer / the worker's ack
+          next
         end
         count
       end
@@ -123,7 +116,7 @@ module Textus
       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
+        File.rename(tmp, dest)
       end
     end
   end

data/lib/textus/ports/sentinel_store.rb

@@ -7,7 +7,7 @@ module Textus
     # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
     # path layout (<store_root>/.run/sentinels/<target-rel-to-repo>.textus-managed.json
     # — runtime, git-ignored, ADR 0070), and all File/FileUtils I/O.
-    # Domain::Sentinel is a pure value object that depends on this port for
+    # Core::Sentinel is a pure value object that depends on this port for
     # reads and writes.
     class SentinelStore
       SUFFIX = ".textus-managed.json".freeze
@@ -26,7 +26,7 @@ module Textus
 
       def load(path, repo_root)
         raw = JSON.parse(File.read(path))
-        Textus::Domain::Sentinel.new(
+        Textus::Core::Sentinel.new(
           target: absolutize(raw["target"], repo_root),
           source: absolutize(raw["source"], repo_root),
           sha256: raw["sha256"],

data/lib/textus/ports/watcher_lock.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Textus
+  module Ports
+    # Flock-based watcher presence lock. Held for the watcher's lifetime.
+    # Process death releases the flock automatically.
+    class WatcherLock
+      def initialize(root)
+        @path = Textus::Layout.watcher_lock(root)
+        @file = nil
+        FileUtils.mkdir_p(File.dirname(@path))
+      end
+
+      def self.running?(root)
+        path = Textus::Layout.watcher_lock(root)
+        return false unless File.exist?(path)
+
+        File.open(path, "r+") do |file|
+          got = file.flock(File::LOCK_EX | File::LOCK_NB)
+          file.flock(File::LOCK_UN) if got
+          return !got
+        end
+      rescue Errno::ENOENT
+        false
+      end
+
+      def acquire
+        @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+        raise "watcher already running" unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+
+        @file.write("pid=#{Process.pid} host=#{Socket.gethostname}\n")
+        @file.flush
+        self
+      end
+
+      def release
+        return unless @file
+
+        @file.flock(File::LOCK_UN)
+        @file.close
+        FileUtils.rm_f(@path)
+        @file = nil
+      end
+    end
+  end
+end

data/lib/textus/produce/engine.rb

@@ -1,94 +1,49 @@
 module Textus
   module Produce
-    # The single convergence engine (ADR 0093/0094). "Make these machine entries
-    # current from upstream." Acquire is per-`from`; publish is one uniform
-    # `publish_via` entry point for all kinds (ADR 0094):
-    #   intake  (from: handler)  -> re-pull (Produce::Acquire::Intake), then publish_via
-    #   derived (from: project)  -> build data + publish_via (ToPaths or None)
-    #   derived (from: command)  -> skip the build; publish_via publishes
-    #                               existing store bytes via mode resolution
-    #                               (None when no targets -> skipped)
-    # Runs as the converge build actor (self-elevating); the passed `call`
-    # supplies only correlation_id/dry_run. Callers choose the key set: the
-    # write subscriber passes rdeps ∩ derived; the converge pass passes
-    # all-derived + stale-intake.
     class Engine
-      # Locked + failure-isolated convergence — the entry point worker handlers
-      # call to materialize a key set (ADR 0093 / job-queue model). A held lock
-      # is a soft miss (an in-flight build/converge already produces fresh
-      # output); any other error is republished as :produce_failed and never
-      # raised at the caller (ADR 0087 §5 failure isolation, preserved).
       def self.converge(container:, call:, keys:)
-        Textus::Ports::BuildLock.with(root: container.root) do
-          new(container: container, call: call).call(keys: keys)
-        end
-      rescue Textus::BuildInProgress
-        nil
-      rescue Textus::Error => e
-        container.events.publish(
-          :produce_failed,
-          ctx: Textus::Hooks::Context.for(container: container, call: call),
-          keys: keys, error: e.message
-        )
+        new(container:, call:).run(keys)
       end
 
       def initialize(container:, call:)
         @container = container
         @call      = call
-        @manifest  = container.manifest
       end
 
-      # keys: the machine entry keys to converge. Returns
-      #   { produced: [k...], skipped: [k...], failed: [{ "key"=>, "error"=> }...] }
-      def call(keys:)
-        build_call = build_actor_call
-        context    = build_context(build_call)
-        out = { produced: [], skipped: [], failed: [] }
-
-        keys.each do |key|
-          produce_one(key, build_call, context, out)
-        rescue Textus::Error => e
-          out[:failed] << { "key" => key, "error" => e.message }
-        end
-        out
+      def run(keys)
+        results = { completed: [], failed: [] }
+        Array(keys).each { |key| produce_one(key, results) }
+        results
       end
 
-      private
+      alias call run
 
-      # Acquire is per-`from`; publish is one uniform entry point (publish_via)
-      # for every kind. The command emit-vs-skip falls out of publish-mode
-      # resolution (Publish::None when no targets), so there is no command branch.
-      def produce_one(key, build_call, context, out)
-        entry = @manifest.resolver.resolve(key).entry
+      private
 
-        if entry.intake?
-          Textus::Produce::Acquire::Intake.new(container: @container, call: build_call).run(key) # acquire: re-pull
-          entry.publish_via(context)                                                # emit any targets
-          out[:produced] << key                                                     # a fetch is production
+      def produce_one(key, results)
+        workflow = @container.workflows.for(key)
+        if workflow
+          Workflow::Runner.new(workflow, container: @container, call: @call).run(key)
         else
-          result = entry.publish_via(context) # derived builds inside; command publishes-or-None
-          result.nil? ? (out[:skipped] << key) : (out[:produced] << key)
+          publish_only(key)
         end
+        results[:completed] << key
+      rescue StandardError => e
+        results[:failed] << { key: key, error: e.message }
       end
 
-      def build_actor_call
-        build_role = @manifest.policy.actor_for("converge") or
-          raise Textus::UsageError.new(
-            "no role holds the 'converge' capability",
-            hint: "declare a role with `can: [converge]` in .textus/manifest.yaml",
-          )
-        Textus::Call.build(
-          role: build_role,
-          correlation_id: @call.correlation_id,
-          dry_run: @call.dry_run,
-        )
-      end
+      def publish_only(key)
+        entry = @container.manifest.resolver.resolve(key).entry
+        return unless entry.publish_tree || !Array(entry.publish_to).empty?
+
+        reader     = Textus::Envelope::Reader.from(container: @container)
+        entry_path = @container.manifest.resolver.resolve(key).path
+        return unless entry.publish_tree || File.exist?(entry_path)
 
-      def build_context(call)
-        Textus::Manifest::Entry::Base::PublishContext.new(
-          container: @container, call: call,
-          reader: Textus::Read::Get.new(container: @container, call: call)
+        pctx = Textus::Manifest::Entry::Base::PublishContext.new(
+          container: @container, call: @call, reader: reader.method(:read),
         )
+        entry.publish_via(pctx)
       end
     end
   end

data/lib/textus/produce/render.rb

@@ -1,17 +1,12 @@
+require "mustache"
+
 module Textus
   module Produce
-    # Renders an entry's stored DATA into the bytes for one publish target
-    # (ADR 0094). Relocates the Mustache logic that used to live in the
-    # build-time Markdown renderer. Provenance is NOT added here — it lives in
-    # the data's `_meta`; a template surfaces it if the output should show it.
-    # A verbatim target (no template) is the caller's job to copy.
     class Render
       def initialize(template_loader:)
         @template_loader = template_loader
       end
 
-      # target: a rendering Policy::PublishTarget. data: parsed entry data.
-      # boot:   boot context hash or nil. Returns the rendered String.
       def bytes_for(target:, data:, boot:)
         raise ArgumentError.new("Produce::Render called for a verbatim target #{target.to.inspect}") unless target.renders?
 

data/lib/textus/schema/tools.rb

@@ -84,10 +84,11 @@ module Textus
       # Orchestrator-free read: schema tooling must never trigger a fetch
       # while inspecting/migrating entries (ADR 0062).
       def self.pure_get(store, role, key)
-        Textus::Read::Get.new(
-          container: store.as(role).container,
+        scope = store.as(role)
+        Textus::Action::Get.new(key: key).call(
+          container: scope.container,
           call: Textus::Call.build(role: role),
-        ).call(key)
+        )
       end
 
       def self.load_schema(store, name)

data/lib/textus/session.rb

@@ -1,15 +1,18 @@
 module Textus
   # The agent session: per-connection (MCP), per-process (CLI), or per-loop
   # (Ruby) orientation state — the audit cursor plus the contract etag and
-  # propose_zone captured at boot. Immutable Data value; advance_cursor
+  # propose_lane captured at boot. Immutable Data value; advance_cursor
   # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
-  Session = Data.define(:role, :cursor, :propose_zone, :contract_etag) do
+  Session = Data.define(:role, :cursor, :propose_lane, :contract_etag) do
+    # Back-compat reader while lane terminology migrates.
+    def propose_zone = propose_lane
+
     def advance_cursor(new_cursor) = with(cursor: new_cursor)
 
     def check_etag!(observed_etag)
       return if observed_etag == contract_etag
 
-      raise Textus::MCP::ContractDrift.new(
+      raise Textus::ContractDrift.new(
         "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
         "now #{short_etag(observed_etag)}); re-run boot",
       )

data/lib/textus/store.rb

@@ -44,8 +44,6 @@ module Textus
 
     def initialize(root)
       @container = build_container(File.expand_path(root))
-      bootstrap_hooks
-      events.publish(:store_loaded, ctx: Hooks::Context.new(scope: as(Role::DEFAULT)))
     end
 
     # Build an agent Session oriented at the current cursor/manifest — the
@@ -54,26 +52,24 @@ module Textus
       Textus::Session.new(
         role: role,
         cursor: audit_log.latest_seq,
-        propose_zone: manifest.policy.propose_zone_for(role),
+        propose_lane: manifest.policy.propose_lane_for(role),
         contract_etag: Textus::Etag.for_contract(root),
       )
     end
 
-    def as(role, dry_run: false, correlation_id: nil)
-      RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
+    def gate
+      @container.gate
     end
 
-    Textus::Dispatcher::VERBS.each_key do |verb|
-      define_method(verb) do |*args, role: Role::DEFAULT, **kwargs|
-        as(role).public_send(verb, *args, **kwargs)
-      end
+    def as(role, dry_run: false, correlation_id: nil)
+      Textus::Surfaces::RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
     end
 
     private
 
     def build_container(root)
       manifest = Manifest.load(root)
-      Container.new(
+      container = Container.new(
         root: root,
         manifest: manifest,
         schemas: Schemas.new(File.join(root, "schemas")),
@@ -83,16 +79,13 @@ module Textus
           max_size: manifest.data.audit_config[:max_size],
           keep: manifest.data.audit_config[:keep],
         ),
-        events: Hooks::EventBus.new,
-        rpc: Hooks::RpcRegistry.new,
+        workflows: Workflow::Loader.load_all(root),
+        gate: nil,
       )
-    end
-
-    def bootstrap_hooks
-      Ports::AuditSubscriber.new(audit_log).attach(events)
-      Ports::ProduceOnWriteSubscriber.new(container).attach(events)
-      Hooks::Builtin.register_all(events: events, rpc: rpc)
-      Hooks::Loader.new(events: events, rpc: rpc).load_dir(File.join(root, "hooks"))
+      gate = Textus::Gate.new(container)
+      container = container.with(gate: gate)
+      gate.instance_variable_set(:@container, container)
+      container
     end
   end
 end

data/lib/textus/surfaces/cli/group/data.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class Data < Group
+          command_name "data"
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli/group/key.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class Key < Group
+          command_name "key"
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli/group/mcp.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class MCP < Group
+          command_name "mcp"
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli/group/rule.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class Rule < Group
+          command_name "rule"
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli/group/schema.rb

@@ -0,0 +1,11 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group
+        class Schema < Group
+          command_name "schema"
+        end
+      end
+    end
+  end
+end

data/lib/textus/surfaces/cli/group.rb

@@ -0,0 +1,50 @@
+module Textus
+  module Surfaces
+    class CLI
+      class Group < Verb
+        class << self
+          # Subcommands are auto-derived: any Verb descendant whose
+          # `parent_group` is this group counts as a subcommand. Sorted
+          # alphabetically by command_name for stable help output.
+          def subcommands
+            Textus::Surfaces::CLI::Runner.install!
+            Verb.descendants
+                .select { |k| k.parent_group == self && k.command_name }
+                .sort_by(&:command_name)
+                .to_h { |k| [k.command_name, k] }
+          end
+
+          def needs_store?
+            # Delegate to the matched subcommand at parse time; default true.
+            true
+          end
+        end
+
+        def parse(argv)
+          subs = self.class.subcommands
+          subname = argv.shift
+          if subname.nil?
+            raise UsageError.new(
+              "#{self.class.command_name} requires a subcommand: #{subs.keys.join(", ")}",
+            )
+          end
+
+          @sub_klass = subs[subname]
+          unless @sub_klass
+            raise UsageError.new(
+              "unknown #{self.class.command_name} subcommand '#{subname}'. " \
+              "Valid: #{subs.keys.join(", ")}",
+            )
+          end
+
+          @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+          @sub.parse(argv)
+        end
+
+        def call(store)
+          @sub.call(@sub_klass.needs_store? ? store : nil)
+        end
+      end
+    end
+  end
+end