# component_architecture_mirror.md - **Stella Ops Mirror** (2025Q4)

> Vulnerability feed mirror and distribution service.

> **Scope.** Architecture for **Mirror**: mirroring vulnerability feeds from upstream sources for offline distribution and reduced external dependencies.

---

## 0) Mission & boundaries

**Mission.** Provide **local mirrors** of vulnerability feeds (NVD, OSV, GHSA, etc.) for offline operation and reduced latency. Enable air-gapped deployments to receive updates via bundle import.

**Boundaries.**

* Mirror **caches upstream feeds**; it does not originate vulnerability data.
* Mirror **produces bundles** for air-gapped distribution.
* Feeds are **cryptographically verified** before distribution.

---

## 1) Integration with Concelier

Mirror is primarily integrated as part of Concelier's federation layer:

```
src/Concelier/__Libraries/
 └─ StellaOps.Concelier.Federation/    # Bundle export/import for offline
```

The `StellaOpsMirror` connector in Concelier handles:
- Upstream feed synchronization
- Local cache management
- Bundle generation for offline distribution

---

## 2) Bundle Format

```json
{
  "bundleId": "mirror-nvd-2025-01-15",
  "source": "nvd",
  "timestamp": "2025-01-15T10:30:00Z",
  "contents": [
    {
      "path": "nvd/CVE-2025-*.json",
      "digest": "sha256:abc123..."
    }
  ],
  "signature": { /* DSSE envelope */ }
}
```

---

## Related Documentation

* Concelier: `../concelier/architecture.md`
* AirGap: `../airgap/architecture.md`
* Provenance observers: `./provenance/observers.md`

---

## 3) Mirror Creator Core (2026-02-08)

Sprint `SPRINT_20260208_041_Mirror_mirror_creator` adds a deterministic core library at:

- `src/Mirror/StellaOps.Mirror.Creator/StellaOps.Mirror.Creator.Core.csproj`

### Implemented Contracts

- `IMirrorCreatorService`
  - `UpsertSourceAsync(MirrorSourceConfiguration source, CancellationToken cancellationToken = default)`
  - `GetSourcesAsync(string tenantId, CancellationToken cancellationToken = default)`
  - `CreateSyncPlanAsync(MirrorSyncRequest request, CancellationToken cancellationToken = default)`
  - `RecordSyncResultAsync(MirrorSyncResult result, CancellationToken cancellationToken = default)`
- Model types in `MirrorModels.cs`:
  - `MirrorSourceConfiguration`
  - `MirrorSyncRequest`
  - `MirrorSyncPlan` and `MirrorSyncPlanItem`
  - `MirrorSyncResult`
  - `MirrorContentKind` and `MirrorSyncMode`
- Options in `MirrorCreatorOptions` with configurable `OutputRoot`.
- DI registration in `MirrorServiceCollectionExtensions.AddMirrorCreator(...)`.

### Determinism Guarantees

- Tenant and source IDs are normalized to lowercase-trimmed values.
- Source ordering is stable (ordinal sort by source ID per tenant).
- Plan IDs are generated from canonical plan content using SHA-256.
- Output bundle path format is stable:
  - `<outputRoot>/<tenant>/<source>/<yyyyMMddHHmmss>.bundle.json`
- Sync mode behavior:
  - `Full` when no prior cursor exists.
  - `Incremental` after successful cursor recording via `RecordSyncResultAsync`.

### Test Evidence

- Test project: `src/Mirror/__Tests/StellaOps.Mirror.Creator.Core.Tests/`
- Executed: `dotnet test src/Mirror/__Tests/StellaOps.Mirror.Creator.Core.Tests/StellaOps.Mirror.Creator.Core.Tests.csproj`
- Result on 2026-02-08: Passed `4/4` tests.

### Current Boundaries

- Implementation is currently in-memory and does not persist checkpoints to a backing store.
- No dedicated HTTP endpoints or CLI command group are added in this sprint.
- Runtime mirror transport/execution remains the responsibility of future integration work.