docs: update OpenWiki

openwiki/.last-update.json

@@ -1,7 +1,7 @@
 {
-  "updatedAt": "2026-08-11T09:04:20.688Z",
+  "updatedAt": "2026-08-20T08:45:01.863Z",
   "command": "update",
-  "gitHead": "474dc01bd70e9c80acadad69d72b9360fdd920bf",
+  "gitHead": "72afb1c68ddf7a86f7720ebbbb5da6e0f460b621",
   "model": "gpt-5.6-terra",
   "status": "complete",
   "language": "en"

openwiki/operations-testing.md

@@ -36,7 +36,14 @@ Run the smallest relevant package test without cached results. The full reposito
 | Controller sequencing and adapter contracts | `pkg/admissionctrl/controller_test.go` and colocated adapter tests | `go test ./pkg/admissionctrl/... -count=1` | shared configuration or executable wiring changes |
 | HCL schema/defaults/startup failures | `pkg/config/config_test.go` | `go test ./pkg/config -count=1` | controller construction is changed too |
 | OTel provider/export and HTTP instrumentation | `pkg/otel/otel_test.go`, `cmd/nacp/nacp_otel_test.go` | `go test ./pkg/otel ./cmd/nacp -count=1` | exporter behavior or metrics schema changes |
-| Notation registry/signature behavior | `pkg/admissionctrl/{notation,validator}/` tests | `go test -tags=integration ./pkg/admissionctrl/notation` | the image verification contract crosses packages |
+| Notation task selection/errors | `TestNotationValidatorValidate` in `pkg/admissionctrl/validator/notation_validator_test.go` | `go test ./pkg/admissionctrl/validator -count=1` | the verifier, registry, trust-store, credential-store, or image-client boundary changes |
+| Notation registry/signature behavior | `TestVerifyImage` in `pkg/admissionctrl/notation/notation_test.go` | `go test -tags=integration ./pkg/admissionctrl/notation` | the image verification contract crosses packages |
+
+### Notation validation dependency boundary
+
+The production verifier in `pkg/admissionctrl/notation/notation.go` uses Notation and ORAS to verify a remote artifact; it does not use a Docker client. Its Docker-backed integration test, `TestVerifyImage`, launches a registry, builds and pushes an image, signs it, and verifies both unauthenticated and authenticated registry cases. That test imports the split Moby API/client modules declared in `go.mod` (`github.com/moby/moby/api` and `github.com/moby/moby/client`), which replace the legacy `github.com/docker/docker` module named by the current visible dependency-change commit.
+
+For a validator-only change, run the ordinary validator package test first. Run the integration command only when changing registry/signature behavior, the test's Docker/Moby client boundary, or the dependency declarations; it requires a usable Docker environment. The result then feeds the `notation` controller contract described in [policy integrations](policy-integrations.md#notation-image-verification).
 
 CI in `.github/workflows/go.yml` runs format, `go vet ./...`, build, and `go test -tags=integration -coverprofile=cov.all.out -v ./...`, then excludes generated `o11y/metric.go` from the coverage report before SonarCloud analysis. `sonar-project.properties` also excludes that generated source through `**/o11y/metric.go`. Use that broader path before a cross-package or release handoff, not as the first check for a narrow change.
 

openwiki/quickstart.md

@@ -61,6 +61,7 @@ Use the narrow package command first; `-count=1` avoids a cached success while k
 | Change mutation ordering, validator behavior, warnings, or errors | [Proxy and admission pipeline](architecture.md#controller-contract) | `pkg/admissionctrl/controller.go` | `JobHandler`, `ApplyAdmissionControllers`, `AdmissionMutators`, `AdmissionValidators` | `TestJobHandler_ApplyAdmissionControllers`, `TestJobHandler_ValidatorsReceiveIsolatedCopyOfMutatedJob` | `go test ./pkg/admissionctrl -count=1` |
 | Add a controller type or change HCL startup validation | [Policy integrations and configuration](policy-integrations.md#configuration-and-startup-validation) | `pkg/config/config.go`, `cmd/nacp/nacp.go` | `Config.Validate`, `validateMutator`, `validateValidator`, `createMutators`, `createValidators` | `TestConfigValidation`, `TestCreateMutatators`, `TestCreateValidators` | `go test ./pkg/config ./cmd/nacp -count=1` |
 | Change embedded OPA, bundle, webhook, patch, or Notation result handling | [Policy integrations and configuration](policy-integrations.md) | `pkg/admissionctrl/{opa,mutator,validator,notation,remoteutil}/` | adapter constructors, `types.Payload`, `DecodeJSONResponse` | corresponding colocated `*_test.go` | `go test ./pkg/admissionctrl/... -count=1` |
+| Change Notation registry/signature behavior or its Docker/Moby test dependencies | [Operations and testing](operations-testing.md#notation-validation-dependency-boundary) | `pkg/admissionctrl/notation/notation.go`, `pkg/admissionctrl/notation/notation_test.go`, `go.mod` | `NewImageVerifier`, `VerifyImage`, `TestVerifyImage` | `TestVerifyImage` covers unauthenticated and authenticated local registries; `TestNotationValidatorValidate` covers Docker-task selection | `go test -tags=integration ./pkg/admissionctrl/notation` (requires Docker) |
 | Change listener/upstream TLS, telemetry, CI, or release | [Operations and testing](operations-testing.md) | `cmd/nacp/nacp.go`, `pkg/otel/otel.go`, `.github/workflows/`, `.goreleaser.yaml` | `buildServer`, `buildCustomTransport`, OTel setup | `TestCreateTlsConfig`, `TestBuildCustomTransport`, `TestOtelInstrumentation` | `go test ./cmd/nacp ./pkg/otel -count=1` |
 | Find an example, fixture, or generated metric source | [Source map](source-map.md) | `example/`, `testdata/`, `pkg/o11y/nacp.yaml` | generated `pkg/o11y/metric.go` | adjacent package tests | `go test ./pkg/o11y/... -count=1` when generator/runtime code changes |
 

openwiki/source-map.md

@@ -34,9 +34,9 @@ The runtime code implements the ordered lifecycle in [architecture](architecture
 | JSON Patch implementation | `pkg/admissionctrl/mutator/opa_json_patch.go`, `pkg/admissionctrl/mutator/jsonpatcher/` | Embedded OPA patching and patch application. |
 | OPA SDK/bundle adapters | `pkg/admissionctrl/{validator,mutator}/opa_bundle_*.go` | SDK decision result handling for validation and patch mutation. |
 | Remote policy adapters | `pkg/admissionctrl/{validator,mutator}/*webhook*.go`, `pkg/admissionctrl/remoteutil/` | Payload serialization, response parsing, forwarded context headers, outbound instrumentation. |
-| Image verification | `pkg/admissionctrl/notation/`, `pkg/admissionctrl/validator/notation_validator.go` | Trust policy/store loading and Docker-task image verification. |
+| Image verification | `pkg/admissionctrl/notation/`, `pkg/admissionctrl/notation/notation_test.go`, `pkg/admissionctrl/validator/notation_validator.go`, `pkg/admissionctrl/validator/notation_validator_test.go` | Trust policy/store loading, remote verification, Docker-task selection, and the Docker-backed registry integration test. |
 
-These paths implement the controller types listed in [policy integrations](policy-integrations.md#configuration-and-startup-validation). Keep result shape tests adjacent to the adapter that interprets it.
+These paths implement the controller types listed in [policy integrations](policy-integrations.md#configuration-and-startup-validation). Keep result shape tests adjacent to the adapter that interprets it. The Docker-backed registry test is an operational, conditional check; its prerequisites and scope are defined in [operations and testing](operations-testing.md#notation-validation-dependency-boundary).
 
 ## Operations and generated observability