# 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.