Domain retention decision must be explicit before physical deletion happens.

bucket = regulator-prod-evidence
key = evidence/case-123/file-789/payload.pdf
versionId = 3HL4kqtJlcpXrof3vjVBH40Nrjfkd

Evidence FILE-789 version 1:
- uploaded by investigator A
- accepted at 2026-07-05T10:00Z
- sha256 = abc...
- policyVersion = evidence-policy-v4

Evidence FILE-789 version 2:
- uploaded as correction by investigator B
- accepted at 2026-07-06T09:30Z
- sha256 = def...
- reason = original unreadable

Never expose raw storage version as the only domain version.

public record FileVersionRecord(
    String fileId,
    int domainVersion,
    String storageBucket,
    String storageKey,
    String storageVersionId,
    String sha256,
    long sizeBytes,
    FileVersionStatus status,
    String createdBy,
    Instant createdAt,
    String reasonCode
) {}

evidence/case-123/main.pdf

evidence/case-123/file-789/v000001/payload

cas/sha256/ab/cd/abcdef.../payload

CREATE TABLE evidence_file_version (
    file_id           VARCHAR(64) NOT NULL,
    domain_version    INTEGER NOT NULL,
    bucket            VARCHAR(255) NOT NULL,
    object_key        VARCHAR(1024) NOT NULL,
    storage_version_id VARCHAR(255),
    sha256            CHAR(64) NOT NULL,
    size_bytes        BIGINT NOT NULL,
    status            VARCHAR(32) NOT NULL,
    created_by        VARCHAR(128) NOT NULL,
    created_at        TIMESTAMP NOT NULL,
    accepted_at       TIMESTAMP,
    PRIMARY KEY (file_id, domain_version),
    UNIQUE (bucket, object_key)
);

Accepted file version must never change physical payload.

retention class + retention basis + retention start + retention until + hold state + deletion eligibility

public record RetentionPolicySnapshot(
    String policyId,
    String policyVersion,
    String retentionClass,
    Instant retentionStartsAt,
    Instant retainUntil,
    boolean legalHold,
    String legalHoldReason,
    String decidedBy,
    Instant decidedAt
) {}

public interface RetentionPolicyEngine {
    RetentionPolicySnapshot decideRetention(FileContext context);
}

public RetentionPolicySnapshot decideRetention(FileContext context) {
    if (context.isEvidence()) {
        Instant start = context.caseClosedAt()
            .orElse(context.acceptedAt());
        return RetentionPolicySnapshot.of(
            "evidence-retention",
            "v7",
            "REGULATORY_EVIDENCE",
            start,
            start.plus(Duration.ofDays(365 * 7)),
            false,
            null,
            "retention-engine",
            Instant.now()
        );
    }

    if (context.isTemporaryExport()) {
        return RetentionPolicySnapshot.of(
            "temporary-export-retention",
            "v2",
            "TEMPORARY_EXPORT",
            context.createdAt(),
            context.createdAt().plus(Duration.ofDays(7)),
            false,
            null,
            "retention-engine",
            Instant.now()
        );
    }

    throw new IllegalArgumentException("Unknown retention context");
}

This artifact must not be deleted until an authorized actor removes the hold.

public record LegalHold(
    String holdId,
    String fileId,
    Integer domainVersion,
    String reasonCode,
    String description,
    String placedBy,
    Instant placedAt,
    String removedBy,
    Instant removedAt
) {
    public boolean active() {
        return removedAt == null;
    }
}

No file version under active legal hold may be physically deleted,
archived into inaccessible storage, or cryptographically shredded.

Hold A: investigation freeze
Hold B: litigation
Hold C: audit sampling

public boolean deletionAllowed(FileRetentionState state) {
    return state.retainUntil().isBefore(Instant.now())
        && state.activeLegalHolds().isEmpty()
        && state.caseState().allowsEvidenceDeletion();
}

storage.delete(bucket, key);
repository.delete(fileId);

public record RequestFileDeletionCommand(
    String fileId,
    Integer domainVersion,
    String requestedBy,
    String reasonCode,
    String idempotencyKey
) {}

public final class FileDeletionService {
    private final FileRepository repository;
    private final RetentionPolicyService retentionPolicy;
    private final FileAccessPolicy accessPolicy;
    private final AuditLog auditLog;
    private final IdempotencyStore idempotencyStore;

    public DeletionDecision requestDeletion(RequestFileDeletionCommand command) {
        return idempotencyStore.getOrCompute(command.idempotencyKey(), () -> {
            StoredFileVersion file = repository.getVersion(command.fileId(), command.domainVersion());

            if (!accessPolicy.canRequestDeletion(command.requestedBy(), file)) {
                throw new AccessDeniedException("Not allowed to request file deletion");
            }

            RetentionDecision decision = retentionPolicy.evaluateDeletion(file);

            if (!decision.allowed()) {
                repository.markDeleteBlocked(file.id(), decision.reasonCode());
                auditLog.record("FILE_DELETION_BLOCKED", file.id(), command.requestedBy(), decision.reasonCode());
                return DeletionDecision.blocked(decision.reasonCode());
            }

            repository.markPhysicalDeletePending(file.id());
            auditLog.record("FILE_DELETION_APPROVED", file.id(), command.requestedBy(), command.reasonCode());
            return DeletionDecision.approved();
        });
    }
}

/tmp-upload/...
/quarantine/...
/accepted/...
/archive/...
/deleted-tombstone/...

/files/{caseId}/{fileName}

If a file identity has been deleted, its identity must not be reused.

CREATE TABLE file_tombstone (
    file_id VARCHAR(64) PRIMARY KEY,
    deleted_at TIMESTAMP NOT NULL,
    deleted_by VARCHAR(128) NOT NULL,
    reason_code VARCHAR(64) NOT NULL,
    last_known_sha256 CHAR(64),
    last_known_domain_version INTEGER
);

CREATE TABLE file_artifact (
    file_id VARCHAR(64) PRIMARY KEY,
    owner_service VARCHAR(128) NOT NULL,
    owner_domain VARCHAR(128) NOT NULL,
    artifact_type VARCHAR(64) NOT NULL,
    current_version INTEGER NOT NULL,
    lifecycle_status VARCHAR(64) NOT NULL,
    created_by VARCHAR(128) NOT NULL,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    version BIGINT NOT NULL
);

CREATE TABLE file_artifact_version (
    file_id VARCHAR(64) NOT NULL,
    domain_version INTEGER NOT NULL,
    bucket VARCHAR(255) NOT NULL,
    object_key VARCHAR(1024) NOT NULL,
    storage_version_id VARCHAR(255),
    sha256 CHAR(64) NOT NULL,
    size_bytes BIGINT NOT NULL,
    content_type VARCHAR(255) NOT NULL,
    status VARCHAR(64) NOT NULL,
    accepted_at TIMESTAMP,
    retention_policy_id VARCHAR(128),
    retention_policy_version VARCHAR(64),
    retention_starts_at TIMESTAMP,
    retain_until TIMESTAMP,
    created_by VARCHAR(128) NOT NULL,
    created_at TIMESTAMP NOT NULL,
    PRIMARY KEY (file_id, domain_version),
    FOREIGN KEY (file_id) REFERENCES file_artifact(file_id)
);

CREATE TABLE file_legal_hold (
    hold_id VARCHAR(64) PRIMARY KEY,
    file_id VARCHAR(64) NOT NULL,
    domain_version INTEGER,
    reason_code VARCHAR(64) NOT NULL,
    description TEXT,
    placed_by VARCHAR(128) NOT NULL,
    placed_at TIMESTAMP NOT NULL,
    removed_by VARCHAR(128),
    removed_at TIMESTAMP,
    FOREIGN KEY (file_id) REFERENCES file_artifact(file_id)
);

ALTER TABLE file_artifact_version
ADD CONSTRAINT retain_until_after_start
CHECK (retain_until IS NULL OR retention_starts_at IS NULL OR retain_until >= retention_starts_at);

ALTER TABLE file_artifact_version
ADD CONSTRAINT accepted_requires_retention_policy
CHECK (
    status <> 'ACCEPTED'
    OR (retention_policy_id IS NOT NULL AND retention_policy_version IS NOT NULL)
);

-- Accepted file without retention decision
SELECT file_id, domain_version
FROM file_artifact_version
WHERE status = 'ACCEPTED'
  AND retention_policy_id IS NULL;

-- Expired retention but active legal hold exists
SELECT v.file_id, v.domain_version
FROM file_artifact_version v
JOIN file_legal_hold h ON h.file_id = v.file_id
WHERE v.retain_until < CURRENT_TIMESTAMP
  AND h.removed_at IS NULL;

-- Delete pending too long
SELECT file_id, lifecycle_status, updated_at
FROM file_artifact
WHERE lifecycle_status = 'PHYSICAL_DELETE_PENDING'
  AND updated_at < CURRENT_TIMESTAMP - INTERVAL '1 hour';

public void reconcileAcceptedFile(FileVersionRecord version) {
    StorageObjectMetadata object = storage.headObject(
        version.storageBucket(),
        version.storageKey(),
        version.storageVersionId()
    );

    if (!version.sha256().equals(object.sha256())) {
        metrics.increment("file_integrity_mismatch_total");
        auditLog.record("FILE_INTEGRITY_MISMATCH", version.fileId(), version.domainVersion());
        incidentPublisher.publishCritical("Accepted file checksum mismatch", version.fileId());
        return;
    }

    RetentionState expected = retentionService.expectedStorageRetention(version);
    RetentionState actual = storage.getRetentionState(version);

    if (!expected.compatibleWith(actual)) {
        metrics.increment("file_retention_drift_total");
        repairQueue.enqueue(version.fileId(), version.domainVersion());
    }
}

GET /files/{fileId}/versions/{version}

{
  "fileId": "FILE-789",
  "version": 2,
  "status": "ACCEPTED",
  "sha256": "...",
  "sizeBytes": 123456,
  "contentType": "application/pdf",
  "createdAt": "2026-07-05T10:00:00Z",
  "acceptedAt": "2026-07-05T10:02:00Z",
  "retention": {
    "policyId": "evidence-retention",
    "policyVersion": "v7",
    "retainUntil": "2033-07-05T10:02:00Z",
    "legalHoldActive": false
  }
}

POST /files/{fileId}/versions/{version}/legal-holds
Content-Type: application/json

{
  "reasonCode": "ACTIVE_INVESTIGATION",
  "description": "Investigation freeze requested by enforcement unit",
  "idempotencyKey": "hold-req-123"
}

{
  "holdId": "HOLD-123",
  "fileId": "FILE-789",
  "version": 2,
  "status": "ACTIVE",
  "placedAt": "2026-07-05T11:00:00Z"
}

POST /files/{fileId}/versions/{version}/deletion-requests

{
  "reasonCode": "RETENTION_EXPIRED",
  "idempotencyKey": "delete-req-456"
}

{
  "decision": "BLOCKED",
  "reasonCode": "ACTIVE_LEGAL_HOLD",
  "activeHoldIds": ["HOLD-123"]
}

{
  "decision": "APPROVED",
  "status": "PHYSICAL_DELETE_PENDING"
}

FILE_VERSION_CREATED
FILE_VERSION_ACCEPTED
FILE_RETENTION_DECIDED
FILE_LEGAL_HOLD_PLACED
FILE_LEGAL_HOLD_REMOVED
FILE_DELETION_REQUESTED
FILE_DELETION_BLOCKED
FILE_PHYSICAL_DELETE_PENDING
FILE_PHYSICAL_DELETED
FILE_RETENTION_DRIFT_DETECTED
FILE_OBJECT_LOCK_APPLIED
FILE_OBJECT_LOCK_FAILED

public record FileGovernanceEvent(
    String eventId,
    String eventType,
    String fileId,
    Integer domainVersion,
    String actorId,
    String reasonCode,
    String policyId,
    String policyVersion,
    String correlationId,
    Instant occurredAt
) {}

1. File accepted in DB.
2. Retention metadata written.
3. Storage object lock call fails.
4. Service returns success.

Accepted retained file must be protected against physical delete.

1. Metadata row removed.
2. Storage delete fails.
3. Object remains without owner.

file_version_created_total
file_version_accepted_total
file_legal_hold_active_total
file_legal_hold_placed_total
file_legal_hold_removed_total
file_deletion_requested_total
file_deletion_blocked_total
file_physical_delete_pending_total
file_retention_drift_total
file_object_lock_apply_failure_total
file_expired_retention_candidate_total
file_tombstone_created_total

Accepted files without retention policy > 0
Object lock apply failures > 0 for 10 minutes
Deletion pending age p95 > threshold
Retention drift detected > 0
Legal hold removal by unusual actor
Lifecycle deleted governed object

@Test
void activeLegalHoldBlocksDeletionEvenAfterRetentionExpires() {
    FileRetentionState state = FileRetentionState.builder()
        .retainUntil(Instant.now().minus(Duration.ofDays(1)))
        .activeLegalHold(new LegalHold("HOLD-1", "FILE-1", 1, "INVESTIGATION", "...", "u1", Instant.now(), null, null))
        .build();

    assertFalse(retentionPolicy.deletionAllowed(state));
}

No silent correction for critical integrity issue.
Critical mismatch creates alert/audit/incident signal.
Safe repair only for known drift classes.