adding docs

# Add X.731 state + health `_CR_CHECKVAL_` characteristics to KubernetesCRDV1 / KubernetesCRV1

Date: 2026-08-29 16:10

Branch: `12-update-the-models-to-address-the-new-resource-state-model`

## Why

Issue #12 introduced the ITU-T X.731 resource state model on

`org.etsi.osl.tmf.ri639.model.Resource`:

- `ResourceAdministrativeStateType` — LOCKED / UNLOCKED / SHUTDOWN

- `ResourceOperationalStateType` — ENABLE / DISABLE

- `ResourceUsageStateType` — IDLE / ACTIVE / BUSY

- `ResourceHealth` (derived) — UP / PENDING / DOWN / HELD / GONE

Until now `KubernetesCRDV1` / `KubernetesCRV1` only let an operator map an observed CR

status-field value onto a `ResourceStatusType` (`_CR_CHECK_FIELD` +

`_CR_CHECKVAL_STANDBY|ALARM|AVAILABLE|RESERVED|UNKNOWN|SUSPENDED`). `ResourceStatusType` is now

inventory/pool bookkeeping only; health lives in the X.731 pair. Operators need the same

value-mapping mechanism for the new state dimensions.

## What changed

Both `KubernetesCRDV1` and `KubernetesCRV1`:

1. **13 new `String` backing fields** alongside the existing `statusCheckValue*` block:

   `adminStateCheckValueLocked/Unlocked/Shutdown`, `operStateCheckValueEnable/Disable`,

   `usageStateCheckValueIdle/Active/Busy`,

   `healthCheckValueUp/Pending/Down/Held/Gone`. Covered by the class-level Lombok

   `@Getter`/`@Setter`; not `@Builder` constructor params (same as the existing fields).

2. **13 new spec characteristics** in `toRSpecCreate()`, added after `_CR_CHECKVAL_SUSPENDED`

   (empty default value, TEXT, non-configurable):

   `_CR_CHECKVAL_ADMINSTATE_LOCKED`, `_CR_CHECKVAL_ADMINSTATE_UNLOCKED`,

   `_CR_CHECKVAL_ADMINSTATE_SHUTDOWN`, `_CR_CHECKVAL_OPERSTATE_ENABLE`,

   `_CR_CHECKVAL_OPERSTATE_DISABLE`, `_CR_CHECKVAL_USAGESTATE_IDLE`,

   `_CR_CHECKVAL_USAGESTATE_ACTIVE`, `_CR_CHECKVAL_USAGESTATE_BUSY`,

   `_CR_CHECKVAL_HEALTH_UP`, `_CR_CHECKVAL_HEALTH_PENDING`, `_CR_CHECKVAL_HEALTH_DOWN`,

   `_CR_CHECKVAL_HEALTH_HELD`, `_CR_CHECKVAL_HEALTH_GONE`.

3. **13 matching resource characteristics** in `toResourceCreate()`, each carrying the value of

   the corresponding new field.

4. **RSpec version bumps** (spec characteristics changed):

   - `KubernetesCRDV1.OSL_KUBCRD_RSPEC_VERSION` `0.0.3` → `0.0.4`

   - `KubernetesCRV1.OSL_KUBCRV1_RSPEC_VERSION` `0.0.4` → `0.0.5`

`toRSpecUpdate()` / `toResourceUpdate()` delegate to the create methods — unchanged.

## Files

- `src/main/java/org/etsi/osl/domain/model/kubernetes/KubernetesCRDV1.java`

- `src/main/java/org/etsi/osl/domain/model/kubernetes/KubernetesCRV1.java`

## Verification

- `mvn -q compile` — clean.

- `grep -c` of the new key prefixes → 26 per file (13 in `toRSpecCreate` + 13 in

  `toResourceCreate`).

## Follow-up

- `KubernetesCRV1.applyHealth(...)` derived health from `statusValue` only — addressed in

  [20260829_1619](20260829_1619_kubernetescrv1-applystate-from-x731-not-status.md)

  (`applyState` now keyed off resolved `healthValue` / `*StateValue` fields).

- Still open: the cridge watcher must populate those resolved fields from the `_CR_CHECK_FIELD` +

  `_CR_CHECKVAL_*` mapping.

# KubernetesCRV1: derive resource state from the X.731 model, not from `statusValue`

Date: 2026-08-29 16:19

Branch: `12-update-the-models-to-address-the-new-resource-state-model`

## Why

`KubernetesCRV1.applyHealth(ResourceCreate)` set `operationalState` / `administrativeState`

by switching on `statusValue` (`ResourceStatusType`). Per issue #12, `ResourceStatusType` is

inventory/pool bookkeeping and must not be the source of a health verdict — health belongs to the

ITU-T X.731 attributes and the derived `ResourceHealth`. The producer (cridge watcher) should

report state directly rather than have the model reverse-engineer it from a pool-status label.

## What changed

`src/main/java/org/etsi/osl/domain/model/kubernetes/KubernetesCRV1.java`:

1. **New resolved-value fields** (builder params, alongside `statusValue`):

   - `ResourceHealth healthValue` — the convenient path

   - `ResourceOperationalStateType operationalStateValue`

   - `ResourceAdministrativeStateType administrativeStateValue`

   - `ResourceUsageStateType usageStateValue`

   These are the producer's *resolved* view. They are distinct from the `*CheckValue*` /

   `healthCheckValue*` strings added earlier, which are operator mapping *configuration* passed

   through as characteristics.

2. **`applyHealth(...)` → `applyState(...)`**, rewritten:

   - `OSL_LABEL_DELETED` short-circuit unchanged (→ `DISABLE` + `SHUTDOWN`).

   - If `healthValue` is set, translate it to the `operationalState`/`administrativeState` pair

     exactly as `Resource.applyHealth` does (UP→enable/unlocked, DOWN→disable/unlocked,

     HELD→enable/locked, GONE→disable/shutdown, PENDING→leave unset) **and return** — the verdict

     is authoritative.

   - Only when `healthValue` is null, apply `operationalStateValue` / `administrativeStateValue` /

     `usageStateValue` individually if set.

   - No longer reads `statusValue`.

3. `statusValue` is retained — it still drives `rs.resourceStatus(...)` (pool bookkeeping only).

The method was kept (not removed): `ResourceCreate` has no `applyHealth` helper, so the

`ResourceHealth` → enum-pair translation still needs a home.

## Verification

- `mvn -q compile` — clean.

- No in-repo callers of `KubernetesCRV1` broke; the Lombok builder gains four optional setters.

- Existing `_CR_CHECKVAL_*` characteristics and `statusValue`→`resourceStatus` mapping unchanged.

## Follow-up (out of scope)

The cridge watcher must be updated to populate `healthValue` (and/or the individual

`*StateValue` fields) on the `KubernetesCRV1` it builds, using the `_CR_CHECK_FIELD` +

`_CR_CHECKVAL_*` mapping now including the new `ADMINSTATE` / `OPERSTATE` / `USAGESTATE` /

`HEALTH` keys.

# Docs index

- [20260829_1610 Add X.731 state + health `_CR_CHECKVAL_` characteristics](20260829_1610_add-crcheckval-state-health-characteristics.md) — new namespaced `_CR_CHECKVAL_ADMINSTATE_*`, `_CR_CHECKVAL_OPERSTATE_*`, `_CR_CHECKVAL_USAGESTATE_*` and `_CR_CHECKVAL_HEALTH_*` characteristics on `KubernetesCRDV1` / `KubernetesCRV1`, plus RSpec version bumps.

- [20260829_1619 KubernetesCRV1: derive state from X.731, not `statusValue`](20260829_1619_kubernetescrv1-applystate-from-x731-not-status.md) — `applyHealth` → `applyState`, keyed off new `healthValue` / `operationalStateValue` / `administrativeStateValue` / `usageStateValue` builder params instead of the `ResourceStatusType` switch.