Generalize live material consumption architecture

PROJECT_KNOWLEDGE.md

@@ -3,8 +3,12 @@
 ## Purpose
 
 This service is a calculation and persistence layer between ENLYZE and
-Grafana. It must not become a second historian: raw process data stays in
-ENLYZE and is retrieved again when historical calculations need reproduction.
+Grafana. Its primary use case is to continuously integrate material consumption
+for the currently active production order and expose its cumulative value in
+Grafana while production is running. K7 fiber is the first validated
+application, not the scope of the product. It must not become a second
+historian: raw process data stays in ENLYZE and is retrieved again when
+historical calculations need reproduction.
 
 ## Core architectural decisions
 
@@ -16,6 +20,17 @@ ENLYZE and is retrieved again when historical calculations need reproduction.
   configuration are committed.
 - Calculations are modular, testable Python implementations. Configuration
   declares instances; it is not a generic low-code language.
+- Historical production-order analysis/backfill is secondary. It uses the same
+  generic integration engine as live processing: one integration engine with
+  live incremental and historical replay/backfill operating modes.
+
+## Material-consumption integration
+
+The core calculation is generic rate integration: cumulative material
+consumption increases by `material_rate * elapsed_time` when the configured
+machine/process-specific validity or gating conditions are satisfied. It is
+reusable across machines, materials, rate variables, units, and gates. The
+project deliberately does not define a broader configuration schema here.
 
 ## Peak-cycle detector
 
@@ -60,18 +75,72 @@ fixtures only.
 ## Central domain context
 
 Production orders connect machine, article/material, source interval, and
-derived results. Metrics and events must retain calculation type/version and
-source-time-range provenance.
+derived results. An ENLYZE Production Run is a time segment; one
+`production_order` can have one or more Production Runs. Integrate each run
+separately, then aggregate derived values on the production-order level. Never
+implicitly bridge gaps between runs. Metrics and events must retain calculation
+type/version and source-time-range provenance.
+
+## K7 fiber integration
+
+The current K7 candidate fiber mass-flow signal is `Stundenleistung Anlage`
+in kg/h. Observed behaviour supports treating it as a process-responsive
+band-scale signal, but it can remain frozen at a non-zero value during a
+machine stop. It must therefore be integrated only while the validated gate
+`Geschwindigkeit Gesamtanlage > 0.5 m/min` is active. The ENLYZE boolean
+`Anlage läuft` is not the primary integration gate.
+
+The process-derived result is `fiber_feed_kg` for a Production Run. It is not
+automatically a finished-product mass or a per-order material yield. Material
+measured at the band scale may still be in the machine at an order transition,
+and ERP feedback can arrive asynchronously or periodically. Differences from
+reported finished-product quantities must not automatically be labelled scrap;
+an exact per-order yield needs WIP/transport-delay accounting.
+
+## Bento 1 bentonite-powder integration
+
+Bento 1 bentonite-powder consumption is the next planned application of the
+same generic integration mechanism. Its ENLYZE source variable and its
+validity/gating logic have not yet been selected or validated; both must be
+determined from Bento 1 process data before implementation. Bento 1 does not
+need a separate subsystem or calculation formula.
+
+## Quantity-total interpretation
+
+For this customer setup, `production_run.quantity_total` is populated from
+ERP/BI production feedback received by ENLYZE, rather than necessarily being
+calculated from machine signals. The tested source CSV field is
+`PCO_FEEDB_QUANTITY`. For inspected machines/articles it represents reported
+finished-product area in m² (for example, 5.00 m × 50 m = 250.00 m²; 4.75 m ×
+50 m = 237.50 m²; 5.80 m × 50 m = 290.00 m²). The unit displayed by ENLYZE is
+separately configured and must not be considered authoritative until its
+configuration is validated.
 
 ## Known versus unknown
 
-Known from the ENLYZE UI: machine identity, operational/downtime state,
-current production order, article/material number, and process signals exist.
-It is **not yet verified** how, or whether, each is exposed by the ENLYZE API.
-Do not infer endpoint paths, authentication mechanisms, identifiers, paging,
-timestamp semantics, or signal payloads. The active open-question list is in
+Validated K7 historical tests show physically plausible fiber-feed totals when
+the band-scale kg/h signal is speed-gated. For production order
+`K 7-12026000842`, its run from 2026-08-31T10:57:54Z to
+2026-08-31T18:23:11Z had ERP `quantity_total` of 12,420 m², approximately
+5.206 active hours, approximately 5,180.1 kg integrated fiber feed,
+approximately 2,174.2 m integrated machine length, and approximately
+995.1 kg/h average active throughput. Article external ID `213408` has width
+6.0 m and static mean basis weight 390.16 g/m²; the corresponding approximate
+reported finished-product mass is 4,845.8 kg. This is a plausibility validation
+case, not a precise material-yield calculation.
+
+Known from the ENLYZE UI/API exploration: machine and product identity,
+Production Runs, and relevant K7 process signals are available. Some API and
+time-series semantics remain unverified; do not infer them beyond documented
+evidence. The active evidence and open-question list is in
 [docs/enlyze-api.md](docs/enlyze-api.md).
 
+## Future refinement
+
+An optional future historical mass-balance refinement is to obtain actual
+QA/QS basis-weight measurements from SQL instead of using static article basis
+weight. It is not a blocker for the live material-consumption MVP.
+
 ## Exploration workflow
 
 A deliberately generic, read-only CLI is available as
@@ -85,5 +154,7 @@ authentication header; its value is never printed.
 
 Unmodified captures are local in ignored `data/raw/enlyze/`. Fixtures written
 to `fixtures/enlyze/` are sanitized, but must still be reviewed before commit.
-The deliverable is verified API observations and sanitized fixtures, not
-production calculations or database ingestion.
+The exploration deliverable is verified API observations and sanitized
+fixtures. The next product deliverable is live incremental material
+integration, using a generic material-rate integrator rather than a separate
+historical-only calculation path.