feat: add Image and ResolvedImage fields to SwarmOpts

[tsivaprasad]

Summary

This PR adds Image and ResolvedImage fields to SwarmOpts and implements precedence-based image resolution in the Swarm orchestrator. This provides the foundation for user-controlled image overrides and stable image pinning.

Changes

• Added Image (user override, never managed by CP) and ResolvedImage (CP-managed) fields to SwarmOpts in server/internal/database/spec.go, serialized under orchestrator_opts.docker.
• Updated SwarmOpts.Clone() to correctly copy both new fields.
• Extracted resolveInstanceImages() in the Swarm orchestrator to implement precedence-based image resolution: Image → ResolvedImage → manifest lookup (lazy backfill).
• When Image is explicitly set, the manifest is bypassed entirely, allowing unknown or custom versions to work through user overrides.

Testing

Verification:

• Created cluster
• Created DB using create_db.json
• Confirm Docker service resolved the correct manifest image

docker service ls
ID             NAME                              MODE         REPLICAS   IMAGE                                                       PORTS
l2837hwwvoy8   postgres-storefront-n1-9ptayhma   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2   
c6wg777c5rig   postgres-storefront-n1-689qacsi   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2   
seysxqetlp0s   postgres-storefront-n1-ant97dj4   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2 

Checklist

• Tests added or updated

PLAT-596

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2cd75598-776e-49c1-b15d-06c6d0321598

📥 Commits

Reviewing files that changed from the base of the PR and between 95fe3df and 44c4a96.

📒 Files selected for processing (1)

• server/internal/orchestrator/swarm/version-manifest.json

---

📝 Walkthrough

Walkthrough

This PR extends SwarmOpts with Image and ResolvedImage fields, updates Clone() to copy them, adds Orchestrator.resolveInstanceImages implementing precedence (Image → ResolvedImage → manifest fetch with lazy backfill and writes), refactors instanceResources to use it, and adds tests plus a version manifest JSON.

Changes

Image Resolution and SwarmOpts Enhancement

Layer / File(s)	Summary
SwarmOpts data model and cloning server/internal/database/spec.go, server/internal/database/spec_test.go	SwarmOpts gains Image (user override) and ResolvedImage (control-plane managed) fields with JSON tags. Clone() copies both new fields alongside existing swarm options. TestSwarmOptsClone validates cloning behavior, independence after mutation, and nil receiver handling.
Image resolution orchestrator logic server/internal/orchestrator/swarm/orchestrator.go	New resolveInstanceImages helper applies image precedence (user Image → stored ResolvedImage → manifest fetch with lazy backfill). It initializes nil OrchestratorOpts/SwarmOpts when needed. instanceResources now uses this helper instead of calling versions.GetImages directly.
Image resolution test coverage server/internal/orchestrator/swarm/resolve_instance_images_test.go	TestResolveInstanceImages exercises explicit overrides, precedence ordering, using stored ResolvedImage without mutation, lazy backfill with nil struct initialization, error handling for unknown versions, and ensures manifest cache/results are not mutated by backfill.
Version manifest server/internal/orchestrator/swarm/version-manifest.json	Adds pinned image tags, stability flags, and default markers for postgres, postgrest, mcp, and rag used by versions.Lookup/GetImages.

Poem

🐰 I nibbled the manifest root,

Image fields now bear their fruit,
User first, then stored reply,
Backfill writes when tags run dry,
SwarmOpts clones hop by hop.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main feature addition: new Image and ResolvedImage fields to SwarmOpts, which aligns with the primary changes in the PR.
Description check	✅ Passed	The PR description includes Summary, Changes, Testing, Checklist sections, and issue link, following the template structure with substantive content for each section.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch PLAT-596-add-image-version-fields-to-database-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codacy-production]

Up to standards ✅

🟢 Issues 1 medium

Results:
1 new issue

Category	Results
Complexity	1 medium

View in Codacy

🟢 Metrics 0 duplication

Metric	Results
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

Actionable comments posted: 0