Enelix-EMS/docs/netplan-v4-application.md

V4 application data and forecast integration

Implemented application path

ManagerNetzfahrplanV4DatenTrait records the configured raw power/SOC/counter sources inside the existing Manager. This replaces the need for permanent standalone observation categories once the native delivery path has been accepted. It never issues device commands. New acquisition properties default disabled.

The private outbox at data/enelix-v4/<installationId> is append-only and delivery is acknowledged by dataset and capture time. Unacknowledged data survives network failures and 429 responses. The native payload budget is below the existing portal 1 MiB request-body limit. Existing authentication and V4 rate limiting are reused.

Server application source is now versioned under services/netplan-v4, rather than existing only as an untracked server working tree. No live measurements, databases, credentials, dependency binaries or settings exports are included in this directory.

The existing worker handles per-plant dataset ingestion, physical five-minute rollup, model training, model storage and corrected-load substitution into the V4 optimizer. It continues to consume the existing PV forecasts and price/operation inputs. The public device route can append measurements but cannot alter source meaning, register a dataset, change live permissions or arm a controlled trial.

Explicit settings and model meaning

• forecastSource=legacy preserves the existing forecast input by default.
• forecastSource=corrected_profile plus measurementDataset uses the trained corrected physical load. Missing models are reported; legacy house values are not substituted silently.
• trainingCadence=daily|weekly is now connected to real profile fitting in the application worker, independently from the optimizer refresh frequency.
• Corrected load profiles are tagged physical-profile-v1: robust daily profile, recent-day profile and weekday/weekend profile paired with PV families 3/13/23. They are not claimed to be the previous load models unchanged. Economic automatic selection still requires the separate, not yet finished cost-replay integration.
• Initial models are explicitly bootstrap models. Later candidates record causal holdout errors; an overlapping validation window cannot certify a promotion.
• Current SDL request persistence is only a labelled shadow scenario. Unknown or stale SDL is not silently zero, and the scenario is not a guaranteed future schedule or a robust SDL-aware production control policy.

Lihrenmoos package scope

Effective EV capacity 161.44 kWh and power 39 kW remain unchanged; SDL reserve is already excluded. The prepared dataset lihrenmoos-physical-v1 uses a configured physical estimate with SolarEdge signed terminal power counted once. It requires at least 24 equivalent usable hours before the first bootstrap profile; the history window is 28 days. Coverage policy 95% with maximum 10-second unsupported portion is an explicit modelling assumption. Gaps and source ages remain visible. It is not an independent electrical metering-boundary proof.

Server entry point on the service host:

python3 /home/agent/services/netplan-v4-shadow/commissioning/deploy_application.py \
  --plant e3a08f9e-af12-4695-99bd-8b51c0520021 --apply

Default without --apply checks source only. The explicit apply command rebuilds and tests V4 in Python 3.11, tests portal routing, backs up the V4 database and recreates only V4 and the portal. It configures the dataset but DOES NOT select it for the existing plan automatically. No forecasts/tariff importer or controllers are restarted by the server command. A previous-image rollback is prepared.

Then, inside Lihrenmoos Symcon:

require '/srv/agent/netplan-v4-application-build/install.php';

This is a data-only patch of the currently installed passive manager, with file backup and library reload. It does NOT install the development control-trial changes in Manager/Batterie. The first runtime invocation imports at most 48h of the existing 23-channel observer as a durable backlog, preserving the original files, then activates acquisition and delivery. If Symcon module registration is not immediately available, the installer reports that a single repeat is needed.

The two temporary standalone samplers are not stopped automatically by this initial package; disable them only after native batch acceptance and history continuity are confirmed. This package creates no new root diagnostic category.

Validation performed before deployment

219 Python tests passed in the isolated host QA runtime, including actual synthetic measurement -> profile -> existing optimizer -> stored shadow plan. 16 Node proxy checks passed. 21 PHP data-path checks and 5 installer scenarios passed with mocked IPS/HTTP and temporary files on the test host. Full staged PHP syntax passed. No new container or new manager data integration has yet been run in production.

Evidence: service APPLICATION_PIPELINE_TEST_RESULTS.txt, APPLICATION_PORTAL_TEST_RESULTS.txt, commissioning/application-source/RELEASE.json; test host netplan-v4-application-build/PREPARATION.json and TEST_RESULTS.txt.

Remaining product scope (do not disguise as complete)

This integrates application data and load forecasting, not completed production commissioning. Economic replay-based automatic family selection, full corrected feedback/control integration, long-term outbox/server retention and real live/ failure acceptance remain open. Existing trial gates are unchanged. No sensor, accounting or hardware evidence identifier is fabricated by data ingestion.

Installer class-path correction (2026-10-03)

The original commissioning installer loaded source/libs/NetzfahrplanV4Messaufnahme.php while importing observation history. A later Manager callback loads the installed copy at modules/Enelix-EMS/libs/NetzfahrplanV4Messaufnahme.php. PHP's once-only file inclusion does not deduplicate class declarations across those different files. The dependent NetzfahrplanV4Bilanzierung class is subject to the same collision.

The tested installer-only fix is preserved in examples/V4ApplicationData/application-class-loading.patch (SHA256 6d53d74d4059bb1ae3a446350637a4f4a4a73cc2fd64d2fc2f0967bd23ec7173). When building a commissioning package, load both classes only from the installed module tree, after validating their expected source hashes. Before any require, check both already-loaded origins without autoload. Reject a foreign staged origin with a controlled error; do not hide it by wrapping the class declaration in a guard. Include installed_capture_bootstrap.php in the package checksum map. Do not change the installed-module manifest or bless unrelated source changes.

The Lihrenmoos staging entrypoint has this fix applied, with backups of its original installer and checksum map. No running modules, data files, timers, native callbacks, server components or actuator settings were changed by the repair. Actual completion still requires the user's fresh Symcon invocation of the corrected installer.

Validation: the original two-path failure was reproduced with the real PHP classes. Thirteen additional isolated installer scenarios passed, including callback/reload loading order, preloaded dependencies, history import, repeat/finished import, foreign-class refusal, partial-import preservation, source drift, registration wait and first installation. These are PHP CLI tests with mocked IPS in temporary trees, not a completed test in the actual Symcon kernel.

Evidence on the test host: /srv/agent/netplan-v4-application-build/class-loading-fix/TEST_RESULTS.json and FIX_RESULT.json. The test harness and exact candidate source are retained there.