git.stella-ops.org/docs/modules/symbols/marketplace-architecture.md

Symbol Marketplace Architecture

Module: src/Symbols/StellaOps.Symbols.Marketplace/ Server: src/Symbols/StellaOps.Symbols.Server/ Sprint: SPRINT_20260220_001, SPRINT_20260220_002 Status: Implemented

---

Overview

The Symbol Marketplace extends the existing Symbols module with a registry of symbol/debug pack sources, a browsable catalog, and a four-dimension trust scoring model. It provides the infrastructure needed to discover, evaluate, and install debug symbol packs from vendor, distro, community, and partner providers.

This directly strengthens the "Symbolized call-stack proofs" moat by ensuring Stella Ops can source verified debug symbols for any artifact in the reachability graph, enabling DSSE-signed call-stack resolution across platforms.

Domain Primitives

SymbolPackSource

Registry entry for a symbol provider. Each source has:

• Key/Name: Human-readable identifier (e.g., microsoft-symbols, ubuntu-debuginfod).
• SourceType: vendor | distro | community | partner.
• Priority: Integer ordering for resolution precedence.
• FreshnessSLA: Target sync interval in seconds (default: 6 hours).
• WarningRatio: Threshold (0-1) for warning state transition.

SymbolPackCatalogEntry

Represents an installable symbol/debug pack:

• PackId: PURL-formatted package identifier.
• Platform: Target platform (e.g., linux/amd64, any).
• Components: Array of debug components included.
• DsseDigest: DSSE signature digest for integrity verification.
• Installed: Whether the pack is active for the tenant.

SymbolSourceFreshnessRecord

Materialized freshness projection following the advisory source pattern:

• Tracks sync cadence, error rates, and SLA compliance.
• Freshness state machine: healthy -> warning -> stale -> unavailable.
• Includes signature coverage metrics (signed/unsigned/failure counts).

SymbolSourceTrustScore

Four-dimension trust scoring:

Dimension	Weight	Description
Freshness	0.30	How up-to-date the source is relative to SLA
Signature	0.30	DSSE signature coverage (signed packs / total packs)
Coverage	0.20	Artifact coverage derived from sync success rate
SLA Compliance	0.20	Whether source stays within freshness window

Overall score = weighted average, clamped to [0, 1].

Database Schema

symbol_pack_sources

Column	Type	Description
id	uuid PK	Source identifier
key	text UNIQUE	Machine-readable key
name	text	Display name
source_type	text	vendor/distro/community/partner
url	text NULL	Source endpoint URL
priority	int	Resolution priority
enabled	boolean	Active flag
freshness_sla_seconds	int	Target sync interval
warning_ratio	decimal	Warning threshold
created_at	timestamptz	Creation timestamp
updated_at	timestamptz NULL	Last update

symbol_pack_catalog

Column	Type	Description
id	uuid PK	Entry identifier
source_id	uuid FK	References symbol_pack_sources
pack_id	text	PURL identifier
platform	text	Target platform
components	text[]	Component list
dsse_digest	text	Signature digest
version	text	Pack version
size_bytes	bigint	Pack size
published_at	timestamptz	Publish date

API Surface

Symbol Sources (/api/v1/symbols/sources)

Method	Path	Description
GET	/	List sources with freshness projections
GET	/summary	Summary cards (healthy/stale/unavailable counts + avg trust)
GET	/{id}	Source detail with trust score
GET	/{id}/freshness	Freshness detail
POST	/	Create source
PUT	/{id}	Update source
DELETE	/{id}	Disable source

Marketplace Catalog (/api/v1/symbols/marketplace)

Method	Path	Description
GET	/	List catalog entries
GET	/search	Search by PURL/platform
GET	/{entryId}	Catalog entry detail
POST	/{entryId}/install	Install pack for tenant
POST	/{entryId}/uninstall	Uninstall pack
GET	/installed	List installed packs
POST	/sync	Trigger sync from sources

All responses include dataAsOf timestamp for staleness detection.

Integration Points

IntegrationType.SymbolSource (= 7)

New integration type added to StellaOps.Integrations.Core:

• MicrosoftSymbols = 700
• UbuntuDebuginfod = 701
• FedoraDebuginfod = 702
• DebianDebuginfod = 703
• PartnerSymbols = 704

UI Integration

• Symbol Sources list: /security-risk/symbol-sources — freshness summary + source table.
• Symbol Source detail: /security-risk/symbol-sources/:sourceId — trust breakdown, sync timeline.
• Symbol Marketplace: /security-risk/symbol-marketplace — catalog browse/search with install/uninstall.
• Sidebar entries under "Security and Risk" section.

Existing Module Touchpoints

• Scanner: Symbol resolution uses marketplace-installed packs for call-stack symbolication.
• ReachGraph: Coverage dimension reflects artifact matching from reachability analysis.
• Attestor: DSSE signatures on packs are verified through the existing proof chain infrastructure.
• Policy: Trust scores feed into policy gate decisions for symbol-dependent verdicts.