textus 0.14.3 → 0.14.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65cfe5f73a64dda44280d1dd58e418aecdc94b79e1abb68340e973d364da3465
-  data.tar.gz: c35f1428a0965c11c946395a8fb7dfeb60202e2fac2514b1bb04dfae1e426ed2
+  metadata.gz: d1e2a12b234bfc677ce44ec7b49b3b04b4ac69abbc15f13496911c82d89549c8
+  data.tar.gz: 6b83336a05cb3cee509d3e0b90ce2048ed57fdeb5fbc603f22303e10c2d5c27c
 SHA512:
-  metadata.gz: edeefd203bb0f4af807457cb96353affd3a21de846331481bb3d6e69e344fc1ea8054f8066ed278e7a7ced366704a65df00269d38b58a5b729d408477bc4f5a5
-  data.tar.gz: 4c30fa46409c381bfa8ef381c38314ce988786b9f2cf81c8b1c76f7508301587b9e5562ce1ced415f85484fe794fe3aeff5186203f733cedea34443d43a4eb57
+  metadata.gz: f126d898385e0d0236a1818a741923f8ee9f88f1f13cab8ef37bbb810d14145904186084f72d0fbc5a4d6bfdf53b5e7e68699f56db4f9aa02d22772019a11316
+  data.tar.gz: 054ea4fea78cf26d570319d49f2a0ffbd4023e6355b56b8830650e7d59b1b57ae2de7b158ef0611b465369136e11b292ba9f968113cd425ecd1cfed1bf96633d

data/CHANGELOG.md

@@ -9,6 +9,48 @@ 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

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/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/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.3"
+  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.3
+  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