{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/evidence-pointer.schema.json",
  "title": "StellaOps Evidence Pointer Schema",
  "description": "Schema for evidence pointers used in timeline events, evidence locker snapshots, and DSSE attestations. Unblocks TASKRUN-OBS-52-001, TASKRUN-OBS-53-001, TASKRUN-OBS-54-001, TASKRUN-OBS-55-001.",
  "type": "object",
  "definitions": {
    "EvidencePointer": {
      "type": "object",
      "description": "Pointer to evidence artifact in the evidence locker",
      "required": ["pointer_id", "artifact_type", "digest", "created_at"],
      "properties": {
        "pointer_id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier for this evidence pointer"
        },
        "artifact_type": {
          "$ref": "#/definitions/ArtifactType"
        },
        "digest": {
          "$ref": "#/definitions/Digest"
        },
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "URI to retrieve the artifact (may be presigned)"
        },
        "storage_backend": {
          "type": "string",
          "enum": ["cas", "evidence", "attestation", "local", "s3", "azure-blob", "gcs"],
          "description": "Storage backend where artifact resides"
        },
        "bucket": {
          "type": "string",
          "description": "Bucket/container name in object storage"
        },
        "key": {
          "type": "string",
          "description": "Object key/path within bucket"
        },
        "size_bytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Size of artifact in bytes"
        },
        "media_type": {
          "type": "string",
          "description": "MIME type of the artifact"
        },
        "compression": {
          "type": "string",
          "enum": ["none", "gzip", "zstd", "brotli"],
          "default": "none"
        },
        "encryption": {
          "$ref": "#/definitions/EncryptionInfo"
        },
        "chain_position": {
          "$ref": "#/definitions/ChainPosition"
        },
        "provenance": {
          "$ref": "#/definitions/EvidenceProvenance"
        },
        "redaction": {
          "$ref": "#/definitions/RedactionInfo"
        },
        "retention": {
          "$ref": "#/definitions/RetentionPolicy"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "ArtifactType": {
      "type": "string",
      "enum": [
        "sbom",
        "vex",
        "attestation",
        "signature",
        "callgraph",
        "scan_result",
        "policy_evaluation",
        "timeline_transcript",
        "evidence_bundle",
        "audit_log",
        "manifest",
        "provenance",
        "rekor_receipt",
        "runtime_trace",
        "coverage_report",
        "diff_report"
      ],
      "description": "Type of evidence artifact"
    },
    "Digest": {
      "type": "object",
      "description": "Cryptographic digest of artifact content",
      "required": ["algorithm", "value"],
      "properties": {
        "algorithm": {
          "type": "string",
          "enum": ["sha256", "sha384", "sha512", "sha3-256", "sha3-384", "sha3-512"],
          "default": "sha256"
        },
        "value": {
          "type": "string",
          "pattern": "^[a-f0-9]+$",
          "description": "Hex-encoded digest value"
        }
      }
    },
    "EncryptionInfo": {
      "type": "object",
      "description": "Encryption information for protected artifacts",
      "properties": {
        "encrypted": {
          "type": "boolean",
          "default": false
        },
        "algorithm": {
          "type": "string",
          "enum": ["AES-256-GCM", "ChaCha20-Poly1305"],
          "description": "Encryption algorithm used"
        },
        "key_id": {
          "type": "string",
          "description": "Key identifier for decryption"
        },
        "key_provider": {
          "type": "string",
          "enum": ["kms", "vault", "local"],
          "description": "Key management provider"
        }
      }
    },
    "ChainPosition": {
      "type": "object",
      "description": "Position in evidence hash chain for tamper detection",
      "properties": {
        "chain_id": {
          "type": "string",
          "format": "uuid",
          "description": "Evidence chain identifier"
        },
        "sequence": {
          "type": "integer",
          "minimum": 0,
          "description": "Sequence number in chain"
        },
        "previous_digest": {
          "$ref": "#/definitions/Digest"
        },
        "merkle_root": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$",
          "description": "Merkle tree root at this position"
        },
        "merkle_proof": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "description": "Merkle inclusion proof"
        },
        "anchored_at": {
          "type": "string",
          "format": "date-time",
          "description": "When chain was anchored to transparency log"
        },
        "anchor_receipt": {
          "type": "string",
          "description": "Receipt from transparency log (e.g., Rekor)"
        }
      }
    },
    "EvidenceProvenance": {
      "type": "object",
      "description": "Provenance information for evidence artifact",
      "properties": {
        "producer": {
          "type": "string",
          "description": "Service/component that produced the evidence"
        },
        "producer_version": {
          "type": "string"
        },
        "build_id": {
          "type": "string",
          "description": "CI/CD build identifier"
        },
        "source_ref": {
          "type": "string",
          "description": "Source reference (e.g., git commit)"
        },
        "tenant_id": {
          "type": "string",
          "format": "uuid"
        },
        "correlation_id": {
          "type": "string",
          "format": "uuid",
          "description": "Trace correlation ID"
        },
        "parent_pointers": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Parent evidence pointers this derives from"
        },
        "attestation_id": {
          "type": "string",
          "format": "uuid",
          "description": "Associated attestation if signed"
        }
      }
    },
    "RedactionInfo": {
      "type": "object",
      "description": "Redaction policy for evidence artifact",
      "properties": {
        "redaction_applied": {
          "type": "boolean",
          "default": false
        },
        "redaction_policy": {
          "type": "string",
          "description": "Policy identifier that was applied"
        },
        "redacted_fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "JSON paths of redacted fields"
        },
        "original_digest": {
          "$ref": "#/definitions/Digest"
        },
        "redaction_timestamp": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "RetentionPolicy": {
      "type": "object",
      "description": "Retention policy for evidence artifact",
      "properties": {
        "policy_id": {
          "type": "string"
        },
        "retention_days": {
          "type": "integer",
          "minimum": 1
        },
        "legal_hold": {
          "type": "boolean",
          "default": false
        },
        "deletion_scheduled_at": {
          "type": "string",
          "format": "date-time"
        },
        "immutable_until": {
          "type": "string",
          "format": "date-time",
          "description": "Cannot be modified/deleted until this time"
        }
      }
    },
    "EvidenceSnapshot": {
      "type": "object",
      "description": "Point-in-time snapshot of evidence locker state",
      "required": ["snapshot_id", "timestamp", "pointers"],
      "properties": {
        "snapshot_id": {
          "type": "string",
          "format": "uuid"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "snapshot_type": {
          "type": "string",
          "enum": ["full", "incremental", "incident"],
          "default": "incremental"
        },
        "pointers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EvidencePointer"
          }
        },
        "aggregate_digest": {
          "$ref": "#/definitions/Digest"
        },
        "previous_snapshot_id": {
          "type": "string",
          "format": "uuid"
        },
        "statistics": {
          "$ref": "#/definitions/SnapshotStatistics"
        },
        "manifest_uri": {
          "type": "string",
          "format": "uri"
        },
        "attestation": {
          "$ref": "#/definitions/SnapshotAttestation"
        }
      }
    },
    "SnapshotStatistics": {
      "type": "object",
      "description": "Statistics about evidence snapshot",
      "properties": {
        "total_artifacts": {
          "type": "integer",
          "minimum": 0
        },
        "total_size_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "artifacts_by_type": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "new_since_last": {
          "type": "integer"
        },
        "modified_since_last": {
          "type": "integer"
        },
        "deleted_since_last": {
          "type": "integer"
        }
      }
    },
    "SnapshotAttestation": {
      "type": "object",
      "description": "DSSE attestation for snapshot integrity",
      "properties": {
        "attestation_id": {
          "type": "string",
          "format": "uuid"
        },
        "predicate_type": {
          "type": "string",
          "default": "https://stella-ops.org/attestations/evidence-snapshot/v1"
        },
        "signature": {
          "type": "string",
          "description": "Base64-encoded signature"
        },
        "key_id": {
          "type": "string"
        },
        "signed_at": {
          "type": "string",
          "format": "date-time"
        },
        "rekor_log_index": {
          "type": "integer",
          "description": "Rekor transparency log index"
        },
        "rekor_log_id": {
          "type": "string"
        }
      }
    },
    "TimelineEvidenceEntry": {
      "type": "object",
      "description": "Evidence entry in timeline event stream",
      "required": ["entry_id", "event_type", "timestamp", "pointer"],
      "properties": {
        "entry_id": {
          "type": "string",
          "format": "uuid"
        },
        "event_type": {
          "type": "string",
          "enum": [
            "evidence.created",
            "evidence.updated",
            "evidence.accessed",
            "evidence.deleted",
            "evidence.redacted",
            "evidence.exported",
            "evidence.verified",
            "evidence.anchored",
            "snapshot.created",
            "snapshot.verified",
            "incident.started",
            "incident.ended"
          ]
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "pointer": {
          "$ref": "#/definitions/EvidencePointer"
        },
        "actor": {
          "$ref": "#/definitions/Actor"
        },
        "context": {
          "type": "object",
          "properties": {
            "pack_run_id": {
              "type": "string",
              "format": "uuid"
            },
            "scan_id": {
              "type": "string",
              "format": "uuid"
            },
            "job_id": {
              "type": "string",
              "format": "uuid"
            },
            "tenant_id": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "previous_entry_id": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "Actor": {
      "type": "object",
      "description": "Actor who performed the action",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["user", "service", "system", "automation"]
        },
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "tenant_id": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "IncidentModeConfig": {
      "type": "object",
      "description": "Configuration for incident mode evidence capture",
      "required": ["incident_id", "started_at"],
      "properties": {
        "incident_id": {
          "type": "string",
          "format": "uuid"
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        },
        "ended_at": {
          "type": "string",
          "format": "date-time"
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"]
        },
        "capture_mode": {
          "type": "string",
          "enum": ["all", "selective", "enhanced"],
          "default": "enhanced",
          "description": "Level of evidence capture during incident"
        },
        "enhanced_retention_days": {
          "type": "integer",
          "minimum": 1,
          "default": 365,
          "description": "Extended retention for incident evidence"
        },
        "legal_hold": {
          "type": "boolean",
          "default": true
        },
        "snapshot_interval_minutes": {
          "type": "integer",
          "minimum": 1,
          "default": 15,
          "description": "How often to take snapshots during incident"
        },
        "affected_tenants": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "affected_components": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "root_cause_evidence": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Pointer IDs of root cause evidence"
        }
      }
    },
    "EvidenceQuery": {
      "type": "object",
      "description": "Query parameters for evidence retrieval",
      "properties": {
        "artifact_types": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ArtifactType"
          }
        },
        "digest": {
          "$ref": "#/definitions/Digest"
        },
        "tenant_id": {
          "type": "string",
          "format": "uuid"
        },
        "correlation_id": {
          "type": "string",
          "format": "uuid"
        },
        "time_range": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "format": "date-time"
            },
            "to": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "include_redacted": {
          "type": "boolean",
          "default": false
        },
        "include_expired": {
          "type": "boolean",
          "default": false
        },
        "chain_id": {
          "type": "string",
          "format": "uuid"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 100
        },
        "cursor": {
          "type": "string"
        }
      }
    },
    "EvidenceQueryResult": {
      "type": "object",
      "description": "Result of evidence query",
      "required": ["pointers", "total_count"],
      "properties": {
        "pointers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EvidencePointer"
          }
        },
        "total_count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string"
        },
        "query_time_ms": {
          "type": "integer"
        }
      }
    }
  },
  "properties": {
    "evidence": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/EvidencePointer"
      }
    }
  },
  "examples": [
    {
      "evidence": [
        {
          "pointer_id": "550e8400-e29b-41d4-a716-446655440001",
          "artifact_type": "sbom",
          "digest": {
            "algorithm": "sha256",
            "value": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
          },
          "uri": "s3://stellaops-evidence/sbom/2025/12/06/sbom-abc123.json",
          "storage_backend": "evidence",
          "bucket": "stellaops-evidence",
          "key": "sbom/2025/12/06/sbom-abc123.json",
          "size_bytes": 45678,
          "media_type": "application/vnd.cyclonedx+json",
          "compression": "gzip",
          "chain_position": {
            "chain_id": "660e8400-e29b-41d4-a716-446655440002",
            "sequence": 42,
            "merkle_root": "b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567a"
          },
          "provenance": {
            "producer": "stellaops-scanner",
            "producer_version": "2025.10.0",
            "tenant_id": "770e8400-e29b-41d4-a716-446655440003",
            "correlation_id": "880e8400-e29b-41d4-a716-446655440004"
          },
          "retention": {
            "retention_days": 365,
            "legal_hold": false
          },
          "created_at": "2025-12-06T10:00:00Z"
        }
      ]
    }
  ]
}