docs(specs): promote the artifact deletes in S14 and S06
Summary
monolith/2026-09-01-artifact-delete-surface gates Steps 6 through 28 on a spec promotion MR. This is that MR. It covers the first slice's single deletes and the deferred bulk slice, so both Phase 1 prohibitions invert once and neither spec is left self-contradictory.
The specs describe the delete surface as it is on gitlab-org/gitlab master
at 786e3c4a44c2 where it has shipped, and specify it where it has not:
- Shipped at
786e3c4a44c2:ArtifactRegistryVersionDelete,ArtifactRegistryManifestDelete,ArtifactRegistryContainerTagDelete,ArtifactRegistryNpmDistTagDelete; the client'sdelete_version,delete_manifest,delete_container_tag, anddelete_npm_dist_tag; the version and manifest row deletes; the version list heading's artifact delete; and the version-detail kebab's Delete version. - Specified here, not shipped: the two bulk mutations over an
idslist, the two bulk client methods (drafts at gitlab!256212 and gitlab!256223, which also carrydelete_all:andbulk_delete_container_tagsthis spec does not specify), page-scoped multi-select with Delete selected, npm dist-tag removal on version detail, the container page's Delete manifest, and the removed-artifact redirect.
What each spec gains
monolith/S14 (version list)
### Mutations: five mutations, the four properties they share withArtifactRegistryArtifactDelete, the shared error mapping, and the two shipped wrong-format refusal forms (payloaderrorsfor the version delete, a top-level argument error for the manifest and container tag deletes).#### The bulk selector: theidslist only, with no whole-collection branch and no bulk tag mutation in the schema; theids→version_ids:/digests:mapping; and the413,503, andRetry-Afterbounds as AR serves them, with the413claim scoped to what the view sends.## Ruby client: the five write methods, local list refusals, the retry exclusion, and the409parentsallowlist behaviour.### Connections: the 20-row page cap, with its source and paging cost.### Delete actions: per-target confirmation copy, the single-vs-bulk meaning of the202with its S17 source, eviction, the empty-page re-read, the removed-artifact redirect keyed on a null read after the view's own delete (aligned with gitlab-org/gitlab#631424 and AR#951), and why Delete manifest stays enabled.### Multi-select and bulk delete: page-scoped selection, Delete selected only, the unreachable 1000 cap at a 20-row page, and the silent skip of a child an outside index references.- No delete renders on a remote repository reached by deep link.
- RSpec and request-spec acceptance criteria for every write, and Jest criteria for the failure outcomes.
- Phase 2 and Resolutions edits that change a stated reason: the Tags and
Referrers rows now say what the manifests list serves (
tags_preview,parents_preview), a new row covers the "referenced by" parent link, the Tags Resolution gives the current reason for the deferral, and the S05 fan-out bullet now reads "one AR request per parent row plus the parent read".
monolith/S06 (version detail)
### Mutations: the two mutations shared with S14, andArtifactRegistryNpmDistTagDelete, which checks format and kind before any AR call.### Header: Delete version, npm dist-tag removal, and the container page's Delete manifest; no delete on a remote repository; and the package or image re-read that decides where a delete lands, including on a failed re-read.- The container page's Phase 2 rows gain Delete manifest beside the Download manifest row, both waiting on that page's kebab.
monolith/S05 (repository detail)
ArtifactRegistryArtifactDeletestays kind-neutral.ArtifactRegistryRepositoryArtifactsDeletemust refuse a repository that is not remote, server-side. Without that refusal, a direct GraphQL call on a hosted repository permanently deletes every artifact. The shipped mutation checks nokind; the implementation is tracked in gitlab-org/gitlab#632065. This reverses 626611's "no kind guard" ruling for the repository clear only, and notes on 626611 and 627172 record that.- The hosted Delete package / Delete image confirmation and success outcome.
monolith/S02 (Ruby client): the retry policy is corrected to the shipped
one. The connection retries GET only and has excluded DELETE since
gitlab-org/gitlab 58f78d3dff79, which S14 and S06 rely on. S02 still said
DELETE was retried, which GitLab Duo flagged as a contradiction.
monolith/S02 also says the per-attempt error callback fires once per
attempt, and records that delete_repository now gets one attempt.
monolith/S15 and docs/specs/README.md: the rows that still carried
delete-file, the files-tab bulk delete, the Phase 1 "no kebab" line, and the
"no layer serves" tag claim are brought in line. S15's shipped-control
paragraph is re-measured at 786e3c4a44c2: four of the five shipped deletes
read the verdict, and only version detail's Delete version does not.
Plan mismatches left for a docs(plans) follow-up
The spec now agrees with the plan on the dist-tag control reading kind
(Steps 18 and 26), the "cannot be undone" copy (Step 11), and an ids-only bulk
bar (Step 14). These mismatches remain in the plan:
- Files:
#delete_file,#bulk_delete_files,ArtifactRegistryFileDelete, andArtifactRegistryFilesBulkDeletein Steps 1, 4, 6, and 9, and Steps 17 and 19 whole. Per-file delete is out of the product.delete_fileremoval is gitlab!253712. - Step 14: "a selection over the cap disables submission and names the cap". With a 20-row page no selection reaches the 1000 cap, so the spec writes no cap message.
- Step 11 and Step 12: node eviction "with no refetch". The spec accepts a
list re-read after a single delete, because a single delete writes before its
202. The shipped versions table re-reads. - Step 15: "a per-manifest
tagsread, which no layer serves". AR servestags_previewon the list and the fulltagson manifest detail. - Steps 4, 9, and 10:
delete_all:,bulk_delete_container_tags,ArtifactRegistryBulkDeleteSelectorInput, andArtifactRegistryContainerTagsBulkDelete. The spec now has no whole-collection branch and no bulk tag mutation.
UX decisions recorded in Resolutions
Each can be overturned without reopening the wire contract.
- Manage-tags removes one tag per action.
- Bulk selection is page-scoped, and the schema carries no whole-collection branch until a surface and its confirmation exist.
Reviewable size
1,096 insertions and 233 deletions across six files at 909eb60b3, over the
500-LOC guideline. The two Phase 1 prohibitions are the gate, one per spec, and
inverting one without the other leaves half the frontend forbidden. S05 and S15
move because the promotion falsifies statements in them, and S02 because its
retry text contradicted the code S14 and S06 cite.
| File | Insertions | Deletions |
|---|---|---|
docs/specs/monolith/S14-version-list.md |
667 | 110 |
docs/specs/monolith/S06-version-detail.md |
312 | 62 |
docs/specs/monolith/S05-repository-detail.md |
75 | 25 |
docs/specs/monolith/S15-permission-gated-controls.md |
27 | 22 |
docs/specs/monolith/S02-ar-ruby-client.md |
13 | 12 |
docs/specs/README.md |
2 | 2 |
Verification
markdownlint-cli2,vale --minAlertLevel=error, andlychee --offline --include-fragmentson all six files: 0 errors.- Monolith facts were checked at
786e3c4a44c2:max_page_size: 20on the versions and manifests connections and on the parent packages and images connections, and the resolvers'FieldCallCountbudgets, unchanged at949f666e5fb2;- which shipped delete controls call
permissionAllows; renders_errors.rb,MAX_RENDERED_PARENTS = 10, theparentsallowlist, and the retry allowlist;- the per-mutation format and kind checks;
- the modal copy.
- AR facts were checked at
origin/main:parents_previewandtags_previewonContainerManifest;GET .../manifests/{digest}inv1.yamlandhandler.go;Retry-Afteronly indenial.go;- the
\uXXXXescape case in the bulk ceilings; - the single-delete write paths;
- npm last-version package removal;
- tag delete removing the tag row only.
E2E scenario impact
None. artifact_registry_ui is dark for every step of the plan this MR
unblocks, and no scenario in docs/testing/e2e/ is
added or changed. The flag's own enablement is tracked at
gitlab#605113.
Related to gitlab-org/gitlab#627172