findxpand 0.1.0

data/lib/findxpand/store.rb

@@ -0,0 +1,657 @@
+# frozen_string_literal: true
+
+# The rule set, held in memory and persisted to one file.
+#
+# **Nothing here ever calls out.** Findxpand pushes to this process; this process
+# never fetches from Findxpand. A middleware that blocks on a network call to a
+# vendor has made that vendor's uptime the site's uptime for the sake of a title
+# tag, and polling is the same coupling with a staleness window attached. The
+# consequence worth holding in mind: if Findxpand is down, this keeps serving
+# whatever it last stored, indefinitely.
+#
+# The cache file exists so a restart is not a regression. Without it every deploy
+# would drop every rule until the next push, and the site would quietly revert to
+# the titles the client is paying to change.
+#
+# **One store per process, shared by every attach point.** Ruby has more ways to
+# get into the request path than Node or Python do — a Railtie, a builder
+# prepend, and a hand-written `use` are all reachable in the same process — and
+# two of them can be live at once. Two `Store` objects would mean two manifests,
+# two sets of counters and a `/status` answering for whichever instance happened
+# to own the admin path, so `Findxpand.store` is memoised and every instance uses
+# it unless a test passes its own (§20.1 rule 2).
+#
+# Frozen string literals: on. Nothing here appends to a literal.
+
+require 'json'
+require 'fileutils'
+
+module Findxpand
+  # The one degraded verdict, worded by the engine and shared with the Node and
+  # Python implementations.
+  #
+  # Mirrors `engine.fix.origin.DEGRADED_REASONS` and
+  # `middleware/node/src/manifest.ts`'s `degradedReason` branch for branch. Two
+  # independently-worded health checks are two that disagree the first time
+  # either is edited, and this one is the sentence a customer pastes into a
+  # support thread — `middleware/conformance/cases.json` carries the three
+  # templates and `test/conformance_test.rb` asserts these against them.
+  #
+  # The order is the order of usefulness: `skip_encoded` names the actual
+  # mistake, so it is reported ahead of the "nothing landed" symptom it causes.
+  # A middleware mounted behind compression matches both branches, and reporting
+  # the symptom would send somebody hunting through their manifest for a
+  # mounting bug.
+  module Degraded
+    def self.reason(counters, has_rules)
+      skip_encoded = count(counters, :skip_encoded)
+      if skip_encoded.positive?
+        return "#{skip_encoded} response(s) arrived already compressed and could not be " \
+               'rewritten - the middleware is mounted after compression, and needs to be ' \
+               'mounted before it'
+      end
+
+      errors = count(counters, :error)
+      if errors.positive?
+        # Not gated on `has_rules`, and the fixture says so in its own row: that
+        # gate guards the third branch only. A rewrite that raised is read from
+        # what happened to a response; `has_rules` is read from the manifest,
+        # and the two are not the same claim.
+        return "#{errors} rewrite(s) raised and the original page was served unchanged"
+      end
+
+      considered = count(counters, :considered)
+      if has_rules && considered.positive? && count(counters, :applied).zero?
+        # `applied == 0`, never `applied < considered`. A page whose rule matched
+        # and whose output was identical is a `pass` rather than a failure, and
+        # reporting 39 of 40 as degraded would flag every site holding a rule for
+        # a page that already carries the right title.
+        return "#{considered} response(s) matched a rule and none were rewritten"
+      end
+
+      ''
+    end
+
+    # One counter, whether it is keyed by Symbol or by String.
+    #
+    # The `Store` keeps Symbols and the shared fixture carries Strings, because
+    # it arrives through `JSON.parse`. Converting inside the test would mean the
+    # suite asserting against a shape it made up rather than the one the fixture
+    # ships (§20.1 rule 1), and converting inside `Store` would leave this
+    # function with a second caller shape it had never been run against. One
+    # lookup that answers both, at the only place that reads a counter by name.
+    def self.count(counters, name)
+      value = counters[name]
+      value = counters[name.to_s] if value.nil?
+      value.to_i
+    end
+  end
+
+  class Store
+    EMPTY = { 'version' => '', 'pages' => {} }.freeze
+
+    # What this process has actually done since it started.
+    #
+    # These exist because the worst failure on this route is invisible. Mounted
+    # behind compression, or mounted on a path the manifest never names, the
+    # middleware serves every page untouched and a status endpoint reporting
+    # only "42 rules, pushed 3 minutes ago" looks perfectly healthy. Answering
+    # that with README prose telling the customer to be careful pushes the
+    # detection onto them; a counter and a `degraded` flag let a monitor find it.
+    #
+    # Raised 19 Aug 2026 by a customer's developer reviewing the install docs,
+    # who was right: "they documented the silent-failure mode instead of fixing
+    # it."
+    #
+    # Ten keys: the eight every implementation reports, plus the two this
+    # runtime can actually reach.
+    #
+    # **The comment that used to sit here said these were "one shape of status
+    # JSON whichever package answers". They are not, and never were.** Node
+    # ships `unmatched` and cannot ship `skip_undecodable` —
+    # `Buffer.toString('utf8')` substitutes replacement characters rather than
+    # failing, so it has nothing to count; Python ships `skip_undecodable` and
+    # no `unmatched`; PHP ships `skip_undecodable` plus `armed` and
+    # `skip_streamed`, which only an `ob_start` attach can fail at. The honest
+    # rule, and the one PHP writes out at `middleware/php/src/Store.php:100-165`,
+    # is: **every key is present at zero rather than absent**, so no reader ever
+    # writes a branch for a key that appears only on the stacks that hit it.
+    #
+    # `unmatched` was the missing one here, and its absence was not cosmetic. It
+    # counts requests that reached this middleware on a path the manifest does
+    # not name, and it is the third value that makes `considered: 0` readable: a
+    # manifest whose keys match nothing looks exactly like an install nobody has
+    # sent a request to. `engine.fix.origin.degraded_reason`'s docstring names
+    # it as the honest fix for that hole, Node implemented it
+    # (`middleware/node/src/manifest.ts:60-89`), and an operator alerting on
+    # `counters.unmatched > 0 && counters.considered == 0` was evaluating
+    # `nil > 0` against a Ruby origin — so the alert never fired, for exactly the
+    # failure it was written for. Ported 2 Sep 2026, counter and semantics
+    # unchanged, rather than reworded here (§20.1 rule 2).
+    #
+    # Still outstanding, and named rather than hidden: Python and PHP do not
+    # have `unmatched` yet, and `Degraded.reason` — which is pinned by the
+    # shared fixture — still does not read it in any language. What reads it
+    # here is `reach_reason`, this package's own layer over the shared verdict.
+    NO_COUNTERS = {
+      considered: 0, applied: 0, passed: 0, skip_encoded: 0,
+      skip_large: 0, skip_undecodable: 0, error: 0, redirect: 0, status: 0,
+      unmatched: 0
+    }.freeze
+
+    # Header marker to counter name. `1` is the applied case; `redirect` and
+    # `status` are served straight from the manifest and never reach a rewrite.
+    COUNTER_KEYS = {
+      '1' => :applied, 'pass' => :passed, 'error' => :error,
+      'skip-encoded' => :skip_encoded, 'skip-large' => :skip_large,
+      'skip-encoding' => :skip_undecodable,
+      'redirect' => :redirect, 'status' => :status
+    }.freeze
+
+    # The markers that mean a rule matched and a rewrite decision was reached.
+    # `redirect` and `status` are excluded: they are answers, not rewrites, and
+    # counting them would make `applied == 0` look explicable on a site whose
+    # manifest happens to be all redirects.
+    CONSIDERED = %w[1 pass error skip-encoded skip-large skip-encoding].freeze
+
+    # How often the cache file is checked for somebody else's push, in seconds.
+    #
+    # **This is the fork problem, and Ruby has it worse than the other two
+    # packages.** Puma in cluster mode, Unicorn and Passenger all serve from
+    # forked workers, and a manifest pushed to `/__findxpand/manifest` arrives at
+    # exactly one of them: the others go on serving the previous rules until the
+    # next deploy. Nothing reports it, and it is worse than a plain staleness bug
+    # — `verify` re-fetches the page through the same load balancer, so a fix
+    # lands or fails to land depending on which worker answers, and the same
+    # change verifies on one request and not the next.
+    #
+    # The worker that took the push has already written the cache file, so every
+    # other worker can see the change with a `stat`. Throttled to once a second
+    # because it is on the read path of every request; the rest of the time this
+    # costs one clock reading and one float comparison.
+    #
+    # Two limits, stated rather than hidden: `mtime` has one-second granularity
+    # on some filesystems, so two pushes inside the same second whose payloads
+    # are also the same length would look identical and the second would be
+    # missed until the one after it; and a deployment with no shared cache file
+    # gets none of this, which is why `FINDXPAND_CACHE_FILE` is documented as
+    # required rather than optional on a forking server.
+    #
+    # **No outbound request is involved.** This reads a local file that this
+    # process's own sibling wrote. The gem never calls Findxpand.
+    RELOAD_INTERVAL_S = 1.0
+
+    # How long after boot the "never in the request path" verdict is withheld.
+    #
+    # A process that has served no page and answers `/status` is either
+    # misattached or thirty seconds old, and those are the same picture. Naming
+    # the mistake immediately would page somebody on every deploy of a
+    # low-traffic site; never naming it is the §20.1 rule 3 failure this whole
+    # counter exists to end. A minute is long enough that a running site has
+    # served something and short enough that a monitor notices within its first
+    # few polls.
+    NEVER_SEEN_AFTER_S = 60
+
+    # How many unmatched requests are evidence, rather than an accident of what
+    # happened to arrive first.
+    #
+    # `unmatched` moves on every request the manifest does not name - an image, a
+    # stylesheet, a favicon, an API call - so one of them is not evidence of
+    # anything, and a verdict that fired at the first would accuse a perfectly
+    # healthy site whose first request was its own logo. §9 rule 3: a threshold
+    # has to be defensible, and "one" is not.
+    #
+    # Twenty, held together with the same one-minute window as the verdict below,
+    # because that pair is the cheapest thing that cannot be reached by accident:
+    # a working site clears it the moment a single page matches a rule
+    # (`considered` becomes positive and the branch stops applying), and a
+    # middleware mounted where pages never go never clears it, because nothing
+    # there will ever match. The review case this exists for reported
+    # `requests_seen: 847, considered: 0` - three floors above this one.
+    #
+    # Node counts the same thing and deliberately does not vote on it yet
+    # (`middleware/node/src/manifest.ts:60-89`: "Reported, so an operator and a
+    # monitor can see it; not yet voted on"), because `degradedReason` is pinned
+    # by the shared fixture and a branch only one package has is drift by
+    # construction. This vote is cast in `reach_reason`, which is this package's
+    # own layer and is not pinned by the fixture - the same place PHP casts its
+    # equivalent.
+    KEYS_MATCH_NOTHING_AFTER = 20
+
+    # The verdicts this package adds after the shared three, and why they are
+    # not *in* the shared three.
+    #
+    # `Degraded.reason` is pinned by `middleware/conformance/cases.json` and has
+    # to answer identically in four languages, so a branch only one of us has
+    # cannot live there. It lives in `reach_reason` instead, asked only when the
+    # shared verdict has nothing to say — the same layering PHP uses
+    # (`middleware/php/src/Store.php:580-633`, `reach_reason`, merged into
+    # `degraded_reason` only when that one is empty). This is not a second
+    # wording of one rule; it is a second rule, about whether the middleware is
+    # anywhere useful at all.
+    #
+    # Ruby's attach has more ways to silently not happen than Node's or
+    # Python's: `RUBYOPT` may not be set on the process that actually serves (a
+    # `bin/rails` wrapper, a Procfile line edited in one place of two), the
+    # Railtie only registers when the gem is required after Rails, a hand-written
+    # `use` can land inside a `map` block that pages never reach, and the server
+    # may parse `config.ru` with its own vendored builder (see `auto.rb`). Every
+    # one of those ends the same way — the admin endpoints answer, the manifest
+    # is present and current, and not one page has ever passed through us — and
+    # the shared verdicts cannot see it, because all three start from
+    # `considered`, which only a request that matched a rule ever moves.
+    #
+    # Each of these three reports something this process **observed**, never
+    # something it arranged (§20.1 rule 3). A push that was not written, requests
+    # that matched nothing, an uptime with no requests at all: all three are
+    # facts about what happened here, and all three are silent until there is
+    # one.
+
+    # A push arrived and could not be stored. Reported first, because it is the
+    # only one of the three that has already lost work: the engine reads the
+    # deployed manifest back before it merges the next fix, so a store that
+    # forgets is a store that discards every previously approved fix at the next
+    # restart, with no error anywhere. That was the shipped behaviour of every
+    # non-`RUBYOPT` install until 2 Sep 2026 — see `Findxpand.store`.
+    PUSH_NOT_PERSISTED =
+      'a manifest was pushed and could not be written to disk - this process serves it now, ' \
+      'a restart drops it, and on a forking server the other workers never saw it. Set ' \
+      'FINDXPAND_CACHE_FILE to a path every worker can write'
+
+    # Rules loaded, traffic arriving, and not one request has matched. The exact
+    # signature of the `normalise_path` disagreement that shipped, and of a
+    # middleware mounted inside a `map` block that pages never reach. `{count}`
+    # is `unmatched` rather than `requests_seen`, because the sentence is about
+    # requests that were *offered* to the manifest and refused by it.
+    KEYS_MATCH_NOTHING =
+      '%<count>d request(s) reached this middleware and not one matched a rule - the ' \
+      'manifest keys do not match the paths this site serves, or this middleware is ' \
+      'mounted where the pages do not go'
+
+    # Nothing has arrived at all, for longer than a boot takes.
+    NEVER_IN_REQUEST_PATH =
+      'the middleware is loaded and answering here, but no page request has ever reached ' \
+      'it - it is attached somewhere requests do not go'
+
+    def initialize(cache_file: nil, manifest_file: nil, clock: nil)
+      @cache_file = cache_file
+      @lock = Mutex.new
+      @current = EMPTY
+      @updated_at = nil
+      @source = 'empty'
+      @counters = NO_COUNTERS.dup
+      @last_applied_at = nil
+      # Every request that reached `Middleware#call` on a path that is not the
+      # admin surface, whether or not a rule matched. Counted separately from
+      # `considered` on purpose: `considered` answers "did a rule match", and
+      # the question here is the one before it, "was I in the path at all".
+      @requests = 0
+      # `nil` until a push has proved it one way or the other by being written
+      # or failing to be. Three states rather than two, and the third one is the
+      # point: an install that has been pushed nothing has not *failed* to
+      # persist, and reporting it as a fault would fire on every correct install
+      # on its first day. §20.1 rule 3 cuts both ways — nothing examined is not
+      # health, and it is not a failure either. Modelled on
+      # `middleware/php/src/Store.php`'s `$persisted`, which is `?bool` for the
+      # same reason.
+      @persisted = nil
+      # Injected so the time-dependent half of `status` is testable without
+      # sleeping. Every reading of the clock in this class goes through it.
+      @clock = clock || -> { Time.now.to_f }
+      @started_at = @clock.call
+      @checked_at = nil
+      @cache_fingerprint = nil
+
+      # A manifest committed to the repository wins at boot and is then
+      # overwritten by the first push. It is the mode for a client whose
+      # security review forbids an inbound endpoint — honestly the worse
+      # product, since it needs a deploy per change, but it must not be worse
+      # than nothing.
+      [[manifest_file, 'file'], [cache_file, 'push']].each do |path, source|
+        next if path.nil? || path.to_s.empty?
+
+        begin
+          loaded = JSON.parse(File.read(path, encoding: 'UTF-8'))
+        rescue SystemCallError, IOError, JSON::ParserError, ArgumentError
+          # A corrupt cache is not a reason to fail a boot. Serving the site
+          # unmodified is always safe; refusing to start never is. `ArgumentError`
+          # is in the list because `File.read` raises it, not a JSON error, when
+          # the file is not valid UTF-8.
+          next
+        end
+        next unless self.class.manifest?(loaded)
+
+        @current = loaded
+        @source = source
+        # **The file's own mtime, not `now`.** `age` is the field an operator
+        # reads to decide whether last night's push landed, and setting it to
+        # the moment this process *looked at* a file makes it answer "how long
+        # since I booted" — so a Rails app redeployed after four weeks with no
+        # push reports `age: 0` for rules that last changed 28 days ago, and
+        # somebody checking whether a push arrived concludes it did. Named and
+        # fixed first in `middleware/php/src/Store.php:294-304` ("Both shipped
+        # stores set `updated_at` to the moment they loaded the file"); Node and
+        # Python still have it. `nil` when the file's mtime cannot be read,
+        # which `status` already renders as `age: null` — unknown, rather than
+        # zero.
+        @updated_at = mtime_of(path)
+      end
+
+      # The boot read counts as a check: the file was just looked at, so
+      # `reload_if_stale` has nothing to learn from it for another interval.
+      # Without this the first request of every process re-reads and re-parses a
+      # file it has already read, and — worse for the suite — the throttle would
+      # be untestable, because its first call would always be the one that acts.
+      @checked_at = @started_at
+      @cache_fingerprint = fingerprint_of(@cache_file)
+    end
+
+    def self.manifest?(value)
+      value.is_a?(Hash) && value['version'].is_a?(String) && value['pages'].is_a?(Hash)
+    end
+
+    def get
+      @current
+    end
+
+    def rule_for(url)
+      rule = @current['pages']
+      return nil unless rule.is_a?(Hash)
+
+      found = rule[Rewrite.normalise_path(url)]
+      found.is_a?(Hash) ? found : nil
+    end
+
+    def redirect_for(url)
+      path = Rewrite.normalise_path(url)
+      list = @current['redirects']
+      return nil unless list.is_a?(Array)
+
+      list.find do |rule|
+        # Exact match only — no prefixes and no patterns. A rule that
+        # accidentally matched a subtree would send a whole section to one URL,
+        # and there is no undo for visitors who already followed it.
+        #
+        # **Both ends must be Strings, and `to` must not be empty.** This was
+        # `Rewrite.normalise_path(rule['from'].to_s)` alone, and the `.to_s` did
+        # two things silently: `{"from":null,"to":"/x"}` normalised to `"/"` and
+        # 301'd the *homepage*, and `{"from":"/old","to":null}` reached the
+        # middleware and was served as a 301 with an empty `location` — a dead
+        # page where the application would have rendered a working one, counted
+        # as a healthy `redirect`. Python raises on `str(redirect["to"])` and
+        # Node throws `ERR_HTTP_INVALID_HEADER_VALUE`; both fail loudly, and
+        # this failed silently in the one direction §3 rule 7 forbids. Matched
+        # to `middleware/php/src/Store.php:333-356`, which drops the entry and
+        # serves the page — the closed direction here is "serve the page
+        # unchanged", never "redirect to nowhere". Dropping the entry rather
+        # than the list is the same shape the engine's own fixture pins for a
+        # malformed `hreflang` row.
+        next false unless rule.is_a?(Hash)
+
+        from = rule['from']
+        to = rule['to']
+        next false unless from.is_a?(String) && to.is_a?(String) && !to.empty?
+
+        Rewrite.normalise_path(from) == path
+      end
+    end
+
+    # Store a pushed manifest and return its version. Raises on rubbish.
+    def replace(payload)
+      unless self.class.manifest?(payload)
+        raise ArgumentError, 'not a manifest: expected {version, pages}'
+      end
+
+      @lock.synchronize do
+        @current = payload
+        @updated_at = @clock.call
+        @source = 'push'
+        write_cache(payload)
+      end
+      payload['version'].to_s
+    end
+
+    # Count one response, by the marker it was served with.
+    #
+    # Takes the header value rather than a symbol so exactly one place decides
+    # what a response was: the middleware sets the header and passes the same
+    # string here. A second classification would eventually disagree with the
+    # header, and the header is what a customer greps for.
+    def record(marker)
+      @lock.synchronize do
+        @counters[:considered] += 1 if CONSIDERED.include?(marker)
+        key = COUNTER_KEYS[marker]
+        next if key.nil?
+
+        @counters[key] += 1
+        @last_applied_at = @clock.call if marker == '1'
+      end
+    end
+
+    # One request arrived on a path that is not the admin surface.
+    #
+    # **Not called for `/__findxpand/status`**, and that is the whole point: a
+    # probe that satisfies its own question is an auditor that cannot fail
+    # (§20.1 rule 3). If asking whether we have ever been in the request path
+    # counted as having been in it, the answer would be yes from the first poll
+    # on a middleware mounted where no page ever goes.
+    #
+    # **It is every non-admin request, not every page request**, and the README
+    # said the latter until 2 Sep 2026. An asset, a favicon, an API call or a
+    # load-balancer probe moves this counter, so one `GET /api/health` clears
+    # `NEVER_IN_REQUEST_PATH` permanently on a middleware mounted inside a `map
+    # '/api'` block that no page will ever reach. That is why it is the weakest
+    # of the three reach verdicts and why `unmatched` exists: this one answers
+    # "was I in a request path", and `unmatched` answers "was I in the one the
+    # pages go down".
+    def saw_request
+      @lock.synchronize { @requests += 1 }
+    end
+
+    # One request reached us on a path the manifest does not name.
+    #
+    # Separate from `record` rather than a marker string through it, because
+    # `record` takes the value of the header the response was served with and
+    # this response is served with no header at all — we hand the request to the
+    # application before it produces one. Passing a marker no header ever
+    # carries would break the one thing `record`'s doc promises: that a customer
+    # can grep the header value and find the counter it moved. Matched to
+    # `middleware/node/src/manifest.ts:274-284`, which says the same thing about
+    # the same counter.
+    def miss
+      @lock.synchronize { @counters[:unmatched] += 1 }
+    end
+
+    # Adopt a manifest another worker was pushed, if there is one.
+    #
+    # Called once per request from the middleware. See `RELOAD_INTERVAL_S` for
+    # why this exists at all; everything here is deliberately silent, because a
+    # cache file that has been deleted, is being written, or was written by a
+    # different version of this gem is not a reason to stop serving pages.
+    def reload_if_stale
+      return if @cache_file.nil? || @cache_file.to_s.empty?
+
+      now = @clock.call
+      return if !@checked_at.nil? && (now - @checked_at) < RELOAD_INTERVAL_S
+
+      @checked_at = now
+      fingerprint = fingerprint_of(@cache_file)
+      return if fingerprint.nil? || fingerprint == @cache_fingerprint
+
+      @cache_fingerprint = fingerprint
+      begin
+        loaded = JSON.parse(File.read(@cache_file.to_s, encoding: 'UTF-8'))
+      rescue SystemCallError, IOError, JSON::ParserError, ArgumentError
+        return
+      end
+      return unless self.class.manifest?(loaded)
+      # Our own write, or a re-read of what we already serve. `updated_at` is
+      # left alone in that case, so `age` keeps meaning "when did these rules
+      # change" rather than "when did we last look at a file".
+      return if loaded['version'] == @current['version']
+
+      @lock.synchronize do
+        @current = loaded
+        # The mtime we just stat'ed, for the same reason as at boot: this is
+        # when the *sibling* wrote these rules, and `now` is when this worker
+        # happened to notice. On a forking server every worker adopts at a
+        # different moment, so `now` would have four workers reporting four
+        # different ages for one push.
+        @updated_at = fingerprint[0]
+        @source = 'push'
+      end
+    end
+
+    def status
+      now = @clock.call
+      pages = @current['pages'].is_a?(Hash) ? @current['pages'].size : 0
+      redirects = @current['redirects'].is_a?(Array) ? @current['redirects'].size : 0
+      counters = @counters.dup
+      has_rules = pages.positive? || redirects.positive?
+      # The shared verdict first, always, and this package's own only when that
+      # one has nothing to say. Same order as
+      # `middleware/php/src/Store.php:743-747`.
+      reason = Degraded.reason(counters, has_rules)
+      reach = reach_reason(counters, has_rules, now)
+      reason = reach if reason.empty?
+
+      {
+        'ok' => true,
+        'version' => @current['version'].to_s,
+        'pages' => pages,
+        'redirects' => redirects,
+        'age' => @updated_at.nil? ? nil : (now - @updated_at).round,
+        'source' => @source,
+        'counters' => counters.transform_keys(&:to_s),
+        'requests_seen' => @requests,
+        'uptime' => (now - @started_at).round,
+        'applied_age' => @last_applied_at.nil? ? nil : (now - @last_applied_at).round,
+        'degraded' => !reason.empty?,
+        'degraded_reason' => reason,
+        # `true` a push was stored, `false` a push was lost, `nil` nothing has
+        # been pushed here yet. Reported rather than folded into `degraded`
+        # alone, because "we cannot persist" and "we have not been asked to yet"
+        # are different answers and a monitor should be able to see which.
+        'persisted' => @persisted,
+        # The reach verdict on its own, whether or not it is the one `degraded`
+        # is reporting. Additive, like PHP's `reach_reason` key: without it, a
+        # process that is both mounted behind compression *and* unable to
+        # persist shows only the first, and the second disappears until the
+        # first is fixed.
+        'reach_reason' => reach,
+        'manifest' => @current
+      }
+    end
+
+    # What only this package can answer, asked after the shared verdict.
+    #
+    # Every branch reports an observation. `@persisted == false` means a push was
+    # taken and a write was attempted or had nowhere to go; `unmatched` past
+    # `KEYS_MATCH_NOTHING_AFTER` with `considered` still at zero means requests
+    # arrived and the manifest refused all of them; `@requests.zero?` past
+    # `NEVER_SEEN_AFTER_S` means nothing has arrived at all for longer than a boot
+    # takes. None of them is inferred from configuration, and all of them are
+    # silent while there is nothing to report — `''` here means *not examined*,
+    # exactly as it does in the shared function.
+    #
+    # The two counting verdicts share the one-minute window, and that is
+    # deliberate: both of them are "this process has been running long enough
+    # that its silence means something", and a process thirty seconds into a
+    # deploy has not. Paging somebody on every deploy is how an alert stops being
+    # read.
+    def reach_reason(counters, has_rules, now)
+      return PUSH_NOT_PERSISTED if @persisted == false
+
+      settled = (now - @started_at) > NEVER_SEEN_AFTER_S
+      unmatched = Degraded.count(counters, :unmatched)
+      if has_rules && settled && Degraded.count(counters, :considered).zero? &&
+         unmatched >= KEYS_MATCH_NOTHING_AFTER
+        return format(KEYS_MATCH_NOTHING, count: unmatched)
+      end
+      return NEVER_IN_REQUEST_PATH if @requests.zero? && settled
+
+      ''
+    end
+
+    private
+
+    # `[mtime, size]` for a file, or nil when there is not one to look at.
+    #
+    # Two signals rather than one because `mtime` has one-second granularity on
+    # some filesystems, and a size is free. Neither is a hash of the content:
+    # reading the file to decide whether to read the file is the loop this is
+    # here to avoid.
+    def fingerprint_of(path)
+      return nil if path.nil? || path.to_s.empty?
+
+      stat = File.stat(path.to_s)
+      [stat.mtime.to_f, stat.size]
+    rescue SystemCallError
+      nil
+    end
+
+    # The file's mtime as a Float, or nil when there is not one to read.
+    def mtime_of(path)
+      stat = fingerprint_of(path)
+      stat.nil? ? nil : stat[0]
+    end
+
+    def write_cache(payload)
+      if @cache_file.nil? || @cache_file.to_s.empty?
+        # Not silence. A push we cannot keep is a push that is lost at the next
+        # restart and that never reaches the other workers, and `/status` said
+        # nothing about it until 2 Sep 2026 — the §20.1 rule 3 failure at its
+        # most expensive, since the engine reads this manifest back before
+        # merging the next fix. Recorded here, reported by `reach_reason`.
+        @persisted = false
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(@cache_file.to_s))
+      write_atomic(@cache_file.to_s, JSON.generate(payload))
+      # Our own write, recorded so `reload_if_stale` does not read it straight
+      # back on the next request and call it somebody else's push.
+      @cache_fingerprint = fingerprint_of(@cache_file)
+      @persisted = true
+    rescue SystemCallError, IOError
+      # Kept in memory regardless. An unwritable cache costs the rules on the
+      # next restart; refusing the push costs them now. Recorded as a failure to
+      # persist, so the loss is reported instead of being invisible.
+      @persisted = false
+      nil
+    end
+
+    # Write to a temporary file in the same directory, then rename onto it.
+    #
+    # `File.write` truncates and rewrites in place, and this is the only one of
+    # the four packages that reads its own cache file from *other processes* on
+    # the request path — `reload_if_stale`, up to once a second per worker. A
+    # sibling that stats the file inside the truncation window sees `[T, 0]`,
+    # stores that as its fingerprint, reads `""`, and defers adoption until the
+    # next stat differs from it; on a filesystem with coarse mtime granularity
+    # that is a wrong answer rather than a one-second delay. `rename` is atomic
+    # within a filesystem on both POSIX and Windows, so a reader sees either the
+    # old file or the new one and never a half-written one. The PHP package
+    # already does this and named it (`middleware/php/src/Store.php:1011-1032`);
+    # this is the same fix, not a second design (§20.1 rule 2).
+    #
+    # The pid is in the temporary name because the whole reason this file exists
+    # is that several forked workers share it, and two of them writing
+    # `manifest.json.tmp` at once would rename each other's half-written bytes
+    # into place. Within one process `replace` holds the lock, so there is no
+    # second writer to collide with.
+    def write_atomic(path, body)
+      temporary = "#{path}.#{Process.pid}.tmp"
+      begin
+        File.write(temporary, body, encoding: 'UTF-8')
+        File.rename(temporary, path)
+      ensure
+        begin
+          File.unlink(temporary) if File.exist?(temporary)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end