# Repository performance and live updates

SmolForge optimizes repository browsing for fast perceived response without hiding durability or freshness.

## User-facing behavior

- Commit history fetches 30 commits at a time through opaque cursors. The UI uses **Load more** and does not calculate an exact total by default.
- File intent-prefetch is bounded and deduplicated. It is disabled when Save-Data is enabled or the connection reports 2G, limited to one concurrent request on 3G, and two on faster or unknown connections.
- In-app file edits immediately retain the local draft while the commit is in flight. The repository header shows **Confirming...**, then **Synced** only after the durable write response. Failures retain the draft and show **Not synced**.
- Open repository pages subscribe to branch ref updates. Web and Git/agent writes publish the same `ref.updated` event, followed by an authoritative content refresh. A private, no-store head check runs only as a recovery path when the socket is unavailable.
- Directory manifests are cached internally by exact tree SHA, including blob sizes. Reused subtrees therefore avoid repeated R2 reads even when they appear under different commits.
- Directory last-commit metadata uses a bounded foreground history scan, then a
  durable Workflow for any unresolved entries. The Workflow advances in
  retryable chunks and writes its latest cursor to D1, so every Cloudflare
  location observes the same progress and an interrupted scan resumes instead
  of restarting. Only complete results enter the data-center-local Cache API,
  keyed by cache format, internal repository ID, exact resolved head SHA, and
  normalized directory path. Access and ref resolution always happen before
  lookup, so a moved ref misses automatically and visibility or collaborator
  revocation takes effect immediately. Browser responses remain private and
  non-cacheable.
- Neutral parsed commit records are cached by exact commit SHA, so later history pages can reuse ancestry metadata without re-reading R2. Commit history pages and details add a disclosure-aware response cache. Pull-request diffs, commit ranges, and merge status are cached by the exact source/target SHA pair.
- Branch and tag snapshots are keyed by a transactionally maintained repository ref generation. Database triggers advance the generation for Git pushes, web commits, merges, branch changes, fork imports, and default-branch changes.
- Repository visibility changes close existing event sockets immediately. Unlisted and private repository synchronization responses are never shared-cacheable.

## Privacy-safe performance telemetry

The browser reports only numeric Web Vitals, a coarse route class, navigation type, and coarse connection class. It never reports repository coordinates, paths, URLs, source, user identity, or content. Do Not Track disables collection.

The API accepts a strict allowlist of fields and metrics, caps payloads at 2 KB, and rejects unknown fields. This prevents accidental expansion of the telemetry schema into user or repository data.

## Guardrails

The production web build enforces its existing entry-bundle budget. Performance changes should also preserve:

- bounded requests and queues;
- no exact-count scans in primary browsing flows;
- explicit pending, confirmed, offline, and recoverable failure states;
- no shared caching for access-controlled repository data;
- reconnect backoff and a visibility-aware recovery path.