Case created
-> evidence gathered
-> review
-> escalation
-> enforcement action
-> appeal
-> closure
-> retention/archive

Evidence must be collected, validated, protected, traceable, retained,
and accessible only under policy.

Attachment
Blob
File thing
Document row

public final class EvidenceItem {
    private final EvidenceId id;
    private final CaseId caseId;
    private EvidenceStatus status;
    private EvidenceFileRef fileRef;
    private RetentionState retentionState;
    private LegalHold legalHold;
    private long version;

    public void attachUploadedFile(EvidenceFileRef ref) {
        requireStatus(EvidenceStatus.COLLECTING);
        if (!ref.isQuarantined()) {
            throw new IllegalArgumentException("Evidence file must be quarantined first");
        }
        this.fileRef = ref;
    }

    public void acceptFile(ScanDecision scanDecision, FileIntegrity integrity) {
        requireStatus(EvidenceStatus.COLLECTING);

        if (!scanDecision.isClean()) {
            throw new IllegalStateException("Cannot accept non-clean evidence file");
        }

        if (integrity == null || !integrity.isVerified()) {
            throw new IllegalStateException("Verified integrity is required");
        }

        this.status = EvidenceStatus.ACCEPTED;
    }

    public void requestDeletion(RetentionDecision decision) {
        if (!decision.deletable()) {
            throw new RetentionViolationException(decision.reasonCode());
        }
        this.status = EvidenceStatus.DELETION_REQUESTED;
    }

    private void requireStatus(EvidenceStatus expected) {
        if (this.status != expected) {
            throw new IllegalStateException("Expected " + expected + " but was " + status);
        }
    }
}

public enum EvidenceStatus {
    DRAFT,
    COLLECTING,
    UPLOAD_PENDING,
    QUARANTINED,
    SCANNING,
    ACCEPTED,
    REJECTED,
    UNDER_REVIEW,
    LOCKED_BY_CASE,
    ARCHIVED,
    DELETION_REQUESTED,
    DELETED
}

Only ACCEPTED evidence can be used in enforcement action.
Evidence attached to escalated case becomes LOCKED_BY_CASE.
LOCKED_BY_CASE cannot be deleted unless case/retention/legal policy allows.
REJECTED evidence cannot become ACCEPTED without new upload/scan decision.
DELETED is terminal.

public record EvidenceFileRef(
    String fileId,
    String bucket,
    String objectKey,
    String objectVersion,
    String sha256,
    long sizeBytes,
    String detectedContentType,
    EvidenceFileState state
) {
    public boolean isQuarantined() {
        return state == EvidenceFileState.QUARANTINED;
    }
}

public enum EvidenceFileState {
    UPLOADING,
    UPLOADED,
    QUARANTINED,
    SCANNING,
    SCANNED_CLEAN,
    SCANNED_MALICIOUS,
    ACCEPTED,
    REJECTED,
    ARCHIVED,
    DELETED
}

EvidenceItem.ACCEPTED requires EvidenceFileState.ACCEPTED
and verified checksum + clean scan decision.

CREATE TABLE evidence_item (
    evidence_id TEXT PRIMARY KEY,
    case_id TEXT NOT NULL,
    tenant_id TEXT NOT NULL,

    status TEXT NOT NULL,
    evidence_type TEXT NOT NULL,

    file_id TEXT NULL,
    object_bucket TEXT NULL,
    object_key TEXT NULL,
    object_version TEXT NULL,

    original_filename_display TEXT NULL,
    detected_content_type TEXT NULL,
    size_bytes BIGINT NULL,
    sha256 TEXT NULL,

    scan_decision TEXT NULL,
    scan_policy_version TEXT NULL,
    scan_completed_at TIMESTAMPTZ NULL,

    retention_policy_version TEXT NULL,
    retention_until TIMESTAMPTZ NULL,
    legal_hold BOOLEAN NOT NULL DEFAULT FALSE,

    created_by TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    version BIGINT NOT NULL
);

ALTER TABLE evidence_item
ADD CONSTRAINT evidence_status_check
CHECK (status IN (
  'DRAFT',
  'COLLECTING',
  'UPLOAD_PENDING',
  'QUARANTINED',
  'SCANNING',
  'ACCEPTED',
  'REJECTED',
  'UNDER_REVIEW',
  'LOCKED_BY_CASE',
  'ARCHIVED',
  'DELETION_REQUESTED',
  'DELETED'
));

ALTER TABLE evidence_item
ADD CONSTRAINT accepted_requires_integrity
CHECK (
  status <> 'ACCEPTED'
  OR (
    file_id IS NOT NULL
    AND object_key IS NOT NULL
    AND sha256 IS NOT NULL
    AND scan_decision = 'CLEAN'
  )
);

Same scan event for same fileId + scannerRunId processed once.
Late scan result after deletion rejected.
Duplicate clean result does not create duplicate accepted event.

CASE_ESCALATED
CASE_CLOSED
CASE_REOPENED
CASE_LEGAL_HOLD_APPLIED
CASE_LEGAL_HOLD_REMOVED

public record EvidenceRetentionPolicy(
    String policyVersion,
    Duration retainAfterCaseClosure,
    boolean legalHoldOverridesDeletion,
    boolean objectLockRequired
) {}

public RetentionDecision evaluate(EvidenceItem item, CaseSnapshot caseSnapshot) {
    if (item.legalHold().active() || caseSnapshot.legalHoldActive()) {
        return RetentionDecision.notDeletable("LEGAL_HOLD_ACTIVE", policyVersion);
    }

    if (!caseSnapshot.closed()) {
        return RetentionDecision.notDeletable("CASE_NOT_CLOSED", policyVersion);
    }

    Instant retentionUntil = caseSnapshot.closedAt().plus(retainAfterCaseClosure);

    if (Instant.now().isBefore(retentionUntil)) {
        return RetentionDecision.notDeletable("RETENTION_ACTIVE", policyVersion, retentionUntil);
    }

    return RetentionDecision.deletable("RETENTION_EXPIRED", policyVersion);
}

Evidence under active legal hold or retention cannot be physically deleted.

public interface EvidenceAccessPolicy {
    Decision canCreateEvidence(UserContext actor, CaseId caseId);
    Decision canReadMetadata(UserContext actor, EvidenceId evidenceId);
    Decision canDownloadPayload(UserContext actor, EvidenceId evidenceId);
    Decision canRequestDeletion(UserContext actor, EvidenceId evidenceId);
    Decision canApplyLegalHold(UserContext actor, CaseId caseId);
}

EVIDENCE_CREATED
EVIDENCE_UPLOAD_SESSION_CREATED
EVIDENCE_PAYLOAD_RECEIVED
EVIDENCE_CHECKSUM_VERIFIED
EVIDENCE_SCAN_REQUESTED
EVIDENCE_SCAN_COMPLETED
EVIDENCE_FILE_ACCEPTED
EVIDENCE_FILE_REJECTED
EVIDENCE_METADATA_VIEWED
EVIDENCE_DOWNLOAD_GRANTED
EVIDENCE_DOWNLOAD_DENIED
EVIDENCE_LOCKED_BY_CASE
EVIDENCE_LEGAL_HOLD_APPLIED
EVIDENCE_LEGAL_HOLD_REMOVED
EVIDENCE_DELETION_REQUESTED
EVIDENCE_DELETION_BLOCKED
EVIDENCE_DELETED
EVIDENCE_PACKAGE_EXPORTED

{
  "eventType": "EVIDENCE_FILE_ACCEPTED",
  "actorId": "service:evidence-worker",
  "actorType": "SERVICE",
  "resourceType": "EVIDENCE_ITEM",
  "resourceId": "EVD-01JZ",
  "resourceVersion": "sha256:abc...",
  "decision": "SUCCESS",
  "reasonCode": "SCAN_CLEAN",
  "policyVersion": "scan-policy-v5",
  "correlationId": "req-abc",
  "occurredAt": "2026-07-05T10:00:00Z"
}

1. User requests package export for case.
2. Authorization checks export permission.
3. Case/evidence snapshot captured.
4. Files collected by fileId, not arbitrary key.
5. Package manifest generated.
6. Checksums included.
7. Package encrypted if required.
8. Short-lived download grant issued.
9. Audit event emitted.
10. Package expires/archived by policy.

{
  "caseId": "CASE-123",
  "packageId": "PKG-01JZ",
  "generatedAt": "2026-07-05T10:00:00Z",
  "policyVersion": "package-export-v2",
  "files": [
    {
      "evidenceId": "EVD-1",
      "fileId": "FILE-1",
      "sha256": "abc...",
      "sizeBytes": 1000
    }
  ]
}

evidence:
  upload:
    max-size-mb: 500
    presigned-upload-ttl: 5m
    allowed-content-types:
      - application/pdf
      - image/jpeg
      - image/png
      - video/mp4
  scan:
    required: true
    timeout: 60s
    reject-on-timeout: false
  retention:
    default-years-after-case-closure: 7
    legal-hold-enabled: true
  download:
    presigned-download-ttl: 2m
    require-fresh-authz: true

scan.required must be true.
download.presigned-download-ttl <= 5m.
retention.legal-hold-enabled must be true.
upload.max-size-mb <= platform maximum.

evidence_created_total
evidence_upload_session_created_total
evidence_scan_pending_age_seconds
evidence_accepted_total
evidence_rejected_total{reason}
evidence_download_granted_total
evidence_download_denied_total{reason}
evidence_deletion_blocked_total{reason}
evidence_retention_mismatch_total
evidence_legal_hold_active_total
evidence_package_exported_total

accepted evidence without checksum > 0
scan pending p95 > SLO
legal hold deletion blocked spike
metadata-object mismatch > 0
audit outbox oldest age > threshold
evidence package cleanup failures

@RestController
@RequestMapping("/cases/{caseId}/evidence")
public final class EvidenceController {
    private final EvidenceApplicationService evidenceService;

    @PostMapping("/upload-sessions")
    public UploadSessionResponse createUploadSession(
        @PathVariable String caseId,
        @RequestBody CreateEvidenceUploadRequest request,
        Principal principal
    ) {
        return evidenceService.createUploadSession(
            new CaseId(caseId),
            request,
            UserContext.from(principal)
        );
    }

    @PostMapping("/{evidenceId}/download-grants")
    public DownloadGrantResponse createDownloadGrant(
        @PathVariable String caseId,
        @PathVariable String evidenceId,
        Principal principal
    ) {
        return evidenceService.createDownloadGrant(
            new CaseId(caseId),
            new EvidenceId(evidenceId),
            UserContext.from(principal)
        );
    }
}

public final class EvidenceApplicationService {
    private final EvidenceRepository repository;
    private final EvidenceAccessPolicy accessPolicy;
    private final CaseClient caseClient;
    private final ObjectStoragePort storage;
    private final AuditService audit;

    public UploadSessionResponse createUploadSession(
        CaseId caseId,
        CreateEvidenceUploadRequest request,
        UserContext actor
    ) {
        CaseSnapshot caseSnapshot = caseClient.getCase(caseId);

        Decision decision = accessPolicy.canCreateEvidence(actor, caseId);
        if (decision.denied()) {
            audit.record(EvidenceAudit.uploadSessionDenied(actor, caseId, decision));
            throw new AccessDeniedException("Not allowed to attach evidence");
        }

        EvidenceItem item = EvidenceItem.create(caseId, actor.actorId(), request.evidenceType());

        repository.save(item);

        PresignedCapability upload = storage.createPresignedUpload(
            PresignUploadRequest.forEvidence(item.id(), request.expectedSizeBytes())
        );

        audit.record(EvidenceAudit.uploadSessionCreated(actor, item, decision));

        return UploadSessionResponse.from(item, upload);
    }
}

[ ] cannot accept evidence without clean scan
[ ] cannot delete under legal hold
[ ] rejected evidence cannot become accepted
[ ] locked evidence cannot be modified by normal actor

[ ] upload completion verifies object exists
[ ] scan event transitions to accepted
[ ] duplicate scan event idempotent
[ ] download grant requires payload permission
[ ] deletion blocked by retention

[ ] object upload succeeds but DB update fails
[ ] scanner timeout leaves evidence not accepted
[ ] audit sink down persists outbox
[ ] secret missing fails readiness
[ ] invalid config fails startup

[ ] path traversal filename ignored
[ ] content-type spoof detected
[ ] presigned URL not logged
[ ] unauthorized download denied and audited
[ ] metadata access does not imply payload access

ADR-001 Evidence identity and object key strategy
ADR-002 Evidence lifecycle state machine
ADR-003 Direct upload with presigned URL
ADR-004 Scanner and quarantine model
ADR-005 Evidence retention and legal hold
ADR-006 Evidence download grant and authorization
ADR-007 Audit event model for chain of custody
ADR-008 Evidence package export model
ADR-009 Reconciliation strategy
ADR-010 Secret/config delivery

RUNBOOK evidence scan backlog
RUNBOOK upload session stuck
RUNBOOK object metadata mismatch
RUNBOOK unauthorized download investigation
RUNBOOK legal hold deletion blocked
RUNBOOK evidence package export failure
RUNBOOK evidence DB credential rotation
RUNBOOK object storage access denied
RUNBOOK audit outbox backlog