Invariant apa yang dijaga?
Invariant apa yang bisa rusak?
Bagaimana kita tahu invariant itu masih benar?

Rule:
User cannot upload file larger than configured max size.

Invariant:
No file in ACCEPTED state may exist without verified size,
verified checksum, storage object reference, and audit event.

Every stored file must have a stable domain identity independent of physical storage key.

fileId = s3://bucket/path/user-upload-2026-07-05.pdf

fileId = FILE-01JZ...
storageKey = evidence/2026/07/05/FILE-01JZ.../payload

A file cannot be promoted to ACCEPTED unless its size, checksum,
content type decision, malware scan result, and metadata record are consistent.

public record FileIntegrity(
    long sizeBytes,
    String sha256,
    String detectedContentType,
    Instant verifiedAt
) {
    public FileIntegrity {
        if (sizeBytes < 0) throw new IllegalArgumentException("sizeBytes must not be negative");
        if (sha256 == null || sha256.length() != 64) {
            throw new IllegalArgumentException("sha256 must be a hex encoded SHA-256 hash");
        }
    }
}

File lifecycle transition must be explicit, monotonic where required,
and auditable.

UPLOADING -> ACCEPTED
REJECTED -> ACCEPTED without new scan decision
DELETED -> ACCEPTED
ACCEPTED -> UPLOADING

public enum FileLifecycleStatus {
    UPLOADING,
    UPLOADED,
    QUARANTINED,
    SCANNED,
    ACCEPTED,
    REJECTED,
    ARCHIVED,
    DELETION_REQUESTED,
    DELETED;

    public boolean canMoveTo(FileLifecycleStatus next) {
        return switch (this) {
            case UPLOADING -> next == UPLOADED;
            case UPLOADED -> next == QUARANTINED;
            case QUARANTINED -> next == SCANNED;
            case SCANNED -> next == ACCEPTED || next == REJECTED;
            case ACCEPTED -> next == ARCHIVED || next == DELETION_REQUESTED;
            case ARCHIVED -> next == DELETION_REQUESTED;
            case REJECTED, DELETION_REQUESTED -> next == DELETED;
            case DELETED -> false;
        };
    }
}

No metadata row may claim a payload is available unless the payload exists
and has passed integrity verification.

1. Create metadata row: UPLOADING
2. Upload payload to temporary object key
3. Verify size/checksum
4. Promote/copy/rename to final key if storage supports safe operation
5. Update metadata: UPLOADED or QUARANTINED
6. Emit audit event
7. Async cleanup temporary object

For every business decision, there must be exactly one authoritative source of truth.

No correctness-critical state may exist only on pod-local filesystem,
heap memory, or container writable layer.

Worker stores upload progress only in /tmp/upload-session.json.
Pod restarts.
Upload cannot resume.
Metadata says upload is still active forever.

Upload progress persisted in DB or object multipart state.
Local temp file is disposable.
Recovery job can reconstruct or expire stale upload session.

Repeating the same command with the same idempotency key must not create
additional committed side effects.

public record RegisterUploadedFileCommand(
    String idempotencyKey,
    String uploadSessionId,
    String fileName,
    long sizeBytes,
    String sha256
) {}

public StoredFile registerUploadedFile(RegisterUploadedFileCommand command) {
    return idempotencyStore.getOrCompute(
        command.idempotencyKey(),
        () -> doRegisterUploadedFile(command)
    );
}

Replaying events or repair jobs must converge to the same valid state
or stop with explicit conflict.

A service must fail startup if required configuration is missing,
malformed, unsafe, or internally inconsistent.

@ConfigurationProperties(prefix = "storage.evidence")
@Validated
public record EvidenceStorageProperties(
    @NotBlank String bucket,
    @NotBlank String region,
    @NotBlank String quarantinePrefix,
    @NotBlank String acceptedPrefix,
    @Min(1) long maxObjectSizeMb,
    @NotNull Duration requestTimeout
) {
    public EvidenceStorageProperties {
        if (quarantinePrefix.equals(acceptedPrefix)) {
            throw new IllegalArgumentException(
                "quarantinePrefix and acceptedPrefix must be different"
            );
        }
    }
}

Service must never start with quarantine and accepted prefix pointing
to the same location.

If config is absent, default must be safe, not convenient.

Only configuration designed for runtime reload may be changed without restart.

Every production config value must have provenance:
source, version, actor, approval, and deployment timestamp.

Loaded config profile=prod
Config source=gitops/config/evidence-service/prod
Config version=8d21a9f
Config schema version=3
Sensitive values redacted

Secret value must never appear in application logs, metrics, traces,
error response, audit payload, config dump, heap dump policy output,
or actuator endpoint.

public final class RedactedSecret {
    private final String value;

    private RedactedSecret(String value) {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Secret is required");
        }
        this.value = value;
    }

    public static RedactedSecret of(String value) {
        return new RedactedSecret(value);
    }

    public String revealForUse() {
        return value;
    }

    @Override
    public String toString() {
        return "[REDACTED]";
    }
}

A service must not assume a leased or dynamic secret remains valid
beyond its TTL.

Secret rotation must not require global downtime.

1. Create new credential/version
2. Allow old and new credential during overlap window
3. Update consumer configuration or secret source
4. Refresh consumer connections gradually
5. Observe successful use of new credential
6. Revoke old credential
7. Alert if old credential still used

Secret must grant only the capability required by the consuming service.

evidence-service gets admin database credential.

evidence-service gets role-scoped credential:
- read/write only evidence schema
- no superuser
- no unrelated database
- short TTL if dynamic
- auditable issuance

Every critical lifecycle transition must emit an audit or operational event.

FILE_UPLOADED
FILE_CHECKSUM_VERIFIED
FILE_QUARANTINED
FILE_SCAN_COMPLETED
FILE_ACCEPTED
FILE_REJECTED
FILE_ARCHIVED
FILE_DELETION_REQUESTED
FILE_DELETED

file_upload_started_total
file_upload_failed_total
file_upload_orphan_object_total
file_metadata_payload_mismatch_total
file_scan_pending_age_seconds
config_validation_failure_total
config_reload_failure_total
secret_refresh_success_total
secret_refresh_failure_total
secret_seconds_until_expiry
state_replay_conflict_total
cache_stale_read_total

Invariant mana yang sedang mendekati batas?

CPU > 90%

Accepted file without verified checksum > 0
Secret expires in < 10 minutes and refresh failed
Config reload failed on > 20% pods
Upload sessions stuck in UPLOADING for > 1 hour
Object exists without metadata for > 24 hours

For every material decision, the system must be able to explain:
who did what, to which artifact, when, from where, under which policy,
and with what result.

public record AuditEvent(
    String eventId,
    String eventType,
    String artifactType,
    String artifactId,
    String actorId,
    String actorType,
    String decision,
    String reasonCode,
    String policyVersion,
    String correlationId,
    Instant occurredAt
) {}

Data under active retention or legal hold must not be physically deleted.

Evidence artifact must be tamper-evident after acceptance.

if (file.getStatus().equals("SCANNED")) {
    file.setStatus("ACCEPTED");
}

public final class EvidenceFile {
    private final FileId id;
    private FileLifecycleStatus status;
    private FileIntegrity integrity;

    public void accept(FileIntegrity verifiedIntegrity) {
        if (status != FileLifecycleStatus.SCANNED) {
            throw new IllegalStateException("Only SCANNED file can be accepted");
        }
        if (verifiedIntegrity == null) {
            throw new IllegalArgumentException("Verified integrity is required");
        }
        this.integrity = verifiedIntegrity;
        this.status = FileLifecycleStatus.ACCEPTED;
    }
}

@Component
public final class StartupInvariantChecker implements ApplicationRunner {
    private final EvidenceStorageProperties properties;

    public StartupInvariantChecker(EvidenceStorageProperties properties) {
        this.properties = properties;
    }

    @Override
    public void run(ApplicationArguments args) {
        if (properties.quarantinePrefix().equals(properties.acceptedPrefix())) {
            throw new IllegalStateException(
                "Invalid storage config: quarantine and accepted prefix must differ"
            );
        }
    }
}

ALTER TABLE evidence_file
ADD CONSTRAINT evidence_file_status_check
CHECK (status IN (
  'UPLOADING',
  'UPLOADED',
  'QUARANTINED',
  'SCANNED',
  'ACCEPTED',
  'REJECTED',
  'ARCHIVED',
  'DELETION_REQUESTED',
  'DELETED'
));

ALTER TABLE evidence_file
ADD CONSTRAINT evidence_file_checksum_required_when_accepted
CHECK (
  status <> 'ACCEPTED'
  OR sha256 IS NOT NULL
);

Reconciliation job:
- find metadata UPLOADING older than threshold
- check object storage temporary keys
- expire stale sessions
- delete orphan temp objects
- emit audit event
- report mismatch metrics

public void reconcileStaleUploads() {
    List<StoredFile> stale = repository.findStaleUploadingFiles(Duration.ofHours(1));

    for (StoredFile file : stale) {
        try {
            storage.deleteTemporaryObjectIfExists(file.storageKey());
            repository.markRejected(file.fileId(), "UPLOAD_EXPIRED");
            metrics.increment("file_upload_expired_total");
        } catch (Exception ex) {
            metrics.increment("file_upload_reconciliation_failed_total");
            log.warn("Failed to reconcile stale upload fileId={}", file.fileId(), ex);
        }
    }
}

@Test
void acceptedFileRequiresScannedStateAndVerifiedIntegrity() {
    EvidenceFile file = EvidenceFile.uploaded(new FileId("FILE-1"));

    assertThrows(IllegalStateException.class, () ->
        file.accept(new FileIntegrity(10, validSha256(), "application/pdf", Instant.now()))
    );
}

Given metadata row created
When object upload fails
Then file status remains UPLOADING or REJECTED
And no ACCEPTED file exists
And cleanup job can remove temp object

Invariant preserved or violation detected and recoverable.

## Invariant Review

### Artifact
- Type:
- Owner:
- Source of truth:

### Identity
- Stable ID:
- Physical location:
- Migration impact:

### Lifecycle
- States:
- Allowed transitions:
- Terminal states:

### Integrity
- Checksum:
- Version:
- Tamper evidence:

### Idempotency
- Idempotency key:
- Duplicate behavior:
- Retry boundary:

### Durability
- Commit point:
- Partial failure recovery:
- Reconciliation job:

### Security
- Access policy:
- Secret exposure risk:
- Least privilege boundary:

### Configuration
- Required config:
- Runtime reload:
- Safe default:
- Provenance:

### Observability
- Audit events:
- Metrics:
- Alerts:
- Runbook:

### Compliance
- Retention:
- Legal hold:
- Audit evidence: