docs(edge): /api/stats states its own scope — per-isolate key availability (LAB-1618)

[27Bslash6]

Skyline slice of LAB-1618 (honest cache-layer reporting). Copy-only in edge/ per coordination with the LAB-1615 renderer rewrite.

• /api/stats payload gains a scope field stating its own semantics: per-isolate counters that reset on isolate recycle, and hit_rate = aggregate-key availability at this isolate — not an SDK L1 rate (the edge reads the backend directly; the publisher runs L1-disabled by design) and not the end-user rate (POP cache hits are served before the worker runs). Additive-only — existing field names untouched (verify.sh, dashboard, tests).
• Dashboard tile label: "Cache hit rate" → "Key availability (this isolate)".
• README API-table row matches.

Companion PRs: cachekit-io/saas#310 (analytics contract), docs (metric scopes).

Verification: npm test (26 passed) + tsc --noEmit clean.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 20 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 605f7731-19d7-4908-84e2-d7bdd80b313c

📥 Commits

Reviewing files that changed from the base of the PR and between f940dbc and b5b260e.

📒 Files selected for processing (3)

• edge/README.md
• edge/public/dashboard.js
• edge/test/dashboard.test.ts

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added scope information to statistics responses, clarifying that metrics are tracked per isolate and reset when an isolate is recycled.
  • Updated the statistics display to show “Key availability (this isolate)”.

• Documentation

  • Clarified aggregate-key availability semantics and distinguished these metrics from SDK L1 and end-user hit rates.
  • Documented that POP cache hits are excluded from reported statistics.

• Tests

  • Expanded coverage for scope information and metric definitions.

Walkthrough

The /api/stats response now reports isolate-scoped metric semantics. The dashboard label, README, and tests identify aggregate-key availability, counter resets, excluded cache layers, and zero-read behaviour.

Changes

Statistics scope

Layer / File(s)	Summary
Define and validate statistics scope edge/src/handler.ts, edge/public/index.html, edge/README.md, edge/test/handler.test.ts	The API adds a scope field. The dashboard and README describe per-isolate aggregate-key availability. Tests verify scope wording and hit_rate: null when no reads occur.

Possibly related PRs

• cachekit-io/bluesky-thinking#2: The PR directly modifies the handler, tests, README, and dashboard changes introduced there.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title uses conventional commit syntax and clearly describes the per-isolate /api/stats scope change.
Description check	✅ Passed	The description directly explains the /api/stats scope field, dashboard label, documentation updates, and verification results.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@edge/test/handler.test.ts`:
- Around line 187-198: Add assertions in the test case “scope names the reset
semantics and disclaims SDK-L1 / end-user readings” to verify body.scope
explicitly excludes the end-user rate and POP-cached readings, while preserving
the existing reset, aggregate-key availability, and SDK L1 assertions.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e684a4dd-8651-4977-9178-575eab1dcf4b

📥 Commits

Reviewing files that changed from the base of the PR and between 5379e98 and 278cf5e.

📒 Files selected for processing (4)

• edge/README.md
• edge/public/index.html
• edge/src/handler.ts
• edge/test/handler.test.ts

[kodus-27b]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[27Bslash6]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[27Bslash6]

Resolved conflict in edge/public/index.html (took main's extracted dashboard.js structure and ported this PR's LAB-1618 tile copy into edge/public/dashboard.js + its test assertion); auto-rebased onto main; CI will re-run.