# SYMBOL_MANIFEST v1

> **Imposed rule:** Symbol bundles must be content-addressed and tenant-scoped; every manifest entry must include the originating image digest and build-id to prevent cross-tenant leakage.

This document specifies the manifest format for distributing native debug symbols (ELF, PDB, dSYM) within StellaOps Offline Kits and symbol servers.

## 1. Use cases
- Offline debugging: GDB/LLDB/WinDBG pointing at local symbol server or file tree.
- Reachability analysis: map call stacks and function addresses to packages for scanner reachability overlays.
- Forensics: correlate runtime crash dumps to signed builds.

## 2. File layout

```
symbols/
  manifest.json          # SYMBOL_MANIFEST v1 (this spec)
  manifest.json.sha256   # sha256 of manifest.json
  /.build-id/aa/bbbbb.debug   # ELF split DWARF
  /.build-id/cc/ddddd.sym     # PE/PDB (optional)
  /mach-o/<uuid>.dSYM        # Apple dSYM bundle (optional)
```

## 3. Manifest schema (JSON)

Top-level fields:

```jsonc
{
  "schema": "SYMBOL_MANIFEST/v1",
  "generated_at": "2025-11-26T12:00:00Z",
  "generator": "stella symbol pack 1.0.0",
  "tenant": "acme",
  "entries": [
    {
      "image_digest": "sha256:...",          // source image
      "component": "openssl",                // optional package/name
      "build_id": "abcdef1234567890",        // GNU build-id or PE GUID
      "file": ".build-id/ab/cdef.debug",     // relative path inside bundle
      "format": "elf-debug" ,                // elf-debug | pdb | dsym
      "arch": "linux/amd64",                 // GOARCH-style
      "size": 123456,                          // bytes
      "sha256": "sha256:...",                // file digest
      "source": {
        "kind": "ci" | "vendor" | "runtime-capture",
        "pipeline": "https://ci.example/pipeline/123", // optional
        "attestation": "sha256:..."           // DSSE bundle digest (optional)
      }
    }
  ]
}
```

Constraints:
- `schema` must be exactly `SYMBOL_MANIFEST/v1`.
- Entries sorted by `build_id` then `file` to keep deterministic ordering.
- `tenant` required; manifests are not shareable across tenants.

## 4. Validation
- Verify `manifest.json.sha256` matches `manifest.json`.
- For each entry, hash the referenced file and compare to `sha256`.
- Ensure `build_id` path matches file location (for ELF: `/.build-id/<aa>/<rest>.debug`).
- When attestation is present, validate the DSSE bundle before serving symbols.

## 5. Transport
- OCI artifact (recommended): media type `application/vnd.stella.symbols.manifest.v1+json`; symbols packed as a tar layer with manifest at root.
- File archive: deterministic `tar.gz` with POSIX `ustar`, sorted entries, UTC mtimes set to `0`.
- Export Center mirrors symbol bundles alongside SBOM/attestation bundles for air-gapped installs.

## 6. Tenant controls
- Symbol server enforces tenant header `X-Stella-Tenant`; manifests without matching tenant are rejected.
- Offline bundles carry tenant in manifest; Console warns if loading mismatched tenant.

## 7. Versioning
- Future versions add optional fields; parsers must ignore unknown fields.
- Breaking changes will bump to `SYMBOL_MANIFEST/v2`.

## 8. References
- `docs/24_OFFLINE_KIT.md` (debug store expectations)
- `docs/benchmarks/signals/bench-determinism.md`
- `docs/modules/scanner/architecture.md` (reachability + symbol linkage)