docs(plan): record the blobs_consistency -> chunks_consistency rename
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/<name>/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) <noreply@anthropic.com>
This commit is contained in:
@@ -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/<name>/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** (`<hash>.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
|
||||
|
||||
Reference in New Issue
Block a user