iriq 0.1.0 → 0.30.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95d6bc09f7de65bcb4acc5db3ad68d1b83c326360d913c45aede66038a100461
-  data.tar.gz: ae58d39b77fce3041cc5561b575dea52706b38f4cfab11d4881cf2f644f6cc59
+  metadata.gz: 598c04e3c1777787ae9e5d1be98e2bc68d441e2020ebe7743bdf8075b20fdaec
+  data.tar.gz: 396ad6b0b0acffb76b7bc2b4e31792b02ac65749c6ac769fd70a47ce5d806496
 SHA512:
-  metadata.gz: a8fa85f112d9766ff4e9e4ad60c1043ce9701fe42e6dbd01f70da39fa0dd554bff573f40c858d88ab1e1539de0c1f017609535cc57e8e4fcc6651f0d20697e60
-  data.tar.gz: 97c714e664874c08278a305b8beff470b68bd2b7e4f58977cc44cf2e3716e619d17011a33d77b8ea9356eec0715acb6c815252551edf64db16eec4599f816274
+  metadata.gz: 16637ff46f4648a2cfc14404ed074d3cedc6fc08cabf0c46a6fa7a39553b8b78020907fde1d9024005cec3a4f2cdb4cb3e999802ec866a942c20c15be6c7af34
+  data.tar.gz: 458aa6deba73a571a07801bb3df445a4d08500a55c3d1d8c50b11df0811dbc785270fd1ef908ebbb58c6f53dfb1ecfc7013fe137e216e88bca81c9bc56d21fa4

data/CHANGELOG.md

@@ -1,3 +1,90 @@
+###  0.30.2  (2026-06-23)
+- Piped stdin and `--file` now **stream** the per-IRI sections (`-n`/`-p`/`-c`/`-e`) line by line, flushing each IRI as it's processed — `tail -f access.log | iriq -n` is live and memory stays bounded on huge inputs. Output is byte-identical to before; the aggregate views (deduped URL list, clusters, `--stats`) still read the whole input. Ruby, Go, and Rust.
+
+###  0.30.1  (2026-06-21)
+- Batch sections (`--normalize` etc.) are now corpus-informed when `--corpus` is supplied, matching single-input behavior.
+- Added a CLI end-to-end test suite (sections, formats, batch/cluster, subcommands) and a `make check` Rust gate + pre-push hook.
+
+###  0.30.0  (2026-06-21)
+- Rust consolidated into a single crate (library + `iriq` binary) with SQLite always on by default — no separate sqlite build.
+- Go moved into the `go/` subdirectory; import path is now `github.com/dpep/iriq/go`.
+
+###  0.11.0  (2026-05-27)
+- New classifier types: `:color` (hex form `#fff`/`#ffffff`/`#ffffff80`), `:coordinate` (`lat,lng` pair with plausible-range validation), `:country` (ISO 3166-1 alpha-2, allowlisted), `:base64` (≥16 chars with `+`/`/`/`=` to disambiguate from `:opaque_id`).
+- `SegmentClassifier.color_kind(value)` / `ColorKind(value)` returns `:hex` for hex-shaped colors — placeholder for future named / rgb / hsl support, mirrors the file_kind pattern.
+- Param-name hint map extended: `color`/`bg`/`fg`/`background`/`foreground` → `:color`, `coords`/`coordinates`/`geo`/`location`/`position`/`latlng` → `:coordinate`, `country`/`country_code`/`nation` → `:country`.
+- `-J` is now a short alias for `--ndjson` (combinable: `iriq -nJ < file`).
+- New CLI `-e/--explain` flag — annotated normalization trace. For each path segment / query param, shows the value, type, output (placeholder or canonical value), and notes for every non-obvious transformation (hint suppression for semantic types, currency upcase, IP umbrella collapse, canonical date, param-name lift). JSON via `-e -j` returns the same structure.
+- Library API: `Iriq::Trace.for(input)` (Ruby) / `iriq.Trace(input)` (Go) returns the same trace data structure.
+- Classifier perf: each regex test is now gated on a cheap composition check (`String#include?` / `IndexByte` / `size`) so a literal like `"users"` skips ~20 regex matches instead of walking the full chain. Measured: Ruby normalize +12%, extract +27%; Go CLI wall time -25%.
+
+###  0.10.0  (2026-05-27)
+- New classifier type `:file` — `name.ext` shape where `ext` is in a curated allowlist spanning image / document / data / text / web / audio / video / archive / code kinds. `image.png` and `report.pdf` classify as `:file` instead of falling through to `:opaque_id`. The per-extension kind (`:image`, `:document`, etc.) is surfaced via `SegmentClassifier.file_kind(value)` / `FileKindOf(value)` for verbose displays.
+- `Cluster#param_summary` adds `:kind_distribution` for `:file`-typed params — buckets observed values by kind. Best-effort: only reflects values within the tracking cap.
+- New phone format: NANP-style `555-666-7777`, `555.666.7777`, `(555) 666-7777`. Leading area-code + exchange digits constrained to 2-9 so dotted version strings / digit blobs don't shadow. The `+` E.164 form still covers international.
+- Param-name hints — when a value's type is generic (`:literal`, `:opaque_id`, `:slug`), the param name can supply the type. `?phone=unknown` becomes `{phone}` and `?email=tbd` becomes `{email}`. Hint map covers phone/email/locale/currency/url/jwt/mime variations. Specific value types (e.g. `?phone=12345` → `:integer`) still win.
+
+###  0.9.0  (2026-05-27)
+- Semantic types (`:version`, `:locale`, `:currency`, `:date`, `:boolean`, `:timestamp`, etc.) now surface as `{type}` placeholders instead of being run through the noun-singularize hint. `/api/v1/status` renders `/api/{version}/status` rather than the misleading `/api/{api_id}/status`. Only ID-shaped types (`:integer`, `:uuid`, `:hash`, `:opaque_id`, `:slug`) keep the `{noun_id}` form.
+- `--normalize` collapses `:ipv4` and `:ipv6` to `{ip}` in placeholder form (previously rendered as `{ipv4}` / `{ipv6}`). The classifier still tracks the specific family; cluster summary keeps the distinct types.
+- `--normalize` canonicalizes currency segments and params to ISO 4217 upper case — `/pricing/usd` → `/pricing/USD`, `?currency=eur` → `?currency=EUR`. Mirrors the existing date canonicalization (`canonical_currencies: true` flag on `PathShape`).
+- `LOCALE_RE` tightened: the region/script portion now caps at 2-4 alphanumeric chars and the language portion is validated against the ISO 639-1 allowlist — `by-locale` no longer wrongly classifies as `:locale`.
+- New classifier types: `:phone` (E.164 — `+` then 7-15 digits with optional separators), `:jwt` (three base64url segments separated by dots), `:mime` (RFC 2046 top-level type + subtype, e.g. `image/png`, `application/vnd.api+json`).
+- New corpus-promoted type `:http_status` — integer positions whose observed range falls inside 100..599 with ≥2 distinct values and ≥5 samples get promoted. Same range-analysis pattern as `:year`.
+- Scheme-less URL detection: query values like `?redirect=foo.com/path` classify as `:url`. Requires a dotted host with a TLD-like ≥2-letter suffix followed by a slash, so `image.png` stays as `:opaque_id`.
+- `Cluster#param_summary` adds two new fields:
+  - `:value_distribution` — fractions per tracked value, for `:boolean` and `:enum` positions (e.g. `{ "true" => 0.97, "false" => 0.03 }`). Same data already in `value_counts`, surfaced as ratios.
+  - `:subtype_distribution` — int-vs-float split for `:number` positions (e.g. `{ integer: 0.4, float: 0.6 }`).
+- `:boolean` now wins over `:enum` when the dominant type is boolean — a position of pure `true`/`false` stays `:boolean` rather than being demoted to a 2-value enum.
+
+###  0.8.0  (2026-05-27)
+- **Breaking**: `:numeric` umbrella renamed to `:number` (Ruby) / `TypeNumeric` → `TypeNumber` (Go). Same semantics.
+- New classifier types: `:boolean` (`true`/`false`, any case), `:version` (`v1`, `v2.0.1`, `v1.2.3-beta` — requires the `v` prefix), `:locale` (BCP 47-ish full forms like `en-US`/`fr_CA`, plus bare 2-letter language codes from an inline ISO 639-1 allowlist of ~55 entries — `en`, `fr`, `ja`, etc.), `:currency` (3-letter codes from an inline ISO 4217 allowlist of ~35 entries).
+- `:year` is now corpus-only: an `:integer` position whose observed min/max land in 1900..2100 with ≥2 distinct values gets promoted. A single 4-digit integer in isolation classifies as `:integer` — only range analysis across observations is reliable.
+- `PositionStats` now tracks `numeric_min` / `numeric_max` / `numeric_sum` / `numeric_count` for `:integer`/`:float` observations. `Cluster#param_summary` surfaces `min` / `max` / `avg` on any param with numeric observations.
+- Shape-y variable types (`:version`, `:locale`, `:currency`, `:boolean`) now respect the stable-literal rule: a single dominant value at a position (`v1` only across many observations) stays as the literal `v1` instead of being placeholdered as `{version}`. High cardinality at the same position falls back to `{version}` / `{locale}` / etc. as expected.
+- 0/1 booleans still classify as `:integer` individually; the existing `:enum` umbrella catches `?flag=0` / `?flag=1` patterns when they cluster.
+
+###  0.7.0  (2026-05-27)
+- **Breaking**: `:integer_id` classifier type renamed to `:integer` (Ruby) / `TypeIntegerID` → `TypeInteger` (Go). The "ID" semantics live in the hints layer (which still produces `{user_id}` placeholders); the classifier now reflects pure shape. Update any direct `.classify(...) == :integer_id` checks, dump-file consumers, and persisted corpora — the type symbol changed in `type_counts` and raw shape strings (e.g. `/users/{integer_id}` → `/users/{integer}`).
+- New `:enum` umbrella (corpus-only): when a param has a small bounded set of repeated values (default ≥20 observations, ≤10 distinct, each ≥2 occurrences, ≥95% coverage), `Cluster#param_type` returns `:enum` and `param_summary` includes the value list under `:values`. Normalize output keeps the `{enum}` placeholder — values aren't inlined.
+- `iriq --host=full|registrable|reg|none` CLI flag plumbs `Corpus#host_strategy` from the command line. `reg` is a short alias for `registrable`.
+
+###  0.6.0  (2026-05-27)
+- New classifier types: `:ipv4`, `:ipv6`, `:url`, `:email` (Ruby) / `TypeIPv4`, `TypeIPv6`, `TypeURL`, `TypeEmail` (Go). Slotted before the generic `:opaque_id` / `:literal` catch-alls so URL params like `?redirect=https://foo.com/...`, `?email=alice@example.com`, `?ip=192.168.1.1`, `?gateway=fe80::1` get distinct types instead of falling through.
+- IPv4 validates octets ≤ 255 — out-of-range dotted-quads fall back to `:opaque_id`.
+- IPv6 accepts the full eight-group form and any compressed form containing `::`. IPv4-mapped variants (`::ffff:192.0.2.1`) are not recognized.
+
+###  0.5.0  (2026-05-27)
+- Float values now classify as `:float` instead of falling through to `:opaque_id` (Ruby `:float` / Go `TypeFloat`). Regex requires digits on both sides of the decimal — `3.14`, `-2.5`, `1.0` match; `.5`, `1.`, `1e10` do not.
+- New `:numeric` umbrella (corpus-only): when a cluster sees both `:integer_id` and `:float` observations at the same param with neither subtype hitting the 80% confidence threshold, the param surfaces as `:numeric` in `param_summary` and renders as `{numeric}` in `Corpus#normalize` output. The classifier itself never returns `:numeric` directly — individual values are always specifically int or float.
+- `Corpus.new(host_strategy: ...)` knob controls how host is keyed into clusters: `:full` (default, unchanged), `:registrable` (strip subdomains, so `api.foo.com` and `app.foo.com` cluster as `foo.com`), `:none` (ignore host, group all observations by shape alone). `:registrable` uses an inline allowlist of ~70 common multi-label TLDs (`co.uk`, `com.au`, `co.jp`, etc.) — niche multi-label suffixes like `.priv.no` will be over-stripped.
+
+###  0.4.0  (2026-05-27)
+- Query-param clustering: each `Cluster` now tracks per-param presence, value cardinality, and type via `param_stats`. Surfaced on `cluster.to_h[:params]` (and the JSON cluster view), persisted in both JSON and SQLite backends.
+- `Corpus#normalize` (Ruby) / `Corpus.NormalizeIdentifier` (Go) now include query params, rendered with corpus-informed types when available (falls back to mechanical classification otherwise).
+- New `corpus.params_for(url)` / `Corpus.ParamsFor(url)` — returns the inferred params for the cluster `url` would fall into. Useful for "what params might this URL accept?" tooling.
+- Date detection expanded to include `YYYY/MM/DD` and `YYYYMMDD` (with year/month/day sanity bounds) alongside the existing `YYYY-MM-DD`.
+- `SegmentClassifier.canonical_date(value)` / `CanonicalDate(value)` returns the ISO form for any recognized date.
+- `--normalize` output canonicalizes recognized date values to `YYYY-MM-DD` (path segments and query params). Cluster keys still use `{date}` placeholders so dated routes still group together.
+- `PositionStats::DEFAULT_MAX_VALUES` is now the value cap for `cluster.param_stats[name]` too.
+
+###  0.3.0  (2026-05-25)
+- Go: SQLite backend is now opt-in via `-tags sqlite`. Default `go install` and the `iriq` Homebrew formula ship a slim binary (~30% smaller) with JSON corpora only. SQLite users compile with `-tags sqlite` or install `dpep/tools/iriq-sqlite`.
+- Makefile: `release` / `release-sqlite` targets strip debug symbols and use `-trimpath` for reproducible builds.
+- CLI: `iriq --help` reports the active build (slim vs sqlite).
+- Slim build returns a friendly error when a `.db` corpus path is opened, pointing at the iriq-sqlite formula.
+- `PositionStats::DEFAULT_MAX_VALUES` / `DefaultMaxValuesPerPosition` raised from 1000 → 5000. Existing corpora keep whatever cap they were created with (the cap is persisted in the dump / SQLite meta table); only freshly-constructed corpora pick up the new default.
+
+###  0.2.0  (2026-05-25)
+- Corpus storage backends: JSON (default) and SQLite, dispatched by file extension
+- Go: `iriq.OpenCorpus(path)`; Ruby: `Iriq::Corpus.open(path)`
+- SQLite backend: incremental UPSERTs, WAL mode, concurrent-safe via busy_timeout + BEGIN IMMEDIATE; checkpoints on close so the WAL sidecar doesn't grow unbounded
+- Batch mode: `corpus.batch { ... }` (Ruby) / `corpus.Batch(fn)` (Go) wraps many observations in one transaction
+- Clusterer now wraps the in-memory Storage backend; only one cluster code path
+- script/bench_storage.sh — JSON vs SQLite timing across single-process, incremental, and concurrent workloads
+- **Breaking (Go)**: `Corpus.HostCounts` / `PathLengthCounts` / `RawShapeCounts` / `FingerprintCounts` are methods now, not fields
+
 ###  0.1.0  (2026-05-24)
 - CLI: auto-detect file argument, retire --extract flag
 - CLI: section flags work in pipe mode + clean up help text

data/CLAUDE.md

@@ -0,0 +1,208 @@
+# 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.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    iriq (0.1.0)
+    iriq (0.30.2)
 
 GEM
   remote: https://rubygems.org/
@@ -19,6 +19,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
+    mini_portile2 (2.8.9)
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
@@ -53,6 +54,8 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    sqlite3 (2.9.5)
+      mini_portile2 (~> 2.8.0)
     stringio (3.2.0)
     tsort (0.2.0)
 
@@ -65,6 +68,7 @@ DEPENDENCIES
   rspec (>= 3.10)
   rspec-debugging
   simplecov (>= 0.22)
+  sqlite3 (>= 1.6)
 
 CHECKSUMS
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
@@ -74,7 +78,8 @@ CHECKSUMS
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.17.0) sha256=168c4ddb93d8a361a045c41d92b2952c7a118fa73f23fe14e55609eb7a863aae
-  iriq (0.1.0)
+  iriq (0.30.2)
+  mini_portile2 (2.8.9) sha256=0cd7c7f824e010c072e33f68bc02d85a00aeb6fce05bb4819c03dfd3c140c289
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
@@ -90,6 +95,7 @@ CHECKSUMS
   simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
   simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
   simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  sqlite3 (2.9.5) sha256=04572973a3f943ad50a8adfffc8dd752a5f06e4c3db2026f71838fed8a982606
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
 

data/Makefile

@@ -0,0 +1,113 @@
+# Iriq Go binary — build/install/clean/uninstall helpers.
+#
+#   make                   - same as `make help`
+#   make build             - dev build into ./bin/iriq (no SQLite, debug info)
+#   make build-sqlite      - dev build with SQLite backend included
+#   make release           - stripped + trimpath build (no SQLite)
+#   make release-sqlite    - stripped + trimpath build with SQLite
+#   make install           - go install into $GOBIN
+#   make test              - go test ./... (both tag states)
+#   make clean             - remove ./bin/
+#   make uninstall         - remove the binary from $GOBIN
+#
+# The default build excludes the SQLite backend to keep the binary lean.
+# Pass `-tags sqlite` (or use the *-sqlite targets) to compile it in. The
+# CLI's `--version` output tells you which backends are baked in.
+#
+# Ruby gem build/install is handled by Bundler/RubyGems; see CLAUDE.md.
+
+GO          ?= go
+GO_DIR      := go
+BIN_DIR     := bin
+BIN         := $(BIN_DIR)/iriq
+# Absolute output path: builds run inside $(GO_DIR) via `go -C`, so a
+# relative -o would land under go/. Keep the binary at the repo-root bin/.
+ABS_BIN     := $(CURDIR)/$(BIN)
+PKG         := ./cmd/iriq
+
+# Rust crate lives under rust/; CI gates fmt + clippy + tests there.
+CARGO       ?= cargo
+RUST_DIR    := rust
+
+# Release flags strip the symbol table (-s), debug info (-w), and bake
+# reproducible paths (-trimpath). Drops binary size ~30% with no
+# functional impact; stack-trace function names are gone but file:line
+# resolution still works.
+RELEASE_FLAGS := -ldflags "-s -w" -trimpath
+
+# Resolve $GOBIN, falling back to $GOPATH/bin (Go's default install location).
+GOBIN       := $(shell $(GO) env GOBIN)
+ifeq ($(GOBIN),)
+GOBIN       := $(shell $(GO) env GOPATH)/bin
+endif
+INSTALLED   := $(GOBIN)/iriq
+
+.DEFAULT_GOAL := help
+.PHONY: help build build-sqlite release release-sqlite install test clean uninstall check fmt hooks
+
+help:
+	@echo "Iriq Go targets:"
+	@echo "  make build            slim dev build into $(BIN)"
+	@echo "  make build-sqlite     dev build with SQLite backend"
+	@echo "  make release          stripped slim build into $(BIN)"
+	@echo "  make release-sqlite   stripped build with SQLite backend"
+	@echo "  make install          go install into $(GOBIN)"
+	@echo "  make test             run go test ./... in both tag states"
+	@echo "  make check            Rust gate: cargo fmt --check + clippy + test (run before merging)"
+	@echo "  make fmt              cargo fmt the Rust crate"
+	@echo "  make hooks            enable the committed git hooks (pre-push runs 'make check')"
+	@echo "  make clean            remove $(BIN_DIR)/"
+	@echo "  make uninstall        remove $(INSTALLED)"
+
+build:
+	@mkdir -p $(BIN_DIR)
+	$(GO) -C $(GO_DIR) build -o $(ABS_BIN) $(PKG)
+	@echo "built $(BIN) (slim, debug)"
+
+build-sqlite:
+	@mkdir -p $(BIN_DIR)
+	$(GO) -C $(GO_DIR) build -tags sqlite -o $(ABS_BIN) $(PKG)
+	@echo "built $(BIN) (sqlite, debug)"
+
+release:
+	@mkdir -p $(BIN_DIR)
+	$(GO) -C $(GO_DIR) build $(RELEASE_FLAGS) -o $(ABS_BIN) $(PKG)
+	@echo "built $(BIN) (slim, stripped)"
+
+release-sqlite:
+	@mkdir -p $(BIN_DIR)
+	$(GO) -C $(GO_DIR) build -tags sqlite $(RELEASE_FLAGS) -o $(ABS_BIN) $(PKG)
+	@echo "built $(BIN) (sqlite, stripped)"
+
+install:
+	$(GO) -C $(GO_DIR) install $(PKG)
+	@echo "installed $(INSTALLED)"
+
+test:
+	$(GO) -C $(GO_DIR) test ./...
+	$(GO) -C $(GO_DIR) test -tags sqlite ./...
+
+# The Rust gate — mirrors CI's Rust job. Run before merging/pushing (the
+# pre-push hook runs this for you once `make hooks` is enabled).
+check:
+	cd $(RUST_DIR) && $(CARGO) fmt --check
+	cd $(RUST_DIR) && $(CARGO) clippy --workspace --all-targets -- -D warnings
+	cd $(RUST_DIR) && $(CARGO) test --workspace
+
+fmt:
+	cd $(RUST_DIR) && $(CARGO) fmt
+
+hooks:
+	git config core.hooksPath .githooks
+	@echo "git hooks enabled (.githooks) — pre-push now runs 'make check'"
+
+clean:
+	rm -rf $(BIN_DIR)
+	@echo "removed $(BIN_DIR)/"
+
+uninstall:
+	@if [ -f "$(INSTALLED)" ]; then \
+		rm "$(INSTALLED)" && echo "removed $(INSTALLED)"; \
+	else \
+		echo "not installed at $(INSTALLED)"; \
+	fi