ruact 0.0.4 → 0.0.6

data/spec/ruact/server_functions/snapshot_spec.rb

@@ -5,104 +5,25 @@ require "tmpdir"
 
 module Ruact
   module ServerFunctions
-    RSpec.describe Snapshot, :story_8_0a do
-      let(:posts_controller) { Class.new { def self.name = "PostsController" } }
-      let(:cats_controller)  { Class.new { def self.name = "CategoriesController" } }
-      let(:actions)          { Registry.new }
-      let(:queries)          { Registry.new }
-      let(:frozen_time)      { Time.utc(2026, 5, 13, 12, 34, 56) }
-
-      describe ".dump (Story 8.0a — pure snapshot builder)" do
-        it "returns the empty payload when both registries are empty" do
-          snapshot = described_class.dump(actions, queries, now: frozen_time)
-
-          expect(snapshot).to eq(
-            version: 1,
-            generated_at: "2026-05-13T12:34:56Z",
-            functions: []
-          )
-        end
-
-        it "merges action + query entries into a single functions array" do
-          actions.register(:create_post, kind: :action, controller: posts_controller)
-          queries.register(:categories, kind: :query, controller: cats_controller)
-
-          snapshot = described_class.dump(actions, queries, now: frozen_time)
-
-          expect(snapshot[:functions]).to contain_exactly(
-            { "ruby_symbol" => "create_post", "js_identifier" => "createPost",
-              "kind" => "action", "controller" => "PostsController" },
-            { "ruby_symbol" => "categories", "js_identifier" => "categories",
-              "kind" => "query", "controller" => "CategoriesController" }
-          )
-        end
-
-        it "sorts functions by ruby_symbol for deterministic output (Story 8.0a)" do
-          actions.register(:zeta, kind: :action, controller: posts_controller)
-          actions.register(:alpha, kind: :action, controller: posts_controller)
-          queries.register(:mike, kind: :query, controller: posts_controller)
-
-          symbols = described_class.dump(actions, queries, now: frozen_time)[:functions]
-                                   .map { |fn| fn["ruby_symbol"] }
-          expect(symbols).to eq(%w[alpha mike zeta])
-        end
-
-        it "stringifies controller class names; falls back to nil for nil controllers" do
-          actions.register(:demo_ping, kind: :action, controller: nil)
-          snapshot = described_class.dump(actions, queries, now: frozen_time)
-          expect(snapshot[:functions].first["controller"]).to be_nil
-        end
+    RSpec.describe Snapshot, :story_9_3 do
+      let(:frozen_time) { Time.utc(2026, 5, 13, 12, 34, 56) }
+      let(:entries) do
+        [
+          { "js_identifier" => "createPost", "kind" => "action", "http_method" => "POST",
+            "path" => "/posts", "segments" => [], "controller" => "posts", "action" => "create" }
+        ]
       end
 
-      describe ".functions_payload — cross-registry collision (Chunk1 Blocker 2026-05-13)" do
-        it "raises Ruact::ConfigurationError shaped per AC7 when an action and a query " \
-           "share a JS identifier (Re-run patch 2026-05-14 — message prefix aligned with " \
-           "within-registry collision)",
-           :aggregate_failures do
-          actions.register(:foo, kind: :action, controller: posts_controller)
-          queries.register(:foo, kind: :query, controller: cats_controller)
-          expect { described_class.functions_payload(actions, queries) }
-            .to raise_error(Ruact::ConfigurationError) do |error|
-              # AC7 exact shape: rake wraps to "[ruact] error: server-function naming collision: :foo (in PostsController) and :foo (in CategoriesController) both map to JS identifier \"foo\""
-              expect(error.message).to start_with("server-function naming collision:")
-              expect(error.message).to include(":foo (in PostsController)")
-              expect(error.message).to include(":foo (in CategoriesController)")
-              expect(error.message).to include('"foo"')
-              # No "kind:" annotation per Pass-2 patch 2026-05-14
-              expect(error.message).not_to include("kind:")
-            end
-        end
-
-        it "raises when different Ruby symbols cross-collide via the naming bridge" do
-          # `:foo_bar` action + `:foo__bar` query both → "fooBar"
-          actions.register(:foo_bar, kind: :action, controller: posts_controller)
-          queries.register(:foo__bar, kind: :query, controller: cats_controller)
-          expect { described_class.functions_payload(actions, queries) }
-            .to raise_error(Ruact::ConfigurationError, /server-function naming collision.*"fooBar"/m)
-        end
-
-        it "raises when both registries contain the same Ruby symbol with matching " \
-           "js_identifier (one js_identifier per emitted export is the design intent)" do
-          actions.register(:categories, kind: :action, controller: posts_controller)
-          queries.register(:categories, kind: :query, controller: cats_controller)
-          expect { described_class.functions_payload(actions, queries) }
-            .to raise_error(Ruact::ConfigurationError, /server-function naming collision/)
-        end
-      end
-
-      describe ".functions_payload (Story 8.0a — fingerprint surface)" do
-        it "excludes the generated_at timestamp so registry-equivalent calls match" do
-          actions.register(:create_post, kind: :action, controller: posts_controller)
-
-          first = described_class.functions_payload(actions, queries)
-          sleep 0.01
-          second = described_class.functions_payload(actions, queries)
-
-          expect(first).to eq(second)
+      describe ".dump_v2" do
+        it "wraps entries in a version-2 snapshot Hash" do
+          snap = described_class.dump_v2(entries, now: frozen_time)
+          expect(snap[:version]).to eq(2)
+          expect(snap[:generated_at]).to eq(frozen_time.iso8601)
+          expect(snap[:functions]).to eq(entries)
         end
       end
 
-      describe ".generate! (Story 8.0a — write-if-changed orchestration)" do
+      describe ".generate_v2! (write-if-changed)" do
         around do |example|
           Dir.mktmpdir do |dir|
             @tmpdir = dir
@@ -112,142 +33,61 @@ module Ruact
 
         let(:path) { File.join(@tmpdir, "server-functions.json") }
 
-        it "writes the file on first call and returns true" do
-          result = described_class.generate!(
-            action_registry: actions, query_registry: queries, path: path, now: frozen_time
-          )
-
-          expect(result).to be(true)
-          expect(File).to exist(path)
+        it "writes a version-2 bridge on first call" do
+          expect(described_class.generate_v2!(entries: entries, path: path, now: frozen_time)).to be(true)
           parsed = JSON.parse(File.read(path))
-          expect(parsed.fetch("version")).to eq(1)
-          expect(parsed.fetch("functions")).to eq([])
+          expect(parsed.fetch("version")).to eq(2)
+          expect(parsed.fetch("functions").first.fetch("js_identifier")).to eq("createPost")
         end
 
-        it "does NOT rewrite the file when the registry is unchanged " \
-           "(Story 8.0a — pitfall #1 mitigation)", :aggregate_failures do
-          actions.register(:create_post, kind: :action, controller: posts_controller)
-          described_class.generate!(action_registry: actions, query_registry: queries,
-                                    path: path, now: frozen_time)
-
-          original_mtime  = File.mtime(path)
-          original_bytes  = File.read(path)
-          original_time   = JSON.parse(original_bytes)["generated_at"]
-          sleep 1.05 # ensure mtime resolution is exceeded if we DID rewrite
-
-          result = described_class.generate!(
-            action_registry: actions, query_registry: queries,
-            path: path, now: Time.now.utc # different now
-          )
-
-          expect(result).to be(false)
-          expect(File.mtime(path)).to eq(original_mtime)
-          expect(JSON.parse(File.read(path))["generated_at"]).to eq(original_time)
+        it "short-circuits when entries are unchanged (no timestamp churn)" do
+          described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
+          expect(described_class.generate_v2!(entries: entries, path: path, now: Time.now.utc)).to be(false)
         end
 
-        it "rewrites the file when a function is added" do
-          described_class.generate!(action_registry: actions, query_registry: queries,
-                                    path: path, now: frozen_time)
-          actions.register(:create_post, kind: :action, controller: posts_controller)
-
-          result = described_class.generate!(
-            action_registry: actions, query_registry: queries, path: path, now: frozen_time
-          )
-
-          expect(result).to be(true)
-          expect(JSON.parse(File.read(path))["functions"].size).to eq(1)
+        it "rewrites when entries change" do
+          described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
+          more = entries + [{ "js_identifier" => "destroyPost", "kind" => "action",
+                              "http_method" => "DELETE", "path" => "/posts/:id",
+                              "segments" => ["id"], "controller" => "posts", "action" => "destroy" }]
+          expect(described_class.generate_v2!(entries: more, path: path, now: frozen_time)).to be(true)
         end
 
         it "creates the parent directory if missing" do
-          nested = File.join(@tmpdir, "deep", "nest", "server-functions.json")
-          expect do
-            described_class.generate!(action_registry: actions, query_registry: queries,
-                                      path: nested, now: frozen_time)
-          end
-            .to change { File.exist?(nested) }.from(false).to(true)
+          nested = File.join(@tmpdir, "deep", "nested", "server-functions.json")
+          expect(described_class.generate_v2!(entries: entries, path: nested, now: frozen_time)).to be(true)
+          expect(File.exist?(nested)).to be(true)
         end
 
         it "recovers from a corrupted existing file by overwriting it" do
-          File.write(path, "not json")
-          result = described_class.generate!(
-            action_registry: actions, query_registry: queries, path: path, now: frozen_time
-          )
-          expect(result).to be(true)
-          expect { JSON.parse(File.read(path)) }.not_to raise_error
-        end
-
-        it "rewrites the file when the on-disk snapshot has a different version " \
-           "(Chunk1 Major 2026-05-13 — version mismatch must not be treated as unchanged)" do
-          File.write(path, JSON.pretty_generate(version: 99, generated_at: "2020-01-01T00:00:00Z", functions: []))
-          result = described_class.generate!(
-            action_registry: actions, query_registry: queries, path: path, now: frozen_time
-          )
-          expect(result).to be(true)
-          expect(JSON.parse(File.read(path))["version"]).to eq(1)
-        end
-      end
-
-      describe "route-driven (v2) snapshot (Story 9.3)", :story_9_3 do
-        let(:entries) do
-          [
-            { "js_identifier" => "createPost", "kind" => "action", "http_method" => "POST",
-              "path" => "/posts", "segments" => [], "controller" => "posts", "action" => "create" }
-          ]
-        end
-
-        describe ".dump_v2" do
-          it "wraps entries in a version-2 snapshot Hash" do
-            snap = described_class.dump_v2(entries, now: frozen_time)
-            expect(snap[:version]).to eq(2)
-            expect(snap[:generated_at]).to eq(frozen_time.iso8601)
-            expect(snap[:functions]).to eq(entries)
-          end
-        end
-
-        describe ".generate_v2! (write-if-changed)" do
-          around do |example|
-            Dir.mktmpdir do |dir|
-              @tmpdir = dir
-              example.run
-            end
+          File.write(path, "{ not json")
+          expect(described_class.generate_v2!(entries: entries, path: path, now: frozen_time)).to be(true)
+          expect(JSON.parse(File.read(path)).fetch("version")).to eq(2)
+        end
+
+        # Story 13.4 — the new typed-query metadata must survive the JSON
+        # round-trip unchanged AND keep the file byte-stable (no churn on a
+        # second pass with identical entries).
+        context "with typed-query params metadata (Story 13.4)", :story_13_4 do
+          let(:query_entries) do
+            [
+              { "js_identifier" => "searchUsers", "kind" => "query", "http_method" => "GET",
+                "path" => "/q/searchUsers", "segments" => [], "accepts_params" => true,
+                "params" => [{ "name" => "term", "required" => true },
+                             { "name" => "limit", "required" => false }],
+                "params_rest" => false, "controller" => "CatalogQuery", "action" => "search_users" }
+            ]
           end
 
-          let(:path) { File.join(@tmpdir, "server-functions.next.json") }
-
-          it "writes a version-2 bridge on first call" do
-            expect(described_class.generate_v2!(entries: entries, path: path, now: frozen_time)).to be(true)
+          it "round-trips the params metadata unchanged" do
+            described_class.generate_v2!(entries: query_entries, path: path, now: frozen_time)
             parsed = JSON.parse(File.read(path))
-            expect(parsed.fetch("version")).to eq(2)
-            expect(parsed.fetch("functions").first.fetch("js_identifier")).to eq("createPost")
-          end
-
-          it "short-circuits when entries are unchanged (no timestamp churn)" do
-            described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
-            expect(described_class.generate_v2!(entries: entries, path: path, now: Time.now.utc)).to be(false)
-          end
-
-          it "rewrites when entries change" do
-            described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
-            more = entries + [{ "js_identifier" => "destroyPost", "kind" => "action",
-                                "http_method" => "DELETE", "path" => "/posts/:id",
-                                "segments" => ["id"], "controller" => "posts", "action" => "destroy" }]
-            expect(described_class.generate_v2!(entries: more, path: path, now: frozen_time)).to be(true)
-          end
-        end
-
-        describe ".v1_declarations? (Decision-#6 ownership primitive)" do
-          it "is false when both registries are empty" do
-            expect(described_class.v1_declarations?(Registry.new, Registry.new)).to be(false)
-          end
-
-          it "is true when the action registry has any entry" do
-            actions.register(:create_post, kind: :action, controller: posts_controller)
-            expect(described_class.v1_declarations?(actions, Registry.new)).to be(true)
+            expect(parsed.fetch("functions")).to eq(query_entries)
           end
 
-          it "is true when the query registry has any entry" do
-            queries.register(:categories, kind: :query, controller: cats_controller)
-            expect(described_class.v1_declarations?(Registry.new, queries)).to be(true)
+          it "is byte-stable: a second pass with identical entries writes nothing" do
+            described_class.generate_v2!(entries: query_entries, path: path, now: frozen_time)
+            expect(described_class.generate_v2!(entries: query_entries, path: path, now: Time.now.utc)).to be(false)
           end
         end
       end

data/spec/ruact/server_rescue_request_spec.rb

@@ -2,9 +2,9 @@
 
 # Story 9.1 — request-cycle spec for the Story 8.4 structured-error chain
 # RE-ANCHORED on the `Ruact::Server` concern (its final, v2 home). Replaces
-# `server_functions/endpoint_controller_rescue_spec.rb` (removed in the same
-# commit — AC5: no orphan salvage, no double coverage). Pins, against REAL
-# host-controller routes (no `/__ruact/fn/` anywhere):
+# the removed v1 endpoint rescue spec (AC5: no orphan salvage, no double
+# coverage). Pins, against REAL host-controller routes (no synthetic gem
+# endpoint anywhere):
 #
 #   - structured payload on function-call requests: discriminator, baseline
 #     fields, dev extras, validation_errors, suggestion (inventory A1, A2,
@@ -56,7 +56,7 @@ I18n.backend.load_translations
 require_relative "controller_request_spec" unless defined?(ControllerRequestSpecSupport)
 
 module ServerRescueSpecSupport
-  # The exact wire shape the 8.1 runtime sends on every `_makeRef` fetch:
+  # The exact wire shape the runtime sends on every server-function fetch:
   # JSON body + `Accept: application/json` — the Bucket-2 / function-call
   # request shape the concern's predicate keys on.
   FUNCTION_CALL_HEADERS = {
@@ -177,8 +177,8 @@ module ServerRescueSpecSupport
   # Host with real CSRF enforcement — the concern's explicit
   # InvalidAuthenticityToken registration must render the structured 403
   # for function-call requests (inventory A13). Forgery is flipped on
-  # per-example via `allow_forgery_protection` (class-level), mirroring the
-  # v1 spec pattern — but on the HOST controller now, not EndpointController.
+  # per-example via `allow_forgery_protection` (class-level), on the host
+  # controller that includes Ruact::Server.
   class ForgeryServerController < ActionController::Base
     include Ruact::Server
 

data/spec/ruact/server_spec.rb

@@ -10,8 +10,8 @@
 #     host until then).
 #   - AC2 / D3: the `__ruact_function_call?` predicate matrix — the single
 #     named discrimination point Story 9.2 reuses. Keyed on the raw `Accept`
-#     header containing `application/json` (what the 8.1 runtime sends on
-#     every `_makeRef` fetch); deliberately NOT `request.format`, which is
+#     header containing `application/json` (what the runtime sends on
+#     every server-function fetch); deliberately NOT `request.format`, which is
 #     influenced by path extensions and `params[:format]`.
 #
 # Request-cycle behavior (error chain, upload guard) is pinned by
@@ -55,15 +55,14 @@ RSpec.describe Ruact::Server, :story_9_1 do
       expect(before_filters.first).to eq(:__ruact_enforce_upload_limit!)
     end
 
-    it "adds NO public instance methods to the host (predicate + handlers are private)" do
+    it "adds only the Story 13.3 `ruact_errors` opt-in helper as a public method (predicate + handlers stay private)" do
+      # Story 9.1's installation surface was "nothing public"; Story 13.3 (FR98)
+      # adds exactly ONE deliberate public method — the `ruact_errors(record)`
+      # opt-in validation-error collector / reader (AC2). The dual-bucket
+      # predicate, error handlers, and flash helpers all remain private.
       added = ServerConcernUnitSupport::ConcernController.public_instance_methods -
               ServerConcernUnitSupport::PlainController.public_instance_methods
-      expect(added).to eq([])
-    end
-
-    it "registers nothing in the v1 registries (codegen exposure is Story 9.3, not 9.1)" do
-      expect(Ruact.action_registry.entries).to be_empty
-      expect(Ruact.query_registry.entries).to be_empty
+      expect(added).to eq([:ruact_errors])
     end
 
     it "keeps INHERITED host rescue_from handlers more recent than its own (review patch)",

data/spec/ruact/signed_references_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Story 13.2 (FR96) — unit specs for the signed-reference primitive:
+# Ruact.signed_global_id (outbound) + Ruact.locate_signed (inbound). Covers the
+# four epic AC cases (round-trip / tampered / expired / wrong-purpose) plus the
+# loud-omission guards that keep an unscoped or silently-non-expiring token
+# unconstructible.
+
+require "spec_helper"
+require "global_id"
+require "active_support"
+require "active_support/core_ext/integer/time"
+require "active_support/core_ext/numeric/time"
+require "active_support/message_verifier"
+
+# A GlobalID-locatable test record: globalid keys off `class.name` + `#id` and
+# resolves via `class.find(id)`. Top-level + constantizable so the locator can
+# reach it (mirrors how query_request_spec defines its host classes top-level).
+class SignedRefSpecPost
+  include GlobalID::Identification
+
+  attr_reader :id
+
+  def initialize(id)
+    @id = id.to_s
+    self.class.store[@id] = self
+  end
+
+  def self.store
+    @store ||= {}
+  end
+
+  def self.find(id)
+    store.fetch(id.to_s)
+  end
+end
+
+module Ruact # rubocop:disable Style/OneClassPerFile
+  RSpec.describe SignedReferences, :story_13_2 do
+    let(:record) { SignedRefSpecPost.new("7") }
+
+    before do
+      # globalid signing needs an app name + a verifier secret. Set both as
+      # test infrastructure (no other spec uses globalid, so the global state
+      # is inert elsewhere).
+      GlobalID.app = "ruact-test"
+      SignedGlobalID.verifier = ActiveSupport::MessageVerifier.new("a" * 64)
+    end
+
+    describe ".signed_global_id + .locate_signed round-trip (AC: round-trip)" do
+      it "mints a token that resolves back to the same record for a matching purpose" do
+        token = Ruact.signed_global_id(record, for: :post_edit, expires_in: 1.hour)
+
+        expect(token).to be_a(String)
+        expect(token).not_to eq("7")    # a signed token, not the raw id
+        expect(token).to include("--")  # MessageVerifier signature separator
+        located = Ruact.locate_signed(token, for: :post_edit)
+        expect(located.id).to eq("7")
+      end
+    end
+
+    describe ".locate_signed rejection cases" do
+      let(:token) { Ruact.signed_global_id(record, for: :post_edit, expires_in: 1.hour) }
+
+      it "rejects a tampered token (AC: tampered)" do
+        expect { Ruact.locate_signed("#{token}tamper", for: :post_edit) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+      end
+
+      it "rejects an expired token (AC: expired)" do
+        expired = Ruact.signed_global_id(record, for: :post_edit, expires_in: -1.hour)
+        expect { Ruact.locate_signed(expired, for: :post_edit) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+      end
+
+      it "rejects a wrong-purpose token (AC: wrong-for)" do
+        expect { Ruact.locate_signed(token, for: :post_delete) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+      end
+
+      it "rejects a nil / garbage token" do
+        expect { Ruact.locate_signed(nil, for: :post_edit) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+        expect { Ruact.locate_signed("not-a-token", for: :post_edit) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+      end
+
+      it "does not echo the raw token in the rejection message (no leak)" do
+        Ruact.locate_signed("#{token}tamper", for: :post_edit)
+      rescue Ruact::InvalidSignedGlobalIDError => e
+        expect(e.message).not_to include(token)
+      end
+    end
+
+    describe "loud-omission guards (never a silent insecure default)" do
+      it "raises when no purpose is given and none is configured" do
+        expect { Ruact.signed_global_id(record, expires_in: 1.hour) }
+          .to raise_error(Ruact::Error, /purpose/)
+      end
+
+      it "raises on an explicit for: nil (an unscoped token is never allowed)" do
+        expect { Ruact.signed_global_id(record, for: nil, expires_in: 1.hour) }
+          .to raise_error(Ruact::Error, /purpose/)
+      end
+
+      it "raises when expiry is omitted and none is configured" do
+        expect { Ruact.signed_global_id(record, for: :post_edit) }
+          .to raise_error(Ruact::Error, /expir/i)
+      end
+
+      it "honors an explicit expires_in: nil as a deliberate non-expiring token" do
+        token = Ruact.signed_global_id(record, for: :post_edit, expires_in: nil)
+        expect(Ruact.locate_signed(token, for: :post_edit).id).to eq("7")
+      end
+
+      it "rejects expires_in: false (globalid would silently treat it as non-expiring)" do
+        expect { Ruact.signed_global_id(record, for: :post_edit, expires_in: false) }
+          .to raise_error(Ruact::Error, /expiry must be/)
+      end
+
+      it "rejects a bare Integer expires_in (globalid would crash on #from_now)" do
+        expect { Ruact.signed_global_id(record, for: :post_edit, expires_in: 3600) }
+          .to raise_error(Ruact::Error, /expiry must be/)
+      end
+
+      it "rejects a configured default of false (the second silent non-expiring path)" do
+        Ruact.configure { |c| c.signed_global_id_default_expires_in = false }
+        expect { Ruact.signed_global_id(record, for: :post_edit) }
+          .to raise_error(Ruact::Error, /expiry must be/)
+      end
+
+      it "raises a clear error for a non-GlobalID-locatable value" do
+        expect { Ruact.signed_global_id("plain-string", for: :post_edit, expires_in: 1.hour) }
+          .to raise_error(Ruact::Error, /GlobalID-locatable/)
+      end
+
+      it "does NOT convert a valid token to a deleted record into InvalidSignedGlobalIDError " \
+         "(contract: a gone record is the host's normal finder concern, not a forged token)" do
+        token = Ruact.signed_global_id(record, for: :post_edit, expires_in: 1.hour)
+        SignedRefSpecPost.store.delete(record.id) # the row is gone, the token is still valid
+
+        # the underlying finder raises (KeyError here; ActiveRecord::RecordNotFound in a real app),
+        # NOT Ruact::InvalidSignedGlobalIDError — the primitive only owns signature/expiry/purpose.
+        expect { Ruact.locate_signed(token, for: :post_edit) }
+          .to raise_error(KeyError)
+      end
+    end
+
+    describe "configured defaults" do
+      it "falls back to signed_global_id_default_purpose / _expires_in when the call omits them" do
+        Ruact.configure do |c|
+          c.signed_global_id_default_purpose = :app_default
+          c.signed_global_id_default_expires_in = 1.hour
+        end
+
+        token = Ruact.signed_global_id(record)
+        expect(Ruact.locate_signed(token).id).to eq("7")
+        # a token minted under the default purpose must not resolve under another
+        expect { Ruact.locate_signed(token, for: :something_else) }
+          .to raise_error(Ruact::InvalidSignedGlobalIDError)
+      end
+    end
+  end
+end

data/spec/ruact/string_distance_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Ruact
+  RSpec.describe StringDistance, :story_13_5 do
+    describe ".damerau_levenshtein" do
+      it "returns 0 for identical strings" do
+        expect(described_class.damerau_levenshtein("postId", "postId")).to eq(0)
+      end
+
+      it "counts an adjacent transposition as a single edit" do
+        expect(described_class.damerau_levenshtein("postId", "postdI")).to eq(1)
+      end
+
+      it "handles empty strings" do
+        expect(described_class.damerau_levenshtein("", "abc")).to eq(3)
+        expect(described_class.damerau_levenshtein("abc", "")).to eq(3)
+      end
+    end
+
+    describe ".closest_match" do
+      let(:pool) { %w[postId initialCount title] }
+
+      it "finds the nearest candidate within the threshold (case-insensitive)" do
+        expect(described_class.closest_match("postID", pool)).to eq("postId")
+      end
+
+      it "returns nil when nothing is within distance" do
+        expect(described_class.closest_match("zzzzzzzz", pool)).to be_nil
+      end
+
+      it "prefers the smallest distance" do
+        expect(described_class.closest_match("titel", pool)).to eq("title")
+      end
+    end
+  end
+end