gemkeeper 0.8.0 → 0.8.1

data/specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-claude.md

@@ -1,124 +0,0 @@
-# Critique v1 — Claude
-# Spec 20260529-091429: Replace Geminabox with Compact Index Proxy
-
-## Summary
-
-The spec is well-structured and the goal is clear.
-The main risks are: the `/versions` merge strategy is underspecified (blocking); ETag generation rules for the merged response are missing (blocking); the upload flow has a gap around gemspec reading after upload; and the offline cache invalidation strategy needs tightening.
-
----
-
-## Blocking Issues
-
-### 1. `/versions` merge is underspecified — will block implementation
-
-FR-3.1 says private gems "take precedence" on name collision and that the response is "merged."
-The `compact_index` gem's `CompactIndex.versions(versions_file, extra_gems)` API expects a `VersionsFile` object managing a cached local file — it is not designed to do a one-shot merge of two remote sources.
-
-Missing:
-- How is the RubyGems.org `/versions` file fetched and stored? Is it written to `cache_dir/rubygems_cache/versions`?
-- Is the VersionsFile constructed from that cached file, with private gems passed as `extra_gems`?
-- What does "take precedence" mean concretely — if `rails` appears in both, does the private entry completely replace all public rails versions, or are the version lists merged?
-- The `/versions` file is append-only and chronologically ordered. A "merged" response that re-orders entries by initial release date across two sources is non-trivial. Does the spec require that ordering, or is a simpler concatenation acceptable?
-
-**Recommendation:** Add an AR or explicit note on the merge algorithm: fetch + cache the upstream versions blob, use it as the VersionsFile, inject private gems as extra_gems, let `compact_index` handle the merge. Clarify that "precedence" means the private gem's info checksum wins for any overlapping name, not that public versions are suppressed.
-
-### 2. ETag / `Repr-Digest` generation for the merged `/versions` response
-
-FR-1.3 requires these headers but does not say how they should be computed for the merged response.
-The RubyGems.org versions file has its own ETag; after merging with private gems, that ETag is invalid.
-If the server forwards the upstream ETag unchanged, Bundler will compute a SHA256 mismatch and retry.
-
-Missing: how the server derives the ETag and `Repr-Digest` for the merged response body.
-
-**Recommendation:** Specify that `ETag` and `Repr-Digest` for `/versions` are computed from the final merged response body (not forwarded from upstream), so Bundler's checksum validation passes.
-
----
-
-## Significant Gaps
-
-### 3. Gemspec reading after upload — fragility risk
-
-FR-2.1 says the server reads gemspec metadata on startup and "after each successful upload."
-But reading dependency metadata from a `.gem` file requires `Gem::Package.new(path).spec`, which loads the full gemspec.
-If a gemspec `require`s a file that isn't present in the server's load path (e.g., `require_relative "lib/my_gem/version"`), spec loading will fail silently or raise.
-
-The spec doesn't address this.
-Geminabox had the same problem and worked around it by parsing gemspecs in a subprocess.
-
-**Recommendation:** Add an AR specifying how gemspec metadata is extracted — either via `Gem::Package.new(path).spec` with rescue, or by shelling out, or by using only the embedded gemspec without loading it. Note that errors here should produce a 422 response, not a server crash.
-
-### 4. Cache invalidation for `/info/:gemname` — unclear boundary
-
-FR-3.2 says `/info/:gemname` entries are "refreshed after 60 minutes" but the spec doesn't say what triggers a refresh — wall-clock age, an upstream ETag check, or both.
-
-Bundler sends `If-None-Match` with the cached ETag.
-If the server forwards that header to RubyGems.org and gets a 304 back, should it reset the 60-minute TTL or not?
-
-**Recommendation:** Clarify: use upstream ETag for conditional GET; if upstream returns 304, update the local TTL; if upstream returns 200, overwrite cache and update TTL.
-
-### 5. Upload directory creation not specified
-
-FR-1.2 says the server saves uploaded gems to `gems_path/gems/`.
-But the server is started before any gems are synced — the `gems/` subdirectory may not exist yet.
-
-The spec should explicitly require the server to `mkdir_p gems_path/gems/` on startup (or on first upload).
-Currently `RackupProcess#generate_config_ru` creates `gems_path` but not the `gems/` subdirectory.
-
-**Recommendation:** Add to FR-1.2: if `gems_path/gems/` does not exist, create it before writing the uploaded file.
-
-### 6. Path traversal in `/gems/:filename.gem`
-
-FR-1.1 defines `GET /gems/:filename.gem` without addressing input validation.
-A filename like `../../etc/passwd` or `../gemkeeper.pid` could escape the `gems_path/gems/` directory.
-
-The spec's security review marks this N/A because the server binds to 127.0.0.1.
-That's reasonable for the server-to-client threat model, but the server also passes the filename to the filesystem and potentially to a RubyGems.org URL.
-A malformed filename could cause unexpected behavior even from localhost.
-
-**Recommendation:** Add a constraint in AR-4.1 or as an AR under Feature 1: filenames in URL paths are validated to match `/\A[a-zA-Z0-9._-]+-[\d.]+(-[a-z0-9_-]+)?\.gem\z/` before filesystem or proxy operations; return 400 otherwise.
-
----
-
-## Minor Issues
-
-### 7. `Gem.path` vs `Gem.paths.home` — API clarification
-
-FR-3.3 uses `Gem.path.map { |p| File.join(p, "cache", filename) }`.
-`Gem.path` returns an array of gem search paths (GEM_PATH), not just GEM_HOME.
-This is correct but worth confirming: on a typical mise-managed setup, `Gem.path` includes both the per-version gem home and any global paths.
-The intent (check all system caches) matches the API.
-No change needed, but the implementer should be aware that `Gem.path` may include paths without a `cache/` subdirectory — the lookup should use `File.exist?` before serving.
-
-### 8. `gemkeeper list` path discrepancy
-
-The codebase exploration noted that `gemkeeper list` reads `Dir.glob(File.join(gems_path, "gems", "*.gem"))` — meaning it expects gems in a `gems/` subdirectory.
-But `gem_syncer.rb` builds gems directly to `gems_path/<name>-<version>.gem` (no subdirectory) before uploading.
-After upload, Geminabox stores them in `gems_path/gems/`.
-
-FR-4.3 says the custom server must store uploaded gems at `gems_path/gems/` to preserve this layout.
-That's correct, but the spec should also note that `gem_syncer.rb`'s build output path (`gems_path/<name>-<version>.gem`) is a staging location, not a final location — the upload step is what moves it into `gems/`.
-This is implicit today; worth making explicit so implementers don't accidentally change the storage layout.
-
-### 9. `compact_index` gem not in Gemfile.lock yet
-
-The spec requires adding `compact_index ~> 0.15` as a runtime dependency.
-Worth noting that the Homebrew formula bundles gems and will need to be rebuilt and re-pushed to the tap for the dependency change to take effect in production.
-This is already noted in the checklist (Rollout) but not connected to a concrete release step.
-
-### 10. `/versions` response size
-
-RubyGems.org's `/versions` file is currently ~5 MB uncompressed.
-Merging it with private gems on every request (even with a 30-minute cache) means the server allocates this in memory for every `/versions` request.
-The checklist marks performance as an open item — this is the specific risk to quantify.
-
----
-
-## Summary of Required Changes
-
-1. **(Blocking)** Specify the `/versions` merge algorithm — VersionsFile from cached upstream + private gems as extra_gems; define "precedence" concretely.
-2. **(Blocking)** Specify ETag and `Repr-Digest` computation for merged `/versions` response bodies.
-3. Specify gemspec extraction strategy and error handling for FR-2.1.
-4. Clarify cache refresh trigger for `/info/:gemname` (wall-clock vs ETag-based).
-5. Add `mkdir_p gems_path/gems/` requirement to FR-1.2.
-6. Add filename validation constraint for `/gems/:filename.gem` path parameter.

data/specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-codex.md

@@ -1,125 +0,0 @@
-# Critique v1 - Codex
-
-## Overview
-
-This spec replaces Geminabox with a custom Rack app that serves private gems through Bundler's compact index protocol while proxying RubyGems.org and keeping an offline cache.
-The direction is right, but the spec is not implementation-ready yet because the compact index merge rules, cache semantics, and input validation rules are underspecified in places that Bundler will exercise directly.
-
-## Approach Summary
-
-- Add `Gemkeeper::CompactIndexServer` as a Rack app mounted by generated `config.ru`.
-- Keep the existing `GemUploader` multipart `/upload` contract and the `gems_path/gems/*.gem` final storage layout.
-- Generate private gem compact index data with `compact_index`.
-- Proxy RubyGems.org `/names`, `/versions`, `/info/:gemname`, and `/gems/:filename.gem` through `Net::HTTP`.
-- Cache upstream compact index files and gem binaries under `cache_dir/rubygems_cache/` for offline fallback.
-
-The replacement choice is well justified by Geminabox's stale dependency endpoint, but the spec currently treats "proxy plus merge" as a simple composition when it is the hardest part of the implementation.
-
-## Risks
-
-### 1. Compact index merge semantics are not concrete enough
-
-Likelihood: high.
-Severity: high.
-The spec says `/versions` is "merged" and private gems "take precedence", but does not define whether a private/public name collision replaces the entire public name entry, replaces matching versions only, or appends a duplicate line and relies on Bundler parser behavior.
-This is also a dependency-confusion risk: if a private gem name exists on RubyGems.org and public versions are still visible, Bundler may resolve a public version.
-The local `compact_index` 0.15-compatible API also expects `CompactIndex.versions(versions_file, gems = nil, args = {})`, where `versions_file` is a `CompactIndex::VersionsFile`, not a raw upstream response body.
-The spec partially addresses the issue by naming `compact_index`, but it needs an explicit algorithm for `/names`, `/versions`, collision precedence, ordering, and checksum generation.
-
-### 2. Bundler's conditional request contract can fail silently or noisily
-
-Likelihood: medium-high.
-Severity: high.
-Bundler fetches `names`, `versions`, and `info/*` through the same updater path and uses `Range`, `If-None-Match`, `ETag`, and `Repr-Digest`/`Digest` to update local cache files.
-FR-1.3 covers only `/versions` and `/info/:gemname`, leaving `/names` weaker even though RubyGems.org serves `/names` with the same cache headers.
-For merged bodies, upstream `ETag` and digest headers are invalid and must be recomputed from the final response body.
-The spec does not say what to do with malformed ranges, suffix ranges, range starts beyond EOF, weak ETags, quoted ETags, or `If-None-Match` against a stale upstream cache.
-
-### 3. Offline cache behavior conflates outage, missing gems, and stale data
-
-Likelihood: high.
-Severity: medium-high.
-FR-3.2 says "non-2xx" means unreachable, but an upstream 404 for `/info/nonexistent-gem` is a valid upstream answer, not an outage.
-FR-3.4 then asks for a 404 body saying `"Upstream unavailable and no local cache"`, which is wrong when RubyGems.org is reachable and the gem simply does not exist.
-The spec also does not define whether 404s are cached, whether TTL refresh uses wall-clock only or conditional GETs, whether a 304 resets the TTL, or how corrupt/partial cache files are detected and discarded.
-Cache writes need to be atomic because Puma can serve concurrent Bundler requests.
-
-### 4. Upload and gem metadata validation are too loose
-
-Likelihood: medium.
-Severity: high.
-`POST /upload` accepts attacker-controlled multipart data from localhost, and "valid gem" is not defined.
-The server should derive name, version, platform, dependencies, required Ruby/RubyGems versions, and checksum from the embedded gemspec in the `.gem`, not from the uploaded filename.
-The spec does not require `mkdir_p gems_path/gems`, atomic temp-file writes, duplicate handling by parsed gem identity, filename/spec mismatch rejection, upload size limits, malformed multipart handling, or cleanup after failed validation.
-It also says `GemUploader` expects only 201 and 409, but the current code treats 200, 201, 302, and 409 as successful upload outcomes.
-
-### 5. The security checklist is incorrectly marked N/A
-
-Likelihood: high.
-Severity: medium.
-Binding to `127.0.0.1` reduces exposure but does not eliminate security requirements.
-The app accepts URL path input, multipart file input, and emits local gem names and versions.
-The spec needs validation for `/info/:gemname` and `/gems/:filename.gem` before filesystem access or upstream URL construction, including path traversal, percent-encoding, absolute paths, control characters, query strings, and overlong names.
-Unauthenticated local upload is explicitly out of scope, but the spec should still state the accepted local-only threat model and require defensive input validation.
-
-### 6. Performance impact is larger than the checklist suggests
-
-Likelihood: high.
-Severity: medium.
-RubyGems.org `/versions` is currently about 23 MB over the wire, and `/names` is about 2.7 MB.
-Regenerating a merged body, digest, and ETag for every request will allocate large strings and add latency on a 16 GB workstation.
-The spec calls this an open question, but implementation needs a concrete caching strategy for final merged response bodies, invalidation on upload, and upstream refresh cadence.
-Gem binary proxying should stream to disk/client or use bounded buffering rather than reading large `.gem` files fully into memory.
-
-## Complexity Hotspots
-
-### Compact index generation and collision rules
-
-This is the core of the feature.
-The spec needs to say how private gems become `CompactIndex::Gem` and `CompactIndex::GemVersion` objects, how `info_checksum` is calculated, and how public/private name collisions are represented.
-The named API fields are slightly off: the local 0.15-compatible `CompactIndex::GemVersion` struct uses `number`, `platform`, `checksum`, `info_checksum`, `dependencies`, `ruby_version`, and `rubygems_version`, not a `version` field.
-
-### HTTP proxy/cache implementation
-
-The proxy has to combine upstream conditional GETs, local TTLs, offline fallback, final-body digest generation, and Bundler's range update behavior.
-This needs a small but explicit cache model: file paths, sidecar metadata, atomic write strategy, status-code handling, and stale-cache rules.
-
-### Upload path and metadata extraction
-
-The server must parse Rack multipart input, validate a gem package, extract metadata, write atomically, and refresh in-memory index state without racing concurrent reads.
-The spec gives the happy path but not the failure and concurrency behavior.
-
-### Test harness
-
-The spec relies on "bundle install works" as a verification target, but a lot of failures only show up through exact headers and cache state.
-Implementation will need unit tests for route behavior and cache transitions, plus at least one integration test that runs Bundler against the local server with both private and public gems.
-
-## Completeness Checklist Audit
-
-| Item | Status | Notes |
-| ---- | ------ | ----- |
-| Scope & acceptance criteria | WARN | Each FR has a verify line, but several acceptance criteria are too broad to implement deterministically, especially "merged", "take precedence", "valid gem", and "offline". |
-| Testing strategy | WARN | Existing tests are identified, but missing tests for upload success, protocol headers, range edge cases, upstream 404 vs outage, corrupt cache files, path validation, and a real Bundler compact-index install. |
-| Existing patterns compared | WARN | The spec references core classes, but misses current `GemUploader#list_gems`, CLI/user-facing Geminabox strings, README/AGENTS updates, `gemkeeper.yml.example`, and the fact that the tracked project doc is `AGENTS.md`, not `CLAUDE.md`. |
-| Dependencies justified | WARN | `compact_index ~> 0.15` is a reasonable choice, but the repo already depends directly on `rubygems-generate_index`, which vendors a 0.15-compatible `compact_index`; Gemfile/Gemfile.lock updates and load-order expectations need to be explicit. |
-| Architecture & interfaces | WARN | The Rack entry point and storage layout are named, but route validation, cache object boundaries, response header helpers, concurrency strategy, and generated `config.ru` require path are not fully specified. |
-| Error handling & failure modes | FAIL | Upstream 404s, malformed ranges, invalid multipart bodies, invalid gem packages, partial downloads, corrupt cache files, filesystem write failures, and cache races are not adequately covered. |
-| Security review | FAIL | Marking security N/A is not adequate because the server accepts path parameters and file uploads and proxies requests based on user-controlled values. |
-| Performance impact | FAIL | The checklist honestly leaves this open, but `/versions` size and per-request merge/digest cost are large enough that the spec needs a concrete design before implementation. |
-| Rollout & migration | WARN | Data migration is probably unnecessary, but the "drop-in" claim omits user-facing renames, docs updates, Gemfile.lock, Homebrew release steps, and whether compatibility endpoints like `/api/v1/gems.json` remain. |
-| Assumptions & risks | WARN | The spec names the strict Bundler cache risk, but understates compact-index API details, public/private name collision behavior, and the incorrect `CLAUDE.md` integration point. |
-
-## Verdict
-
-NEEDS WORK.
-The goal and high-level architecture are solid, but implementation would force too many protocol, cache, security, and migration decisions in code.
-Those decisions affect correctness under Bundler, so they should be settled in the spec first.
-
-## Suggested Next Steps
-
-1. Define the exact `/names` and `/versions` merge algorithm, including private/public name collision semantics and dependency-confusion behavior.
-2. Specify how `ETag`, `Repr-Digest`, `Digest`, `Accept-Ranges`, 206, 304, and invalid range responses are generated for all compact index endpoints, including `/names`.
-3. Define the proxy cache layout and rules for TTL, conditional upstream refresh, upstream 404 vs outage, corrupt cache recovery, atomic writes, and stale fallback.
-4. Add explicit validation requirements for gem names, gem filenames, upload files, parsed gemspec identity, and filesystem path construction.
-5. Correct codebase assumptions: use `AGENTS.md` instead of `CLAUDE.md`, decide whether `/api/v1/gems.json` is still supported for `GemUploader#list_gems`, and include README/CLI/example config wording if Geminabox is truly replaced.
-6. Expand tests to cover compact-index route units, upload success/failure, offline cache transitions, malicious paths, and a Bundler integration install with one private gem and one public gem.

data/specs/20260529-091429-replace-geminabox-compact-proxy/critique-v-1-copilot.md

@@ -1,261 +0,0 @@
-# Critique: Replace Geminabox with Compact Index Proxy
-
-Reviewed by: GitHub Copilot (claude-sonnet-4.6)
-Date: 2026-05-29
-
-## Summary
-
-The spec is well-scoped and the integration points are clearly identified.
-The constraints table and out-of-scope list are unusually precise — useful.
-However, several correctness traps exist that would produce a server that passes basic smoke tests but fails under Bundler's actual caching behaviour.
-The most serious issues are the `/versions` byte-stability problem (correctness), the missing thread-safety requirement (reliability), and the unspecified `/names` scope (ambiguity with large performance consequences).
-The testing section is thin for the volume of new logic being introduced.
-
----
-
-## 1. Critical: Correctness Blockers
-
-### 1.1 `/versions` byte-stability is unaddressed, and merging breaks Bundler's range fetching
-
-FR-1.3 requires the server to support `Range: bytes=N-` to serve partial `/versions` responses.
-This is how Bundler efficiently updates its local copy: it records the file size it last fetched, then asks for only the bytes after that offset.
-
-The spec's merge strategy (FR-3.1: "private gem entries take precedence when a name appears in both") sorts or interleaves private gems into the rubygems.org `/versions` body.
-Any time a new private gem is added, the byte offsets of every subsequent line in the merged file shift.
-Bundler's cached offset is now wrong: the range request returns garbled data, and Bundler either fails or silently resolves wrong versions.
-
-The spec does not define a stable layout for the merged `/versions` output.
-Options include appending private gems after the public block, or rebuilding the rubygems.org block verbatim and appending private entries — but the spec is silent.
-Without a stable layout rule, this is a correctness defect, not just a performance issue.
-
-### 1.2 `info_checksum` has a circular dependency
-
-FR-2.2 requires `CompactIndex::GemVersion` to carry an `info_checksum` field.
-That checksum is the SHA256 of the `/info/:gemname` response body.
-To populate it in the `/versions` entry, the server must generate the `/info` body first, hash it, and embed the hash in `/versions`.
-
-The spec never describes this ordering, nor does it mention that the `info_checksum` must be recomputed whenever a new version of a gem is uploaded (because the `/info` body changes).
-An implementer who builds the versions index first and the info body second will produce invalid checksums that cause Bundler to re-fetch unconditionally.
-
-### 1.3 `/names` scope is undefined and carries large performance risk
-
-FR-1.1 says `/names` returns "all gem names (local and proxied)."
-The rubygems.org `/names` file currently contains ~175,000 gem names (roughly 2 MB uncompressed).
-"Proxied" in this context almost certainly means the full public gem namespace.
-
-The spec never says whether the server fetches, caches, and merges the rubygems.org `/names` file (like it does for `/versions`), or whether `/names` is scoped only to gems that have been locally requested or cached.
-These produce completely different behaviour:
-- Full public namespace: bundle install resolves public gems by name — correct, but the endpoint becomes expensive.
-- Local-only: bundle install fails on any public gem not already in the info cache.
-
-The performance checklist item (unchecked) notes only the `/versions` merge cost; it does not mention `/names`.
-This is a missing requirement.
-
----
-
-## 2. Ambiguous Requirements
-
-### 2.1 "Valid gem" definition in FR-1.2
-
-FR-1.2 returns 422 "if the file is not a valid gem" but does not define valid.
-Three plausible interpretations:
-
-1. File extension is `.gem`
-2. File is a parseable tar archive containing `metadata.gz` and `data.tar.gz`
-3. The gemspec within `metadata.gz` can be loaded without error
-
-These have substantially different implementation and security implications.
-Option 1 is trivially bypassable.
-Option 3 can raise arbitrary Ruby exceptions if the gemspec calls `require`.
-The spec should specify what validation is expected — likely option 2 at minimum.
-
-### 2.2 `/versions` cache stores raw upstream or merged output?
-
-FR-3.2 says cache the `/versions` response.
-It is ambiguous whether the cache stores:
-
-- The raw rubygems.org response (requiring re-merge with private gems on every request), or
-- The merged result (requiring cache invalidation on every gem upload)
-
-Both are valid designs; they have different invalidation logic.
-The spec does not specify which, leaving the implementer to decide and potentially choosing the one that breaks ETag/Range behaviour.
-
-### 2.3 ETag algorithm: "MD5 or SHA256"
-
-FR-1.3 says use "MD5 or SHA256" for the ETag.
-Giving two options creates inconsistency risk — different code paths might use different algorithms, making ETags non-comparable across restarts.
-Pick one.
-SHA256 is the better choice (used for `Repr-Digest` too; re-using the same hash avoids a second pass).
-
-### 2.4 `handle_response` in `GemUploader` accepts 200 and 302, not just 201
-
-FR-4.2 states that the new server must return "the same status codes (201, 409) that `GemUploader` expects."
-This is inaccurate.
-`GemUploader#handle_response` maps `200`, `201`, and `302` as success.
-The spec's description of `GemUploader`'s contract is wrong.
-While the new server returning 201 will still work (201 is handled), a future implementer auditing the spec against the code will find the discrepancy and may add unnecessary 302 handling or question the spec's accuracy.
-
----
-
-## 3. Codebase Assumption Gaps
-
-### 3.1 `GemUploader#list_gems` calls `/api/v1/gems.json`
-
-The spec says "no changes to `GemUploader`" and it is correct that `list_gems` is never called from any production code path (the `list` CLI reads the filesystem directly via `Dir.glob`, per FR-4.3).
-But `list_gems` is a public method that calls `GET /api/v1/gems.json`, a Geminabox-specific endpoint.
-After this migration, calling `list_gems` will return a 404.
-
-The spec should either note that `list_gems` becomes a dead method (and optionally raise `NotImplementedError`), or explicitly call out this known breakage so the implementer doesn't silently leave a broken public method.
-
-### 3.2 `rubygems-generate_index` dependency is not addressed
-
-The gemspec currently declares `rubygems-generate_index ~> 1.0`.
-This gem exists to support Geminabox's legacy Marshal index generation (`specs.4.8.gz`, `Marshal.4.8.gz`).
-The spec removes Geminabox and explicitly excludes legacy index formats from scope, but says only to swap `geminabox` for `compact_index` in the gemspec.
-`rubygems-generate_index` is likely now unused dead weight.
-Whether to remove it is a judgment call, but the spec should at least acknowledge it.
-
-### 3.3 Integration test has more Geminabox assertions than lines 80–81
-
-The Integration Points table says to update lines 80–81 of `test_server_lifecycle_integration.rb`.
-In the current file, there are two assertions that reference Geminabox:
-
-```ruby
-assert_match(/Geminabox\.data/, content)               # line 80
-assert_match(/Geminabox\.rubygems_proxy\s*=\s*true/, content)  # line 81
-```
-
-But the test method is named `test_server_generates_config_ru`, and the test class also has `test_server_status_while_running` which checks `status[:url]` equals `@config.geminabox_url`.
-The `geminabox_url` method name on `Configuration` is referenced both here and in `RackupProcess#wait_for_server`.
-The spec is silent on this naming — the constraint says "no changes to `configuration.rb`", so the stale method name remains.
-The integration test assertion on `geminabox_url` will still pass (the URL format doesn't change), but it should be called out in the spec as an accepted naming inconsistency rather than left for the implementer to discover.
-
-### 3.4 `compact_index` gem API is assumed but not verified
-
-The spec builds on `CompactIndex::GemVersion`, `CompactIndex::Dependency`, `CompactIndex.names()`, and `CompactIndex.info()`.
-The spec's own checklist flags this: "key assumption: `compact_index` 0.15.x API is stable."
-The `compact_index` gem is primarily an internal RubyGems.org dependency.
-Its README is sparse and its public API is not documented for external consumers.
-Before implementation begins, the actual gem should be inspected to confirm the class names and method signatures match what the spec assumes.
-This is flagged here not as a spec defect, but as a pre-implementation step that is conspicuously absent from the spec.
-
----
-
-## 4. Error Handling and Edge Case Gaps
-
-### 4.1 Thread safety for the in-memory gem index
-
-FR-2.1 says the server rescans `gems_path/gems/*.gem` after each successful upload.
-Puma (the configured server) uses a thread pool by default.
-A concurrent GET `/info/:gemname` while an upload is updating the in-memory index will produce a data race.
-
-The spec does not require synchronization (a `Mutex` around index reads and writes, or a copy-on-write swap).
-In practice, Ruby's GVL limits the impact, but it is not zero — especially during index rebuild where multiple instance variables are updated in sequence.
-The spec should specify that the gem index is updated atomically (e.g., replace the entire index object with a new one via a single assignment).
-
-### 4.2 Range request with explicit end byte is unspecified
-
-FR-1.3 says handle `Range: bytes=N-` (open-ended).
-The HTTP spec also allows `Range: bytes=N-M` (explicit end) and multi-range requests (`Range: bytes=0-99, 200-299`).
-Bundler currently only sends open-ended ranges, but the spec should be explicit that multi-range and bounded-range requests return 416 (`Range Not Satisfiable`) or fall back to the full response, rather than leaving this undefined.
-
-### 4.3 Behaviour when `gems_path/gems/` contains a corrupt `.gem` file
-
-FR-2.1 scans all `.gem` files on startup and on upload.
-If a file is corrupt (truncated download, disk error), extracting gemspec metadata will raise an exception.
-The spec does not say whether the server should skip corrupt files with a warning or abort startup.
-If startup is aborted, a single bad file makes the server unlaunchable.
-
-### 4.4 Concurrent upload of the same gem
-
-FR-1.2 returns 409 if the file already exists.
-If two `gemkeeper sync` processes run simultaneously and both upload the same gem at the same time, a TOCTOU race exists between the existence check and the file write.
-The spec should specify last-write-wins, or require a file lock.
-
-### 4.5 System gem cache traversal under `Gem.path`
-
-FR-3.3 checks `Gem.path.map { |p| File.join(p, "cache", filename) }`.
-`Gem.path` includes user-defined paths from `GEM_PATH` environment variable.
-A developer with a misconfigured `GEM_PATH` pointing to a path they don't own could cause unexpected file-serving behaviour.
-This is a minor concern given localhost-only binding, but the spec should note that only paths where the file is readable are considered.
-
----
-
-## 5. Security Concerns
-
-### 5.1 Path traversal in `/gems/:filename.gem`
-
-FR-3.3 constructs a filesystem path from the URL parameter `filename`.
-A request to `/gems/../../../../etc/passwd` (URL-decoded by Rack before routing) would traverse outside `gems_path`.
-Even on localhost, any process on the same machine can make this request.
-
-The spec's security checklist dismisses auth and input validation as out of scope because the server "binds to 127.0.0.1 only."
-That reasoning does not cover path traversal — localhost binding doesn't prevent local processes from exploiting it.
-The spec should require that `filename` be validated to contain only safe characters (`[a-zA-Z0-9._-]`) or that the resolved path is asserted to be under `gems_path` before serving.
-
-### 5.2 SSRF via cached rubygems.org requests
-
-The server makes outbound requests to `https://rubygems.org/info/:gemname` where `gemname` comes from the incoming request URL.
-A local process could request `/info/../../../../etc/passwd` — the gemname would be used to construct the upstream URL `https://rubygems.org/info/../../../../etc/passwd`.
-While rubygems.org would return a 404, the spec should require URL-encoding or validation of `:gemname` before constructing the upstream URL.
-
----
-
-## 6. Performance Concerns
-
-### 6.1 In-memory merge of `/versions` on each request (already flagged in checklist)
-
-The spec acknowledges this is an open question.
-A concrete recommendation: cache the fully merged `/versions` body in memory and invalidate it only when a gem is uploaded (cheap) or when the upstream ETag changes (already covered by FR-3.2).
-The spec should promote this from "open question" to a requirement: "merged `/versions` response is memoized in memory; invalidated on upload or upstream ETag change."
-
-### 6.2 Full gem metadata re-scan on every upload
-
-FR-2.1 says "scans `gems_path/gems/*.gem`" after each upload.
-For a large private gem store, this O(n) re-scan on every upload is unnecessary.
-An incremental approach (add the newly uploaded gem to the in-memory index directly) would be more efficient.
-This is a recommendation rather than a blocker, but if left as a full re-scan, the spec should cap the acceptable gem count or note the known performance characteristic.
-
----
-
-## 7. Testing Strategy Gaps
-
-### 7.1 No unit tests specified for `CompactIndexServer`
-
-The spec introduces a new 200+ line Rack application implementing 8 endpoints, proxy logic, cache management, and ETag/Range support.
-The testing section mentions only one integration test update (lines 80–81) and four "Verify" lines that describe manual/integration scenarios.
-
-There are no unit tests specified for:
-- Correct `ETag` and `Repr-Digest` header generation
-- 304 response when ETag matches
-- 206 response for range requests
-- The merge logic for `/versions`
-- Corrupt gem handling (FR-4.3 gap above)
-- Offline fallback path (FR-3.4)
-
-Given the project's existing unit test pattern (one `test_*.rb` per class), `test/gemkeeper/test_compact_index_server.rb` should be called out explicitly, even if only to anchor a few key behaviours.
-
-### 7.2 FR-4.2 verify claim is overconfident
-
-FR-4.2 says "the existing `test/gemkeeper/test_gem_uploader.rb` passes without modification."
-The existing tests only test connection failure paths (no live server involved).
-They do not test a successful upload against a real or mock server.
-The claim that the tests "pass without modification" is true today, but it does not verify that the upload flow actually works against the new server.
-A new integration test covering the upload round-trip should be called out here.
-
----
-
-## 8. Spec Completeness Checklist Assessment
-
-| Item | Assessment |
-| ---- | ---------- |
-| Scope & acceptance criteria | ✅ Clear. Out of Scope list is precise and useful. |
-| Testing strategy | ⚠️ Thin. No unit tests for the new Rack app; FR-4.2 verify is misleading. |
-| Existing patterns | ✅ Correctly identifies `GemUploader`, `Dir.glob` list pattern, `ServerReadinessProbe`. |
-| Dependencies | ⚠️ `rubygems-generate_index` not addressed; `faraday`/`faraday-multipart` not mentioned as retained. |
-| Architecture & interfaces | ✅ Rack app interface, config.ru, storage layout clearly specified. |
-| Error handling & failure modes | ⚠️ Corrupt gem files, TOCTOU on upload, thread safety, and range-end handling are missing. |
-| Security review | ❌ Path traversal in filename parameter and SSRF in gemname-to-upstream-URL construction are unaddressed. The localhost-only justification does not cover these. |
-| Performance impact | ⚠️ Acknowledged as open question but not resolved. `/names` scope is a larger risk than the spec recognises. |
-| Rollout & migration | ✅ Drop-in; no data migration; Homebrew rebuild noted. |
-| Assumptions & risks | ⚠️ `compact_index` API stability flagged but no pre-implementation verification step prescribed. |