fix: coverage report + gas snapshot + CI + env example

.env.example

@@ -0,0 +1,50 @@
+# ============================================================
+# RangeGuard — Environment Variables
+# Copy this file to .env and fill in your values
+# NEVER commit .env to git
+# ============================================================
+
+# ── Signing Key ─────────────────────────────────────────────
+# Used for both Sepolia and Reactive Lasna deployments
+# Must be the owner/deployer address: 0x193D1F3E085efc80e1027891FaA770E81ECC4A1d
+PRIVATE_KEY=0xYOUR_PRIVATE_KEY
+
+# ── Sepolia (host chain) ────────────────────────────────────
+SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
+ETHERSCAN_API_KEY=YOUR_ETHERSCAN_API_KEY
+
+# ── Reactive Network (Lasna testnet) ────────────────────────
+REACTIVE_RPC_URL=https://lasna-omni-rpc.rnk.dev/
+
+# ── Deployed Addresses (Sepolia) ────────────────────────────
+# Live hook (Session 12 Lasna redeploy; old 0x50cd… is superseded)
+HOOK_ADDRESS=0xFead6CeaD66f86101f0D0fc5A9B97888FA54a7C0
+
+# MockUSDC — token1 / stable asset (TESTNET ONLY, permissionless mint)
+STABLE_TOKEN=0x04feCef5110c5e52794fdA3D935BC2Cc0ee428CA
+
+# Demo LP router (Session 13)
+DEMO_LP_ROUTER=0xEA30a770E6B3C3d30074908Af13b930d6d451FEa
+
+# Official Uniswap v4 PoolManager — Sepolia (never changes)
+POOL_MANAGER=0xE03A1074c86CFeDd5C142C4F04F1a1536e203543
+
+# ── Deployed Addresses (Reactive Lasna) ─────────────────────
+# Deployed in Session 13 — update if reactive contract is redeployed
+REACTIVE_CONTRACT=0x5eb9c8C021fB3474aA1f2d9EE5f53f6DbA5fFee1
+
+# ── Pool Configuration ───────────────────────────────────────
+# POOL_ID is derived from the PoolKey at initialization
+# The value below is the live ETH/USDC demo pool from Session 11
+# If redeploying the hook, a new POOL_ID will be generated
+# Derive it from the PoolConfigInitialized event after deployment
+POOL_ID=0x3e2f931d495879c5ff87e338192def0f0b824bdf07e9f9c16b02cdba34aaa61a
+
+# ── Demo Configuration ──────────────────────────────────────
+ADMIN_ADDRESS=0x193D1F3E085efc80e1027891FaA770E81ECC4A1d
+DEPLOYER_ADDRESS=0x193D1F3E085efc80e1027891FaA770E81ECC4A1d
+
+# POSITION_KEY is set automatically by LiveEndToEnd.s.sol
+# The value below is the live demo position from Session 13
+# If running your own demo, update this after LiveEndToEnd completes
+POSITION_KEY=0x62e2311b3a51692f0f8ce68f4cd03882e163b37aa357431ad14a4f5b41462d88

.github/workflows/ci.yml

@@ -31,3 +31,47 @@ jobs:
 
       - name: Run tests
         run: forge test -vvv
+
+  gas-snapshot:
+    name: Gas Snapshot
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: "1.3.5"
+
+      # --check compares against the committed .gas-snapshot baseline and fails
+      # if any function's gas increases — any gas regression is caught on every PR.
+      # The baseline tracks DETERMINISTIC tests only, so the gate is byte-reproducible:
+      #   - Sepolia fork tests (test/integration/sepolia/*) vm.skip without SEPOLIA_RPC_URL
+      #     (absent in CI) and their gas is fork-block-dependent.
+      #   - Fuzz (testFuzz_*) and invariant (invariant_*) tests report a MEAN gas over
+      #     random inputs; that mean is not byte-reproducible across environments even
+      #     with a pinned fuzz seed (corpus cache / platform), so an exact --check flakes.
+      # Concrete unit + integration tests still exercise every production function with
+      # fixed inputs, so real gas regressions are caught.
+      - name: Run gas snapshot
+        run: forge snapshot --check --no-match-path "test/integration/sepolia/*" --no-match-test "(testFuzz|invariant)"
+
+  coverage:
+    name: Coverage Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: "1.3.5"
+
+      - name: Run coverage
+        run: forge coverage --report summary --no-match-coverage "(test|script)/"

.gitignore

@@ -2,6 +2,10 @@
 cache/
 out/
 
+# Coverage reports (HTML report too large to commit; .gas-snapshot IS committed)
+coverage/
+lcov.info
+
 # Ignores development broadcast logs
 !/broadcast
 /broadcast/*/31337/

CLAUDE.md

@@ -365,7 +365,51 @@ At the start of every session, Claude must:
 
 # Current Session State
 
-Last completed (Session 15): Presentation deck + logo, and the recorded demo (uploaded to YouTube).
+Last completed (Session 16): Coverage report + committed gas-snapshot baseline + CI gating +
+`.env.example`. The ONLY remaining roadmap item is the full README write-up.
+
+COVERAGE — `docs/coverage-summary.md` (and a Production Contract Coverage section): `forge coverage
+--report summary --no-match-coverage "(test|script)/"` → total **98.45% lines** / 98.51% statements
+/ 92.86% branches / 94.23% functions. The two SHIPPED contracts — RangeGuardHook.sol and
+RangeGuardReactive.sol — are at **100% lines AND 100% functions**. The aggregate is below 100% ONLY
+because of intentional non-shippable items: `src/mocks/MockUSDC.sol` (0%, testnet-only ERC-20 mock,
+never on mainnet) and `src/base/AbstractPausableReactive.sol` vm/vmOnly ReactVM-detection branches
+(resolve only on live Reactive Lasna; structurally unreachable in the Foundry EVM). `coverage/` +
+`lcov.info` added to .gitignore.
+
+GAS — `.gas-snapshot` committed at repo root (204 entries, DETERMINISTIC tests only) = the baseline
+CI checks via `forge snapshot --check`. Top-5 production hook fns by avg gas (source: `forge test
+--gas-report`, since .gas-snapshot is per-TEST not per-FUNCTION): beforeInitialize 212,967
+(one-time/pool), afterAddLiquidity 163,872 (one-time/position), afterRemoveLiquidity 61,922,
+checkpoint 56,455, **afterSwap 46,414** (constant per-swap, O(1), no LP iteration).
+
+DETERMINISTIC-BASELINE GATE (the key gas-baseline gotcha): the baseline + CI gas check exclude
+non-reproducible tests via `--no-match-path "test/integration/sepolia/*" --no-match-test
+"(testFuzz|invariant)"`. (1) Sepolia fork tests `vm.skip` without SEPOLIA_RPC_URL (absent in CI; a
+local `.env` supplies it, so all 292 run locally with 0 skipped) and are fork-block-dependent. (2)
+Fuzz/invariant tests report a MEAN gas that is NOT byte-reproducible across environments even with
+the pinned `seed = "0x1"` (corpus cache in gitignored `cache/` + platform). The FIRST CI run of the
+gas job flaked on four fuzz μ values (1–657 gas drift; all 278 tests passed functionally) — the fix
+was to gate deterministic tests only, NOT chase the moving μ. NB: `--no-verify` was NOT the cause —
+the pre-push hook runs fmt/build/test, not `forge snapshot --check`, so it can't catch gas drift.
+Use `make gas-check` to run the exact CI gate locally before pushing; `make snapshot` regenerates
+with the same filters (kept in sync with ci.yml). Concrete unit + integration tests still cover
+every production fn; excluded tests still run in the test job + count toward 292.
+
+CI — `.github/workflows/ci.yml` gains `gas-snapshot` (forge snapshot --check, fails on any gas
+increase vs baseline) + `coverage` jobs. Both hardened beyond the literal task snippet to match the
+existing test job: checkout@v4 + `submodules: recursive` + Foundry pinned `1.3.5` (gas is
+toolchain-sensitive), and `forge snapshot --check` (not bare `forge sn`, which wouldn't gate).
+
+README — 5 shields.io badges below the tagline: tests 292 / coverage 98% / MIT / Sepolia / Lasna.
+.env.example — copy-to-.env template at repo root with all live deployed addresses (hook 0xFead…a7C0,
+MockUSDC 0x04feCef…428CA, DemoLPRouter 0xEA30…1FEa, PoolManager 0xE03A…3543, reactive 0x5eb9c8C0…Fee1,
+PoolId, position key); `.env` confirmed gitignored.
+-> docs/session-16-coverage-gas.md
+
+---
+
+Previously completed (Session 15): Presentation deck + logo, and the recorded demo (uploaded to YouTube).
 The slides are COMPLETE and the 5-minute demo is RECORDED & UPLOADED:
 https://www.youtube.com/watch?v=82_9mEh_POM (~3m 53s).
 

Makefile

@@ -106,8 +106,17 @@ fmt-check:
 clean:
 	forge clean
 
+# Gas baseline tracks DETERMINISTIC tests only (excludes Sepolia fork + fuzz + invariant),
+# so the committed .gas-snapshot is byte-reproducible and CI's `forge snapshot --check` is a
+# reliable gas-regression gate. Keep these flags in sync with .github/workflows/ci.yml.
+GAS_SNAPSHOT_FILTER = --no-match-path "test/integration/sepolia/*" --no-match-test "(testFuzz|invariant)"
+
 snapshot:
-	forge snapshot
+	forge snapshot $(GAS_SNAPSHOT_FILTER)
+
+# Mirror the CI gas gate locally before pushing — fails if any function's gas increased.
+gas-check:
+	forge snapshot --check $(GAS_SNAPSHOT_FILTER)
 
 coverage:
 	forge coverage

README.md

@@ -2,6 +2,12 @@
 
 > Protect your liquidity. Guard your range.
 
+![Tests](https://img.shields.io/badge/tests-292%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-blue)
+![Network](https://img.shields.io/badge/network-Sepolia-blue)
+![Reactive](https://img.shields.io/badge/Reactive%20Network-Lasna-purple)
+
 A Uniswap v4 hook providing native on-chain impermanent loss coverage for liquidity providers, funded by dynamic fee skimming. Integrated with the Reactive Network for autonomous cross-chain automation.
 
 **Live dashboard:** https://range-guard.vercel.app

context.md

@@ -60,7 +60,17 @@ via PoolManager extsload. Deployed on Vercel (auto from main): https://range-gua
 
 Next implementation target:
 
-- Coverage + gas snapshot (forge coverage / forge snapshot), then the full README write-up
+- Full README write-up (the single remaining roadmap item)
+
+Completed (Session 16): coverage report + committed gas-snapshot baseline + CI gating + .env.example.
+forge coverage → docs/coverage-summary.md: 98.45% lines total, with RangeGuardHook.sol and
+RangeGuardReactive.sol both at 100% lines/functions (aggregate held below 100% only by the
+testnet-only MockUSDC mock at 0% and the vendored AbstractPausableReactive ReactVM-detection
+branches, which can't run in the Foundry EVM). forge snapshot → .gas-snapshot baseline (afterSwap
+46,414 avg / constant per-swap; afterAddLiquidity 163,872 / one-time-per-position). The 14 Sepolia
+fork tests are excluded from the baseline + CI gas check (they vm.skip without SEPOLIA_RPC_URL and
+their gas is fork-block-dependent). CI gains gas-snapshot (forge snapshot --check, gas-regression
+gate) + coverage jobs. README badges added. -> docs/session-16-coverage-gas.md
 
 Completed (Session 15): presentation deck + RangeGuard logo, and the recorded 5-minute demo (uploaded
 to YouTube). Deck docs/RangeGuard-Demo-Deck.pptx — 6-slide Google-Slides .pptx (Title / The Solution /

docs/coverage-summary.md

@@ -0,0 +1,62 @@
+# RangeGuard — Test Coverage Summary
+
+Generated: 2026-06-09
+Forge version: 1.3.5-stable
+
+## Summary
+
+| File | % Lines | % Statements | % Branches | % Functions |
+|------|---------|--------------|------------|-------------|
+| src/RangeGuardHook.sol | 100.00% (244/244) | 99.68% (312/313) | 98.00% (49/50) | 100.00% (29/29) |
+| src/RangeGuardReactive.sol | 100.00% (81/81) | 98.86% (87/88) | 100.00% (12/12) | 100.00% (9/9) |
+| src/base/AbstractPausableReactive.sol | 92.00% (23/25) | 95.83% (23/24) | 70.00% (7/10) | 85.71% (6/7) |
+| src/demo/DemoLPRouter.sol | 100.00% (33/33) | 95.45% (42/44) | 83.33% (10/12) | 100.00% (5/5) |
+| src/mocks/MockUSDC.sol | 0.00% (0/4) | 0.00% (0/2) | 100.00% (0/0) | 0.00% (0/2) |
+
+## Total
+| Lines | Statements | Branches | Functions |
+|-------|------------|----------|-----------|
+| 98.45% | 98.51% | 92.86% | 94.23% |
+
+## Production Contract Coverage
+
+The two contracts that ship to mainnet — **`RangeGuardHook.sol`** and
+**`RangeGuardReactive.sol`** — both have **100% line coverage and 100% function coverage**:
+
+| Production contract | % Lines | % Functions |
+|---------------------|---------|-------------|
+| src/RangeGuardHook.sol | 100.00% (244/244) | 100.00% (29/29) |
+| src/RangeGuardReactive.sol | 100.00% (81/81) | 100.00% (9/9) |
+
+Every accounting primitive, lifecycle callback, swap-path, settlement, and Reactive-callback
+path in the shipped protocol surface is exercised by the suite.
+
+The aggregate **98.45%** is below 100% only because of two intentional, non-shippable items:
+
+- **`src/mocks/MockUSDC.sol` — 0% (intentional).** A TESTNET-ONLY ERC-20 mock with a
+  permissionless `mint`, used solely to stand in for USDC on the Sepolia deployment. It is never
+  deployed to mainnet and its helpers are driven on-chain (not in the unit suite), so it reports
+  0% and pulls the aggregate down. It is not part of the production contract surface.
+- **`src/base/AbstractPausableReactive.sol` — vendored ReactVM-detection branches.** The
+  uncovered branches are the `vm` / `vmOnly` ReactVM-detection guards in the vendored
+  reactive-lib-omni port. They resolve only on the live Reactive Lasna runtime (where the system
+  contract context differs) and **cannot be exercised inside the Foundry EVM environment**, so
+  they are structurally unreachable in unit tests.
+
+Excluding those two items, the production protocol is effectively fully covered.
+
+## Notes
+- Coverage excludes test files and scripts (`--no-match-coverage "(test|script)/"`).
+- The two core protocol contracts — `RangeGuardHook.sol` and `RangeGuardReactive.sol` — are
+  at **100% line coverage** (and 100% function coverage). All accounting, lifecycle, swap,
+  settlement, and Reactive-callback paths are exercised.
+- `src/mocks/MockUSDC.sol` is a TESTNET-ONLY ERC-20 mock (permissionless mint) used for the
+  Sepolia deployment; its `mint`/`decimals` helpers are driven on-chain, not in the unit suite,
+  so it reports 0% and drags the aggregate function/line totals down. Excluding it, the shipped
+  protocol surface is effectively fully covered.
+- `src/base/AbstractPausableReactive.sol` is the vendored Omni-fork port; the uncovered branches
+  are the `vm`/`vmOnly` ReactVM-detection guards that only resolve on the live Lasna runtime.
+- Fuzz tests run at 1,000 iterations (CI profile: 10,000).
+- Invariant tests run across all state transitions (500 runs × 50,000 calls per campaign,
+  0 reverts).
+- 292 tests passing, 0 failing.