textus 0.52.0 → 0.53.0

data/lib/textus/manifest/schema/validator.rb

@@ -14,34 +14,36 @@ module Textus
           raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
           walk(raw, ROOT_KEYS, "$")
+          raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
+
           validate_roles!(raw["roles"])
-          validate_zones!(raw["zones"])
+          validate_lanes!(raw["lanes"])
           validate_entries!(raw["entries"])
-          validate_owners!(raw["zones"], raw["entries"])
+          validate_owners!(raw["lanes"], raw["entries"])
           validate_rules!(raw["rules"])
           walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
           validate_single_queue!(raw)
           validate_single_machine!(raw)
-          validate_zone_kind_consistency!(raw)
+          validate_lane_kind_consistency!(raw)
         end
 
-        def validate_zones!(zones)
-          Array(zones).each_with_index do |z, i|
-            walk(z, ZONE_KEYS, "$.zones[#{i}]")
+        def validate_lanes!(lanes)
+          Array(lanes).each_with_index do |z, i|
+            walk(z, LANE_KEYS, "$.lanes[#{i}]")
             if z["kind"].nil?
-              raise BadManifest.new("zone '#{z["name"]}' at '$.zones[#{i}]' must declare a kind (one of: #{ZONE_KINDS.join(", ")})")
+              raise BadManifest.new("lane '#{z["name"]}' at '$.lanes[#{i}]' must declare a kind (one of: #{LANE_KINDS.join(", ")})")
             end
-            next if ZONE_KINDS.include?(z["kind"])
+            next if LANE_KINDS.include?(z["kind"])
 
             if %w[quarantine derived].include?(z["kind"])
               raise BadManifest.new(
-                "zone kind '#{z["kind"]}' at '$.zones[#{i}]' was folded into 'machine' (ADR 0091) — " \
+                "lane kind '#{z["kind"]}' at '$.lanes[#{i}]' was folded into 'machine' (ADR 0091) — " \
                 "use `kind: machine`",
               )
             end
 
             raise BadManifest.new(
-              "unknown zone kind '#{z["kind"]}' at '$.zones[#{i}]' (known: #{ZONE_KINDS.join(", ")})",
+              "unknown lane kind '#{z["kind"]}' at '$.lanes[#{i}]' (known: #{LANE_KINDS.join(", ")})",
             )
           end
         end
@@ -217,9 +219,9 @@ module Textus
         # (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 validate_owners!(zones, entries)
-          Array(zones).each_with_index do |z, i|
-            check_owner!(z["owner"], "$.zones[#{i}]")
+        def validate_owners!(lanes, entries)
+          Array(lanes).each_with_index do |z, i|
+            check_owner!(z["owner"], "$.lanes[#{i}]")
           end
           Array(entries).each_with_index do |e, i|
             check_owner!(e["owner"], "$.entries[#{i}]")
@@ -265,20 +267,20 @@ module Textus
         end
 
         def validate_single_queue!(raw)
-          queues = Array(raw["zones"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
+          queues = Array(raw["lanes"]).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(", ")})",
+            "at most one lane may declare kind: queue (found: #{queues.join(", ")})",
           )
         end
 
         def validate_single_machine!(raw)
-          machines = Array(raw["zones"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
+          machines = Array(raw["lanes"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
           return if machines.size <= 1
 
           raise BadManifest.new(
-            "at most one zone may declare kind: machine (found: #{machines.join(", ")})",
+            "at most one lane may declare kind: machine (found: #{machines.join(", ")})",
           )
         end
 
@@ -300,20 +302,20 @@ module Textus
           end
         end
 
-        # Write authority is derived from capabilities (ADR 0030): a zone of a
+        # Write authority is derived from capabilities (ADR 0030): a lane 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
+        # verb. Reject a manifest declaring a lane 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 validate_zone_kind_consistency!(raw)
+        def validate_lane_kind_consistency!(raw)
           held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
 
-          Array(raw["zones"]).each_with_index do |z, i|
+          Array(raw["lanes"]).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}]' " \
+              "lane '#{z["name"]}' (#{z["kind"]}) at '$.lanes[#{i}]' " \
               "needs a role with capability '#{verb}'; none declared",
             )
           end

data/lib/textus/manifest/schema/vocabulary.rb

@@ -15,7 +15,7 @@ module Textus
           "queue" => "propose",
         }.freeze
 
-        ZONE_KINDS         = LANES.keys.freeze
+        LANE_KINDS         = LANES.keys.freeze
         CAPABILITIES       = LANES.values.uniq.freeze
         KIND_REQUIRES_VERB = LANES
       end

data/lib/textus/manifest/schema.rb

@@ -7,13 +7,13 @@ module Textus
     module Schema
       # Re-export the vocabulary.
       LANES              = Vocabulary::LANES
-      ZONE_KINDS         = Vocabulary::ZONE_KINDS
+      LANE_KINDS         = Vocabulary::LANE_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
+      LANE_KEYS             = Keys::LANE_KEYS
       ENTRY_KEYS            = Keys::ENTRY_KEYS
       PUBLISH_KEYS          = Keys::PUBLISH_KEYS
       SOURCE_KEYS           = Keys::SOURCE_KEYS

data/lib/textus/manifest.rb

@@ -6,8 +6,8 @@ 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_entry?,
-  #     queue_zone?, permission_for, …)
+  #   * policy   — zone/role authority (lane_writers, declared_kind, derived_entry?,
+  #     queue_lane?, permission_for, …)
   #   * rules    — match-block rule engine (lifecycle, handler allowlist, materialize, …)
   #
   # Use `manifest.data.entries`, `manifest.policy.declared_kind(z)`, etc.

data/lib/textus/{produce → pipeline}/acquire/handler.rb

@@ -1,7 +1,7 @@
 require "timeout"
 
 module Textus
-  module Produce
+  module Pipeline
     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
@@ -18,7 +18,7 @@ module Textus
 
         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)
+            caps.steps.invoke(:fetch, handler, caps: caps, config: config, args: args)
           end
         rescue Timeout::Error
           raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")

data/lib/textus/{produce → pipeline}/acquire/intake.rb

@@ -1,21 +1,21 @@
 require "timeout"
 
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       # Internal ingest executor for one machine-zone intake entry. No longer a
       # public verb (ADR 0079 collapsed the `fetch` surface): used by the
       # converge sweep (drain/serve) and `textus hook run` only — ingest is system-pushed
       # (ADR 0089 removed the read-through that once also drove it).
       class Intake
-        FETCH_TIMEOUT_SECONDS = Textus::Produce::Acquire::Handler::FETCH_TIMEOUT_SECONDS
+        FETCH_TIMEOUT_SECONDS = Textus::Pipeline::Acquire::Handler::FETCH_TIMEOUT_SECONDS
 
         def initialize(container:, call:)
           @container    = container
           @call         = call
           @manifest     = container.manifest
           @schemas      = container.schemas
-          @rpc          = container.rpc
+          @steps          = container.steps
         end
 
         # call(key) is the primary entry; run is kept as an alias for
@@ -61,10 +61,6 @@ module Textus
 
         private
 
-        def fetch_events
-          @fetch_events ||= Textus::Produce::Events.from(container: @container, call: @call)
-        end
-
         # ADR 0079: a per-rule fetch_timeout_seconds override was an accepted loss
         # in the fetch:/retention: → lifecycle: collapse; the constant ceiling
         # applies to every intake.
@@ -72,36 +68,35 @@ module Textus
           FETCH_TIMEOUT_SECONDS
         end
 
+        def steps_ctx
+          @steps_ctx ||= Textus::Step::Context.for(container: @container, call: @call)
+        end
+
         def fetch_with_events(key, mentry, remaining)
-          fetch_events.started(key)
+          @steps.publish(:entry_fetch_started, ctx: steps_ctx, key: key, mode: :sync)
           call_intake(key, mentry, remaining)
         end
 
         def call_intake(key, mentry, remaining)
-          Textus::Produce::Acquire::Handler.invoke(
+          Textus::Pipeline::Acquire::Handler.invoke(
             caps: @container, handler: mentry.handler,
             config: mentry.config,
             args: { trigger_key: key, leaf_segments: remaining || [] },
             label: "intake", timeout: fetch_timeout_for(key)
           )
         rescue Textus::Error => e
-          fetch_events.failed(key, e)
+          @steps.publish(:entry_fetch_failed, ctx: steps_ctx, key: key,
+                                              error_class: e.class.name, error_message: e.message)
           raise
         rescue StandardError => e
-          fetch_events.failed(key, e)
+          @steps.publish(:entry_fetch_failed, ctx: steps_ctx, key: key,
+                                              error_class: e.class.name, error_message: e.message)
           raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
         end
 
         def persist_and_notify(key, mentry, result, before_etag)
           normalized = self.class.normalize_action_result(result, format: mentry.format)
-          Textus::Domain::Policy::GuardFactory.new(
-            manifest: @manifest, schemas: @schemas,
-          ).for(:converge, key).check!(
-            Textus::Domain::Policy::Evaluation.new(
-              actor: @call.role, transition: :converge, origin: nil,
-              target: key, envelope: nil, manifest: @manifest
-            ),
-          )
+          auth.check_action!(action: :converge, actor: @call.role, key: key)
           envelope = writer.put(
             key,
             mentry: mentry,
@@ -110,7 +105,10 @@ module Textus
             ),
           )
           change = detect_change(before_etag, envelope)
-          fetch_events.fetched(key, envelope, change)
+          unless change == :unchanged
+            @steps.publish(:entry_fetched, ctx: steps_ctx, key: key,
+                                           envelope: envelope, change: change)
+          end
           envelope
         end
 
@@ -124,6 +122,10 @@ module Textus
         def writer
           @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
         end
+
+        def auth
+          @auth ||= Textus::Gate::Auth.new(@container)
+        end
       end
     end
   end

data/lib/textus/{produce → pipeline}/acquire/projection.rb

@@ -1,7 +1,7 @@
 require "fileutils"
 
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       # Builds an entry's DATA artifact (ADR 0094) by running the projection
       # pipeline; rendering is a publish concern. External entries are NOT built
@@ -34,13 +34,13 @@ module Textus
           end
         end
 
-        Deps = Data.define(:manifest, :reader, :lister, :rpc, :transform_context)
+        Deps = Data.define(:manifest, :reader, :lister, :steps, :transform_context)
 
         def self.renderers
           @renderers ||= {
-            "text" => Produce::Acquire::Serializer::Text,
-            "json" => Produce::Acquire::Serializer::Json,
-            "yaml" => Produce::Acquire::Serializer::Yaml,
+            "text" => Textus::Pipeline::Acquire::Serializer::Text,
+            "json" => Textus::Pipeline::Acquire::Serializer::Json,
+            "yaml" => Textus::Pipeline::Acquire::Serializer::Yaml,
           }
         end
 
@@ -49,14 +49,16 @@ module Textus
           @call       = call
           @manifest   = container.manifest
           @file_store = container.file_store
-          @rpc        = container.rpc
+          @steps      = container.steps
           @root       = container.root
         end
 
         # Runs the projection pipeline for `mentry` and returns the on-disk
         # target_path string.
         def run(mentry)
-          reader   = Textus::Read::Get.new(container: @container, call: @call)
+          reader = lambda do |key|
+            Textus::Action::Get.new(key: key).call(container: @container, call: @call)
+          end
           # Projections must be able to read source data from any nested entry,
           # including keyless (publish_tree) ones like knowledge.decisions.
           # The `include_keyless: true` option makes the resolver walk those dirs
@@ -64,15 +66,15 @@ module Textus
           resolver = @manifest.resolver
           lister = lambda do |prefix:|
             resolver.enumerate(prefix: prefix, include_keyless: true)
-                    .map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
+                    .map { |row| { "key" => row[:key], "lane" => row[:manifest_entry].lane, "path" => row[:path] } }
           end
           self.class.pipeline_run(
             mentry: mentry,
             deps: Deps.new(
               manifest: @manifest,
-              reader: reader.method(:call),
+              reader: reader,
               lister: lister,
-              rpc: @rpc,
+              steps: @steps,
               transform_context: @container,
             ),
           )
@@ -95,7 +97,7 @@ module Textus
               reader: deps.reader,
               spec: mentry.source.projection_spec,
               lister: deps.lister,
-              rpc: deps.rpc,
+              steps: deps.steps,
               transform_context: deps.transform_context,
             ).run
 

data/lib/textus/{produce → pipeline}/acquire/serializer/json.rb

@@ -1,13 +1,13 @@
 require "json"
 
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       class Serializer
         class Json < Serializer
           def call(mentry:, data:)
             content = default_shape(mentry, data)
-            final   = Produce::Acquire::Projection::InjectMeta.call(content, mentry)
+            final   = Textus::Pipeline::Acquire::Projection::InjectMeta.call(content, mentry)
             Entry.for_format("json").serialize(meta: {}, body: "", content: final)
           end
 

data/lib/textus/{produce → pipeline}/acquire/serializer/text.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       class Serializer
         class Text < Serializer

data/lib/textus/{produce → pipeline}/acquire/serializer/yaml.rb

@@ -1,13 +1,13 @@
 require "yaml"
 
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       class Serializer
         class Yaml < Serializer
           def call(mentry:, data:)
             content = default_shape(mentry, data)
-            final   = Produce::Acquire::Projection::InjectMeta.call(content, mentry)
+            final   = Textus::Pipeline::Acquire::Projection::InjectMeta.call(content, mentry)
             Entry.for_format("yaml").serialize(meta: {}, body: "", content: final)
           end
 

data/lib/textus/{produce → pipeline}/acquire/serializer.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Produce
+  module Pipeline
     module Acquire
       # Abstract base for output serializers. Each concrete serializer owns
       # producing the bytes for one manifest format (json/yaml/text).

data/lib/textus/{produce → pipeline}/engine.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Produce
+  module Pipeline
     # 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):
@@ -25,9 +25,9 @@ module Textus
       rescue Textus::BuildInProgress
         nil
       rescue Textus::Error => e
-        container.events.publish(
+        container.steps.publish(
           :produce_failed,
-          ctx: Textus::Hooks::Context.for(container: container, call: call),
+          ctx: Textus::Step::Context.for(container: container, call: call),
           keys: keys, error: e.message
         )
       end
@@ -62,7 +62,7 @@ module Textus
         entry = @manifest.resolver.resolve(key).entry
 
         if entry.intake?
-          Textus::Produce::Acquire::Intake.new(container: @container, call: build_call).run(key) # acquire: re-pull
+          Textus::Pipeline::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
         else
@@ -87,7 +87,9 @@ module Textus
       def build_context(call)
         Textus::Manifest::Entry::Base::PublishContext.new(
           container: @container, call: call,
-          reader: Textus::Read::Get.new(container: @container, call: call)
+          reader: lambda { |key|
+            Textus::Action::Get.new(key: key).call(container: @container, call: call)
+          }
         )
       end
     end

data/lib/textus/{produce → pipeline}/render.rb

@@ -1,5 +1,7 @@
+require "mustache"
+
 module Textus
-  module Produce
+  module Pipeline
     # 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

data/lib/textus/ports/audit_log.rb

@@ -78,16 +78,42 @@ module Textus
       def verify_integrity
         return [] unless File.exist?(@path)
 
-        out = []
-        File.foreach(@path).with_index(1) do |line, lineno|
-          violation = check_line(line.chomp, lineno)
-          out << violation if violation
+        [].tap do |out|
+          iterate_with_prev_seq do |line, lineno, prev_seq|
+            check_line_integrity(line, lineno, prev_seq, out)
+          end
         end
-        out
       end
 
       private
 
+      def iterate_with_prev_seq
+        prev_seq = nil
+        File.foreach(@path).with_index(1) do |line, lineno|
+          yield line.chomp, lineno, prev_seq
+          parsed = parse_row(line.chomp)
+          prev_seq = parsed["seq"] if parsed&.dig("seq").is_a?(Integer)
+        end
+      end
+
+      def check_line_integrity(line, lineno, prev_seq, out)
+        violation = check_line(line, lineno)
+        if violation
+          out << violation
+          return
+        end
+
+        parsed = parse_row(line)
+        return unless parsed && (seq = parsed["seq"]).is_a?(Integer)
+        return unless prev_seq && seq != prev_seq + 1
+
+        out << {
+          "lineno" => lineno,
+          "reason" => "seq_gap",
+          "detail" => "expected #{prev_seq + 1}, got #{seq}",
+        }
+      end
+
       def rotated(n)
         File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}")
       end

data/lib/textus/ports/audit_subscriber.rb

@@ -3,9 +3,9 @@
 module Textus
   module Ports
     # Writes an "event_error" audit row when a user hook raises during
-    # Hooks::EventBus publish. Attached at Store boot.
+    # Step::EventBus publish. Attached at Store boot.
     #
-    # Integration: uses Hooks::EventBus#on_error callback (chosen over a
+    # Integration: uses Step::EventBus#on_error callback (chosen over a
     # synthetic :hook_error event because the bus already owns the
     # rescue and the failure is a bus-internal concern, not a domain
     # event subscribers should be able to filter by key glob).
@@ -19,8 +19,8 @@ module Textus
         @audit_log = audit_log
       end
 
-      def attach(bus)
-        bus.on_error do |event:, hook:, key:, kwargs:, error:|
+      def attach(registry)
+        registry.on_error do |event:, hook:, key:, kwargs:, error:|
           record_error(event: event, hook: hook, key: key, kwargs: kwargs, error: error)
         end
         self

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

@@ -2,12 +2,12 @@ require "digest"
 require "json"
 
 module Textus
-  module Domain
-    module Jobs
+  module Ports
+    class Queue
       # 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

@@ -42,7 +42,7 @@ module Textus
           rescue Errno::ENOENT
             next # another worker won this one
           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

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