more testing

instrumentation.md

@@ -150,9 +150,59 @@ For example, if the deployed JavaScript is available at
 `source=/assets/main-abc123.js`. The source-map filename on the build machine
 does not need to match the URL, but the `source` field must.
 
-Maps are parsed and retained server-side. Issue responses include a resolved
-stack when `service.release` and the generated bundle path match. Original
-source files and map contents are never returned by the API.
+Maps are parsed, written to `OTEL_SOURCEMAP_DIR`, and reloaded on receiver
+start. Issue responses include a resolved stack when `service.release` and the
+generated bundle path match. Uploaded maps are never returned, but when a map
+embeds `sourcesContent` the RUM "JS errors" view shows a few lines of original
+source around each mapped frame to signed-in users.
+
+### Requirements checklist
+
+A stack only resolves when every one of these holds. When it does not, check
+them in this order:
+
+1. **The build emits maps, with sources embedded.** Enable source maps in the
+   bundler (Vite `build.sourcemap: true`, webpack `devtool: "source-map"`).
+   Keep `sourcesContent` (the default) or the code view has nothing to show.
+2. **The browser reports a release.** Pass the release to `OtelRUM.init({ release })`
+   (or `data-release` on the script tag), injected at build time. An event
+   with no release, or `dev`, can never match an upload.
+3. **The uploaded release is byte-for-byte the same string.** Use one value for
+   both the bundle build and the upload (a git short SHA works).
+4. **`source` matches the path in the browser stack.** Everything before
+   `/assets/` and any `?query` is ignored, so `source=/assets/main-abc123.js`
+   matches `https://app.example.com/assets/main-abc123.js`. Content-hashed
+   names must match exactly, and chunks each need their own upload.
+5. **The map belongs to the deployed bundle.** Upload the maps from the very
+   build that produced the deployed files. A second local rebuild can differ
+   (dependencies, Node version) and silently mismatch. In Docker, copy the maps
+   out of the build stage (`docker build --target <stage>`, then `docker cp`)
+   instead of rebuilding. `build.sh` does this.
+6. **Every chunk is uploaded.** Loop over all `*.js.map` files and fail the
+   deploy when none are found, since an empty loop otherwise succeeds silently.
+7. **The receiver keeps its maps.** `OTEL_SOURCEMAP_DIR` must be on persistent
+   storage (a PVC in Kubernetes, not `emptyDir`). Maps written to an ephemeral
+   directory vanish on restart.
+8. **Maps are not published with the site.** Delete `*.map` from the served
+   image unless public maps are intended (see below).
+
+### Verifying a deploy
+
+List what the receiver has loaded (requires a signed-in session or token):
+
+```sh
+curl -H "Authorization: Bearer $TOKEN" https://otel.example.com/api/sourcemaps
+# [{"release":"2026.09.18-a1b2c3","source":"/assets/main-abc123.js"}, ...]
+```
+
+Then trigger a real uncaught error from application code, for example a
+button that runs `setTimeout(() => { throw new Error("source-map check") })`
+(this repository's RUM "JS errors" view has a *Generate test error* button),
+and confirm the card shows **Source-mapped** with the original file and line.
+
+Frame status in the stack explorer explains a miss: `no-release` (event has no
+release), `no-map` (nothing uploaded for that release and file), or `unmapped`
+(a map exists but has no mapping for that position).
 
 The Docker build removes `.map` files from production images by default. For
 development or staging, public maps can be enabled for Chrome DevTools:
@@ -170,6 +220,7 @@ production unless that is intentional.
 2. Trigger a controlled backend error span or ERROR log.
 3. Confirm both appear under Issues as separate frontend/backend issues.
 4. Confirm the issue sample contains the expected release.
-5. Confirm a mapped frontend stack shows original file and line information.
+5. Confirm a mapped frontend stack shows original file and line information
+   (see *Requirements checklist* under Source maps if it does not).
 6. Confirm trace IDs connect frontend requests to backend traces where headers
    were propagated.