git.stella-ops.org/src/__Libraries/StellaOps.Signals.Contracts/AGENTS.md

StellaOps.Signals.Contracts

Shared signal contracts for cross-module signal communication in StellaOps.

Purpose

This library provides the common contracts (interfaces and DTOs) for signal-based communication between StellaOps modules. It enables:

• Concelier to emit reachability and trust signals
• Scanner to emit entropy and unknown symbol signals
• Policy Engine to consume all signal types for risk scoring
• Signals service to aggregate and cache signals
• Authority to emit trust/provenance signals

Signal Types

Type	Producer	Description
Reachability	Concelier, Scanner	Whether vulnerable code paths are reachable
Entropy	Scanner	Code complexity and risk metrics
Exploitability	Concelier	KEV status, EPSS scores, exploit availability
Trust	Authority, Scanner	Publisher reputation, provenance, signatures
UnknownSymbol	Scanner	Unresolved dependencies during analysis
Custom	Any	Extension point for module-specific signals

Usage

Emitting Signals

public class MySignalProducer
{
    private readonly ISignalEmitter _emitter;
    private readonly ISignalContext _context;

    public async Task EmitReachabilityAsync(string purl, bool isReachable)
    {
        var signal = new ReachabilitySignal
        {
            Purl = purl,
            IsReachable = isReachable,
            Confidence = 0.95
        };

        var envelope = _context.CreateReachabilityEnvelope(purl, signal);
        await _emitter.EmitAsync(envelope);
    }
}

Consuming Signals

public class MySignalConsumer
{
    private readonly ISignalConsumer _consumer;

    public async Task ProcessSignalsAsync(CancellationToken ct)
    {
        await foreach (var signal in _consumer.ConsumeAsync(SignalType.Reachability, ct))
        {
            // Process signal
        }
    }
}

Dependencies

• Microsoft.Extensions.DependencyInjection.Abstractions — DI registration helpers

Implementation Notes

This library contains only contracts. Actual transport implementations are provided by:

• StellaOps.Signals.Nats — NATS JetStream transport
• StellaOps.Signals.InMemory — In-memory transport for testing

Related

• Signal Flow Architecture
• Policy Engine Signals Integration