Gaps fill up, fixes, ui restructuring

docs/modules/symbols/marketplace-architecture.md

@@ -0,0 +1,129 @@
+# 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.