iriq 0.30.2 → 0.35.0

data/lib/iriq/corpus.rb

@@ -54,6 +54,10 @@ module Iriq
         unless HOST_STRATEGIES.include?(host_strategy)
 
       @classifier    = classifier
+      # Stored activations layer onto the base; @activations is the set
+      # @classifier was built from.
+      @base_classifier = classifier
+      @activations     = []
       @host_strategy = host_strategy
       @storage       = storage || Storage::Memory.new(
         classifier: classifier,
@@ -95,42 +99,50 @@ module Iriq
     # replay against alternate reducers / thresholds for re-runnable
     # inference. See lib/iriq/event.rb and lib/iriq/reducer.rb.
     def observe(input)
-      iri     = coerce(input)
-      events  = events_for(iri)
-      cluster = nil
-
-      @storage.transaction do |s|
-        events.each do |e|
-          result = Reducer.apply(e, s)
-          cluster = result if e.is_a?(Event::ClusterAddition)
-        end
-        s.record_observation(iri.canonical) if s.respond_to?(:record_observation)
+      iri = coerce(input)
+
+      addition = batch do
+        # Derived inside the batch, which may have just adopted activations.
+        events = events_for(iri)
+        events.each { |e| Reducer.apply(e, @storage) }
+        @storage.record_observation(iri.canonical) if @storage.respond_to?(:record_observation)
+        events.find { |e| e.is_a?(Event::ClusterAddition) }
       end
 
-      Observation.new(corpus: self, identifier: iri, cluster: cluster)
+      Observation.new(corpus: self, identifier: iri, cluster_key: addition.key)
+    end
+
+    # Observe every IRI. On SQLite they commit a turn of about a second at a
+    # time, so other processes writing the corpus get the lock in between; a
+    # failure keeps the turns already committed. Inside #batch they all join
+    # its transaction.
+    def observe_all(iris)
+      done = 0
+      while done < iris.size
+        batch do
+          while done < iris.size
+            observe(iris[done])
+            done += 1
+            break if @storage.turn_over?
+          end
+        end
+      end
+      nil
     end
 
-    # Drop every materialized view (host counts, position stats, clusters,
-    # …) and rebuild them by replaying the source-IRI log through the
-    # current events + reducers pipeline. Useful for:
+    # Rebuild every materialized view (host counts, position stats, clusters,
+    # …) by replaying the source-IRI log through the current events +
+    # reducers pipeline. Useful for:
     #
     #   - Tuning thresholds (swap a Corpus constant, call reinfer)
     #   - Swapping the classifier (open the Corpus with a different
     #     classifier, call reinfer — events are re-derived from raw IRIs)
     #   - Recovering after a Reducer-set change
     #
-    # Wrapped in a single backend transaction so a failure mid-replay
-    # leaves the prior views intact.
+    # The views change all at once, keeping what other connections observe
+    # meanwhile; a failure leaves the prior views intact.
     def reinfer
-      @storage.transaction do |s|
-        iris = []
-        s.each_observed_iri { |canonical| iris << canonical }
-        s.clear_materialized_views
-        iris.each do |canonical|
-          iri = Parser.parse(canonical)
-          events_for(iri).each { |e| Reducer.apply(e, s) }
-        end
-      end
+      rebuild(nil)
       nil
     end
 
@@ -154,38 +166,28 @@ module Iriq
       strategies.flat_map { |s| s.propose(@storage, **opts) }
     end
 
-    # Promote a RecognizerProposal into a live Recognizer for this corpus.
-    #
-    # Mechanics:
-    #   1. Synthesize a SynthesizedRecognizer from the proposal's prefix.
-    #   2. Switch to a per-corpus classifier (if we were sharing the
-    #      module-level DEFAULT) so activation doesn't leak to other
-    #      corpora using the same default singleton.
-    #   3. Register the Recognizer on the classifier — the ensemble
-    #      picks it up on the next classify() call.
-    #   4. Persist the activation in storage so reopens re-apply it.
-    #   5. Reinfer so existing observations get re-classified through
-    #      the new Recognizer.
+    # Promote a RecognizerProposal into a live Recognizer for this corpus:
+    # store the activation, then reinfer existing observations through it.
+    # Both commit in one transaction — a failure leaves neither behind, in
+    # storage or in this corpus's classifier. Activating a recognizer the
+    # corpus already holds changes nothing.
     #
     # Returns the synthesized Recognizer.
     def activate_proposal(proposal)
       recognizer = SynthesizedRecognizer.from_proposal(proposal)
-      ensure_per_corpus_classifier!
-      @classifier.register_recognizer(recognizer)
-      if @storage.respond_to?(:record_activated_recognizer)
-        @storage.record_activated_recognizer(recognizer.to_dump)
-      end
-      reinfer
+      activate(recognizer)
       recognizer
     end
 
     # Convenience: activate every proposal whose confidence clears the
-    # given threshold. Returns the activated Recognizers. Confidence
-    # incorporates both per-position coverage AND cross-host
+    # given threshold. Returns the Recognizers this call newly activated.
+    # Confidence incorporates both per-position coverage AND cross-host
     # corroboration — see RecognizerProposal#compute_confidence.
     def activate_proposals_above(confidence_threshold, **propose_opts)
-      proposals = propose_recognizers(**propose_opts)
-      proposals.select { |p| p.confidence >= confidence_threshold }.map { |p| activate_proposal(p) }
+      propose_recognizers(**propose_opts)
+        .select { |p| p.confidence >= confidence_threshold }
+        .map { |p| SynthesizedRecognizer.from_proposal(p) }
+        .select { |r| activate(r) }
     end
 
     # Number of activated recognizers persisted with this corpus.
@@ -232,8 +234,9 @@ module Iriq
     def events_for(input)
       iri = coerce(input)
       hinted_entries = SegmentHints.derive(iri.path_segments, @classifier)
-      raw_shape    = PathShape.new(classifier: @classifier, hints: false).from_entries(hinted_entries)
-      hinted_shape = PathShape.new(classifier: @classifier, hints: true).from_entries(hinted_entries)
+      shape        = Shape.from_entries(hinted_entries)
+      raw_shape    = shape.render(hints: false)
+      hinted_shape = shape.render(hints: true)
       keying_host  = effective_host(iri.host)
 
       events = [
@@ -263,9 +266,9 @@ module Iriq
     # call into Normalizer with `evidence: self`; the corpus-informed path
     # and query rendering live in #render_path / #render_query below
     # (the evidence-source interface).
-    def normalize(input)
+    def normalize(input, hints: true)
       iri = coerce(input)
-      Normalizer.normalize_identifier(iri, classifier: @classifier, hints: true, evidence: self)
+      Normalizer.normalize_identifier(iri, classifier: @classifier, hints: hints, evidence: self)
     end
 
     # Evidence-source interface — called by Normalizer when this Corpus is
@@ -273,27 +276,33 @@ module Iriq
     # classifications (variability promotion, popular-outlier preservation).
     # Always emits a leading "/" — empty path collapses to "/" to match
     # mechanical output and anchor any trailing query.
-    def render_path(iri, _classifier, _hints)
-      tokens = annotate_segments(iri).map { |entry| corpus_token(entry) }
+    def render_path(iri, _classifier, hints)
+      tokens = annotate_segments(iri).map { |entry| corpus_token(entry, hints) }
       "/" + tokens.join("/")
     end
 
-    # Evidence-source interface — render the query string with
-    # cluster-inferred param types where available. The mechanical
-    # NullEvidenceSource provides the classifier-only fallback; this
-    # version prefers the cluster's observed type per param (dominant
-    # type_count, subject to the corpus thresholds).
+    # Evidence-source interface — render the query string. A param the
+    # cluster has seen at least MIN_OBSERVATIONS_FOR_INFERENCE times renders
+    # with the cluster's type; below that the corpus has no opinion and the
+    # param renders exactly as mechanical normalize would.
     def render_query(iri, _classifier = @classifier)
+      return "" if iri.query_params.nil? || iri.query_params.empty?
+
       hinted_shape = PathShape.new(classifier: @classifier, hints: true)
                               .from_entries(SegmentHints.derive(iri.path_segments, @classifier))
       key, * = Cluster.key_for(iri, classifier: @classifier, shape: hinted_shape,
                                host: effective_host(iri.host))
-      cluster = @storage.cluster_for(key)
+      mechanical = NullEvidenceSource.new
 
       iri.query_params.keys.sort.map do |k|
-        v = iri.query_params[k].to_s
-        type = inferred_param_type(cluster, k, v)
-        shaped = render_param_value(v, type)
+        v     = iri.query_params[k].to_s
+        stats = @storage.param_stats(key, k)
+        shaped =
+          if stats && stats.total >= MIN_OBSERVATIONS_FOR_INFERENCE
+            render_param_value(v, Cluster.param_type_for(k, stats) || @classifier.classify(v))
+          else
+            mechanical.render_param(k, v, @classifier)
+          end
         "#{k}=#{shaped}"
       end.join("&")
     end
@@ -373,31 +382,141 @@ module Iriq
     # Wrap many observations in a single backend transaction. For SQLite this
     # turns thousands of fsyncs into one; for in-memory backends it's a
     # no-op. Use when ingesting a batch.
-    def batch(&block)
-      @storage.batch(&block)
+    #
+    # Every write runs in one, and classifies with exactly the activations
+    # stored as of its start — including any another connection committed.
+    def batch
+      @storage.batch do |changed|
+        reapply_activated_recognizers! if changed
+        yield
+      end
     end
 
     private
 
-    # If we're still sharing the module-level DEFAULT classifier, switch
-    # to our own copy so register_recognizer doesn't leak into other
-    # corpora using the same default singleton.
-    def ensure_per_corpus_classifier!
-      return if @classifier != SegmentClassifier::DEFAULT
+    # Whether this call activated `recognizer`. The dedup check runs under
+    # the write lock, so two corpora racing to activate it can't both win.
+    def activate(recognizer)
+      rebuild(recognizer.to_dump)
+    end
+
+    # Storage's activations changed while a rebuild replayed; they now read
+    # `stored`.
+    class StaleRebuild < StandardError
+      attr_reader :stored
+
+      def initialize(stored)
+        super("activations changed during a rebuild")
+        @stored = stored
+      end
+    end
+
+    # Rebuild every view from the observation log and, given `activation`,
+    # store that recognizer with them: both commit together or not at all.
+    # The replay runs into views only this connection sees, without the write
+    # lock, which it takes just to replay what others observed meanwhile and
+    # install the result. False, changing nothing, when `activation` is
+    # already stored.
+    def rebuild(activation)
+      planned = stored_activations
+      if activation
+        return false if holds_activation?(planned, activation)
+
+        planned += [activation]
+      end
+      loop do
+        outcome = begin
+          install_views(build_views(planned), planned, activation)
+        ensure
+          @storage.discard_rebuild
+        end
+        # The rebuild classified with `planned`; storage decides from here.
+        reapply_activated_recognizers!
+        return outcome unless outcome.is_a?(StaleRebuild)
 
-      @classifier = SegmentClassifier.new
+        planned = outcome.stored
+      end
+    rescue StandardError
+      reapply_activated_recognizers! rescue nil
+      raise
+    end
+
+    # Replay the log into a rebuild classified with `activations`, catching
+    # up while each pass replays less than the one before. Returns the log
+    # mark replayed through.
+    def build_views(activations)
+      use_activations(activations)
+      @storage.begin_rebuild
+      mark = 0
+      last_pass = Float::INFINITY
+      loop do
+        replayed, mark = replay_log_since(mark)
+        return mark if replayed.zero? || replayed >= last_pass
+
+        last_pass = replayed
+      end
+    end
+
+    # Under the write lock, record `activation`, replay the log past `mark`
+    # and install the rebuild — unless the stored activations are no longer
+    # the `planned` set the rebuild classified with (a StaleRebuild, returned).
+    def install_views(mark, planned, activation)
+      batch do
+        if activation
+          next false if holds_activation?(stored_activations, activation)
+
+          @storage.record_activated_recognizer(activation)
+        end
+        stored = stored_activations
+        raise StaleRebuild, stored unless stored == planned
+
+        use_activations(stored)
+        replay_log_since(mark)
+        @storage.install_rebuild
+        true
+      end
+    rescue StaleRebuild => e
+      e
+    end
+
+    # Replay the observations logged after `mark`. Returns how many, and the
+    # mark through them.
+    def replay_log_since(mark)
+      iris = []
+      mark = @storage.each_observed_iri_since(mark) { |canonical| iris << canonical }
+      iris.each { |canonical| events_for(Parser.parse(canonical)).each { |e| Reducer.apply(e, @storage) } }
+      [iris.size, mark]
+    end
+
+    # An activation is its prefix and type: specificity never changes what it
+    # classifies, and older Rust binaries stored a different one.
+    def holds_activation?(activations, activation)
+      activations.any? { |a| a.values_at("prefix", "type") == activation.values_at("prefix", "type") }
+    end
+
+    def stored_activations
+      [].tap { |stored| @storage.each_activated_recognizer { |dump| stored << dump } }
     end
 
-    # On Corpus.open, walk the stored activations and register each one
-    # on this corpus's classifier. Switches to a per-corpus classifier
-    # if any activations exist.
     def reapply_activated_recognizers!
-      return if @storage.activated_recognizer_count.zero?
+      use_activations(stored_activations)
+    end
+
+    # The classifier is a function of the activations: the base classifier
+    # when there are none, otherwise a private copy of it holding exactly
+    # them (so nothing leaks into a shared DEFAULT). Rebuilt only when the
+    # set changed, so the classifier keeps its cache.
+    def use_activations(activations)
+      return if activations == @activations
 
-      ensure_per_corpus_classifier!
-      @storage.each_activated_recognizer do |dump|
-        @classifier.register_recognizer(SynthesizedRecognizer.from_dump(dump))
+      @classifier = if activations.empty?
+        @base_classifier
+      else
+        @base_classifier.dup.tap do |c|
+          activations.each { |dump| c.register_recognizer(SynthesizedRecognizer.from_dump(dump)) }
+        end
       end
+      @activations = activations
     end
 
     def coerce(input)
@@ -409,10 +528,10 @@ module Iriq
       prefix = ""
       keying_host = effective_host(iri.host)
       hinted.map do |entry|
-        stats = @storage.position_stats(Position.path(host: keying_host, prefix: prefix))
+        position = Position.path(host: keying_host, prefix: prefix)
         out = entry.merge(
           prefix:         prefix,
-          classification: classify(entry, stats),
+          classification: classify(entry) { @storage.position_evidence(position, entry[:value]) },
         )
         prefix = "#{prefix}/#{placeholder(entry)}"
         out
@@ -437,28 +556,29 @@ module Iriq
     # position, the literal is almost always the better display.
     STABLE_VARIABLE_TYPES = %i[version locale currency boolean slug opaque_id].freeze
 
-    def classify(entry, stats)
+    # The block reads the position's PositionEvidence; a variable of a
+    # non-stable type is answered without it.
+    def classify(entry)
       variable = entry[:variable]
+      return :variable_identifier if variable && !STABLE_VARIABLE_TYPES.include?(entry[:type])
 
+      stats = yield
       return variable ? :variable_identifier : :ambiguous if stats.nil? || stats.total.zero?
-      if variable && !STABLE_VARIABLE_TYPES.include?(entry[:type])
-        return :variable_identifier
-      end
 
-      value            = entry[:value]
       total            = stats.total
       variable_frac    = stats.variable_fraction(@classifier)
       cardinality_frac = stats.cardinality.to_f / total
       enough_data      = total >= MIN_OBSERVATIONS_FOR_INFERENCE
-      value_frac       = stats.value_fraction(value)
+      value_frac       = stats.value_fraction
 
       # For STABLE_VARIABLE_TYPES (version, locale, currency, boolean),
       # a dominant value wins over the variable-dominance branch — a
       # single-version /api/v1/... pattern stays as the literal `v1`
-      # rather than placeholdering to {version}. Without dominance,
-      # fall through to :variable_identifier (the per-type placeholder).
+      # rather than placeholdering to {version}. Without dominance, or
+      # without enough observations to call anything dominant (one sample
+      # is always 100%), fall through to :variable_identifier.
       if variable
-        return :stable_literal if value_frac >= STABLE_LITERAL_THRESHOLD
+        return :stable_literal if enough_data && value_frac >= STABLE_LITERAL_THRESHOLD
 
         return :variable_identifier
       end
@@ -466,7 +586,7 @@ module Iriq
       if enough_data && variable_frac >= VARIABLE_DOMINANCE_THRESHOLD
         # Position is dominated by variable types (UUIDs, integers, etc.).
         # A literal here is a special-case outlier (e.g. /users/me).
-        stats.value_counts.key?(value) ? :rare_literal : :ambiguous
+        stats.value_count ? :rare_literal : :ambiguous
       elsif value_frac >= STABLE_LITERAL_THRESHOLD
         # This specific value dominates — preserve it regardless of how
         # diverse the rest of the position is.
@@ -476,10 +596,10 @@ module Iriq
         # recognize values that dramatically exceed the uniform baseline as
         # "popular outliers" (e.g. /workspaces/mainspace surviving in a slot
         # full of one-shot user-created workspace names).
-        popular_outlier?(stats, value) ? :stable_literal : :corpus_inferred_variable
+        popular_outlier?(stats) ? :stable_literal : :corpus_inferred_variable
       elsif stats.cardinality == 1
         :stable_literal
-      elsif stats.value_counts.key?(value)
+      elsif stats.value_count
         :rare_literal
       else
         :ambiguous
@@ -493,28 +613,25 @@ module Iriq
         stats.cardinality >= MIN_CARDINALITY_FOR_INFERENCE
     end
 
-    def popular_outlier?(stats, value)
-      count = stats.value_counts[value] || 0
-      return false if count < POPULAR_MIN_COUNT
+    def popular_outlier?(stats)
+      return false if (stats.value_count || 0) < POPULAR_MIN_COUNT
 
       baseline = 1.0 / stats.cardinality
-      stats.value_fraction(value) >= POPULAR_BASELINE_MULTIPLE * baseline
+      stats.value_fraction >= POPULAR_BASELINE_MULTIPLE * baseline
     end
 
-    def inferred_param_type(cluster, name, value)
-      # Prefer the cluster's confident type when we have enough samples;
-      # otherwise classify the current value directly. Cluster#param_type
-      # applies the :date quorum gate (see Cluster::DATE_CONFIDENCE_THRESHOLD).
-      stats = cluster && cluster.param_stats[name]
-      if stats && stats.total >= MIN_OBSERVATIONS_FOR_INFERENCE
-        cluster.param_type(name) || @classifier.classify(value)
-      else
-        @classifier.classify(value)
+    # Dates and currencies print in canonical form (ISO date, upper-case code)
+    # rather than as a placeholder — same as mechanical normalize. nil when
+    # the value isn't one.
+    def canonical_form(type, value)
+      case type
+      when :date     then SegmentClassifier.canonical_date(value)
+      when :currency then SegmentClassifier.canonical_currency(value)
       end
     end
 
     def render_param_value(value, type)
-      if type == :date && (canon = SegmentClassifier.canonical_date(value))
+      if (canon = canonical_form(type, value))
         canon
       elsif @classifier.variable?(type)
         "{#{SegmentClassifier.display_type(type)}}"
@@ -523,27 +640,29 @@ module Iriq
       end
     end
 
-    def corpus_token(entry)
+    def corpus_token(entry, hints)
+      if (canon = canonical_form(entry[:type], entry[:value]))
+        return canon
+      end
+
       case entry[:classification]
       when :variable_identifier, :corpus_inferred_variable
-        placeholder_for_variable(entry)
+        placeholder_for_variable(entry, hints)
       else
         entry[:value]
       end
     end
 
-    def placeholder_for_variable(entry)
-      # Dates render in canonical ISO form rather than as a `{date}` placeholder
-      # — matches what mechanical Iriq.normalize does for path segments and
-      # what render_param_value does for query params.
-      if entry[:type] == :date && (canon = SegmentClassifier.canonical_date(entry[:value]))
-        return canon
+    def placeholder_for_variable(entry, hints)
+      if entry[:variable]
+        return "{#{(hints && entry[:hint]) || SegmentClassifier.display_type(entry[:type])}}"
       end
-      return "{#{entry[:hint] || SegmentClassifier.display_type(entry[:type])}}" if entry[:variable]
 
       # corpus-inferred variable: classifier said literal, corpus says
-      # otherwise. Derive a hint from the prefix's last literal segment if
-      # we can.
+      # otherwise. There's no type to show, so without hints it's {value};
+      # with hints, name it after the prefix's last literal segment.
+      return "{value}" unless hints
+
       last_literal = entry[:prefix].split("/").reject(&:empty?).reject { |s| s.start_with?("{") }.last
       base = last_literal ? Inflector.singularize(last_literal) : nil
       base ? "{#{base}}" : "{value}"
@@ -575,9 +694,7 @@ module Iriq
     private
 
     def write_json_dump(path)
-      tmp = "#{path}.tmp"
-      File.write(tmp, JSON.generate(memory_view.to_dump))
-      File.rename(tmp, path)
+      Storage.write_atomically(path, JSON.generate(memory_view.to_dump))
     end
 
     # Materialize a Memory snapshot of the current state — used by dump for

data/lib/iriq/errors.rb

@@ -1,4 +1,13 @@
 module Iriq
   class Error < StandardError; end
   class ParseError < Error; end
+  # A corpus iriq can't use: unrecognized, from a newer iriq, or failing to
+  # open, read or write. The message is `corpus PATH: reason`.
+  class CorpusError < Error; end
+
+  # An OS error in the words Rust's io::Error uses, `Permission denied (os
+  # error 13)`, without Ruby's ` @ rb_sysopen - PATH` suffix.
+  def self.os_error_message(error)
+    "#{SystemCallError.new(nil, error.errno).message} (os error #{error.errno})"
+  end
 end

data/lib/iriq/identifier.rb

@@ -37,7 +37,7 @@ module Iriq
     # Unicode display form (no punycode / percent-encoding pass).
     def canonical
       if urn?
-        "urn:#{nss}"
+        "#{scheme}:#{nss}"
       else
         out = +""
         out << "#{scheme}://" if scheme

data/lib/iriq/normalizer.rb

@@ -70,25 +70,28 @@ module Iriq
 
     def render_query(iri, classifier)
       iri.query_params.keys.sort.map do |k|
-        v    = iri.query_params[k]
-        type = classifier.classify(v.to_s)
-        # Param-name hint can lift a generic literal/opaque_id/slug into
-        # a semantic type — `?phone=unknown` becomes `{phone}`.
-        if (hint = SegmentClassifier.param_name_hint(k, type))
-          type = hint
-        end
-        shaped =
-          if type == :date && (canon = SegmentClassifier.canonical_date(v.to_s))
-            canon
-          elsif type == :currency && (canon = SegmentClassifier.canonical_currency(v.to_s))
-            canon
-          elsif classifier.variable?(type)
-            "{#{SegmentClassifier.display_type(type)}}"
-          else
-            v
-          end
-        "#{k}=#{shaped}"
+        "#{k}=#{render_param(k, iri.query_params[k], classifier)}"
       end.join("&")
     end
+
+    # One param's mechanical rendering. Corpus#render_query delegates here for
+    # params it lacks evidence on, so the two paths can't drift.
+    def render_param(name, value, classifier)
+      type = classifier.classify(value.to_s)
+      # Param-name hint can lift a generic literal/opaque_id/slug into
+      # a semantic type — `?phone=unknown` becomes `{phone}`.
+      if (hint = SegmentClassifier.param_name_hint(name, type))
+        type = hint
+      end
+      if type == :date && (canon = SegmentClassifier.canonical_date(value.to_s))
+        canon
+      elsif type == :currency && (canon = SegmentClassifier.canonical_currency(value.to_s))
+        canon
+      elsif classifier.variable?(type)
+        "{#{SegmentClassifier.display_type(type)}}"
+      else
+        value
+      end
+    end
   end
 end

data/lib/iriq/observation.rb

@@ -1,13 +1,18 @@
 module Iriq
   # The result of Corpus#observe. Lightweight value object — heavy work
-  # (explanation, normalization) is deferred until you ask.
+  # (cluster load, explanation, normalization) is deferred until you ask.
   class Observation
-    attr_reader :identifier, :cluster
+    attr_reader :identifier
 
-    def initialize(corpus:, identifier:, cluster:)
-      @corpus     = corpus
-      @identifier = identifier
-      @cluster    = cluster
+    def initialize(corpus:, identifier:, cluster_key:)
+      @corpus      = corpus
+      @identifier  = identifier
+      @cluster_key = cluster_key
+    end
+
+    # The cluster as it stands when first read; observing doesn't load it.
+    def cluster
+      @cluster ||= @corpus.storage.cluster_for(@cluster_key)
     end
 
     def fingerprint

data/lib/iriq/parser.rb

@@ -44,7 +44,11 @@ module Iriq
           parse_authority_url(input, scheme, rest[2..])
         else
           # opaque scheme like mailto:foo@bar — keep nss, mark as urn-ish so we
-          # don't pretend we know its host/path layout.
+          # don't pretend we know its host/path layout. A bare scheme with no
+          # content ("mailto:") carries no identifier — and would canonicalize
+          # to "urn:", which itself fails to parse — so reject it.
+          raise ParseError, "opaque scheme missing content" if rest.empty?
+
           Identifier.new(original: input, scheme: scheme, nss: rest, kind: :urn)
         end
       else

data/lib/iriq/position_evidence.rb

@@ -0,0 +1,31 @@
+module Iriq
+  # The slice of a position's stats that classifying one value reads
+  # (Corpus#classify). A backend can answer it without materializing every
+  # value tracked at the position.
+  PositionEvidence = Struct.new(:total, :type_counts, :cardinality, :value_count, keyword_init: true) do
+    # value_count is nil when the value isn't tracked (never seen, or dropped
+    # at the cap).
+    def self.from_stats(stats, value)
+      new(
+        total:       stats.total,
+        type_counts: stats.type_counts,
+        cardinality: stats.cardinality,
+        value_count: stats.value_counts.fetch(value, nil),
+      )
+    end
+
+    # Same as PositionStats#variable_fraction.
+    def variable_fraction(classifier)
+      return 0.0 if total.zero?
+
+      type_counts.sum { |t, c| classifier.variable?(t) ? c : 0 }.to_f / total
+    end
+
+    # Same as PositionStats#value_fraction for the probed value.
+    def value_fraction
+      return 0.0 if total.zero?
+
+      (value_count || 0).to_f / total
+    end
+  end
+end