fix(attribution)!: partition author facts by declared audit route

[sunib]

The bug

Reported by the gitops-api team: every object mirrored through a dedicated in-cluster ClusterProvider was committed as unknown (attribution unresolved), while the same actor's writes through default attributed correctly. Mirroring stayed correct, no condition changed, and no reconcile failed, so the loss was visible only in the commit author.

Their measurement, reproduced twice: 5 objects absent, all having waited the full grace window, with written=66 / matched=12 and zero expiries. Facts were being written the whole time, under a key nobody read.

Why

A kube-apiserver takes one --audit-webhook-config-file, and that file uses the kubeconfig format to specify the remote address of the service, singular. So one physical cluster posts audit under exactly one route.

Facts were partitioned by the ClusterProvider's name, so every other provider naming that same cluster read a partition nothing writes.

That shape is one the product encourages. allowedNamespaces and allowSourceNamespaceOverride are provider-wide, so a platform admin granting the override to one tenant and withholding it from another has no choice but to create two providers on one cluster — which is exactly what the source-namespace e2e does.

The fix

ClusterProvider.spec.attribution.auditRoute declares the route a cluster's events arrive on, and that value partitions the facts.

metadata:
  name: tenant-acme-delegating   # the name humans read and GitTargets reference
spec:
  attribution:
    auditRoute: prod-eu-1        # the route this cluster's audit events arrive on

• Defaults to metadata.name, so an install that sets nothing resolves exactly what it resolved before.
• Several providers share one cluster's facts by declaring one route.
• Providers on different clusters keep separate partitions. That is what still separates an etcd-snapshot clone from its origin: a clone reproduces every metadata.uid, so a design keying facts by object identity alone could not tell them apart, while a human-chosen route can.

Ingestion gets simpler, and loses its last Kubernetes read

The /audit-webhook/<route> existence gate, AuditProviderResolver, its cmd/main.go adapter, and the annotation-routing startup rule are all deleted. Parse the route, record the fact — no API call.

A route is a partition name, not a claim about an object, so a fact for a route no provider declares is stored and expires unread. That also stops dropping audit batches in flight while a provider is being created or recreated, which the API server does not retry after a 404.

The failure is now loud

A route that has never resolved and produces five unresolved events in a row logs once, naming the fix rather than the symptom. The threshold is not one because a lone miss is ordinary under audit-batch delay; a run with nothing ever matched is the signature of a route nobody writes to.

Also removed

PurgeClusterFacts and its decision record. It was unwired, and a shared route makes it unsafe: purging on one provider's deletion would drop the facts of every other provider on that route, and of the operator's own cluster, which was never torn down. The reasoning that still binds — no finalizer, because helm uninstall would strand the object in Terminating — moved onto LegacyClusterProviderFinalizer, where someone about to re-add one will actually read it.

Breaking changes

No deprecated aliases and no dual-read, deliberately: this path has no users to protect.

Change	From	To
flag	--author-attribution-cluster-annotation-key	--author-attribution-audit-route-annotation-key
chart value	attribution.clusterAnnotationKey	attribution.auditRouteAnnotationKey
fact-key infix	cluster:<name>	route:<auditRoute>

An operator still passing the old flag fails to start, which is the loud outcome. The key-infix change gives a rolling upgrade a TTL-bounded window (minutes) where events commit as the configured committer — the ordinary degradation, and the same rollout behaviour the v2→v3 key bump had.

Tests

• e2e (test/e2e/audit_route_attribution_e2e_test.go): a dedicated in-cluster ClusterProvider whose name is not default, declaring auditRoute: default, must commit as the impersonated OIDC identity and specifically not the unresolved placeholder. This fails on main. A second case reaches an object through a rules[].sourceNamespace override, pinning the report's claim that the override was innocent.
• unit: AuditRoute() defaulting; two providers sharing a route joining one fact while a non-declaring one still misses; the Declare-time capture and its teardown; the warning's four cases; the handler storing a fact for a route no provider declares.

task lint, task test, and task test-e2e all pass (Ran 69 of 91 — 69 Passed, 0 Failed).

Stacked on #262

This targets chore/docs-linting (#262), not main, so the unrelated markdown-linting work squash-merges as its own commit. Review #262 first; GitHub retargets this to main automatically once it merges. The diff shown here is the fix alone.

Design: docs/design/attribution-fact-identity.md

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 13ae72b2-1320-4b36-a8b2-8fc1453ebc1a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/attribution-audit-route

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 83.20611% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/watch/target_watch.go	12.5%	7 Missing ⚠️
internal/queue/attribution_index.go	82.6%	0 Missing and 4 partials ⚠️
internal/watch/author_resolver.go	88.2%	4 Missing ⚠️
cmd/main.go	76.9%	2 Missing and 1 partial ⚠️
internal/watch/cluster_context.go	85.0%	3 Missing ⚠️
internal/controller/gittarget_source_cluster.go	85.7%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!