libbeachcomber 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33c71976f78100c4d66bed305d8ce20a9a3ef47887426d584a4ef57d786a8253
-  data.tar.gz: 980c0b4e878b7fc1372d5f9d543a554abcd4b2b65467ce3191dd295a08163a69
+  metadata.gz: d3c045383cb88693dccb3888f17a5dbed1d5fcea26e582898d59034095d04f98
+  data.tar.gz: 9bfa55709e0f57da1632fdba84b817836490c65c6fef75a16dd03beb0af78160
 SHA512:
-  metadata.gz: a41a648a7de7e71930635cc1881a71ddbc596ab2c4cef8a311206e8794dc392d9c724462300a44655aa32d0fa3850e918f4cad9e3cc45b9cc52dd4acaa3faea4
-  data.tar.gz: 074e44fc57027685cd2f19a36000249398ba2e2c8755825883e0e96f854bd2fdca2f551483eba3ca1a259f3bd9051a3b25f1959e781236372b2cbc098268df12
+  metadata.gz: 1fbc30c179de56aea27c151833d8a5934edc1ee5401957695a25191904b30ab6f134420b53df961b8af82bda333331de5a41176574b38ff1a1b1d37242fed6e0
+  data.tar.gz: 7951707bcabfe101803feef42ccc192dc1c434b9ff9eb2e1f95453fd60556514d759ff431d4f2552566418af12b40e0e6c95a3996465b321828e17092cf5e09d

data/lib/beachcomber/client.rb

@@ -2,268 +2,279 @@ require 'json'
 
 require_relative 'ffi'
 require_relative 'errors'
-require_relative 'result'
 require_relative 'types'
 require_relative 'watch_stream'
 
 module Beachcomber
-  DEFAULT_TIMEOUT = 0.1 # seconds (100 ms) — matches libbeachcomber's own default.
-
-  # Response-shaping helpers shared by Client and Session: the ABI's JSON
-  # payload shapes are identical regardless of which handle made the call.
-  module ResponseParsing
+  # Request-building helpers shared by Client and Session.
+  module Requests
     private
 
-    def build_result(payload)
-      Result.new(
-        ok: true,
-        data: payload['data'],
-        age_ms: (payload['age_ms'] || 0).to_i,
-        stale: payload['stale'] == true,
-        error: nil,
-      )
+    # The +options_json+ +bc_get+ and +bc_session_get+ take: the options the
+    # caller gave, +force+ when it is set and +wait+ as given; none is nil.
+    def get_options(force, wait)
+      options = {}
+      options['force'] = true if force
+      options['wait'] = wait unless wait.nil?
+      json_or_nil(options.empty? ? nil : options)
     end
 
-    def parse_hello(data)
-      HelloInfo.new(
-        protocol_version: data['protocol_version'].to_s,
-        daemon_version: data['daemon_version'].to_s,
-      )
+    def json_or_nil(value)
+      value ? JSON.generate(value) : nil
     end
+  end
 
-    def parse_cache_rows(data)
-      raise ProtocolError, 'status data is not an array' unless data.is_a?(Array)
+  # The typed shapes, built from the JSON the ABI hands on: each Struct's
+  # members, a member the ABI left out nil.
+  module Typed
+    module_function
 
-      data.map { |row| build_cache_row(row) }
+    def of(struct, json)
+      struct.new(**struct.members.to_h { |m| [m, json[m.to_s]] })
     end
 
-    def build_cache_row(row)
-      CacheRow.new(
-        provider: row['provider'].to_s,
-        field: row['field'],
-        path: row['path'],
-        value: row['value'],
-        age_ms: Integer(row['age_ms'] || 0),
-        stale: row['stale'] == true,
-        kind: row['kind'],
-        poll_interval_secs: row['poll_interval_secs'],
-        keep_alive_polls: row['keep_alive_polls'],
-        fsevents_reinstate: row['fsevents_reinstate'],
-        polls_elapsed: row['polls_elapsed'],
-        failure: row['failure'],
-        source: row['source'],
-      )
+    def cache_rows(data)
+      raise ParseError, 'status data is not an array' unless data.is_a?(Array)
+
+      data.map { |row| of(CacheRow, row) }
     end
 
-    def parse_daemon_health(data)
-      reaper = data['reaper']
-      DaemonHealth.new(
-        pid: Integer(data['pid'] || 0),
-        version: data['version'].to_s,
-        uptime_secs: Integer(data['uptime_secs'] || 0),
-        socket_path: data['socket_path'].to_s,
-        config_path: data['config_path'],
-        requests_total: Integer(data['requests_total'] || 0),
-        in_flight: Integer(data['in_flight'] || 0),
-        active_watchers: Integer(data['active_watchers'] || 0),
-        cache_entries: Integer(data['cache_entries'] || 0),
-        watch_backend: data['watch_backend'],
-        reaper: reaper && Reaper.new(
-          armed: reaper['armed'],
-          visibility: reaper['visibility'],
-          sweeps: reaper['sweeps'],
-          reaped: reaper['reaped'],
-          kill_denied: reaper['kill_denied'],
-        ),
-        verdicts: (data['verdicts'] || []).map do |v|
-          Verdict.new(level: v['level'].to_s, message: v['message'].to_s)
-        end,
-      )
+    def daemon_health(data)
+      health = of(DaemonHealth, data)
+      health.reaper = data['reaper'] && of(ReaperStatus, data['reaper'])
+      health.verdicts = (data['verdicts'] || []).map { |v| of(Verdict, v) }
+      health
     end
 
-    def parse_introspect(subject, data)
+    def introspect(subject, data)
       if subject == IntrospectSubject::DAEMON && data.is_a?(Hash)
-        IntrospectResponse.new(subject: subject, daemon: parse_daemon_health(data), other: nil)
+        IntrospectResponse.new(subject: subject, daemon: daemon_health(data), other: nil)
       else
         IntrospectResponse.new(subject: subject, daemon: nil, other: data)
       end
     end
-
-    def json_or_nil(value)
-      value ? JSON.generate(value) : nil
-    end
   end
 
   # Session holds a persistent connection to the daemon, held open by the
-  # shared library, for {#get}/{#get_with_flags}/{#put}/{#set_context}.
+  # shared library, and a directory of its own ({#set_context}) that {#get},
+  # {#put} and {#refresh} read or write at when given no directory.
   #
   # Obtain a Session via {Client#session}:
   #
   #   client.session do |s|
   #     s.set_context('/repo')
-  #     r = s.get('git.branch')
+  #     branch = s.get('git.branch')
   #   end
   #
-  # {#refresh}, {#status}, {#hello} and {#introspect} are also available for
-  # API-compatibility with the pre-ABI client, but the C ABI provides no
-  # session-scoped equivalents for them (only get/put/set_context reuse the
-  # persistent connection — see Task 3.6 of the client-ABI plan); they route
-  # through the parent Client's connection instead, one-shot per call.
+  # #status, #hello and #introspect address no directory and need no
+  # connection of their own, so they are the Client's alone.
   #
   # The underlying handle is guarded by the library's own mutex: a
   # concurrent caller on the same session gets {Beachcomber::BusyError}
   # rather than blocking or interleaving requests.
   class Session
-    include ResponseParsing
+    include Requests
 
-    def initialize(handle, client_handle)
+    def initialize(handle)
       @handle = handle
-      @client_handle = client_handle
       @closed = false
     end
 
-    # Sets the default path for subsequent {#get}/{#get_with_flags} queries
-    # on this connection.
+    # Sets this session's directory: every later {#get} that names no +cwd+,
+    # and {#put} and {#refresh} that name no path, address it. The session
+    # keeps it and sends it with each request.
     #
     # @param path [String]
     def set_context(path)
-      Beachcomber::FFI.call!(:bc_session_set_context, @handle, path)
+      Beachcomber::FFI.call!(:bc_session_set_context, handle!, path)
       nil
     end
 
-    # Reads a cached value.
+    # {Client#get} on this session's persistent connection. +cwd: nil+ is
+    # this session's directory ({#set_context}) when it has one, else the
+    # global entry.
     #
     # @param key [String] e.g. "git.branch" or "git"
-    # @param path [String, nil] optional working-directory override
-    # @return [Result]
-    def get(key, path: nil)
-      build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, 0))
+    # @param cwd [String, nil]
+    # @param env [Hash, nil] the caller's environment for `env.*` refs
+    # @param force [Boolean]
+    # @param wait [String, nil] a duration or "forever", as {Client#get}
+    # @return [Object, nil] the value, or nil on a miss
+    def get(key, cwd: nil, env: nil, force: false, wait: nil)
+      Beachcomber::FFI.call!(:bc_session_get, handle!, key, cwd, json_or_nil(env), get_options(force, wait))
     end
 
-    # Reads a cached value with protocol flags.
-    #
-    # @param key [String]
-    # @param path [String, nil]
-    # @param force [Boolean] bypass cache and recompute
-    # @param wait [Boolean] block until a fresh value is available
-    # @return [Result]
-    def get_with_flags(key, path: nil, force: false, wait: false)
-      flags = (force ? Beachcomber::FFI::GET_FORCE : 0) | (wait ? Beachcomber::FFI::GET_WAIT : 0)
-      build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, flags))
-    end
-
-    # Forces the daemon to recompute a provider/key.
+    # {Client#refresh} on this session's connection; +path: nil+ is this
+    # session's directory.
     #
     # @param key [String]
     # @param path [String, nil]
     def refresh(key, path: nil)
-      Beachcomber::FFI.call!(:bc_refresh, @client_handle, key, path)
+      Beachcomber::FFI.call!(:bc_session_refresh, handle!, key, path)
       nil
     end
 
-    # Returns cache rows from the daemon.
-    #
-    # @return [Array<CacheRow>]
-    def status
-      parse_cache_rows(Beachcomber::FFI.call!(:bc_status, @client_handle))
-    end
-
-    # Sends a hello handshake and returns server info.
-    #
-    # @return [HelloInfo]
-    def hello
-      parse_hello(Beachcomber::FFI.call!(:bc_hello, @client_handle))
-    end
-
-    # Writes a value into the daemon cache on this session's connection.
-    # +data = nil+ clears the entry.
+    # {Client#put} on this session's connection; +path: nil+ is this
+    # session's directory.
     #
     # @param key [String]
     # @param data [Object, nil]
     # @param ttl [Numeric, String, nil] time-to-live
     # @param path [String, nil]
+    # @param persist [Boolean] keep the put across a daemon restart, best effort
     # @return [nil]
-    def put(key, data = nil, ttl: nil, path: nil)
-      Beachcomber::FFI.call!(:bc_session_put, @handle, key, JSON.generate(data), ttl&.to_s, path)
+    def put(key, data, ttl: nil, path: nil, persist: false)
+      Beachcomber::FFI.call!(:bc_session_put, handle!, key, JSON.generate(data), ttl&.to_s, path, persist ? 1 : 0)
       nil
     end
 
-    # Introspects a daemon subsystem.
-    #
-    # @param subject [String] one of the IntrospectSubject constants
-    # @param duration_secs [Numeric, nil]
-    # @return [IntrospectResponse]
-    def introspect(subject, duration_secs: nil)
-      options_json = duration_secs ? JSON.generate(duration_secs: duration_secs) : nil
-      data = Beachcomber::FFI.call!(:bc_introspect, @client_handle, subject.to_s, options_json)
-      parse_introspect(subject.to_s, data)
-    end
-
     # Closes the underlying connection. Idempotent.
     def close
       return if @closed
 
       @closed = true
       Beachcomber::FFI.close_session(@handle)
+      @handle = nil
+    end
+
+    private
+
+    # The handle every operation passes on. A closed session has none, and
+    # the library must never see a freed handle, so the call fails here.
+    def handle!
+      @handle or raise IoError, 'the session is closed'
     end
   end
 
   # Client sends individual requests through the shared library, which owns
   # socket handling, framing and JSON mapping. For workloads that issue many
   # queries per invocation, use {#session} to reuse a persistent connection.
+  # It follows the SDK API table, docs/sdk-api.md.
   #
   # Examples:
   #
   #   client = Beachcomber::Client.new
-  #   result = client.get('git.branch', path: '/repo')
-  #   puts result.data if result.hit?
+  #   branch = client.get('git.branch', cwd: '/repo') # nil on a miss
+  #   client.get('git:template.branch')               # the template, unrendered
+  #   client.close
   class Client
-    include ResponseParsing
+    include Requests
 
-    # @param socket_path [String, nil] explicit socket path; library default
-    #   discovery applies when nil.
-    # @param timeout [Numeric, nil] socket read/write timeout in seconds
-    #   (default 0.1 / 100ms, matching the library's own default).
+    # Each option given is passed to +bc_client_new+ as it is; nil is not
+    # given, and the library's default applies. This SDK has no defaults of
+    # its own.
+    #
+    # @param socket_path [String, nil] explicit socket path; nil is the
+    #   library's discovery.
+    # @param timeout_ms [Integer, nil] how long one read or write on the
+    #   socket may take, in milliseconds; at least 1. nil is the library's
+    #   default (100).
+    # @param connect_timeout_ms [Integer, nil] how long connecting keeps
+    #   retrying before it gives up, in milliseconds; 0 is one attempt. nil
+    #   is the library's default (1500).
     # @param autostart [Boolean, nil] attempt to start the daemon if it isn't
-    #   running. When nil (the default) the shared library's default applies
-    #   (autostart on); pass false to disable. The library only autostarts
-    #   when the socket path is auto-discovered — never for an explicit
-    #   socket_path.
-    def initialize(socket_path: nil, timeout: DEFAULT_TIMEOUT, autostart: nil)
-      options = {}
-      options[:autostart] = autostart unless autostart.nil?
-      options[:socket_path] = socket_path if socket_path
-      options[:timeout_ms] = (timeout * 1000).round if timeout
-
-      @handle = Beachcomber::FFI.new_client(JSON.generate(options))
+    #   running; nil is the library's default (on). The library only
+    #   autostarts when the socket path is auto-discovered — never for an
+    #   explicit socket_path.
+    # @param exec [Boolean, nil] whether a template this client renders
+    #   ({#get}, {#eval}) may call +exec()+; nil is the library's default
+    #   (off), and a template that calls it then fails with
+    #   "exec() is disabled in this context".
+    def initialize(socket_path: nil, timeout_ms: nil, connect_timeout_ms: nil, autostart: nil, exec: nil)
+      options = self.class.options_json(
+        socket_path: socket_path, timeout_ms: timeout_ms, connect_timeout_ms: connect_timeout_ms,
+        autostart: autostart, exec: exec,
+      )
+      @handle = Beachcomber::FFI.new_client(options)
       ObjectSpace.define_finalizer(self, self.class.finalizer(@handle))
     end
 
+    # The +options_json+ +bc_client_new+ takes: exactly the options given
+    # (nil is not given), under the ABI's own names.
+    #
+    # @return [String]
+    def self.options_json(**options)
+      JSON.generate(options.compact)
+    end
+
     def self.finalizer(handle)
       proc { Beachcomber::FFI.free_client(handle) }
     end
 
-    # Reads a cached value.
+    # The value `comb get` prints for this key, cwd and env. The daemon holds
+    # the templates (`<provider>:template`, seeded from configuration or
+    # {#put}); this client renders them. A plain field is its cached value,
+    # a templated one is rendered, and a bare provider name is the whole
+    # merged namespace. The unrendered halves are facets, read like any key:
+    # <tt>"p:template.x"</tt> is the template as stored, <tt>"p:put.x"</tt>
+    # and <tt>"p:source.x"</tt> those layers' values.
     #
-    # @param key [String] e.g. "git.branch" or "git"
-    # @param path [String, nil] optional working-directory context
-    # @return [Result]
-    # @raise [Beachcomber::DaemonNotRunning] when the socket cannot be reached
-    # @raise [Beachcomber::ServerError] when the daemon returns ok: false
-    def get(key, path: nil)
-      build_result(Beachcomber::FFI.call!(:bc_get, @handle, key, path, 0))
+    # @param key [String] "provider.field" or a bare provider name
+    # @param cwd [String, nil] the directory the read addresses (`~` is home,
+    #   a relative path is against this process's working directory); nil is
+    #   the global entry
+    # @param env [Hash, nil] the caller's environment for `env.*` refs; nil
+    #   is the calling process's environment, as `comb` renders
+    # @param force [Boolean] re-execute every Source the read demands first
+    # @param wait [String, nil] how long to wait for a run the read needs
+    #   before answering what is stored, as `comb get --wait`: a duration
+    #   ("0", "50ms", "2s") or "forever"; nil is the read's budget. The read
+    #   may take +timeout_ms+ plus the wait; "forever" has no deadline
+    # @return [Object, nil] the value, or nil on a miss
+    # @raise [Beachcomber::DaemonNotRunningError] when no daemon answers
+    # @raise [Beachcomber::ServerError] when the daemon refuses the read
+    # @raise [Beachcomber::ParseError] when +wait+ is no duration
+    def get(key, cwd: nil, env: nil, force: false, wait: nil)
+      Beachcomber::FFI.call!(:bc_get, handle!, key, cwd, json_or_nil(env), get_options(force, wait))
+    end
+
+    # Renders a template that is stored nowhere — the same value `comb eval`
+    # prints. Every ref resolves exactly as it would inside a stored
+    # template, so <tt>eval('{{ p.f }}')</tt> and <tt>get('p.f')</tt> agree.
+    #
+    # +template+ accepts a single <tt>{{ expr }}</tt> tag, or literal
+    # text/several tags — the former keeps the expression's natural type,
+    # the latter is always a string (a source with no tags at all is its
+    # literal text).
+    #
+    # @param template [String]
+    # @param cwd [String, nil] read as {#get} reads it; nil is the global entry
+    # @param env [Hash, nil] the caller's environment for `env.*` refs
+    # @return [Object, nil] the value, or nil when it renders nothing
+    def eval(template, cwd: nil, env: nil)
+      Beachcomber::FFI.call!(:bc_eval, handle!, template, cwd, json_or_nil(env))
+    end
+
+    # Opens a persistent watch on the *value* of +key+ — what {#get}
+    # answers for it — and emits it again whenever it changes. A template
+    # edited under the watch fires it just as a changed cache record does.
+    # Returns a WatchStream (Enumerable). The caller is responsible for
+    # closing the stream.
+    #
+    # @param key [String] "provider.field" or a bare provider name
+    # @param cwd [String, nil] read as {#get} reads it — the directory every
+    #   subscription addresses and every re-resolution runs at; nil is the
+    #   global entry
+    # @param env [Hash, nil] the caller's environment for `env.*` refs
+    # @return [WatchStream]
+    def watch(key, cwd: nil, env: nil)
+      handle = Beachcomber::FFI.new_watch(handle!, key, cwd, json_or_nil(env))
+      raise Beachcomber::IoError, 'NULL returned from bc_watch_open (allocation failure)' if handle.nil? || handle.null?
+
+      WatchStream.new(handle)
     end
 
-    # Reads a cached value with protocol flags.
+    # Writes a value into the daemon cache. +data = nil+ removes the node.
     #
     # @param key [String]
+    # @param data [Object, nil]
+    # @param ttl [Numeric, String, nil] time-to-live (e.g. "60s")
     # @param path [String, nil]
-    # @param force [Boolean] bypass cache and recompute
-    # @param wait [Boolean] block until a fresh value is available
-    # @return [Result]
-    def get_with_flags(key, path: nil, force: false, wait: false)
-      flags = (force ? Beachcomber::FFI::GET_FORCE : 0) | (wait ? Beachcomber::FFI::GET_WAIT : 0)
-      build_result(Beachcomber::FFI.call!(:bc_get, @handle, key, path, flags))
+    # @param persist [Boolean] keep the put across a daemon restart, best effort
+    # @return [nil]
+    def put(key, data, ttl: nil, path: nil, persist: false)
+      Beachcomber::FFI.call!(:bc_put, handle!, key, JSON.generate(data), ttl&.to_s, path, persist ? 1 : 0)
+      nil
     end
 
     # Forces the daemon to recompute a provider/key.
@@ -271,39 +282,23 @@ module Beachcomber
     # @param key [String]
     # @param path [String, nil]
     def refresh(key, path: nil)
-      Beachcomber::FFI.call!(:bc_refresh, @handle, key, path)
+      Beachcomber::FFI.call!(:bc_refresh, handle!, key, path)
       nil
     end
 
     # Returns cache rows from the daemon.
     #
     # @return [Array<CacheRow>]
+    # @raise [Beachcomber::ParseError] when the answer is not a list of rows
     def status
-      parse_cache_rows(Beachcomber::FFI.call!(:bc_status, @handle))
+      Typed.cache_rows(Beachcomber::FFI.call!(:bc_status, handle!))
     end
 
     # Sends a hello handshake and returns server info.
     #
     # @return [HelloInfo]
     def hello
-      parse_hello(Beachcomber::FFI.call!(:bc_hello, @handle))
-    end
-
-    # Writes a value into the daemon cache. +data = nil+ clears the entry
-    # without dropping the registry entry.
-    #
-    # @param key [String]
-    # @param data [Object, nil]
-    # @param ttl [Numeric, String, nil] time-to-live (e.g. "60s")
-    # @param path [String, nil]
-    # @return [nil]
-    def put(key, data = nil, ttl: nil, path: nil)
-      if data.nil?
-        Beachcomber::FFI.call!(:bc_put_null, @handle, key, path)
-      else
-        Beachcomber::FFI.call!(:bc_put, @handle, key, JSON.generate(data), ttl&.to_s, path)
-      end
-      nil
+      Typed.of(HelloInfo, Beachcomber::FFI.call!(:bc_hello, handle!))
     end
 
     # Introspects a daemon subsystem.
@@ -313,53 +308,8 @@ module Beachcomber
     # @return [IntrospectResponse]
     def introspect(subject, duration_secs: nil)
       options_json = duration_secs ? JSON.generate(duration_secs: duration_secs) : nil
-      data = Beachcomber::FFI.call!(:bc_introspect, @handle, subject.to_s, options_json)
-      parse_introspect(subject.to_s, data)
-    end
-
-    # Resolves a virtual field ("provider.field") or a provider's path
-    # expression ("provider") client-side, exactly as `comb get`'s
-    # resolution layer does. `cache.*` refs the expression makes are fetched
-    # live through this client.
-    #
-    # @param key [String] "provider.field" or a bare provider name
-    # @param cwd [String] required — path-expression evaluation has no
-    #   ambient fallback; the library never reads the process's own cwd.
-    # @param env [Hash, nil] env var values `env.*` refs resolve against
-    # @param overrides [Hash, nil] expression overrides, keyed
-    #   "provider.field" or a bare provider name
-    # @return [Object, nil] the resolved value, or nil on a path-expression miss
-    def resolve(key, cwd:, env: nil, overrides: nil)
-      Beachcomber::FFI.call!(:bc_resolve, @handle, key, cwd, json_or_nil(env), json_or_nil(overrides))
-    end
-
-    # Evaluates a value expression against `env.*`/`cache.*` refs, using the
-    # same evaluator {#resolve} uses for a declared field.
-    #
-    # +template+ accepts a bare expression, a single <tt>{{ expr }}</tt>
-    # tag, or literal text/several tags — the first two keep the
-    # expression's natural type, the third is always a string.
-    #
-    # @param template [String]
-    # @param cwd [String] required, matching {#resolve}
-    # @param env [Hash, nil]
-    # @param overrides [Hash, nil]
-    # @return [Object]
-    def eval_expression(template, cwd:, env: nil, overrides: nil)
-      Beachcomber::FFI.call!(:bc_eval, @handle, template, cwd, json_or_nil(env), json_or_nil(overrides))
-    end
-
-    # Opens a persistent watch subscription. Returns a WatchStream
-    # (Enumerable). The caller is responsible for closing the stream.
-    #
-    # @param key [String]
-    # @param path [String, nil]
-    # @return [WatchStream]
-    def watch(key, path: nil)
-      handle = Beachcomber::FFI.new_watch(@handle, key, path)
-      raise Beachcomber::Error, 'bc_watch_open returned NULL (allocation failure)' if handle.nil? || handle.null?
-
-      WatchStream.new(handle)
+      data = Beachcomber::FFI.call!(:bc_introspect, handle!, subject.to_s, options_json)
+      Typed.introspect(subject.to_s, data)
     end
 
     # Opens a persistent session and yields it to the block. The connection
@@ -368,11 +318,29 @@ module Beachcomber
     # @yield [Session]
     # @return the block's return value
     def session
-      handle = Beachcomber::FFI.new_session(@handle)
-      sess = Session.new(handle, @handle)
+      sess = Session.new(Beachcomber::FFI.new_session(handle!))
       yield sess
     ensure
       sess&.close
     end
+
+    # Frees the client's handle. Idempotent; a later operation fails. The
+    # finalizer frees it when a client is never closed.
+    def close
+      return if @handle.nil?
+
+      ObjectSpace.undefine_finalizer(self)
+      Beachcomber::FFI.free_client(@handle)
+      @handle = nil
+    end
+
+    private
+
+    # The handle every operation passes on. A closed client has none, and
+    # the library must never see a NULL or freed handle, so the call fails
+    # here, as an io_error.
+    def handle!
+      @handle or raise IoError, 'the client is closed'
+    end
   end
 end

data/lib/beachcomber/errors.rb

@@ -1,127 +1,59 @@
 module Beachcomber
-  # Base class for all Beachcomber errors.
-  class Error < StandardError; end
-
-  # Raised when libbeachcomber cannot be located. Names every location tried,
-  # in order, per the shared discovery contract.
-  class LibraryNotFound < Error; end
-
-  # Raised when a loaded libbeachcomber is missing a required bc_* symbol.
-  # Names the symbol and the bc_version() of what was actually loaded.
-  class MissingSymbol < Error; end
-
-  # Base class for every `ok: false` envelope the library returns, plus the
-  # library-level conditions (bad_flags, busy, panic, version_skew) it can
-  # raise outside the CombError variant set.
+  # The base of every error this SDK raises: one subclass per kind in the
+  # SDK API table (docs/sdk-api.md), each named for its kind.
   #
-  # +kind+ is the stable, machine-readable slug from the envelope's
-  # +error.kind+ field (e.g. "server_error", "daemon_not_running"). The
-  # message always includes the loaded library's bc_version().
-  class CombError < Error
-    attr_reader :kind
-
-    def initialize(kind, message)
+  # +kind+ is the stable, machine-readable slug — the C ABI envelope's
+  # +error.kind+, or one this SDK raises itself (+library_not_found+,
+  # +library_symbol+, +unsupported+). +message+ is the ABI's message,
+  # unchanged. +library_version+ is the loaded library's bc_version(), nil
+  # when no library was loaded.
+  class CombError < StandardError
+    class << self
+      # The kind slug this class stands for; nil on the base class, which
+      # carries a kind this SDK does not know yet.
+      attr_reader :kind
+    end
+
+    attr_reader :kind, :library_version
+
+    def initialize(message = nil, kind: self.class.kind, library_version: Beachcomber::FFI.loaded_version)
+      super(message)
       @kind = kind
-      super("beachcomber: #{message} (kind=#{kind}, lib_version=#{safe_version})")
-    end
-
-    private
-
-    def safe_version
-      Beachcomber::FFI.version
-    rescue StandardError
-      'unknown'
-    end
-  end
-
-  # FFI-boundary conditions (no CombError variant on the Rust side).
-  class BadFlagsError < CombError
-    def initialize(message)
-      super('bad_flags', message)
-    end
-  end
-
-  class BusyError < CombError
-    def initialize(message)
-      super('busy', message)
-    end
-  end
-
-  class PanicError < CombError
-    def initialize(message)
-      super('panic', message)
-    end
-  end
-
-  class VersionSkewError < CombError
-    def initialize(message)
-      super('version_skew', message)
-    end
-  end
-
-  # One class per `CombError` variant on the Rust side (see
-  # libbeachcomber-ffi/src/envelope.rs).
-  class DaemonNotRunning < CombError
-    def initialize(message)
-      super('daemon_not_running', message)
+      @library_version = library_version
     end
   end
 
-  class ConnectionFailedError < CombError
-    def initialize(message)
-      super('connection_failed', message)
-    end
-  end
-
-  class IoError < CombError
-    def initialize(message)
-      super('io_error', message)
-    end
+  # Defines the error class for +kind+, named for it.
+  def self.define_error(name, kind)
+    klass = Class.new(CombError) { @kind = kind }
+    const_set(name, klass)
   end
+  private_class_method :define_error
 
-  # Raised when a response cannot be parsed as valid JSON, or the daemon
-  # rejects malformed input.
-  class ProtocolError < CombError
-    def initialize(message)
-      super('parse_error', message)
-    end
-  end
-
-  # Raised when the daemon returns ok: false for an op it actually executed.
-  class ServerError < CombError
-    def initialize(message)
-      super('server_error', message)
-    end
-  end
-
-  class TimeoutError < CombError
-    def initialize(message)
-      super('timeout', message)
-    end
-  end
+  define_error :DaemonNotRunningError, 'daemon_not_running'
+  define_error :ConnectionFailedError, 'connection_failed'
+  define_error :IoError, 'io_error'
+  define_error :ParseError, 'parse_error'
+  define_error :ServerError, 'server_error'
+  define_error :TimeoutError, 'timeout'
+  define_error :BusyError, 'busy'
+  define_error :PanicError, 'panic'
+  define_error :LibraryNotFoundError, 'library_not_found'
+  define_error :LibrarySymbolError, 'library_symbol'
+  define_error :UnsupportedError, 'unsupported'
 
-  # error.kind slug -> exception class. Kept in sync with
-  # libbeachcomber-ffi/src/envelope.rs's ErrorKind enum.
-  KIND_TO_CLASS = {
-    'bad_flags' => BadFlagsError,
-    'busy' => BusyError,
-    'panic' => PanicError,
-    'version_skew' => VersionSkewError,
-    'daemon_not_running' => DaemonNotRunning,
-    'connection_failed' => ConnectionFailedError,
-    'io_error' => IoError,
-    'parse_error' => ProtocolError,
-    'server_error' => ServerError,
-    'timeout' => TimeoutError,
-  }.freeze
+  # error.kind slug -> its class.
+  KIND_TO_CLASS = constants.map { |c| const_get(c) }
+                           .select { |c| c.is_a?(Class) && c < CombError }
+                           .to_h { |c| [c.kind, c] }
+                           .freeze
 
-  # Raises the idiomatic exception for an envelope's error.kind/error.message.
-  # An unrecognised kind (future ABI additions) still raises CombError with
-  # that kind preserved, rather than failing to raise at all.
+  # Raises the error for an envelope's error.kind/error.message. A kind
+  # this SDK does not know yet still raises a CombError carrying it.
   def self.raise_for_error(kind, message)
     klass = KIND_TO_CLASS[kind]
     raise klass.new(message) if klass
 
-    raise CombError.new(kind, message)
+    raise CombError.new(message, kind: kind)
   end
 end

data/lib/beachcomber/ffi.rb

@@ -7,46 +7,45 @@ module Beachcomber
   # Fiddle::Function objects, plus JSON-envelope decoding shared by
   # Client/Session/WatchStream.
   #
-  # Discovery order (the shared contract every dynamic-language binding
-  # follows):
+  # Discovery is the one rule every SDK follows (docs/sdk-api.md, "Library
+  # discovery"; the shared fixture is sdks/discovery.json):
   #
-  #   1. $BEACHCOMBER_LIB
-  #   2. ../lib/<libname> relative to the resolved `comb` on $PATH
-  #   3. the platform default dynamic-linker search path
+  #   1. $BEACHCOMBER_LIB, when set and not empty. It is then the only
+  #      candidate: a path set on purpose that does not load is an error,
+  #      not a reason to load some other library.
+  #   2. Beside `comb`: <dir>/../lib/<file>, where <dir> is the directory of
+  #      the first executable `comb` on $PATH, its symlinks resolved (a
+  #      Homebrew `comb` is a symlink into its Cellar, the library beside it).
+  #   3. The system loader, given the bare file name.
   #
-  # `../lib/` beside `comb` is checked before the system path deliberately:
-  # library and binary ship together, so the copy next to the `comb` you
-  # would actually run is the matching one, and a stale system-wide copy
-  # must not win.
-  #
-  # A failure to find or load the library, or a missing required symbol, is
-  # a loud error naming every location tried (or the missing symbol) plus
-  # the loaded library's bc_version() where known. There is no silent
-  # fallback to a subprocess transport.
+  # The candidates are tried in order and the first that loads wins. When
+  # none does, LibraryNotFoundError names every candidate and why it failed;
+  # a missing required symbol is LibrarySymbolError. There is no fallback to
+  # a subprocess transport.
   module FFI
-    LIB_BASENAME =
-      case RbConfig::CONFIG['host_os']
-      when /darwin/i
-        'libbeachcomber.dylib'
-      when /linux/i
-        'libbeachcomber.so'
-      else
-        raise Beachcomber::Error, "unsupported platform: #{RbConfig::CONFIG['host_os']}"
-      end
+    # The library's file name: libbeachcomber.dylib on macOS and
+    # libbeachcomber.so on every other platform.
+    def self.library_basename(host_os = RbConfig::CONFIG['host_os'])
+      host_os =~ /darwin/i ? 'libbeachcomber.dylib' : 'libbeachcomber.so'
+    end
+
+    LIB_BASENAME = library_basename
+
+    # One location the loader tries: where it came from, and the path (or,
+    # for the system loader, the bare file name) handed to dlopen.
+    Candidate = Struct.new(:description, :path)
 
     # The 22 bc_* symbols this binding calls, checked at load (not on first
     # use) so a version-skewed or partial install fails loudly up front.
     REQUIRED_SYMBOLS = %w[
       bc_version bc_client_new bc_client_free bc_string_free
-      bc_get bc_put bc_put_null bc_refresh bc_status bc_introspect bc_hello
-      bc_resolve bc_eval
-      bc_session_open bc_session_close bc_session_get bc_session_put bc_session_set_context
+      bc_get bc_put bc_refresh bc_status bc_introspect bc_hello
+      bc_eval
+      bc_session_open bc_session_close bc_session_get bc_session_put bc_session_refresh
+      bc_session_set_context
       bc_watch_open bc_watch_next bc_watch_cancel bc_watch_free
     ].freeze
 
-    GET_FORCE = 1 << 0
-    GET_WAIT  = 1 << 1
-
     VOIDP = Fiddle::TYPE_VOIDP
     INT   = Fiddle::TYPE_INT
     VOID  = Fiddle::TYPE_VOID
@@ -55,9 +54,8 @@ module Beachcomber
       attr_reader :library_path
     end
 
-    # Finds `comb` on $PATH the way a shell would, resolving symlinks (a
-    # Homebrew-linked binary, for instance) so `../lib/` is computed
-    # relative to where the binary actually lives.
+    # The first executable `comb` on $PATH, its symlinks resolved; nil when
+    # there is none.
     def self.resolved_comb_path
       ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
         next if dir.nil? || dir.empty?
@@ -72,48 +70,43 @@ module Beachcomber
       nil
     end
 
-    def self.candidate_beside_comb
+    # The locations to try for +file+, in order. Reads the environment and
+    # $PATH; loads nothing.
+    #
+    # @return [Array<Candidate>]
+    def self.candidates(file = LIB_BASENAME)
+      explicit = ENV['BEACHCOMBER_LIB']
+      return [Candidate.new('$BEACHCOMBER_LIB', explicit)] if explicit && !explicit.empty?
+
+      out = []
       comb = resolved_comb_path
-      return nil unless comb
+      if comb
+        beside = File.expand_path(File.join(File.dirname(comb), '..', 'lib', file))
+        out << Candidate.new("beside comb (#{comb})", beside)
+      end
+      out << Candidate.new('the system loader', file)
+    end
 
-      File.expand_path(File.join(File.dirname(comb), '..', 'lib', LIB_BASENAME))
+    # The first of +candidates+ that loads, as [handle, path]; when none
+    # does, LibraryNotFoundError naming each and why it failed.
+    def self.open_first(candidates)
+      tried = candidates.map do |candidate|
+        return [Fiddle.dlopen(candidate.path), candidate.path]
+      rescue Fiddle::DLError => e
+        "#{candidate.description} (#{candidate.path}): #{e.message}"
+      end
+      raise Beachcomber::LibraryNotFoundError.new(
+        "could not load libbeachcomber; tried, in order: #{tried.join('; ')}", library_version: nil,
+      )
     end
 
     # Loads the library (idempotent) and returns the Fiddle::Handle.
     def self.load!
       return @handle if defined?(@handle) && @handle
 
-      tried = []
-
-      env_lib = ENV['BEACHCOMBER_LIB']
-      if env_lib && !env_lib.empty?
-        tried << env_lib
-        handle = try_open(env_lib)
-        return finish_load!(handle, env_lib) if handle
-      end
-
-      candidate = candidate_beside_comb
-      if candidate
-        tried << candidate
-        handle = try_open(candidate)
-        return finish_load!(handle, candidate) if handle
-      end
-
-      tried << "#{LIB_BASENAME} (platform default search path)"
-      handle = try_open(LIB_BASENAME)
-      return finish_load!(handle, LIB_BASENAME) if handle
-
-      raise Beachcomber::LibraryNotFound,
-            "could not locate #{LIB_BASENAME}; tried: #{tried.join(', ')}"
+      finish_load!(*open_first(candidates))
     end
 
-    def self.try_open(path)
-      Fiddle.dlopen(path)
-    rescue Fiddle::DLError
-      nil
-    end
-    private_class_method :try_open
-
     def self.finish_load!(handle, path)
       @handle       = handle
       @library_path = path
@@ -135,9 +128,10 @@ module Beachcomber
       missing = REQUIRED_SYMBOLS.reject { |sym| symbol_present?(sym) }
       return if missing.empty?
 
-      raise Beachcomber::MissingSymbol,
-            "#{@library_path} is missing required symbol(s): #{missing.join(', ')} " \
-            "(bc_version=#{safe_version_for_error})"
+      raise Beachcomber::LibrarySymbolError.new(
+        "#{@library_path} is missing required symbol(s): #{missing.join(', ')}",
+        library_version: safe_version_for_error,
+      )
     end
     private_class_method :check_symbols!
 
@@ -158,21 +152,20 @@ module Beachcomber
         bc_client_new: fnew('bc_client_new', [VOIDP], VOIDP),
         bc_client_free: fnew('bc_client_free', [VOIDP], VOID),
         bc_string_free: fnew('bc_string_free', [VOIDP], VOID),
-        bc_get: fnew('bc_get', [VOIDP, VOIDP, VOIDP, INT], VOIDP),
-        bc_put: fnew('bc_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
-        bc_put_null: fnew('bc_put_null', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_get: fnew('bc_get', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_put: fnew('bc_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP, INT], VOIDP),
         bc_refresh: fnew('bc_refresh', [VOIDP, VOIDP, VOIDP], VOIDP),
         bc_status: fnew('bc_status', [VOIDP], VOIDP),
         bc_introspect: fnew('bc_introspect', [VOIDP, VOIDP, VOIDP], VOIDP),
         bc_hello: fnew('bc_hello', [VOIDP], VOIDP),
-        bc_resolve: fnew('bc_resolve', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
-        bc_eval: fnew('bc_eval', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_eval: fnew('bc_eval', [VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
         bc_session_open: fnew('bc_session_open', [VOIDP], VOIDP),
         bc_session_close: fnew('bc_session_close', [VOIDP], VOID),
-        bc_session_get: fnew('bc_session_get', [VOIDP, VOIDP, VOIDP, INT], VOIDP),
-        bc_session_put: fnew('bc_session_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_session_get: fnew('bc_session_get', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_session_put: fnew('bc_session_put', [VOIDP, VOIDP, VOIDP, VOIDP, VOIDP, INT], VOIDP),
+        bc_session_refresh: fnew('bc_session_refresh', [VOIDP, VOIDP, VOIDP], VOIDP),
         bc_session_set_context: fnew('bc_session_set_context', [VOIDP, VOIDP], VOIDP),
-        bc_watch_open: fnew('bc_watch_open', [VOIDP, VOIDP, VOIDP], VOIDP),
+        bc_watch_open: fnew('bc_watch_open', [VOIDP, VOIDP, VOIDP, VOIDP], VOIDP),
         bc_watch_next: fnew('bc_watch_next', [VOIDP, INT], VOIDP),
         bc_watch_cancel: fnew('bc_watch_cancel', [VOIDP], VOID),
         bc_watch_free: fnew('bc_watch_free', [VOIDP], VOID),
@@ -192,6 +185,14 @@ module Beachcomber
       ptr.null? ? '' : ptr.to_s
     end
 
+    # The build version of the library already loaded, or nil when none is:
+    # never loads one, so an error raised while loading can ask for it.
+    def self.loaded_version
+      return nil unless defined?(@fn) && @fn
+
+      version
+    end
+
     # Calls a void*(...)-returning bc_* function, reads the NUL-terminated
     # JSON result, frees it via bc_string_free, and returns the raw JSON
     # string. Not for bc_version, whose result must never be freed.
@@ -199,7 +200,7 @@ module Beachcomber
       load!
       fn = @fn.fetch(sym) { raise ArgumentError, "unknown bc_* function #{sym}" }
       ptr = fn.call(*args)
-      raise Beachcomber::Error, "unexpected NULL pointer from #{sym}" if ptr.nil? || ptr.null?
+      raise Beachcomber::IoError, "NULL returned from #{sym}" if ptr.nil? || ptr.null?
 
       json = ptr.to_s
       @fn[:bc_string_free].call(ptr)
@@ -231,9 +232,9 @@ module Beachcomber
       @fn[:bc_session_open].call(client_handle)
     end
 
-    def self.new_watch(client_handle, key, path)
+    def self.new_watch(client_handle, key, cwd, env_json)
       load!
-      @fn[:bc_watch_open].call(client_handle, key, path)
+      @fn[:bc_watch_open].call(client_handle, key, cwd, env_json)
     end
 
     # Void-returning teardown calls (null-safe on the C side; harmless if

data/lib/beachcomber/types.rb

@@ -1,20 +1,29 @@
 module Beachcomber
+  # The typed shapes of the SDK API table (docs/sdk-api.md): exactly the
+  # fields libbeachcomber::protocol defines, as bc_hello, bc_status and
+  # bc_introspect hand them on. A field the ABI leaves out is nil.
   HelloInfo = Struct.new(:protocol_version, :daemon_version, keyword_init: true)
+
+  # One row of #status. +kind+ and +failure+ are the JSON the ABI hands on.
   CacheRow = Struct.new(
-    :provider, :field, :path, :value, :age_ms, :stale,
-    :kind, :poll_interval_secs, :keep_alive_polls, :fsevents_reinstate, :polls_elapsed,
-    :failure, :source,
+    :provider, :path, :source, :field, :value, :age_ms,
+    :kind, :poll_interval_secs, :poll_count, :polls_elapsed,
+    :next_poll_in_secs, :failure,
     keyword_init: true
   )
   Verdict = Struct.new(:level, :message, keyword_init: true)
-  Reaper = Struct.new(:armed, :visibility, :sweeps, :reaped, :kill_denied, keyword_init: true)
+  ReaperStatus = Struct.new(:armed, :visibility, :sweeps, :reaped, :kill_denied, keyword_init: true)
   DaemonHealth = Struct.new(
     :pid, :version, :uptime_secs, :socket_path, :config_path,
     :requests_total, :in_flight, :active_watchers, :cache_entries,
     :watch_backend, :reaper, :verdicts,
     keyword_init: true
   )
-  WatchEvent = Struct.new(:data, :age_ms, :stale, keyword_init: true)
+  # One emitted change on a watch. +data+ is the value — what `comb get`
+  # would print for the watched key — or nil when nothing is stored there.
+  # A value resolved from several cache records has no single age or
+  # staleness, so a watch reports neither.
+  WatchEvent = Struct.new(:data, keyword_init: true)
 
   module IntrospectSubject
     DAEMON    = "daemon"
@@ -28,7 +37,7 @@ module Beachcomber
     PROCS     = "procs"
   end
 
-  # Introspect response wrapper. For DAEMON subject: #daemon is populated.
-  # For others: #other holds the raw Hash/Array.
+  # An #introspect answer. For the DAEMON subject #daemon is a DaemonHealth;
+  # for the others #other is the JSON the ABI hands on.
   IntrospectResponse = Struct.new(:subject, :daemon, :other, keyword_init: true)
 end

data/lib/beachcomber/watch_stream.rb

@@ -2,11 +2,14 @@ module Beachcomber
   # Iterates events from a bc_watch_open handle. Create via
   # {Client#watch} rather than directly.
   #
-  # bc_watch_next distinguishes five outcomes: event, timeout, eof,
-  # cancelled, error. #next_event folds timeout/eof/cancelled into a single
-  # nil (matching the previous socket-based API's "nil means the stream is
-  # over" contract) and raises the idiomatic exception for error. Pass an
-  # explicit +timeout_ms+ to observe timeouts distinctly.
+  # Each event is the value of the watched key — what `comb get` would print
+  # for it — re-resolved whenever any key the resolution reads changes,
+  # including the provider's template tree.
+  #
+  # bc_watch_next has five outcomes: event, timeout, eof, cancelled, error.
+  # #next_event answers a WatchEvent for an event, nil once the stream has
+  # ended (eof or cancelled), and raises: TimeoutError when its wait runs
+  # out, the error's own class for an error.
   class WatchStream
     include Enumerable
 
@@ -24,13 +27,18 @@ module Beachcomber
       end
     end
 
-    # Waits for the next event. +timeout_ms+: -1 (default) blocks
-    # indefinitely, 0 polls once, >0 waits that long.
+    # Waits for the next event: indefinitely when +timeout_ms+ is nil, else
+    # that long (0 polls once).
     #
-    # @return [WatchEvent, nil] nil on end-of-stream (daemon closed the
-    #   connection, the watch was cancelled, or the wait elapsed).
-    def next_event(timeout_ms = -1)
-      json = Beachcomber::FFI.raw_call(:bc_watch_next, @handle, timeout_ms)
+    # @return [WatchEvent, nil] the value on an emitted change; nil once the
+    #   stream has ended (the daemon closed it, or it was cancelled). An
+    #   event whose +data+ is nil is a miss, not the end of the stream.
+    # @raise [Beachcomber::TimeoutError] when +timeout_ms+ runs out with no
+    #   event; the stream is still open
+    def next_event(timeout_ms = nil)
+      return nil if @closed
+
+      json = Beachcomber::FFI.raw_call(:bc_watch_next, @handle, timeout_ms || -1)
       envelope = JSON.parse(json)
 
       unless envelope['ok']
@@ -40,30 +48,29 @@ module Beachcomber
 
       case envelope['outcome']
       when 'event'
-        payload = envelope['data']
-        WatchEvent.new(
-          data: payload['data'],
-          age_ms: (payload['age_ms'] || 0).to_i,
-          stale: payload['stale'] == true,
-        )
-      when 'timeout', 'eof', 'cancelled'
+        WatchEvent.new(data: envelope['data'])
+      when 'eof', 'cancelled'
         nil
+      when 'timeout'
+        raise Beachcomber::TimeoutError, "no event within #{timeout_ms}ms"
       else
-        raise Beachcomber::ProtocolError, "unknown watch outcome: #{envelope['outcome'].inspect}"
+        raise Beachcomber::ParseError, "unknown watch outcome: #{envelope['outcome'].inspect}"
       end
     end
 
-    # Unblocks a pending or future #next_event call. Safe to call from
-    # another thread while a call is in flight.
+    # Ends the stream: a pending or later #next_event answers nil. Safe to
+    # call from another thread while a call is in flight.
     def cancel
-      Beachcomber::FFI.cancel_watch(@handle)
+      Beachcomber::FFI.cancel_watch(@handle) unless @closed
       nil
     end
 
+    # Cancels the stream and frees its handle. Idempotent.
     def close
       return if @closed
 
       @closed = true
+      Beachcomber::FFI.cancel_watch(@handle)
       Beachcomber::FFI.free_watch(@handle)
     end
   end

data/lib/beachcomber.rb

@@ -1,8 +1,6 @@
 require_relative 'beachcomber/errors'
 require_relative 'beachcomber/ffi'
-require_relative 'beachcomber/result'
 require_relative 'beachcomber/types'
-require_relative 'beachcomber/discovery'
 require_relative 'beachcomber/watch_stream'
 require_relative 'beachcomber/client'
 
@@ -16,15 +14,14 @@ require_relative 'beachcomber/client'
 #   require 'beachcomber'
 #
 #   client = Beachcomber::Client.new
-#   result = client.get('git.branch', path: '/path/to/repo')
-#   puts result.data if result.hit?
+#   branch = client.get('git.branch', cwd: '/path/to/repo') # nil on a miss
 #
 # Persistent session (one connection, multiple queries):
 #
 #   client.session do |s|
 #     s.set_context('/path/to/repo')
-#     r1 = s.get('git.branch')
-#     r2 = s.get('git.dirty')
+#     branch = s.get('git.branch')
+#     dirty = s.get('git.dirty')
 #   end
 module Beachcomber
   VERSION = '0.1.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libbeachcomber
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - NavistAu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies: []
 description: Communicates with the beachcomber daemon over a Unix domain socket to
   query cached shell-environment data (git state, hostname, battery, etc.).
@@ -19,10 +19,8 @@ extra_rdoc_files: []
 files:
 - lib/beachcomber.rb
 - lib/beachcomber/client.rb
-- lib/beachcomber/discovery.rb
 - lib/beachcomber/errors.rb
 - lib/beachcomber/ffi.rb
-- lib/beachcomber/result.rb
 - lib/beachcomber/types.rb
 - lib/beachcomber/watch_stream.rb
 homepage: https://github.com/NavistAu/beachcomber

data/lib/beachcomber/discovery.rb

@@ -1,24 +0,0 @@
-require 'etc'
-
-module Beachcomber
-  # Discovers the Unix socket path for the beachcomber daemon.
-  #
-  # Mirrors the daemon's bind-path resolution (Config::resolve_socket_path),
-  # minus the config-file step which is daemon-only. Discovery order:
-  #   1. $BEACHCOMBER_SOCKET  (if set and non-empty)
-  #   2. /tmp/beachcomber-<uid>/sock
-  #
-  # There is no existence probe and no session-scoped environment is
-  # consulted ($TMPDIR, $XDG_RUNTIME_DIR): the result is the single path the
-  # daemon binds for the same environment. Non-standard setups point clients
-  # at the daemon via BEACHCOMBER_SOCKET.
-  module Discovery
-    # @return [String] the resolved socket path
-    def self.socket_path
-      sock = ENV['BEACHCOMBER_SOCKET']
-      return sock if sock && !sock.empty?
-
-      File.join('/tmp', "beachcomber-#{Process.uid}", 'sock')
-    end
-  end
-end

data/lib/beachcomber/result.rb

@@ -1,81 +0,0 @@
-module Beachcomber
-  # Wraps a daemon response.
-  #
-  # A result can represent a cache hit (data present), a miss (ok but no data),
-  # or an error (ok: false — though errors are normally raised as ServerError).
-  #
-  # Examples:
-  #
-  #   result = client.get('git.branch', path: '/repo')
-  #   if result.hit?
-  #     puts result.data    # "main"
-  #     puts result.age_ms  # 42
-  #   end
-  #
-  #   # hash data access
-  #   result = client.get('git', path: '/repo')
-  #   puts result['branch']
-  class Result
-    # @return [Boolean] whether the daemon reported success
-    attr_reader :ok
-
-    # @return [Object, nil] decoded payload (String, Integer, Hash, Array, etc.)
-    attr_reader :data
-
-    # @return [Integer] age of the cached value in milliseconds
-    attr_reader :age_ms
-
-    # @return [String, nil] error message when ok is false
-    attr_reader :error
-
-    def initialize(ok:, data:, age_ms:, stale:, error:)
-      @ok     = ok
-      @data   = data
-      @age_ms = age_ms
-      @stale  = stale
-      @error  = error
-    end
-
-    # @return [Boolean]
-    def ok?
-      @ok
-    end
-
-    # @return [Boolean] true when the response carried data (cache hit)
-    def hit?
-      @ok && !@data.nil?
-    end
-
-    # @return [Boolean] true when the response was successful but had no data
-    def miss?
-      @ok && @data.nil?
-    end
-
-    # @return [Boolean] true when the cached value is stale
-    def stale?
-      @stale
-    end
-
-    # Delegates field access to the data hash.
-    #
-    # @param key [String] field name
-    # @return [Object, nil]
-    # @raise [TypeError] if data is not a Hash
-    def [](key)
-      unless @data.is_a?(Hash)
-        raise TypeError, "Result#[] requires hash data, got #{@data.class}"
-      end
-
-      @data[key]
-    end
-
-    def inspect
-      parts = ["ok=#{@ok}"]
-      parts << "data=#{@data.inspect}" unless @data.nil?
-      parts << "age_ms=#{@age_ms}" if @age_ms > 0
-      parts << "stale=true" if @stale
-      parts << "error=#{@error.inspect}" if @error
-      "#<Beachcomber::Result #{parts.join(', ')}>"
-    end
-  end
-end