Schema Mapping Reference

This document maps StellaOps data storage across its three backing stores — PostgreSQL, Valkey, and RustFS (S3-compatible object storage) — organized by the module that owns each schema, keyspace, or path prefix. It is written for operators and service authors who need to know which module owns which data, where it lives, and how it is keyed.

Altitude note. This is an ownership-and-shape map, not a DDL reference. Exact column lists, indexes, and Valkey TTLs live in each service’s embedded migrations and configuration and drift over time; the tables below capture the durable ownership and intent. The authoritative, forward-only migration files in src/ are the source of truth — see the database auto-migration requirement (§2.7). When this page and the migrations disagree, the migrations win.

Table of Contents

• 1. Storage Overview
• 2. PostgreSQL Schema Ownership
• 3. Valkey Keyspace Reference
• 4. RustFS (S3) Path Conventions
• 5. Module-to-Storage Mapping
• 6. Cross-References

1. Storage Overview

StellaOps uses three primary storage systems:

Storage Principles

1. Schema Isolation: Each module owns its PostgreSQL schema
2. Append-Only for Evidence: Advisory, VEX, and SBOM raw data is immutable (AOC)
3. Content-Addressable: Blob storage uses SHA256 digest prefixes
4. Deterministic Keys: Valkey keys follow predictable patterns
5. TTL Management: Cache entries have explicit TTLs

2. PostgreSQL Schema Ownership

Schema-to-Module Mapping

Detailed Schema Definitions (authoritative source)

The exact column definitions for every schema are not reproduced here — they drift. Each service owns its DDL as embedded SQL migrations that auto-apply on startup (see database auto-migration requirement, §2.7). The canonical, forward-only migration files are the source of truth; the summaries below capture only the shape and intent.

Invariants worth carrying (verify against the migrations, not this table):

• Append-only evidence (AOC): vuln.advisory_raw and vex.vex_raw store the original JSON as-received and are immutable; ingest must not mutate, only append revisions.
• Content-addressed keys: scanner artifacts are keyed by sha256: digest, not surrogate IDs.
• Compiled-IR + hash: policy.policies stores both source YAML and a hashed compiled IR so evaluation is deterministic and replayable.
• Dynamic finding tables: Policy creates effective_finding_{policyId} (snapshot) and effective_finding_{policyId}_history (audit) per policy rather than one wide table.

The shared migration runner (AddStartupMigrations) lives in src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/. See also the consolidated schema doc, ../DATA_SCHEMAS.md.

3. Valkey Keyspace Reference

Key Patterns by Module

Stream Definitions

Valkey Configuration

Streams use Redis consumer groups (e.g. scanner-workers on scanner:jobs, notify-workers on notify:delivery) with an LRU eviction policy. Concrete maxmemory, eviction, and consumer-group tuning are deployment concerns — see the compose/Valkey configuration under devops/compose/ rather than pinning values here.

4. RustFS (S3) Path Conventions

Blob Storage Layout

blobs/
+-- {sha256_prefix}/               # First 4 chars of digest
    +-- {full_digest}/
        +-- sbom.json              # SBOM payload (any format)
        +-- sbom.meta.json         # Wrapper envelope
        +-- sbom.cdx.pb            # CycloneDX Protobuf (compact)
        +-- attestation.dsse       # DSSE envelope
        +-- evidence.bundle        # Evidence package

images/
+-- {imageDigest}/
    +-- inventory.cdx.json         # Inventory SBOM
    +-- inventory.cdx.pb           # Inventory (Protobuf)
    +-- usage.cdx.json             # Usage SBOM (entrypoint closure)
    +-- usage.cdx.pb               # Usage (Protobuf)
    +-- call-graph.json            # Call graph data
    +-- reachability.json          # Reachability analysis

evidence/
+-- {bundleId}/
    +-- manifest.json              # Bundle manifest
    +-- manifest.dsse              # Signed manifest
    +-- sboms/                     # SBOM files
    +-- attestations/              # Attestation files
    +-- proofs/                    # Verification proofs

offline-kits/
+-- {kitId}/
    +-- feeds/                     # Advisory snapshots
    +-- images/                    # Container images
    +-- signatures/                # DSSE signatures
    +-- trust-roots/               # CA certificates
    +-- manifest.json              # Kit manifest

SBOM Wrapper Envelope

{
  "id": "sha256:417f...",
  "imageDigest": "sha256:e2b9...",
  "created": "2025-01-02T15:30:00Z",
  "format": "cdx-json",
  "layers": [
    "sha256:d38b...",
    "sha256:af45..."
  ],
  "partial": false,
  "provenanceId": "prov_0291"
}

Content Types

5. Module-to-Storage Mapping

Complete Reference Table

6. Cross-References

Data Flow Dependencies

+---------+     +-----------+     +--------+     +--------+
| Scanner |---->| SbomService|---->| Policy |---->| Notify |
+---------+     +-----------+     +--------+     +--------+
     |                |                |              |
     v                v                v              v
+----------+    +-----------+    +-----------+   +---------+
| scanner  |    |  blobs/   |    |  policy   |   | notify  |
| (PG)     |    |  (RustFS) |    |  (PG)     |   | (PG)    |
+----------+    +-----------+    +-----------+   +---------+

+-----------+     +----------+
| Concelier |---->|  Policy  |
+-----------+     +----------+
     |                 ^
     v                 |
+----------+     +-----------+
|   vuln   |     | Excititor |
|  (PG)    |     +-----------+
+----------+           |
                       v
                 +----------+
                 |   vex    |
                 |  (PG)    |
                 +----------+

Schema Version Tracking

All schemas support versioning:

-- Every schema has a version tracking table
schema_migrations (
  version INTEGER PRIMARY KEY,
  description TEXT,
  applied_at TIMESTAMPTZ,
  checksum VARCHAR(64)
);

Backup Considerations

Related Documentation

• Data Schemas - Detailed schema definitions
• Data Flows - How data moves through the system
• Data Isolation - Per-tenant isolation model
• Module Matrix - Complete module inventory
• Request Flows - HTTP/Binary protocol flows