# Reachability Analysis Technical Reference

**Source Advisories**:
- 05-Dec-2025 - Building a Deterministic, Reachability‑First Architecture
- 13-Dec-2025 - Designing the Call‑Stack Reachability Engine
- 03-Dec-2025 - Reachability Benchmarks and Moat Metrics
- 09-Dec-2025 - Caching Reachability the Smart Way
- 06-Dec-2025 - Reachability Methods Worth Testing This Week
- 04-Dec-2025 - Ranking Unknowns in Reachability Graphs
- 02-Dec-2025 - Designing Deterministic Reachability UX
- 05-Dec-2025 - Design Notes on Smart‑Diff and Call‑Stack Analysis

**Last Updated**: 2025-12-14

---

## 1. ARCHITECTURE PATTERNS

### 1.1 Core System Architecture

**Module Responsibilities**
- `StellaOps.Scanner.WebService`: Authoritative for reachability pipeline and lattice computation
- Language workers: Stateless compute producing `CallGraph.v1.json`
- Runtime collectors: Agent/sidecar emitting evidence events only
- Concelier/Excititor: Provide pruned sources; never compute reachability
- Authority: Manages replay manifests, crypto profiles
- Scheduler: Executes rescan/escalation policies

**Architectural Rules**
- Scanner = origin of truth for reachability
- Concelier/Vexer = prune-preservers only
- Authority = replay manifest owner
- Scheduler = executor of policies
- Postgres = System of Record (SoR)
- Valkey = ephemeral only (dedupe, hot cache, rate limits)

### 1.2 Evidence Graph Structure

**Node Types**
- `Artifact`, `Component`, `Vulnerability`, `Attestation`, `Build`, `Deployment`, `RuntimeSignal`

**Edge Types**
- `DESCRIBES`, `AFFECTS`, `NOT_AFFECTED_BY`, `FIXED_IN`, `DERIVED_FROM`, `DEPLOYS`, `OBSERVED_AT_RUNTIME`

**Edge Signing**
- Sign edges, not just nodes (edge = claim)

### 1.3 Determinism Requirements

**Input Manifest Structure**
```jsonc
{
  "scannerVersion": "1.3.0",
  "rulesetId": "stella-default-2025.11",
  "feeds": {
    "nvdDigest": "sha256:...",
    "osvDigest": "sha256:..."
  },
  "sbomDigest": "sha256:...",
  "policyDigest": "sha256:..."
}
```

**Canonicalization Rules**
- Sort arrays by stable keys
- Normalize paths (POSIX style)
- Line endings (LF)
- Encodings (UTF-8)
- No environment variables in core algorithms
- No machine-local files
- No system clock inside algorithms

### 1.4 Build Once, Query Many (avoid all-pairs precompute)

Separate *graph construction* from *reachability queries*:

1. **Build step (once per artifact/version)**
   - Produce a deterministic call graph index: `CallGraph.v1.json` (or a binary format with an accompanying canonical JSON manifest and digest).
   - Persist it content-addressed and bind it into the `ReplayManifest`.

2. **Query step (per entrypoint/sink query)**
   - Run a bounded search (BFS / bidirectional BFS / A*) over the stored index.
   - Return: `reachable`, a canonical shortest path, and `why[]` evidence (callsite/method IDs).

Rule: never compute full transitive-closure tables unless the graph is proven small and bounded; prefer per-query search + caching keyed by immutable inputs.

### 1.5 Deterministic Reachability Cache Key

Cache *query results*, not graph construction:

```
reachabilityCacheKey = (
  graphRevisionId,
  algorithmId,
  fromSymbolId,
  toSymbolId,
  contextHash        // entrypoints, flags/env, runtime profile selector
)
```

Cache requirements:
- Include the canonical path in cache entries; tie-break with stable neighbor ordering.
- Cache negative results explicitly (`reachable=false`) and represent uncertainty (`reachable=null`) without coercion.
- Invalidate by construction: when `graphRevisionId` changes, cache keys naturally change.

### 1.6 Compositional Library Summaries (ReachCheck-style option)

For third-party libraries, evaluate a compositional approach:
- Precompute *library reachability summaries* once per `(purl, version, digest)` offline.
- Merge summaries with the application graph at query time.
- Store each summary as content-addressed evidence with its own digest and tool version.

If using matrix-based transitive-closure summaries, treat them as an optimization layer only: surface any unsoundness/unknowns explicitly and keep all outputs deterministic (no sampling, no nondeterministic parallel traversal ordering).

## 2. DATA CONTRACTS

### 2.1 CallGraph.v1.json Schema

```json
{
  "schema": "stella.callgraph.v1",
  "scanKey": "uuid",
  "language": "dotnet|java|node|python|go|rust|binary",
  "artifacts": [{
    "artifactKey": "<artifactKey>",
    "kind": "assembly|jar|module|binary",
    "sha256": "<sha256>"
  }],
  "nodes": [{
    "nodeId": "<nodeId>",
    "artifactKey": "<artifactKey>",
    "symbolKey": "Namespace.Type::Method(<signature>)",
    "visibility": "public|internal|private|unknown",
    "isEntrypointCandidate": false
  }],
  "edges": [{
    "from": "nodeId",
    "to": "nodeId",
    "kind": "static|heuristic",
    "reason": "direct_call|virtual_call|reflection_string|di_binding|dynamic_import|unknown",
    "weight": 1.0
  }],
  "entrypoints": [{
    "nodeId": "<nodeId>",
    "kind": "http|grpc|cli|job|event|unknown",
    "route": "/api/orders/{id}",
    "framework": "aspnetcore|minimalapi|spring|express|unknown"
  }]
}
```

### 2.2 RuntimeEvidence.v1.json Schema

```json
{
  "schema": "stella.runtimeevidence.v1",
  "scanKey": "uuid",
  "collectedAt": "2025-12-14T10:00:00Z",
  "environment": {
    "os": "linux|windows",
    "k8s": {"namespace": "<namespace>", "pod": "<pod>", "container": "<container>"},
    "imageDigest": "sha256:<digest>",
    "buildId": "<buildId>"
  },
  "samples": [{
    "timestamp": "<utc-iso8601>",
    "pid": 1234,
    "threadId": 77,
    "frames": ["nodeId","nodeId","nodeId"],
    "sampleWeight": 1.0
  }],
  "loadedArtifacts": [{
    "artifactKey": "<artifactKey>",
    "evidence": "loaded_module|mapped_file|jar_loaded"
  }]
}
```

### 2.3 ReplayManifest.json Schema

```json
{
  "schema": "stella.replaymanifest.v1",
  "scanId": "uuid",
  "inputs": {
    "sbomDigest": "sha256:<digest>",
    "callGraphs": [{"language":"dotnet","digest":"sha256:<digest>"}],
    "runtimeEvidence": [{"digest":"sha256:<digest>"}],
    "concelierSnapshot": "sha256:<digest>",
    "excititorSnapshot": "sha256:<digest>",
    "policyDigest": "sha256:<digest>"
  }
}
```

### 2.4 ProofSpine Data Model

```csharp
public sealed record ProofSpine(
    string SpineId,
    string ArtifactId,
    string VulnerabilityId,
    string PolicyProfileId,
    IReadOnlyList<ProofSegment> Segments,
    string Verdict,
    string VerdictReason,
    string RootHash,
    string ScanRunId,
    DateTimeOffset CreatedAt,
    string? SupersededBySpineId
);

public sealed record ProofSegment(
    string SegmentId,
    string SegmentType,
    int Index,
    string InputHash,
    string ResultHash,
    string? PrevSegmentHash,
    DsseEnvelope Envelope,
    string ToolId,
    string ToolVersion,
    string Status
);
```

**Segment Types**
- `SBOM_SLICE`: Component relevance
- `MATCH`: SBOM-to-vuln mapping
- `REACHABILITY`: Symbol reachability
- `GUARD_ANALYSIS`: Config/feature flag gates
- `RUNTIME_OBSERVATION`: Runtime evidence
- `POLICY_EVAL`: Lattice decision

## 3. DATABASE SCHEMAS

### 3.1 Core Reachability Tables (Postgres)

```sql
-- Scan tracking
CREATE TABLE scan (
    scan_id uuid PRIMARY KEY,
    created_at timestamptz,
    repo_uri text,
    commit_sha text,
    sbom_digest text,
    policy_digest text,
    status text
);
CREATE INDEX idx_scan_cache ON scan(commit_sha, sbom_digest);

-- Artifacts
CREATE TABLE artifact (
    artifact_id uuid PRIMARY KEY,
    scan_id uuid REFERENCES scan,
    artifact_key text,
    kind text,
    sha256 text,
    build_id text,
    purl text,
    UNIQUE(scan_id, artifact_key)
);

-- Call graph nodes
CREATE TABLE cg_node (
    scan_id uuid,
    node_id text,
    artifact_key text,
    symbol_key text,
    visibility text,
    flags int,
    PRIMARY KEY(scan_id, node_id)
);

-- Call graph edges
CREATE TABLE cg_edge (
    scan_id uuid,
    from_node_id text,
    to_node_id text,
    kind smallint,
    reason smallint,
    weight real,
    PRIMARY KEY(scan_id, from_node_id, to_node_id, kind, reason)
);
CREATE INDEX idx_cg_edge_from ON cg_edge(scan_id, from_node_id);
CREATE INDEX idx_cg_edge_to ON cg_edge(scan_id, to_node_id);

-- Entrypoints
CREATE TABLE entrypoint (
    scan_id uuid,
    node_id text,
    kind text,
    framework text,
    route text,
    PRIMARY KEY(scan_id, node_id, kind, framework, route)
);

-- Runtime samples
CREATE TABLE runtime_sample (
    scan_id uuid,
    collected_at timestamptz,
    env_hash text,
    sample_id bigserial PRIMARY KEY,
    timestamp timestamptz,
    pid int,
    thread_id int,
    frames text[],
    weight real
);

-- Symbol-to-component mapping
CREATE TABLE symbol_component_map (
    scan_id uuid,
    node_id text,
    purl text,
    mapping_kind text,
    confidence real,
    PRIMARY KEY(scan_id, node_id, purl)
);

-- Reachability results
CREATE TABLE reachability_component (
    scan_id uuid,
    purl text,
    status smallint,
    confidence real,
    why jsonb,
    evidence jsonb,
    PRIMARY KEY(scan_id, purl)
);

CREATE TABLE reachability_finding (
    scan_id uuid,
    cve_id text,
    purl text,
    status smallint,
    confidence real,
    why jsonb,
    evidence jsonb,
    PRIMARY KEY(scan_id, cve_id, purl)
);
```

### 3.2 Unknowns Ranking Tables

```sql
CREATE TABLE unknowns (
    unknown_id uuid PRIMARY KEY,
    pkg_id text,
    pkg_version text,
    digest_anchor bytea,
    unknown_flags jsonb,
    popularity_p float,
    potential_e float,
    uncertainty_u float,
    centrality_c float,
    staleness_s float,
    score float,
    band text CHECK(band IN ('HOT','WARM','COLD')),
    graph_slice_hash bytea,
    evidence_set_hash bytea,
    normalization_trace jsonb,
    callgraph_attempt_hash bytea,
    created_at timestamptz,
    updated_at timestamptz
);

CREATE TABLE deploy_refs (
    pkg_id text,
    image_id text,
    env text,
    first_seen timestamptz,
    last_seen timestamptz
);

CREATE TABLE graph_metrics (
    pkg_id text PRIMARY KEY,
    degree_c float,
    betweenness_c float,
    last_calc_at timestamptz
);
```

### 3.3 Proof Spine Tables

```sql
CREATE TABLE proof_spines (
    spine_id uuid PRIMARY KEY,
    artifact_id text,
    vuln_id text,
    policy_profile_id text,
    verdict text,
    verdict_reason text,
    root_hash text,
    scan_run_id uuid,
    created_at timestamptz,
    superseded_by_spine_id uuid,
    segment_count int
);
CREATE INDEX idx_spine_lookup ON proof_spines(artifact_id, vuln_id, policy_profile_id);

CREATE TABLE proof_segments (
    segment_id uuid PRIMARY KEY,
    spine_id uuid REFERENCES proof_spines,
    idx int,
    segment_type text,
    input_hash text,
    result_hash text,
    prev_segment_hash text,
    envelope bytea,
    tool_id text,
    tool_version text,
    status text,
    created_at timestamptz
);
```

## 4. ALGORITHMS

### 4.1 Reachability Status Classification

**Status Values**
- `UNREACHABLE`: No path from entrypoints
- `POSSIBLY_REACHABLE`: Graph incomplete/dynamic behavior
- `REACHABLE_STATIC`: Static path exists
- `REACHABLE_PROVEN`: Runtime evidence confirms

**Confidence Scoring (Deterministic)**

Base scores:
```
UNREACHABLE → 0.05
POSSIBLY_REACHABLE → 0.35
REACHABLE_STATIC → 0.70
REACHABLE_PROVEN → 0.95
```

Modifiers:
```
+0.10 if path uses only static edges
-0.15 if path includes reflection_string|dynamic_import
+0.10 if runtime evidence hits affected component
-0.10 if NO_ENTRYPOINTS_DISCOVERED
Clamp to [0, 1]
```

### 4.2 Reachability Computation Algorithm

```
Inputs:
- Call graph nodes/edges + entrypoints
- Runtime evidence (optional)
- SBOM with purls
- Vulnerability facts (CVE ↔ purl/version)
- VEX statements

Steps:
1. Build adjacency list for cg_edge.kind in (static, heuristic)
2. Optional: Compress SCCs (Tarjan/Kosaraju)
3. Seed from entrypoints; if empty → mark POSSIBLY_REACHABLE with NO_ENTRYPOINTS_DISCOVERED
4. Traverse reachable nodes; track:
   - firstSeenFromEntrypoint[node]
   - pathWitness[node]
5. Map reachable nodes to purls via symbol_component_map:
   Priority order:
   a. Exact binary symbol → package metadata
   b. Assembly/jar/module to SBOM component (hash/purl)
   c. Heuristics: namespace prefixes, import paths, jar manifest
6. Runtime evidence upgrade:
   - Mark frame nodes as "executed"
   - Mint runtime edges: consecutive frames → runtime_minted
   - Upgrade to REACHABLE_PROVEN if executed node maps to affected purl
7. Compute confidence using deterministic formula
```

### 4.3 Unknowns Ranking Algorithm

**Score Formula**
```
Score = clamp01(
    wP·P  +  # Popularity impact
    wE·E  +  # Exploit consequence potential
    wU·U  +  # Uncertainty density
    wC·C  +  # Graph centrality
    wS·S     # Evidence staleness
)
```

**Default Weights**
```
wP = 0.25  (deployment impact)
wE = 0.25  (potential consequence)
wU = 0.25  (uncertainty density)
wC = 0.15  (graph centrality)
wS = 0.10  (evidence staleness)
```

**Heuristics**
```
P = min(1, log10(1 + deployments)/log10(1 + 100))
U = sum of flags, capped at 1.0:
    +0.30 if no provenance anchor
    +0.25 if version_range
    +0.20 if conflicting_feeds
    +0.15 if missing_vector
    +0.10 if unreachable source advisory
S = min(1, age_days / 14)
```

**Band Assignment**
```
Score ≥ 0.70 → HOT (immediate rescan + VEX escalation)
0.40 ≤ Score < 0.70 → WARM (scheduled rescan 12-72h)
Score < 0.40 → COLD (weekly batch)
```

### 4.4 Node ID Computation (.NET)

**Primary (IL-based)**
```
nodeId = SHA256(MVID + ":" + metadataToken + ":" + arity + ":" + signatureShape)
```

**Fallback (source-only)**
```
nodeId = SHA256(projectPath + ":" + file + ":" + span + ":" + symbolDisplayString)
```

**External nodes**
```
nodeId = SHA256("ext:" + artifactKey + ":" + symbolKey)
```

### 4.5 Canonical Symbol Key Format

```
{Namespace}.{TypeName}[`Arity][+Nested]::{MethodName}[`Arity]({ParamType1},{ParamType2},...)
```

Rules:
- Use `System.*` full names for BCL types
- Use `+` for nested types (metadata style)
- Use backtick arity for generic type/method definitions
- Arrays: `System.String[]`
- Byref: `System.String&`

### 4.6 Reachability Cache Algorithm

```csharp
public readonly record struct ReachKey(
    string AlgoSig,        // e.g., "RTA@sha256:…"
    string InputsHash,     // SBOM slice + policy + versions
    string CallPathHash    // normalized query graph
);

public sealed class ReachCache {
    private readonly ConcurrentDictionary<ReachKey, Lazy<Task<ReachResult>>> _memo = new();

    public Task<ReachResult> GetOrComputeAsync(
        ReachKey key,
        Func<Task<ReachResult>> compute,
        CancellationToken ct)
    {
        var lazy = _memo.GetOrAdd(key, _ => new Lazy<Task<ReachResult>>(
            () => compute(), LazyThreadSafetyMode.ExecutionAndPublication));

        return lazy.Value.ContinueWith(t => {
            if (t.IsCompletedSuccessfully) return t.Result;
            _memo.TryRemove(key, out _);
            throw t.Exception ?? new Exception("reachability failed");
        }, ct);
    }
}
```

**Operational rules**
- Canonical everything: sort nodes/edges, normalize paths
- Cache scope: per-scan, per-workspace, or per-feed version
- TTL: 15-60 minutes or evict after pipeline completes
- Max-entries cap
- Concurrency: `Lazy<Task<>>` coalesces duplicate in-flight calls

### 4.7 Proof Spine Construction

```
1. Sbomer produces SBOM_SLICE segment, DSSE-signs it
2. Scanner produces MATCH segment
3. Reachability produces REACHABILITY segment
4. Guard Analyzer produces GUARD_ANALYSIS segment
5. Vexer evaluates lattice, produces POLICY_EVAL segment
6. ProofSpineBuilder:
   - Sorts segments by predetermined order
   - Chains PrevSegmentHash
   - Computes RootHash = hash(concat of segment hashes)
   - Stores ProofSpine with deterministic SpineId
```

## 5. API CONTRACTS

### 5.1 Scanner Ingestion Endpoints

```
POST /api/scans
  Returns: scanId

POST /api/scans/{scanId}/callgraphs
  Body: CallGraph.v1.json
  Header: Content-Digest (for idempotency)

POST /api/scans/{scanId}/runtimeevidence
  Body: RuntimeEvidence.v1.json

POST /api/scans/{scanId}/sbom
  Body: CycloneDX/SPDX

POST /api/scans/{scanId}/compute-reachability
  Idempotent trigger
```

### 5.2 Query Endpoints

```
GET /api/scans/{scanId}/reachability/components?purl=...
GET /api/scans/{scanId}/reachability/findings?cve=...
GET /api/scans/{scanId}/reachability/explain?cve=...&purl=...
  Returns: why[], path witness, sample refs
```

### 5.3 Export Endpoints

```
GET /api/scans/{scanId}/exports/sarif
GET /api/scans/{scanId}/exports/cdxr  # CycloneDX reachability extension
GET /api/scans/{scanId}/exports/openvex
```

### 5.4 Proof Spine Endpoints

```
GET /graph/runtime/{podId}/lineage
GET /graph/image/{digest}/vex
GET /spines/{spineId}
  Returns: ProofSpine with all segments
```

## 6. .NET IMPLEMENTATION PATTERNS

### 6.1 .NET Worker (Roslyn + IL) Required Features

**Call Graph Extraction**
- Direct invocation edges: `InvocationExpressionSyntax`
- Object creation edges: constructors
- Delegate invocation: record heuristic edge when target unresolved
- Virtual/interface dispatch: record `virtual_call` edge to declared method
- Async/await: connect logical caller → awaited method

**Entrypoint Discovery**
- `Program.Main` (classic)
- ASP.NET Core:
  - Controllers: `[ApiController]`, route attributes, action methods
  - Minimal APIs: `MapGet/MapPost/MapMethods` patterns
  - gRPC: `MapGrpcService<T>()` and service methods
  - Hosted services: `IHostedService`, `BackgroundService.ExecuteAsync`

**Reflection and DI Heuristics**
- `Type.GetType("…")`, `Assembly.GetType`, `GetMethod("…")`, `Invoke`
- `services.AddTransient<IFoo,Foo>()` / `AddScoped` / `AddSingleton`
- `Activator.CreateInstance`, `ServiceProvider.GetService`
- Produce heuristic edges with `reason = di_binding` or `reflection_string`

### 6.2 NuGet Dependencies

```xml
<!-- Roslyn / MSBuild -->
<PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="5.0.0" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.0.0" />
<PackageReference Include="Microsoft.Build.Locator" Version="*" />

<!-- IL + metadata -->
<!-- Use System.Reflection.Metadata (BCL) -->
<!-- Optional: Mono.Cecil for faster IL traversal -->

<!-- CLI + JSON -->
<PackageReference Include="System.CommandLine" Version="*" />
<PackageReference Include="System.Text.Json" Version="*" />
```

### 6.3 Roslyn IL Opcodes for Call Detection

```
Recognize as "calls":
- call
- callvirt
- newobj
- jmp
- ldftn
- ldvirtftn
```

### 6.4 MSBuild Workspace Loading Pattern

```csharp
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.MSBuild;

var ws = MSBuildWorkspace.Create();
var sln = await ws.OpenSolutionAsync(@"path\to.sln");
foreach (var proj in sln.Projects)
foreach (var doc in proj.Documents)
{
    var model = await doc.GetSemanticModelAsync();
    var root = await doc.GetSyntaxRootAsync();
    foreach (var node in root.DescendantNodes()
        .OfType<InvocationExpressionSyntax>())
    {
        var sym = model.GetSymbolInfo(node).Symbol as IMethodSymbol;
        if (sym != null)
        {
            // record edge: caller -> sym
        }
    }
}
```

## 7. CONFIGURATION PATTERNS

### 7.1 Crypto Profiles

```csharp
public interface ICryptoProfile
{
    string ProfileId { get; }
    byte[] Sign(byte[] data, string keyId);
    bool Verify(byte[] data, byte[] signature, string keyId);
}

// Implementations: FipsProfile, GostProfile, EidasProfile, SmProfile, PqcProfile
```

**Profile Metadata**
- Algorithm
- Key ID
- Profile name

**Key Rotation**
- Keys have validity intervals
- Spines keep KeyId in each DSSE signature
- Authority maintains trust table: which keys trusted for which SegmentType and time window

### 7.2 Offline Bundle Format

**Required Contents**
- SBOM + feeds + policy bundle + key material
- Manifest with hashes of all contents
- Replay manifest for deterministic rerun

**Format**
- Zip/tar + manifest
- Each entry content-addressed

### 7.3 Cache Configuration (appsettings)

```json
{
  "Scanner": {
    "Reach": {
      "Cache": {
        "MaxEntries": 10000,
        "TtlMinutes": 60,
        "EvictOnPipelineComplete": true
      }
    }
  }
}
```

## 8. METRICS AND THRESHOLDS

### 8.1 Performance SLOs (v1)

```
Medium service (100k LOC .NET) static graph: < 2 minutes
Reachability compute: < 30 seconds
Query GET finding: < 200ms p95
```

### 8.2 Quality Metrics

**Proof verification**
- % verified proofs
- Proof verification failures
- Proof age since last verification
- % entries with valid inclusion proof (Rekor)

**Unknowns triage**
- Hot/Warm/Cold distribution
- Rescan success rate after N attempts
- Evidence staleness distribution

**Drift detection**
- Runtime edges not in static graph (above threshold → emit COVERAGE_DRIFT warning)

### 8.3 Benchmark Metrics (Moat)

| Metric | Target |
|--------|--------|
| Time-to-evidence: SBOM → signed call-graph | < 5 minutes for 100k LOC service |
| SBOM-diff false positive rate under dependency churn | < 5% change in reachability status for non-code changes |
| Deterministic priority scoring under air-gap replay | Bit-identical results given same inputs |
| Proof verification time | < 200ms p95 |

## 9. TESTING PATTERNS

### 9.1 Golden Corpus Requirements

**Mandatory Test Cases**
1. Minimal ASP.NET controller with reachable endpoint → vulnerable lib call
2. Vulnerable lib present but never called → unreachable
3. Reflection-based activation → "possible" unless runtime proves
4. BackgroundService job case
5. Version range ambiguity
6. Mismatched epoch/backport
7. Missing CVSS vector
8. Conflicting severity vendor/NVD
9. Unanchored filesystem library

**Assertions per Test**
- Reachability status
- At least one `why[]` reason
- Deterministic confidence within ±0.01
- Segments with expected status (verified/partial/invalid)

### 9.2 Replay Manifest Tests

Given manifest containing:
- feed hashes
- rules version
- normalization logic
- lattice rules

Assert: ranking/reachability recomputes identically (byte-for-byte)

### 9.3 Signature Tampering Tests

- Flip byte in DSSE payload → UI must show `invalid`
- Mark key untrusted → segments show `untrusted-key`
- Entire spine marked as compromised

## 10. SPECIFICATION COMPLIANCE

### 10.1 SBOM Standards

**CycloneDX**
- Version: 1.6 (ECMA-424) and 1.7 (current)
- Media type: include version parameter
- Ingest: validate against ECMA-424/1.7 schemas

**SPDX**
- Version: 3.0.1
- Validate against canonical spec

**Ingestion Rules**
- Accept only `*.cdx.json` and `*.spdx.json`
- Hard fail others
- Store: raw bytes + parsed form + normalized canonical form

### 10.2 VEX Standards

**OpenVEX**
- Minimal, SBOM-agnostic
- Predicate type: `https://openvex.dev/ns/v0.2.0`

**CSAF VEX**
- Alternative format for interoperability

**Required VEX Fields**
- status: `not_affected|affected|fixed|under_investigation`
- justification
- timestamp
- author
- link to supporting evidence

### 10.3 Attestation Standards

**DSSE (Dead Simple Signing Envelope)**
- Use for all signed artifacts
- Payload: canonical JSON
- Envelope: signature + key metadata + profile

**in-toto**
- Statement structure
- Predicate types:
  - SBOM: `https://spdx.dev/Document`
  - VEX: OpenVEX predicate URI
  - Custom: reachability predicates

**Cosign Integration**
```bash
cosign attest --yes --type https://spdx.dev/Document \
  --predicate sbom.spdx.json \
  --key cosign.key \
  "${IMAGE_DIGEST}"
```

### 10.4 Rekor Integration

**CLI Verification**
```bash
rekor-cli verify --rekor_server https://rekor.sigstore.dev \
  --signature artifact.sig \
  --public-key cosign.pub \
  --artifact artifact.bin
```

**Persistence per Entry**
- Rekor UUID
- Log index
- Integrated time
- Inclusion proof data

## 11. CLI COMMANDS

### 11.1 Worker CLI

```bash
# Artifacts-first scan
stella-worker-dotnet scan \
  --scanKey 00000000-0000-0000-0000-000000000000 \
  --assemblies ./artifacts/bin/Release \
  --out ./callgraph.json

# Build-and-scan
stella-worker-dotnet scan \
  --scanKey ... \
  --sln ./src/MySolution.sln \
  --configuration Release \
  --tfm net10.0 \
  --buildMode build \
  --out ./callgraph.json

# Upload to scanner.webservice
stella-worker-dotnet scan \
  --scanKey ... \
  --assemblies ./artifacts/bin/Release \
  --upload https://scanner/api/scans/{scanId}/callgraphs \
  --apiKey $STELLA_API_KEY
```

### 11.2 Replay CLI

```bash
stellaops scan \
  --replay-manifest <id-or-file> \
  --artifact <image-digest> \
  --vuln <cve> \
  --explain
```

### 11.3 Reachability Query CLI

```bash
stella scan graph --lang dotnet --sln path.sln --out graph.scc.json
stella scan runtime --target pod/myservice --duration 30s --out stacks.json
stella reachability join \
  --graph graph.scc.json \
  --runtime stacks.json \
  --sbom bom.cdx.json \
  --out reach.cdxr.json
```

## 12. DEVELOPER CHECKLIST

### 12.1 Per-Feature Definition of Done

For any feature touching scans, VEX, or evidence:

- [ ] Deterministic: input manifest defined, canonicalization applied, golden fixture(s) added
- [ ] Evidence: outputs DSSE-wrapped and linked
- [ ] Reachability/Lattice: runs only in allowed services, records algorithm IDs
- [ ] Crypto: calls through profile abstraction, tests for ≥2 profiles
- [ ] Graph: lineage edges added, node/edge IDs stable and queryable
- [ ] UX/API: API to retrieve structured evidence
- [ ] Tests: unit + golden + integration test with full SBOM → scan → VEX chain

### 12.2 Determinism Checklist

- [ ] Input manifest type defined and versioned
- [ ] Canonicalization applied before hashing/signing
- [ ] Output stored with `inputsDigest` and `algoDigest`
- [ ] At least one golden fixture proves determinism
- [ ] No environment variables in core algorithm
- [ ] No machine-local files
- [ ] No system clock inside algorithms

### 12.3 Reachability Implementation Checklist

- [ ] Reachability algorithms only in Scanner.WebService
- [ ] Cache lazy and keyed by deterministic inputs
- [ ] Output includes explicit evidence pointers
- [ ] UI endpoints expose reachability state in structured form
- [ ] All modifiers recorded in `why[]`

### 12.4 Crypto-Sovereign Checklist

- [ ] No direct crypto calls in feature code; only via profile layer
- [ ] All attestations carry algorithm + key id + profile
- [ ] Offline bundle type exists for this workflow
- [ ] Tests for at least 2 different crypto profiles

### 12.5 Policy/Lattice Checklist

- [ ] Facts and policies serialized separately
- [ ] Lattice code in allowed services only
- [ ] Merge strategies named and versioned
- [ ] Artifacts record which lattice algorithm used

### 12.6 Proof-Linked VEX Checklist

- [ ] VEX schema includes pointers to all upstream artifacts (sbomDigest, scanId, reachMapDigest, policyDigest, signerKeyId)
- [ ] No duplication of SBOM/scan content inside VEX
- [ ] DSSE used as standard envelope type

### 12.7 Unknowns Triage Checklist

- [ ] Persist all traces for deterministic replay
- [ ] Ranking depends only on manifest-declared parameters
- [ ] All uncertainty factors are explicit flags
- [ ] Scoring reproducible under identical inputs
- [ ] Scheduler decision table deterministic and tested
- [ ] API exposes full reasoning

---

**Document Version**: 1.0
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17