docs: state what a uid actually guarantees

[sunib]

Prompted by the question "a Kubernetes uid is globally unique, isn't it?" — and the honest answer is almost, in a way that matters here.

What Kubernetes actually guarantees: every object created over the whole lifetime of one cluster has a distinct uid. Unique in space and in time. The time half is what earns uid the key in this library: a resource deleted and recreated under the same name is a different object, and a store keyed on name would reattach a user's unsaved draft to it.

What it does not guarantee: global uniqueness. The guarantee is cluster-scoped. In practice a uid is a UUID, so a cross-cluster collision is not a thing that happens — but the protocol doesn't lean on that, and spec §1 already takes the strict line: a uid is unique within one upstream target, and a consumer holding objects from more than one stream MUST key on (target, uid).

So the spec was right and the glossary was wrong. docs/glossary.md said a resource is identified "uniquely by metadata.uid", full stop — looser than the spec it is supposed to introduce, and exactly the sentence that would let a reader merge two targets into one store. It now states the real guarantee, says why the time half is the load-bearing one, notes that (target, uid) is the key across streams, and points at the spec.

Docs only.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@sunib, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4bd96a8b-33ed-49fb-901b-0f4ec5068be8

📥 Commits

Reviewing files that changed from the base of the PR and between d5d686c and 5d8c4ac.

📒 Files selected for processing (1)

• docs/glossary.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/uid-uniqueness

---

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.}