docs(openapi): define delete_all completion for remote repositories
Why
api/openapi/v1.yaml defines delete_all completion as acceptance-time emptiness. That holds for hosted repositories but not remote ones: the caller's own read traffic re-fetches a remote collection's rows, so a poll-until-empty loop against a live remote cache never terminates. Container's text already carries the hosted/remote split. The shared Maven/npm response schema, PackagesBulkDeleteAccepted, still states the hosted-only promise unconditionally, and five smaller sites in the files this MR touches name only "npm" for behavior Maven's remote pass shares.
What
- Splits
PackagesBulkDeleteAcceptedinto hosted/remote clauses, reusingContainerBulkDeleteAccepted's wording byte for byte so the sibling schemas read as one voice. - Widens the five npm-only sites in
v1.yaml's bulk-delete descriptions by dropping the format name rather than enumerating formats, so a fourth format with a remote pass needs no edit here. - Pins the new promise with four
Containschecks on the whitespace-normalized description. YAML re-wrapping cannot split a pin, and nothing structural reads this prose, so nothing else would catch a flattening rebase. - Aligns
api/bruno/**as a ride-along: no operation changed, so the Bruno guardrail does not fire, but the files restate the same broken promise, including one container file the earlier container fix never resynced.
Test plan
go test ./internal/managementapi/... -run TestContract -v: the newTestContract_PackagesBulkDeleteAccepted_HostedRemoteSplitis red onmain(each pinned substring has zero occurrences there) and green here, and the rest of the contract suite stays green.npx --yes @redocly/cli@2.34.0 lint --config api/openapi/redocly.yaml, the version CI'slint:openapijob pins: passes.- Every commit ran the full pre-commit hook chain (no
--no-verify: the guard test lands with the prose it pins, already green).
Spec coverage
| Contract site | Change | Guard |
|---|---|---|
PackagesBulkDeleteAccepted, completion sentence |
split: hosted acceptance-time boundary, remote bounded pass | pins holds no entry older than the request, what is promised is the pass, re-cached behind it is still there |
PackagesBulkDeleteAccepted, resubmission sentence |
split: hosted retry boundary, remote second pass | pin remote repository is another pass |
bulkDeletePackages (2 sentences), bulkDeleteVersions (1), bulkDeleteFiles (1), PackagesBulkDeleteAllSelector (1) |
"remote npm" widened to "remote" | prose only |
api/bruno/management-api/: container-bulk-deletes/folder.bru and 4 package-bulk-deletes/*.bru |
same split and widening as their openapi sites | prose only |
All four pins run against the description with whitespace runs collapsed (strings.Fields join), so a wrapping change cannot break them.
Closes #738 (closed)
Context for LLM agents
Rationale
- Three commits with a red
test(openapi)commit first. Rejected: this MR has no production layer to split from, and the repo's precedent for contract prose lands guard test and prose in one green commit, as in docs(openapi): Declare API lifecycle status (!2004 - merged) • Chance Feick. Containson the raw description. Rejected: a YAML re-wrap moves line breaks and silently splits a pin. Chosen: collapse whitespace first, then pin four clause fragments.- Widening "npm" to "Maven or npm". Rejected: neither container passage names a format, and a genericized sentence needs no edit when a fourth format gains a remote pass.
Consequences: the pins are reword-sensitive by design. A rewording that keeps the promise in different words fails the test and must update the pins.
Non-goals
- The four
remote npmsites left inv1.yaml(~1389, ~1557, ~1642, ~1722), the parallel packument sentence kept inbulk-delete-files.bru, and the threeartifact-deletes/*.brufiles. npm-specific mechanics (packument freshness, dist-tags) with no Maven analog. - Pinning
ContainerBulkDeleteAccepted's prose. The same undefended-prose risk exists there, but it predates this issue. Follow-up candidate. - The stale "will declare its own equivalents" comment above
PackagesBulkDeleteAccepted(~4837). Out-of-hunk churn, declined. docs/specs/S17-rest-management-api.md. Already states the split.