From a7b7045ed2268223af2c20e056e5d7e4f649a844 Mon Sep 17 00:00:00 2001 From: Edouard Vanbelle Date: Sun, 23 Aug 2026 18:35:54 +0200 Subject: [PATCH] docs(plan): record the blobs_consistency -> chunks_consistency rename MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows from the blob/chunk taxonomy already in this section: the job iterates storage.blobs, which post-CDC holds chunks, so it inherits whatever that table ends up called. Two rules attached, because a job name is not an internal identifier — it appears in POST /api/admin/jobs//trigger, in background_runs.job_name, and in whatever dashboards operators built: * Travel with the schema rename, never ahead of it. A job called chunks_consistency iterating a table still called storage.blobs is more confusing than today's mismatch. * Never recycle `blobs_consistency`. Under the corrected taxonomy the manifest job IS the blob-level job, so the freed name looks available — and a name that survives a release while changing meaning silently breaks admin URLs and orphans run history. manifests_consistency is unambiguous either way, so exactly one job gets renamed rather than two swapping. Also records what is explicitly NOT renamed: the `.blob` on-disk suffix, where correcting it to `.chunk` would mean renaming every file in every deployment's blob store — a migration that can fail halfway, for clarity no consumer benefits from since nothing parses the suffix. And file.blob_hash, whose semantics are unchanged. Docs only. Co-Authored-By: Claude Opus 5 (1M context) --- docs/plan/derived-blobs.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/plan/derived-blobs.md b/docs/plan/derived-blobs.md index 2cb6c2cc..149915b9 100644 --- a/docs/plan/derived-blobs.md +++ b/docs/plan/derived-blobs.md @@ -1257,10 +1257,40 @@ Schema rename (deferred, requires migration): - `storage.chunk_manifests` → `storage.blob_manifests` (or keep — arguable) - `BlobStorageBackend` trait → `ChunkStorageBackend` — reads and writes physical chunks, not blobs +- **`blobs_consistency` job → `chunks_consistency`** — it iterates + `storage.blobs`, so it inherits whatever that table is called. -`file.blob_hash` semantics stay — references a Blob via its -manifest OR (for pre-CDC legacy) points directly at a single-chunk -Blob whose hash equals its lone chunk's hash. +### The job rename has two rules of its own + +**Travel with the schema, never ahead of it.** A job named +`chunks_consistency` iterating a table still called `storage.blobs` is +*more* confusing than today's mismatch, not less. + +**Never recycle `blobs_consistency`.** Under the corrected taxonomy the +manifest job *is* the blob-level job, so the freed name looks +available — and reusing it would be the worst outcome available. A job +name that survives a release while changing meaning silently breaks +`POST /api/admin/jobs//trigger` URLs, every historical row in +`background_runs.job_name`, and any dashboard or alert keyed on it. +`manifests_consistency` is unambiguous under either taxonomy; leave it +alone. Net effect: one job renamed, not two swapped. + +Budget for the operational cost either way — job names are not internal +identifiers. A rename orphans past runs unless `background_runs.job_name` +is migrated alongside, and any runbook naming the old one breaks. Worth +an alias period or an explicit release note. + +### Explicitly NOT renamed + +- **The `.blob` on-disk suffix** (`.blob` in `LocalBlobBackend` + and `CachedBlobBackend`). Correcting it to `.chunk` would mean + renaming every file in every deployment's blob store — a migration + whose cost is wildly out of proportion to the clarity gained, and one + that can fail halfway. The suffix is an implementation detail no + consumer parses; leave it. +- **`file.blob_hash`** — semantics stay. It references a Blob via its + manifest OR (for pre-CDC legacy) points directly at a single-chunk + Blob whose hash equals its lone chunk's hash. Scope for this rename: ~23 files touch the SQL, plus a migration for the table rename. Not free. Ship AFTER the tier-2 write-side