git.stella-ops.org/docs-archived/modules/symbols/specs/bundle-guide.md

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.

7. Offline verification procedure (2026-02-26 batch)

1. Load bundle archive and manifest.json.
2. Verify manifest hash and every object digest before cryptographic checks.
3. Verify DSSE envelope signature and payload binding.
4. Verify Rekor inclusion metadata when present (or classify as explicit offline/missing-proof state).
5. Verify Merkle inclusion proof nodes against expected root and reject mismatches deterministically.

Expected failure classes for automation:

• payload_too_large
• missing_subject
• invalid_media_type
• referrer_cycle_detected
• missing_symbol_bundle