@yarkivaev/scada 2.4.8 → 2.5.0

package/README.md

@@ -420,7 +420,7 @@ await runtime.stop();
 
 Adapters include `stream` (registered source/transform/sinks), `modbus`,
 `activity`, `amqp-relay`, `amqp-metrics`, `mqtt-metrics`, `operation-sync`,
-`amqp-pg-metrics`, `silent-streams` and `stomp-ingest`. Plant packages extend the
+`amqp-pg-metrics`, `mqtt-pg-metrics`, `silent-streams` and `stomp-ingest`. Plant packages extend the
 registry with domain-specific adapters; OPC UA belongs here, not in
 source-to-sink. Constructors do not open connections. A task owns independent
 connections and must close them in `stop()`. Factories are trusted code, not
@@ -439,8 +439,11 @@ Secrets can be references such as `{ "$secret": "AMQP_URL" }`, resolved by the
 host immediately before adapter construction. Status excludes configuration and
 exception messages. Optional `COLLECTOR_HEALTH_PORT` and
 `COLLECTOR_HEALTH_HOST` (default `127.0.0.1`) expose read-only `/live`, `/ready`
-and `/status`. Readiness represents admission, not the health of every remote
-server. Fatal cleanup makes liveness fail. A blocked event loop cannot answer
+and `/status`. Readiness rejects failed or degraded tasks as well as runtime
+shutdown. Fatal cleanup or an uncertain MQTT acceptance/write timeout makes
+liveness fail; configure an external restart policy. Transient MQTT errors mark
+the task degraded until broker reconnect; terminal timeouts require a fresh
+executor after the old process drains its IO. A blocked event loop cannot answer
 an external probe; synchronous infinite loops/native crashes still affect the
 entire process. No hard CPU or native-memory isolation is claimed.
 
@@ -464,6 +467,23 @@ deduplicate. Sources with a non-null checkpoint must implement `restore()`;
 unsupported restoration fails closed. Live telemetry cannot replay downtime.
 Loki fails a saturated page rather than silently advancing across truncated data.
 
+`mqtt-pg-metrics` uses `{ mqtt, postgres, topic, options, limits }`. URLs may be
+secret references; `options.clientId` and `options.sessionExpiryInterval` preserve
+an existing persistent MQTT session. Records use the existing numeric/JSON metric
+decoder and are acknowledged after PostgreSQL writes. Runtime limits bound accepted
+records and bytes; a one-record budget works without reserving the record twice.
+
+The `modbus` adapter also accepts `config.plans`, one non-empty `[{ point, topic }]`
+array per device. For example, `plans: [[{ point: 'holding:4000:cdab',
+topic: 'existing/device/voltage' }]]` publishes that exact wire topic. Points must
+use `holding:<integer>[:abcd|cdab]` within the 16-bit register address range.
+Explicit plans replace `maps`; mixing the two or repeating a topic is rejected.
+All devices still share one poll window.
+
+Collector state is optional for live-only assignments. Ordinary supervisor-sink
+business migrations skip collector state and never delete an existing state table.
+Call `migrate(pool, migrationsDir, profile, { runtimeState: true })` only when
+explicitly enabling task-state storage, or apply its SQL separately.
 The runner accepts `COLLECTOR_STATE_URL` for PostgreSQL. Apply
 `db/migrations/V0009__collector_task_state.sql` explicitly and grant the service
 role access before starting stateful assignments; the runner never runs schema
@@ -522,3 +542,40 @@ for idempotent replay. WAL durability remains enabled.
 counts, SQL-call count, and maximum transaction/wait durations. They contain no payloads or tags.
 Compare these counters with RabbitMQ ACK/drain rates and process memory when tuning. More messages
 per batch reduce COMMIT frequency; the number of SQL writes still depends on command semantics.
+
+## Ordered release stages
+
+`executeStages(stages, action = 'render', execute?)` runs ordered generic release
+plans. For `apply`/`adopt`, every stage is preflighted before the first mutation;
+each rollout and `afterReady`/`beforeApply` gate must finish before the next stage.
+Read-only actions do not invoke mutation gates. A plan may declare exact Deployment
+`retirements: [{ workload: 'deployment/old-reader', selector: 'app=old-reader' }]`
+and `podsAbsentBeforeApply` selectors to fence old readers before a replacement.
+Retirement waits for foreground deletion and verifies no matching pods remain;
+failures stop execution. Context, namespace and field manager remain explicit.
+
+The application chart accepts existing PostgreSQL/RabbitMQ claims, secret-backed
+environment values, `envFrom`, config volumes, probes and extra Kubernetes objects.
+PostgreSQL honors the root `pullSecret`. Existing claims are referenced without
+creating or deleting storage; plant packages supply their precise deployment values.
+
+### Per-server module configuration
+
+A server may override its profile's `modules`. Maps merge recursively; omitted
+fields are inherited, arrays replace, and null removes an inherited key.
+`state_store.pgdata` selects PostgreSQL's existing data directory and takes
+precedence over the compatible `state_store.chart.data` setting.
+
+```yaml
+servers:
+  - id: cell-a
+    modules:
+      state_store:
+        pgdata: /var/lib/postgresql/data/pgdata
+    profile:
+      id: cell
+      variables:
+        cluster: cell-a
+```
+
+This changes the selected server only; it does not mutate the shared profile.

package/charts/scada/templates/_helpers.tpl

@@ -94,3 +94,12 @@ volumeMode: Filesystem
 {{- define "scada.brokerConfigName" -}}
 {{- default (printf "%s-rabbitmq" (include "scada.prefix" .)) .Values.rabbitmq.configName -}}
 {{- end }}
+
+{{/* Literal env values remain strings; Kubernetes valueFrom references stay opaque. */}}
+{{- define "scada.envValue" -}}
+{{- if kindIs "map" . }}
+{{- toYaml . }}
+{{- else }}
+value: {{ . | quote }}
+{{- end }}
+{{- end }}

package/charts/scada/templates/extra-objects.yaml

@@ -0,0 +1,4 @@
+{{- range .Values.extraObjects }}
+---
+{{ toYaml . }}
+{{- end }}

package/charts/scada/templates/postgres.yaml

@@ -11,7 +11,7 @@ spec:
   ports:
     - name: postgres
       port: 5432
-      targetPort: postgres
+      targetPort: 5432
   selector:
     {{- include "scada.match" (dict "app" "postgres" "ctx" .) | nindent 4 }}
 ---
@@ -30,38 +30,75 @@ spec:
     matchLabels:
       {{- include "scada.match" (dict "app" "postgres" "ctx" .) | nindent 6 }}
   template:
+    {{- if .Values.postgres.podTemplate }}
+    {{- toYaml .Values.postgres.podTemplate | nindent 4 }}
+    {{- else }}
     metadata:
       labels:
         {{- include "scada.labels" . | nindent 8 }}
         {{- include "scada.match" (dict "app" "postgres" "ctx" .) | nindent 8 }}
     spec:
+      {{- with .Values.pullSecret }}
+      imagePullSecrets:
+        - name: {{ . }}
+      {{- end }}
       containers:
         - name: postgres
           image: {{ .Values.postgres.image | quote }}
+          {{- with .Values.postgres.command }}
+          command: {{ toJson . }}
+          {{- end }}
+          {{- with .Values.postgres.args }}
+          args: {{ toJson . }}
+          {{- end }}
           ports:
             - name: postgres
               containerPort: 5432
           env:
-            - name: POSTGRES_DB
-              value: {{ .Values.postgres.database | quote }}
-            - name: POSTGRES_USER
-              valueFrom:
-                secretKeyRef:
-                  name: {{ .Values.postgres.secret }}
-                  key: user
-            - name: POSTGRES_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: {{ .Values.postgres.secret }}
-                  key: password
-            - name: PGDATA
-              value: {{ .Values.postgres.data | quote }}
+            {{- $env := dict "POSTGRES_DB" .Values.postgres.database "PGDATA" .Values.postgres.data
+              "POSTGRES_USER" (dict "valueFrom" (dict "secretKeyRef" (dict "name" .Values.postgres.secret "key" "user")))
+              "POSTGRES_PASSWORD" (dict "valueFrom" (dict "secretKeyRef" (dict "name" .Values.postgres.secret "key" "password"))) }}
+            {{- range $key, $value := .Values.postgres.env }}
+            {{- $_ := set $env $key $value }}
+            {{- end }}
+            {{- $order := concat (list "POSTGRES_DB" "POSTGRES_USER" "POSTGRES_PASSWORD" "PGDATA") (without (keys $env | sortAlpha) "POSTGRES_DB" "POSTGRES_USER" "POSTGRES_PASSWORD" "PGDATA") }}
+            {{- range $key := $order }}
+            - name: {{ $key }}
+              {{- include "scada.envValue" (index $env $key) | nindent 14 }}
+            {{- end }}
+          {{- with .Values.postgres.envFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- range $key := list "readinessProbe" "livenessProbe" "startupProbe" "resources" }}
+          {{- with index $.Values.postgres $key }}
+          {{ $key }}:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- end }}
           volumeMounts:
             - name: data
               mountPath: /var/lib/postgresql/data
+            {{- with .Values.postgres.volumeMounts }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+      {{- if or .Values.postgres.existingClaim .Values.postgres.volumes }}
+      volumes:
+        {{- if .Values.postgres.existingClaim }}
+        - name: data
+          persistentVolumeClaim:
+            claimName: {{ .Values.postgres.existingClaim }}
+        {{- end }}
+        {{- with .Values.postgres.volumes }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- end }}
+  {{- end }}
+  {{- if not .Values.postgres.existingClaim }}
   volumeClaimTemplates:
     - metadata:
         name: data
       spec:
         {{- include "scada.claim" (dict "size" .Values.postgres.storage "class" .Values.postgres.storageClass) | nindent 8 }}
 {{- end }}
+{{- end }}

package/charts/scada/templates/processes.yaml

@@ -1,6 +1,7 @@
 {{- $names := dict }}
 {{- $devices := dict }}
 {{- range .Values.processes }}
+{{- $process := . }}
 {{- $name := required "process name is required" .name }}
 {{- if hasKey $names $name }}
 {{- fail (printf "duplicate process name %s" $name) }}
@@ -58,11 +59,22 @@ spec:
           image: {{ required "process image is required" (default $.Values.image .image) | quote }}
           imagePullPolicy: IfNotPresent
           command: {{ required "process command is required" .command | toJson }}
-          {{- with .health }}
+          {{- with .args }}
+          args: {{ toJson . }}
+          {{- end }}
+          {{- if or .ports .health }}
           ports:
+            {{- with .ports }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+            {{- with .health }}
             - name: health
               containerPort: {{ .port }}
               protocol: TCP
+            {{- end }}
+          {{- end }}
+          {{- with .health }}
+          {{- if not $process.livenessProbe }}
           livenessProbe:
             httpGet:
               path: {{ default "/live" .livenessPath | quote }}
@@ -71,6 +83,8 @@ spec:
             periodSeconds: {{ default 10 .periodSeconds }}
             timeoutSeconds: {{ default 2 .timeoutSeconds }}
             failureThreshold: {{ default 3 .failureThreshold }}
+          {{- end }}
+          {{- if not $process.readinessProbe }}
           readinessProbe:
             httpGet:
               path: {{ default "/ready" .readinessPath | quote }}
@@ -80,31 +94,50 @@ spec:
             timeoutSeconds: {{ default 2 .timeoutSeconds }}
             failureThreshold: {{ default 3 .failureThreshold }}
           {{- end }}
+          {{- end }}
+          {{- range $key := list "readinessProbe" "livenessProbe" "startupProbe" }}
+          {{- with index $process $key }}
+          {{ $key }}:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- end }}
           {{- if .hostDevices }}
           securityContext:
             privileged: true
+          {{- end }}
+          {{- if or .hostDevices .volumeMounts }}
           volumeMounts:
             {{- range $index, $path := .hostDevices }}
             - name: serial-{{ add1 $index }}
               mountPath: {{ $path | quote }}
             {{- end }}
+            {{- with .volumeMounts }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
           {{- end }}
           {{- with .env }}
           env:
             {{- range $key, $value := . }}
             - name: {{ $key }}
-              value: {{ $value | quote }}
+              {{- include "scada.envValue" $value | nindent 14 }}
             {{- end }}
           {{- end }}
+          {{- with .envFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
           resources:
             {{- toYaml (default $.Values.resources .resources) | nindent 12 }}
-      {{- with .hostDevices }}
+      {{- if or .hostDevices .volumes }}
       volumes:
-        {{- range $index, $path := . }}
+        {{- range $index, $path := .hostDevices }}
         - name: serial-{{ add1 $index }}
           hostPath:
             path: {{ $path | quote }}
             type: CharDevice
         {{- end }}
+        {{- with .volumes }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
       {{- end }}
 {{- end }}

package/charts/scada/templates/rabbitmq.yaml

@@ -40,6 +40,9 @@ spec:
     matchLabels:
       {{- include "scada.match" (dict "app" "rabbitmq" "ctx" .) | nindent 6 }}
   template:
+    {{- if .Values.rabbitmq.podTemplate }}
+    {{- toYaml .Values.rabbitmq.podTemplate | nindent 4 }}
+    {{- else }}
     metadata:
       labels:
         {{- include "scada.labels" . | nindent 8 }}
@@ -47,9 +50,14 @@ spec:
         {{- with .Values.workloadLabels }}
         {{- toYaml . | nindent 8 }}
         {{- end }}
-      {{- if .Values.rabbitmq.rolloutOnConfigChange }}
+      {{- if or .Values.rabbitmq.rolloutOnConfigChange .Values.rabbitmq.podAnnotations }}
       annotations:
+        {{- with .Values.rabbitmq.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+        {{- if .Values.rabbitmq.rolloutOnConfigChange }}
         checksum/config: {{ include (print $.Template.BasePath "/rabbitmq-config.yaml") . | sha256sum }}
+        {{- end }}
       {{- end }}
     spec:
       {{- with .Values.pullSecret }}
@@ -103,19 +111,23 @@ spec:
         - name: data
           persistentVolumeClaim:
             claimName: {{ . }}
----
-apiVersion: v1
-kind: PersistentVolumeClaim
-metadata:
-  name: {{ . }}
-  namespace: {{ $.Release.Namespace }}
-spec:
-  {{- include "scada.claim" (dict "size" $.Values.rabbitmq.storage "class" $.Values.rabbitmq.storageClass) | nindent 2 }}
-      {{- else }}
+      {{- end }}
+    {{- end }}
+  {{- if not .Values.rabbitmq.claimName }}
   volumeClaimTemplates:
     - metadata:
         name: data
       spec:
         {{- include "scada.claim" (dict "size" .Values.rabbitmq.storage "class" .Values.rabbitmq.storageClass) | nindent 8 }}
+  {{- end }}
+{{- if and .Values.rabbitmq.claimName .Values.rabbitmq.createClaim }}
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Values.rabbitmq.claimName }}
+  namespace: {{ .Release.Namespace }}
+spec:
+  {{- include "scada.claim" (dict "size" .Values.rabbitmq.storage "class" .Values.rabbitmq.storageClass) | nindent 2 }}
 {{- end }}
 {{- end }}

package/charts/scada/templates/site-server.yaml

@@ -9,6 +9,9 @@ metadata:
     app: site-server
 spec:
   replicas: 1
+  strategy:
+    type: Recreate
+    rollingUpdate: null
   selector:
     matchLabels:
       {{- include "scada.match" (dict "app" "site-server" "ctx" .) | nindent 6 }}
@@ -51,8 +54,17 @@ spec:
             {{- end }}
             {{- range .Values.env }}
             - name: {{ .name }}
+              {{- if .valueFrom }}
+              valueFrom:
+                {{- toYaml .valueFrom | nindent 16 }}
+              {{- else }}
               value: {{ .value | quote }}
+              {{- end }}
             {{- end }}
+          {{- with .Values.envFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
           readinessProbe:
             httpGet:
               path: /api/v1/machines

package/charts/scada/values.schema.json

@@ -6,29 +6,126 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "command"],
+        "required": [
+          "name",
+          "command"
+        ],
         "properties": {
-          "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" },
-          "command": { "type": "array", "minItems": 1, "items": { "type": "string" } },
-          "env": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+          },
+          "command": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "env": {
+            "type": "object",
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": [
+                    "string",
+                    "number",
+                    "boolean"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "valueFrom"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "valueFrom": {
+                      "type": "object",
+                      "minProperties": 1
+                    }
+                  }
+                }
+              ]
+            }
+          },
           "health": {
-            "type": "object", "required": ["port"], "additionalProperties": false,
+            "type": "object",
+            "required": [
+              "port"
+            ],
+            "additionalProperties": false,
             "properties": {
-              "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
-              "livenessPath": { "type": "string", "pattern": "^/" },
-              "readinessPath": { "type": "string", "pattern": "^/" },
-              "initialDelaySeconds": { "type": "integer", "minimum": 0 },
-              "periodSeconds": { "type": "integer", "minimum": 1 },
-              "timeoutSeconds": { "type": "integer", "minimum": 1 },
-              "failureThreshold": { "type": "integer", "minimum": 1 }
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "livenessPath": {
+                "type": "string",
+                "pattern": "^/"
+              },
+              "readinessPath": {
+                "type": "string",
+                "pattern": "^/"
+              },
+              "initialDelaySeconds": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "periodSeconds": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "timeoutSeconds": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "failureThreshold": {
+                "type": "integer",
+                "minimum": 1
+              }
             }
           },
           "hostDevices": {
-            "type": "array", "uniqueItems": true,
-            "items": { "type": "string", "pattern": "^/dev/([a-zA-Z0-9_-][a-zA-Z0-9_.-]*/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$" }
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^/dev/([a-zA-Z0-9_-][a-zA-Z0-9_.-]*/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$"
+            }
           }
         }
       }
+    },
+    "extraObjects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "apiVersion",
+          "kind",
+          "metadata"
+        ]
+      }
+    },
+    "postgres": {
+      "type": "object",
+      "properties": {
+        "podTemplate": {
+          "type": "object",
+          "description": "Opaque PodTemplateSpec override for preserving existing storage pods during adoption; empty uses generated defaults."
+        }
+      }
+    },
+    "rabbitmq": {
+      "type": "object",
+      "properties": {
+        "podTemplate": {
+          "type": "object",
+          "description": "Opaque PodTemplateSpec override for preserving existing storage pods during adoption; empty uses generated defaults."
+        }
+      }
     }
   }
 }

package/charts/scada/values.yaml

@@ -10,6 +10,8 @@ sink:
 workloadLabels: {}
 # Named deployments with command, env, optional resources and hostDevices.
 processes: []
+# Raw Kubernetes manifests; template expressions are not evaluated.
+extraObjects: []
 image: ""
 command: []
 pullSecret: ""
@@ -17,6 +19,8 @@ machines: []
 sites: []
 collectors: []
 env: []
+# Kubernetes envFrom references for the site API.
+envFrom: []
 extraLabels: {}
 service:
   port: 3000
@@ -26,6 +30,18 @@ postgres:
   enabled: true
   image: postgres:16
   secret: scada-postgres
+  # Existing PVC: no PVC or volumeClaimTemplate is created.
+  existingClaim: ""
+  env: {}
+  envFrom: []
+  command: []
+  args: []
+  volumeMounts: []
+  volumes: []
+  readinessProbe: {}
+  livenessProbe: {}
+  startupProbe: {}
+  resources: {}
   database: scada
   storage: 10Gi
   storageClass: ""
@@ -35,6 +51,8 @@ rabbitmq:
   deadLetter: null
   # A named standalone PVC replaces the default volumeClaimTemplates when set.
   claimName: ""
+  createClaim: true
+  podAnnotations: {}
   configName: ""
   rolloutOnConfigChange: false
   definitions: null

package/index.js

@@ -105,3 +105,5 @@ export { default as pointPaths } from './src/application/deploy/pointPaths.js';
 export { clusterOf, serverFor } from './src/application/deploy/releaseNodes.js';
 export { default as executeRelease } from './src/infrastructure/deploy/executeRelease.js';
 export { default as collectorProcesses } from './src/application/deploy/collectorProcesses.js';
+
+export { default as executeStages } from './src/infrastructure/deploy/executeStages.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.4.8",
+  "version": "2.5.0",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",

package/src/application/deploy/expandFlows.js

@@ -160,6 +160,7 @@ function draftOne(server, paths, mappings) {
         id: server.id,
         objects,
         ownership: server.ownership,
+        modules: server.modules,
         patternsIn: remote,
         patternsOut: server.fan_out || [],
         profile: server.profile,
@@ -238,6 +239,9 @@ function materialize(server) {
     if (server.service) {
         row.service = server.service;
     }
+    if (server.modules) {
+        row.modules = server.modules;
+    }
     return row;
 }
 

package/src/application/deploy/mergeDocuments.js

@@ -19,7 +19,7 @@ function isMap(value) {
  * @example
  *   mergeMaps({ secret: 'pg' }, { image: 'plant:1' });
  */
-function mergeMaps(left, right) {
+export function mergeMaps(left, right) {
     const value = { ...(left || {}) };
     Object.keys(right || {}).forEach((key) => {
         const next = right[key];

package/src/application/deploy/releaseNodes.js

@@ -1,3 +1,5 @@
+import { mergeMaps } from './mergeDocuments.js';
+
 /**
  * Reads an object entry as a path.
  *
@@ -114,7 +116,7 @@ export function profileFor(document, server) {
         throw new Error(`system document has no profile ${label}`);
     }
     const values = { ...(profile.variables || {}), ...(server.profile.variables || {}) };
-    return { ...profile, variables: values };
+    return { ...profile, ...(server.modules && { modules: mergeMaps(profile.modules, server.modules) }), variables: values };
 }
 
 /** Selects an explicitly named service or the sole service of the source. */

package/src/application/deploy/releaseValues.js

@@ -13,7 +13,8 @@ import { clusterOf, objectPath, serverById, serviceOf } from './releaseNodes.js'
  */
 function bindOne(name, spec, secret) {
     if (name === 'state_store') {
-        return ['postgres', { enabled: spec.enabled !== false, secret: secret || 'scada-postgres' }];
+        return ['postgres', { ...spec.chart, ...(spec.pgdata !== undefined && { data: spec.pgdata }),
+            enabled: spec.enabled !== false, secret: secret || 'scada-postgres' }];
     }
     if (name === 'message_bus') {
         return ['rabbitmq', { ...spec.chart, enabled: spec.enabled !== false,

package/src/application/runtime/additionalAdapters.js

@@ -1,5 +1,6 @@
 import ingestHealth from '../ingestHealth.js';
 import { clickhouseSink } from '../../infrastructure/streams/index.js';
+import mqttMetrics from '../../infrastructure/ingest/mqtt/mqttMetrics.js';
 import amqpMetricsIngest from '../../infrastructure/ingest/telemetry/amqpMetricsIngest.js';
 import operationSyncIngest from '../../infrastructure/sync/operationSyncIngest.js';
 import operationsFromPg from '../../infrastructure/persistence/pg/operations.js';
@@ -14,7 +15,7 @@ import alertPipeline from '../../infrastructure/ingest/pipelines/alertPipeline.j
 import resolveSecrets from './resolveSecrets.js';
 
 function urlOptions(spec) {
-    const protocols = { amqp: ['amqp:', 'amqps:'], stomp: ['stomp:', 'stomps:'],
+    const protocols = { mqtt: ['mqtt:', 'mqtts:', 'ws:', 'wss:'], amqp: ['amqp:', 'amqps:'], stomp: ['stomp:', 'stomps:'],
         postgres: ['postgres:', 'postgresql:'], clickhouse: ['http:', 'https:'] };
     Object.entries(protocols).forEach(([key, allowed]) => {
         const value = spec[key];
@@ -58,6 +59,20 @@ function metrics(spec, pool, context) {
     const sink = telemetry(spec, pool);
     return ownedSink(amqpMetricsIngest(spec.amqp, spec.queue, sink, { ...boundedOptions(spec), budget: context.budget }), sink);
 }
+function mqttPostgres(spec, pool, context) {
+    let failed = false;
+    context.report?.({ state: 'degraded' });
+    return mqttMetrics(spec.mqtt, metricsSinkFromPool(pool), spec.topic, {
+        ...boundedOptions(spec), budget: context.budget,
+        onReady() { if (!failed) { context.report?.({ state: 'running' }); } },
+        onError(error) {
+            // An uncertain write retires the executor. Reconnect cannot safely
+            // reuse the poisoned batch or overlap SQL still running in its pool.
+            failed ||= ['WRITE_TIMEOUT', 'OPERATION_TIMEOUT'].includes(error.code);
+            context.report?.({ state: failed ? 'failed' : 'degraded', fatal: failed });
+        }
+    });
+}
 function silent(spec, pool, context) {
     const sink = telemetry(spec, pool);
     const streams = silentStreams({ budget: spec.budget, interval: spec.interval,
@@ -143,6 +158,7 @@ export default function additionalAdapters() {
             return operationSyncIngest(spec.amqp, spec.queue, operationsFromPg(pool), { ...boundedOptions(spec), budget: context.budget });
         }, ['amqp', 'queue', 'postgres'])],
         ['amqp-pg-metrics', descriptor(metrics, ['amqp', 'queue', 'postgres'])],
+        ['mqtt-pg-metrics', descriptor(mqttPostgres, ['mqtt', 'topic', 'postgres'])],
         ['silent-streams', descriptor(silent, ['amqp', 'queue', 'sources'], silentConfig, (spec) => {
             return [...new Set(spec.sources.map((source) => { return `modbus-tcp:${source.host}:${source.port}`; }))];
         })],

package/src/application/runtime/runtimeHealth.js

@@ -4,7 +4,9 @@ import { monitorEventLoopDelay } from 'node:perf_hooks';
 function response(runtime, histogram, request, result) {
     if (!['/live', '/ready', '/status'].includes(request.url)) { result.writeHead(404).end(); return; }
     const state = runtime.status();
-    const ready = !state.fatal && !state.stopping;
+    const ready = !state.fatal && !state.stopping && !state.tasks.some((task) => {
+        return task.state === 'failed' || ['failed', 'degraded'].includes(task.health);
+    });
     const body = request.url === '/status' ? { ...state, memory: process.memoryUsage(), eventLoopP99Ms: histogram.percentile(99) / 1e6 } : { ready };
     result.writeHead((request.url === '/ready' && !ready) || (request.url === '/live' && state.fatal) ? 503 : 200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
     result.end(JSON.stringify(body));

package/src/infrastructure/deploy/executeRelease.js

@@ -22,6 +22,13 @@ function validate(plan, action) {
     }
     const fields = action === 'render' ? ['chart', 'release', 'namespace'] : ['chart', 'release', 'namespace', 'context', 'fieldManager'];
     validateRetirements(plan);
+    if (plan.podsAbsentBeforeApply !== undefined && (!Array.isArray(plan.podsAbsentBeforeApply)
+        || plan.podsAbsentBeforeApply.some((selector) => {
+            return typeof selector !== 'string' || !/^[A-Za-z0-9_./-]+=[A-Za-z0-9_.-]+(?:,[A-Za-z0-9_./-]+=[A-Za-z0-9_.-]+)*$/u.test(selector);
+        }))) { throw new Error('podsAbsentBeforeApply requires exact equality label selectors'); }
+    if (plan.beforeApply !== undefined && typeof plan.beforeApply !== 'function') {
+        throw new Error('beforeApply must be a function');
+    }
     fields.forEach((key) => {
         if (typeof plan[key] !== 'string' || !plan[key].trim()) { throw new Error(`release requires ${key}`); }
     });
@@ -63,8 +70,21 @@ function preflightRetirements(plan, action, kube, manifests) {
     }
 }
 
+/** Live gates run only for mutating actions, after all staged dry-runs. */
+function gateApply(plan, action, kube) {
+    if (['apply', 'adopt'].includes(action)) {
+        for (const selector of plan.podsAbsentBeforeApply || []) {
+            if (kube(['get', 'pods', '-l', selector, '-o', 'name'], undefined, true).trim()) {
+                throw new Error(`pods remain for ${selector}`);
+            }
+        }
+        plan.beforeApply?.(plan, kube);
+    }
+}
+
 /** Adopt legacy fields, then enforce the complete manifest before waiting for rollouts. */
 function applyRelease(plan, action, kube, manifests) {
+    gateApply(plan, action, kube);
     preflightRetirements(plan, action, kube, manifests);
     if (['adopt', 'check-adoption'].includes(action)) {
         applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], action === 'check-adoption');
@@ -86,6 +106,8 @@ function applyRelease(plan, action, kube, manifests) {
  * resource/name references. Optional retirements are { workload: "deployment/name",
  * selector: "app=label" }; callers bind these to the old declarative app. They are
  * removed after preflight and before any writes, with no selected pods remaining.
+ * podsAbsentBeforeApply equality selectors must have no pods before any mutation.
+ * beforeApply(plan, kube) provides caller-owned live gates; throwing stops writes.
  * afterReady(plan, kube) runs after a successful apply.
  */
 export default function executeRelease(plan, action = 'render', execute = execFileSync) {

package/src/infrastructure/deploy/executeStages.js

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process';
+import executeRelease from './executeRelease.js';
+
+/** Execute ordered full release plans, preflighting every stage before mutations.
+ * Stage rollout/afterReady and beforeApply gates must succeed before continuing.
+ * Read-only actions execute each stage without invoking mutation gates.
+ */
+export default function executeStages(stages, action = 'render', execute = execFileSync) {
+    if (!Array.isArray(stages) || !stages.length) { throw new Error('stages must be a nonempty array'); }
+    if (['apply', 'adopt'].includes(action)) {
+        for (const stage of stages) {
+            // SSA can claim legacy fields only after the stage's CSA handoff.
+            // Validate all stages without mutating their current ownership first.
+            executeRelease(stage, action === 'adopt' ? 'check-adoption' : 'check', execute);
+        }
+    }
+    return stages.map((stage) => { return executeRelease(stage, action, execute); });
+}

package/src/infrastructure/ingest/db/migrate.js

@@ -3,8 +3,9 @@ import path from 'path';
 import { migrationApplies, migrationSinkRunnable } from './migrationProfile.js';
 /* eslint-disable no-await-in-loop */
 
-function migrationSelected(name, profile, privileged) {
-    if (!name.endsWith('.sql') || !migrationApplies(name, profile)) {
+function migrationSelected(name, profile, privileged, options) {
+    if (!name.endsWith('.sql') || !migrationApplies(name, profile)
+        || (name === 'V0009__collector_task_state.sql' && options.runtimeState !== true)) {
         return false;
     }
     const sinkRunnable = migrationSinkRunnable(name);
@@ -20,10 +21,10 @@ async function ensureMigrationsTable(pool) {
     `);
 }
 
-async function applyMigrationFiles(pool, migrationsDir, profile, privileged) {
+async function applyMigrationFiles(pool, migrationsDir, profile, privileged, options = {}) {
     const files = (await fs.readdir(migrationsDir))
         .filter((name) => {
-            return migrationSelected(name, profile, privileged);
+            return migrationSelected(name, profile, privileged, options);
         })
         .sort((left, right) => {
             return left.localeCompare(right);
@@ -52,16 +53,17 @@ async function applyMigrationFiles(pool, migrationsDir, profile, privileged) {
 }
 
 /**
- * Applies SQL migrations runnable as supervisor_sink.
+ * Applies SQL migrations runnable as supervisor_sink. Collector state is opt-in.
  *
  * @param {object} pool - pg.Pool instance.
  * @param {string} migrationsDir - absolute path to migration files.
  * @param {string} [profile] - central or edge; filters E/C prefixed files
+ * @param {object} [options] - runtimeState: true explicitly includes collector task state
  * @returns {Promise<void>}
  */
-export default async function migrate(pool, migrationsDir, profile = 'edge') {
+export default async function migrate(pool, migrationsDir, profile = 'edge', options = {}) {
     await ensureMigrationsTable(pool);
-    await applyMigrationFiles(pool, migrationsDir, profile, false);
+    await applyMigrationFiles(pool, migrationsDir, profile, false, options);
 }
 
 /**

package/src/infrastructure/ingest/mqtt/modbusPublish.js

@@ -198,6 +198,32 @@ function oneWindow(rows, plans, config) {
  * @returns {Array<Array<{point: string, topic: string}>>} plans
  */
 function plansFor(rows, config) {
+    if (config.plans !== undefined) {
+        if (!Array.isArray(config.plans) || config.plans.length !== rows.length
+            || config.plans.some((plan) => { return !Array.isArray(plan) || plan.length === 0; })) {
+            throw new TypeError('Publish plans must contain one non-empty array per device');
+        }
+        if (config.maps?.length) { throw new TypeError('Explicit plans cannot be combined with MAPPING'); }
+        const topics = new Set();
+        return config.plans.map((plan) => {
+            return plan.map((item) => {
+                if (!item || typeof item.point !== 'string' || typeof item.topic !== 'string'
+                    || !item.topic.trim() || /[+#\0]/u.test(item.topic)) {
+                    throw new TypeError('Publish plan requires a register point and a concrete MQTT topic');
+                }
+                if (!/^holding:\d+(?::(?:abcd|cdab))?$/u.test(item.point)) {
+                    throw new TypeError(`Invalid register point: ${item.point}`);
+                }
+                const parsed = parsePoint(item.point);
+                if (!Number.isSafeInteger(parsed.address) || parsed.address + parsed.width > 65536) {
+                    throw new TypeError(`Register point exceeds holding-register bounds: ${item.point}`);
+                }
+                if (topics.has(item.topic)) { throw new TypeError(`Duplicate publish topic: ${item.topic}`); }
+                topics.add(item.topic);
+                return { point: item.point, topic: item.topic };
+            });
+        });
+    }
     return rows.map((row, index) => {
         return measurementPlans(streamOf(config, index), mapOf(config, index));
     });
@@ -225,7 +251,9 @@ function assertPublish(mqtt, config) {
 }
 
 /**
- * Polls Modbus and publishes measurements named by STREAM and MAPPING.
+ * Polls Modbus and publishes explicit per-device plans or STREAM and MAPPING.
+ * config.plans is an array of [{ point, topic }] arrays aligned with devices.
+ * Explicit plans replace generated mappings; combining the two is rejected.
  *
  * A point is `holding:<pdu>`, `holding:<pdu>:abcd`, or `holding:<pdu>:cdab`.
  * The topic is the document path `stream/parameter`. Devices come from

package/src/infrastructure/ingest/mqtt/mqttMetrics.js

@@ -47,10 +47,17 @@ export default function mqttMetrics(mqtt, sink, topic, config) {
     if (!config || typeof config !== 'object') {
         throw new Error('Config must be an object');
     }
-    const collector = ingestBatch(sink, { ...config, size: 1 });
+    // The source owns one lease through durable acceptance. Reserving again in
+    // the batch would reject every message at a one-record runtime budget.
+    const { budget, ...batchConfig } = config;
+    const collector = ingestBatch(sink, { ...batchConfig, size: 1 });
     const transformer = metricsCodec(collector);
     const source = mqttSource(mqtt, topic, transformer, {
-        budget: config.budget,
+        budget,
+        onError: config.onError,
+        onReady: config.onReady,
+        ...(config.acceptTimeoutMs === undefined ? {} : { acceptTimeoutMs: config.acceptTimeoutMs }),
+        ...(config.stopTimeoutMs === undefined ? {} : { stopTimeoutMs: config.stopTimeoutMs }),
         prefetch: config.prefetch,
         maxPacketBytes: config.maxBytes,
         clientId: config.clientId,

package/src/infrastructure/streams/mqttSource.js

@@ -10,6 +10,11 @@ function report(options, error) {
 }
 function bind(live, collector, options) {
     live.client.on('error', (error) => { report(options, error); });
+    for (const event of ['offline', 'close']) {
+        live.client.on(event, () => {
+            if (live.active) { report(options, new Error('MQTT source disconnected')); }
+        });
+    }
     // MQTT.js serializes handleMessage and sends PUBACK/PUBCOMP only on successful completion.
     live.client.handleMessage = (packet, callback) => {
         const accepted = Promise.resolve().then(() => {
@@ -34,7 +39,17 @@ function open(url, list, collector, options) {
     const live = { client, active: true, pending: new Set(), controller: new AbortController() };
     bind(live, collector, options);
     client.on('connect', () => {
-        if (live.active) { client.subscribe(list, { qos: options.qos ?? (options.clientId ? 1 : 0) }); }
+        if (live.active) {
+            client.subscribe(list, { qos: options.qos ?? (options.clientId ? 1 : 0) }, (error, granted) => {
+                if (!live.active) { return; }
+                if (error || granted?.some((entry) => { return entry.qos >= 128; })) {
+                    report(options, error ?? new Error('MQTT subscription denied')); return;
+                }
+                try { options.onReady?.(); } catch {
+                    // Diagnostics cannot break transport callbacks.
+                }
+            });
+        }
     });
     return live;
 }