# REPLAY.yaml Manifest Specification

## Overview

The **REPLAY.yaml** manifest defines the complete set of inputs required to reproduce a StellaOps evaluation. It is the root document in a `.stella-replay.tgz` bundle.

## File Location

```
.stella-replay.tgz
├── REPLAY.yaml          # This manifest
├── sboms/
├── vex/
├── reach/
├── exceptions/
├── policies/
├── feeds/
├── config/
└── SIGNATURE.sig        # Optional DSSE signature
```

## Schema Version

Current schema version: `1.0.0`

```yaml
version: "1.0.0"
```

## Complete Example

```yaml
version: "1.0.0"

snapshot:
  id: "snap-20241222-abc123"
  createdAt: "2024-12-22T12:00:00Z"
  artifact: "sha256:abc123..."
  previousId: "snap-20241221-xyz789"

inputs:
  sboms:
    - path: "sboms/cyclonedx.json"
      format: "cyclonedx-1.6"
      digest: "sha256:def456..."
    - path: "sboms/spdx.json"
      format: "spdx-3.0.1"
      digest: "sha256:ghi789..."

  vex:
    - path: "vex/vendor-lodash.json"
      source: "vendor:lodash"
      format: "openvex"
      digest: "sha256:jkl012..."
      trustScore: 0.95
    - path: "vex/redhat-csaf.json"
      source: "distro:redhat"
      format: "csaf"
      digest: "sha256:mno345..."
      trustScore: 0.90

  reachability:
    - path: "reach/api-handler.json"
      entryPoint: "/api/handler"
      digest: "sha256:pqr678..."
      nodeCount: 42
      edgeCount: 57

  exceptions:
    - path: "exceptions/exc-001.json"
      exceptionId: "exc-001"
      digest: "sha256:stu901..."

  policies:
    bundlePath: "policies/bundle.tar.gz"
    digest: "sha256:vwx234..."
    version: "2.1.0"
    rulesHash: "sha256:yza567..."

  feeds:
    - feedId: "nvd"
      name: "National Vulnerability Database"
      version: "2024-12-22T00:00:00Z"
      digest: "sha256:bcd890..."
      fetchedAt: "2024-12-22T06:00:00Z"
    - feedId: "ghsa"
      name: "GitHub Security Advisories"
      version: "2024-12-22T01:00:00Z"
      digest: "sha256:efg123..."
      fetchedAt: "2024-12-22T06:15:00Z"

  lattice:
    type: "K4"
    configDigest: "sha256:hij456..."

  trust:
    configDigest: "sha256:klm789..."
    defaultWeight: 0.5

outputs:
  verdictPath: "verdict.json"
  verdictDigest: "sha256:nop012..."
  findingsPath: "findings.ndjson"
  findingsDigest: "sha256:qrs345..."

seeds:
  rng: 12345678
  sampling: 87654321

environment:
  STELLAOPS_POLICY_VERSION: "2.1.0"
  STELLAOPS_LATTICE_TYPE: "K4"

signature:
  algorithm: "ecdsa-p256"
  keyId: "signing-key-prod-2024"
  value: "MEUCIQDx..."
```

## Field Reference

### snapshot

Metadata about the snapshot itself.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique snapshot identifier |
| createdAt | datetime | Yes | ISO 8601 timestamp |
| artifact | string | Yes | Artifact digest being evaluated |
| previousId | string | No | Previous snapshot for diff |

### inputs.sboms

SBOM documents included in bundle.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| path | string | Yes | Path within bundle |
| format | string | Yes | `cyclonedx-1.6` or `spdx-3.0.1` |
| digest | string | Yes | Content digest |

### inputs.vex

VEX documents from various sources.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| path | string | Yes | Path within bundle |
| source | string | Yes | Source identifier (vendor:*, distro:*, etc.) |
| format | string | Yes | `openvex`, `csaf`, `cyclonedx-vex` |
| digest | string | Yes | Content digest |
| trustScore | number | Yes | Trust weight (0.0-1.0) |

### inputs.reachability

Reachability subgraph data.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| path | string | Yes | Path within bundle |
| entryPoint | string | Yes | Entry point identifier |
| digest | string | Yes | Content digest |
| nodeCount | integer | No | Number of nodes |
| edgeCount | integer | No | Number of edges |

### inputs.exceptions

Active exceptions at snapshot time.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| path | string | Yes | Path within bundle |
| exceptionId | string | Yes | Exception identifier |
| digest | string | Yes | Content digest |

### inputs.policies

Policy bundle reference.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| bundlePath | string | Yes | Path to policy bundle |
| digest | string | Yes | Bundle digest |
| version | string | No | Policy version |
| rulesHash | string | Yes | Hash of compiled rules |

### inputs.feeds

Advisory feed versions at snapshot time.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| feedId | string | Yes | Feed identifier |
| name | string | No | Human-readable name |
| version | string | Yes | Feed version/timestamp |
| digest | string | Yes | Feed content digest |
| fetchedAt | datetime | Yes | When feed was fetched |

### inputs.lattice

Lattice configuration for merge semantics.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | Yes | `K4`, `Boolean`, `8-state` |
| configDigest | string | Yes | Configuration hash |

### inputs.trust

Trust weight configuration.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| configDigest | string | Yes | Configuration hash |
| defaultWeight | number | No | Default trust weight |

### outputs

Evaluation outputs for verification.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| verdictPath | string | Yes | Path to verdict file |
| verdictDigest | string | Yes | Verdict content digest |
| findingsPath | string | No | Path to findings file |
| findingsDigest | string | No | Findings content digest |

### seeds

Random seeds for deterministic evaluation.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| rng | integer | No | Random number generator seed |
| sampling | integer | No | Sampling algorithm seed |

### environment

Environment variables captured (non-sensitive).

Key-value pairs of environment configuration.

### signature

DSSE signature over manifest.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| algorithm | string | Yes | Signing algorithm |
| keyId | string | Yes | Signing key identifier |
| value | string | Yes | Base64-encoded signature |

## Digest Format

All digests use the format:
```
sha256:<64-char-hex>
```

Example:
```
sha256:a1b2c3d4e5f6...
```

## Validation

Bundle validation checks:
1. REPLAY.yaml exists at bundle root
2. All referenced files exist
3. All digests match content
4. Schema validates against JSON Schema
5. Signature verifies (if present)

## CLI Usage

```bash
# Create bundle
stella snapshot export --output snapshot.stella-replay.tgz

# Verify bundle
stella snapshot verify snapshot.stella-replay.tgz

# Replay from bundle
stella replay --bundle snapshot.stella-replay.tgz

# View manifest
stella snapshot manifest snapshot.stella-replay.tgz
```

## Related Documentation

- [Knowledge Snapshot Model](./knowledge-snapshot.md)
- [Merge Preview](./merge-preview.md)
- [Replay Engine](../../modules/policy/implementation_plan.md)