An app pod mutator can refuse, and a refusal stops the write

[incognick]

WithAppPodMutator grows an error return, and a hook that returns one stops the write.

func (a *Adapter) WithAppPodMutator(fn func(PodIdentity, *corev1.PodSpec) error) *Adapter

Needs a record. This refines ADR-0100 §1 the way ADR-0100 refined ADR-0061 §1. Not merged until that record is accepted.

Why

A hook told which app it is shaping will read per-app policy from somewhere, and a read can fail. With a void hook it has two ways out and both are worse than a failed deploy: guess — apply a default and run the pod under a policy nobody chose, the outcome least likely to be noticed; or poison the spec so the API server rejects it, which stops the write but reports the refusal as whatever validation error the poison triggers. An operator is told their runtime class is not a valid DNS subdomain and has to already know that means a database was unreachable. A deploy that fails for a reason nobody can read is only half of failing closed.

What changes

• Both invocation sites carry the error out: buildDeployment → (*appsv1.Deployment, error), runJob → (*batchv1.Job, error). Each builds the object and then returns, so nothing reaches the API server.
• ApplyWorkload and RunJob fail with the hook's own error, wrapped with the app, the namespace and which of the app's two pods it was. errors.Is recovers the embedder's error.
• A refusal is not a conflict, so the deploy path's RetryOnConflict returns it rather than re-running the closure — asserted, the hook is called exactly once.
• ADR-0061 §3 stands: a nil hook, and a hook returning nil, author what they always did. Pinned by comparing the two spellings' output.

What does not change

WithPodMutator keeps its exact signature, stays Deprecated:, and still wires into the same field — its hook cannot fail, so the wrapper reports nil. WithPlatformPodMutator is untouched (ADR-0077 §2, ADR-0100 §4).

The signature pin was edited, deliberately

controlplane/kube/app_pod_identity_test.go:23 pinned WithAppPodMutator's old type and has been changed, with a comment saying it was changed on purpose and why — a pin edited quietly is a pin defeated. The two lines in controlplane/kube/placement_test.go:299-302 pinning WithPodMutator and WithPlatformPodMutator are not touched and still compile.

Note for whoever wrote the brief: the WithAppPodMutator pin lives in app_pod_identity_test.go, not in placement_test.go — ADR-0100 §5 describes it as a third line beside the other two, and it landed in the identity test's own file instead.

Compatibility, decided rather than assumed

This is a source break for anything compiled against WithAppPodMutator. Taken deliberately, not avoided with a fourth name for one hook:

• The spelling shipped in exactly one release, v0.14.0-rc.53, cut today.
• Nothing has adopted it. The only known embedder's adoption is an open, unmerged pull request in its own repository, which reworks against this signature.
• ADR-0100's Consequences already call two spellings of one seam a wart. Three would be worse than a compile error nobody will ever see.
• WithPodMutator's retention is not analogous: that seam has been released and wired for many versions, and it cannot fail, so it has nothing to gain from the change.

Verification

On the dev box at a01653a, go1.26.3: gofmt -l . clean, go vet ./... clean, go build ./... clean, go test ./... fully green. CI is the authority for the tiers this cannot run.

Three mutation rounds, each build-gated and reverted:

mutant	caught by
applyAppPodMutator swallows the hook's error	the two deploy refusal tests, the run refusal test, and the message test
runJob ignores its refusal and returns the Job	the run refusal test and the message test
the WithPodMutator wrapper reports an error instead of nil	8 tests, including every pre-existing WithPodMutator test

The refusal tests use a fake cluster that fails a run-Job create rather than only recording it, so a regression that let a refused run through fails in milliseconds instead of waiting out RunJob's ten-minute deadline — a guard whose failure mode is a ten-minute hang is one somebody deletes rather than fixes.