convert_sdk 1.0.0

data/README.md

@@ -0,0 +1,183 @@
+# Convert Ruby SDK
+
+[![Quality Checks](https://github.com/convertcom/ruby-sdk/actions/workflows/qa.yml/badge.svg)](https://github.com/convertcom/ruby-sdk/actions/workflows/qa.yml)
+[![Gem Version](https://badge.fury.io/rb/convert_sdk.svg)](https://rubygems.org/gems/convert_sdk)
+[![API docs](https://img.shields.io/badge/API_docs-YARD-blue)](https://convertcom.github.io/ruby-sdk)
+
+The official Convert Experiences FullStack Ruby SDK — server-side A/B testing,
+feature flags, and personalizations for Ruby applications. Bucketing-compatible
+with the Convert JavaScript SDK. **Zero runtime dependencies** (stdlib only).
+
+- **Fork-safe with zero configuration** — works under Puma cluster, Unicorn,
+  Passenger, Sidekiq, AWS Lambda, and plain CLI scripts. See
+  [Fork safety](#fork-safety-zero-config) below — it's the differentiator.
+- **Never crashes the host** — every public method degrades to a documented
+  return value and a log line; only misconfiguration at `ConvertSdk.create`
+  raises (an `ArgumentError`).
+- **Ruby ≥ 3.1** — CRuby 3.1–3.4 and JRuby are supported.
+
+## Install
+
+```ruby
+# Gemfile
+gem "convert_sdk"
+```
+
+```sh
+gem install convert_sdk
+```
+
+## 5-minute start
+
+The complete flow — build a client, create a per-visitor context, decide an
+experience, act on the result, track a conversion, and flush — in one
+copy-pasteable block:
+
+```ruby
+require "convert_sdk"
+
+# 1. Build ONE client at boot and reuse it for the life of the process.
+#    (Fetch mode: pass an sdk_key. Direct-data mode: pass a pre-fetched `data:`.)
+CONVERT_SDK = ConvertSdk.create(sdk_key: ENV.fetch("CONVERT_SDK_KEY"))
+
+# 2. One context per visitor (per web request / per job). Cheap — no network,
+#    no thread.
+context = CONVERT_SDK.create_context("visitor-123", { "country" => "US" })
+
+# 3. Decide an experience. Returns a BucketedVariation on a hit, or a Sentinel
+#    on a miss — NEVER raises, NEVER a bare nil.
+variation = context.run_experience("homepage-test")
+
+# 4. Act on the result. `variation&.key` is the variation key on a hit and nil
+#    on a miss (a Sentinel's #key is always nil), so a single `case` covers both.
+case variation&.key
+when nil           then render_default        # business miss — show the control
+when "treatment"   then render_treatment
+else                    render_variation(variation.key)
+end
+
+# 5. Track a conversion with revenue. Deduplicated per visitor per goal.
+context.track_conversion("purchase", goal_data: { amount: 49.99, transaction_id: "tx-1" })
+
+# 6. Flush queued events synchronously. In long-running servers the background
+#    timer also drains; call flush explicitly before a process exits (Lambda/CLI).
+CONVERT_SDK.flush
+```
+
+> **Production wiring per runtime** — Rails, Sidekiq, AWS Lambda, and CLI recipes live in the wiki: [Fork Safety & Runtime Recipes](https://github.com/convertcom/ruby-sdk/wiki/ForkSafety) and [Quickstart](https://github.com/convertcom/ruby-sdk/wiki/Quickstart).
+
+## Fork safety (zero config)
+
+Fork safety is the SDK's flagship guarantee, so it leads the docs.
+
+**The claim:** build the client once, let your server fork workers, and events
+are delivered from every forked worker — **with zero fork-handling code in your
+app.** No `postfork`, no `on_worker_boot` hook required.
+
+**How it works:**
+
+- At `require "convert_sdk"` the SDK installs a single `Process._fork` hook
+  (its only global mutation). The hook is cheap and starts **no threads**.
+- The SDK starts **no background threads until first use** — a client built in a
+  preloading master (Puma `preload_app!`) carries no thread state across the
+  fork.
+- On the first decision in a forked worker, the `_fork` detection plus
+  **PID-guarded** flush boundaries automatically re-arm the client (timers
+  re-start lazily, the queue's process ownership resets) — so the worker decides
+  and delivers on its own.
+
+**When you need `postfork`:** only for setups that bypass `Process._fork`
+entirely (or daemonize via `Process.daemon`), or if you prefer an explicit
+re-arm (LaunchDarkly-style). The
+[fork/daemon matrix in the troubleshooting guide](https://github.com/convertcom/ruby-sdk/wiki/ForkSafety#forkdaemon-matrix)
+spells out exactly which runtimes are automatic and which need an explicit
+`CONVERT_SDK.postfork` call. The four quickstarts ship the right wiring for each.
+
+## Public API
+
+The full public API is documented in the wiki and the YARD API reference. The
+entry point is `ConvertSdk.create` (factory); it returns a `Client` with
+`#create_context`, `#flush`, `#postfork`, and `#on`. Each `Context` exposes
+`#run_experience`, `#run_feature`, `#track_conversion`, and related methods.
+See [Code Examples](https://github.com/convertcom/ruby-sdk/wiki/CodeExamples) and
+the **[API reference (YARD)](https://convertcom.github.io/ruby-sdk)** for full
+signatures.
+
+## The sentinel return contract
+
+Decisioning methods **never raise** and **never return a bare `nil`** for a
+business miss. They return a value object:
+
+- A **hit** returns a frozen `BucketedVariation` (or `BucketedFeature`): `#key`
+  is the real key, `#error?` is `false`.
+- A **miss** returns a frozen `Sentinel`: `#key` is **always `nil`**, `#error?`
+  is **always `true`**, and `#to_s` is the wire string.
+
+This is why the documented branch pattern works for both cases at once:
+
+```ruby
+case (variation = context.run_experience("homepage-test")).key
+when nil then render_default            # Sentinel — a business miss
+else          render_variation(variation.key)
+end
+```
+
+For features, branch on `#status` instead (a feature miss is a DISABLED
+`BucketedFeature`, never a sentinel):
+
+```ruby
+feature = context.run_feature("new-checkout")
+if feature.status == ConvertSdk::FeatureStatus::ENABLED
+  render_new_checkout(feature.variables["headline"])
+else
+  render_legacy_checkout
+end
+```
+
+## Configuration
+
+All configuration options are passed as keyword arguments to `ConvertSdk.create`.
+See the [Configuration wiki page](https://github.com/convertcom/ruby-sdk/wiki/Configuration)
+for the full option table with defaults. Pass `data_refresh_interval: nil` and
+`flush_interval: nil` for Lambda/CLI (timer-off mode).
+
+## Data stores
+
+Sticky bucketing and goal deduplication persist through a store port (default:
+in-process `MemoryStore`). See
+[Configuration](https://github.com/convertcom/ruby-sdk/wiki/Configuration) for
+the `RedisStore` recipe and custom store duck-typing contract.
+
+## Documentation
+
+Full developer documentation lives in the **[Convert Ruby SDK wiki](https://github.com/convertcom/ruby-sdk/wiki)**:
+
+- [Quickstart](https://github.com/convertcom/ruby-sdk/wiki/Quickstart) ·
+  [Installation](https://github.com/convertcom/ruby-sdk/wiki/Installation) ·
+  [Initialization](https://github.com/convertcom/ruby-sdk/wiki/Initialization)
+- [Configuration](https://github.com/convertcom/ruby-sdk/wiki/Configuration) ·
+  [Return Types & Sentinels](https://github.com/convertcom/ruby-sdk/wiki/ReturnTypes) ·
+  [Code Examples](https://github.com/convertcom/ruby-sdk/wiki/CodeExamples)
+- [Fork Safety & Runtime Recipes](https://github.com/convertcom/ruby-sdk/wiki/ForkSafety) ·
+  [Tracking Control](https://github.com/convertcom/ruby-sdk/wiki/TrackingControl) ·
+  [Testing](https://github.com/convertcom/ruby-sdk/wiki/Testing)
+- Core concepts & how-to: bucketing algorithm, rule evaluation, running experiences (see the wiki sidebar)
+- **[API reference (YARD)](https://convertcom.github.io/ruby-sdk)** — generated method-level docs
+- **[Contributing](CONTRIBUTING.md)**
+
+## Development
+
+```sh
+bundle install        # install dev/test dependencies
+bundle exec rake      # the default task: RSpec + RuboCop
+bundle exec rbs -r net-http -r uri -r json -I sig validate   # validate RBS signatures
+bundle exec steep check                                      # static type check
+```
+
+Publishing is handled exclusively by the OIDC release workflow — there is no
+`rake release` task. See [CONTRIBUTING.md](CONTRIBUTING.md) for the release
+process.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

data/RELEASE.md

@@ -0,0 +1,313 @@
+# Release Process
+
+This document describes how releases of the Convert Ruby SDK (`convert_sdk`) are
+produced and what must be configured before the release pipeline can run.
+
+The short version: **every push to `main` whose Conventional Commit history
+contains a `feat:`, `fix:`, `refactor:`, or a `BREAKING CHANGE` triggers a new
+release.** The release workflow runs `semantic-release`, which writes the next
+version into `lib/convert_sdk/version.rb` (a build-time, **uncommitted**
+working-tree edit), builds and pushes the gem to RubyGems.org via **OIDC Trusted
+Publishing**, then creates the `vX.Y.Z` git tag and a GitHub Release with the
+generated notes.
+
+No manual version bumping. No manual publishing. No long-lived RubyGems API key.
+Conventional commits drive everything, and there is **no `rake release` task** —
+publishing happens only through the OIDC `release.yml` workflow.
+
+---
+
+## Release Chain Overview
+
+```
+PR merged to main (squash merge → PR title becomes the commit subject)
+  -> "Quality Checks" workflow runs (lint, typecheck, matrix RSpec, parity,
+     full-chain, gem-smoke)
+  -> "Release" workflow triggers via workflow_run AFTER Quality Checks succeeds
+     (and only when the triggering event was a push to main)
+    -> rubygems/configure-rubygems-credentials exchanges the workflow's OIDC
+       token for a short-lived RubyGems credential
+    -> semantic-release analyzes commits since the last v* tag:
+      1. @semantic-release/commit-analyzer          → compute next version
+      2. @semantic-release/release-notes-generator   → render markdown notes
+      3. @semantic-release/exec (prepareCmd)         → write version into
+                                                       lib/convert_sdk/version.rb
+                                                       (UNCOMMITTED working-tree edit)
+      4. @semantic-release/exec (publishCmd)         → gem build + gem push
+                                                       to RubyGems.org
+      5. @semantic-release/github                    → push vX.Y.Z tag + create
+                                                       GitHub Release (via API)
+```
+
+The pipeline is **tag-only** — it pushes **no commit** to `main`. semantic-release
+core pushes only the `vX.Y.Z` tag (a `refs/tags/*` ref, which the `main` branch
+ruleset does not gate), and `@semantic-release/github` creates the Release via
+the GitHub API. The version write in `lib/convert_sdk/version.rb` is a build-time
+working-tree edit consumed by `gem build` and is **never committed**; the next
+release derives its version from this run's git tag.
+
+The plugin order above is **load-bearing** (defined in `release.config.mjs`).
+**Publish-before-Release:** step 4 (`gem push`) runs before step 5 (the GitHub
+Release). If `gem push` fails, semantic-release aborts **before** the tag and
+Release are finalized — there is never a GitHub Release without a corresponding
+gem on RubyGems.org. The repo stays in its pre-release state and the next push
+retries.
+
+This release flow uses no `@semantic-release/git` and no
+`@semantic-release/changelog` plugins (deliberately forbidden — they would commit
+to `main` and ship a committed `CHANGELOG.md`). The changelog lives on **GitHub
+Releases** (the gemspec's `changelog_uri` points there).
+
+---
+
+## Versioning & Conventional-Commit Map
+
+semantic-release computes the next version with the standard
+`@semantic-release/commit-analyzer` (`conventionalcommits` preset). Only the
+following commit types influence a release; everything else is a no-release:
+
+| Commit type | Release type | In release notes |
+|---|---|---|
+| `fix:` | patch | Yes (Bug Fixes) |
+| `feat:` | minor | Yes (Features) |
+| `refactor:` | (per preset) | Yes (Refactoring) |
+| `BREAKING CHANGE:` footer / `!` marker | **major** | Yes |
+| `chore:`, `docs:`, `ci:`, `test:`, `style:`, `perf:` | no release | No (hidden) |
+
+The release-notes generator surfaces only `feat` / `fix` / `refactor` sections;
+the maintenance types (`chore`, `docs`, `ci`, `test`, `style`, `perf`) are marked
+hidden in `release.config.mjs` and never appear in the notes.
+
+All tags use the `v` prefix (`v1.0.0`, `v1.2.3`) — `tagFormat: 'v${version}'`.
+
+---
+
+## One-Time Setup (Repo Admin)
+
+These steps must be completed **before the first merge to `main`** that should
+publish, otherwise the release workflow will fail.
+
+### 1. Register the RubyGems Trusted Publisher (OIDC)
+
+RubyGems OIDC Trusted Publishing lets the release workflow authenticate with a
+short-lived, exchanged credential instead of a long-lived API key. Register the
+trusted publisher on RubyGems.org once:
+
+1. Sign in at <https://rubygems.org>.
+2. Create (or claim) the gem `convert_sdk` if it does not exist yet (the first
+   `gem push` can also create it once trusted publishing is wired — but the
+   trusted-publisher entry must exist first).
+3. Go to the gem's settings → **Trusted publishers** → **Add a new publisher**
+   (GitHub Actions), and enter:
+   - **Repository:** `convertcom/ruby-sdk`
+   - **Workflow filename:** `release.yml`
+   - (Optional) environment: leave blank — the workflow uses no GitHub
+     Environment.
+4. Save. From then on, the `release.yml` workflow running on
+   `convertcom/ruby-sdk` is trusted to publish `convert_sdk` with no stored API
+   key.
+
+There is **no `RUBYGEMS_API_KEY` secret anywhere** — the
+`rubygems/configure-rubygems-credentials@v2.0.0` step in `release.yml` performs
+the OIDC token exchange at run time. This is the Ruby-specific divergence from
+the PHP SDK (whose `release.yml` carries only `contents: write`); ours also needs
+`id-token: write`.
+
+### 2. Enable GitHub Pages (API docs)
+
+The YARD API docs deploy to GitHub Pages on every push to `main`
+(`.github/workflows/pages.yml`). Enable Pages once:
+
+1. Repo → **Settings** → **Pages**.
+2. Set **Source** to **GitHub Actions**.
+
+The published docs site is `https://convertcom.github.io/ruby-sdk` (the gemspec's
+`documentation_uri`).
+
+### 3. Repository secrets
+
+| Secret | Required | Source |
+|---|---|---|
+| `GITHUB_TOKEN` | yes (auto) | Provided automatically by GitHub Actions for every run — nothing to configure. Used by semantic-release core to push the `vX.Y.Z` tag and by `@semantic-release/github` to create the Release. |
+
+That is the **complete** secret list. RubyGems authentication is handled by OIDC
+Trusted Publishing (step 1), so no RubyGems API-key secret is stored. The
+workflow's only declared permissions are `contents: write` (tag + Release) and
+`id-token: write` (OIDC exchange).
+
+### 4. Branch-protection required checks
+
+Configure branch protection on `main` (Repo → **Settings** → **Branches** →
+add/edit the `main` rule) to require these status checks to pass before merge.
+The names below are the **exact job names** from the workflows — quote them
+verbatim:
+
+From the **Quality Checks** workflow (`.github/workflows/qa.yml`):
+
+- `PR title (Conventional Commits)`
+- `Lint (RuboCop)`
+- `Typecheck (RBS + Steep)`
+- `Test (3.1)`, `Test (3.2)`, `Test (3.3)`, `Test (3.4)`, `Test (jruby)`
+- `Cross-SDK parity (MurmurHash3)` — **release-blocking** (100% of the vendored
+  MurmurHash3 vectors must pass)
+- `Full-chain release gate` — **release-blocking** (the end-to-end
+  create→decide→track→flush loop, exact wire bytes, zero secret leakage)
+- `Gem build / install / require smoke`
+
+From the **Demo Fork Smoke** workflow (`.github/workflows/demo-smoke.yml`, a
+structurally independent workflow):
+
+- `Puma-cluster fork smoke (release-blocking)` — **release-blocking** (events
+  from ≥ 2 distinct forked Puma workers reach the track endpoint)
+
+The two release-blocking gates and the fork-smoke gate must be in the required
+set so a hashing/wiring/fork-safety regression can never reach a published gem.
+
+---
+
+## Triggering a Release
+
+Releases are fully automatic. The process:
+
+1. Open a PR containing one or more conventional commits. This repo is
+   **squash-merge only**, so the **PR title** becomes the squash commit subject
+   and must itself be a valid Conventional Commit (CI validates it).
+2. Merge the PR to `main`. GitHub fires the **Quality Checks** workflow
+   (`.github/workflows/qa.yml`).
+3. On Quality Checks success, GitHub fires the **Release** workflow
+   (`.github/workflows/release.yml`) via a `workflow_run` trigger
+   (`workflows: ['Quality Checks']`, `branches: [main]`).
+4. semantic-release analyzes every commit on `main` since the last `v*` tag and
+   applies the version/notes map above.
+5. If a release-worthy commit exists, it writes the version into
+   `lib/convert_sdk/version.rb`, runs `gem build convert_sdk.gemspec && gem push
+   convert_sdk-*.gem`, then pushes the `vX.Y.Z` tag and creates the GitHub
+   Release. If nothing is release-worthy (only `chore`/`docs`/`ci`/`test`/…),
+   the workflow succeeds silently with no release.
+
+**No manual publish step.** You never bump the version or run `gem push` by hand
+— write an accurate PR title and the pipeline does the rest on merge.
+
+---
+
+## Previewing a Release: Dry Run
+
+`yarn release:dry-run` runs semantic-release in dry-run mode
+(`semantic-release --dry-run --no-ci`). It will:
+
+- Analyze commits since the last tag.
+- Decide the next version.
+- Show the rendered release notes.
+- **Not** write `version.rb`, **not** build or push the gem, **not** tag.
+
+semantic-release checks the current branch against the `branches` entry in
+`release.config.mjs` (currently `['main']`). On `main`, the dry-run prints the
+next-version plan. On any other branch it exits with:
+
+```
+This test run was not triggered in a known release branch
+```
+
+That message is **expected** — it confirms the config parses. To exercise a full
+dry-run on a feature branch, temporarily add the branch name to
+`release.config.mjs`'s `branches` array, run the dry-run, then discard the
+temporary edit before committing:
+
+```bash
+# On main:
+yarn release:dry-run
+
+# On a feature branch (full dry-run):
+# 1. Edit release.config.mjs → branches: ['main', 'feature/my-branch']
+# 2. yarn release:dry-run
+# 3. discard the temporary edit to release.config.mjs (do NOT commit it)
+```
+
+The branch must exist on `origin` (semantic-release needs `git ls-remote`); push
+first if it is local-only.
+
+---
+
+## First Release (v1.0.0)
+
+The first release is produced automatically by the pipeline — no manual tagging.
+On the first merge to `main` after the release workflow is configured,
+semantic-release observes that no prior `v*` tag exists, so it:
+
+1. Treats every releasable commit in history (all `feat:` / `fix:` / `refactor:`
+   / `BREAKING CHANGE` since project inception) as part of the first release.
+2. Emits `v1.0.0` as the version (semantic-release's fixed first-release
+   default).
+3. Generates a release-notes block covering the full history, grouped by commit
+   type.
+4. Writes `1.0.0` into `lib/convert_sdk/version.rb` (uncommitted), runs `gem
+   build` + `gem push`, then pushes the `v1.0.0` tag and publishes a GitHub
+   Release on it.
+
+`lib/convert_sdk/version.rb` ships with `VERSION = "0.0.0"` as a dev placeholder
+— the first release overwrites it at build time (and never commits the change).
+Do **not** create a `v1.0.0` tag manually before or after the first merge — the
+pipeline owns this, and a pre-existing tag will be raced or block the automated
+tag push.
+
+---
+
+## Fork-PR Safeguard (DO NOT REMOVE)
+
+The release workflow's `if:` guard carries two conditions, both required:
+
+```yaml
+if: >
+  github.event.workflow_run.conclusion == 'success' &&
+  github.event.workflow_run.event == 'push'
+```
+
+The **second** condition — `github.event.workflow_run.event == 'push'` — is
+critical. `workflow_run` fires on every completed Quality Checks run, including
+runs triggered by pull requests. Fork PRs run with no secret/OIDC access, so
+without this guard a fork PR's Quality Checks run would also fire the release
+workflow, which would either:
+
+1. Fail noisily (no OIDC token to exchange), cluttering the PR with red
+   cross-marks, or — worse —
+2. Under certain misconfigurations, leak into the PR's logs.
+
+Always keep the `push` check. If you are ever tempted to remove it because
+"release ran twice for one push", the answer is almost certainly a different fix
+(concurrency groups — the workflow already uses `concurrency: { group: release,
+cancel-in-progress: false }`), not weakening this guard.
+
+---
+
+## Rollback Procedure
+
+**Published RubyGems versions cannot be silently replaced.** Once `convert_sdk
+X.Y.Z` is pushed, re-pushing the same version is rejected. If a bad release slips
+through:
+
+1. Do **not** try to overwrite the version.
+2. Push a conventional `fix:` commit that addresses the problem. The next release
+   workflow publishes a new patch version (e.g. if `v1.2.3` was bad, the fix
+   ships as `v1.2.4`).
+3. If the bad version must be made un-installable, **yank** it:
+   ```bash
+   gem yank convert_sdk -v X.Y.Z
+   ```
+   `gem yank` removes the version from the index so it can no longer be resolved
+   by `gem install` / `bundle install`, but it does **not** delete the artifact
+   and the version number can never be reused. Prefer shipping a forward fix
+   (`fix:`) over yanking unless the release is actively harmful.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `release.yml` didn't run after a merge to `main` | Quality Checks failed, or the triggering event wasn't a push, or the commits were all non-release types. | Check the Actions tab — the Release workflow only proceeds when Quality Checks concluded `success` AND the event was `push`. If Quality Checks failed, fix that. If the commits were `chore:`/`docs:`, no release is expected. |
+| Release ran but published nothing | No release-worthy commit since the last tag (only `chore`/`docs`/`ci`/`test`/`style`/`perf`). | Expected — semantic-release succeeds silently with no version. Land a `feat:`/`fix:` to publish. |
+| `gem push` failed / no RubyGems credential | The RubyGems Trusted Publisher is not registered (or the repo/workflow filename in the registration doesn't match `convertcom/ruby-sdk` ↔ `release.yml`). | Re-check the trusted-publisher entry on rubygems.org (One-Time Setup step 1). The workflow needs `id-token: write` (it has it) and the OIDC exchange step must run before semantic-release. |
+| GitHub Release/tag created but gem missing | Should not happen — publish runs before the Release (publish-before-Release). If you see it, a manual tag was likely pushed out of band. | Do not hand-create `v*` tags. Let the pipeline own tagging. |
+| `yarn release:dry-run` errors "This test run was not triggered in a known release branch" | Expected on any branch except `main`. | To force a full dry-run on a feature branch, temporarily add the branch to `release.config.mjs`'s `branches` array (discard before committing). On `main`, this means the local branch isn't pushed to `origin` — push first. |
+| `Cannot find module '<preset>'` from a semantic-release plugin | The yarn node linker isn't producing a `node_modules/` tree the dynamic preset import can walk. | Confirm `.yarnrc.yml` selects the `node-modules` linker and re-run `yarn install --immutable`. |
+| Forbidden release mechanism reintroduced (lint job fails) | A `@semantic-release/git`/`@semantic-release/changelog` plugin, a `rake release` task, `bundler/gem_tasks`, or `rubygems/release-gem` was added. | These are blocked by the release-safety step in the `Lint (RuboCop)` job. Remove the forbidden mechanism — publishing happens only via OIDC `release.yml`. |

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# NOTE: `bundler/gem_tasks` is deliberately NOT required. It defines `rake
+# release`, whose `git_push` pushes the branch ref (the Android qs-03 GH013
+# failure mode). Publishing happens exclusively via the OIDC release workflow
+# (Epic 5) — `rake release` MUST NOT exist in this gem.
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/convert_sdk.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "lib/convert_sdk/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "convert_sdk"
+  spec.version = ConvertSdk::VERSION
+  spec.authors = ["Convert Insights, Inc."]
+  spec.email = ["support@convert.com"]
+
+  spec.summary = "Convert Experiences FullStack Ruby SDK for A/B testing, feature flags, and personalizations."
+  spec.description = "The official Convert Experiences Ruby SDK. Provides bucketing-compatible " \
+                     "A/B testing, feature flag evaluation, and personalizations for server-side Ruby " \
+                     "applications (Rails, Sinatra, Hanami, and plain scripts). Zero runtime dependencies."
+  spec.homepage = "https://www.convert.com"
+  spec.license = "Apache-2.0"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/convertcom/ruby-sdk"
+  spec.metadata["changelog_uri"] = "https://github.com/convertcom/ruby-sdk/releases"
+  spec.metadata["documentation_uri"] = "https://github.com/convertcom/ruby-sdk/wiki"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  #
+  # The reject list keeps non-runtime files OUT of the packaged gem. The Node
+  # release tooling (package.json / release.config.mjs / lockfiles / .releaserc /
+  # node_modules) is DEV-ONLY: it drives semantic-release on the CI runner and
+  # must NOT ship inside the gem — the gem keeps ZERO runtime deps and contains
+  # no Node artifacts. (node_modules is also gitignored, so it won't appear in
+  # `git ls-files`, but it is listed defensively.)
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[
+                        bin/ test/ spec/ features/ docs/ demo/ sig/
+                        .git .github appveyor Gemfile Steepfile
+                        package.json package-lock.json yarn.lock .yarnrc.yml .yarn/
+                        release.config.mjs .releaserc .npmrc node_modules/
+                      ])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies are EMPTY by design (zero-runtime-deps architecture —
+  # stdlib only at runtime). Adding a runtime dependency is an architecture
+  # change, not a story decision. All dev/test gems live in the Gemfile.
+end