fix(flow): preserve expected component descriptions

[pbreton]

Summary

Preserve Core descriptions for ExpectedMachine, ExpectedSwitch, and ExpectedPowerShelf when Flow mirrors expected inventory.

The Core-owned value is stored under the reserved expected_description key so expected reconciliation can create, update, or clear it without replacing runtime- or operator-owned description entries.

Fixes #4353.

Root cause

The Core API detail models already exposed descriptions, but the Flow normalization and persistence paths omitted them. Consequently, new mirrored components lost their descriptions and existing components never received description changes.

The description column is also shared with runtime metadata such as the NVSwitch nvos_ip, so replacing the entire JSON map would have caused data loss.

Changes

• Carry descriptions through normalization for ExpectedMachine, ExpectedSwitch, and ExpectedPowerShelf.
• Store the expected description under the reserved expected_description key.
• Merge updates into the existing description map, preserving runtime and operator keys.
• Remove only expected_description when Core clears the value.
• Add unit coverage for conversion, change detection, merging, and clearing.
• Add PostgreSQL-backed insert, change, clear, and merge coverage for every component type.

Validation

• make test-flow
• go vet ./flow/internal/scheduler/jobs/inventorysync
• git diff --check

The full Flow suite was rerun after rebasing onto current upstream main.

Note

This is an attempt at fully automated issue resolution using Codex.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6ac37d13-b8c0-4f47-ba07-761005eb1aab

📥 Commits

Reviewing files that changed from the base of the PR and between 54ac133 and 1643cc9.

📒 Files selected for processing (3)

• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component.go
• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component_test.go
• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_db_test.go

---

Summary by CodeRabbit

• New Features

  • Component synchronization now carries expected descriptions for machines, switches, and power shelves.
  • Description updates preserve operator- and system-managed metadata while adding, updating, or removing the expected description as needed.

• Bug Fixes

  • Improved detection and application of component description changes.
  • Clearing an expected description now removes only the managed entry without affecting unrelated descriptions.

• Tests

  • Added coverage for description synchronization across supported component types and database updates.

Walkthrough

The mirror now carries Core descriptions into normalized machine, NVSwitch, and power-shelf components. Reconciliation manages the reserved description entry, preserves unrelated metadata, persists updates, and clears removed descriptions. Unit and database-backed tests cover the lifecycle.

Changes

Expected description synchronization

Layer / File(s)	Summary
Normalize expected descriptions rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component.go, rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component_test.go	Expected component specifications now include descriptions from machine, switch, and power-shelf details. Component conversion stores descriptions under the reserved expected_description key.
Reconcile description metadata rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component.go, rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component_test.go, rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_db_test.go	Component creation and updates modify only the reserved description entry, preserve unrelated metadata, handle non-object and non-string values, detect changes, and clear removed descriptions. Tests cover creation, replacement, clearing, and interleaved runtime updates.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: preserving expected component descriptions in Flow.
Description check	✅ Passed	The description directly explains description propagation, ownership, merging, clearing, and test coverage for the changed components.
Linked Issues check	✅ Passed	The changes satisfy issue #4353 by preserving descriptions across component types, supporting lifecycle updates, and retaining runtime and operator metadata.
Out of Scope Changes check	✅ Passed	The changes remain within issue #4353 and add only the required implementation and tests for expected component description synchronization.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[pbreton]

@coderabbitai full review.

[coderabbitai]

@pbreton: I will perform a complete review of PR #4713.

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component.go`:
- Line 446: Update the inventory reconciliation update logic around the
description column so it never replaces the complete stored JSONB map with the
stale snapshot value. Use an atomic JSONB expression against the database column
to update only expected_description, deleting that key when Core clears it,
while preserving unrelated runtime metadata such as nvos_ip. Add an interleaving
integration test covering a runtime metadata update during reconciliation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d60ad4bc-7b8c-4fd8-8cab-313b65fbe667

📥 Commits

Reviewing files that changed from the base of the PR and between 54ac133 and 659c611.

📒 Files selected for processing (3)

• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component.go
• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_component_test.go
• rest-api/flow/internal/scheduler/jobs/inventorysync/expected_mirror_db_test.go

[pbreton]

@coderabbitai full review.

[coderabbitai]

@pbreton: I will perform a complete review of PR #4713.

✅ Action performed

Full review finished.