From a4909d3e0064f982922c8b2a4378ff94e7b01845 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Thu, 10 Sep 2026 01:31:17 +0200
Subject: [PATCH] docs(env): say exactly which object the off-host worker
 deletes

E1. Two halves of one correction. `.env.example` still said backup objects
older than BACKUP_RETENTION_DAYS are pruned, which no code does, so a
self-hoster reading that file alone still expected the worker to keep the
bucket tidy. It now carries the same sentence as the production example.

And that sentence overreached in the other direction: "the worker never
deletes an object" is not true of `_healthcheck/<ts>.bin`, the 1-byte key
the Test-connection button writes and then deletes. The delete swallows
its own failure, so an operator who granted exactly the three documented
actions leaves one orphan per press and is never told. Both files now say
"a BACKUP object", and name the one key and what happens without
DeleteObject on that prefix.
---
 .env.example            | 10 +++++++++-
 .env.production.example |  9 ++++++---
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/.env.example b/.env.example
index 3c02cfbec..31cee47cc 100644
--- a/.env.example
+++ b/.env.example
@@ -207,12 +207,20 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # the backup silently. The backup runs at 02:30 Europe/Berlin via pg-boss cron.
 # Restore with `pnpm tsx scripts/restore-backup.ts <userId> <YYYY-MM-DD>`.
 # See docs/ops/backup-restore.md for the format spec + step-by-step.
+#
+# The worker never deletes a BACKUP object -- its grant is PutObject, GetObject
+# and AbortMultipartUpload -- so BACKUP_RETENTION_DAYS is the number you set
+# the bucket's own lifecycle rule to, not something the worker enforces. The
+# one key it does delete is its own connection test's `_healthcheck/<ts>.bin`,
+# and that delete is best-effort: without DeleteObject on that prefix every
+# Test-connection press leaves one 1-byte orphan behind, silently.
+#
 # BACKUP_S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
 # BACKUP_S3_BUCKET="healthlog-backups"
 # BACKUP_S3_ACCESS_KEY=""
 # BACKUP_S3_SECRET_KEY=""
 # BACKUP_S3_REGION="auto"           # "auto" for Cloudflare R2; real region for AWS S3
-# BACKUP_RETENTION_DAYS="30"        # objects older than this are pruned (best-effort; prefer a bucket lifecycle rule)
+# BACKUP_RETENTION_DAYS="30"        # the number for your bucket lifecycle rule (see above)
 # BACKUP_ENCRYPTION_KEY=""          # 64-hex-char or base64 32-byte; SEPARATE from ENCRYPTION_KEY
 
 
diff --git a/.env.production.example b/.env.production.example
index 4a56a53b6..27486de2b 100644
--- a/.env.production.example
+++ b/.env.production.example
@@ -315,9 +315,12 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # BACKUP_S3_REGION="auto"
 #
 # How long backup objects are meant to live, in days. Default 30, minimum 1.
-# The worker never deletes an object -- its grant is PutObject, GetObject and
-# AbortMultipartUpload -- so this number is what you set the bucket's own
-# lifecycle rule to. See docs/ops/backup-restore.md.
+# The worker never deletes a BACKUP object -- its grant is PutObject, GetObject
+# and AbortMultipartUpload -- so this number is what you set the bucket's own
+# lifecycle rule to. The one key it does delete is its own connection test's
+# `_healthcheck/<ts>.bin`, and that delete is best-effort: without DeleteObject
+# on that prefix every Test-connection press leaves one 1-byte orphan behind,
+# silently. See docs/ops/backup-restore.md.
 # BACKUP_RETENTION_DAYS="30"