fix(telemetry): tracer recognizes file:* spans for oddkit_get fast path

[klappy]

Summary

Follow-up to #138. The streaming-race fix corrected the timing bug, but oddkit_get for klappy:// URIs still records cache_tier="none" because of a separate defect: the tracer's _indexSource setter only recognized "index" and "index-build" labels.

The remaining gap

runGet for klappy:// URIs takes a fast path that skips getIndex entirely — the URI-to-path mapping is computable without the index. It calls getFile directly. The fetcher emits file:${path} spans, but the setter's exact-match check ignored them. Result: _indexSource stayed null, blob9 = "none".

This is the dominant get path: klappy:// URIs make up ~95% of oddkit_get calls. So even after #138, ~95% of get calls had cache_tier="none" — defeating the dashboard's purpose for that tool.

Fix

Extend the setter to also recognize file:* labels alongside index / index-build. First-wins guard preserved:

Action	Spans (in order)	Result
runSearch	index → file:* (per hit)	index tier wins (primary work)
runGet klappy://	file:* only	file tier wins (primary work)
runGet kb:///odd://	index → file:*	index tier wins (acceptable approximation, ~5% of gets)
runVersion / runTime	none with valid source	"none" (correct — no fetch)

file-r2:* (R2 miss with source="miss") is excluded by an explicit source !== "miss" guard. "miss" is not a tier and must never appear in blob9.

Naming honesty

The internal field name (_indexSource) and getter name (indexSource) stay unchanged. The public envelope key index_source in tracer.toJSON() is part of the response contract — renaming would be a breaking change for any consumer reading the trace. The doc-comment on the getter is updated to reflect the broader semantic: "primary cache tier" rather than strictly the navigability index.

Regression tests added (4)

1. file:* span with each tier (memory/r2/build) populates indexSource
2. Index wins when fired before file spans (search pattern preserved)
3. file-r2:* miss spans correctly excluded
4. Original index-only behavior preserved (no regression on existing semantics)

Test count: 18 → 22 passing.

What this completes

After #138 + this PR, every tool with a real data fetch records its actual tier:

• oddkit_search, oddkit_orient, oddkit_catalog, oddkit_challenge, oddkit_encode, oddkit_preflight, oddkit_validate, oddkit_gate → index tier (the dominant fetch they all perform)
• oddkit_get (klappy://) → file tier (the actual document fetch)
• oddkit_get (kb://, odd://) → index tier (URI lookup is the index hit, ~5% of gets)
• oddkit_version, oddkit_time → "none" (correctly — no fetch)

cache_tier becomes a meaningful field for every tool in the dashboard.

---

Note

Low Risk
Low risk: changes are limited to how RequestTracer derives the single telemetry cache_tier value and adds tests to lock behavior; it doesn’t affect request handling beyond reporting.

Overview
Fixes telemetry cache_tier attribution for oddkit_get fast-path requests by letting RequestTracer treat file:* spans (in addition to index/index-build) as the primary tier, while keeping a first-wins rule and ignoring source="miss".

Adds integration tests covering file-only paths, index-before-file precedence, exclusion of file-r2:* miss spans, and a regression check for the original index-only behavior.

^{Reviewed by Cursor Bugbot for commit 904d804. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	oddkit	904d804	Commit Preview URL Branch Preview URL	Apr 26 2026, 02:57 AM