stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
69651212ec42ade25a9c7952b5655e9d4a5514c7
git.stella-ops.org/docs/specs/symbols/bundle-guide.md
StellaOps Bot d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-26 20:23:28 +02:00

2.0 KiB
Raw Blame History

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.