# :book: Context This is the collection point for amendments to `docs/specs/S09-authorization.md` and `docs/plans/2026-08-21-s09-authorization-enforcement.md` that surface while the S09 Enforcement plan's steps land. Step MRs in that plan are scoped to their step's Files list — and the extraction steps are pinned behavior-preserving — so a spec or plan sentence a step falsifies gets recorded here and corrected through a dedicated `docs` MR rather than widening the step MR. Add a dated section per batch; close the item only when every recorded amendment has landed. The spec is the contract of record, so an amendment here is documentation-accuracy work only: any change that would alter behavior, a contract, or ADR-021's model is out of scope for this item and needs its own discussion. # :memo: Amendments from step 14 (decision core extraction, https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1951) While that MR is open, the spec still describes the pre-extraction shape accurately on `main`; once it merges, the claims below go stale. Deferral agreed in review: https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1951#note_3745818612. ## `docs/specs/S09-authorization.md` 1. **Locator drift (lines 58 and 132 at revision 4a52ee53c):** the Decision layer section names pre-extraction symbols — the tuple-read description points at `resolveTuples`'s object list, and the tuple-read section names `namespace.Resolution.OrganizationUUID` as the ancestor gate. After the extraction, the decision sequence lives in `internal/authz/decision.go` (`Evaluator.Evaluate` over a supplied object id and ancestor ids, with `readTuples` underneath), and the live IAM-side ancestor derivation is `authz.OrganizationAncestorID`; `resolveTuples` survives as a `namespace.Resolution`-shaped wrapper and `OrganizationUUID` has no production caller on this path. 1. **`denials_total` totality claim (line 385 and the Denial mapping table, lines 142–154, same revision):** the Observability section says `denials_total{denial_reason}` counts every masked-404 denial by reason. The extracted core adds one deliberate exception: `evaluate`'s zero-object-id guard returns a masked 404 while incrementing nothing — a wiring defect signaled by a WARN log, documented as a carve-out in `internal/authz/metrics.go` and `docs/dev/observability.md`. The spec's counter claim and the mapping table need the same carve-out so the three documents agree. ## `docs/plans/2026-08-21-s09-authorization-enforcement.md` 1. **Step 17 Tests row:** carry the target-not-caller obligation — the management enforcement's call site must source `authz.OrganizationAncestorID`'s `targetEntityType`/`targetEntityID` from the resolved target namespace's anchor, never from the caller's identity, and its tests must pin that. The function's doc comment carries the hazard; the plan row is what puts it in front of the step 17 implementer. # :memo: Amendments from step 9 (Maven wiring, https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2064 and https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2065) Review of the step MR reversed the plan's e2e-catalog instruction: the three Maven access-control rows (`e2e.maven.access.reader-cannot-deploy`, `e2e.maven.access.non-member-denied`, `e2e.maven.access.role-inheritance`) stay `blocked` on `docs/testing/e2e/oci.md`'s format-agnostic rationale — role assignment is a GitLab UI/API surface this repository does not own, so a journey that starts from an assigned role has no path through the rig. The step MR carries the revert in 7fb7ca95c; while that MR is open, the plan and `main`'s catalog still agree, and once it merges the plan text below claims a catalog state the tree no longer has. ## `docs/plans/2026-08-21-s09-authorization-enforcement.md` 1. **Step 9 entry:** rewrite the `docs/testing/e2e/maven.md` instruction to what landed — the access-control rows stay `blocked` with `oci.md`'s rationale, and the section intro states enforcement is active when `iam:` and `glaz:` are both configured (both clients, not `iam:` alone). 1. **Step 13 entry:** the `docs/testing/e2e/npm.md` instruction carries the same move-off-`blocked` claim; correct it the same way so the step-13 author does not re-derive the reversal. 1. **Testing Strategy section:** the same move-off-`blocked` claim appears there; apply the same correction. 1. **Status table:** step 9's `MR` cell is empty; fill it with [!2064](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2064) and [!2065](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2065) (the step shipped as a two-part stack) in the same sitting. # :memo: Amendments from step 19 (permission-filtered repository listing, https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2251 and its stack) Parts 1–3 of the step's stack are merged, so the two spec claims below are stale on `main` today. ## `docs/specs/S09-authorization.md` 1. **`denial_reason` value set (line 437 at revision c7cc9ac92):** the Observability section enumerates `denial_reason ∈ (anonymous, unparsed_route, unresolved_repository, no_role_assignment, unresolved_principal, glaz_denied)` and reads as the closed set. The code also emits `escaped_separator` (`internal/authz/metrics.go`, `denialReasonEscapedSeparator`), and `docs/dev/observability.md` already lists it; add it to the spec's set so the three documents agree. 1. **GLAZ-deny log and counter totality (lines 437 and 441, same revision):** "Every GLAZ deny is logged with the action, object id, and the engine's decision reason" and "`denials_total{denial_reason}` counts every masked-404 denial by reason" both predate `authz.Evaluator.Probe`. `Probe` answers the identical verdict while booking neither the denial log nor the counter — the repository-listing route branches on it rather than answering with it — and the listing filter's per-candidate denials (`evaluateChunk`) drop a denied candidate with no decision-layer log or counter increment either. `internal/authz/metrics.go`'s Help text and `docs/dev/observability.md` state both carve-outs; the spec's two totality sentences need the same qualification. # :white_check_mark: Acceptance - Every amendment recorded above has landed through a `docs` MR, and the spec, plan, and code carry no claim a landed step falsified. - For the step 14 batch specifically: the three spec locations describe the post-extraction code and name live symbols; the spec, `internal/authz/metrics.go`, and `docs/dev/observability.md` state the same zero-object-id carve-out; the plan's Step 17 Tests row names the target-not-caller pin. - For the step 9 batch specifically: the plan's Step 9 and Step 13 entries and the Testing Strategy section describe the `blocked` outcome and the two-client gate, and the Status table carries the step 9 MR references. - For the step 19 batch specifically: the spec's `denial_reason` set carries `escaped_separator`, and its deny-log and counter totality sentences carry the `Probe` and listing-filter carve-outs, matching `internal/authz/metrics.go` and `docs/dev/observability.md`. Related to https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/1951