textus 0.14.2 → 0.14.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a732844e2441328f7519ffd93571c3ff611fd0514c2b1f927b5c4ada499db16
-  data.tar.gz: 63a3e530439c37fbbff8c8b3864b1489cd34c88c88bd1c10f03ae980f4a66041
+  metadata.gz: d1e2a12b234bfc677ce44ec7b49b3b04b4ac69abbc15f13496911c82d89549c8
+  data.tar.gz: 6b83336a05cb3cee509d3e0b90ce2048ed57fdeb5fbc603f22303e10c2d5c27c
 SHA512:
-  metadata.gz: 5470a6aaf29f1b081144b2eca3b1e87e5b1d465977422c967366196d259041cdbb8e0993ce293d87d7903f9446649f80ea99e1e6367b9731f7b839bf18f9d67f
-  data.tar.gz: dcd3f57064d2f6753f049daf1315a937566e3b77a9ec130455a54410292f73ec55104bafe1e1b20431dc186a1c13735a7e6c6018ef8f54b77122f0eb2e267e8c
+  metadata.gz: f126d898385e0d0236a1818a741923f8ee9f88f1f13cab8ef37bbb810d14145904186084f72d0fbc5a4d6bfdf53b5e7e68699f56db4f9aa02d22772019a11316
+  data.tar.gz: 054ea4fea78cf26d570319d49f2a0ffbd4023e6355b56b8830650e7d59b1b57ae2de7b158ef0611b465369136e11b292ba9f968113cd425ecd1cfed1bf96633d

data/CHANGELOG.md

@@ -9,6 +9,63 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.14.4 — 2026-05-26
+
+### Fixed
+
+- `textus build` no longer triggers per-leaf refresh fan-out when
+  projection reads encounter stale entries under `on_stale: timed_sync`
+  / `on_stale: sync`. Build is a downstream materialization step over
+  current store state; freshness is an inflow concern, and they
+  shouldn't compose. Previously, building a marketplace-style output
+  whose projection selected `intake.vendor.**` against ~400 stale
+  leaves spawned ~400 concurrent detached refresh workers, each
+  re-running the full intake handler, exhausting the system. The
+  build pipeline now reads through an `Application::Context` with
+  `bypass_freshness: true`, so `Application::Reads::Get` returns the
+  on-disk envelope annotated as fresh without consulting the
+  orchestrator. Explicit freshness before build still works via
+  `textus refresh stale`. (#59)
+
+### Added
+
+- `Application::Context#bypass_freshness?` — new flag for read paths
+  that must not initiate refresh. Threaded through `Operations.for`
+  and propagated across `Context#with_role`. Used by `Builder::Pipeline`
+  via a `bypass_freshness:` constructor kwarg on `Projection`.
+- `textus doctor` now reports stale per-key refresh lock files under
+  `<root>/.locks/` whose recorded PID is no longer running, as an
+  `info`-level `refresh_lock.stale` issue. The check is purely
+  informational: `Refresh::Lock` uses `flock(2)`, which the kernel
+  releases on process death, so stale `.lock` files on disk do not
+  block subsequent refresh acquires. The check exists so users can
+  clean up forensic clutter and notice unexpected accumulation. No
+  read-path changes — adding a PID probe + unlink there would
+  reintroduce the TOCTOU and PID-reuse hazards explicitly rejected
+  in 0.14.3 / PR #57. (#58)
+
+### Tested
+
+- Added a regression spec that forks a child, takes a per-key
+  `Refresh::Lock`, SIGKILLs the child, and asserts a fresh acquire
+  on the same key succeeds without manual cleanup. Pins the
+  flock-survives-SIGKILL contract.
+
+## 0.14.3 — 2026-05-26
+
+### Added
+
+- Top-level `flock(2)` mutex at `<root>/.build.lock` prevents concurrent
+  `textus build` invocations against the same store. A second build
+  while one is already running exits with code `75` (`EX_TEMPFAIL`) and
+  emits a `build_in_progress` error envelope, so wrappers like `rake
+  update` and CI can distinguish "another build is busy" from "this
+  build is broken". The lock is FD-bound and released by the kernel on
+  process death (including SIGKILL/OOM), so no stale-lock takeover
+  logic is needed. `close_on_exec` prevents the lock from leaking into
+  `bundle exec` and lefthook child processes. Per-key locks under
+  `.locks/` are unchanged. (#56)
+
 ## 0.14.2 — 2026-05-26
 
 ### Added

data/lib/textus/application/context.rb

@@ -9,13 +9,14 @@ module Textus
         new(store: store, role: "human")
       end
 
-      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
-        @store          = store
-        @role           = role.to_s
-        @correlation_id = correlation_id || SecureRandom.uuid
-        @clock          = clock
-        @dry_run        = dry_run
-        @now            = nil
+      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false, bypass_freshness: false)
+        @store             = store
+        @role              = role.to_s
+        @correlation_id    = correlation_id || SecureRandom.uuid
+        @clock             = clock
+        @dry_run           = dry_run
+        @bypass_freshness  = bypass_freshness
+        @now               = nil
       end
 
       def now
@@ -26,6 +27,10 @@ module Textus
         @dry_run
       end
 
+      def bypass_freshness?
+        @bypass_freshness
+      end
+
       def can_write?(zone)
         store.manifest.permission_for(zone.to_s).allows_write?(role)
       end
@@ -41,6 +46,7 @@ module Textus
           correlation_id: @correlation_id,
           clock: @clock,
           dry_run: @dry_run,
+          bypass_freshness: @bypass_freshness,
         )
       end
     end

data/lib/textus/application/reads/get.rb

@@ -11,6 +11,7 @@ module Textus
         def call(key)
           envelope = @ctx.store.reader.read_raw_envelope(key)
           return nil if envelope.nil?
+          return annotate_fresh(envelope) if @ctx.bypass_freshness?
 
           policy_set = @ctx.store.manifest.rules_for(key)
           refresh_policy = policy_set.refresh

data/lib/textus/builder/pipeline.rb

@@ -62,7 +62,7 @@ module Textus
         # 1. Load sources + project + reduce
         data =
           if mentry.projection
-            Projection.new(store, mentry.projection).run
+            Projection.new(store, mentry.projection, bypass_freshness: true).run
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end

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

@@ -5,12 +5,14 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          ops = Textus::Operations.for(store, role: "builder")
-          build_res   = ops.writes.build.call(prefix: prefix)
-          publish_res = ops.writes.publish.call(prefix: prefix)
-          emit({ "protocol" => Textus::PROTOCOL,
-                 "built" => build_res["built"],
-                 "published_leaves" => publish_res["published_leaves"] })
+          Textus::Infra::BuildLock.with(root: store.root) do
+            ops = Textus::Operations.for(store, role: "builder")
+            build_res   = ops.writes.build.call(prefix: prefix)
+            publish_res = ops.writes.publish.call(prefix: prefix)
+            emit({ "protocol" => Textus::PROTOCOL,
+                   "built" => build_res["built"],
+                   "published_leaves" => publish_res["published_leaves"] })
+          end
         end
       end
     end

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

@@ -0,0 +1,49 @@
+module Textus
+  module Doctor
+    class Check
+      # Lists per-key refresh lock files under <store.root>/.locks/ whose
+      # recorded PID is no longer running. These are forensic artifacts only:
+      # Refresh::Lock uses flock(2), which the kernel releases on process
+      # death, so stale files do not block subsequent acquires. The check
+      # exists to let users clean up clutter and notice unexpected accumulation
+      # (e.g. a refresh path that crashes repeatedly).
+      class RefreshLocks < Check
+        def call
+          dir = File.join(store.root, ".locks")
+          return [] unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "*.lock")).filter_map { |path| inspect_lock(path) }
+        end
+
+        private
+
+        def inspect_lock(path)
+          pid = File.read(path).strip.to_i
+          return nil if pid.zero?
+          return nil if pid_alive?(pid)
+
+          {
+            "code" => "refresh_lock.stale",
+            "level" => "info",
+            "subject" => path,
+            "message" => "refresh lock file at #{path} records dead PID #{pid} " \
+                         "(does not block refresh; flock is kernel-released on exit)",
+            "fix" => "safe to delete: rm #{path}",
+          }
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def pid_alive?(pid)
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH
+          false
+        rescue Errno::EPERM
+          # Process exists but owned by another user — treat as alive.
+          true
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -23,6 +23,7 @@ module Textus
       Check::SchemaViolations,
       Check::RuleAmbiguity,
       Check::HandlerAllowlist,
+      Check::RefreshLocks,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/errors.rb

@@ -122,6 +122,18 @@ module Textus
     def initialize(m) = super("io_error", m, exit_code: 64)
   end
 
+  class BuildInProgress < Error
+    def initialize(holder)
+      super(
+        "build_in_progress",
+        "textus build already running (#{holder})",
+        details: { "holder" => holder },
+        exit_code: 75,
+        hint: "wait for the running build to finish, or check for a recursive hook trigger"
+      )
+    end
+  end
+
   class UsageError < Error
     def initialize(m, hint: nil) = super("usage", m, exit_code: 2, hint: hint)
   end

data/lib/textus/infra/build_lock.rb

@@ -0,0 +1,59 @@
+require "fileutils"
+require "socket"
+require "time"
+
+module Textus
+  module Infra
+    class BuildLock
+      LOCK_FILENAME = ".build.lock"
+      MAX_HOLDER_BYTES = 512
+
+      def self.with(root:, &)
+        new(root: root).acquire_or_raise(&)
+      end
+
+      def initialize(root:)
+        @path = File.join(root, LOCK_FILENAME)
+        @file = nil
+      end
+
+      def acquire_or_raise
+        FileUtils.mkdir_p(File.dirname(@path))
+        @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+        @file.close_on_exec = true
+
+        unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+          holder = read_holder_safely
+          @file.close
+          @file = nil
+          raise Textus::BuildInProgress.new(holder)
+        end
+
+        @file.truncate(0)
+        @file.write("pid=#{Process.pid} started=#{Time.now.utc.iso8601} host=#{Socket.gethostname}\n")
+        @file.flush
+
+        yield
+      ensure
+        release
+      end
+
+      private
+
+      def release
+        return unless @file
+
+        @file.flock(File::LOCK_UN)
+        @file.close
+        @file = nil
+      end
+
+      def read_holder_safely
+        content = File.read(@path, MAX_HOLDER_BYTES)
+        content.gsub(/[^[:print:]\t ]/, "").strip
+      rescue StandardError
+        "unknown"
+      end
+    end
+  end
+end

data/lib/textus/operations.rb

@@ -9,12 +9,13 @@ module Textus
   #
   # Replaces the prior `Textus::Composition` module (deleted in v0.12.2).
   class Operations
-    def self.for(store, role: Role::DEFAULT, correlation_id: nil, dry_run: false)
+    def self.for(store, role: Role::DEFAULT, correlation_id: nil, dry_run: false, bypass_freshness: false)
       ctx = Application::Context.new(
         store: store,
         role: role,
         correlation_id: correlation_id,
         dry_run: dry_run,
+        bypass_freshness: bypass_freshness,
       )
       new(ctx)
     end

data/lib/textus/projection.rb

@@ -6,9 +6,10 @@ module Textus
     MAX_LIMIT = 1000
     REDUCER_TIMEOUT_SECONDS = 2
 
-    def initialize(store, spec)
+    def initialize(store, spec, bypass_freshness: false)
       @store = store
       @spec = spec || {}
+      @bypass_freshness = bypass_freshness
       @limit = (@spec["limit"] || MAX_LIMIT).to_i
       raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
     end
@@ -16,8 +17,9 @@ module Textus
     def run
       keys = collect_keys
       explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
+      ops = Operations.for(@store, bypass_freshness: @bypass_freshness)
       rows = keys.map do |key|
-        env = Operations.for(@store).reads.get.call(key)
+        env = ops.reads.get.call(key)
         row = pluck(env.meta, env.body)
         explicit_pluck ? row : row.merge("_key" => key)
       end
@@ -50,7 +52,7 @@ module Textus
 
     def collect_keys
       prefixes = Array(@spec["select"])
-      ops = Operations.for(@store)
+      ops = Operations.for(@store, bypass_freshness: @bypass_freshness)
       prefixes.flat_map { |p| ops.reads.list.call(prefix: p).map { |row| row["key"] } }.uniq
     end
 

data/lib/textus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.14.4
 platform: ruby
 authors:
 - Patrick
@@ -188,6 +188,7 @@ files:
 - lib/textus/doctor/check/intake_registration.rb
 - lib/textus/doctor/check/manifest_files.rb
 - lib/textus/doctor/check/protocol_version.rb
+- lib/textus/doctor/check/refresh_locks.rb
 - lib/textus/doctor/check/rule_ambiguity.rb
 - lib/textus/doctor/check/schema_parse_error.rb
 - lib/textus/doctor/check/schema_violations.rb
@@ -223,6 +224,7 @@ files:
 - lib/textus/hooks/dsl.rb
 - lib/textus/hooks/loader.rb
 - lib/textus/hooks/registry.rb
+- lib/textus/infra/build_lock.rb
 - lib/textus/infra/clock.rb
 - lib/textus/infra/event_bus.rb
 - lib/textus/infra/publisher.rb