pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/finalizers.rb

@@ -1,54 +1,44 @@
 # frozen_string_literal: true
 
 module Pikuri
-  # Process-global teardown registry: one +at_exit+ for the whole
-  # process, with everything that owns a resource needing orderly
-  # shutdown (agents, {VectorDb::Server::Chroma}, future background
-  # workers) registering here instead of growing its own +at_exit+.
-  # It is {Agent#on_close} promoted from per-agent to per-process —
-  # the same LIFO + per-handler-rescue + idempotent shape, one level
-  # up.
+  # Process-global teardown registry: one +at_exit+ for the whole process,
+  # with everything owning a resource that needs orderly shutdown (agents,
+  # {VectorDb::Server::Chroma}, background workers) registering here instead of
+  # growing its own +at_exit+. {Agent#on_close} promoted per-agent → per-process
+  # — the same LIFO + per-handler-rescue + idempotent shape.
   #
   # == Why one chokepoint
   #
-  # Independent +at_exit+ hooks fire in an order decided by file load
-  # order, which is invisible and fragile. Routing every teardown
-  # through one registry makes the order explicit and controllable:
-  # the SIGTERM-the-strays backstop ({Subprocess.cleanup!}) registers
-  # at *load* time, so it sits at the bottom of the LIFO stack and runs
-  # *last* — after agents and servers (which register at *construction*
-  # time) have closed gracefully, while the subprocess machinery they
-  # shell out to during close (e.g. {VectorDb::Server::Chroma#close}'s
-  # +docker stop+) is still live.
+  # Independent +at_exit+ hooks fire in file-load order — invisible and fragile.
+  # One registry makes the order explicit: the SIGTERM-the-strays backstop
+  # ({Subprocess.cleanup!}) registers at *load* time, so it sits at the bottom
+  # of the LIFO stack and runs *last* — after agents and servers (registered at
+  # *construction* time) close gracefully, while the subprocess machinery they
+  # shell out to during close (a +docker stop+) is still live.
   #
   # == Contract
   #
-  # A registrant MUST respond to +#close+, and +#close+ MUST be
-  # idempotent and tolerant of running at process exit — the host may
-  # also have closed it explicitly earlier. Pass a block instead for
-  # teardown that has no natural +#close+ (e.g.
-  # +Finalizers.register { Pikuri::Subprocess.cleanup! }+).
+  # A registrant MUST respond to +#close+, idempotent and tolerant of running at
+  # exit (the host may have closed it earlier). Pass a block instead for
+  # teardown with no natural +#close+
+  # (+Finalizers.register { Pikuri::Subprocess.cleanup! }+).
   #
   # == Order: LIFO
   #
-  # Last registered, first closed — Ruby +ensure+ semantics. A
-  # registrant that depends on an earlier one (a background indexer
-  # writing into {VectorDb::Server::Chroma}) is registered later and so
-  # tears down first. Registration order is therefore dependency order;
-  # register the dependency before its dependents.
+  # Last registered, first closed. A registrant depending on an earlier one (a
+  # background indexer writing into {VectorDb::Server::Chroma}) registers later
+  # and tears down first — registration order is dependency order.
   #
   # == Errors are contained
   #
-  # Each +#close+ runs inside its own +rescue+: a raise is logged via
-  # {Pikuri.logger_for} and the sweep continues, so one botched
-  # teardown can't strand the rest. {.run!} drains the registry, so a
-  # second call (an explicit one, then the +at_exit+) closes nothing.
+  # Each +#close+ runs in its own +rescue+ (a raise is logged, the sweep
+  # continues). {.run!} drains the registry, so a second call closes nothing.
   module Finalizers
     # @return [Logger] subsystem logger for contained teardown failures.
     LOGGER = Pikuri.logger_for('Finalizers')
 
     # Adapts a teardown block to the +#close+ protocol, so a block and a
-    # closeable object can share one registry.
+    # closeable share one registry.
     Closer = Struct.new(:block) do
       # @return [void]
       def close
@@ -60,17 +50,14 @@ module Pikuri
     @mutex      = Mutex.new
 
     class << self
-      # Register a closeable (or a block) to be torn down at process
-      # exit. Returns the registered handle so the caller can later
-      # {.unregister} it — a resource closed explicitly before exit
-      # should drop out so it can be garbage-collected rather than
-      # pinned alive until the process dies.
+      # Register a closeable (or a block) to tear down at exit. Returns the
+      # handle so the caller can later {.unregister} it — a resource closed
+      # explicitly before exit should drop out to be GC'd, not pinned alive.
       #
-      # @param closeable [#close, nil] resource to close at exit; omit
-      #   when passing a block
-      # @yield teardown to run at exit, for resources with no +#close+
-      # @return [#close] the registered handle — the object itself, or
-      #   the {Closer} wrapping the block; pass it to {.unregister}
+      # @param closeable [#close, nil] resource to close; omit when passing a block
+      # @yield teardown for resources with no +#close+
+      # @return [#close] the registered handle (the object, or the {Closer}
+      #   wrapping the block); pass to {.unregister}
       # @raise [ArgumentError] if neither an object nor a block is given
       def register(closeable = nil, &block)
         unless closeable || block
@@ -82,8 +69,7 @@ module Pikuri
         handle
       end
 
-      # Drop a previously-registered handle. Idempotent — unregistering
-      # something already gone (or never registered) is a no-op.
+      # Drop a previously-registered handle. Idempotent.
       #
       # @param handle [#close] the value returned by {.register}
       # @return [void]
@@ -92,10 +78,9 @@ module Pikuri
         nil
       end
 
-      # Close every registrant in LIFO order, each guarded by its own
-      # +rescue+. Wired to +at_exit+ at the bottom of this file.
-      # Draining the registry under the lock makes a repeat call a
-      # no-op and keeps it safe against a concurrent caller.
+      # Close every registrant in LIFO order, each guarded by its own +rescue+.
+      # Wired to +at_exit+ below. Draining under the lock makes a repeat call a
+      # no-op and stays safe against a concurrent caller.
       #
       # @return [void]
       def run!

data/lib/pikuri/paths.rb

@@ -1,23 +1,35 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'tmpdir'
+require 'fileutils'
 
 module Pikuri
-  # Standardized on-disk locations for pikuri's local state. Centralizes
-  # the XDG resolution so every component that caches to disk roots under
-  # one place instead of each re-deriving it — currently
-  # {Pikuri::VectorDb::Server::Chroma} (its corpus volume) and
-  # {Pikuri::Memory::Mem0Server} (its mem0 checkout + data volume).
+  # Standardized on-disk locations for pikuri's local state, centralizing XDG
+  # resolution so every disk-caching component roots under one place instead of
+  # re-deriving it. The load-bearing distinction is {.cache} (shared across all
+  # pikuri processes, persistent) vs. {.new_temp} (private to this process,
+  # ephemeral) — reach for the wrong one and two concurrent processes clobber
+  # each other's scratch.
   module Paths
-    # Pikuri's cache root: +$XDG_CACHE_HOME/pikuri+ when +XDG_CACHE_HOME+
-    # is set and non-empty, else +~/.cache/pikuri+.
+    # +temp-*+ umbrellas older than this are reaped by {.sweep_stale_temps!} at
+    # core load — generous enough not to disturb a long-lived process in another
+    # shell, tight enough that one killed last week doesn't leak forever.
     #
-    # A method, not a frozen constant, on purpose: a constant would
-    # snapshot +XDG_CACHE_HOME+ at +require+ time, which breaks
-    # env-stubbing in tests and ignores a runtime change in a long-lived
-    # process. The directory is *not* created — callers +mkdir_p+ the
-    # subdirectory they need (e.g. +Paths.cache.join('chroma')+,
-    # +Paths.cache.join('mem0')+).
+    # @return [Integer] seconds
+    TEMP_STALE_SECONDS = 7 * 24 * 60 * 60
+
+    # Pikuri's cache root: +$XDG_CACHE_HOME/pikuri+ or +~/.cache/pikuri+.
+    #
+    # Shared across ALL pikuri processes and PERSISTENT (survives exit) — the
+    # home for state meant to be reused: the URL cache, mem0 / Qdrant / Chroma
+    # server data. For scratch private to *this* process that should vanish when
+    # it exits, use {.new_temp}; reaching for +cache+ + a fixed subdir is how two
+    # concurrent processes end up overwriting each other's files.
+    #
+    # A method, not a constant: a constant would snapshot +XDG_CACHE_HOME+ at
+    # +require+ time, breaking env-stubbing in tests and a runtime change. Not
+    # created — callers +mkdir_p+ the subdir they need.
     #
     # @return [Pathname] the +<cache home>/pikuri+ directory
     def self.cache
@@ -25,5 +37,84 @@ module Pikuri
       home = File.expand_path('~/.cache') if home.nil? || home.empty?
       Pathname.new(home).join('pikuri')
     end
+
+    # A fresh scratch dir private to this process, reaped at exit via
+    # {Pikuri::Finalizers} (and stale-swept by {.sweep_stale_temps!} for strays a
+    # crash leaves behind). Mint one per concurrent-safe scratch need and hold
+    # the result:
+    #
+    #   dir  = Paths.new_temp                       # ~/.cache/pikuri/temp-XXXX/
+    #   snap = Snapshot.new(source: db, dir: dir)   # can't collide with another process
+    #
+    # Minted IN HOME under {.cache} — never +/tmp+ — for two concrete reasons: a
+    # +cp --reflink=auto+ copy shares extents only on the source's filesystem
+    # (the copied DB lives under +$HOME+), and the bubblewrap sandbox binds its
+    # scratch at +/tmp+ inside, so an umbrella already under +/tmp+ would bind on
+    # top of itself.
+    #
+    # A factory — a *new* dir each call (hence +new_+, not a memoized accessor
+    # like {.cache}); a caller memoizes if it wants one stable dir, but per
+    # *consumer*, not per process. Memoizing one at process scope and handing it
+    # to several agents puts two writers on one path — the collision this exists
+    # to prevent, moved inside the process.
+    #
+    # @return [Pathname] absolute, symlink-resolved path of the freshly-made dir
+    def self.new_temp
+      FileUtils.mkdir_p(cache)
+      path = Pathname.new(Dir.mktmpdir('temp-', cache)).realpath
+      Pikuri::Finalizers.register { FileUtils.remove_entry(path.to_s) if path.exist? }
+      path
+    end
+
+    # Reap +temp-*+ umbrellas under {.cache} older than {TEMP_STALE_SECONDS}.
+    # Called once at core load (so every binary sweeps, regardless of which gems
+    # it wires) — the net for a process killed before its {Pikuri::Finalizers}
+    # reap could fire. Failures are swallowed (best-effort; the Finalizers
+    # removal is the load-bearing path), and recent dirs are left for concurrent
+    # processes.
+    #
+    # @return [void]
+    def self.sweep_stale_temps!
+      return unless File.directory?(cache)
+
+      cutoff = Time.now - TEMP_STALE_SECONDS
+      Dir.children(cache).each do |entry|
+        next unless entry.start_with?('temp-')
+
+        path = File.join(cache, entry)
+        next unless File.directory?(path)
+        next if File.mtime(path) > cutoff
+
+        FileUtils.remove_entry(path)
+      rescue StandardError
+        # best-effort sweep; never block the host on dead state
+      end
+    end
+
+    # Pikuri's config root: +$XDG_CONFIG_HOME/pikuri+ or +~/.config/pikuri+.
+    # Home for user-owned, hand-edited config (the OS helper's +MACHINE.md+).
+    #
+    # A method for the same reason as {.cache}. Not created — config is
+    # user-owned, so callers +mkdir_p+ only when writing.
+    #
+    # @return [Pathname] the +<config home>/pikuri+ directory
+    def self.config
+      home = ENV['XDG_CONFIG_HOME']
+      home = File.expand_path('~/.config') if home.nil? || home.empty?
+      Pathname.new(home).join('pikuri')
+    end
+
+    # Pikuri's state root: +$XDG_STATE_HOME/pikuri+ or +~/.local/state/pikuri+.
+    # Created automatically. For state that persists across restarts but isn't
+    # portable enough for XDG_DATA_HOME (logs, history, layout).
+    #
+    # @return [Pathname] the +<state home>/pikuri+ directory
+    def self.state
+      state = ENV['XDG_STATE_HOME']
+      state = File.expand_path('~/.local/state') if state.nil? || state.empty?
+      state = Pathname.new(state).join('pikuri')
+      FileUtils.mkdir_p(state.to_path)
+      state
+    end
   end
 end

data/lib/pikuri/ruby_llm_patches.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module Pikuri
+  # Local corrections to ruby_llm, applied at load time, carried until the fix
+  # ships upstream. Each patch pins us to a ruby_llm internal's private shape, so
+  # it's a liability: small, self-contained, tied to a tracked upstream issue so
+  # we know when to delete it. Reopening a third-party class is last resort —
+  # here only because the defect is on the live chat path and the release cadence
+  # isn't ours. Patching rather than dropping the dependency is the standing
+  # policy — `DECISIONS.md` +D_keep_ruby_llm+.
+  #
+  # == The streaming error-parse crash (ruby_llm #837)
+  #
+  # {https://github.com/crmne/ruby_llm/issues/837}
+  #
+  # On a *streaming* turn, a non-200 response whose body parses to a non-Hash
+  # JSON value crashes ruby_llm 1.16.0 with +TypeError: String does not have
+  # #dig+ at +providers/openai/streaming.rb:43+, instead of surfacing the
+  # endpoint's error. Two bodies trigger it, both because the method assumes a
+  # nested object to +.dig+:
+  #
+  # 1. A bare JSON string. The guard +return unless error_data['error']+ is
+  #    meant as key-presence, but on a +String+ that's substring matching, so a
+  #    body containing "error" slips through into +.dig+.
+  # 2. A +{"error": "<message>"}+ body where +error+ is a string value
+  #    (xAI/Grok), not an object: the guard passes, then
+  #    +error_data.dig('error', 'type')+ calls +String#dig+ — same +TypeError+.
+  #
+  # The non-streaming path already handles both (cases on Hash/Array/else,
+  # short-circuits a string +error+). This mirrors that: never +.dig+ a non-Hash,
+  # hand a non-typed error up as the message with a +nil+ status so ruby_llm's
+  # +build_stream_error_response+ falls back to the real HTTP status.
+  #
+  # Redefined whole (not +prepend+ + +super+) because it's a small self-contained
+  # +module_function+ with no state — faithful reproduction plus the guard is
+  # clearer than wrapping the buggy original. Re-running +module_function+
+  # replaces both the module method and the private copy the provider gets via
+  # +include+.
+  #
+  # == When to delete this file
+  #
+  # ruby_llm main already carries an equivalent fix, in a module renamed to
+  # +RubyLLM::Protocols::ChatCompletions::Streaming+ — so the next release past
+  # 1.16.0 obsoletes the patch *and* moves its target. The load-time guard below
+  # turns that into a boot failure naming this file; delete it and its spec then.
+  module RubyLlmPatches
+    module_function
+
+    # @return [Boolean] +true+ once the patches below have been applied; a
+    #   literal, kept honest by the load-time guard that raises if the target
+    #   module has moved out from under it
+    def applied? = true
+  end
+end
+
+# Reopening a module that has moved silently defines a fresh empty one: the
+# patch would stop applying, the bug would return, and nothing — not even
+# {Pikuri::RubyLlmPatches.applied?} — would notice. Fail at boot instead.
+unless defined?(RubyLLM::Providers::OpenAI::Streaming) &&
+       RubyLLM::Providers::OpenAI::Streaming.respond_to?(:parse_streaming_error)
+  raise "RubyLLM::Providers::OpenAI::Streaming.parse_streaming_error is gone from ruby_llm " \
+        "#{RubyLLM::VERSION} — the streaming error-parse patch no longer applies. It is fixed " \
+        'upstream: delete pikuri-core/lib/pikuri/ruby_llm_patches.rb and its spec (ruby_llm #837).'
+end
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      module Streaming
+        # Parse a streaming error body into a +[status, message]+ pair,
+        # tolerating a non-Hash parsed body. See
+        # {Pikuri::RubyLlmPatches} for why this override exists and when
+        # to remove it (ruby_llm #837).
+        #
+        # @param data [String] the JSON error body as received
+        # @return [Array(Integer, nil), String] a +[status, message]+
+        #   pair; +status+ is +nil+ when the body carries no error type,
+        #   deferring classification to the response's HTTP status
+        def parse_streaming_error(data)
+          error_data = JSON.parse(data)
+          # Non-Hash body (a bare JSON string/number/array): no structured
+          # error to read — surface it as the message, defer status.
+          return [nil, error_data.to_s] unless error_data.is_a?(Hash)
+
+          error = error_data['error']
+          return [nil, error_data.to_s] unless error
+          # A string error value (xAI/Grok's {"error": "..."}) has no type
+          # field — hand it up as-is, defer status to the HTTP response.
+          return [nil, error] if error.is_a?(String)
+
+          case error['type']
+          when 'server_error'
+            [500, error['message']]
+          when 'rate_limit_exceeded', 'insufficient_quota'
+            [429, error['message']]
+          else
+            [400, error['message']]
+          end
+        end
+        module_function :parse_streaming_error
+      end
+    end
+  end
+end

data/lib/pikuri/sanitizer.rb

@@ -1,73 +1,53 @@
 # frozen_string_literal: true
 
 module Pikuri
-  # Renders attacker-controlled text safe to display, and reports *why*
-  # it was unsafe.
+  # Renders attacker-controlled text safe to display, and reports *why* it was
+  # unsafe.
   #
-  # Every string an LLM composes is untrusted: a bash command, a tool
-  # observation echoed back to the user, a description it wrote for a
-  # confirmation prompt. A model that is broken — or, far more likely,
-  # being driven by a prompt injection — can embed bytes that a terminal
-  # acts on rather than prints: a carriage return that overwrites the
-  # line the user just read, an ESC that recolors or repositions, a
-  # backspace that erases, a bidirectional override that reorders text so
-  # it reads differently than it runs, a zero-width character that hides
-  # in plain sight, or a Cyrillic +а+ masquerading as a Latin +a+. The
-  # whole point of a confirmation prompt collapses if the bytes the user
-  # approves are not the bytes that execute.
+  # Every string an LLM composes is untrusted (a bash command, a tool
+  # observation echoed to the user, a confirmation-prompt description). A model
+  # — usually one being prompt-injected — can embed bytes a terminal *acts on*
+  # rather than prints: a CR that overwrites the line just read, an ESC that
+  # recolors/repositions, a backspace that erases, a bidi override that reorders
+  # text so it reads differently than it runs, a zero-width char, or a Cyrillic
+  # +а+ posing as Latin +a+. A confirmation prompt is worthless if the bytes the
+  # user approves aren't the bytes that execute.
   #
-  # {.sanitize} is the one chrome-independent primitive every renderer
-  # (terminal, TUI, web) routes through. It does two things and returns
-  # both as a {Result}:
+  # {.sanitize} is the one chrome-independent primitive every renderer routes
+  # through, returning a {Result}:
   #
-  # 1. *Neutralize* — make the dangerous bytes visible without changing
-  #    structure. Control bytes become +\xNN+, bidi/zero-width codepoints
-  #    become +\u{NNNN}+, tab becomes +\t+. Newlines are preserved
-  #    (multi-line commands are normal). This is *faithful, not
-  #    beautifying*: it never collapses runs of whitespace or rewrites a
-  #    tab to a space, because the user must see exactly what they are
-  #    approving — a Makefile's leading tab stays visibly a tab. A web
-  #    chrome composes +html_escape(sanitize(s).text)+; the HTML layer is
-  #    the caller's, not ours.
-  # 2. *Warn* — return a {Warning} per category detected, each a semantic
-  #    record (kind + offending tokens + a plain-English explanation).
-  #    Presentation is the chrome's: a terminal renders these bold yellow,
-  #    a web client a banner. The {Warning} carries no color or markup.
+  # 1. *Neutralize* — make dangerous bytes visible without changing structure:
+  #    control bytes → +\xNN+, bidi/zero-width → +\u{NNNN}+, tab → +\t+;
+  #    newlines preserved. *Faithful, not beautifying* — it never collapses
+  #    whitespace or rewrites a tab, because the user must see exactly what they
+  #    approve (a Makefile's leading tab stays a tab). A web chrome adds
+  #    +html_escape+ on top; the HTML layer is the caller's.
+  # 2. *Warn* — one {Warning} per category detected (kind + offending tokens +
+  #    plain-English explanation). Presentation is the chrome's.
   #
   # == Scope (deliberately closed)
   #
-  # Detection covers the *invisibility / cursor-control / reordering*
-  # attack classes completely, because each is a finite, enumerable set
-  # of codepoints: C0 controls, C1 controls (a second ANSI introducer on
-  # some emulators), DEL, the bidi overrides, and the zero-width
-  # characters. On top of that, {.sanitize} flags *mixed-script tokens* —
-  # a single word combining letters from Latin + Cyrillic + Greek, which
-  # is the signature of a homoglyph spoof and has near-zero false
-  # positives on real text (humans do not weld two alphabets inside one
-  # word; +café+ is all-Latin, +Москва+ all-Cyrillic, only +Pаypal+ mixes).
+  # Detection is complete on the *invisibility / cursor-control / reordering*
+  # classes, each a finite codepoint set: C0/C1 controls, DEL, bidi overrides,
+  # zero-width chars. Plus *mixed-script tokens* — one word welding Latin +
+  # Cyrillic + Greek, the homoglyph-spoof signature, near-zero false positives
+  # (+café+ all-Latin, +Москва+ all-Cyrillic, only +Pаypal+ mixes).
   #
-  # Two confusable classes are explicitly *out of scope*, because
-  # detecting them needs Unicode confusables tables and produces heavy
-  # false positives on legitimate multilingual text:
-  #
-  # * *Whole-script* homoglyphs — an entirely-Cyrillic string that merely
-  #   looks Latin (no mixing to detect).
-  # * *Single-symbol* confusables — the Greek question mark +;+ (U+037E)
-  #   that looks like a semicolon, full-width forms, the division slash.
-  #
-  # "Solid" here means complete on the classes above, not exhaustive over
-  # all of Unicode.
+  # Two confusable classes are *out of scope* — detecting them needs Unicode
+  # confusables tables and heavy false positives on legitimate multilingual
+  # text: *whole-script* homoglyphs (an all-Cyrillic string that looks Latin,
+  # no mixing to detect) and *single-symbol* confusables (the Greek +;+ U+037E,
+  # full-width forms). "Solid" means complete on the classes above, not
+  # exhaustive over Unicode.
   module Sanitizer
-    # One reason a piece of text was flagged, ready for a chrome to
-    # render however it surfaces warnings (bold yellow line, web banner).
+    # One reason a piece of text was flagged, for a chrome to render its own way.
     #
-    # * +kind+ — a {Symbol} category: +:backspace+, +:control_bytes+,
-    #   +:bidi+, +:zero_width+, or +:mixed_script+.
-    # * +offenders+ — the distinct offending tokens, in first-seen order:
-    #   the escaped forms (+"\\x1b"+, +"\\u{202e}"+) for byte categories,
-    #   the raw tokens (+"Pаypal"+) for +:mixed_script+.
-    # * +explanation+ — a one-line, chrome-agnostic English summary of
-    #   what the bytes can do.
+    # * +kind+ — a {Symbol}: +:backspace+, +:control_bytes+, +:bidi+,
+    #   +:zero_width+, or +:mixed_script+.
+    # * +offenders+ — the distinct offending tokens, first-seen order: escaped
+    #   forms (+"\\x1b"+, +"\\u{202e}"+) for byte categories, raw tokens
+    #   (+"Pаypal"+) for +:mixed_script+.
+    # * +explanation+ — a one-line chrome-agnostic summary.
     Warning = Data.define(:kind, :offenders, :explanation)
 
     # The output of {Sanitizer.sanitize}.
@@ -84,17 +64,15 @@ module Pikuri
     # zero-width no-break space.
     ZERO_WIDTH = [0x200b, 0x200c, 0x200d, 0xfeff].freeze
 
-    # Codepoints {.sanitize} rewrites: C0 controls including tab (U+0009)
-    # but *excluding* newline (U+000A, which passes through untouched),
-    # C1 controls + DEL (U+007F–009F), the zero-width set, and the bidi
-    # overrides. Newline is the one control character a faithful render
-    # must keep, so the C0 range is split around it.
+    # Codepoints {.sanitize} rewrites: C0 controls including tab (U+0009) but
+    # *excluding* newline (U+000A, passes through), C1 + DEL (U+007F–009F), the
+    # zero-width set, and the bidi overrides. Newline is the one control a
+    # faithful render keeps, so the C0 range splits around it.
     SUSPECT = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200b-\u200d\u202a-\u202e\u2066-\u2069\ufeff]/
 
-    # The three Latin-confusable scripts whose mixing inside one token
-    # signals a homoglyph spoof. Punctuation, digits and spaces are the
-    # +Common+ script and match none of these, so they never count toward
-    # the "two distinct scripts" threshold.
+    # The three Latin-confusable scripts whose mixing inside one token signals a
+    # homoglyph spoof. Punctuation/digits/spaces are +Common+ and match none, so
+    # they never count toward the two-script threshold.
     CONFUSABLE_SCRIPTS = { 'Latin' => /\p{Latin}/, 'Cyrillic' => /\p{Cyrillic}/, 'Greek' => /\p{Greek}/ }.freeze
 
     # Neutralize +text+ for literal display and report what was flagged.