[Initiative] Object Lifecycle Versioning Contract for UID and resourceVersion

[juliuskrah]

Summary

Define and enforce the object lifecycle/versioning contract for git commit hash, resourceVersion, and uid across edits, renames, status updates, and delete/recreate flows.

In Scope

• Specify canonical transition rules for (commit, resourceVersion, uid) under these operations:
  • content edit
  • file rename
  • status-only update
  • delete + re-add
• Implement controller and API behavior to enforce those transitions consistently
• Publish conformance tests and examples for lifecycle transitions
• Expose transition semantics in API/CLI docs

Out of Scope

• New transport protocols
• Frontend UX changes
• Admission mutation phase

Acceptance Criteria

• A documented lifecycle matrix exists and is referenced by controller and API components
• resourceVersion increments on every persisted state transition
• uid remains stable for edit/rename/status updates and changes for delete/recreate
• Commit hash behavior is correct for status-only updates (no Git commit mutation required)
• Integration tests validate all matrix transitions
• Watch consumers can rely on monotonic, gap-detectable progression semantics

Implementation Notes

Consumers need deterministic semantics to build reliable automation. The watch path, sync controller, and admission flow all depend on predictable identity/version behavior. Treating this as an explicit contract avoids drift between services and prevents subtle bugs in resume/replay logic.

Action	Git Commit Hash	resourceVersion	UID
Edit Content	Changes	Increments	Stays Same
Rename File	Changes	Increments	Stays Same
Update Status	Stays Same	Increments	Stays Same
Delete/Re-add	Changes	Resets (New Object)	Changes (New Entity)

Dependencies

• Depends on: [Initiative] Controller Watch API with resourceVersion Resume #131 (watch API), [Initiative] Tag-Gated Sync Controller for Atomic Release Promotion #132 (sync controller), [Initiative] Stable Catalog Resource Identity and Rename-Aware UID Lifecycle #135 (stable resource identity)
• Related: [Initiative] API Admission Controller (Validating Phase Only) #123 (validating admission), ValidatingAdmissionPolicy Engine for Catalog Objects #106 (validation policy engine)