feat(lifecycle): sweep periodic worker and composition-root registration (S20-A plan: 16/21)

What this step delivers

The tombstone sweep runs on a booted pod, and the composition root registers both lifecycle job kinds. This is the merge request after which a tombstone on a running server is reaped rather than only recorded.

internal/lifecycle/sweep.go adds the periodic worker. One tick enumerates every namespace by keyset page, and probes each namespace at both purge scopes. It enqueues one purge job for each namespace and scope that still holds an eligible tombstone. The enqueue carries content-based uniqueness, narrowed to the states in which a job is still pending or in flight. A namespace therefore holds at most two live purge jobs, one at repository scope and one at artifact scope. The per-run budget of a tick is the configured sweep_interval.

internal/lifecycle/register.go adds RegisterPeriodicJobs, the registration seam for both kinds. cmd/artifact-registry/wire_lifecycle.go adds the composition-root tier that calls it. The tier takes the pool and the lifecycle section as concrete values, and it refuses an unusable set at boot. It asserts the field count of PurgeWorkerDeps, the two fields it sets, and the three it leaves unset. A new field therefore fails the build instead of arriving unset at runtime.

SweepWorker.probeScope stops at the first level that answers a tombstone for a namespace and scope. The spec describes the walk as running each level's scan once per namespace, at docs/specs/S20-a-lifecycle-closed-beta.md:252. One hit is all the scope needs, because the enqueue is addressed by the namespace and the scope and covers every level of it. The short circuit therefore enqueues an identical set of jobs at a strictly lower query cost.

Four things are visible on a running pod:

• The boot line that names the registered job kinds gains lifecycle:purge and lifecycle:tombstone-sweep.
• Every boot logs one WARN about the zero retention window, because zero is the shipped default.
• Every tick logs what it covered, and there are four such lines. lifecycle sweep tick walked the fleet at INFO when it reached the end of the keyset. lifecycle sweep tick ran past its budget at WARN when it did not. lifecycle sweep tick interrupted by a shutdown at INFO on a drain. lifecycle sweep tick lost the namespace enumeration at WARN when the enumeration query failed.
• river_job gains rows of both kinds on a database that holds tombstones.

cmd/artifact-registry/main.go adds the startup breadcrumb that emits the retention-window lines.

An over-budget tick is terminal. SweepWorker.Work classifies the tick's result through mapSweepTickResult, added by commit d5ae8ec8f. A tick that runs out of sweep_interval returns river.JobCancel. It therefore does not occupy a slot of the shared default queue with retries that re-walk the same prefix. Every attempt carries the same budget and starts the same walk from the start of the keyset. A retry therefore stops in the same place. Every other failure keeps River's ladder, a shutdown included. The classification reads the tick's own context rather than the error chain, and that choice is deliberate. A statement timeout inside a probe also surfaces as context.DeadlineExceeded, and a test over the error chain would make a transient database fault terminal.

The sizing rule for sweep_interval. The interval is also one tick's wall-clock budget, so it must exceed the time one tick needs to walk every namespace. Commit 4200e9c85 states that rule on all three configuration surfaces: proto/artifactregistry/config/v1/config.proto, config.example.yaml, and docs/dev/configuration-reference.md. Each one names gitlab_artifact_registry_jobs_duration_seconds{kind="lifecycle:tombstone-sweep"} as the measurement. None of them gives a threshold. The per-namespace probe cost is not measured, and the fleet size is not in this repository. A figure here would be one no reader can check.

Both lifecycle knobs now have a reader, and sweep_interval had none before this change. These surfaces stated the old state, and this change corrects each one:

• internal/config/lifecycle.go — the LifecycleConfig doc comment and the comment on errLifecycleSweepIntervalTooLong.
• proto/artifactregistry/config/v1/config.proto — the LifecycleConfig message comment and both field comments.
• config.example.yaml — the comment on the lifecycle: block.
• docs/dev/configuration-reference.md — the lifecycle section.
• internal/lifecycle/purge.go and internal/lifecycle/chunk.go — the comments that described the sweep as future work.

docs/dev/background-jobs.md adds internal/lifecycle as a periodic registrant. .claude/skills/run-artifact-registry/SKILL.md moves with the boot change, and driver.sh smoke passed against it.

Why a feat(lifecycle): merge request carries an edit under .claude/skills/. AGENTS.md guardrail 21 puts the run recipe in the same merge request as the change to how the service boots. This step's merged plan says the same at docs/plans/2026-08-11-s20a-lifecycle-closed-beta.md:807, and repeats it for steps 16 and 18 at :986. The two recipe edits ride chore(skills): commits, which is the per-path prefix docs/dev/conventions.md asks for. The merge request title takes the type of the feature the rest of the diff delivers. The wording in docs/dev/conventions.md is the subject of a separate documents change, and this merge request does not make it.

Spec coverage

Spec: docs/specs/S20-a-lifecycle-closed-beta.md

The criteria below carry the namespace-and-scope unit. The section Where the corrected criteria come from names the code that unit was measured against.

#	Acceptance criterion	Test
1	A tombstoned repository with no live purge job is re-queued within one sweep_interval, verified with an injectable tick, and a namespace and scope that already have a live purge job are not re-queued at that scope.	TestSweepWorker_Work_RequeuesATombstonedRepositoryWithNoLivePurgeJob, TestSweepWorker_Work_DoesNotRequeueANamespaceAndScopeWithALiveJob
2	A second eligible tombstone in the same namespace and scope earns no second job, and one at the other scope earns a job of its own — two live purge jobs per namespace is the ceiling, not one.	TestSweepWorker_Work_ASecondTombstoneEarnsNoJobAndTheOtherScopeEarnsItsOwn
3	A namespace still holding an eligible tombstone, whose prior purge job at that scope reached a terminal state, is re-queued at that scope by the next tick — the assertion that pins the uniqueness scope to UniqueByArgsWhileLive().	TestSweepWorker_Work_RequeuesAfterThePriorJobReachedATerminalState
4	Each namespace's tombstones are read oldest-first, verified by seeding more eligible tombstones than one page holds, in interleaved write order.	TestSweepWorker_Work_ProbesANamespacesOldestTombstoneFirst
5	A tombstoned npm_packages row whose versions are all reaped is enumerated and re-queued.	TestSweepWorker_Work_RequeuesAnOrphanedTombstonedNpmPackage
6	A registration that omits RegisterWorker fails Start with ErrPeriodicKindNoWorker, asserted so the composition root cannot regress into a boot abort.	TestRegisterPeriodicJobs_Integration_APeriodicKindWithNoWorkerFailsStart, with the positive half in TestRegisterPeriodicJobs_Integration_RegistersBothKindsAndTheSweepSchedule
7	An enumeration failure returns an error and loses nothing.	TestSweepWorker_Work_AnEnumerationFailureFailsTheTickAndLosesNothing
8	A namespace that does not serve writes has none of its eligible tombstones enqueued, and the same namespace is re-queued on the first tick after the condition clears, verified alongside a serviceable namespace whose tombstone the same tick does re-queue.	TestSweepWorker_Work_SkipsANamespaceThatDoesNotServeWritesUntilItClears
9	driver.sh smoke passes against the recipe as updated.	Run and passed: 48 passed, 0 failed. Plus a hand-driven end-to-end reap; see section 4's evidence.

Evidence for criterion 9, from a driver rig on this branch. driver.sh smoke was re-run at 6cc6dac26, after every review fix landed, and it reported 48 passed and 0 failed. It was run again after the coverage-line fix in 018bf9da9, with the same 48 passed and 0 failed. The commits after that one change Markdown, Go comment text, and Go test files. No executable line of production code changed in any of them, so none of them moves this figure. The rig then marked one repository with soft_deleted_at, and one sweep_interval later river_job held both rows:

           kind            |   state   |                                 args
---------------------------+-----------+----------------------------------------------------------------------
 lifecycle:tombstone-sweep | completed | {}
 lifecycle:purge           | completed | {"scope": 1, "namespace_id": "ffb20c1f-e79b-4fef-80b3-26f979989701"}

select count(*) from repositories where name = 'npm-repo' returned 0 after that purge, so the job the sweep enqueued reaped the tombstoned repository.

The same run confirmed the run recipe's lifecycle section against a booted rig rather than by reading the code:

• Both job kinds appear in the boot line.
• Ticks arrive exactly 300s apart.
• The lifecycle sweep tick walked the fleet INFO line carries all four counter names verbatim.
• An idle rig holds purge_jobs_enqueued at 0.
• A soft-deleted row produces a purge job within one interval.
• The river_job query in the recipe works as written.

What the rig did not exercise. The rig did not reach the river.JobCancel classification that d5ae8ec8f adds. A one-namespace fleet finishes its walk at once, so no tick came near its budget. Every river_job row was completed at attempt 1, with no cancelled row and no retryable one. The three tests named in the interval-overrun error-case row are the evidence for that path, and the rig is not a second source for it.

Wiring guard obligation:

Obligation	Test
The tier takes the pool and the lifecycle configuration as concrete values and refuses an unusable one at boot, on newChunkWorkerDeps' shape.	TestNewPurgeWorkerDeps_PanicsOnAnUnusableDependencySet
A zero retention_window is not one of those refusals; it keeps the startup WARN.	TestNewPurgeWorkerDeps_AZeroRetentionWindowIsNotARefusal, TestLogLifecycle
The tier leaves Namespaces, Levels and ChunkSize unset and takes NewPurgeWorker's defaults.	TestNewPurgeWorkerDeps_WiresEverySeam
A field-count assertion over PurgeWorkerDeps plus one assertion per field the tier sets, on TestNewChunkWorkerDeps_WiresEverySeam's shape rather than a reflection walk.	TestNewPurgeWorkerDeps_WiresEverySeam

Error cases from the spec:

Error case	Test
Sweep: enumeration query fails. The tick returns an error and River retries under its backoff. Nothing is lost.	TestSweepWorker_Work_AnEnumerationFailureFailsTheTickAndLosesNothing
Sweep: interval elapses before enumeration completes. The tick ends at its budget and River cancels it rather than retrying it. It keeps every purge job it already enqueued, and it does not resume. The next tick re-enumerates from the start of the keyset, so the namespaces behind the stopping point are reached only by a tick that gets further. Full coverage is a sizing property of sweep_interval rather than a property of the walk.	TestSweepWorker_Work_ATickThatRanOutItsBudgetIsCancelledRatherThanRetried, TestSweepWorker_Work_AProbesOwnDeadlineIsNotTheTicksBudget, TestSweepWorker_Timeout_IsTheConfiguredSweepInterval

Security considerations from the spec:

Consideration	Test
No purger input is user-controlled: the sweep enumerates by column predicate and the purge job carries UUID identifiers, so no format-layer identifier, name or digest reaches a query as text.	Structural rather than asserted. SweepArgs is an empty struct and PurgeArgs carries two typed values; the whole suite drives the tick with no caller-supplied string.
A frozen namespace is not reaped: no write applies while the platform holds the namespace.	TestSweepWorker_Work_SkipsANamespaceThatDoesNotServeWritesUntilItClears
A purge that fails permanently stays re-queued at the bounded once-per-interval cadence and is never silently abandoned.	Covered at the sweep's half by criterion 3's test; the purge-side half is the purge worker's own suite from step 15.

One note on the tables above. test-author produced them before the review pass, and the review pass then added the tests that close the rows which had none.

• internal/lifecycle/sweep_test.go and internal/lifecycle/sweep_internal_test.go are new files. The sweep shipped with no unit suite at all, while its mirror PurgeWorker carries purge_test.go and purge_internal_test.go. Guardrail 6's dropped-subtest diff is what surfaced that, and two of the defects this branch fixed were among the dropped subtests.
• internal/lifecycle/purge_internal_test.go gains TestCheckPurgeLevels_RefusesALevelWithNoName, because PurgeLevel.Name doubles as the sweep's no-hit sentinel.
• internal/lifecycle/register_internal_test.go is a new file carrying TestNewSweepWorkerDeps_WiresEverySeam, which asserts the sweep's own six-field derivation beside the purge tier's five-field one.

How this branch was authored

One author wrote both the tests and the implementation. /implement-step's test-author subagent failed in this environment, so this branch lost the split that keeps test authorship separate from implementation authorship. That author wrote internal/lifecycle/sweep.go, internal/lifecycle/register.go and cmd/artifact-registry/wire_lifecycle.go in full before the test(...) commit existed. The branch is squashed, so the commit order no longer shows this, and that is why the description states it.

The table below maps each test to what it asserts, and flags the rows that are shape-driven rather than criterion-driven. A row that reads "Amended criterion N" names criterion N of the Spec coverage table above.

Test	What it asserts, and where that comes from	Shape-driven?
TestSweepWorker_Work_RequeuesATombstonedRepositoryWithNoLivePurgeJob	Amended criterion 1's first half, and the spec's "enqueuing one purge job per namespace and scope wherever a scan found anything".	No
TestSweepWorker_Work_DoesNotRequeueANamespaceAndScopeWithALiveJob	Amended criterion 1's second half, and spec criterion "A namespace and scope that already have a live purge job are not re-queued at that scope".	No
TestSweepWorker_Work_ASecondTombstoneEarnsNoJobAndTheOtherScopeEarnsItsOwn	Amended criterion 2 in full, and the PurgeEnqueueOptions doc's "a namespace carries at most two live purge jobs".	No
TestSweepWorker_Work_RequeuesAfterThePriorJobReachedATerminalState	Amended criterion 3, and the spec's argument for UniqueByArgsWhileLive() over UniqueByArgs().	No
TestSweepWorker_Work_ProbesANamespacesOldestTombstoneFirst	Amended criterion 4 and the spec's "Within a namespace the scan reads the oldest tombstone first".	Partly. See below.
TestSweepWorker_Work_RequeuesAnOrphanedTombstonedNpmPackage	Amended criterion 5 and the spec's npm_packages scan-level argument.	No
TestSweepWorker_Work_AnEnumerationFailureFailsTheTickAndLosesNothing	Amended criterion 7 and the spec's "Sweep: enumeration query fails" error case.	Partly. See below.
TestSweepWorker_Work_SkipsANamespaceThatDoesNotServeWritesUntilItClears	Amended criterion 8 and the spec's "A frozen namespace is not reaped" table row for the sweep.	No
TestRegisterPeriodicJobs_Integration_RegistersBothKindsAndTheSweepSchedule	The spec's "the sweep's registration is two calls" and the plan's RegisterPeriodicJobs entry.	No
TestRegisterPeriodicJobs_Integration_APeriodicKindWithNoWorkerFailsStart	Amended criterion 6.	No
TestWireLifecycle_ContributesBothJobRegistrations	The plan's wire_lifecycle.go / wire.go entry, on TestWireRemote_ContributesHealthSweepRegistration's shape.	No
TestNewPurgeWorkerDeps_WiresEverySeam	The wiring-guard bullet's field-count-plus-per-field obligation, verbatim.	No
TestNewPurgeWorkerDeps_PanicsOnAnUnusableDependencySet	The wiring-guard bullet's "refuses an unusable one at boot".	Partly. See below.
TestNewPurgeWorkerDeps_AZeroRetentionWindowIsNotARefusal	The wiring-guard bullet's explicit carve-out for a zero window.	No
TestLogLifecycle	The plan's main.go / internal/config/lifecycle.go entry: WARN on a zero window, INFO when configured.	No
TestLogLifecycle_AConfiguredSectionNamesBothKnobs	The same entry's "logs its effective values".	No
TestLogLifecycle_TheSilentArmIsUnreachableWhileTheWindowDefaultsToZero	The plan's own sentence that the silence case is unreachable while the default is 0s.	Yes, and deliberately. See below.
TestLifecycle_IsDefault, TestLifecycle_IsDefaultAgreesWithTheLoader	The plan's LifecycleConfig.IsDefault entry.	No
TestWireLifecycle_ContributesUnderTheDatabaselessUnitStub	No criterion. It mirrors wireAccounting's documented contribution contract.	Yes. See below.
TestWireLifecycle_ContributedClosuresRegisterOnceAcrossEveryEntry	No criterion. It exists because the implementation contributes two entries and therefore needs a sync.Once.	Yes. See below.
TestSweepWorker_probeScope_StopsAtTheFirstLevelThatAnswers	No criterion. It pins the short circuit What this step delivers states.	Yes. See below.
TestSweepWorker_Work_ReportsTheJobsItEnqueuedAndNotTheOnesItDeduplicated	No criterion. It pins purge_jobs_enqueued and enqueuePurge's Duplicate early return.	Yes. See below.

The flagged rows, stated plainly:

1. TestWireLifecycle_ContributedClosuresRegisterOnceAcrossEveryEntry is shape-driven. No acceptance criterion asks for it. The implementation contributes one registration entry per kind, which is what makes a sync.Once necessary. The author kept it because the failure it prevents is silent: a sweep on two schedules ticks at twice its cadence, with every tick still correct. wireAccounting carries the same guard and the same test, for the same reason. If a reviewer prefers the single-entry design, this test goes with it.
2. TestWireLifecycle_ContributesUnderTheDatabaselessUnitStub is shape-driven. It asserts that the tier appends its entries even with a nil pool. That is a property of the closure rather than a criterion of this step. Same precedent as above.
3. TestLogLifecycle_TheSilentArmIsUnreachableWhileTheWindowDefaultsToZero documents dead code, and it is a finding rather than coverage. logLifecycle has three arms, and one of them cannot fire: a section with a non-zero retention window is never IsDefault(), and a section with a zero one takes the WARN before the predicate is consulted. The IsDefault() call inside logLifecycle therefore decides nothing today. The merged plan predicts this at docs/plans/2026-08-11-s20a-lifecycle-closed-beta.md:805 and says what the method is for: "IsDefault gates the breadcrumb for the GA default rather than for any closed-beta configuration, and the WARN fires on every closed-beta pod." The test fails as soon as the default window moves, which is the moment the arm becomes live.
4. The three "partly" rows are narrower. TestSweepWorker_Work_ProbesANamespacesOldestTombstoneFirst observes the probe through an injected PurgeLevel whose Scan the case wraps, so it sees only what a level-based dispatch exposes. TestSweepWorker_Work_AnEnumerationFailureFailsTheTickAndLosesNothing injects a failing SweepNamespaceLister, and the spec asks for the behavior rather than for that seam. TestNewPurgeWorkerDeps_PanicsOnAnUnusableDependencySet asserts that the panic string names newPurgeWorkerDeps, which is a property of the message rather than of a criterion.
5. The two cases the branch's last three commits added are shape-driven too, and both pin a property this description states rather than a criterion. TestSweepWorker_probeScope_StopsAtTheFirstLevelThatAnswers reads the scan call counts of the levels behind the hit. The returned level name is the same with the short circuit removed, so those counts are the only witness there is. TestSweepWorker_Work_ReportsTheJobsItEnqueuedAndNotTheOnesItDeduplicated reads purge_jobs_enqueued on a tick that inserts two jobs, and on a second tick over the same fixture that inserts none. That counter was asserted only as a zero before, so the increment and enqueuePurge's Duplicate early return both survived deletion. enqueuePurge's error arm is covered by TestSweepWorker_Work_AnEnqueueFailureIsCollectedAndTheOtherScopeStillRuns, added in the review round: it builds a client through jobsriver.New over a connector that never dials and registers no purge worker, so the enqueue is refused inside prepare before any backend contact.

An independent validation pass read all four against the criteria and the code. It found that none of the four restates the implementation. Three of them assert coverage that no other case in their file provides. On the dead-code row it agrees with the author and adds one fact. The merged plan predicts the unreachable arm at line 805, and it states what LifecycleConfig.IsDefault is for. The arm is therefore a documented decision rather than an oversight.

e2e scenario catalogs

This step turns on background reaping and changes no request path. The merged plan asks it to confirm two updated scenarios rather than add one, at docs/plans/2026-08-11-s20a-lifecycle-closed-beta.md:982. Both are confirmed present on origin/main, and this merge request changes neither:

• e2e.docker.setup.delete-repository, in docs/testing/e2e/docker.md.
• e2e.oci.setup.delete-repository, in docs/testing/e2e/oci.md.

Step 18 owns their update for the destructive DELETE.

The six fix(lifecycle) commits on this branch affect no scenario either. A background job's retry classification is not reachable through an e2e scenario, because docs/testing/ drives the service through its request routes. What mapSweepTickResult changes is what River does with a tick's returned error, and no route observes that. docs/testing/ also carries no sweep-cadence scenario, so the sizing rule reaches no row. Two rows name the purger and neither changes: e2e.npm.lifecycle.version-cap-survives-unpublish in docs/testing/e2e/npm.md, and e2e.maven.lifecycle.soft-delete-invisible in docs/testing/e2e/maven.md.

One sentence in the plan's own e2e paragraph is out of date about the npm and Maven catalogs. docs/testing/e2e/maven.md and docs/testing/e2e/npm.md both exist, so that sentence is not the ground for anything here. Guardrail 4 keeps a step merge request out of the plan file, and !1840 (merged) already carries the correction on its branch.

Diff size

25 files, 4340 insertions and 99 deletions, measured at 63c4426f8 against this merge request's base 9addc98ac. Excluding the generated config.pb.go, that is 4312 reviewable insertions, past the 500-line threshold in docs/dev/development-model.md. The figures grew by 331 insertions in the review round: two new test cases, one new integration test file, and comment corrections across seven files. The split by file group:

Group	Insertions	Deletions	Files, insertions unless a second number states deletions
Tests	2913	8	sweep_integration_test.go 877, sweep_test.go 861, sweep_internal_test.go 356, wire_lifecycle_test.go 303, wiring_test.go 137, wire_lifecycle_integration_test.go 132, register_internal_test.go 108, purge_internal_test.go 69, internal/config/lifecycle_test.go 63/2, wire_accounting_integration_test.go 7/6
Production Go	1231	38	sweep.go 805, wire_lifecycle.go 158, register.go 120, main.go 48, internal/config/lifecycle.go 45/23, purge.go 45/13, wire.go 8, chunk.go 2/2
Docs and run recipe	118	5	run-artifact-registry/SKILL.md 79, background-jobs.md 29/1, configuration-reference.md 8/2, S20-a-lifecycle-closed-beta.md 2/2
Schema	50	31	config.proto 28/17, config.example.yaml 22/14
Generated	28	17	gen/artifactregistry/config/v1/config.pb.go 28/17

Tests are 67.1% of the 4340 insertions. The production code is one worker, its registration seam, and the wiring that reaches it. A split gives either a registered worker with no sweep, or a sweep that nothing registers. Neither half is testable on its own, so a split costs review value rather than adding it. A second reason applies to the growth since the first commit, and that growth has kept going. Measured on its own, the diff from the branch's first commit 6f80f1df8 to 3056c4366 is 1974 insertions and 137 deletions across 16 files. No commit after that first one carries a feat type: they are review fixes, corrected documents, and added coverage. They land inside sweep.go and the suites that cover it. Any split by file group therefore separates a fix from the code it corrects.

Where the corrected criteria come from

!1840 (merged) is open, and nothing here takes it as authority. The two facts the criteria rest on were measured on this merge request's base branch, prozlach/s20a-lifecycle-closed-beta-step-15a:

• PurgeArgs carries NamespaceID and Scope, at internal/lifecycle/purge.go:141.
• The PurgeEnqueueOptions doc comment opens at internal/lifecycle/purge.go:234, and its sentence on the ceiling begins at line 245: "The uniqueness scope is (kind, args), and a purge job's arguments are the namespace and the scope, so a namespace carries at most two live purge jobs".

The uniqueness key is the pair rather than the namespace alone. A criterion written per namespace therefore states less than the code does, which is why the criteria above name the namespace and the scope together.

The interval overrun, the spec amendment, and the first tick

The old description of this error case was wrong, in this merge request and in the spec alike. The spec's row said the remainder is picked up by the next tick. The sweep does not do that, and it never did. A reader who took that first clause has no reason to size sweep_interval at all.

Commit d3fc534a7 amends docs/specs/S20-a-lifecycle-closed-beta.md:995 to state the restart alone. The row now says that the tick keeps the jobs it enqueued and does not resume. The namespaces behind its stopping point are reached only by a tick that gets further. It also deletes a fleet-level inference the old row drew from the oldest-first scan order. Oldest-first is a guarantee inside one namespace, and it carries nothing about which namespaces a truncated tick reached.

A second row carried the same inference, and commit 9e5ee2ff2 amends it. That row is "What the ceiling assumes", at docs/specs/S20-a-lifecycle-closed-beta.md:727, in the table under ### Purge latency and its bound. Its old text made the extra wait a function of a tombstone's position in the backlog. It also said that a tombstone's wait never grows, because newer ones keep arriving. Neither reading survives a truncated tick. The row now states what :995 states, in the same words:

• Oldest-first is a guarantee within one namespace.
• A truncated tick does not resume, and the next tick re-enumerates from the start of the keyset.
• Full coverage is a sizing property rather than a property of the walk.

The ceiling row is the one a reader consults for the bound. That is why it could not be left holding an inference the error-case row had already lost.

The spec author assented to both amendments, so both rows are settled. The two row corrections were read verbatim and agreed as written, on 2026-08-24. d3fc534a7 edits a row of the merged spec's ## Error Cases table. 9e5ee2ff2 edits a row of the table under ### Purge latency and its bound. A reviewer can read both commits as agreed rather than proposed.

The behavior did not change with either amendment. What changed on this branch is the retry classification, in d5ae8ec8f, and the sizing rule on the three configuration surfaces, in 4200e9c85.

The first tick after this merge request deploys. The sweep's first tick runs against a database that holds no customer tombstones, because closed beta has not launched. The merged spec is the ground for this. docs/specs/S20-a-lifecycle-closed-beta.md:141 states that the tables are empty because closed beta has not launched and there is no production deployment. :143 states that the same reason stops holding the moment any of those tables carries production rows. docs/roadmap/closed-beta.md:230 carries the committed launch date, 2026-09-07.

No live measurement supports this, and none was taken. The Grafana query that reports whether an environment runs a pod today was not run, because this environment holds no credential for it. That query is a pre-deploy check, and it is not a completed one. docs/dev/gitlab-com-infrastructure.md describes the path: Grafana Explore against the Mimir - Runway datasource, over kube_pod_container_info{namespace="artifact-registry-gke", container="app"} filtered per environment. An environment with no matching series runs no workload. Run it per environment before this code deploys.

This description gives no fleet number and no crossover figure, deliberately. Work item #816, "Decide the tombstone sweep's fleet-coverage strategy before closed beta outgrows one tick", carries the arithmetic and the decision.

Merge order and the deferred metrics call

A stack can merge out of order, so the order is stated here rather than left to the branches:

1. !1868 (merged) merges.
2. This merge request retargets to main.
3. !1867 (merged) merges.
4. This merge request adds the lifecycle.RegisterMetrics call.
5. This merge request merges.

!1867 (merged) merged at 2026-08-23T23:30:07Z, in merge commit 31951ad0a. That is step 3, and it landed ahead of steps 1 and 2. The list is left as it was stated, and these lines record the event rather than revising the order.

!1840 (merged) lands at any point before this merge request merges.

This merge request must not merge without the lifecycle.RegisterMetrics call. The waiver against !1840 (merged)'s "merges before this step's MR opens" gate covers the opening only, and not the merging.

Guardrail 4 keeps a step merge request out of the plan file, so this merge request edits none. Row 16 of the plan's Status table is recorded on !1840 (merged)'s branch, as commit 335135453.

lifecycle.RegisterMetrics lives on !1867 (merged)'s branch, at internal/lifecycle/metrics.go:423. Its signature is func RegisterMetrics(reg prometheus.Registerer) error. While !1867 (merged) is open, that symbol is not reachable from this branch's base, and no call to it compiles here. No file in this diff calls it, imports it, or stubs it, and the omission is deliberate.

Four facts constrain where the call can land, and none of them leaves it as a one-line addition to an unchanged function:

• It cannot go inside the register closure wireLifecycle contributes. That closure has the signature func(c *jobsriver.Client), at cmd/artifact-registry/wire_jobs.go:79, and it cannot carry the returned error.
• Registering from inside the River build closure is unprecedented here, and the gates are the reason. wireJobs returns early when the database client or the Redis client is nil. The build closure that applies the entries runs behind the migration gate. Collectors registered from there reach /-/metrics on some pods and not on others, which is the opposite of what every sibling call buys.
• Nine RegisterMetrics(appReg) calls sit in registerServiceMetrics, at cmd/artifact-registry/main.go:294-393. All nine are unconditional, so the series exist on /-/metrics from boot, and each panics on a duplicate registration because that is a boot defect.
• Two further calls do register from a wiring tier, on w.reg: glaz.RegisterMetrics at cmd/artifact-registry/wire_glaz.go:53, and iam.RegisterMetrics at cmd/artifact-registry/wire_iam.go:70. A tier-level call is therefore precedented, and lifecycle.RegisterMetrics' own doc comment names the tier as the caller to come.

wireLifecycle captures the database client and the lifecycle configuration, and nothing else. It holds no registerer today, so the tier gains a use of w.reg, which the wiring struct already carries for wireGLAZ and wireIAM.

What ran locally, and what did not

The local Garage rig was broken for the first half of this branch, and it was repaired during the run. The root cause was not a deleted access key. Garage's cluster layout had been purged with its data, so the layout version was 0 and the node held no role. That is why the key could not exist. The repair is confirmed by a put, get and delete round trip against http://127.0.0.1:8333, and TestS3DriverConformance passes against the repaired rig.

The repair landed between 0721ccf15 and 5ca12b43b, so the branch has two halves:

• Every commit up to and including 0721ccf15 ran under the workaround. Its hook run cleared ARTIFACT_REGISTRY_TEST_S3_BUCKET and ARTIFACT_REGISTRY_TEST_S3_ENDPOINT, so the suites in internal/format/oci, internal/storage and internal/storage/driver/s3 took their documented skip. The review-fix commits 576c3f20f, 91f28af49, b03be0f35 and 0721ccf15 are all in this half.
• 5ca12b43b, decc0931b, fe4915b94 and 6cc6dac26 ran against the repaired rig with nothing cleared. The go-test hook on 5ca12b43b executed internal/format/oci and internal/storage/driver/s3 rather than skipping them, and that run took about nine minutes.

The repair does not reach backwards. The first half of the branch still has no local run of those three packages.

Ten commits landed after 6cc6dac26, and none of them is covered by either half above. 018bf9da9 was committed with SKIP=go-test, and its commit body records that. The hook had failed twice on internal/datastore, with panic: test timed out after 10m0s at 602.9s and 602.8s against the 600s per-package default. This diff does not touch that package. A make-up run of the hook's own command, go test -short ./..., on the branch as it stood then returned exit 0 with zero failures over 77 packages. internal/datastore took 611.137s in that run, past the default the hook enforces. Note 3722274805 on this merge request records the run in full. 4aed91dd7, 82ee53e25, d4896526c, 6883f90c2 and ea6507ec5 change only Markdown. The go-test hook runs only when Go files change, at .pre-commit-config.yaml:115, so it selected none of the five. The other four change Go files. 1febcb5b3 changes comment text and assertion messages, and d07186937, 4b0517bf2 and e2a486abd change test files under internal/lifecycle. The hook ran on all four and passed.

GOFLAGS on this host carries -tags=integration,development_stubs. That is host state rather than anything in the repository, and -short does not remove a build tag. The hook and both make-up runs therefore compile the //go:build integration files here, so their scope is wider than a bare go test -short ./... suggests. -short narrows nothing in these suites either, because no *_integration_test.go file under internal/ calls testing.Short() — 0 of 307. Note 3722620667 on this merge request records the same correction against the earlier make-up run.

A second make-up run of go test -short ./... returned exit 0 with zero failures: 66 packages ok and 11 with no test files. It ran at e2a486abd, the branch head before the rebase. That is the same 77 packages the 018bf9da9 make-up run reported. Every package result came from Go's build cache, which is what a recent full run over these trees looks like. That full-suite run stands only for the head it ran on. The rebase changed internal/lifecycle/purge.go by 153 lines, and sweep_integration_test.go is byte-identical across it. The new case TestSweepWorker_Work_ReportsTheJobsItEnqueuedAndNotTheOnesItDeduplicated is therefore the same case over different code. go test -count=1 ./internal/lifecycle/ on 3056c4366 is what covers it now, and it returned ok in 13.796s with the integration suites against a live PostgreSQL. golangci-lint run --build-tags=integration over that package reported 0 issues. The case was also run on its own with -tags=integration against a live PostgreSQL. The pipeline's test:integration job ran it on Postgres 16, 17 and 18. Neither of those depends on this host's environment, so they are the portable evidence.

The two variables were cleared inline on a commit invocation, and never exported into a session. No commit on this branch used --no-verify. Every other hook ran on every commit. go-test ran over every other package on every commit that changed Go files, except 018bf9da9.

The pipeline covers those three packages independently of all of this. None of the three depends on internal/lifecycle: go list -deps over each one names no lifecycle package, so this diff cannot reach them.

Related to #611

This is a bot message 🤖 — /smurfit