up

docs/specs/symbols/SYMBOL_MANIFEST_v1.md

@@ -0,0 +1,80 @@
+# 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)