# 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

```csharp
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

```csharp
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](../../docs/modules/signals/architecture.md)
- [Policy Engine Signals Integration](../../docs/modules/policy/signals.md)