Lumi/docs/update-audit-0.2.0.md

0.2.0 Update Compatibility Audit

This audit compares pre-merge main (1173b8a, core 0.1.9) with the initially published merge (c917615, incorrectly numbered 1.2.0). The merge changed 191 files: 75 core/runtime files, 85 plugin files, 20 generated knowledge files, and 11 other project files.

Confirmed Upgrade Failures

1. Core imported an independently preserved plugin. src/web/server.js loaded plugins/okf/backend/file_knowledge during startup. Core-only updates deliberately preserve the whole plugins/ directory, so a 0.1.9 install did not receive the new OKF plugin file and crashed before the web server started.
2. A newly added package was required before dependencies were updated. The OBS connector loaded obs-websocket-js at module initialization. Core updates preserve node_modules/ and the old updater did not reconcile it with the new lockfile, producing another startup crash.
3. Core and plugin delivery were not coordinated. The merged repository had patch-bumped plugins, but a core update copied none of them by design. There was no historical release catalog or exact-version plugin installer to let an administrator bring an old installation to a known release set.
4. The release number was wrong. 1.2.0 was a mistaken major-version jump from 0.1.9. Normal semantic-version ordering would reject the corrected 0.2.0 as a downgrade for an already affected install.

No unresolved static relative imports remain in the repaired tree. Plugin data remains isolated under each plugin's data/ directory, and current plugin manifests match the 0.2.0 release catalog.

Repairs

• Core now uses the OKF capability registered at global.lumiFrameworks.okf.saveCorrection; if OKF is absent, only that action shows an install/enable message.
• OBS WebSocket is an optional dependency and is loaded behind a guarded connector boundary. Its absence cannot stop the overlay or web server.
• run.js reconciles required direct dependencies with package-lock.json before each application start. Optional integration failure is degraded, not fatal.
• release-index.json maps core, plugin, and Lumi AI tool versions to immutable release tags. Admins can install or reinstall an exact core/plugin version.
• update-manifest.json declares 0.2.0 as the supported replacement for 1.2.0, allowing affected installations to repair themselves despite semver ordering.
• Repository checkout and post-copy verification both confirm the requested version. Plugin updates preserve plugin data and now restart before reporting the selected code as active.

Data Safety

The repair does not replace data/, plugins/, node_modules/, configuration, storage, uploads, logs, databases, secrets, environment files, knowledge/community/, or knowledge/corrections/. It creates a compressed rollback snapshot first. The repair ZIP contains only managed core files, a preservation manifest, and SHA-256 hashes; it contains no user or plugin data.

The snapshot database copy is a safety backup, not a migration or replacement. The repair introduces no destructive database migration.