[api] Reorganize v1alpha1 types and conditions

- Split API into *_types.go and *_conditions.go; add shared helpers
- Rename condition constants to object-scoped Replicated*Cond* identifiers
- Update controllers/tests to use the new condition/type names
- Regenerate CRDs and move Cursor rules under .cursor/rules/*

Signed-off-by: David Magton <david.magton@flant.com>

Author: David Magton

.cursor/api_conditions_rules.mdc

@@ -10,6 +10,9 @@ alwaysApply: true
   - If I add a new API object/type or modify an existing one in `api/` (especially changes to `// +kubebuilder:*` markers, validation markers, printcolumns, subresources, etc.), I MUST run code generation and include the regenerated outputs in the same change.
   - In this repo, run generation from the repository root:
     - `bash hack/generate_code.sh`
+  - If I am intentionally doing an **API-only refactor stage** where changes outside `api/` are temporarily forbidden/undesired (e.g. the rest of the repo is not yet refactored and will not compile), then:
+    - It is acceptable to **defer CRD regeneration** (outputs under `crds/`) until the stage when cross-repo refactor is allowed.
+    - I MUST still keep `api/v1alpha1` internally consistent and compilable; prefer running **object/deepcopy generation only** when possible, instead of editing generated files by hand.
 
 - Generated files (MUST NOT edit by hand):
   - Do NOT edit `zz_generated*` files (e.g. `api/v1alpha1/zz_generated.deepcopy.go`) manually.

.cursor/api_codegen_rules.mdc .cursor/rules/api-codegen/RULE.md.cursor/api_codegen_rules.mdc renamed to .cursor/rules/api-codegen/RULE.md

@@ -0,0 +1,58 @@
+---
+description: API Conditions naming rules (v1alpha1)
+globs:
+  - "api/**/*_conditions.go"
+  - "!api/linstor/**/*.go"
+alwaysApply: true
+---
+
+- Condition constants naming:
+  - Every API object `Status` MUST expose `.status.conditions` (`[]metav1.Condition`) (see `types_rules.mdc`).
+  - Any API object that has at least one standardized/used condition MUST have its own condition type/reason constants scoped by object name.
+  - If the API type exposes `.status.conditions` but there are **no** standardized/used conditions yet:
+    - The `Conditions` field MUST remain in the API (it is part of the contract).
+    - The `<objprefix>_conditions.go` file MAY be absent.
+    - Do NOT create placeholder/empty condition constants “just in case”.
+  - Current API types that expose `.status.conditions` in this repo:
+    - `ReplicatedVolume`
+    - `ReplicatedVolumeReplica`
+    - `ReplicatedVolumeAttachment`
+    - `ReplicatedStorageClass`
+    - `ReplicatedStoragePool`
+
+- Condition Type constants MUST be named:
+  - `<ObjName>Cond<CondTypeName>Type`
+  - `CondTypeName` MUST match the string value of `.Type`.
+  - Examples:
+    - `ReplicatedVolumeCondIOReadyType = "IOReady"`
+    - `ReplicatedVolumeReplicaCondDataInitializedType = "DataInitialized"`
+    - `ReplicatedVolumeAttachmentCondReplicaIOReadyType = "ReplicaIOReady"`
+
+- Condition Reason constants MUST be named:
+  - `<ObjName>Cond<CondTypeName>Reason<ReasonName>`
+  - `CondTypeName` MUST match the string value of the condition type (the `.Type` string).
+  - `ReasonName` MUST match the string value of `.Reason`.
+  - Examples:
+    - `ReplicatedVolumeReplicaCondScheduledReasonReplicaScheduled = "ReplicaScheduled"`
+    - `ReplicatedVolumeCondQuorumReasonQuorumLost = "QuorumLost"`
+    - `ReplicatedVolumeAttachmentCondAttachedReasonSettingPrimary = "SettingPrimary"`
+
+- Conditions grouping (MUST):
+  - Keep each condition type and **all of its reasons in a single `const (...)` block**.
+  - Conditions MUST be ordered alphabetically by condition type name within the file/package.
+  - Reasons within a condition MUST be ordered alphabetically by reason constant name.
+
+- Conditions comments (MUST):
+  - Avoid controller-specific comments like “managed by X” in API packages.
+  - Add short English docs: what the condition represents and what the reasons mean.
+
+- Value stability (MUST):
+  - Do NOT change string values of `.Type` and `.Reason` constants.
+  - Only rename Go identifiers when reorganizing/clarifying.
+
+- Scoping & duplication (MUST):
+  - Do NOT use generic `ConditionType*` / `Reason*` constants.
+  - If the same reason string is used by multiple conditions, create separate constants per condition type, even if the string is identical.
+    - Example: `"NodeNotReady"`:
+      - `ReplicatedVolumeReplicaCondOnlineReasonNodeNotReady = "NodeNotReady"`
+      - `ReplicatedVolumeReplicaCondIOReadyReasonNodeNotReady = "NodeNotReady"`

.cursor/rules/api-conditions/RULE.md

@@ -0,0 +1,23 @@
+---
+description: API file structure and conventions (sds-replicated-volume)
+globs:
+  - "api/**/*.go"
+  - "!api/linstor/**/*.go"
+alwaysApply: true
+---
+
+- Object prefixes (MUST):
+  - Use short prefixes: `rv`, `rvr`, `rva`, `rsc`, `rsp`.
+
+- File naming per object (MUST):
+  - `<objprefix>_types.go`: API types (kubebuilder tags), object/spec/status structs, adapters for interfaces (e.g. GetConditions/SetConditions) and tightly coupled constants/types and pure set/get/has helpers (no I/O, no external context).
+  - `<objprefix>_conditions.go`: condition Type/Reason constants for the object.
+    - MAY be absent if the API object exposes `.status.conditions` but there are no standardized/used conditions yet (do not create empty placeholder constants).
+  - `<objprefix>_custom_logic_that_should_not_be_here.go`: non-trivial/domain logic helpers (everything that does not fit `*_types.go`).
+
+- Common file naming (MUST):
+  - `common_types.go`: shared types/enums/constants for the API package.
+  - `common_helpers.go`: shared pure helpers used across API types.
+  - `labels.go`: well-known label keys (constants).
+  - `finalizers.go`: module finalizer constants.
+  - `register.go`: scheme registration.

.cursor/rules/api-file-structure/RULE.md

@@ -0,0 +1,45 @@
+---
+description: API naming rules for label keys and finalizers (sds-replicated-volume)
+globs:
+  - "api/**/labels.go"
+  - "api/**/finalizers.go"
+  - "!api/linstor/**/*.go"
+alwaysApply: true
+---
+
+## Label keys (`labels.go`)
+
+- **Constant naming (MUST)**:
+  - Label key constants MUST end with `LabelKey`.
+    - Good: `ReplicatedVolumeLabelKey`, `NodeNameLabelKey`
+    - Bad: `LabelReplicatedVolume`, `NodeLabel`, `LabelNodeName`
+
+- **Prefix constant (MUST)**:
+  - The label prefix constant MUST be private and named `labelPrefix` (unless there is a proven need to export it).
+  - The prefix value MUST be the module-scoped prefix:
+    - `sds-replicated-volume.deckhouse.io/`
+
+- **Value format (MUST)**:
+  - Label key values MUST be built as `labelPrefix + "<suffix>"`.
+  - The `<suffix>` part MUST be lowercase-kebab-case, without repeating the module name.
+    - Good: `labelPrefix + "replicated-volume"`
+    - Bad: `labelPrefix + "sds-replicated-volume-replicated-volume"`
+
+- **Layout (MUST)**:
+  - Keep all exported `...LabelKey` constants in a single `const (...)` block.
+  - Avoid commented-out placeholder constants; prefer adding constants only when actually needed.
+
+## Finalizers (`finalizers.go`)
+
+- **Constant naming (MUST)**:
+  - Finalizer constants MUST end with `Finalizer`.
+    - Good: `ControllerFinalizer`, `AgentFinalizer`
+    - Bad: `FinalizerController`, `ControllerFinalizerName`
+
+- **Value format (MUST)**:
+  - Finalizer values MUST be module-scoped and stable:
+    - `sds-replicated-volume.deckhouse.io/<component>`
+  - `<component>` MUST be lowercase and short (e.g. `controller`, `agent`).
+
+- **Stability (MUST)**:
+  - Do NOT change existing finalizer string values (this would break cleanup semantics).

.cursor/rules/api-labels-and-finalizers/RULE.md

@@ -0,0 +1,145 @@
+---
+description: API rules for type-centric layout, enums, status, naming, and helpers/custom logic
+globs:
+  - "api/**/*_types.go"
+  - "api/**/common_types.go"
+  - "!api/linstor/**/*.go"
+  - "!api/**/zz_generated*"
+alwaysApply: true
+---
+
+## Code layout: type-centric blocks (MUST)
+
+- **Type-centric blocks** MUST be used to organize code:
+  - Each type MUST be readable without scrolling across the file (keep related declarations together).
+  - Code from different types MUST NOT be interleaved.
+
+- **API object file layout** (MUST):
+  - This applies to typical files containing one API root object (`type <Obj> struct`) plus its `Spec`/`Status`/`List`.
+  - The main flow MUST read top-to-bottom without jumping:
+    - Root object: `type <Obj> struct { ... }`
+    - `type <Obj>List struct { ... }` (see List rule below)
+    - `type <Obj>Spec struct { ... }`
+    - Spec-local types/enums/constants/interfaces/helpers used by `Spec`
+    - `type <Obj>Status struct { ... }`
+    - Status-local types/enums/constants/interfaces/helpers used by `Status`
+    - Secondary/helper types referenced by the above (pseudo-DFS), keeping each type block contiguous
+    - Shared helpers (if any) at the very end
+
+- **Block structure** for each type MUST follow this strict order:
+  - `type <TypeName> struct { ... }`
+  - Enums and constants belonging to this type (incl. tightly-coupled sub-enums)
+  - Interfaces tightly coupled to the type
+  - Public methods of the type
+  - Private helpers of the type
+
+- **Block ordering in a file** MUST be a human-oriented dependency order (pseudo-DFS), not alphabetical:
+  - Main (primary) type of the file
+  - Types directly referenced by the main type
+  - Secondary/helper types
+
+- **List types** (MUST):
+  - `<Obj>List` SHOULD be placed immediately after `<Obj>` (right under the root object), to make navigation consistent and fast.
+  - `<Obj>List` MUST NOT split the `Spec`/`Status` flow (i.e. do not put it between `Spec` and spec-local enums/helpers, or between `Status` and status-local enums/helpers).
+  - If there is a strong reason (rare), `<Obj>List` MAY be placed after `Status`/secondary types, but keep it as a single contiguous block (no interleaving).
+
+- **Locality rule for enums/constants/helpers** (MUST):
+  - If an enum/const/helper is primarily used by `Spec`, it MUST be placed in the Spec-local section (right after `type <Obj>Spec ...` and its methods).
+  - If an enum/const/helper is primarily used by `Status`, it MUST be placed in the Status-local section (right after `type <Obj>Status ...` and its methods).
+  - If an enum/const/helper is used by both `Spec` and `Status`, it SHOULD be placed with the `Spec` section (earlier) unless that hurts readability; do NOT duplicate it.
+
+- **Shared helpers**:
+  - Avoid generic helpers without a clear owning type.
+  - If a helper is used by multiple types, it MUST be placed after all type blocks (or moved to `common_helpers.go` if shared broadly).
+
+- Enums (MUST):
+  - If a field has a finite set of constant values, model it as an enum:
+    - `type EnumType string`
+    - `const ( EnumTypeValue1 EnumType = "Value1" ... )`
+  - Enum declaration order MUST be contiguous:
+    - `type EnumType string`
+    - `const (...)` with all enum values
+    - enum helpers (if any) — right after the const block
+  - Enums MUST provide `String()` method:
+    - `func (e EnumType) String() string { return string(e) }`
+  - Keep enum values documented (short English comment per value or a short block comment).
+  - Do NOT create separate wrapper types for arbitrary string/number/bool fields unless there is a strong, confirmed need.
+  - Common enums (MUST):
+    - If the same enum is used by multiple API objects, it MUST be moved to `common_types.go`.
+    - Do NOT move enums to `common_types.go` if they are only used by a single API object.
+
+- Status (MUST):
+  - `Spec` and `Status` structs MUST be embedded as values on the root object (e.g. `Spec TSpec`, `Status TStatus`), not `*TStatus`.
+  - Every API object `Status` MUST expose `.conditions` as `[]metav1.Condition`:
+    - Field name MUST be `Conditions []metav1.Condition`.
+    - Use the standard kubebuilder/patch markers for mergeable conditions list:
+      - `// +patchMergeKey=type`
+      - `// +patchStrategy=merge`
+      - `// +listType=map`
+      - `// +listMapKey=type`
+      - `// +optional`
+      - JSON tag: ``json:"conditions,omitempty"`` and patch tags consistent with the above.
+    - Condition Type/Reason constants are defined in `<objprefix>_conditions.go` only when they become standardized/used (see `conditions_rules.mdc`).
+
+- Type naming (MUST):
+  - This section applies to ALL API types (including enums).
+  - Names MUST be unique within the API package.
+  - Names MUST NOT start with short object prefixes like `RV`, `RVR`, `RVA`, `RSC`, `RSP`.
+  - Usually, names MUST NOT start with the full object name if the type is not generic and is unlikely to clash:
+    - Good: `ReplicaType`, `DiskState`
+    - Prefer full object name only for generic/repeated concepts (below).
+  - If the type name is generic and likely to be repeated across objects (e.g. `Phase`, `Type`), it MUST start with the full object name:
+    - Examples: `ReplicatedStoragePoolPhase`, `ReplicatedStoragePoolType`, `ReplicatedVolumeAttachmentPhase`
+  - Structural type name (e.g. `Spec`, `Status`) MUST be prefixed by the full object name:
+    - Examples: `ReplicatedVolumeSpec`, `ReplicatedVolumeStatus`, `ReplicatedStorageClassSpec`, `ReplicatedStorageClassStatus`
+
+## Helpers vs custom_logic_that_should_not_be_here (MUST)
+
+Write helpers in `*_types.go`. If a function does **not** fit the rules below, it MUST go to `*_custom_logic_that_should_not_be_here.go`.
+
+## What belongs in `*_types.go` (MUST)
+
+Helpers are **pure**, **local**, **context-free** building blocks.
+
+- **Pure / deterministic**:
+  - Same input → same output.
+  - No reads of current time, random, env vars, filesystem, network, Kubernetes API, shell commands.
+  - No goroutines, channels, retries, backoff, sleeping, polling.
+
+- **No external context**:
+  - Do not require `context.Context`, `*runtime.Scheme`, `client.Client`, informers, listers, recorders, loggers.
+  - Do not require controller-runtime utilities (e.g. `controllerutil.*`).
+
+- **Allowed operations**:
+  - Field reads/writes on in-memory structs and maps/slices.
+  - Simple validation and parsing/formatting that is deterministic.
+  - Nil-guards and trivial branching.
+  - Returning `(value, ok)` / `(changed bool)` patterns.
+
+- **Typical helper shapes (examples)**:
+  - `HasX() bool`, `GetX() (T, bool)`, `SetX(v T) (changed bool)`, `ClearX() (changed bool)`
+  - `IsXEqual(...) bool`, `XEquals(...) bool`
+  - `ParseX(string) X` / `FormatX(...) string` (no I/O, no time, no external lookups)
+
+## What MUST NOT be in `*_types.go` (MUST NOT)
+
+If any of these are present, the code belongs in `*_custom_logic_that_should_not_be_here.go`.
+
+- **Business / orchestration logic**:
+  - Decisions that interpret cluster state, desired/actual reconciliation, phase machines, progress tracking.
+  - Anything that “synchronizes” different parts of an object (spec ↔ status, spec ↔ labels/annotations, cross-object references).
+
+- **Conditions/status mutation logic**:
+  - Creating/updating `metav1.Condition` / using `meta.SetStatusCondition` / computing reason/message based on multi-step state.
+  - Anything that sets `.status.phase`, `.status.reason`, counters, aggregates, etc. based on logic.
+
+- **Controller/Kubernetes integration**:
+  - `controllerutil.SetControllerReference`, finalizer management with external expectations, scheme usage.
+  - Any reads/writes via API clients (even if “simple”).
+
+- **I/O and side effects**:
+  - File/network access, exec/shell, OS calls, time-based logic (`time.Now`, `time.Since`), randomness.
+
+- **Non-trivial control flow**:
+  - Complex `if/switch` trees, multi-branch logic tied to domain semantics.
+  - Loops that encode placement/selection/scheduling decisions.