iriq 0.2.0 → 0.30.2

data/lib/iriq/specificity.rb

@@ -0,0 +1,35 @@
+module Iriq
+  # Per-Recognizer claim strength. Higher specificity wins when multiple
+  # Recognizers fire on the same segment; the ensemble picks the
+  # max(specificity × confidence).
+  #
+  # The bands below capture the current type taxonomy at coarse-grain:
+  # they're explicitly NOT linear "how confident" scores. They encode "how
+  # surprising would it be for this Recognizer to fire by accident on a
+  # different actual type." UUID's shape is so distinctive that a non-UUID
+  # producing that string is vanishingly unlikely (SEMANTIC); a 4-digit
+  # integer could plausibly be a year, an HTTP status, or an ID, so
+  # `:integer` claims only TYPED.
+  #
+  # Calibration corpus tests in spec/iriq/calibration_spec.rb / Go's
+  # calibration_test.go are the source of truth for whether these
+  # values are well-chosen — adjust them and re-run to validate.
+  module Specificity
+    # Unambiguous semantic shapes — the regex effectively can't fire by
+    # accident. (UUID, JWT, email with @, URL with ://, color hex.)
+    SEMANTIC   = 1.0
+    # Restrictive structured patterns. Could collide with broader types
+    # at edges. (date, file with known ext, ipv4, mime.)
+    STRUCTURED = 0.8
+    # Digit-shaped with an additional bound — range or allowlist — that
+    # makes the shape alone meaningful. (timestamp, currency, country,
+    # boolean.)
+    BOUNDED    = 0.7
+    # Lexically broad but typed. (integer, float, version.)
+    TYPED      = 0.5
+    # Generic pattern-based shape. (slug.)
+    PATTERN    = 0.3
+    # Generic fallback shapes. (literal, opaque_id.)
+    FALLBACK   = 0.1
+  end
+end

data/lib/iriq/storage/memory.rb

@@ -9,11 +9,15 @@ module Iriq
     #   increment_path_length(length)
     #   increment_raw_shape(shape)
     #   increment_fingerprint(shape)
-    #   observe_position(host, prefix, value, type)
+    #   observe_position(position, value, type)        # position is Iriq::Position
     #   add_to_cluster(key, host, scheme, shape, identifier)
+    #   record_observation(canonical)                  # append to source-IRI log
     #
     #   host_counts / path_length_counts / raw_shape_counts / fingerprint_counts
-    #   position_stats(host, prefix)
+    #   position_stats(position)
+    #   each_position_stats { |position, stats| ... }
+    #   each_observed_iri { |canonical| ... }
+    #   clear_materialized_views                       # for reinfer
     #   clusters / cluster_size
     #
     #   transaction { ... }    # backends may batch within
@@ -36,6 +40,15 @@ module Iriq
         @fingerprint_counts      = Hash.new(0)
         @position_stats          = {}
         @clusters                = {}
+        # The source-IRI log. Persisted alongside materialized views; the
+        # log is the source of truth, the views are derived. Corpus#reinfer
+        # drops the views and replays the log through events + reducers.
+        @observed_iris           = []
+        # Recognizers promoted from RecognizerProposal via
+        # Corpus#activate_proposal. Stored as {prefix, type, specificity}
+        # hashes so reopens can re-synthesize them onto the corpus's
+        # classifier.
+        @activated_recognizers   = []
       end
 
       def transaction
@@ -70,17 +83,61 @@ module Iriq
         @fingerprint_counts[shape] += 1
       end
 
-      def observe_position(host, prefix, value, type)
-        stats = @position_stats[[host, prefix]] ||= PositionStats.new(max_values: @max_values_per_position)
+      def observe_position(position, value, type)
+        stats = @position_stats[position] ||= PositionStats.new(max_values: @max_values_per_position)
         stats.observe(value, type)
       end
 
       def add_to_cluster(key, host, scheme, shape, identifier)
-        cluster = @clusters[key] ||= Cluster.new(key: key, host: host, scheme: scheme, shape: shape)
-        cluster.add(identifier)
+        cluster = @clusters[key] ||= Cluster.new(
+          key: key, host: host, scheme: scheme, shape: shape,
+          max_values: @max_values_per_position,
+        )
+        cluster.add(identifier, classifier: @classifier)
         cluster
       end
 
+      # Append a canonical IRI to the source-IRI log. Called by Corpus#observe
+      # after the event reducers have applied; the log is the source of truth
+      # that Corpus#reinfer replays.
+      def record_observation(canonical)
+        @observed_iris << canonical
+      end
+
+      def each_observed_iri(&block)
+        @observed_iris.each(&block)
+      end
+
+      def observed_iri_count
+        @observed_iris.size
+      end
+
+      # --- Activated recognizers (Corpus#activate_proposal) -----------------
+
+      def record_activated_recognizer(dump)
+        @activated_recognizers << dump
+      end
+
+      def each_activated_recognizer(&block)
+        @activated_recognizers.each(&block)
+      end
+
+      def activated_recognizer_count
+        @activated_recognizers.size
+      end
+
+      # Drop every materialized view (host_counts, position_stats, clusters,
+      # …) without touching the source-IRI log. Corpus#reinfer calls this
+      # before replaying the log so views rebuild from scratch.
+      def clear_materialized_views
+        @host_counts        = Hash.new(0)
+        @path_length_counts = Hash.new(0)
+        @raw_shape_counts   = Hash.new(0)
+        @fingerprint_counts = Hash.new(0)
+        @position_stats     = {}
+        @clusters           = {}
+      end
+
       # --- Reads ------------------------------------------------------------
 
       def host_counts;        @host_counts;        end
@@ -88,8 +145,8 @@ module Iriq
       def raw_shape_counts;   @raw_shape_counts;   end
       def fingerprint_counts; @fingerprint_counts; end
 
-      def position_stats(host, prefix)
-        @position_stats[[host, prefix]]
+      def position_stats(position)
+        @position_stats[position]
       end
 
       def each_position_stats(&block)
@@ -104,6 +161,13 @@ module Iriq
         @clusters.size
       end
 
+      # O(1) lookup by cluster key — used by Corpus#normalize to pull the
+      # cluster's param_stats for the URL being normalized. nil if no cluster
+      # has been observed under this key yet.
+      def cluster_for(key)
+        @clusters[key]
+      end
+
       # --- Bulk load (used by JSON backend) --------------------------------
 
       def load_dump!(h)
@@ -112,11 +176,14 @@ module Iriq
         @raw_shape_counts   = Hash.new(0).merge(h["raw_shape_counts"])
         @fingerprint_counts = Hash.new(0).merge(h["fingerprint_counts"])
         @max_values_per_position = h.fetch("max_values_per_position", PositionStats::DEFAULT_MAX_VALUES)
-        @position_stats = h["position_stats"].each_with_object({}) do |(host, prefix, sdump), acc|
-          acc[[host, prefix]] = PositionStats.from_dump(sdump)
+        @position_stats = h["position_stats"].each_with_object({}) do |entry, acc|
+          position = Position.from_dump(entry["position"])
+          acc[position] = PositionStats.from_dump(entry["stats"])
         end
         cdump = h.fetch("clusterer", { "clusters" => {} })
-        @clusters = cdump["clusters"].transform_values { |c| Cluster.from_dump(c) }
+        @clusters = cdump["clusters"].transform_values { |c| Cluster.from_dump(c, max_values: @max_values_per_position) }
+        @observed_iris         = h.fetch("observed_iris", [])
+        @activated_recognizers = h.fetch("activated_recognizers", [])
         self
       end
 
@@ -127,10 +194,14 @@ module Iriq
           "raw_shape_counts"        => @raw_shape_counts,
           "fingerprint_counts"      => @fingerprint_counts,
           "max_values_per_position" => @max_values_per_position,
-          "position_stats"          => @position_stats.map { |(host, prefix), s| [host, prefix, s.dump] },
+          "position_stats"          => @position_stats.map { |pos, s|
+            { "position" => pos.to_dump, "stats" => s.dump }
+          },
           "clusterer"               => {
             "clusters" => @clusters.transform_values(&:dump),
           },
+          "observed_iris"           => @observed_iris,
+          "activated_recognizers"   => @activated_recognizers,
         }
       end
     end

data/lib/iriq/storage/sqlite.rb

@@ -11,7 +11,7 @@ module Iriq
     # the existing `iriq --corpus c.db <url>` pattern works without a flock
     # at the application layer.
     class Sqlite
-      SCHEMA_VERSION = 1
+      SCHEMA_VERSION = 4
 
       SCHEMA = <<~SQL.freeze
         CREATE TABLE IF NOT EXISTS meta (
@@ -34,25 +34,33 @@ module Iriq
           shape TEXT PRIMARY KEY,
           count INTEGER NOT NULL
         );
+        -- Position is (host, scope, locator). For scope='path' the locator
+        -- is the typed prefix; for scope='query' it's the param name.
+        -- Today only 'path' is observed here (query params live on the
+        -- cluster_* tables) — scope is in the schema so future commits
+        -- can fold query positions in without another migration.
         CREATE TABLE IF NOT EXISTS position_stats (
-          host   TEXT NOT NULL,
-          prefix TEXT NOT NULL,
-          total  INTEGER NOT NULL DEFAULT 0,
-          PRIMARY KEY (host, prefix)
+          host    TEXT NOT NULL,
+          scope   TEXT NOT NULL,
+          locator TEXT NOT NULL,
+          total   INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (host, scope, locator)
         );
         CREATE TABLE IF NOT EXISTS position_values (
-          host   TEXT NOT NULL,
-          prefix TEXT NOT NULL,
-          value  TEXT NOT NULL,
-          count  INTEGER NOT NULL,
-          PRIMARY KEY (host, prefix, value)
+          host    TEXT NOT NULL,
+          scope   TEXT NOT NULL,
+          locator TEXT NOT NULL,
+          value   TEXT NOT NULL,
+          count   INTEGER NOT NULL,
+          PRIMARY KEY (host, scope, locator, value)
         );
         CREATE TABLE IF NOT EXISTS position_types (
-          host   TEXT NOT NULL,
-          prefix TEXT NOT NULL,
-          type   TEXT NOT NULL,
-          count  INTEGER NOT NULL,
-          PRIMARY KEY (host, prefix, type)
+          host    TEXT NOT NULL,
+          scope   TEXT NOT NULL,
+          locator TEXT NOT NULL,
+          type    TEXT NOT NULL,
+          count   INTEGER NOT NULL,
+          PRIMARY KEY (host, scope, locator, type)
         );
         CREATE TABLE IF NOT EXISTS clusters (
           key    TEXT PRIMARY KEY,
@@ -75,6 +83,44 @@ module Iriq
           count       INTEGER NOT NULL,
           PRIMARY KEY (cluster_key, position, value)
         );
+        CREATE TABLE IF NOT EXISTS cluster_params (
+          cluster_key TEXT NOT NULL,
+          name        TEXT NOT NULL,
+          total       INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (cluster_key, name)
+        );
+        CREATE TABLE IF NOT EXISTS cluster_param_values (
+          cluster_key TEXT NOT NULL,
+          name        TEXT NOT NULL,
+          value       TEXT NOT NULL,
+          count       INTEGER NOT NULL,
+          PRIMARY KEY (cluster_key, name, value)
+        );
+        CREATE TABLE IF NOT EXISTS cluster_param_types (
+          cluster_key TEXT NOT NULL,
+          name        TEXT NOT NULL,
+          type        TEXT NOT NULL,
+          count       INTEGER NOT NULL,
+          PRIMARY KEY (cluster_key, name, type)
+        );
+        -- Source-IRI log. The materialized views above are derived from
+        -- this log via events + reducers. Corpus#reinfer drops the views
+        -- and replays the log to rebuild them. id is monotonic so
+        -- iteration order is observation order.
+        CREATE TABLE IF NOT EXISTS observed_iris (
+          id        INTEGER PRIMARY KEY AUTOINCREMENT,
+          canonical TEXT NOT NULL
+        );
+        -- Recognizers promoted from RecognizerProposal via
+        -- Corpus#activate_proposal. Re-applied to the corpus's
+        -- classifier on Corpus.open so a reopen picks up its learned
+        -- patterns. Keyed by prefix; activating the same prefix twice
+        -- is a no-op.
+        CREATE TABLE IF NOT EXISTS activated_recognizers (
+          prefix      TEXT PRIMARY KEY,
+          type        TEXT NOT NULL,
+          specificity REAL NOT NULL DEFAULT 1.0
+        );
       SQL
 
       attr_reader :path, :max_values_per_position
@@ -188,36 +234,38 @@ module Iriq
         upsert_shape("fingerprint_counts", shape)
       end
 
-      def observe_position(host, prefix, value, type)
-        host ||= ""
-        @db.execute(<<~SQL, [host, prefix])
-          INSERT INTO position_stats (host, prefix, total) VALUES (?, ?, 1)
-          ON CONFLICT(host, prefix) DO UPDATE SET total = total + 1
+      def observe_position(position, value, type)
+        host    = position.host || ""
+        scope   = position.scope.to_s
+        locator = position.locator
+        @db.execute(<<~SQL, [host, scope, locator])
+          INSERT INTO position_stats (host, scope, locator, total) VALUES (?, ?, ?, 1)
+          ON CONFLICT(host, scope, locator) DO UPDATE SET total = total + 1
         SQL
 
         # Type counts are unbounded — always upsert.
-        @db.execute(<<~SQL, [host, prefix, type.to_s])
-          INSERT INTO position_types (host, prefix, type, count) VALUES (?, ?, ?, 1)
-          ON CONFLICT(host, prefix, type) DO UPDATE SET count = count + 1
+        @db.execute(<<~SQL, [host, scope, locator, type.to_s])
+          INSERT INTO position_types (host, scope, locator, type, count) VALUES (?, ?, ?, ?, 1)
+          ON CONFLICT(host, scope, locator, type) DO UPDATE SET count = count + 1
         SQL
 
         # Value counts are capped at max_values_per_position. If the value
         # already exists, increment it; otherwise insert only when
         # cardinality is below the cap. Two-step rather than ON CONFLICT
         # because we need to enforce the cap on insert.
-        @db.execute(<<~SQL, [host, prefix, value])
+        @db.execute(<<~SQL, [host, scope, locator, value])
           UPDATE position_values SET count = count + 1
-          WHERE host = ? AND prefix = ? AND value = ?
+          WHERE host = ? AND scope = ? AND locator = ? AND value = ?
         SQL
         if @db.changes.zero?
           card = @db.get_first_value(
-            "SELECT COUNT(*) FROM position_values WHERE host = ? AND prefix = ?",
-            [host, prefix],
+            "SELECT COUNT(*) FROM position_values WHERE host = ? AND scope = ? AND locator = ?",
+            [host, scope, locator],
           )
           if card < @max_values_per_position
             @db.execute(
-              "INSERT INTO position_values (host, prefix, value, count) VALUES (?, ?, ?, 1)",
-              [host, prefix, value],
+              "INSERT INTO position_values (host, scope, locator, value, count) VALUES (?, ?, ?, ?, 1)",
+              [host, scope, locator, value],
             )
           end
         end
@@ -251,9 +299,99 @@ module Iriq
           SQL
         end
 
+        # Per-param stats (presence + value cardinality + type) — mirrors the
+        # in-memory Cluster#add path. Value table respects the same per-key
+        # cap as position_values.
+        (identifier.query_params || {}).each do |name, value|
+          v = value.to_s
+          type = @classifier.classify(v).to_s
+
+          @db.execute(<<~SQL, [key, name])
+            INSERT INTO cluster_params (cluster_key, name, total) VALUES (?, ?, 1)
+            ON CONFLICT(cluster_key, name) DO UPDATE SET total = total + 1
+          SQL
+          @db.execute(<<~SQL, [key, name, type])
+            INSERT INTO cluster_param_types (cluster_key, name, type, count) VALUES (?, ?, ?, 1)
+            ON CONFLICT(cluster_key, name, type) DO UPDATE SET count = count + 1
+          SQL
+
+          @db.execute(<<~SQL, [key, name, v])
+            UPDATE cluster_param_values SET count = count + 1
+            WHERE cluster_key = ? AND name = ? AND value = ?
+          SQL
+          if @db.changes.zero?
+            card = @db.get_first_value(
+              "SELECT COUNT(*) FROM cluster_param_values WHERE cluster_key = ? AND name = ?",
+              [key, name],
+            )
+            if card < @max_values_per_position
+              @db.execute(
+                "INSERT INTO cluster_param_values (cluster_key, name, value, count) VALUES (?, ?, ?, 1)",
+                [key, name, v],
+              )
+            end
+          end
+        end
+
         load_cluster(key)
       end
 
+      # Append a canonical IRI to the source-IRI log. Inside the same
+      # transaction as the event reducers, so the log and views stay
+      # consistent.
+      def record_observation(canonical)
+        @db.execute("INSERT INTO observed_iris (canonical) VALUES (?)", [canonical])
+      end
+
+      def each_observed_iri
+        @db.execute("SELECT canonical FROM observed_iris ORDER BY id") do |row|
+          yield row[0]
+        end
+      end
+
+      def observed_iri_count
+        @db.get_first_value("SELECT COUNT(*) FROM observed_iris") || 0
+      end
+
+      # --- Activated recognizers --------------------------------------------
+
+      def record_activated_recognizer(dump)
+        @db.execute(<<~SQL, [dump["prefix"], dump["type"], dump.fetch("specificity", 1.0)])
+          INSERT INTO activated_recognizers (prefix, type, specificity) VALUES (?, ?, ?)
+          ON CONFLICT(prefix) DO UPDATE SET type = excluded.type, specificity = excluded.specificity
+        SQL
+      end
+
+      def each_activated_recognizer
+        @db.execute("SELECT prefix, type, specificity FROM activated_recognizers ORDER BY prefix") do |row|
+          yield({ "prefix" => row[0], "type" => row[1], "specificity" => row[2] })
+        end
+      end
+
+      def activated_recognizer_count
+        @db.get_first_value("SELECT COUNT(*) FROM activated_recognizers") || 0
+      end
+
+      # Drop every materialized view without touching the source-IRI log.
+      # Corpus#reinfer calls this before replaying the log.
+      def clear_materialized_views
+        @db.execute_batch(<<~SQL)
+          DELETE FROM host_counts;
+          DELETE FROM path_length_counts;
+          DELETE FROM raw_shape_counts;
+          DELETE FROM fingerprint_counts;
+          DELETE FROM position_stats;
+          DELETE FROM position_values;
+          DELETE FROM position_types;
+          DELETE FROM clusters;
+          DELETE FROM cluster_examples;
+          DELETE FROM cluster_segments;
+          DELETE FROM cluster_params;
+          DELETE FROM cluster_param_values;
+          DELETE FROM cluster_param_types;
+        SQL
+      end
+
       # --- Reads ------------------------------------------------------------
 
       def host_counts
@@ -274,10 +412,13 @@ module Iriq
         rows_to_count_hash("fingerprint_counts", "shape")
       end
 
-      def position_stats(host, prefix)
-        host ||= ""
+      def position_stats(position)
+        host    = position.host || ""
+        scope   = position.scope.to_s
+        locator = position.locator
         total = @db.get_first_value(
-          "SELECT total FROM position_stats WHERE host = ? AND prefix = ?", [host, prefix],
+          "SELECT total FROM position_stats WHERE host = ? AND scope = ? AND locator = ?",
+          [host, scope, locator],
         )
         return nil if total.nil?
 
@@ -286,13 +427,15 @@ module Iriq
 
         vc = Hash.new(0)
         @db.execute(
-          "SELECT value, count FROM position_values WHERE host = ? AND prefix = ?", [host, prefix]
+          "SELECT value, count FROM position_values WHERE host = ? AND scope = ? AND locator = ?",
+          [host, scope, locator],
         ) { |r| vc[r[0]] = r[1] }
         stats.instance_variable_set(:@value_counts, vc)
 
         tc = Hash.new(0)
         @db.execute(
-          "SELECT type, count FROM position_types WHERE host = ? AND prefix = ?", [host, prefix]
+          "SELECT type, count FROM position_types WHERE host = ? AND scope = ? AND locator = ?",
+          [host, scope, locator],
         ) { |r| tc[r[0].to_sym] = r[1] }
         stats.instance_variable_set(:@type_counts, tc)
 
@@ -301,10 +444,13 @@ module Iriq
 
       def each_position_stats
         seen = []
-        @db.execute("SELECT DISTINCT host, prefix FROM position_stats ORDER BY ROWID") do |row|
+        @db.execute("SELECT DISTINCT host, scope, locator FROM position_stats ORDER BY ROWID") do |row|
           seen << row
         end
-        seen.each { |host, prefix| yield [host, prefix], position_stats(host, prefix) }
+        seen.each do |host, scope, locator|
+          pos = Position.new(host: host, scope: scope.to_sym, locator: locator)
+          yield pos, position_stats(pos)
+        end
       end
 
       def clusters
@@ -319,6 +465,10 @@ module Iriq
         @db.get_first_value("SELECT COUNT(*) FROM clusters")
       end
 
+      def cluster_for(key)
+        load_cluster(key)
+      end
+
       private
 
       def upsert_shape(table, shape)
@@ -340,7 +490,10 @@ module Iriq
         )
         return nil unless row
 
-        c = Cluster.new(key: row[0], host: row[1], scheme: row[2], shape: row[3])
+        c = Cluster.new(
+          key: row[0], host: row[1], scheme: row[2], shape: row[3],
+          max_values: @max_values_per_position,
+        )
         c.instance_variable_set(:@count, row[4])
 
         examples = []
@@ -360,6 +513,32 @@ module Iriq
         end
         c.instance_variable_set(:@segment_counts, seg_counts)
 
+        # Rebuild @param_stats from the three cluster_param_* tables.
+        params = {}
+        @db.execute(
+          "SELECT name, total FROM cluster_params WHERE cluster_key = ?", [key],
+        ) do |r|
+          # PositionStats.new already initializes empty Hash.new(0) for value
+          # and type counts; only @total needs filling here. The followup
+          # SELECTs below populate value/type rows in place.
+          stats = PositionStats.new(max_values: @max_values_per_position)
+          stats.instance_variable_set(:@total, r[1])
+          params[r[0]] = stats
+        end
+        @db.execute(
+          "SELECT name, value, count FROM cluster_param_values WHERE cluster_key = ?", [key],
+        ) do |r|
+          stats = params[r[0]] or next
+          stats.value_counts[r[1]] = r[2]
+        end
+        @db.execute(
+          "SELECT name, type, count FROM cluster_param_types WHERE cluster_key = ?", [key],
+        ) do |r|
+          stats = params[r[0]] or next
+          stats.type_counts[r[1].to_sym] = r[2]
+        end
+        c.instance_variable_set(:@param_stats, params)
+
         c
       end
     end

data/lib/iriq/synthesized_recognizer.rb

@@ -0,0 +1,56 @@
+module Iriq
+  # Recognizer built dynamically from a learned-prefix pattern.
+  #
+  # Used by Corpus#activate_proposal to promote a RecognizerProposal
+  # into a live Recognizer that the classifier ensemble consults. Same
+  # shape as the built-in Recognizers — uuid, date, integer — but the
+  # pattern + type are supplied at construction instead of compiled-in.
+  #
+  #   r = SynthesizedRecognizer.new(prefix: "ghp_", type: :ghp)
+  #   r.try("ghp_abcdef123")  # → {type: :ghp, confidence: 1.0, specificity: 1.0}
+  #
+  # Pattern: `<prefix><[A-Za-z0-9]+>` — anchored, alphanumeric suffix
+  # only. Matches the same shape PrefixUnderscoreId proposes from, so
+  # round-trip (propose → activate → reinfer) reclassifies the same
+  # values the proposal was derived from.
+  #
+  # Specificity defaults to SEMANTIC. A learned prefix is very specific
+  # by construction (a distinctive literal prefix that recurred enough
+  # to clear the proposal noise floor) — calling it as confident as a
+  # built-in UUID is reasonable.
+  class SynthesizedRecognizer < Recognizer
+    attr_reader :prefix, :type, :specificity
+
+    def self.from_proposal(proposal)
+      new(prefix: proposal.prefix, type: proposal.suggested_type)
+    end
+
+    def initialize(prefix:, type:, specificity: Specificity::SEMANTIC)
+      raise ArgumentError, "prefix must be a non-empty string" if prefix.nil? || prefix.empty?
+      raise ArgumentError, "type must be a symbol" unless type.is_a?(Symbol)
+
+      @prefix      = prefix
+      @type        = type
+      @specificity = specificity
+      @pattern     = /\A#{Regexp.escape(prefix)}[A-Za-z0-9]+\z/.freeze
+    end
+
+    def try(segment)
+      return nil unless segment.start_with?(@prefix) && @pattern.match?(segment)
+
+      { type: @type, confidence: 1.0, specificity: @specificity }
+    end
+
+    def to_dump
+      { "prefix" => @prefix, "type" => @type.to_s, "specificity" => @specificity }
+    end
+
+    def self.from_dump(h)
+      new(
+        prefix:      h["prefix"],
+        type:        h["type"].to_sym,
+        specificity: h.fetch("specificity", Specificity::SEMANTIC),
+      )
+    end
+  end
+end