## What this work item asks for The Maven hosted publish path must refuse to commit a `maven_versions` row when the package carries a tombstone. npm already fences the same shape of window. This work item carries that fence to Maven. Every symbol, line number and quotation below was read at `origin/main` = `3bef15683790c3a6c22d1cd2dfb25a32f20504a0`, on 2026-09-03. ## The window A Maven publish resolves both parent rows on the connection pool, before the request body streams. Two statements do that work, in this order: | Statement | Anchor | What it resolves | | --- | --- | --- | | `store.FindOrCreatePackage` | `internal/format/maven/upload.go:141` | the `maven_packages` row | | `store.FindOrCreateVersion` | `internal/format/maven/upload.go:179` | the `maven_versions` row | Both run on `r.Context()`, which binds the pool handle. Neither runs inside the upload's own commit transaction. That transaction opens later, at `internal/format/maven/upload.go:573`. `MavenVersionStore.FindOrCreateVersion` reads no parent column. Its only liveness predicate is the version's own `soft_deleted_at`. A package mark can therefore commit `soft_deleted_at` between the two statements above. The version INSERT then commits a live `maven_versions` row under a tombstoned package. `docs/dev/storage-accounting.md:2342` states the same fact from the reaper's side: > A writer does make that state reachable: `MavenVersionStore.FindOrCreateVersion` runs on the pool before the body streams and reads no parent `soft_deleted_at`, so a publish that resolved the package before the mark can commit a `maven_versions` row after it. ## What the client gets, and what stays behind The client is refused correctly, and no artifact is lost. `upsertFileRow` re-verifies the package inside the commit transaction, at `internal/format/maven/upload.go:695`. The commit then rolls back whole and the upload answers `404`. Three states stay behind: - A childless `maven_versions` row under the tombstone. - One `ErrReapParentPinned` on the package delete. The next chunk's state-blind version page takes the raced-in row, so this clears without operator action. - A `components_count` value that is one low until reconciliation corrects it. The fence buys correctness of shape. It does not buy data safety, because the data is already safe. ## The shape to follow `internal/datastore/npm_packages.go:374-395` is npm's fence for this window, and it is the precedent this work item follows: ```go // LockActiveNpmPackageForPublish takes a SELECT ... FOR UPDATE row lock on the // active npm_packages row for (namespaceID, npmRepositoryID, name), serializing // a publish transaction against a concurrent whole-package unpublish // (NpmPackageUnpublishDeleter). The unpublish deleter documents this lock as the // required closure for the interim publish/unpublish race: without it a publish // can commit a new npm_versions row between the deleter's pre-transaction rev // read and its cascade, leaving an active version orphaned under a soft-deleted // package with permanently skewed artifacts_count / size_bytes counters. // // The commit transaction calls it before any DML. db must be the caller's // *sql.Tx so the lock is held for the whole publish transaction (a *sql.Tx // satisfies qrm.DB). The soft_deleted_at IS NULL predicate targets exactly the // active row the deleter's SoftDeleteNpmPackage takes a row-exclusive lock on, // so the two transactions serialize on it. // // A first-time publication has no active row: the lock matches nothing and the // method returns nil (there is no concurrent unpublish possible for a package // that does not yet exist, and UpsertNpmPackage will insert the row next). A // republish after a concurrent unpublish commits finds the row soft-deleted, // again locks nothing, and UpsertNpmPackage inserts a fresh active row — no // orphan results either way. func (s *NpmPackageStore) LockActiveNpmPackageForPublish( ``` Two parts of that comment transfer to Maven, and one does not. The lock and its placement transfer. The primitive already exists on the Maven side: `MavenPackageStore.ReVerifyPackageAlive` at `internal/datastore/maven_packages.go:197` takes `FOR UPDATE` on the package row and returns `ErrNotFound` when the row is soft-deleted. What is missing is a transaction to hold it across the version INSERT. `FindOrCreateVersion` takes a `qrm.DB`, and the production adapter binds the pool handle to it. The counter reason does not transfer whole. npm's comment names "permanently skewed" counters. The Maven drift is one low `components_count` value, and reconciliation corrects it. ## What the fence costs `internal/datastore/repository_parent_gate.go:172-176` records the cost of this family of lock: > That caller is also the one that can wait here, and nothing bounds the wait: the service sets no lock_timeout and no statement_timeout, so this SELECT blocks for as long as any conflicting writer of the parent row holds it, not only the tombstone. A caller on a request path owes this call a context deadline. The Maven upload derives no deadline of its own. Neither `internal/format/maven/upload.go` nor `internal/format/maven/handler.go` calls `context.WithTimeout` or `context.WithDeadline`. `internal/lifecycle/tombstone.go:57` is the existing bound for such a wait, `TombstoneTimeout = 10 * time.Second`, and its own comment states why it exists: "with no lock_timeout or statement_timeout set, SoftDelete's row-lock wait is otherwise unbounded". Which shape the fence takes is open, and this work item does not choose it. A shape that holds the lock to the upload's commit also serializes concurrent primary-file `PUT`s for one package across the body stream. `docs/specs/S10-maven-hosted.md:858-868` declines that posture for concurrent `PUT`s on one path, so the shape has to answer it. ## What is not covered by a test today No test stages a package mark landing strictly between `internal/format/maven/upload.go:141` and `:179`. This is a property of the test seam rather than a gap in any one suite. The only rendezvous hook in the package is `awaitConflictRendezvous`, called at `internal/format/maven/upload.go:668`. That call is the first statement of `upsertFileRow`, which runs inside the commit transaction, downstream of both pool-side resolves. A test can therefore park an upload inside its commit, and it cannot park one between the two resolves. `internal/format/maven/upload_liveness_race_test.go` holds four tests that use that hook. `TestUpload_PackageMarkedMidCommit_FailsTheCommit` at line 132 asserts the `404`, zero live `maven_files` rows, and zero `blob_storage_attachments` rows. It also asserts the INFO rollback record, which carries the blob digest and the marked package's id. It counts no `maven_versions` rows, so it neither asserts nor excludes the residue row this work item is about. A fence that lands here leaves every one of its assertions true. ## What work item 1044 does instead [#1044](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1044) records the behavior rather than fencing it, and this work item is the fence it defers. While the merge request for #1044 is open, `docs/specs/S20-a-lifecycle-closed-beta.md` carries no package-tier row in its `## Error Cases` section. Once that merge request merges, the section carries a package-tier row beside the repository-tier row at line 1002. That row states the delete-wins outcome as accepted for closed beta, and this work item is what removes it. A fix that lands here therefore rewrites that row rather than only adding code. The same merge request corrects one sentence in `docs/dev/storage-accounting.md`. Line 2188 there ends with "and nothing inserts under a tombstone", as a claim over every arm that pages its ids with a `SELECT`. Line 2342 of the same file contradicts it for `maven_versions`. While the merge request for #1044 is open, both sentences stand. Once it merges, line 2188 no longer denies this window. ## What closing this work item also closes [#535](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/535) asks for the same serialization of the same statement, from the metadata-freshness side. Its first scope bullet reads: > - Take the package `FOR UPDATE` lock (or an equivalent serialization against > `Reconcile`) on the upload path. One half of that bullet is already merged. `internal/format/maven/reconciler.go:671-674` says so: "The upload path does take the package FOR UPDATE lock — upsertFileRow calls ReVerifyPackageAlive before its upsert and holds it to commit, so an upload's maven_files write serializes against this transaction." The other half is what is left, and it is this work item's subject. The same comment names it at `:674-676`: "What is not written under that lock is the maven_versions row: FindOrCreateVersion runs on the pool before the body streams, and it commits its row outside the upload's own transaction." It names the remedy at `:682-684`: "Closing this gap needs the version INSERT serialized against Reconcile — the remedy the restore path needs above — rather than anything this reconciler can do on its own." So a fence that lands here satisfies #535's first scope bullet. Issue #535 carries a third scope bullet that this work item does not carry: a test that interleaves an upload of vN with a reconcile whose reads both predate it. _This is a bot message 🤖 — /smurfit_