# Symbol Bundle Guide

This guide explains how to package, validate, and distribute symbol bundles that comply with `SYMBOL_MANIFEST/v1`.

## 1. Packaging steps
1. Gather debug artifacts (ELF `.debug`, PDB, dSYM) for the target release.
2. Compute `sha256` for each file and record size/arch/format.
3. Build `manifest.json` as per `SYMBOL_MANIFEST_v1.md`; sort entries by `build_id`, then `file`.
4. Write `manifest.json.sha256` with the hex digest of `manifest.json`.
5. Create a deterministic tarball:
   - POSIX ustar
   - Sorted file order
   - `mtime=0`, `uid=gid=0`, `uname=guname=root`
   - Compression: gzip `-n` to avoid timestamps
6. Optional: wrap as OCI artifact with media type `application/vnd.stella.symbols.manifest.v1+json`.

## 2. Validation checklist
- [ ] `manifest.json` hashes to `manifest.json.sha256`.
- [ ] Each file hash matches manifest entry.
- [ ] Build-id path structure is correct (ELF `.build-id/aa/<rest>.debug`).
- [ ] Tenant in manifest matches upload tenant.
- [ ] Tarball ordering is lexicographic and mtimes are zeroed.

## 3. Ingestion (API)
- POST the tar/OCI blob to `/api/v1/symbols/ingest` with header `X-Stella-Tenant`.
- Server recomputes digests; rejects mismatches or tenant mismatch.
- Optional DSSE attestation digest recorded in manifest for downstream verification.

## 4. Reachability integration
- Scanner attaches `build_id` and source image digest to reachability edges; Graph API can fetch symbol manifests to render function names in overlays.
- When symbols are missing, UI shows “symbol lookup unavailable” badge; import the matching manifest to enable function-level overlays.

## 5. Offline kits
- Place `symbols/` directory (manifest + files) at the kit root; include tarball and manifest digest.
- `debug-manifest.json` in Offline Kit should link to symbol manifest for cross-reference.

## 6. Tenant controls & audit
- Symbol server enforces tenant; exports are tagged with tenant in manifest and tar annotations.
- Emit Timeline events on ingest with bundle digest and tenant; attach DSSE attestation if present.