Signals Module Architecture

Overview

The Signals service (StellaOps.Signals) is the reachability and runtime-evidence plane. It ingests and serves the raw evidence signals that downstream scoring and policy consume: static call graphs, reachability facts, runtime facts (observed symbol execution from the runtime agent / deployment-observation agent), unknown symbols, execution evidence, and verification beacons. It owns the signals PostgreSQL schema, exposes an HTTP API under /signals (plus SCM/CI webhooks and a compatibility /api/v1/signals surface), and publishes signals.fact.updated.v1 events when reachability facts change.

The service also owns the Evidence-Weighted Score (EWS) and Unified Score runtime. Score/Endpoints/ScoreEndpoints.cs exposes the tenant-scoped /api/v1/score API, backed by ScoreEvaluationService and durable signals.score_history; the older UnifiedScore/ facade remains an in-process library rather than the endpoint handler. The EWS algorithm is documented under Evidence-Weighted Score (scoring library) below.

Audience: engineers producing or consuming reachability/runtime evidence, integrators of the EWS scoring library, and operators configuring durable storage and the SCM/CI webhook surface. For the scoring model in isolation see unified-score.md; for the wire contract see api-reference.md.

Module Purpose

• Ingest & serve reachability evidence: Call graphs, reachability facts, runtime facts, unknown symbols, execution evidence, beacons — keyed by callgraph/scan/subject identifiers.
• Own durable evidence storage: The signals PostgreSQL schema (auto-migrated on startup) plus a content-addressed artifact store (filesystem or RustFS) for callgraph and runtime-facts blobs.
• Score deterministically: Combine normalized evidence dimensions into a single 0-100 score via the EWS / Unified Score calculators; same inputs + policy = same score, always.
• Provide transparency: Decomposable scores with per-dimension contributions, applied guardrails, and explanations.
• Fail closed: Outside explicit local-harness mode, require durable PostgreSQL, an explicit cache endpoint, Authority authentication, and (in production) the RustFS artifact store. See Production Runtime Boundary.

Location

src/Signals/
├── StellaOps.Signals/                         # Web service (minimal-API host)
│   ├── Program.cs                             # Host + all /signals endpoints
│   ├── CompatibilityApiV1Endpoints.cs         # /api/v1/signals (static demo records)
│   ├── Scm/ScmWebhookEndpoints.cs             # /webhooks/{github,gitlab,gitea}
│   ├── Hosting/                               # SignalsRuntimeConfigurationValidator,
│   │                                          #   SignalsSealedModeMonitor, SignalsStartupState
│   ├── Models/                                # Callgraph*, ReachabilityFact*, RuntimeFacts*,
│   │                                          #   Unknown*, Beacon*, ExecutionEvidence* DTOs
│   ├── Persistence/                           # Repo interfaces + in-memory implementations
│   ├── Services/                              # Ingestion, scoring, events, retention, decay
│   ├── Storage/                               # FileSystem/RustFs callgraph + runtime-facts stores
│   ├── EvidenceWeightedScore/                 # EWS scoring library used by Score runtime
│   │   ├── EvidenceWeightedScoreCalculator.cs # also defines EvidenceWeightedScoreResult,
│   │   │                                      #   AppliedGuardrails, DimensionContribution
│   │   ├── EvidenceWeightedScoreInput.cs
│   │   ├── EvidenceWeightPolicy.cs            # weights, guardrails, BucketThresholds
│   │   ├── EvidenceWeightPolicyOptions.cs / IEvidenceWeightPolicyProvider.cs
│   │   ├── WeightManifest.cs / FileBasedWeightManifestLoader.cs / IWeightManifestLoader.cs
│   │   ├── ReachabilityInput.cs / RuntimeInput.cs / BackportInput.cs /
│   │   │   ExploitInput.cs / SourceTrustInput.cs / MitigationInput.cs / AnchorMetadata.cs
│   │   └── Normalizers/
│   │       ├── BackportEvidenceNormalizer.cs   ExploitLikelihoodNormalizer.cs
│   │       ├── MitigationNormalizer.cs         ReachabilityNormalizer.cs
│   │       ├── RuntimeSignalNormalizer.cs      SourceTrustNormalizer.cs
│   │       ├── IEvidenceNormalizer.cs          NormalizerAggregator.cs / INormalizerAggregator.cs
│   │       └── EvidenceNormalizersServiceCollectionExtensions.cs
│   ├── Score/                                 # Live /api/v1/score endpoints, contracts, services
│   └── UnifiedScore/                          # Older in-process facade over EWS
│       ├── UnifiedScoreService.cs / IUnifiedScoreService.cs / UnifiedScoreModels.cs
│       ├── UnknownsBandMapper.cs              ServiceCollectionExtensions.cs
│       └── Replay/                            # Deterministic replay verifier
├── StellaOps.Signals.RuntimeAgent/           # In-process runtime evidence agent (CLR EventPipe, eBPF)
├── StellaOps.Signals.Scheduler/              # Scheduler queue job client for rescans
├── __Libraries/
│   ├── StellaOps.Signals.Persistence/        # PostgreSQL repos + Migrations/*.sql (schema: signals)
│   └── StellaOps.Signals.Ebpf/               # eBPF micro-witness support
└── __Tests/
    └── StellaOps.Signals.Tests/              # Unit, property, integration, snapshot tests

Note: The doc previously listed EvidenceWeightedScoreResult.cs, Guardrails/ScoreGuardrails.cs, and Policy/EvidenceWeightPolicyProvider.cs as separate files. Those do not exist. The result record (EvidenceWeightedScoreResult) and guardrail types live inside EvidenceWeightedScoreCalculator.cs; the policy provider interface is IEvidenceWeightPolicyProvider.cs.

Evidence-Weighted Score (scoring library)

Status: The EWS calculator remains a reusable in-process library, and the Unified Score facade is also registered by AddScoreEvaluationServices() and exposed through the live /api/v1/score/* Signals API. The evidence dimensions below are populated from plain input DTOs (ReachabilityInput, RuntimeInput, BackportInput, ExploitInput, SourceTrustInput, MitigationInput) supplied by the caller — Signals does not hold direct project references to Policy, Concelier, Scanner, or Excititor (see Integration Points).

Evidence Dimensions

Scoring Formula

The calculator (EvidenceWeightedScoreCalculator) supports several formula modes selected by policy/input: the standard weighted-sum, an advisory formula (raw = 0.25*cvss + 0.30*epss + 0.20*reachability + 0.10*exploit_maturity - 0.15*patch_proof), an attested-reduction mode, and a VEX override (authoritative not_affected/fixed forces score 0). The standard weighted-sum is:

Score = clamp01(W_rch*RCH + W_rts*RTS + W_bkp*BKP + W_xpl*XPL + W_src*SRC - W_mit*MIT) * 100

Note: MIT is subtractive — mitigations reduce risk. The result is an EvidenceWeightedScoreResult carrying the score, bucket, per-dimension DimensionContribution values, applied AppliedGuardrails, badge flags, a canonical digest, and CalculatedAt.

Guardrails

Hard caps and floors based on evidence conditions:

1. Not-Affected Cap: If vendor says not-affected (BKP=1) and no runtime contradiction (RTS<0.6), cap at 15
2. Runtime Floor: If strong live signal (RTS>=0.8), floor at 60
3. Speculative Cap: If no reachability and no runtime (RCH=0, RTS=0), cap at 45

Score Buckets

Architecture

Component Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        Signals Module                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐    ┌──────────────────────────────────┐   │
│  │ NormalizerAggr. │───▶│ EvidenceWeightedScoreCalculator  │   │
│  └────────┬────────┘    └──────────────┬───────────────────┘   │
│           │                            │                        │
│           ▼                            ▼                        │
│  ┌─────────────────┐    ┌──────────────────────────────────┐   │
│  │   Normalizers   │    │   Guardrails (AppliedGuardrails,  │   │
│  │ ┌─────┐ ┌─────┐ │    │   in EvidenceWeightedScoreCalc.)  │   │
│  │ │ BKP │ │ XPL │ │    └──────────────────────────────────┘   │
│  │ └─────┘ └─────┘ │                                           │
│  │ ┌─────┐ ┌─────┐ │    ┌──────────────────────────────────┐   │
│  │ │ MIT │ │ RCH │ │    │   IEvidenceWeightPolicyProvider   │   │
│  │ └─────┘ └─────┘ │                                           │
│  │ ┌─────┐ ┌─────┐ │                                           │
│  │ │ RTS │ │ SRC │ │                                           │
│  │ └─────┘ └─────┘ │                                           │
│  └─────────────────┘                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
           │                          │
           ▼                          ▼
┌─────────────────────┐   ┌───────────────────────────────────────┐
│   Caller-supplied   │   │            Consumers                  │
│   input DTOs        │   │                                       │
│                     │   │ • In-process callers / tests          │
│ • ReachabilityInput │   │ • Unified Score facade                │
│ • RuntimeInput      │   │   (UnifiedScore/UnifiedScoreService)  │
│ • BackportInput     │   │                                       │
│ • ExploitInput      │   │ • Signals /api/v1/score API           │
│ • SourceTrustInput  │   │                                       │
│ • MitigationInput   │   │                                       │
└─────────────────────┘   └───────────────────────────────────────┘

The diagram above describes the EWS scoring library only. The Signals service runtime is described under HTTP API Surface and Persistence. NormalizerAggregator and the calculator are registered as part of the score-evaluation service. They still take caller-supplied DTOs; this wiring does not create direct project references to evidence producers.

Data Flow (EWS library)

1. Caller assembles an EvidenceWeightedScoreInput from the per-dimension input DTOs.
2. Normalizers (ReachabilityNormalizer, RuntimeSignalNormalizer, …) convert raw evidence to 0-1 values; NormalizerAggregator composes them.
3. EvidenceWeightedScoreCalculator selects a formula mode and applies it against the active EvidenceWeightPolicy.
4. Guardrails (caps/floors, encoded in the calculator + AppliedGuardrails) adjust the score.
5. An EvidenceWeightedScoreResultis returned with score, bucket, per-dimension contributions, applied guardrails, badge flags, and a canonical digest.

HTTP API Surface

Signals is a minimal-API host (Program.cs). Endpoints under /signals are authorized per-request via Program.TryAuthorize against the scopes below (Authority bearer token, or X-Scopes header when Signals:Authority:AllowAnonymousFallback=true in local/test harnesses). All /signals endpoints also run the sealed-mode gate (SignalsSealedModeMonitor) and return 503 when sealed-mode evidence is invalid. Several write endpoints emit audit events via .Audited(AuditModules.Signals, …).

Health / discovery (anonymous)

Core /signals API

Runtime observation ingest (agent)

Unlike the /signals/* endpoints, this endpoint does not apply Program.TryAuthorize — the deployment-observation agent authenticates at the network edge (mTLS / backend networking), not via the Authority OAuth flow, and the tenant id is carried in the request body.

SCM/CI webhooks (anonymous; signature-validated)

See SCM/CI Integration (Webhooks). Endpoints /webhooks/{github,gitlab,gitea} are mapped via MapScmWebhookEndpoints and run the sealed-mode gate; authorization is by provider signature, not Authority scopes.

Compatibility API (/api/v1/signals)

Truthfulness flag: CompatibilityApiV1Endpoints currently serves a hard-coded array of five static demo records (sig-001…sig-005), not data sourced from the signals schema. It exists so the gateway/orchestrator compatibility surface and orch:read consumers resolve, but it is not a live query of stored signals. Treat this as a placeholder until backed by real persistence.

Unified score API (/api/v1/score)

MapScoreEndpoints() exposes evaluation, persisted score lookup/history, weight manifests, explanation, replay-envelope retrieval, and deterministic replay verification. The group is tenant-required. All routes require signals.score.read (score.read); POST /evaluate also requires signals.score.evaluate (score.evaluate). See Unified Score and the generated API reference.

Authorization scopes

Defined in StellaOps.Signals.Routing.SignalsPolicies:

Persistence (signals PostgreSQL schema)

Signals owns the signalsPostgreSQL schema (SignalsDataSource.DefaultSchemaName). Per repo policy [§2.7], it auto-migrates on startup: AddSignalsPersistence calls AddStartupMigrations("signals", "Signals.Persistence", typeof(SignalsDataSource).Assembly), and the migration SQL files are embedded resources (Migrations\**\*.sql, excluding Migrations\_archived\**). The connection string is resolved from Signals:Postgres:ConnectionString, Postgres:Signals:ConnectionString, or the equivalent Signals__… / Postgres__… environment variables (see ResolveSignalsPostgresConnectionString). When no connection string is present, durable repos are replaced with InMemory* implementations only in local-harness mode (otherwise startup throws).

Migrations

Tables (by responsibility)

Repository interfaces live under StellaOps.Signals/Persistence/ (with InMemory* doubles) and PostgreSQL implementations under StellaOps.Signals.Persistence/Postgres/Repositories/ (PostgresCallgraphRepository, PostgresReachabilityFactRepository, PostgresUnknownsRepository, PostgresReachabilityStoreRepository, PostgresDeploymentRefsRepository, PostgresGraphMetricsRepository, PostgresCallGraphQueryRepository, PostgresCallGraphProjectionRepository, PostgresRuntimeObservationRepository).

Artifact storage (blobs)

Callgraph and runtime-facts blobs are stored separately from the relational schema via a content-addressed artifact store selected by Signals:Storage:Driver:

• filesystem (default) → FileSystemCallgraphArtifactStore / FileSystemRuntimeFactsArtifactStore (development-only; container filesystem is ephemeral).
• rustfs → RustFsCallgraphArtifactStore / RustFsRuntimeFactsArtifactStore (required in production — see Runtime-facts production storage).

Events

When a reachability fact is created/updated, Signals publishes an event built by ReachabilityFactEventBuilder (signals.fact.updated@v1 payload). The publisher is selected by Signals:Events:Driver:

• redis → RedisEventsPublisher
• router → RouterEventsPublisher (HTTP to the Stella Router)
• inmemory → InMemoryEventsPublisher (local-harness only)
• disabled (Signals:Events:Enabled=false) → NullEventsPublisher

The default topic is signals.fact.updated.v1 (overridable via Signals:AirGap:EventTopic).

Background workers & scheduler

• NightlyDecayWorker (hosted service) runs the unknowns decay pass (UnknownsDecayService, configured via UnknownsDecayOptions).
• UnknownsRescanWorker / SchedulerRescanOrchestrator route rescans of stale unknowns through the scheduler (StellaOps.Signals.Scheduler → SchedulerQueueJobClient); a NullSchedulerJobClient is the no-op fallback.

Production Runtime Boundary

Signals is fail-closed outside explicit local harness mode:

• Signals:Postgres:ConnectionString or Postgres:Signals:ConnectionString is required. Non-durable repositories are available only when the host runs as TestingLocalHarness, or when Signals:LocalHarness:Enabled=true is set in Development/Testing.
• Signals:Authority:Enabled=true is required, and Signals:Authority:AllowAnonymousFallback=false is required. Header/anonymous fallback is only for explicit local and test harnesses. Production startup throws (via StellaOps.Signals.Hosting.SignalsRuntimeConfigurationValidator, which implements the shared IRuntimeConfigurationValidatorcontract introduced in Sprint 20260513_018 URCV-002) if either constraint is violated; the validator short-circuits only for Development, Testing, TestingLocalHarness, or the explicit Signals:LocalHarness:Enabled=true opt-in. Operators must declare Signals__Authority__Enabled=true and Signals__Authority__AllowAnonymousFallback=false explicitly in production compose profiles.
• Signals:Cache:ConnectionString must be explicitly configured. Production startup must not silently use a local Redis/Valkey default such as localhost:6379.
• Signals:Events:Driver=inmemory is local-harness-only. Production can use redis, router, or explicitly disable publishing with Signals:Events:Enabled=false, which binds the null publisher intentionally.
• /signals/runtime-facts/synthetic is local-harness-only and is not mapped on production hosts. Synthetic probes are deterministic test fixtures, not verified runtime observations, and must not influence release policy decisions.
• Runtime-facts batch ingestion is evidence-bearing. It requires a configured ICryptoHash provider and a runtime-facts artifact store before any subject is processed. Signals must fail closed instead of returning timestamp-derived hashes or cas:// references when the raw batch was not actually persisted. The filesystem driver binds FileSystemRuntimeFactsArtifactStore; the RustFS driver binds RustFsRuntimeFactsArtifactStore and persists runtime-facts artifacts under runtime-facts/{first2}/{blake3}/runtime-facts.ndjson[.gz]. RustFS save, read, existence, and delete operations verify the BLAKE3-256 digest instead of trusting object metadata.

Runtime-facts production storage (Sprint 20260502_013 G9-RFS)

Production hosts MUST use the RustFS-compatible object-store driver for runtime-facts artifacts. The local filesystem driver is a development-only escape hatch (the container filesystem is ephemeral, non-shared across replicas, and not durable across redeploys). SignalsRuntimeConfigurationValidator rejects the filesystem driver (options.Storage.IsFileSystemDriver(), i.e. Signals:Storage:Driver=filesystem) outside of Development, Testing, TestingLocalHarness, or the explicit Signals:LocalHarness:Enabled=true opt-in.

Truthfulness note: the validator’s error message string reads "Signals artifact storage Provider=Filesystem is not permitted in Production. Set Signals:ArtifactStorage:Provider=RustFs and configure RustFs:Endpoint.". Those config keys (Signals:ArtifactStorage:Provider, RustFs:Endpoint) are stale in the message text — the options class actually bound is SignalsArtifactStorageOptions, whose keys are Signals:Storage:Driver (filesystem/rustfs) and Signals:Storage:RustFs:BaseUrl. Use the keys in the table below; the validator message is misleading and should be corrected in code.

The RustFS driver is implemented in RustFsRuntimeFactsArtifactStore. Required configuration keys:

Operational guarantees:

• Digest-verified round-trip. SaveAsync re-reads the object after PUT and re-hashes the bytes; mismatched digests throw InvalidDataException rather than returning a fake CAS URI.
• Bounded failure propagation. RustFS 4xx/5xx responses surface as InvalidOperationException carrying status code + reason; there is no silent fallback to filesystem.
• Retention emits structured telemetry. RuntimeFactsRetentionService deletes the underlying artifact by digest via IRuntimeFactsArtifactStore and on transient RustFS failures (e.g. 503) logs a warning carrying StoreType=rustfs, Operation=delete, and ErrorKind=<exception> instead of swallowing the error.

Coverage lives in RustFsRuntimeFactsIntegrationTests (production-shape round-trip, fail-closed on misconfigured endpoint, fail-closed on 5xx) and RuntimeFactsRetentionRustFsTests (delete-by-digest + structured telemetry on 503). The shared object-store CAS pattern is mirrored in BinaryIndex Fingerprints; see docs/modules/binary-index/architecture.md.

EWS weight manifests

EWS weight policies are versioned JSON manifests loaded by FileBasedWeightManifestLoader from etc/weights/*.json (keyed by version, e.g. ews.v1). Versioning supports reproducibility — a computed score carries the policy digest. The default weights/guardrails (below) match EvidenceWeights.Default and BucketThresholds.Default / guardrail defaults in EvidenceWeightPolicy:

{
  "version": "ews.v1",
  "weights": { "rch": 0.30, "rts": 0.25, "bkp": 0.15, "xpl": 0.15, "src": 0.10, "mit": 0.10 },
  "guardrails": {
    "not_affected_cap": { "enabled": true, "max_score": 15 },
    "runtime_floor":    { "enabled": true, "min_score": 60 },
    "speculative_cap":  { "enabled": true, "max_score": 45 }
  }
}

Do not confuse these EWS weight manifests with the Signals:Scoring config section in etc/signals.yaml. The latter configures the reachability confidence scorer (ReachableConfidence, UnreachableConfidence, RuntimeBonus, MaxConfidence, MinConfidence) used by ReachabilityScoringService, not the EWS dimension weights.

Service configuration (etc/signals.yaml)

Top-level sections under Signals: (see SignalsOptions and etc/signals.yaml.sample):

Integration Points

Truthfulness note: StellaOps.Signals.csproj holds no project references to Policy, Concelier, Scanner, or Excititor. The previous “Direct type reference” inbound table was inaccurate — the EWS calculator consumes plain caller-supplied input DTOs, and the service ingests evidence over HTTP. The integration model below reflects the actual build graph and wire surface.

Inbound (how evidence reaches Signals)

Direct project references: StellaOps.Auth.* (Authority), StellaOps.Messaging / StellaOps.Router.Transport.Messaging (events/router), StellaOps.Infrastructure.Postgres (migrations), StellaOps.Audit.Emission, StellaOps.Cryptography, StellaOps.Canonical.Json, and the local StellaOps.Signals.Persistence / StellaOps.Signals.RuntimeAgent libraries.

Outbound (Consumers)

Determinism

Signals maintains strict determinism in its scoring and evidence digests:

1. Same inputs + same policy = same score: No randomness, no time-dependent factors in the EWS formula. AddDeterminismDefaults() is wired in Program.cs, and time-dependent values are explicitly annotated (// Determinism:Allowed).
2. Policy versioning: Each weight manifest is versioned; the EvidenceWeightedScoreResult carries a canonical digest (WithComputedDigest()).
3. Reproducible replay: UnifiedScore/Replay/IReplayVerifier re-derives scores for verification.
4. Canonical fact digests: ReachabilityFactDigestCalculator produces stable digests over reachability facts; runtime-facts artifacts are content-addressed (BLAKE3-256).

The performance targets that previously appeared here (single calc <10ms, batch <1s, cache hit >80%, etc.) were aspirational and not codified in a benchmark in this module; they have been removed pending a real perf harness.

Testing Strategy

Tests live in the single project __Tests/StellaOps.Signals.Tests/, grouped by feature subdirectory (not by Properties/Integration/Snapshots folders as earlier drafts claimed):

Related Documentation

• Companion: unified-score.md, api-reference.md, README.md
• eBPF determinism contract: contracts/ebpf-micro-witness-determinism-profile.md
• Runtime configuration validation: ../../architecture/runtime-configuration-validation.md
• Forward-only migration policy: ADR-004
• BinaryIndex CAS pattern (shared object-store shape): ../binary-index/architecture.md

Earlier drafts linked a 24-Dec-2025 Evidence-Weighted Score Model advisory, SPRINT_8200_0012_* plans, and per-module pages (policy/confidence-scoring.md, concelier/backport-detection.md, scanner/epss-enrichment.md, excititor/trust-vector.md). Those links were not verified to exist at the stated paths and the cross-module “direct integration” they implied is not present in the build graph; they have been dropped in favour of in-module companions above.

SCM/CI Integration (Webhooks)

The Signals module also handles webhook ingestion from SCM (Source Code Management) and CI (Continuous Integration) providers. This enables:

• Triggering scans on push/PR/release events
• SBOM uploads from CI pipelines
• Image push detection and automated scanning

Location

src/Signals/StellaOps.Signals/Scm/
├── Models/
│   ├── NormalizedScmEvent.cs      # Provider-agnostic event payload
│   ├── ScmEventType.cs            # Event type enumeration
│   └── ScmProvider.cs             # Provider enumeration
├── Webhooks/
│   ├── IWebhookSignatureValidator.cs
│   ├── GitHubWebhookValidator.cs  # HMAC-SHA256 validation
│   ├── GitLabWebhookValidator.cs  # Token-based validation
│   ├── GiteaWebhookValidator.cs   # HMAC-SHA256 validation
│   ├── IScmEventMapper.cs
│   ├── GitHubEventMapper.cs       # GitHub -> NormalizedScmEvent
│   ├── GitLabEventMapper.cs       # GitLab -> NormalizedScmEvent
│   └── GiteaEventMapper.cs        # Gitea -> NormalizedScmEvent
├── Services/
│   ├── IScmWebhookService.cs
│   ├── ScmWebhookService.cs       # Orchestrates validation + mapping
│   ├── IScmTriggerService.cs
│   └── ScmTriggerService.cs       # Routes events to Scanner/Orchestrator
└── ScmWebhookEndpoints.cs         # Minimal API webhook endpoints

Supported Providers

Event Types

Webhook Payload Normalization

All provider-specific payloads are normalized to NormalizedScmEvent:

public sealed record NormalizedScmEvent
{
    public required string EventId { get; init; }
    public ScmProvider Provider { get; init; }
    public ScmEventType EventType { get; init; }
    public DateTimeOffset Timestamp { get; init; }
    public required ScmRepository Repository { get; init; }
    public ScmActor? Actor { get; init; }
    public string? Ref { get; init; }
    public string? CommitSha { get; init; }
    public ScmPullRequest? PullRequest { get; init; }
    public ScmRelease? Release { get; init; }
    public ScmPipeline? Pipeline { get; init; }
    public ScmArtifact? Artifact { get; init; }
    public IReadOnlyDictionary<string, object?>? RawMetadata { get; init; }
    public string? TenantId { get; init; }
    public string? IntegrationId { get; init; }
}

The full ScmEventType enum is broader than the trigger table above — it also includes PullRequest, PullRequestClosed, TagCreated, RefCreated, RefDeleted, PipelineStarted, PipelineCompleted, PipelineFailed, and ArtifactPublished. Only the subset listed in the table currently triggers downstream work.

Trigger Routing

ScmTriggerService.ShouldTriggerScan triggers a scan for: Push to a main/release branch (main, release/*, release-*), PullRequestMerged, ReleasePublished, ImagePushed, and PipelineSucceeded. SBOM ingestion is triggered for SbomUploaded (and artifact events carrying SBOM content).

Security

• Signature verification: All webhooks validate the provider signature before processing (GitHub/Gitea HMAC-SHA256, GitLab token match); missing secret or invalid signature is rejected with a warning log.
• Sealed-mode gate: Webhook handlers run the sealed-mode check and return 503 when sealed-mode evidence is invalid.
• Delivery logging: Each delivery is logged with provider, event type, and delivery ID (structured ILogger scope), and the result is returned to the caller.

Webhook secrets are resolved from Signals:Scm options — IntegrationSecrets[integrationId], then ProviderSecrets[provider], then DefaultSecret. When no secret is configured, the request is rejected unless Signals:Scm:AllowUnsignedWebhooks=true.

Truthfulness note: the previous draft claimed AuthRef-managed secrets and built-in rate limiting for webhooks. Neither is implemented in src/Signals/StellaOps.Signals/Scm/ as of 2026-05-29 — secrets come from Signals:Scm config (above), and there is no rate limiter in the SCM webhook path. These claims have been removed pending implementation.