iriq 0.30.2 → 0.33.0

data/Gemfile.lock

@@ -1,103 +0,0 @@
-PATH
-  remote: .
-  specs:
-    iriq (0.30.2)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    date (3.5.1)
-    debug (1.11.1)
-      irb (~> 1.10)
-      reline (>= 0.3.8)
-    diff-lcs (1.6.2)
-    docile (1.4.1)
-    erb (6.0.4)
-    io-console (0.8.2)
-    irb (1.17.0)
-      pp (>= 0.6.0)
-      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)
-    prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
-    rdoc (7.2.0)
-      erb
-      psych (>= 4.0.0)
-      tsort
-    reline (0.6.3)
-      io-console (~> 0.5)
-    rspec (3.13.2)
-      rspec-core (~> 3.13.0)
-      rspec-expectations (~> 3.13.0)
-      rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.6)
-      rspec-support (~> 3.13.0)
-    rspec-debugging (0.0.4)
-      rspec-expectations (>= 3)
-    rspec-expectations (3.13.5)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.8)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.13.0)
-    rspec-support (3.13.7)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      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)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  debug (>= 1)
-  iriq!
-  rspec (>= 3.10)
-  rspec-debugging
-  simplecov (>= 0.22)
-  sqlite3 (>= 1.6)
-
-CHECKSUMS
-  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
-  debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
-  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
-  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
-  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
-  irb (1.17.0) sha256=168c4ddb93d8a361a045c41d92b2952c7a118fa73f23fe14e55609eb7a863aae
-  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
-  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
-  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
-  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
-  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
-  rspec-debugging (0.0.4) sha256=7a8e2dc240c140f0ed27b452a5661a56474ee8cf7b84c5bcbefd827ad36f0a6f
-  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
-  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
-  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
-  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
-
-BUNDLED WITH
-  4.0.9

data/Makefile

@@ -1,113 +0,0 @@
-# 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

data/docs/ARCHITECTURE.md

@@ -1,223 +0,0 @@
-# iriq architecture
-
-As of v0.28.0, this describes the system that's actually in the repo —
-Phase 1 of the rearchitecture roadmap (target model below) is complete,
-and Phase 2 has added the learning layer on top. Originally written as
-the *target* model at the start of Phase 1; the implementation has
-caught up.
-
-`ROADMAP.md` tracks what's still pending (inter-position correlations,
-near-shape clustering, and Phase 3 productize items).
-
-For the inner details, read the source: `lib/iriq/{recognizer,position,
-shape,evidence,event,reducer,recognizer_proposal,synthesized_recognizer,
-cross_host_shape,corpus}.rb` and their Go counterparts at the repo root.
-
-## Core principle
-
-The system pivots around **Position** (a slot in a host's structure) and
-**Evidence** (what we know about a Position). Strings are observations;
-types are inferences. Everything composable hangs off these two nouns.
-
-## Core types
-
-### Identifier (existing, mostly unchanged)
-
-A parsed IRI: scheme, host, port, path_segments, query_params, fragment,
-plus `kind ∈ {:url, :urn}` and the urn `nss`. Produced by `Parser` from a
-candidate string; produced in bulk by `Extractor` from free text.
-
-### Position (new)
-
-A stable identity for a slot in a host's structure.
-
-```
-Position {
-  host:    string        # normalized per host_strategy (full|registrable|none)
-  scope:   :path | :query
-  locator: path_prefix   # for :path — the typed-shape prefix that led here
-         | param_name    # for :query — the ?key= name
-}
-```
-
-Two Identifiers occupy the *same* Position when their hosts agree and their
-typed prefix agrees. "Typed prefix" means the prefix rendered with inferred
-types (`/users/{integer}/...`), not raw values. This makes Position identity
-robust to the specific values seen.
-
-### Recognizer (new)
-
-A pluggable classifier for a single (or small family of) types.
-
-```
-Recognizer#try(string) -> { type:, confidence:, canonical:, notes: } | nil
-```
-
-- `type` is a symbol from the recognized vocabulary (uuid, date, integer, …).
-- `confidence` is in `[0, 1]`. Calibrated against
-  `spec/fixtures/calibration/`.
-- `canonical` is the canonical form (e.g. ISO date for `:date`, uppercased
-  ISO 4217 for `:currency`). `nil` means "use the input as-is".
-- `notes` is an optional array of strings the Trace view may surface.
-
-Recognizers are independent. There is no global ordering. The
-**SegmentClassifier becomes an ensemble** that runs each Recognizer and
-picks the highest-confidence answer above a floor. `:literal` is the
-fallback when no Recognizer fires above the floor.
-
-### Evidence (new)
-
-The universal substrate for explanation. A small fixed schema, emitted by
-both classification and inference.
-
-```
-Evidence {
-  position: Position
-  kind:     :lexical | :corpus | :recognizer | :neighbor | :policy
-  payload:  { ... kind-specific fields ... }
-  weight:   float in [0, 1]      # contribution to the final inference
-}
-```
-
-Examples:
-- `:recognizer` payload: `{ name:, type:, lexical_confidence: }`
-- `:corpus` payload: `{ observations:, distinct_values:, cardinality_frac: }`
-- `:neighbor` payload: `{ prior_literal:, inferred_hint: }`
-- `:policy` payload: `{ rule:, applied: }` (e.g. "ipv4→ip umbrella collapse")
-
-`Trace` and `Explanation` are *views* over a list of Evidence. They render
-strings for human consumption but the data shape is shared.
-
-### Shape (new — replaces PathShape strings as the identity)
-
-An ordered list of typed Positions for a single Identifier path:
-
-```
-Shape { positions: [Position], inferred_types: [Symbol] }
-```
-
-`Shape#render(:string)` produces the human-readable form (`/users/{user_id}`)
-that today's `PathShape` produces. Cluster identity is the structural Shape,
-not the string. String renderings are derived for display, not for keying.
-
-### Cluster (existing; refactored)
-
-Same role: a group of Identifiers sharing (host, Shape). Internals shift to
-key on structural Shape; aggregation (`PositionStats`) is unchanged.
-Inference (variability promotion, enum detection, etc.) moves *out* of
-Cluster and into its own stage so it can be re-run over stored evidence
-without re-feeding observations.
-
-### Reducer (new)
-
-A function over the event stream that maintains a materialized view.
-
-```
-Reducer#apply(event, state) -> state
-```
-
-Examples ship in v1:
-- `HostCountsReducer`
-- `PositionStatsReducer`
-- `ClusterReducer`
-- `FingerprintReducer`
-
-Storage backends store the event log (or, equivalently, the materialized
-views — backends choose). Adding a new metric is: write a Reducer, declare
-its state shape; no other module changes.
-
-## Pipeline (target end-state)
-
-```
-text
- └─► Extractor       ─► [candidate strings]
-       └─► Parser    ─► Identifier
-             └─► Recognition  ─► annotated segments + per-segment Evidence
-                   └─► Events ─► Storage event log
-                                  └─► Reducers ─► materialized views
-                                                   (PositionStats, Clusters, ...)
-                                        ├─► Inference  ─► per-Position type + Evidence
-                                        └─► Rendering  ─► normalized string / Shape view
-```
-
-Each stage is a separate module with input/output contracts. Inference
-re-reads materialized views; it does not require re-running the pipeline.
-
-## What this fixes (vs. the today code)
-
-- **No more string-fingerprint cluster keys.** Classifier tuning no longer
-  fractures clusters.
-- **No more order-dependent first-match classifier.** Add a Recognizer
-  without considering global ordering.
-- **`SegmentClassifier` stops being a god module.** Recognizers own their
-  patterns and canonical forms; reference data (locales, currencies,
-  countries) lives in `ReferenceData::*`; display names / variability
-  predicate live in a small `Policy` / `Naming` module.
-- **One Normalizer.** Mechanical mode is "NullEvidence" — no special case.
-- **Two-axis type taxonomy.** Lexical shape and semantic role can grow
-  independently. Cardinality character is a *property of Position*, not of
-  type — `:year`, `:http_status`, `:enum` collapse into "integer-shape +
-  bounded-cardinality" expressed via Evidence.
-- **Re-runnable inference.** Threshold tuning no longer requires
-  re-observation.
-- **One explanation substrate.** Trace, Explanation, future schema export,
-  future PR-diff annotator are all views over Evidence.
-
-## What stays the same
-
-- `Identifier` as the parsed record.
-- `Parser` + `Extractor` — already cleanly separated.
-- `Storage::*` backends (Memory, Json, Sqlite). Internals change to persist
-  events rather than ad-hoc counters, but the file-extension routing API
-  (`Corpus.open(path)`) stays.
-- Public CLI surface (`exe/iriq`, the Go `cmd/iriq` binary).
-- The four `Iriq.*` module methods: `parse`, `normalize`, `explain`,
-  `extract`.
-
-## Extensibility (where it stands)
-
-- **Recognizer registry**: per-classifier and mutable as of v0.26.
-  `SegmentClassifier#register_recognizer` appends to the instance's
-  ensemble; `SegmentClassifier::DEFAULT` is the module-level singleton
-  that fresh corpora share, and the first `Corpus#activate_proposal`
-  call swaps to a private classifier so activations don't leak.
-  External users registering their own Recognizer subclasses works
-  today via the same API; an *external* registry / discovery surface
-  (load Recognizers from a config file or env var) is still future
-  work.
-- **ProposalStrategy**: pluggable via `Iriq::ProposalStrategy::DEFAULTS`.
-  Adding a strategy = define a class with `#propose(storage, **opts)`
-  and append. v1 ships one strategy (PrefixUnderscoreId); next-segment
-  / cross-position correlation strategies are pending Phase 2 work.
-- **Reducer registry**: the dispatch table `Iriq::Reducer::DEFAULTS`
-  maps `Event` subclasses to reducer lambdas. Adding a metric = define
-  an `Event` subtype, write a Reducer, register it. The registry is
-  exposed as a constant; safe to monkeypatch in user code, though no
-  public registration API ships yet.
-- **Storage backends**: three ship (Memory, JSON, SQLite). Adding a
-  fourth = implement the `Storage` interface (lib/iriq/storage/memory.rb
-  is the canonical reference), wire it into `Storage.open` extension
-  routing, add it to `script/cli_parity.sh`.
-
-## Learning layer (Phase 2, on top of the substrate above)
-
-The Phase 1 substrate gives us typed observations, structured Shape,
-and re-runnable inference. Phase 2 builds the learning pipeline on top:
-
-- **Source-IRI log** (v0.21). Storage persists every observed canonical
-  IRI alongside the materialized views. `Corpus#reinfer` drops the
-  views and replays the log through the current classifier + reducers
-  — lets us tune thresholds or swap the classifier without re-feeding.
-- **RecognizerProposal** (v0.23). A struct describing a learned
-  pattern: prefix / suggested_type / positions / hosts / coverage /
-  confidence / observation_count / sample_values / strategy.
-  Emitted by ProposalStrategy implementations; not auto-applied.
-- **SynthesizedRecognizer** (v0.26). Built from a proposal's prefix;
-  regex `^<prefix>[A-Za-z0-9]+$`, `Specificity::SEMANTIC`. Same
-  Recognizer interface as the built-ins (UUID, Date, Integer) — the
-  ensemble doesn't know the difference.
-- **CrossHostShape** (v0.27). Read-side: route shapes that recur
-  across multiple hosts. Independent evidence of semantic pattern.
-- **Confidence formula** (v0.28). `min(1.0, coverage + 0.05 *
-  (host_count - 1))`. Single-host proposals are unchanged; cross-host
-  proposals get boosted. `--activate-above F` checks confidence.

data/docs/ROADMAP.md

@@ -1,190 +0,0 @@
-# iriq roadmap
-
-A multi-quarter plan to lift iriq from a single-pass string classifier into an
-event-driven inference system over typed Positions. Pre-release; we will break
-APIs freely and bump minor versions per shipped feature.
-
-Source of the plan: principal-engineer architectural review on 2026-05-30,
-captured in the project history.
-
-## Where to pick up next time
-
-Last updated: 2026-05-31, current version **v0.28.0**.
-
-**Phase 1**: complete (v0.11 → v0.19). The structural foundation —
-Recognizer ensemble, Position, Shape, Evidence, single Normalizer,
-events + reducers — is all in place.
-
-**Phase 2**: 5 of 7 items shipped (v0.21 → v0.28).
-- ✅ Re-runnable inference (library + CLI)
-- ✅ Learned recognizers (library + propose CLI + auto-activate CLI)
-- ✅ Cross-host learning (catalog + confidence integration)
-- ⏭️ **Inter-position correlations** — next up. When slot A's value
-  predicts slot B's type, surface that ("after `/orgs/{org_id}/` the
-  next segment is almost always `users` or `repos`"). Read-side query
-  over existing cluster + position stats; no storage changes needed.
-  Estimated scope: similar to cross-host shape learning. One commit.
-- ⏭️ **Near-shape clustering** — edit-distance over Shapes catches
-  near-duplicates that today require exact match. Bigger scope — needs
-  a Shape distance metric, candidate-pair search, and CLI for
-  inspection. Two or three commits.
-
-**Phase 3**: not started. Schema export, PII mode, streaming observatory,
-external recognizer registry.
-
-**Housekeeping done**: Ruby 3.3 dropped (4d49509), shell completion
-with brew auto-install (v0.25), homebrew skill updated, README has the
-full learning-loop documentation, all CLI flags reflected in `-h` and
-completion scripts. Homebrew formula tracks 0.28.0.
-
-**Recommended next commit**: inter-position correlations. The
-read-side seam is clean (walk clusters, group segments by their
-predecessor) and the payoff is concrete (next-segment hints for
-corpus-informed normalization). Falls out of the existing data with
-no schema changes.
-
-## Operating ground rules (decisions on file)
-
-- **Backward compatibility:** none required while pre-1.0. Break what you must.
-  Bump the minor version per feature.
-- **Public API surface:** narrow on purpose. The four `Iriq.*` module methods
-  and the CLI are the contract; everything else may move freely. Dev speed
-  beats API stability for now.
-- **Ruby ↔ Go parity:** still the goal. The current discipline (Ruby-first,
-  fixture regen, Go-mirror, parity test) stays in force as the *acceptance
-  gate*; ordering within a single feature commit is implementer's call.
-- **Performance:** no hard target. Don't be wasteful. Watch out for obvious
-  regressions (per-segment allocation in hot paths, redundant classify calls,
-  etc.) but no benchmark gates yet.
-- **Extensibility:** internal-only is fine for v1. Design the seams so an
-  external recognizer registry is a small follow-up, not a redesign.
-- **Calibration data:** we generate and check in our own. See task #3.
-- **Commit discipline:** one feature, one commit, immediate push. Tests must
-  pass: `bundle exec rspec && go test ./... && script/cli_parity.sh`.
-
-## Phase 1 — Year 1: structural foundation
-
-Status: **complete**. All 9 tasks shipped in a single session, v0.11.0 → v0.19.0.
-
-Goal: stop being a 554-line `SegmentClassifier` doing five jobs. Land the
-substrate that the year-2 learning work compounds on.
-
-Ordered task list (each was a commit checkpoint, each bumped a minor version):
-
-1. ✅ **Docs + plan** — this file and `ARCHITECTURE.md`. Shipped at 866525f.
-2. ✅ **Recognizer interface (uuid, date, integer)** — carved three
-   Recognizers out of `SegmentClassifier`. No behavior change; first-match
-   equivalent. Shipped in v0.12.0 (b3cc889).
-3. ✅ **Calibration corpus** — 202 labeled segments across 25 types at
-   `spec/fixtures/calibration/segments.json`, generated by
-   `script/build_calibration.rb`. Loaded by both Ruby (`calibration_spec`)
-   and Go (`calibration_test.go`) as a regression suite + future
-   calibration target. Shipped in v0.13.0 (f9eb980).
-4. ✅ **Scored ensemble** — added Specificity bands (SEMANTIC, STRUCTURED,
-   BOUNDED, TYPED, PATTERN, FALLBACK) on each Recognizer's Verdict and an
-   Ensemble helper that picks max(specificity × confidence) with stable
-   earlier-wins tie-break. Shipped in v0.14.0 (924f1ba).
-5. ✅ **Position promoted to first-class** — Position is { host, scope ∈
-   {:path,:query}, locator } — a typed slot in a host's URL structure.
-   Storage contracts now take Position; SQLite schema gained a `scope`
-   column (bumped to v2). Shipped in v0.15.0 (954e7a6).
-6. ✅ **Structured Shape** — Shape is a value object: an ordered list of
-   typed segment entries plus Render() / Equal() over the structured form.
-   PathShape became a thin wrapper. Cluster gained `#shape_object`.
-   Shipped in v0.16.0 (97a60c2).
-7. ✅ **Evidence records + Trace as view** — Evidence is the structured
-   substrate for explanation: three subject kinds (segment / position /
-   cluster), five sources (lexical / recognizer / corpus / neighbor /
-   policy). Ruby Trace was rewritten to build Evidence internally and
-   render it into the same `{value, type, output, notes}` hash. Go ships
-   the Evidence types but kept Trace internals hand-coded (output parity
-   preserved). Shipped in v0.17.0 (9e1133e).
-8. ✅ **One Normalizer** — folded mechanical Normalizer and
-   corpus-informed Corpus#normalize into one entry point with an evidence
-   source. NullEvidence provides classifier-only behavior; Corpus
-   implements the same RenderPath / RenderQuery interface for
-   corpus-informed rendering. Shipped in v0.18.0 (24ad168).
-9. ✅ **Events + reducers** — Corpus.observe now builds an ordered Event
-   list (HostSeen, PathLengthSeen, RawShapeSeen, FingerprintSeen,
-   per-segment PositionSeen, ClusterAddition) and applies each through
-   the Reducer registry. Adding a new metric = define a new Event +
-   Reducer; no other module changes. Event list is transient today;
-   future commit can persist it for re-runnable inference. Shipped in
-   v0.19.0 (891fd12).
-
-End of Phase 1 deliverable: the same CLI surface, but the internals are an
-evidence-driven inference system over typed Positions with pluggable
-recognizers and re-runnable-inference-ready event emission.
-
-## Phase 2 — Year 2: learning that compounds on the new substrate
-
-Each of these is a non-trivial multi-PR initiative.
-
-- ✅ **Re-runnable inference (library)** — source-IRI log persisted alongside
-  materialized views; `Corpus#reinfer` drops the views and replays the log
-  through events + reducers. Lets users tune thresholds or swap the
-  classifier without re-feeding IRIs. Shipped in v0.21.0.
-- ✅ **Re-runnable inference (CLI)** — `iriq --corpus PATH --reinfer`
-  replays the log and prints a before/after summary. Parity scenarios
-  added for JSON + SQLite backends. Shipped in v0.22.0.
-- **Inter-position correlations** — when slot A's value predicts slot B's
-  type, surface that. Catches things like "the segment after `/orgs/{org_id}/`
-  is almost always `users` or `repos`".
-- ✅ **Learned recognizers** — full loop:
-    * `Corpus#propose_recognizers` scans observed values via pluggable
-      ProposalStrategy strategies (v0.23.0). v1 ships PrefixUnderscoreId
-      (detects `ghp_…`, `cus_…`, `sk_…` shapes at slug/opaque_id
-      positions).
-    * `iriq --corpus PATH --propose-recognizers [--json]` CLI flag with
-      tunable `--min-observations` / `--min-coverage` / `--min-hosts`
-      thresholds (v0.24.0).
-    * `Corpus#activate_proposal(p)` promotes a proposal into a live
-      SynthesizedRecognizer on the corpus's classifier, persists it,
-      and reinfers. Reopens re-apply via `Corpus.open`. Doesn't leak
-      to the module-level DEFAULT classifier — corpora are isolated
-      (v0.26.0).
-    * `iriq --corpus PATH --propose-recognizers --activate-above F`
-      auto-activates every proposal at or above coverage F (v0.26.0).
-- ✅ **Cross-host learning** — full integration:
-    * `Corpus#cross_host_shapes(min_hosts:)` lists route shapes that
-      recur across multiple hosts (independent evidence of semantic
-      pattern, not host-local quirk). CLI `--cross-host-shapes`. v0.27.0.
-    * Cross-host count wires into `RecognizerProposal#confidence`:
-      each additional host beyond the first adds 0.05 (capped at 1.0).
-      Single-host proposals get `confidence == coverage`; cross-host
-      proposals get boosted. `--activate-above F` checks confidence
-      (not raw coverage). Proposals are sorted by confidence desc.
-      v0.28.0.
-- **Near-shape clustering** — edit-distance over Shapes catches
-  near-duplicates that today require exact match.
-
-## Phase 3 — Year 3: productize
-
-Speculative; revisit after Phase 2.
-
-- Exported learned schemas (OpenAPI-ish: routes per host with inferred
-  types per Position).
-- Privacy/PII mode (recognizer-driven redaction policies).
-- Streaming observatory with shape-drift alerts.
-- External recognizer registry (the public surface for what Phase 1 keeps
-  internal).
-
-## Risks tracked
-
-- **Parity tax compounds.** Every refactor is 2× surface. If a refactor's Go
-  port slips a release, mark it explicitly in CHANGELOG and treat it as tech
-  debt — don't let it sit.
-- **Confidence calibration is theater without truth data.** Task #3 ships
-  before #4 for that reason.
-- **Recognizer-set versioning.** Once we ship pluggable recognizers, stored
-  corpora need to know which recognizer-set produced them. Plan: stamp
-  `recognizer_set_id` into `PositionStats` at observation time. Defer
-  implementation until Phase 2.
-
-## How to use this document
-
-- Update it as decisions change. It is not a frozen artifact.
-- Each completed Phase 1 task: tick it off, add a one-line "shipped in vX.Y.Z"
-  pointer. Don't delete history.
-- Bigger plan changes (reorder, scope cut, scope grow): leave the prior
-  list intact and append a "Plan change YYYY-MM-DD" note explaining why.