# Signals Provenance Contract v1.0.0

**Status:** APPROVED
**Version:** 1.0.0
**Effective:** 2025-12-19
**Owner:** Signals Guild + Platform Storage Guild
**Sprint:** SPRINT_0140_0001_0001 (unblocks SIGNALS-24-002, 24-003, 24-004, 24-005)

---

## 1. Purpose

This contract defines the provenance tracking for runtime facts, callgraph storage, and CAS (Content-Addressable Storage) promotion policies. It enables deterministic, auditable signal processing with signed manifests and attestations.

## 2. Schema References

| Schema | Location |
|--------|----------|
| Provenance Feed | `docs/schemas/provenance-feed.schema.json` |
| Runtime Facts | `docs/signals/runtime-facts.md` |
| Reachability Input | `docs/modules/policy/contracts/reachability-input-contract.md` |

## 3. CAS Storage Architecture

### 3.1 Bucket Structure

```
cas://signals/
├── callgraphs/
│   ├── {tenant}/
│   │   ├── {graph_id}.ndjson.zst      # Compressed callgraph
│   │   └── {graph_id}.meta.json       # Callgraph metadata
│   └── global/
│       └── ...
├── manifests/
│   ├── {graph_id}.json                # Signed manifest
│   └── {graph_id}.json.dsse           # DSSE envelope
├── runtime-facts/
│   ├── {tenant}/
│   │   ├── {batch_id}.ndjson.zst      # Runtime fact batch
│   │   └── {batch_id}.provenance.json # Provenance record
│   └── global/
│       └── ...
└── attestations/
    └── {batch_id}.dsse                 # Batch attestation
```

### 3.2 Access Policies

| Principal | callgraphs | manifests | runtime-facts | attestations |
|-----------|------------|-----------|---------------|--------------|
| Signals Service | read/write | read/write | read/write | read/write |
| Policy Engine | read | read | read | read |
| Scanner Worker | write | - | - | - |
| Audit Service | read | read | read | read |
| All Others | deny | deny | deny | deny |

### 3.3 Retention Policies

| Content Type | Retention | GC Policy |
|--------------|-----------|-----------|
| Manifests | Indefinite | Never delete |
| Callgraphs (referenced) | Indefinite | Never delete |
| Callgraphs (orphan) | 30 days | Rolling GC |
| Runtime Facts | 90 days | Rolling GC |
| Attestations | Indefinite | Never delete |

## 4. Manifest Schema

### 4.1 CallgraphManifest

```csharp
public sealed record CallgraphManifest
{
    /// <summary>Unique graph identifier (ULID).</summary>
    public required string GraphId { get; init; }

    /// <summary>SHA-256 digest of callgraph content.</summary>
    public required string Digest { get; init; }

    /// <summary>Programming language.</summary>
    public required string Language { get; init; }

    /// <summary>Source identifier (scanner, analyzer, runtime agent).</summary>
    public required string Source { get; init; }

    /// <summary>When the callgraph was created.</summary>
    public required DateTimeOffset CreatedAt { get; init; }

    /// <summary>Tenant scope.</summary>
    public required string TenantId { get; init; }

    /// <summary>Component PURL.</summary>
    public required string ComponentPurl { get; init; }

    /// <summary>Entry points discovered.</summary>
    public ImmutableArray<string> EntryPoints { get; init; }

    /// <summary>Node count in the graph.</summary>
    public int NodeCount { get; init; }

    /// <summary>Edge count in the graph.</summary>
    public int EdgeCount { get; init; }

    /// <summary>Signing key ID.</summary>
    public string? SignerKeyId { get; init; }

    /// <summary>Signature (Base64).</summary>
    public string? Signature { get; init; }

    /// <summary>Rekor log UUID if transparency-logged.</summary>
    public string? RekorUuid { get; init; }
}
```

### 4.2 JSON Example

```json
{
  "graphId": "01HWXYZ123456789ABCDEFGHJK",
  "digest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
  "language": "javascript",
  "source": "stella-callgraph-node",
  "createdAt": "2025-12-19T10:00:00Z",
  "tenantId": "tenant-001",
  "componentPurl": "pkg:npm/%40acme/backend@1.2.3",
  "entryPoints": ["src/index.js", "src/server.js"],
  "nodeCount": 1523,
  "edgeCount": 4892,
  "signerKeyId": "signals-signer-2025-001",
  "signature": "base64...",
  "rekorUuid": "24296fb24b8ad77a..."
}
```

## 5. Runtime Facts Provenance

### 5.1 ProvenanceRecord

```csharp
public sealed record RuntimeFactProvenance
{
    /// <summary>Provenance record ID (ULID).</summary>
    public required string ProvenanceId { get; init; }

    /// <summary>Callgraph ID this fact batch relates to.</summary>
    public required string CallgraphId { get; init; }

    /// <summary>Batch ID for this fact set.</summary>
    public required string BatchId { get; init; }

    /// <summary>When facts were ingested.</summary>
    public required DateTimeOffset IngestedAt { get; init; }

    /// <summary>When facts were received from source.</summary>
    public required DateTimeOffset ReceivedAt { get; init; }

    /// <summary>Tenant scope.</summary>
    public required string TenantId { get; init; }

    /// <summary>Source host/service.</summary>
    public required string Source { get; init; }

    /// <summary>Pipeline version (git SHA or build ID).</summary>
    public required string PipelineVersion { get; init; }

    /// <summary>SHA-256 of raw fact blob.</summary>
    public required string ProvenanceHash { get; init; }

    /// <summary>Signing key ID.</summary>
    public string? SignerKeyId { get; init; }

    /// <summary>Rekor UUID or skip reason.</summary>
    public string? RekorUuid { get; init; }

    /// <summary>Skip reason if not transparency-logged.</summary>
    public string? SkipReason { get; init; }

    /// <summary>Fact count in this batch.</summary>
    public int FactCount { get; init; }

    /// <summary>Fact types included.</summary>
    public ImmutableArray<string> FactTypes { get; init; }
}
```

### 5.2 Enrichment Pipeline

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Runtime Agent   │────▶│ Signals Ingest   │────▶│ CAS Storage     │
│ (runtime-facts) │     │ (provenance)     │     │ (facts+prov)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │ DSSE Attestation │
                        │ (per batch)      │
                        └──────────────────┘
```

## 6. API Endpoints

### 6.1 Callgraph Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `POST /signals/callgraphs` | POST | Store new callgraph |
| `GET /signals/callgraphs/{graphId}` | GET | Retrieve callgraph |
| `GET /signals/callgraphs/{graphId}/manifest` | GET | Get signed manifest |
| `GET /signals/callgraphs/by-purl/{purl}` | GET | Find by component PURL |

### 6.2 Runtime Facts

| Endpoint | Method | Description |
|----------|--------|-------------|
| `POST /signals/runtime-facts` | POST | Ingest runtime fact batch |
| `GET /signals/runtime-facts/{batchId}` | GET | Retrieve fact batch |
| `GET /signals/runtime-facts/{batchId}/provenance` | GET | Get provenance record |
| `GET /signals/runtime-facts/ndjson` | GET | Stream facts (with provenance) |

### 6.3 Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `tenant` | string | Filter by tenant |
| `callgraph_id` | string | Filter by callgraph |
| `since` | datetime | Facts after timestamp |
| `include_provenance` | bool | Include provenance_hash and callgraph_id |

## 7. Signing and Attestation

### 7.1 Manifest Signing

All callgraph manifests are signed using:
- Algorithm: `ECDSA-P256-SHA256` or `Ed25519`
- Key management: Via Authority service key registry
- Transparency: Optional Sigstore Rekor logging

```csharp
public interface IManifestSigner
{
    Task<SignedManifest> SignAsync(
        CallgraphManifest manifest,
        CancellationToken cancellationToken = default);

    Task<bool> VerifyAsync(
        SignedManifest signedManifest,
        CancellationToken cancellationToken = default);
}
```

### 7.2 Batch Attestation

Runtime fact batches are attested using in-toto/DSSE:

```csharp
public sealed record RuntimeFactAttestation
{
    public required string PredicateType { get; init; } // "https://stella.ops/attestation/runtime-facts/v1"
    public required string BatchId { get; init; }
    public required string ProvenanceHash { get; init; }
    public required int FactCount { get; init; }
    public required DateTimeOffset Timestamp { get; init; }
    public required ImmutableArray<string> Subjects { get; init; } // callgraph IDs
}
```

## 8. Telemetry

### 8.1 Metrics

| Metric | Type | Labels | Description |
|--------|------|--------|-------------|
| `signals_callgraphs_stored_total` | counter | `language`, `tenant` | Callgraphs stored |
| `signals_callgraph_nodes_total` | histogram | `language` | Nodes per callgraph |
| `signals_runtime_facts_ingested_total` | counter | `fact_type`, `tenant` | Facts ingested |
| `signals_runtime_facts_batch_size` | histogram | - | Facts per batch |
| `signals_provenance_records_total` | counter | - | Provenance records created |
| `signals_attestations_created_total` | counter | - | DSSE attestations created |
| `signals_cas_operations_total` | counter | `operation`, `result` | CAS operations |

### 8.2 Alerts

```yaml
groups:
  - name: signals-provenance
    rules:
      - alert: SignalsAttestationFailure
        expr: increase(signals_attestations_created_total{result="failure"}[5m]) > 0
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "Runtime fact attestation failures detected"

      - alert: SignalsProvenanceMissing
        expr: signals_runtime_facts_ingested_total - signals_provenance_records_total > 100
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Runtime facts missing provenance records"
```

## 9. Configuration

```yaml
# etc/signals.yaml
Signals:
  CAS:
    BucketPrefix: "cas://signals"
    WriteEnabled: true
    RetentionDays:
      RuntimeFacts: 90
      OrphanCallgraphs: 30

  Provenance:
    Enabled: true
    SignManifests: true
    AttestBatches: true
    RekorEnabled: true  # Set to false for air-gap

  Signing:
    KeyId: "signals-signer-2025-001"
    Algorithm: "ECDSA-P256-SHA256"
```

## 10. Validation Rules

1. `GraphId` must be valid ULID
2. `Digest` must be valid `sha256:` prefixed hex
3. `Language` must be known language identifier
4. `TenantId` must exist in Authority tenant registry
5. `ComponentPurl` must be valid Package URL
6. `ProvenanceHash` must match recomputed hash of fact blob
7. Manifests must have valid signature if `SignManifests: true`
8. Attestations must have valid DSSE envelope

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-12-19 | Initial release - unblocks SIGNALS-24-002 through 24-005 |