## Re-scoped on 2026-08-27: this item is now the ADR-007 amendment obligation alone This item bundled three npm code gaps with two handbook ADR amendments, and it declared that it "closes when both halves are discharged, and not before". That condition spans two repositories, so no single merge request could ever close it. The three code gaps have moved out. | What it held | Where it is now | | --- | --- | | Gap 1, the repository `Δsize` at npm publish is not first-attach gated | !1997, open. It introduces `NpmFileStore.RepositoryHoldsBlob` and gates the publish emit on it | | Gap 2, the repository `Δsize` never carries packument bytes | https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/939 | | Gap 3, the namespace `Δdedup_size` never carries packument bytes | https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/939 | | The merge-order hazard against !1719 to !1723 | resolved. That stack landed, and work item 939 states its own dependency, which is !1997 | | The implementer caution about ADR-007's decrement clause | copied to work item 939, where an implementer meets it | **What stays here is the obligation that no merge request in this repository can discharge.** Both remaining sections need a merge request against `gitlab-com/content-sites/handbook`, editing `content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/007_database_schema.md`. The `docs/adr/` copy in this repository is a daily mirror of that file, so an edit there discharges nothing. This item now closes when the handbook merge request merges. **The increment half is discharged elsewhere and is not this item's to wait on.** The operator decided that the code moves on that half, and !1997 is that change. Reading the increment half as discharging this item is the failure the paragraph below exists to stop, and the decrement half is what keeps it open. The same decision is recorded on https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/438 and https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/550, which reach the same ADR-007 sentence from their own sides. --- ## The handbook ADR amendment, deferred to this item The project guardrail "Check every change against its governing ADRs" names two artifacts for a change that deviates from an ADR. The first is an escalation, and it is on the record for this deviation. The second is a merge request that amends the ADR in the handbook. The operator decided to defer that merge request to this work item, rather than open it from the step 17 branch. This deferral is the operator's decision, and not an oversight. The amendment reconciles the ADR text with one shipped behavior, in one format, on the decrement half of one sentence. That sentence is ADR-007 line 2103 on handbook `main` on 2026-08-26, and earlier revisions of this item numbered it 2101 and 2092. It reads: `repositories.size_bytes` "increments only when a `sha256` first becomes attached in the repository and decrements when garbage collection hard-deletes the last attachment of that `sha256`". This item records an obligation on each half of that sentence, and the operator decided which side moves in each. The increment half is npm's. The npm publish path emits the full tarball byte count on every publish, with no first-attach gate. Gap 1 in the section "The three gaps" carries the detail. The operator decided that the code moves on this half. The npm publish path gains the first-attach gate, and the ADR-007 increment clause stays as written. The decrement half is Container/OCI's. The OCI manifest `DELETE` and blob `DELETE` decrement `size_bytes` when the client delete commits, rather than when garbage collection hard-deletes the last attachment. Those emit sites landed with step 18 of the S22 plan, in [artifact-registry!1793](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1793). [artifact-registry!1895](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1895) wires the counter sink those sites emit through, so while that merge request is open the sites move no counter, and once it merges they move one at the operation. The section "One caution for the implementer" reaches the same clause from the packument side, and reports that a literal reading of it never decrements at all. The operator decided that the ADR text moves on this half. The handbook amendment carries this half, and the OCI emit sites stay as they are. A different artifact discharges each half. The change that adds the first-attach gate to the npm publish path discharges the increment half, and it lands in this repository. One merge request against `gitlab-com/content-sites/handbook` discharges the decrement half. That merge request edits `content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/007_database_schema.md`. It amends lines 2103 and 2123, the two sentences that the tree departs from. It adds a clarifying clause to line 2072, rather than a reversal. All three numbers are handbook `main` on 2026-08-26. The `docs/adr/` copy in this repository is a daily mirror of that handbook file, so an edit there discharges nothing. This item closes when both halves are discharged, and not before. Adding the npm first-attach gate settles the increment half alone. The decrement half stays open after it, because the OCI delete sites still decrement at the client delete. Two changes can settle the decrement half: an amendment to the ADR text, or a move of the OCI decrement to the garbage-collection path. The operator decided on the amendment, so the OCI decrement stays on the client delete path. Reading either half as discharging this item is the failure this paragraph exists to stop. Handbook merge request https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/20835 also edits the ADR-007 file. On 2026-08-20 its diff carried one hunk, `@@ -2091,9 +2091,16 @@`, and handbook line 2092 held the `repositories.size_bytes` sentence as a context line. While that merge request stays open, an amendment that edits that sentence needs a rebase against its branch. Once that merge request merges, the amendment branch rebases onto the new handbook `main`. That merge request merged on 2026-08-21, so the amendment branch needs no merge order against it. The merged diff carries two hunks. The hunk `@@ -1770,7 +1770,16 @@` adds nine lines above that sentence, so that merge moved the sentence down by nine lines. _This is a bot message 🤖 — /smurfit_ ## A second ADR-007 divergence, on the index inventory ADR-007 states in several places that the hosted container tables carry no `(namespace_id, blob_sha256)` index. Its `container_blobs` bullet says the `(namespace_id, digest)` index serves the content-hash reverse lookup "without a separate `(namespace_id, blob_sha256)` index". Its `container_remote_blobs` bullet says the hosted `container_blobs` table "carries no `blob_sha256` index for this to mirror". Its hash-column paragraph says "the hosted container tables carry no separate `blob_sha256` index". Its `container_manifests` bullet adds that a cross-image manifest-payload lookup "scans the namespace-pruned partition". `index_container_blobs_on_ns_id_blob_sha256` and `index_container_manifests_on_ns_id_blob_sha256` have existed since migrations `20260820224726` and `20260820224727`. Those migrations argue the departure in their own text and reference no amendment, so nothing carried the obligation until this section. `datastore.ContainerBlobFootprintStore` keys both membership arms on `blob_sha256` and states its index rationale from those two indexes, so a reader who checks that comment against ADR-007 finds the ADR describing a schema the tree no longer has. This divergence needs the same kind of artifact the section above names: a merge request against the same handbook file. Whether it rides the merge request that discharges the decrement half is open, and this item does not settle it.