## :mag: Summary The slug → namespace lookup is currently **duplicated per format**. OCI resolves it through `namespace.Resolver` + `namespaceFinderAdapter` (`cmd/artifact-registry/wire_oci.go:140-151`), and the npm work (S11 Step 6) introduces a parallel `npm.NamespaceFinder` plus a forthcoming npm adapter that wraps the **same** `*datastore.NamespaceStore.FindBySlug` and performs the **same** `datastore.ErrNotFound` → `ErrNamespaceNotFound` translation — differing only in which format-specific sentinel it targets. This issue tracks **Approach A**: extract the format-neutral namespace tier into shared infrastructure so both formats consume it, removing the namespace-finder duplication. ## :compass: Why this is the intended architecture [ADR 023: Code Structure and Enforcement](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/023_code_structure_and_enforcement.md) already designates namespace resolution as **shared infrastructure**, not per-format code: > "(storage, auth, **namespace resolution**, garbage collection, and data access) lives in **shared packages**" > "Format packages import shared infrastructure (CAS, auth, **namespace**, datastore)." The `format-isolation` depguard rule forbids only **format → sibling-format** imports. `internal/namespace` lives outside `internal/format/`, so it is a **shared** package that both OCI and npm are already permitted to import. The deduplication is not blocked by the isolation rules — it is what the ADR anticipated. ## :microscope: Why the duplication exists today The duplication is contingent, not structural: - `internal/namespace` is **shared-located but OCI-shaped**. Its public surface is `Resolution{ContainerRepositoryID, …}` and `ContainerRepositoryFinder`, so a format importing it today would couple to OCI's repository tier. - The format-neutral part — slug → `*model.Namespaces` plus a single `ErrNamespaceNotFound` — is real but **not exposed as a format-neutral API**. It is buried inside an OCI-flavored resolver. - So npm duplicated the namespace finder not because the ADR forced it to, but because the shared package does not yet offer a neutral namespace tier to depend on. ## :hammer_and_wrench: Scope (Approach A) Extract the format-neutral namespace tier into shared infrastructure: 1. Expose a format-neutral namespace-tier resolver in `internal/namespace` (or a clearly-named shared package): `slug → *model.Namespaces`, plus a single shared `ErrNamespaceNotFound` and the `*datastore.NamespaceStore` error-translation adapter (the `datastore.ErrNotFound` → sentinel, never-`(nil, nil)` contract — mirror today's `wire_oci.go:140-151`). 2. Have both the OCI and npm resolvers depend on this shared tier for tier 1, deleting the per-format namespace adapter. 3. Likely rename / resplit `internal/namespace` so its API stops being OCI-shaped: a shared **namespace tier** plus an OCI-specific **repository tier**. ## :white_check_mark: Key decisions (to preserve through the refactor) - **Error-vocabulary ownership stays per-format.** The shared tier returns a neutral sentinel; each format maps it to its own transport code (npm → `namespace_not_found` in the S01 envelope; OCI → `NAME_UNKNOWN`). This keeps ADR 023's "formats own their transport surface" intact. - **The repository tier stays format-specific.** It is genuinely different code, not duplication: OCI's `ContainerRepositoryStore.FindByNameInNamespace` returns `(container_repository_id, repository_id)` with a container-format filter; npm needs an `npm_packages`-side lookup with `format=npm, kind=local, soft_deleted_at IS NULL` returning a single id. Only the namespace tier is shared. - **Trusted-slug provenance must survive.** The canonical slug must continue to be sourced from the resolved `namespaces` row, never echoed from the raw request segment (it is embedded in npm `dist.tarball` / tarball-download URLs). Whichever layer resolves the namespace must carry the row's canonical slug forward. - **`(nil, nil)` / `(0, nil)` contract.** The shared adapter must replicate the OCI translation contract: map `datastore.ErrNotFound` → the sentinel, otherwise wrap, and never return a nil/zero value alongside a nil error. ## :crystal_ball: Out of scope — future end-state (Approach B) A stronger end-state is to **resolve the namespace once and stash it in the request context**, so format resolvers read it and perform only their repository-tier lookup. This removes the duplication *and* the redundant per-format DB query. This is deliberately **not** in scope here because it depends on later work: - The S08 MVP auth is a **slug-agnostic bootstrap token** ("grants every operation on every slug, no identity is propagated"); it does not resolve the namespace. - Per-namespace authorization that genuinely needs the resolved namespace is **S09** territory (see [ADR 022: Namespace Decoupling](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/022_namespace_decoupling.md)). When S09 lands, the namespace can be resolved once for authorization and reused by every format from context, at which point the namespace finder disappears from formats entirely. Approach A is the contained, available-now step toward that end-state. ## :link: Context - npm Step 6 resolver MR: https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/429 - That MR ships the resolver and finder interfaces with test fakes only; the production npm namespace adapter lands with the Step 8 wiring MR. For consistency, that adapter should mirror `wire_oci.go:140-151` for now — this issue's refactor then replaces both per-format adapters with the shared tier. ## :dart: Acceptance - A format-neutral namespace-tier resolver exists in shared infrastructure and is imported by both the OCI and npm resolvers. - The per-format namespace finder adapters are removed; no format duplicates the `datastore.ErrNotFound` → namespace-not-found translation. - Each format still maps the shared not-found sentinel to its own transport code and envelope. - The trusted-slug provenance and the never-`(nil, nil)` adapter contract are preserved and unit-tested.