git.stella-ops.org/docs/specs/symbols/SYMBOL_MANIFEST_v1.md

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:

{
  "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)