Module finalizers

Expand description

Workspace-canonical finalizer keys the tatara controllers stamp on their owned CRDs to gate cascade-delete + orphan-reap on graceful teardown.

§Family

The reconciler binaries in this workspace own three top-level CRDs that participate in the K8s garbage-collection contract via the metadata.finalizers list:

PROCESS — the crate::prelude::Process reconciler’s finalizer key. Stamped by tatara-reconciler::phase_machine::handle_pending via [crate::patch::ensure_finalizer]; stripped by handle_reaped via remove_finalizer.
ALLOCATION — the crate::prelude::EphemeralAllocation controller’s finalizer key. Reserved by tatara-pool-reconciler::controller_allocation::reconcile for the future Bound → Releasing → Released cascade-delete gate.
POOL — the crate::prelude::EphemeralPool controller’s finalizer key. Reserved by tatara-pool-reconciler::controller_pool::build_member_process for the future member-Process orphan-reap gate.

ALL enumerates the three consts in stable declaration order so downstream sweeps (a fleet-wide finalizer audit binary, an ops diagnostic dumping every tatara-owned finalizer on a cluster, a per-key coverage report) iterate through ONE substrate slice rather than three hand-typed literals.

§Peer axes

Peer to crate::annotations on the “K8s metadata key that pins a reconciliation contract” axis-family — where crate::annotations owns keys the reconciler READS or WRITES on OWNED resources (FluxCD HelmRelease, Kustomization, member Process on a pool member), this module owns keys the reconciler stamps on the CRDs IT OWNS (the crate::prelude::Process, crate::prelude::EphemeralAllocation, crate::prelude::EphemeralPool metadata.finalizers list). Both families carry the same tatara.pleme.io/<slug> wire-form shape; the finalizer family additionally carries the shared <owner>-finalizer suffix — a convention pinned by [tests::all_carry_finalizer_suffix] so a future addition to the family cannot silently drift the suffix.

§Compounding

Pre-lift the three wire-form finalizer literals were spread across three files (the crate::PROCESS_FINALIZER top-level const at crate + private POOL_FINALIZER / ALLOC_FINALIZER consts in tatara-pool-reconciler), with no cross-owner coherence pin binding the shared tatara.pleme.io/<x>-finalizer shape. A future rename that shifted (e.g.) the group segment to v2/ or the per-owner suffix to -guard had to be applied at three separate files coherently — a partial edit would silently orphan or double-finalize whichever owner missed the update. Post-lift the three consts live at ONE substrate owner + one closed ALL slice + four family-invariant pins (per-key wire-form parity, per-key -finalizer suffix, per-key tatara.pleme.io/ prefix, cross-key uniqueness).

Theory grounding: THEORY.md §VI.1 (generation over composition — the tatara.pleme.io/<owner>-finalizer wire-form shape recurred at THREE hand-authored declaration sites past the ★★ PRIME-DIRECTIVE ≥ 2 duplication threshold; lifted to ONE per-owner const + ONE ALL slice + four family-invariant pins here). THEORY.md §II.1 invariant 5 (composition preserves proofs — the invariant pins bind the family shape at fail-before-pass- after granularity; a future rename that drifted the group prefix or the suffix at ONE arm surfaces at [tests::all_share_group_prefix] or [tests::all_carry_finalizer_suffix] rather than as silent operator-facing skew at whichever owner’s finalizer no longer matches the K8s-side registered wire form).

Constants§

ALL: Closed family of tatara-owned finalizer keys in declaration order: PROCESS, ALLOCATION, POOL. Downstream sweeps (a per-owner coverage report, a fleet-wide finalizer audit binary, an ops diagnostic dumping every tatara-owned finalizer on a cluster) iterate through this ONE slice rather than re-listing the three consts by hand.
ALLOCATION: Finalizer key reserved for the crate::prelude::EphemeralAllocation controller (tatara-pool-reconciler::controller_allocation). Once the Bound → Releasing → Released cascade is wired the controller will stamp/strip this key through the same [crate::patch::ensure_finalizer] / remove_finalizer primitives the Process reconciler already routes through for PROCESS.
FINALIZER_SUFFIX: Shared owner-suffix every finalizer key in the ALL family carries — the convention <owner>-finalizer distinguishes a finalizer key from a signal/label/annotation key on the same group. Pinned across every arm by [tests::all_carry_finalizer_suffix].
GROUP_PREFIX: Shared group prefix every finalizer key in the ALL family carries — the same tatara.pleme.io/ group segment every tatara-owned CRD annotation + finalizer key rides through, matching the #[kube(group = "tatara.pleme.io", …)] derive slot on the CRD structs. Pinned across every arm by [tests::all_share_group_prefix] so a future rename of the group (a shift to v2/ under a migration, a per-fleet override) lands at ONE substrate const here + the paired CRD derive slots rather than at three independent finalizer wire forms.
POOL: Finalizer key reserved for the crate::prelude::EphemeralPool controller (tatara-pool-reconciler::controller_pool). Once the member-Process orphan-reap gate is wired the controller will stamp/strip this key at pool birth + pool teardown through the same [crate::patch::ensure_finalizer] / remove_finalizer primitives.
PROCESS: Finalizer key stamped on the crate::prelude::Process metadata.finalizers list by tatara-reconciler::phase_machine::handle_pending. The reconciler blocks K8s garbage collection until it has emitted the terminal crate::prelude::ProcessAttestation receipt and stripped the finalizer at handle_reaped.