docs(specs): spec S17 phase 3 format artifact reads

📋 What does this MR do?

Patches S17: REST management API with Phase 3: format artifact reads — the read-only artifact surface beneath a hosted repository, per ADR-009's format-specific artifact APIs.

🗺️ Surface

13 GET endpoints under /api/v1/:slug/repositories/:repository_name/:format/:

Formats Endpoints
docker, oci Images (list, detail), image tags (list, detail), manifests (list)
maven, npm Packages (list, detail), versions (list, detail), files (list, detail)
npm Dist-tags (list, detail)

The :format segment is the repository's format value; ADR-009 predates the Docker/OCI format split and is amended via the handbook in a follow-up.

🎯 Key decisions (full reasoning in the spec's Resolutions)

  • Stored fields only. Responses serialize stored columns plus three single-row joins (blob size, tag manifest digest, dist-tag version); no read-time aggregates, so every list stays one index-ordered keyset scan.
  • Specced against the live schema. No soft-delete filtering on container tables (the columns do not exist there), versions_count cap semantics documented, tag-join invariants derived from the S11/S12 transactional delete paths.
  • Three new keyset indexes on (namespace_id, <parent>_id, created_at, id) back the created_at desc list defaults: maven_versions (partial, live rows), container_manifests partial (WHERE subject_digest IS NULL, the default referrer-excluding manifests list), and container_manifests full (the include_referrers=true view); ADR-007's index list is amended via the handbook.
  • Deferred with documented follow-ups: per-artifact sizes and download counts (S18/S22), npm package.json metadata (waits for the monolith S06 artifact-detail spec), the remote-kind cache object (S13).

Status

Spec status is Approved; the merge is the approval signal per the repo gate. Open Questions: none. markdownlint and Vale pass; the mermaid flowchart renders.

Related to #312 (closed)

Edited by David Fernandez

Merge request reports

Loading
Loading