Connector Config — Schema versioning leaf and migration (boost.connectors.__schemaVersion)

[mareklibra]

Labels: ready-to-code (when starting), workspace/boost, feature
Depends on: #4044 (connector leaves exist)
Priority: P2 — no connector DB overrides exist yet; safe to land after #4044
RHIDP Stories: RHIDP-15340 (deferred slice) + OpenSpec group 9
Feature: RHDHPLAN-1513 — Epic RHIDP-15332
Parent gate: #4044 implementation gate (OUT → this issue)

Why (single scope)

#4044 bumps global BOOST_CONFIG_SCHEMA_VERSION and registers v1 connector leaves. OpenSpec also calls for:

• per-connector metadata leaf boost.connectors.<id>.__schemaVersion (configScope: db-only, excluded from normal per-leaf Zod product validation / must survive validateStoredValues())
• migration when stored connector schema version < current
• tests + docs for future v1→v2 field changes

There is no prior connector override data to migrate at first ship — implementing migration in #4044 would be speculative. Isolate it here.

In

From openspec/changes/connector-config-hot-reload/tasks.md:

• Task 2.8 (migration logic) and group 9 (9.1–9.3)
• Spec scenarios in specs/config-schemas/spec.md under Schema Versioning / migration (not the basic leaf registration covered by Connector Config — Zod Schemas and RuntimeConfigResolver Extension (issue 6 of 29) #4044)
• Register __schemaVersion leaves for jira/github/gitlab as db-only
• Document how connector field renames/removals bump version and run migration
• Unit tests: missing version → treat as v1; v1→v2 migration hook (can be a no-op transform plus version bump until a real breaking change exists)

Out

• Initial connector leaf schemas / defaults / URL-cron validation (Connector Config — Zod Schemas and RuntimeConfigResolver Extension (issue 6 of 29) #4044)
• Health reader handoff (TBD-SUB-1)
• Hot-reload (Hot-Reload Propagation to Active Connectors (issue 22 of 29) #4060), admin UI (Connector Config Admin UI (issue 28 of 29) #4066)

Specs

• openspec/changes/connector-config-hot-reload/specs/config-schemas/spec.md (Schema Versioning)
• openspec/changes/connector-config-hot-reload/tasks.md group 9

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 8:08 AM UTC · Completed 8:10 AM UTC

Commit: ff6683f · View workflow run →

[fullsend-ai-triage]

This issue is blocked on #4044 (Connector Config — Zod Schemas and RuntimeConfigResolver Extension), which is still open with no PR in progress. The issue body explicitly gates this work on #4044 landing first, since the schema versioning leaf and migration logic depend on the connector leaf registration and BOOST_CONFIG_SCHEMA_VERSION bump introduced there.

Once #4044 merges, this issue will be unblocked and ready for implementation.

Blocked by:

• Connector Config — Zod Schemas and RuntimeConfigResolver Extension (issue 6 of 29) #4044

---

Labels: The issue is a feature request in the boost workspace, blocked on prerequisite work. Applying feature and workspace/boost labels per issue metadata, plus blocked to reflect the dependency on #4044.

[mareklibra]

The #4044 is merged now.

[mareklibra]

/fs-triage

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 11:43 AM UTC · Completed 11:46 AM UTC

Commit: e6c850f · View workflow run →

[fullsend-ai-triage]

The prerequisite #4044 has merged — this issue is now unblocked and ready for implementation.

Proposed test cases

1. Missing __schemaVersion → treat as v1, write v1 explicitly
2. Stored __schemaVersion < current → run migration hook, bump stored version
3. v1→v2 migration hook: no-op transform preserving all fields + version bump
4. __schemaVersion leaf excluded from normal Zod product validation
5. __schemaVersion survives validateStoredValues() without being stripped

References: openspec/changes/connector-config-hot-reload/specs/config-schemas/spec.md (Schema Versioning section) and tasks.md group 9 (tasks 9.1–9.3).

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[mareklibra]

/fs-code