STRICT CHECKPOINT CONTRACT

POST /checkpoint (receipt-gated enforcement)

Strict mode means: no proof, no termination. Your workload must own durable checkpoint writes and return a validated receipt (optionally HMAC-signed).

What Voidburn guarantees

Termination is gated behind checkpoint proof (strict mode)
Snapshot evidence happens before terminate
Receipts include checkpoint marker + resumability status
Manual resume semantics (explicit capacity restore)

What your workload must do

Implement POST /checkpoint
Write state to persistent storage (PVC/EFS/EBS)
Return 200 only after durable write + validation probe
Return an HMAC receipt when signature is required

Data safety note (important)

checkpoint_confirmed means recoverable state at checkpoint time.
It does not preserve in-memory work performed after the checkpoint.
To minimize replay, drain intake and flush offsets/state before returning receipt.
Use idempotent handlers so replayed work is safe after resume.

Strict flow (receiver-triggered)

Sentinel -> POST http://voidburn-checkpoint.<workload-ns>.svc.cluster.local:8080/voidburn/trigger
Receiver -> POST <WorkloadCheckpointUrl>
Receiver validates receipt and patches marker configmap

Checkpoint request/response contract

POST /checkpoint
Authorization: Bearer <WorkloadCheckpointSecret>
{
  "reason": "checkpoint_window",
  "windowSeconds": 300,
  "windowId": "<uuid>"
}

200 Response:
{
  "ok": true,
  "validated": true,
  "format": "voidburn-checkpoint/v1",
  "windowId": "<uuid>",
  "timestamp": "<RFC3339>",
  "checkpointPath": "/checkpoints/...",
  "sizeBytes": 123,
  "sha256": "<hex>",
  "sigAlgo": "hmac-sha256",
  "sig": "<hex>"
}

If the receipt is missing/invalid, strict mode blocks termination.

Resume commands

kubectl -n <ns> rollout restart deploy/<name>
# or
kubectl -n <ns> rollout restart statefulset/<name>
# or re-run job