Module consts 

Well-known wire-contract strings: the finalizer, labels, annotations, and condition types that form kopiur’s public Kubernetes surface (ADR §4.5, ADR-0005 §2/§14(c)).

These live in kopiur-api — not the controller — because they are part of the API contract itself: external tooling (the kubectl kopiur plugin, GitOps health checks, user automation) must agree on them byte-for-byte with the operator. Controller-internal reasons/actions/deadlines stay in kopiur-controller’s own consts module.

Constants

ALLOW_IDENTITY_CHANGE_ANNOTATION

Acknowledges an intentional identity-affecting change on UPDATE. Two surfaces share it:

ALLOW_MASS_DELETION_ANNOTATION

Acknowledges a mass-deletion wave on a Repository/ClusterRepository. Value: an RFC3339 timestamp. A HELD external deletion is released iff its Snapshot’s metadata.deletionTimestamp <= this value — “I approve what is pending NOW”. Deliberately VALUED (unlike the presence-only allow-identity-change ack, consumed at a single admission instant): this annotation is read continuously by the controller, so a presence-only ack left behind (or committed to Git) would disarm the breaker forever. With the timestamp, a stale ack is inert against any LATER wave, nothing ever needs to remove it, and the operator never edits user metadata. The controller clamps the effective value to <= its own now (clock-skew guard); an unparseable value is ignored (Warning event on the repository).

API_VERSION

The API version string for kopiur CRDs (used in mover TargetRefs and kubectl -o name-style output).

AZURE_WORKLOAD_IDENTITY_LABEL

Pod label opting a mover pod into the azure-workload-identity mutating webhook: pods carrying azure.workload.identity/use: "true" and running as a federated ServiceAccount get AZURE_TENANT_ID/AZURE_CLIENT_ID/ AZURE_FEDERATED_TOKEN_FILE (and the projected token volume) injected — exactly the env kopia’s azure backend binds its credential flags to. Stamped by the operator (and the CLI’s browse sessions) on every mover pod for a repository whose azure backend uses auth.workloadIdentity. Lives here because the operator and kubectl kopiur must agree on it byte-for-byte.

AZURE_WORKLOAD_IDENTITY_LABEL_VALUE

The AZURE_WORKLOAD_IDENTITY_LABEL value opting the pod in.

CONFIG_LABEL

Label naming the SnapshotPolicy a Snapshot was produced from.

DEFAULT_CATALOG_REFRESH_INTERVAL

Default catalog re-scan cadence when spec.catalog.refreshInterval is unset: how often a Ready repository re-lists its kopia snapshots to materialize (and expire) origin: discovered Snapshot CRs. Part of the documented API contract (field-reference), so it lives here rather than in the controller.

DEFAULT_FAILED_JOBS_HISTORY_LIMIT

Default SnapshotSchedule.spec.failedJobsHistoryLimit when unset: how many Failed Snapshot CRs from a schedule to retain (the rest are pruned). Bounds failure history so a schedule firing against a persistently-failing precondition or backend doesn’t accumulate Failed CRs forever. GFS retention applies only to successful snapshots, so this is the only bound on failures (ADR-0003). Part of the documented API contract, so it lives here, not in the controller.

DEFAULT_HEALTH_PROBE_FAILURE_THRESHOLD

Default spec.health.probe.failureThreshold: how many consecutive failing probes must accumulate before the loud RepositoryVanished / BackendReachable=False condition is raised and an event fired. Debounces a single transient blip (an S3 list-after-delete race, a NAS reboot, a credential-rotation moment) from alarming on-call or nudging a destructive manual recreate.

DEFAULT_HEALTH_PROBE_INTERVAL

Default spec.health.probe.interval when unset: how often an opt-in backend health probe re-connects a Ready repository to confirm the kopia repository still exists at the backend. Off by default; only meaningful once spec.health.probe.enabled: true. Conservative — a vanished/unreachable repository is rare and the probe runs a short mover Job — so it leans long. Part of the documented API contract, so it lives here, not in the controller.

DEFAULT_INDEX_BLOB_WARN_THRESHOLD

Default spec.health.indexBlobWarnThreshold: the index-blob count above which the reconciler warns that maintenance isn’t keeping up. A freshly-compacted repo sits near zero; a wedged-maintenance repo climbs unbounded (a real one reached 1448). Conservative so it only fires when maintenance is clearly behind. Overridable per-repo; 0 disables the warning. Part of the documented API contract, so it lives here rather than in the controller.

DEFAULT_MASS_DELETION_THRESHOLD

Default spec.deletionProtection.threshold (0 disables). 10 pending external destructive deletions is far above legitimate manual cleanup but far below a tooling-driven cascade (the motivating incident was ~600).

INDEX_BLOB_HEALTH_CONDITION

Repository/ClusterRepository condition reporting content-index-blob health (ADR-0005 §13). True = healthy (count under threshold); False with reason TooManyIndexBlobs = the index is growing unbounded because maintenance isn’t compacting. NON-BLOCKING: the repository stays Ready and GitOps health gates are not tripped — it’s a degradation warning, not an outage. Wire-visible (the kubectl plugin’s status reads it).

MAINTENANCE_CONFIGURED_CONDITION

Repository/ClusterRepository condition recording whether a Maintenance covers it (ADR §3.7). Wire-visible: GitOps health checks and the kubectl plugin’s status read it.

MANAGED_BY_LABEL

The standard app.kubernetes.io/managed-by label key. Stamped on every operator-created object (mover Jobs, work-spec ConfigMaps, cache PVC, minted mover SA/RoleBinding, projected credential Secret, CSI VolumeSnapshots) so Argo/Flux recognize them as controller-owned and neither prune nor report them OutOfSync (ADR-0005 §14(c)).

MANAGED_BY_VALUE

The MANAGED_BY_LABEL value identifying kopiur-managed objects.

MASS_DELETION_HELD_CONDITION

Repository/ClusterRepository condition: pending external destructive deletions for this repository are at/above the breaker threshold and held.

MIN_CATALOG_REFRESH_INTERVAL

Floor for spec.catalog.refreshInterval, enforced at admission. Each re-scan of an object-store repository runs a short mover Job; anything faster than this is Job churn with no operational value.

MIN_HEALTH_PROBE_INTERVAL

Floor for spec.health.probe.interval, enforced at admission. Each probe runs a short mover Job (object-store / volume-backed) or an in-process connect; anything faster than this is Job churn with no operational value. Shares the 30s floor with the catalog re-scan for the same reason.

OP_LABEL

Label naming the operation a mover Job performs, for Jobs whose owning CR doesn’t record the Job name in status (e.g. Restore). Values: OP_RESTORE, OP_RESTORE_TARGET.

OP_RESTORE

OP_LABEL value for a Restore’s mover Job.

OP_RESTORE_TARGET

OP_LABEL value for a Restore’s operator-created target PVC.

ORIGIN_LABEL

Label mirroring a Snapshot’s origin (scheduled/manual/discovered).

PRUNED_BY_ANNOTATION

Marks a Snapshot the OPERATOR is deleting as part of its own lifecycle, stamped immediately before the delete call. Values: PrunedBy annotation values (retention, failed-history). The Snapshot finalizer uses it to distinguish Kopiur’s own prunes from external deletions (GC cascades, kubectl, third-party controllers); external destructive deletions are subject to the schedule-cascade guard and the mass-deletion breaker, operator prunes are not. Any unrecognized value is treated as EXTERNAL (fail-safe). Wire-visible: users and tooling may read it on terminating CRs.

READY_CONDITION

kstatus-compliant standard condition types (ADR-0005 §2) so kubectl wait --for=condition=Ready and Flux/Argo health checks work natively against every reconciled kopiur CRD. The headline readiness condition.

RECONCILING_CONDITION

Set True while a reconcile is making progress toward Ready.

REPOSITORY_UID_LABEL

Label keying a discovered Snapshot to the owning Repository UID (dedup).

RUN_MODE_ANNOTATION

Companion annotation selecting the run kind: quick (default) or full (see kopiur_api::maintenance::ManualRunMode).

RUN_REQUESTED_ANNOTATION

Annotation requesting an out-of-band Maintenance run NOW (Flux-style reconcile trigger). Value: an RFC3339 timestamp; a NEW timestamp requests a new run (re-applying the same value is a no-op once handled). Usable from bare kubectl annotate or kubectl kopiur maintenance run.

SCHEDULE_LABEL

Label naming the SnapshotSchedule that fired a scheduled Snapshot (selector for a schedule’s own children, distinct from CONFIG_LABEL under policySelector fan-out).

SESSION_BROWSE

SESSION_LABEL value for a read-only browse session.

SESSION_LABEL

Label marking a mover Job as an interactive data-plane session pod (spawned by kubectl kopiur browse/ls/cat/download, not by the operator). Value: SESSION_BROWSE. Wire-visible: the CLI finds (and reuses) a warm session by this selector, and session end deletes by it.

SESSION_REPO_LABEL

Label keying a session Job to the repository it holds open, as <kind>-<name> (e.g. Repository-nas). One warm session per repository: the CLI selects on this so two snapshots in the same repository share a pod.

SKIP_SNAPSHOT_CLEANUP_ANNOTATION

Repo-offline escape hatch: when present, the finalizer is removed without contacting the repository, the snapshot is recorded orphaned, and a SnapshotOrphaned event is emitted (ADR §4.5).

SNAPSHOT_CLEANUP_FINALIZER

The finalizer every Snapshot carries so the operator can run snapshot cleanup before the CR is removed (ADR §4.5 / SKILL “Snapshot lifecycle = CR lifecycle”).

SNAPSHOT_ID_LABEL

Label keying a discovered Snapshot to its kopia snapshot id (dedup, §2.1).

STALLED_CONDITION

Set True when the resource is stuck and won’t progress without intervention (mapped from a terminal ErrorClass::Terminal failure).

Functions

effective_failed_jobs_history_limit

The effective failed-history limit: failedJobsHistoryLimit when set, else DEFAULT_FAILED_JOBS_HISTORY_LIMIT. Some(0) keeps no failed snapshots.

effective_mass_deletion_threshold

The effective mass-deletion breaker threshold: deletionProtection.threshold when set, else DEFAULT_MASS_DELETION_THRESHOLD. Some(0) disables the breaker.