iriq 0.30.2 → 0.33.0

data/lib/iriq/cluster.rb

@@ -30,14 +30,35 @@ module Iriq
     NUMBER_CONFIDENCE_THRESHOLD = 0.8
     NUMBER_SUBTYPE_THRESHOLD    = 0.8
 
+    # Param classification is a confidence ladder: constant → string → enum.
+    # A param with a single observed value is a constant (rendered as-is); one
+    # that varies but isn't yet a trustworthy enum is :string (a generic
+    # placeholder); a bounded, well-supported value set is :enum.
+    #
     # `:enum` thresholds. Promote a param to :enum when the corpus has seen
-    # enough samples to trust the bound, the value set is small, each value
-    # appears more than once (rules out singletons), and the tracked values
-    # account for nearly all observations (lets a few stragglers through).
+    # enough samples to trust the bound (ENUM_MIN_OBSERVATIONS), the *established*
+    # values — those seen at least ENUM_MIN_VALUE_COUNT times — are few
+    # (ENUM_MAX_CARDINALITY) and cover nearly all observations
+    # (ENUM_MIN_COVERAGE). Rare one-off values are stragglers, not
+    # disqualifiers: this is what keeps a single brand-new value from knocking
+    # an established enum back down (the observe-before-normalize case).
     ENUM_MIN_OBSERVATIONS = 20
     ENUM_MAX_CARDINALITY  = 10
-    ENUM_MIN_VALUE_COUNT  = 2
-    ENUM_MIN_COVERAGE     = 0.95
+    ENUM_MIN_VALUE_COUNT  = 3
+    ENUM_MIN_COVERAGE     = 0.9
+    # An enum is a bounded *set*: a single repeated value is a constant, not an
+    # enum, so it takes at least two established members to qualify.
+    ENUM_MIN_MEMBERS      = 2
+
+    # `:string` — a param that has taken on 2+ distinct non-typed values but
+    # isn't (yet) a confident enum. The intermediate rung: we know it varies
+    # and looks like free-form text, but haven't earned the bounded-set claim.
+    STRING_MIN_DISTINCT = 2
+
+    # Confidence smoothing constant. confidence = total / (total + K): a
+    # monotone curve that is 0.5 at K observations and asymptotes to 1.0. The
+    # type names our guess; this number says how much evidence backs it.
+    CONFIDENCE_SMOOTHING = 15
 
     def initialize(key:, host:, scheme:, shape:, max_values: PositionStats::DEFAULT_MAX_VALUES)
       @key            = key
@@ -72,7 +93,8 @@ module Iriq
       return unless identifier.query_params
       identifier.query_params.each do |name, value|
         stats = @param_stats[name] ||= PositionStats.new(max_values: @max_values)
-        stats.observe(value.to_s, classifier.classify(value.to_s))
+        value_s = value.to_s
+        stats.observe(value_s, classifier.classify(value_s))
       end
     end
 
@@ -105,7 +127,9 @@ module Iriq
     end
 
     # Per-param summary, ordered by descending presence. Each entry is:
-    #   { name: "page", count: N, type: :integer, cardinality: K, presence: 0.83 }
+    #   { name: "page", count: N, type: :integer, confidence: 0.83,
+    #     cardinality: K, presence: 0.83 }
+    # confidence is how much evidence backs the type (see param_confidence);
     # presence is count / @count — the fraction of observations that had
     # this param.
     def param_summary
@@ -118,6 +142,7 @@ module Iriq
           name:        name,
           count:       stats.total,
           type:        type,
+          confidence:  param_confidence(stats),
           cardinality: stats.cardinality,
           presence:    @count.positive? ? stats.total.to_f / @count : 0.0,
         }
@@ -205,6 +230,11 @@ module Iriq
         return hint
       end
 
+      # :string rung — a literal-valued param that has taken on more than one
+      # distinct value varies, so it's a placeholder, not a fixed constant.
+      # Below the enum bar (checked above), so we claim only "free-form text".
+      return :string if type == :literal && stats.cardinality >= STRING_MIN_DISTINCT
+
       type
     end
 
@@ -239,21 +269,37 @@ module Iriq
     end
 
     # True when stats shows a bounded set of repeated values worth treating
-    # as an enum. See ENUM_* constants at the top of this class.
+    # as an enum. Built around the *established* members (values seen at least
+    # ENUM_MIN_VALUE_COUNT times) so a stray one-off value is a straggler, not
+    # a disqualifier. See ENUM_* constants at the top of this class.
     def enum?(stats)
       return false if stats.total < ENUM_MIN_OBSERVATIONS
-      return false if stats.cardinality.zero? || stats.cardinality > ENUM_MAX_CARDINALITY
-      return false if stats.value_counts.any? { |_, n| n < ENUM_MIN_VALUE_COUNT }
 
-      coverage = stats.value_counts.values.sum.to_f / stats.total
+      established = established_values(stats)
+      return false unless established.size.between?(ENUM_MIN_MEMBERS, ENUM_MAX_CARDINALITY)
+
+      coverage = established.values.sum.to_f / stats.total
       coverage >= ENUM_MIN_COVERAGE
     end
 
-    # Distinct values tracked for this param, ordered by descending count
-    # (lex tie-break). Returned alongside :enum-typed rows in param_summary
-    # so verbose/explain consumers can render the value set.
+    # Values seen often enough to count as real members of the set (vs noise).
+    def established_values(stats)
+      stats.value_counts.select { |_, n| n >= ENUM_MIN_VALUE_COUNT }
+    end
+
+    # Confidence that the assigned type is right, given how much evidence backs
+    # it. Monotone in observation count; 0.5 at CONFIDENCE_SMOOTHING, → 1.0.
+    def param_confidence(stats)
+      return 0.0 if stats.total.zero?
+
+      (stats.total.to_f / (stats.total + CONFIDENCE_SMOOTHING)).round(2)
+    end
+
+    # The enum's member values — the established ones (seen enough to be real),
+    # ordered by descending count (lex tie-break). Stragglers are excluded so
+    # the advertised set is what the corpus is actually confident about.
     def enum_values(stats)
-      stats.value_counts.sort_by { |v, n| [-n, v] }.map(&:first)
+      established_values(stats).sort_by { |v, n| [-n, v] }.map(&:first)
     end
 
     # value_distribution returns the fraction of total observations each
@@ -357,8 +403,8 @@ module Iriq
       if iri.urn?
         ns, value = (iri.nss || "").split(":", 2)
         derived = value ? urn_value_shape(ns, value, classifier) : nil
-        key     = "urn:#{ns}:#{derived}"
-        [key, nil, "urn", key]
+        key     = "#{iri.scheme}:#{ns}:#{derived}"
+        [key, nil, iri.scheme, key]
       else
         shape ||= PathShape.new(classifier: classifier).for(iri.path_segments)
         effective_host = host.nil? ? iri.host : host

data/lib/iriq/clusterer.rb

@@ -47,17 +47,6 @@ module Iriq
       end
     end
 
-    def dump
-      { "clusters" => clusters.each_with_object({}) { |c, h| h[c.key] = c.dump } }
-    end
-
-    def self.from_dump(h, classifier: SegmentClassifier::DEFAULT)
-      c = new(classifier: classifier)
-      restored = h["clusters"].transform_values { |cdump| Cluster.from_dump(cdump) }
-      c.instance_variable_get(:@storage).instance_variable_set(:@clusters, restored)
-      c
-    end
-
     private
 
     def coerce(input)

data/lib/iriq/corpus.rb

@@ -232,8 +232,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 = [

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/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_stats.rb

@@ -79,8 +79,8 @@ module Iriq
     end
 
     # Most common type. On count ties, breaks lexicographically by type
-    # symbol name so the result is deterministic and matches Go's
-    # DominantType (Go's map iteration is randomized).
+    # symbol name so the result is deterministic and matches the Rust
+    # port's dominant_type regardless of map iteration order.
     def dominant_type
       best = nil
       best_count = -1

data/lib/iriq/recognizer.rb

@@ -32,7 +32,7 @@ module Iriq
     # mutually-exclusive on shape, so the ensemble is effectively a
     # short-circuit OR. As more Recognizers carve out of SegmentClassifier
     # they'll join the pool and the scoring becomes load-bearing.
-    def self.ensemble(segment, *recognizers)
+    def self.ensemble(segment, recognizers)
       best = nil
       best_score = -1.0
       recognizers.each do |r|

data/lib/iriq/recognizer_proposal.rb

@@ -115,7 +115,7 @@ module Iriq
             acc[:positions] << position
             acc[:hosts] << position.host
             # Collect every match; we'll sort + cap to a stable top-N at
-            # emission time so Ruby and Go produce identical samples
+            # emission time so Ruby and Rust produce identical samples
             # regardless of underlying Hash / map iteration order.
             acc[:matches] << value
           end
@@ -135,7 +135,7 @@ module Iriq
             hosts:             acc[:hosts],
             coverage:          coverage,
             observation_count: acc[:matching_count],
-            # Sort + cap to 5 so Ruby and Go produce identical samples
+            # Sort + cap to 5 so Ruby and Rust produce identical samples
             # regardless of underlying Hash / map iteration order. The
             # samples are illustrative for humans; alphabetical is fine.
             sample_values:     acc[:matches].sort.first(5),

data/lib/iriq/segment_classifier.rb

@@ -14,8 +14,10 @@ module Iriq
     #
     # `:enum` is similarly corpus-only — it surfaces when a position has a
     # bounded set of distinct values observed across enough samples (see
-    # Cluster::ENUM_* thresholds).
-    TYPES = %i[literal integer float number uuid date year timestamp hash slug
+    # Cluster::ENUM_* thresholds). `:string` is the rung below `:enum`: a
+    # param that varies across free-form literal values but isn't a confident
+    # bounded set yet. Neither is ever returned for a single value.
+    TYPES = %i[literal string integer float number uuid date year timestamp hash slug
                ipv4 ipv6 url email boolean version locale currency phone jwt mime
                file color coordinate country base64 http_status enum opaque_id].freeze
 
@@ -125,9 +127,10 @@ module Iriq
       document: %w[pdf doc docx xls xlsx ppt pptx odt ods odp rtf epub],
       data:     %w[csv tsv json xml yaml yml parquet sqlite db ndjson jsonl],
       text:     %w[txt md log markdown rst],
-      web:      %w[html htm css js mjs cjs ts jsx tsx],
+      web:      %w[html htm css js mjs cjs ts jsx tsx map],
+      font:     %w[woff woff2 ttf otf eot],
       audio:    %w[mp3 wav ogg flac aac m4a opus],
-      video:    %w[mp4 mov avi mkv webm flv wmv m4v],
+      video:    %w[mp4 mov avi mkv webm flv wmv m4v m3u8],
       archive:  %w[zip tar gz bz2 7z rar xz tgz],
       code:     %w[rb py go java c cc cpp h hpp sh swift kt rs],
     }.freeze
@@ -262,7 +265,7 @@ module Iriq
       # Scored ensemble over the live Recognizer list — built-ins +
       # anything Corpus#activate_proposal has registered for this
       # classifier instance.
-      if (v = Recognizer.ensemble(segment, *@recognizers))
+      if (v = Recognizer.ensemble(segment, @recognizers))
         return v[:type]
       end
 

data/lib/iriq/specificity.rb

@@ -11,9 +11,9 @@ module Iriq
   # 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.
+  # Calibration corpus tests in spec/iriq/calibration_spec.rb 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.)

data/lib/iriq/storage/sqlite.rb

@@ -141,7 +141,7 @@ module Iriq
         # concurrent open, and without busy_timeout set they fail
         # immediately with SQLITE_BUSY.
         @db.execute("PRAGMA busy_timeout = 30000")
-        @db.execute("PRAGMA journal_mode = WAL")
+        enable_wal!
         @db.execute("PRAGMA synchronous = NORMAL")
         @db.execute("PRAGMA foreign_keys = ON")
         @in_batch = false
@@ -151,8 +151,11 @@ module Iriq
         @db.execute_batch(SCHEMA)
         existing = @db.get_first_value("SELECT value FROM meta WHERE key = 'schema_version'")
         if existing.nil?
-          @db.execute("INSERT INTO meta (key, value) VALUES ('schema_version', ?)", SCHEMA_VERSION.to_s)
-          @db.execute("INSERT INTO meta (key, value) VALUES ('max_values_per_position', ?)",
+          # OR IGNORE: two processes can race to initialize a fresh corpus
+          # concurrently — both read schema_version as nil, and the loser's
+          # INSERT must not blow up on the PRIMARY KEY.
+          @db.execute("INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', ?)", SCHEMA_VERSION.to_s)
+          @db.execute("INSERT OR IGNORE INTO meta (key, value) VALUES ('max_values_per_position', ?)",
                       @max_values_per_position.to_s)
         else
           @max_values_per_position = (@db.get_first_value(
@@ -280,12 +283,18 @@ module Iriq
           ON CONFLICT(key) DO UPDATE SET count = count + 1
         SQL
 
-        # Examples — capped at Cluster::MAX_EXAMPLES.
+        # Examples — capped at Cluster::MAX_EXAMPLES, deduped by canonical
+        # (mirrors Cluster#add so the SQLite view matches the in-memory one).
+        canonical = identifier.canonical
         examples_count = @db.get_first_value(
           "SELECT COUNT(*) FROM cluster_examples WHERE cluster_key = ?", [key],
         )
-        if examples_count < Cluster::MAX_EXAMPLES
-          @db.execute(<<~SQL, [key, examples_count, identifier.canonical])
+        already_present = @db.get_first_value(
+          "SELECT 1 FROM cluster_examples WHERE cluster_key = ? AND canonical = ?",
+          [key, canonical],
+        )
+        if examples_count < Cluster::MAX_EXAMPLES && already_present.nil?
+          @db.execute(<<~SQL, [key, examples_count, canonical])
             INSERT INTO cluster_examples (cluster_key, position, canonical)
             VALUES (?, ?, ?)
           SQL
@@ -439,6 +448,7 @@ module Iriq
         ) { |r| tc[r[0].to_sym] = r[1] }
         stats.instance_variable_set(:@type_counts, tc)
 
+        recompute_numeric!(stats)
         stats
       end
 
@@ -471,6 +481,24 @@ module Iriq
 
       private
 
+      # Converting a rollback-mode database to WAL takes an exclusive lock,
+      # and SQLite does NOT consult the busy handler for that lock — so
+      # concurrent first-opens of a fresh corpus can fail with SQLITE_BUSY
+      # even with busy_timeout set. WAL is a persistent database property:
+      # retry briefly — either this connection wins the conversion or
+      # another process already converted the file.
+      def enable_wal!
+        attempts = 0
+        begin
+          @db.execute("PRAGMA journal_mode = WAL")
+        rescue SQLite3::BusyException
+          raise if (attempts += 1) > 100
+
+          sleep 0.01
+          retry
+        end
+      end
+
       def upsert_shape(table, shape)
         @db.execute(<<~SQL, shape)
           INSERT INTO #{table} (shape, count) VALUES (?, 1)
@@ -537,10 +565,39 @@ module Iriq
           stats = params[r[0]] or next
           stats.type_counts[r[1].to_sym] = r[2]
         end
+        params.each_value { |stats| recompute_numeric!(stats) }
         c.instance_variable_set(:@param_stats, params)
 
         c
       end
+
+      # The rolling numeric aggregates (count/min/max/sum) aren't stored in
+      # the schema — rebuild them from the tracked value counts, mirroring
+      # the Rust backend: only positions with integer/float observations
+      # qualify, and cap-trimmed values are lost.
+      def recompute_numeric!(stats)
+        return if (stats.type_counts[:integer] + stats.type_counts[:float]).zero?
+
+        count = 0
+        min   = nil
+        max   = nil
+        sum   = 0.0
+        stats.value_counts.each do |value, n|
+          num = Float(value, exception: false)
+          next unless num
+
+          count += n
+          min = num if min.nil? || num < min
+          max = num if max.nil? || num > max
+          n.times { sum += num }
+        end
+        return if count.zero?
+
+        stats.instance_variable_set(:@numeric_count, count)
+        stats.instance_variable_set(:@numeric_min, min)
+        stats.instance_variable_set(:@numeric_max, max)
+        stats.instance_variable_set(:@numeric_sum, sum)
+      end
     end
   end
 end

data/lib/iriq/version.rb

@@ -1,3 +1,3 @@
 module Iriq
-  VERSION = "0.30.2"
+  VERSION = "0.33.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iriq
 version: !ruby/object:Gem::Version
-  version: 0.30.2
+  version: 0.33.0
 platform: ruby
 authors:
 - Daniel Pepper
@@ -86,16 +86,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CLAUDE.md
-- Gemfile
-- Gemfile.lock
 - LICENSE.txt
-- Makefile
 - README.md
 - completions/_iriq
 - completions/iriq.bash
-- docs/ARCHITECTURE.md
-- docs/ROADMAP.md
 - exe/iriq
 - iriq.gemspec
 - lib/iriq.rb
@@ -153,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 3.6.9
 specification_version: 4
 summary: IRI extraction, normalization, and clustering.
 test_files: []

data/CLAUDE.md

@@ -1,208 +0,0 @@
-# Iriq development conventions
-
-> **⚠️ Behavior changes touch ALL THREE runtimes.** Ruby is the reference; Go
-> + Rust mirror it. Before committing any change to
-> parser/normalizer/extractor/CLI/etc:
->
->   1. Update Ruby + specs.
->   2. `bundle exec ruby script/generate_fixtures.rb` (regenerate JSON parity fixtures).
->   3. Port the change to Go (the Go module lives in `go/`).
->   4. `go -C go test ./...` — fixture tests should still pass.
->   5. `make build && script/cli_parity.sh` — Ruby ↔ Go CLI parity should still pass.
->   6. Port the change to Rust under `rust/`.
->   7. `cd rust && cargo test --workspace` — Rust fixture tests should still pass
->      (SQLite is a default feature).
->   8. `cd rust && cargo build --release --bin iriq && cd .. && script/rust_parity.sh`
->      — Rust ↔ Go CLI parity (covers Ruby transitively).
->   9. Commit the regenerated fixtures alongside the code change.
->
-> CI's parity + Rust jobs will fail if any step is skipped. The **Rust gate**
-> (fmt + clippy + tests) is automated — run `make hooks` once to install the
-> committed pre-push hook that runs `make check`. Full multi-runtime pre-push
-> for a behavior change:
-> `bundle exec rspec && go -C go test ./... && script/cli_parity.sh && make check && script/rust_parity.sh`.
-
-## Repo layout — Ruby at the root, Go and Rust in subdirs
-
-The Ruby gem lives at the repo root (it's the reference implementation and the
-published gem); the two mirror implementations are compartmentalized into
-`go/` and `rust/`. Earlier the Go code was intermixed at the root; it now sits
-in `go/`, symmetric with `rust/`, so the root reads as "Ruby + two ports."
-
-```
-iriq/
-  lib/ exe/ spec/         ← Ruby gem (library, CLI, specs) — the reference
-  completions/            ← shell-completion scripts shipped by the gem
-  iriq.gemspec
-  Gemfile
-
-  go/                     ← Go module github.com/dpep/iriq/go
-    go.mod go.sum
-    *.go                  ← Go package `iriq`
-    cmd/iriq/             ← Go CLI binary
-    completions/          ← Go's own embedded copy (go:embed can't reach ../)
-
-  rust/                   ← Cargo workspace
-    Cargo.toml            ← workspace root
-    iriq/                 ← one crate: library + `iriq` CLI binary; inlines completions
-    REPORT.md             ← Go → Rust port spike notes + perf
-    target/               ← Rust build artifacts (gitignored)
-
-  bin/                    ← built Go binary (gitignored)
-  script/                 ← shared dev scripts (fixture gen, parity, benches)
-  spec/fixtures/          ← golden JSON shared by Ruby specs + Go + Rust tests
-  .github/workflows/      ← Ruby CI, Go CI, Rust CI, parity CIs
-```
-
-Notes on this layout:
-
-- Go's import path is now `github.com/dpep/iriq/go` (the `/go` suffix matches
-  the subdir). Consumers import `github.com/dpep/iriq/go`.
-- One version tag (`vX.Y.Z`) serves all three runtimes — Ruby's gemspec, Go's
-  module, and Rust's `Cargo.toml` use the same tag stream.
-- The gemspec ships only Ruby + `completions/`, excluding `go/` and `rust/`:
-  `git ls-files * ':!:spec' ':!:script' ':!:bin' ':!:rust' ':!:go'`.
-- Completion scripts exist in three places (gem root `completions/`, `go/completions/`
-  for `go:embed`, and inlined in the Rust CLI) — keep them in sync like fixtures.
-
-## Building
-
-```sh
-# Ruby gem
-bundle install
-bundle exec exe/iriq --help     # runs the CLI from source
-
-# Go binary — convenience targets in the Makefile
-make build                      # → ./bin/iriq
-make install                    # go install into $GOBIN
-make uninstall                  # remove from $GOBIN
-make clean                      # remove ./bin/
-make test                       # go test ./...
-
-# Rust — one crate (library + `iriq` binary), SQLite bundled by default
-cd rust && cargo build --release --bin iriq    # → ./rust/target/release/iriq
-cd rust && cargo install --path iriq           # install into ~/.cargo/bin
-cd rust && cargo test --workspace
-
-# Via Homebrew (builds the Rust CLI from main)
-brew install dpep/tools/iriq
-
-# Via crates.io
-cargo install iriq
-```
-
-## Keeping the three runtimes in sync
-
-Ruby is the **reference implementation**. Go and Rust mirror its public API
-and behavior. Three layers of parity testing keep them aligned:
-
-1. **Golden JSON fixtures** (`spec/fixtures/*.json`)
-   Generated by `script/generate_fixtures.rb` from the Ruby implementation
-   over a curated set of inputs. Go's `fixtures_test.go` and Rust's
-   `rust/iriq/tests/fixtures.rs` both load each file and assert the same
-   outputs.
-
-2. **Ruby ↔ Go CLI parity harness** (`script/cli_parity.sh`)
-   Runs the same input through `bundle exec exe/iriq` and the Go binary and
-   diffs stdout. Lives in CI as the `Ruby ↔ Go parity` job.
-
-3. **Rust ↔ Go CLI parity harness** (`script/rust_parity.sh`)
-   Same idea — runs every Phase 1 + Phase 2 scenario (single-input,
-   pipe-mode, JSON corpus, SQLite corpus, --stats, --reinfer,
-   --propose-recognizers, --cross-host-shapes, --host=reg) through the
-   Go and Rust binaries and diffs stdout. Lives in CI as the
-   `Rust ↔ Go parity` job. Rust transitively inherits Ruby parity via Go.
-
-When changing behavior:
-
-1. Update the Ruby code + specs first.
-2. Regenerate fixtures: `bundle exec ruby script/generate_fixtures.rb`.
-3. Port the change to Go.
-4. `go test ./...` (uses the updated fixtures).
-5. `script/cli_parity.sh` should pass.
-6. Port the change to Rust under `rust/`.
-7. `cd rust && cargo test --workspace`.
-8. `cd rust && cargo build --release --bin iriq && cd .. && script/rust_parity.sh` should pass.
-9. Commit fixtures with the change — CI will fail if they're stale.
-
-## Tests
-
-```sh
-bundle exec rspec                                # Ruby suite (305+ examples)
-go test ./...                                    # Go suite (native + fixture parity)
-script/cli_parity.sh                             # Ruby ↔ Go CLI parity
-cd rust && cargo test --workspace
-cd rust && cargo fmt --check                      # formatting (CI-gated)
-cd rust && cargo clippy --workspace --all-targets -- -D warnings
-make check                                        # the three Rust checks above, in one shot
-script/rust_parity.sh                            # Rust ↔ Go CLI parity (~59 scenarios)
-```
-
-## Releases
-
-Versioning is single-stream: one `vX.Y.Z` covers all three runtimes. Bump the
-three version constants **together** — the `--version` parity checks fail
-if they drift:
-
-1. `lib/iriq/version.rb` (`VERSION`), `go/version.go` (`Version`), and the two
-   `version = "X.Y.Z"` / `pub const VERSION` lines in `rust/iriq/Cargo.toml` and
-   `rust/iriq/src/lib.rs` — same string.
-2. `Gemfile.lock` — re-resolve so the pinned `iriq (X.Y.Z)` matches
-   (`bundle install`, or it regenerates on the next `bundle exec`). Commit it.
-3. Run `cd rust && cargo update -p iriq` to refresh `Cargo.lock`.
-4. Tag `vX.Y.Z` and push. Go consumers pick it up via
-   `go get github.com/dpep/iriq/go@vX.Y.Z`.
-5. `gem push iriq-X.Y.Z.gem` to publish to RubyGems.
-6. `cd rust && cargo publish -p iriq` to publish to crates.io (the crate ships
-   both the library and the `iriq` binary).
-
-### Keep Homebrew in sync — bump on EVERY version change
-
-The tap (`~/code/lib/homebrew-tools`) ships a single `Formula/iriq.rb` that
-builds the Rust CLI (`cargo install --path rust/iriq`) from `branch: "main"`.
-SQLite is on by default (the `iriq` crate's `default` feature set), so there is
-no longer a separate `iriq-sqlite` formula.
-
-The formula pins a static `version "X.Y.Z"` label. Because the build tracks
-`main` rather than a tagged tarball, `brew upgrade` only rebuilds when that
-label changes. So on every bump here, update the `version` string in
-`Formula/iriq.rb` to match `version.rb`, then commit + push the tap. Leaving it
-stale means brew users never get the new code even though it's already on `main`.
-
-## Corpus storage backends
-
-The `Corpus` class delegates state to a `Storage` backend; three backends ship:
-
-- **Memory** — default, in-process only.
-- **JSON** — Memory wrapped with atomic load/save against a JSON file
-  (`.json` by default). Same shape both runtimes have always written.
-- **SQLite** — incremental UPSERTs against a `.db` / `.sqlite` / `.sqlite3`
-  file with WAL journaling. Supports concurrent observers and avoids
-  loading the whole corpus into memory.
-
-`Corpus.open(path)` (Ruby) / `iriq.OpenCorpus(path)` (Go) picks the backend
-by file extension. `corpus.save(other_path)` exports as JSON regardless of
-the live backend; `corpus.save(same_path)` is idempotent (no clobbering a
-SQLite file with JSON, etc.).
-
-The Ruby `sqlite3` gem is loaded lazily (only when a `.db` path is opened),
-keeping the iriq install footprint minimal for users that stick with JSON.
-On the Go side we use `modernc.org/sqlite` (pure Go — no cgo). The Rust
-side uses `rusqlite` with the `bundled` feature (statically links C SQLite,
-~3-4 MB binary cost). Schema v4 is shared across all three runtimes — a
-`.db` written by any binary opens cleanly in any other.
-
-When adding a new backend, replicate the contract in all three languages
-and add parity scenarios in `script/cli_parity.sh`'s `corpus_pair`
-section + `script/rust_parity.sh`'s `corpus_pair`.
-
-## What lives where in scripts
-
-- `script/benchmark.rb` — Ruby-only throughput benchmark.
-- `script/memory.rb` — Ruby-only memory profile.
-- `script/generate_fixtures.rb` — produces `spec/fixtures/*.json` for cross-runtime parity.
-- `script/cli_parity.sh` — Ruby ↔ Go CLI diff.
-- `script/rust_parity.sh` — Rust ↔ Go CLI diff.
-- `script/bench_three_way.sh` — Go vs Rust wall-clock comparison.
-- `script/bench_compare.sh` — Ruby vs Go CLI wall-time comparison.
-- `script/bench_storage.sh` — JSON vs SQLite backend timing (single-process, incremental, concurrent).

data/Gemfile

@@ -1,3 +0,0 @@
-source "https://rubygems.org"
-
-gemspec