fix(history): model sparse publication without relaxing live freshness

docs/netplan-v4-history-timing.md

@@ -0,0 +1,90 @@
+# Historical publication timing (2026-10-03)
+
+## Implemented scope
+
+`services/netplan-v4/netplan_v4/history_timing.py` implements optional, bounded
+retrospective estimates between consecutive identical source values at DIFFERENT
+original publication timestamps. It is used by the existing measurement pipeline,
+model training and forecast source substitution. It is NOT a real-time estimator,
+a measurement certificate, an actuator authority or a repair of device communications.
+
+No source `maxAgeSeconds` is changed. When a regular hold expires, only its tail
+until the next qualifying original publication may be estimated. Strict processing
+remains the default. The following forbid the estimate: unequal endpoints,
+nonfinite/missing observations, conflicting same-timestamp values, collector gaps,
+invalid source intervals or a span beyond the explicit source-specific bound.
+There is no extrapolation past the last observation and no fabricated zero.
+
+Each window reports `publicationEstimatedSeconds`, per-source estimated portions,
+uncovered-source seconds and `availableNotBefore`. Training/validation must not use
+a confirmation or receipt before it was actually available. Backfilled windows
+cannot establish a supposedly causal holdout at a date before their availability.
+All physical windows remain configured estimates; even full support is not proof
+that the physical waveform stayed constant between the two endpoint readings.
+
+## Evidence and model assumptions
+
+Read-only source configuration projection on the test server, snapshot
+2026-10-03T07:47:24Z: GoodWe 1 instance 19742 (ModBus Device) has Poller 60000 ms;
+GoodWe 2 instance 57658 has Poller 5000 ms; SolarEdge scale instance 48996
+(ModBus Address) has Poller 20000 ms. No polling setting was changed.
+Projection program: /srv/agent/netplan-v4-application-build/inspect_source_update_policy.py.
+
+Official Symcon documentation accessed on 2026-10-03:
+https://www.symcon.de/de/service/dokumentation/modulreferenz/geraete/modbus-rtu-tcp/vorlagen/
+It documents value publication for ModBus Device on changes or when the variable is
+older than 60 seconds, including ordinary and virtual addresses. VariableUpdated
+is therefore not automatically the last successful device poll. The documentation
+is not a proof that a particular installed device link was healthy.
+
+Explicit Lihrenmoos HISTORICAL estimate bounds:
+- GoodWe 1 PV/physical storage: equal original publications at most 130 s apart
+  (60 s publication suppression + configured 60 s poll + 10 s scheduling allowance).
+- GoodWe 2 PV/physical storage: at most 75 s (60 + 5 + 10).
+- SolarEdge scale: equal scale publications at most 90 s apart. This is a modelling
+  bound based on the configured 20 s polling and observed sparse scale publication,
+  not a manufacturer guarantee and not proof of the same internal implementation
+  as ModBus Device. Raw AC power remains under the original strict limit.
+The 10 s margins are explicit scheduling assumptions, NOT measured timing guarantees.
+Gaps of many minutes (e.g. the previously observed GoodWe gaps above 600 s) are NOT
+bridged. Nonzero changes are never interpolated by this policy.
+
+## Versioned dataset without restarting collection
+
+`lihrenmoos-physical-published-v2` references immutable observations in
+`lihrenmoos-physical-v1`. No observations are copied, deleted, relabelled or resent.
+Registration requires the same installation and identical original mapping,
+formula, coverage and training configuration. Cycles/reference chains and device
+uploads directly into a derived dataset are rejected. Original ingestion continues
+unchanged in the Manager. The 24 usable-hour minimum stays in force.
+
+Models/windows are stored separately for v1/v2 and record their timing policy. An
+existing selected model/family is not automatically switched by this release.
+The current SDL request still uses the strict current-state requirements; no
+historical bridge grants a future SDL schedule or a live battery permission.
+
+## Tests and release
+
+254 isolated Python tests passed (219 previous + 35 new including simulated
+installation/recovery). Includes the actual service pipeline from referenced
+observations to model and optimizer using synthetic records. No new target-container
+or field-history evaluation has been run with this release yet; do not infer an
+improved real coverage percentage or production acceptance from unit tests.
+Evidence: /home/agent/services/qa/history-timing-20261003/ALL_TEST_RESULTS.txt.
+
+Prepared command on enelix-services (root required for Docker):
+
+    python3 /home/agent/services/netplan-v4-shadow/commissioning/deploy_history_timing.py \
+      --plant e3a08f9e-af12-4695-99bd-8b51c0520021 --apply
+
+Default without --apply validates staged source only. The apply path backs up source
+files, builds and runs the exact target tests, backs up the V4 SQLite database, and
+recreates ONLY the V4 service. A failed test restores source without a service
+restart; failed post-deploy validation attempts the previous image and preserves
+additive data. Concurrently modified files are not silently overwritten.
+
+No portal/forecast/tariff/Symcon restart, no new sensor requests, no change to
+161.44 kWh / 39 kW, SOC accounting, old raw samplers or actuator permissions.
+The new dataset is registered but not selected for the active forecast. A root
+execution and successful report are still required to install it. Previous release
+manifests remain historical records; do not bypass them to reapply an older build.