deploy gap: occ upgrade does not apply register schema changes — new schemas/fields silently missing on existing installs

[rubenvdlinde]

Found by live testing the 2026-07-23 market-gap wave on a real instance (NC 34, 8080) on 2026-07-24.

What happened

Deployed the development head (all 8 wave changes) to a live instance, bumped appinfo/info.xml 0.2.17 → 0.2.18, ran occ upgrade. The upgrade reported success and ran InitializeSettings ("Updated to 0.2.18").

But none of the wave's register changes reached OpenRegister:

• bioMaatregel and sbomComponent schemas: not created
• module: missing all 7 new properties (bbnLevel, dpiaStatus, dpiaDate, dpiaVolgendeBeoordeling, dpiaDocumentRef, verwerkingsregisterRef, eolProductSlug)
• gebruik: missing all 3 TIME fields (timeClassification, timeRationale, timeReviewDate)

Every one of those features is therefore dead on an upgraded instance, while looking green in CI.

Only an explicit forced import fixed it:
POST /api/settings/import {"force": true} → schemas created (bioMaatregel 5036, sbomComponent 5037), all properties present, magic tables auto-created.

Why this matters

lib/Settings/softwarecatalogus_register.json is the delivery vehicle for every schema change in the app. If a normal app upgrade doesn't apply it, every future OpenSpec change that touches the register ships dead to existing installations. This is the orphaned-capability / green-but-dead defect class.

Suspected cause

SettingsService::loadSettings() gates ConfigurationService::importFromApp() on the register JSON's own info.version (+ a fragment signature), not the app version. On this instance the JSON was already at 2.4.0 while OpenRegister had 2.3.1+frag.9003c029 stored — the versions differed, so a re-import should have happened, yet no schema changes were applied and no import log line appeared. Also note there are three duplicate Software Catalog Register configuration rows in oc_openregister_configurations (ids 7, 117 at 2.3.1+frag.9003c029, id 81 at 2.3.0) which may be confusing the version gate.

Asks

1. Make an app upgrade reliably apply register changes (or make a failure loud instead of silent).
2. Investigate/clean up the duplicate configuration rows.
3. Add a post-upgrade assertion (repair-step warning or admin health check) that the live schema set matches the shipped register JSON, so a silent no-op is visible.

[rubenvdlinde]

Closed end-to-end by #396 (version signature now includes the monolith hash + fixed the broken semver-vs-content-version gate) plus #400 (force the import when the computed version differs).

Live-verified on NC 34 via the non-forced path only: adding a throwaway property to a register.d fragment and calling GET /api/settings/load (force=false) landed it in the database; removing it reverted the schema and the stored version exactly.

Upstream root cause remains open as ConductionNL/openregister#2075 — importFromApp(force:false) advances the stored configuration version without applying changes to existing schemas. #400 works around that for this app; the upstream fix is still worth having so the version can't advance on a partially-applied import.