docs: authorize the S16 list query bound, correct two stale premises

Two corrections to S16, both surfaced reviewing !1717 (merged). This MR merges before !1717 (merged).

The live-list query size bound was unauthorized, under a borrowed code

RemoteTagListProxy.ServeTagList bounds the client query string it splices onto the upstream URL at 8 KiB and refuses past it. Two things were wrong with that, and only the second is a defect in the code:

  1. The spec did not authorize the refusal. API Contracts says AR "never rejects a cursor" on a remote list.
  2. The refusal answered 400 PAGINATION_NUMBER_INVALID, the exact status-and-code pair the Error Cases list row reserves for a propagated upstream 400. A client could not tell AR's own resource bound from the upstream's verdict on the cursor it sent.

The bound itself stays. The query is forwarded as opaque bytes and never parsed, so size is the only bound available, and without one Go's default Server.MaxHeaderBytes (1 MiB) is the sole ceiling: one inbound request drives an upstream GET of the same size, at no cost to the client beyond its own connection.

What this MR changes:

  • The pagination exception carves the size bound out of "no pagination validation", on the ground that a byte cap bounds the request rather than validating the cursor's content, which is the thing verbatim forwarding exists to leave alone.
  • Error Cases gains a row for the AR-side refusal, with a new extension code QUERY_LIMIT_EXCEEDED so it cannot be confused with a propagated upstream 400.
  • ## Resolutions records the reasoning.
  • The plan's Step 16 acceptance line admits the bound it previously read as excluding.

The Go change emitting QUERY_LIMIT_EXCEEDED lands in !1717 (merged), which is why this merges first.

Two plan entries rested on an expired premise

Step 5's Gated bullet withheld the three eviction criteria on the grounds that their triggers were S17 management-API writes absent from main, and the S17 remote-repository CRUD entry in Dependencies said the same thing. internal/managementapi/update.go now serves the remote settings PATCH and performs a credential replace or clear without a url change, which is exactly the credential-only trigger. No remote-repository create handler has landed, so that half of the entry still holds.

Both entries say what changed rather than substituting the corrected fact silently, per the plan-corrections rule in AGENTS.md.

The gate moves to the fact that still holds: no caller performs the eviction on the credential arm, tracked in #706. The url arm needs no eviction of its own: oci.RemoteTokenCache keys its entries by upstream URL as of !1717 (merged), so a repointed remote misses rather than reusing the token the old host minted.

Testing

Documentation only; no code, no tests. markdownlint-cli2, vale, and lychee pass in the pre-commit run.

Related to #706

Edited by Sylvia Shen

Merge request reports

Loading
Loading