@attraccess/plugin-wago 0.1.0-nightly.1081.1 → 0.1.0-nightly.1086.1

package/dist/index.js

@@ -3190,17 +3190,19 @@ function validEventPayload(data, kind, canonical) {
   return true;
 }
 function validStatePayload(data, kind, canonical) {
-  if (kind === "state" && data.manualOutputChannelIds !== void 0 && (!Array.isArray(data.manualOutputChannelIds) || data.manualOutputChannelIds.length > MAX_CHANNELS || !data.manualOutputChannelIds.every(identifier)))
+  if (kind !== "state") return true;
+  if (data.manualOutputChannelIds !== void 0 && (!Array.isArray(data.manualOutputChannelIds) || data.manualOutputChannelIds.length > MAX_CHANNELS || !data.manualOutputChannelIds.every(identifier)))
     return false;
-  if (canonical && kind === "state" && data.readiness !== void 0 && (!isObject(data.readiness) || data.readiness.hardwareAvailable !== void 0 && typeof data.readiness.hardwareAvailable !== "boolean"))
+  return !canonical || validCanonicalState(data);
+}
+function validCanonicalState(data) {
+  if (data.readiness !== void 0 && (!isObject(data.readiness) || data.readiness.hardwareAvailable !== void 0 && typeof data.readiness.hardwareAvailable !== "boolean"))
     return false;
-  if (canonical && kind === "state" && !(data.contentHash === null || typeof data.contentHash === "string" && /^[0-9a-f]{64}$/i.test(data.contentHash)))
+  if (!(data.contentHash === null || typeof data.contentHash === "string" && /^[0-9a-f]{64}$/i.test(data.contentHash)))
     return false;
-  if (canonical && kind === "state" && (typeof data.connected !== "boolean" || !(data.revision === null || Number.isSafeInteger(data.revision) && data.revision >= 0) || !isObject(data.outputs) || data.inputs !== void 0 && !isObject(data.inputs) || ![...Object.values(data.outputs), ...Object.values(isObject(data.inputs) ? data.inputs : {})].every(
+  return typeof data.connected === "boolean" && (data.revision === null || Number.isSafeInteger(data.revision) && data.revision >= 0) && isObject(data.outputs) && (data.inputs === void 0 || isObject(data.inputs)) && [...Object.values(data.outputs), ...Object.values(isObject(data.inputs) ? data.inputs : {})].every(
     (value) => typeof value === "boolean"
-  )))
-    return false;
-  return true;
+  );
 }
 function freshness(timestamp, now = Date.now(), maxAge = 9e4) {
   if (!timestamp) return "missing";
@@ -3785,27 +3787,13 @@ function wagoFlowPreview(config, kind, controller, snapshot, names) {
 function localizedPreview(config, kind, controller, snapshot, names, german) {
   const text = (english, translated) => german ? translated : english;
   const channel = snapshot?.logicalChannels.find((item) => item.id === config.channelId);
-  const point = snapshot?.physicalPoints?.find((item) => item.id === channel?.physicalPointId);
-  let channelName = channel ? typeof names[channel.id] === "string" ? String(names[channel.id]) : channel.id : typeof config.channelId === "string" ? `${config.channelId} (${text("unavailable", "nicht verf\xFCgbar")})` : text("Not selected", "Nicht ausgew\xE4hlt");
-  if (point?.modbus) {
-    const device = snapshot?.modbus?.devices.find((item) => item.id === point.modbus?.deviceId);
-    if (device) channelName = `${channelName} \xB7 ${device.name}`;
-  } else if (point?.hardwareProfile === "751-9301") {
-    const terminal = DIGITAL_TERMINALS.find((item) => item.channel === point.channel)?.label;
-    if (terminal && !channelName.includes(terminal)) channelName += ` \xB7 ${terminal}`;
-  }
   const rows = [
-    {
-      label: text("Device", "Ger\xE4t"),
-      value: controller?.name || controller?.hardwareId || (typeof config.controllerId === "number" ? `Controller ${config.controllerId} (${text("unavailable", "nicht verf\xFCgbar")})` : text("Not selected", "Nicht ausgew\xE4hlt"))
-    },
-    { label: text("Channel", "Kanal"), value: channelName }
+    { label: text("Device", "Ger\xE4t"), value: deviceLabel(config, controller, text) },
+    { label: text("Channel", "Kanal"), value: channelLabel(config, channel, snapshot, names, text) }
   ];
-  if (kind === "command") {
-    const action = config.action === "set" ? config.value === true ? text("Turn ON", "Einschalten") : config.value === false ? text("Turn OFF", "Ausschalten") : text("Select ON/OFF", "EIN/AUS ausw\xE4hlen") : config.action === "pulse" ? `${text("Pulse", "Impuls")}${channel?.pulse ? ` \xB7 ${duration(channel.pulse.durationMs)}` : ""}` : text("Not selected", "Nicht ausgew\xE4hlt");
-    return [...rows, { label: text("Action", "Aktion"), value: action }];
-  }
-  const category = config.category === "measurement" ? text("Measurement", "Messwert") : config.category === "fault" ? text("Fault", "Fehler") : config.category === "state" ? channel?.capabilities.includes("input") ? text("Input state", "Eingangszustand") : text("Output state", "Ausgangszustand") : void 0;
+  if (kind === "command")
+    return [...rows, { label: text("Action", "Aktion"), value: commandAction(config, channel, text) }];
+  const category = categoryLabel(config, channel, text);
   if (kind === "event")
     return [
       ...rows,
@@ -3816,12 +3804,11 @@ function localizedPreview(config, kind, controller, snapshot, names, german) {
     ];
   if (kind === "read")
     return [...rows, { label: text("Read", "Lesen"), value: category ?? text("Not selected", "Nicht ausgew\xE4hlt") }];
-  const expected = typeof config.equals === "boolean" ? config.equals ? text("ON", "EIN") : text("OFF", "AUS") : typeof config.equals === "number" && Number.isFinite(config.equals) ? `${config.equals} (${text("wire value", "Rohwert")})` : text("Not set", "Nicht festgelegt");
   return [
     ...rows,
     {
       label: text("Wait for", "Warten auf"),
-      value: `${category ?? text("Not selected", "Nicht ausgew\xE4hlt")} = ${expected}`
+      value: `${category ?? text("Not selected", "Nicht ausgew\xE4hlt")} = ${expectedValue(config, text)}`
     },
     {
       label: text("Timeout", "Zeitlimit"),
@@ -3829,6 +3816,38 @@ function localizedPreview(config, kind, controller, snapshot, names, german) {
     }
   ];
 }
+function deviceLabel(config, controller, text) {
+  return controller?.name || controller?.hardwareId || (typeof config.controllerId === "number" ? `Controller ${config.controllerId} (${text("unavailable", "nicht verf\xFCgbar")})` : text("Not selected", "Nicht ausgew\xE4hlt"));
+}
+function channelLabel(config, channel, snapshot, names, text) {
+  const point = snapshot?.physicalPoints?.find((item) => item.id === channel?.physicalPointId);
+  let channelName = channel ? typeof names[channel.id] === "string" ? String(names[channel.id]) : channel.id : typeof config.channelId === "string" ? `${config.channelId} (${text("unavailable", "nicht verf\xFCgbar")})` : text("Not selected", "Nicht ausgew\xE4hlt");
+  if (point?.modbus) {
+    const device = snapshot?.modbus?.devices.find((item) => item.id === point.modbus?.deviceId);
+    if (device) channelName = `${channelName} \xB7 ${device.name}`;
+  } else if (point?.hardwareProfile === "751-9301") {
+    const terminal = DIGITAL_TERMINALS.find((item) => item.channel === point.channel)?.label;
+    if (terminal && !channelName.includes(terminal)) channelName += ` \xB7 ${terminal}`;
+  }
+  return channelName;
+}
+function commandAction(config, channel, text) {
+  if (config.action === "set")
+    return config.value === true ? text("Turn ON", "Einschalten") : config.value === false ? text("Turn OFF", "Ausschalten") : text("Select ON/OFF", "EIN/AUS ausw\xE4hlen");
+  if (config.action === "pulse")
+    return `${text("Pulse", "Impuls")}${channel?.pulse ? ` \xB7 ${duration(channel.pulse.durationMs)}` : ""}`;
+  return text("Not selected", "Nicht ausgew\xE4hlt");
+}
+function categoryLabel(config, channel, text) {
+  if (config.category === "measurement") return text("Measurement", "Messwert");
+  if (config.category === "fault") return text("Fault", "Fehler");
+  if (config.category !== "state") return void 0;
+  return channel?.capabilities.includes("input") ? text("Input state", "Eingangszustand") : text("Output state", "Ausgangszustand");
+}
+function expectedValue(config, text) {
+  if (typeof config.equals === "boolean") return config.equals ? text("ON", "EIN") : text("OFF", "AUS");
+  return typeof config.equals === "number" && Number.isFinite(config.equals) ? `${config.equals} (${text("wire value", "Rohwert")})` : text("Not set", "Nicht festgelegt");
+}
 function duration(milliseconds) {
   return milliseconds < 1e3 ? `${milliseconds} ms` : `${milliseconds / 1e3} s`;
 }
@@ -5441,22 +5460,9 @@ var WagoControllerEnrollment = class extends WagoRevisions {
 // backend/controllers/subscriptions.ts
 var WagoSubscriptions = class extends WagoControllerEnrollment {
   async onHeartbeat(hardwareId, payload) {
-    let heartbeat;
-    try {
-      heartbeat = parseHeartbeat(payload);
-    } catch (error) {
-      this.context.logger.warn(
-        `Ignoring invalid WAGO heartbeat: ${error instanceof Error ? error.message : String(error)}`
-      );
-      return;
-    }
-    if (heartbeat.hardwareId !== hardwareId) return;
-    let rawHeartbeat;
-    try {
-      rawHeartbeat = JSON.parse(payload.toString("utf8"));
-    } catch {
-      return;
-    }
+    const parsed = this.parseHeartbeatPayload(hardwareId, payload);
+    if (!parsed) return;
+    const { heartbeat, rawHeartbeat } = parsed;
     const canonical = canonicalEnvelope(rawHeartbeat, "heartbeat");
     const controller = await this.controllers.findOneBy({ hardwareId });
     if (!controller || controller.trustState !== "claimed" || !canonical && heartbeat.sequence !== void 0 && heartbeat.sequence < controller.lastSequence)
@@ -5466,23 +5472,47 @@ var WagoSubscriptions = class extends WagoControllerEnrollment {
     const admitted = this.diagnostics.ingest(controller.id, "heartbeat", payload);
     if (canTrackDiagnostics && !admitted) return;
     const heartbeatAt = admitted ? this.diagnostics.read(controller.id).heartbeatAt : typeof rawHeartbeat.timestamp === "string" ? rawHeartbeat.timestamp : void 0;
-    const persistedHeartbeatAt = sourceTime(controller.lastHeartbeatAt);
-    if (canonical && (!validEnvelope(rawHeartbeat, Date.now()) || !heartbeatAt || persistedHeartbeatAt !== null && sourceTime(heartbeatAt) < persistedHeartbeatAt))
+    if (canonical && !acceptedCanonicalHeartbeat(rawHeartbeat, heartbeatAt, controller.lastHeartbeatAt)) return;
+    if (canonical && (admitted || !canTrackDiagnostics))
+      this.reportRuntimeStatus(controller.id, heartbeat, rawHeartbeat);
+    if (controller.lastHeartbeatAt && freshness(controller.lastSeenAt, Date.now(), 3e4) === "fresh" && !heartbeatMetadataChanged(controller, heartbeat))
       return;
-    if (canonical && (admitted || !canTrackDiagnostics) && typeof rawHeartbeat.streamId === "string" && typeof rawHeartbeat.timestamp === "string") {
-      this.runtimeStatusHandler?.(controller.id, {
-        imageId: heartbeat.runtimeImageId ?? "",
-        runtimeVersion: heartbeat.runtimeVersion,
-        streamId: rawHeartbeat.streamId,
-        timestamp: Date.parse(rawHeartbeat.timestamp),
-        receivedAt: Date.now(),
-        sequence: rawHeartbeat.sequence,
-        ...heartbeat.runtimePolicyToken ? { runtimePolicyToken: heartbeat.runtimePolicyToken } : {}
-      });
+    await this.checkpointHeartbeat(controller, heartbeat, canonical, heartbeatAt, now);
+  }
+  /** Parse a heartbeat for the expected controller; malformed packets are ignored. */
+  parseHeartbeatPayload(hardwareId, payload) {
+    let heartbeat;
+    try {
+      heartbeat = parseHeartbeat(payload);
+    } catch (error) {
+      this.context.logger.warn(
+        `Ignoring invalid WAGO heartbeat: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return void 0;
     }
-    const metadataChanged = controller.protocolVersion !== heartbeat.protocolVersion || controller.runtimeVersion !== heartbeat.runtimeVersion || controller.capabilities !== JSON.stringify(heartbeat.capabilities) || controller.compatibilityError !== compatibilityError(heartbeat);
-    if (controller.lastHeartbeatAt && freshness(controller.lastSeenAt, Date.now(), 3e4) === "fresh" && !metadataChanged)
-      return;
+    if (heartbeat.hardwareId !== hardwareId) return void 0;
+    try {
+      return { heartbeat, rawHeartbeat: JSON.parse(payload.toString("utf8")) };
+    } catch {
+      return void 0;
+    }
+  }
+  reportRuntimeStatus(controllerId, heartbeat, rawHeartbeat) {
+    if (typeof rawHeartbeat.streamId !== "string" || typeof rawHeartbeat.timestamp !== "string") return;
+    this.runtimeStatusHandler?.(controllerId, {
+      imageId: heartbeat.runtimeImageId ?? "",
+      runtimeVersion: heartbeat.runtimeVersion,
+      streamId: rawHeartbeat.streamId,
+      timestamp: Date.parse(rawHeartbeat.timestamp),
+      receivedAt: Date.now(),
+      sequence: rawHeartbeat.sequence,
+      ...heartbeat.runtimePolicyToken ? { runtimePolicyToken: heartbeat.runtimePolicyToken } : {}
+    });
+  }
+  /** Persist a heartbeat checkpoint. Canonical heartbeats record their source
+   * time; legacy heartbeats advance the sequence and use receipt time.
+   */
+  async checkpointHeartbeat(controller, heartbeat, canonical, heartbeatAt, now) {
     controller.protocolVersion = heartbeat.protocolVersion;
     controller.runtimeVersion = heartbeat.runtimeVersion;
     controller.capabilities = JSON.stringify(heartbeat.capabilities);
@@ -5717,6 +5747,14 @@ var WagoSubscriptions = class extends WagoControllerEnrollment {
     return rebuild;
   }
 };
+function acceptedCanonicalHeartbeat(rawHeartbeat, heartbeatAt, lastHeartbeatAt) {
+  if (!validEnvelope(rawHeartbeat, Date.now()) || !heartbeatAt) return false;
+  const persistedHeartbeatAt = sourceTime(lastHeartbeatAt);
+  return persistedHeartbeatAt === null || (sourceTime(heartbeatAt) ?? 0) >= persistedHeartbeatAt;
+}
+function heartbeatMetadataChanged(controller, heartbeat) {
+  return controller.protocolVersion !== heartbeat.protocolVersion || controller.runtimeVersion !== heartbeat.runtimeVersion || controller.capabilities !== JSON.stringify(heartbeat.capabilities) || controller.compatibilityError !== compatibilityError(heartbeat);
+}
 
 // backend/controllers/service.ts
 var WagoService = class extends WagoSubscriptions {
@@ -9223,6 +9261,11 @@ var RuntimeUpdateError = class extends Error {
 var LEASE_MS = 30 * 6e4;
 var CURRENT_RECHECK_MS = 5 * 6e4;
 var OPERATION_MS = 25 * 6e4;
+function inspectionBlocker(inspection) {
+  if (!inspection.claimed || !inspection.managed) return "management_required";
+  if (!inspection.online) return "offline";
+  return inspection.compatible ? null : "incompatible";
+}
 var WagoRuntimeUpdateCoordinator = class {
   constructor(store, desired, host, audit, now = Date.now, concurrency = 2) {
     __publicField(this, "store", store);
@@ -9245,133 +9288,12 @@ var WagoRuntimeUpdateCoordinator = class {
     if (this.stopped || this.running.has(controllerId) || this.running.size >= this.concurrency) return "busy";
     this.running.add(controllerId);
     let acquired = false;
-    const { owner, operation, timer, assertOwned, persist, acknowledge } = this.createLease(controllerId);
+    const lease = this.createLease(controllerId);
+    const { owner, operation, timer } = lease;
     try {
       acquired = await this.store.acquire(controllerId, owner, this.now(), this.now() + LEASE_MS);
       if (!acquired) return "busy";
-      let record2 = await this.store.load(controllerId);
-      await advanceRuntimeRetry(record2, retry, persist);
-      if (record2 && ["current", "failed"].includes(record2.phase) && record2.token) {
-        if (!await acknowledge(record2)) return "deferred";
-      }
-      if (record2 && active.has(record2.phase)) {
-        if (record2.phase === "recovery_required" && record2.retryAt > this.now()) return "deferred";
-        if (!record2.token || !record2.previousImageId) throw new RuntimeUpdateError("recovery");
-        record2.phase = "recovering";
-        await persist(record2);
-        try {
-          await this.host.recover(controllerId, record2.token, record2.previousImageId, operation.signal);
-          assertOwned();
-        } catch {
-          record2.phase = "recovery_required";
-          record2.failure = "recovery";
-          record2.retryAt = this.now() + 6e4;
-          await persist(record2);
-          return "settled";
-        }
-        record2.phase = "failed";
-        record2.failure = "interrupted";
-        record2.retryAt = this.now();
-        await persist(record2);
-        if (!await acknowledge(record2)) return "deferred";
-        return "settled";
-      }
-      const desired = await this.desired();
-      assertOwned();
-      const contradictedCurrent = record2?.phase === "current" && observedImageId !== void 0 && observedImageId !== (record2.currentImageId ?? record2.desiredImageId);
-      if (record2 && !contradictedCurrent && record2.desiredImageId === desired.imageId && record2.retryAt > this.now())
-        return "deferred";
-      const attempt = (record2?.desiredImageId === desired.imageId ? record2.attempt : 0) + 1;
-      let inspection;
-      try {
-        inspection = await this.host.inspect(controllerId, operation.signal);
-        assertOwned();
-      } catch (error) {
-        await persist({
-          controllerId,
-          phase: "blocked",
-          token: null,
-          desiredImageId: desired.imageId,
-          desiredRuntimeVersion: desired.manifest.runtimeVersion,
-          previousRuntimeVersion: record2?.desiredImageId === desired.imageId ? record2.previousRuntimeVersion ?? null : null,
-          desiredDigest: desired.digest,
-          buildId: desired.buildId,
-          previousImageId: record2?.desiredImageId === desired.imageId ? record2.previousImageId : null,
-          attempt,
-          startedAt: this.now(),
-          updatedAt: this.now(),
-          retryAt: this.retryAt(attempt),
-          failure: error instanceof RuntimeUpdateError ? error.failure : "offline"
-        });
-        return "settled";
-      }
-      const previous = record2;
-      const retainPrevious = previous?.desiredImageId === desired.imageId && inspection.imageId === desired.imageId;
-      record2 = {
-        controllerId,
-        phase: "blocked",
-        token: null,
-        desiredImageId: desired.imageId,
-        desiredRuntimeVersion: desired.manifest.runtimeVersion,
-        previousRuntimeVersion: retainPrevious ? previous.previousRuntimeVersion ?? inspection.runtimeVersion ?? null : inspection.runtimeVersion ?? null,
-        desiredDigest: desired.digest,
-        buildId: desired.buildId,
-        ...desired.installerSha256 ? { installerSha256: desired.installerSha256 } : {},
-        previousImageId: retainPrevious ? previous.previousImageId ?? inspection.imageId : inspection.imageId,
-        attempt,
-        startedAt: this.now(),
-        updatedAt: this.now(),
-        retryAt: 0,
-        failure: null,
-        cleanupAttempt: 0,
-        cleanupRetryAt: 0
-      };
-      const blocker = !inspection.claimed || !inspection.managed ? "management_required" : !inspection.online ? "offline" : !inspection.compatible ? "incompatible" : null;
-      if (blocker) {
-        record2.failure = blocker;
-        record2.retryAt = this.retryAt(attempt);
-        await persist(record2);
-        return "settled";
-      }
-      if (this.host.prepare) {
-        record2.phase = "preparing";
-        await persist(record2);
-        try {
-          await this.host.prepare(controllerId, desired, operation.signal);
-          await this.assertCurrent(desired.imageId);
-          assertOwned();
-        } catch (error) {
-          assertOwned();
-          record2.phase = "blocked";
-          record2.failure = error instanceof RuntimeUpdateError ? error.failure : "incompatible";
-          record2.retryAt = this.retryAt(attempt);
-          await persist(record2);
-          return "settled";
-        }
-      }
-      const targetImageId = runtimeTargetImageId(desired, inspection);
-      if (inspection.imageId === targetImageId)
-        return await this.verifyExisting(
-          controllerId,
-          desired,
-          record2,
-          operation,
-          assertOwned,
-          persist,
-          attempt,
-          targetImageId
-        );
-      return await this.applyRollout(
-        controllerId,
-        desired,
-        record2,
-        inspection,
-        operation,
-        assertOwned,
-        persist,
-        acknowledge,
-        attempt
-      );
+      return await this.reconcileOwned(controllerId, retry, observedImageId, lease);
     } finally {
       clearTimeout(timer);
       operation.abort();
@@ -9384,6 +9306,146 @@ var WagoRuntimeUpdateCoordinator = class {
       }
     }
   }
+  async reconcileOwned(controllerId, retry, observedImageId, lease) {
+    const { operation, assertOwned, persist, acknowledge } = lease;
+    let record2 = await this.store.load(controllerId);
+    await advanceRuntimeRetry(record2, retry, persist);
+    if (record2 && ["current", "failed"].includes(record2.phase) && record2.token) {
+      if (!await acknowledge(record2)) return "deferred";
+    }
+    if (record2 && active.has(record2.phase)) return await this.recoverInterrupted(controllerId, record2, lease);
+    const desired = await this.desired();
+    assertOwned();
+    const contradictedCurrent = record2?.phase === "current" && observedImageId !== void 0 && observedImageId !== (record2.currentImageId ?? record2.desiredImageId);
+    if (record2 && !contradictedCurrent && record2.desiredImageId === desired.imageId && record2.retryAt > this.now())
+      return "deferred";
+    const attempt = (record2?.desiredImageId === desired.imageId ? record2.attempt : 0) + 1;
+    let inspection;
+    try {
+      inspection = await this.host.inspect(controllerId, operation.signal);
+      assertOwned();
+    } catch (error) {
+      await persist(this.uninspectedRecord(controllerId, desired, record2, attempt, error));
+      return "settled";
+    }
+    record2 = this.plannedRecord(controllerId, desired, record2, inspection, attempt);
+    const blocker = inspectionBlocker(inspection);
+    if (blocker) {
+      record2.failure = blocker;
+      record2.retryAt = this.retryAt(attempt);
+      await persist(record2);
+      return "settled";
+    }
+    if (!await this.prepareHost(controllerId, desired, record2, lease, attempt)) return "settled";
+    const targetImageId = runtimeTargetImageId(desired, inspection);
+    if (inspection.imageId === targetImageId)
+      return await this.verifyExisting(
+        controllerId,
+        desired,
+        record2,
+        operation,
+        assertOwned,
+        persist,
+        attempt,
+        targetImageId
+      );
+    return await this.applyRollout(
+      controllerId,
+      desired,
+      record2,
+      inspection,
+      operation,
+      assertOwned,
+      persist,
+      acknowledge,
+      attempt
+    );
+  }
+  /** Resumes an interrupted rollout found in an active phase by asking the host to recover. */
+  async recoverInterrupted(controllerId, record2, { operation, assertOwned, persist, acknowledge }) {
+    if (record2.phase === "recovery_required" && record2.retryAt > this.now()) return "deferred";
+    if (!record2.token || !record2.previousImageId) throw new RuntimeUpdateError("recovery");
+    record2.phase = "recovering";
+    await persist(record2);
+    try {
+      await this.host.recover(controllerId, record2.token, record2.previousImageId, operation.signal);
+      assertOwned();
+    } catch {
+      record2.phase = "recovery_required";
+      record2.failure = "recovery";
+      record2.retryAt = this.now() + 6e4;
+      await persist(record2);
+      return "settled";
+    }
+    record2.phase = "failed";
+    record2.failure = "interrupted";
+    record2.retryAt = this.now();
+    await persist(record2);
+    if (!await acknowledge(record2)) return "deferred";
+    return "settled";
+  }
+  /** Blocked record for a controller whose host inspection failed. */
+  uninspectedRecord(controllerId, desired, record2, attempt, error) {
+    const sameTarget = record2?.desiredImageId === desired.imageId;
+    return {
+      controllerId,
+      phase: "blocked",
+      token: null,
+      desiredImageId: desired.imageId,
+      desiredRuntimeVersion: desired.manifest.runtimeVersion,
+      previousRuntimeVersion: sameTarget ? record2.previousRuntimeVersion ?? null : null,
+      desiredDigest: desired.digest,
+      buildId: desired.buildId,
+      previousImageId: sameTarget ? record2.previousImageId : null,
+      attempt,
+      startedAt: this.now(),
+      updatedAt: this.now(),
+      retryAt: this.retryAt(attempt),
+      failure: error instanceof RuntimeUpdateError ? error.failure : "offline"
+    };
+  }
+  /** Fresh blocked record for a new attempt, retaining the rollback target of a repeated one. */
+  plannedRecord(controllerId, desired, previous, inspection, attempt) {
+    const retainPrevious = previous?.desiredImageId === desired.imageId && inspection.imageId === desired.imageId;
+    return {
+      controllerId,
+      phase: "blocked",
+      token: null,
+      desiredImageId: desired.imageId,
+      desiredRuntimeVersion: desired.manifest.runtimeVersion,
+      previousRuntimeVersion: retainPrevious ? previous.previousRuntimeVersion ?? inspection.runtimeVersion ?? null : inspection.runtimeVersion ?? null,
+      desiredDigest: desired.digest,
+      buildId: desired.buildId,
+      ...desired.installerSha256 ? { installerSha256: desired.installerSha256 } : {},
+      previousImageId: retainPrevious ? previous.previousImageId ?? inspection.imageId : inspection.imageId,
+      attempt,
+      startedAt: this.now(),
+      updatedAt: this.now(),
+      retryAt: 0,
+      failure: null,
+      cleanupAttempt: 0,
+      cleanupRetryAt: 0
+    };
+  }
+  /** Runs the optional host preparation; false once a blocked record has been persisted. */
+  async prepareHost(controllerId, desired, record2, { operation, assertOwned, persist }, attempt) {
+    if (!this.host.prepare) return true;
+    record2.phase = "preparing";
+    await persist(record2);
+    try {
+      await this.host.prepare(controllerId, desired, operation.signal);
+      await this.assertCurrent(desired.imageId);
+      assertOwned();
+    } catch (error) {
+      assertOwned();
+      record2.phase = "blocked";
+      record2.failure = error instanceof RuntimeUpdateError ? error.failure : "incompatible";
+      record2.retryAt = this.retryAt(attempt);
+      await persist(record2);
+      return false;
+    }
+    return true;
+  }
   async verifyExisting(controllerId, desired, record2, operation, assertOwned, persist, attempt, targetImageId) {
     const since = record2.startedAt;
     try {
@@ -10302,27 +10364,12 @@ var WagoManagedRuntimeEnrollment = class extends WagoManagedRuntimeServiceState
     }
   }
   async publicStatus(access, requestedControllerId) {
-    if (access && !["retiring", "retired"].includes(access.state)) {
-      try {
-        const stored = await this.loadSession(access.sessionId);
-        if (!stored) throw new Error();
-        this.credentials(stored);
-      } catch {
-        await this.setActiveState(access.sessionId, "recovery_required").catch(() => void 0);
-        access = await this.access.findOneBy({ sessionId: access.sessionId });
-      }
-    }
+    access = await this.revalidatedAccess(access);
     const row = access?.controllerId ? await this.updates.findOneBy({ controllerId: access.controllerId }) : null;
     const controllerId = requestedControllerId ?? access?.controllerId;
     const controller = controllerId ? await this.controllers.findOneBy({ id: controllerId }) : null;
     const desired = controller ? await this.artifacts.current().catch(() => null) : null;
-    const managementSetup = access?.state === "verified" ? this.enrolmentProgress.get(controllerId ?? 0) ?? {
-      state: "waiting",
-      reason: controller ? await this.enrolmentWaitReason(
-        controller,
-        await this.sessions.findOneBy({ id: access.sessionId })
-      ) ?? "scheduled" : "connection"
-    } : void 0;
+    const managementSetup = access?.state === "verified" ? await this.managementSetup(access, controller, controllerId) : void 0;
     const managementFailure = access && ["verified", "recovery_required"].includes(access.state) ? (await this.sessions.findOneBy({ id: access.sessionId }))?.failureReason : null;
     return {
       ...managementFailure ? { managementFailure } : {},
@@ -10331,22 +10378,51 @@ var WagoManagedRuntimeEnrollment = class extends WagoManagedRuntimeServiceState
       keyFingerprint: access?.keyFingerprint ?? null,
       update: row?.metadata ? JSON.parse(row.metadata) : null,
       ...managementSetup ? { managementSetup } : {},
-      ...controller ? {
-        runtime: {
-          runningVersion: controller.runtimeVersion,
-          runningImageId: this.heartbeats.get(controller.id)?.imageId || null,
-          desiredVersion: desired?.manifest.runtimeVersion ?? null,
-          desiredImageId: desired && "imageId" in desired ? runtimeTargetImageId(desired, {
-            imageId: this.heartbeats.get(controller.id)?.imageId ?? "",
-            runtimeVersion: this.heartbeats.get(controller.id)?.runtimeVersion ?? controller.runtimeVersion
-          }) : null
-        }
-      } : {},
-      ...access?.controllerId && this.wago.isRuntimeUpdateRequired ? { runtimeUpdateRequired: this.wago.isRuntimeUpdateRequired(access.controllerId) } : {},
-      ...access?.controllerId && this.reconciliationFailures.has(access.controllerId) ? { blocker: this.reconciliationFailures.get(access.controllerId) } : {},
+      ...controller ? { runtime: this.runtimeStatus(controller, desired) } : {},
+      ...this.runtimeAttention(access?.controllerId),
       physicalQualification: "unverified"
     };
   }
+  /** Marks active access whose stored envelope no longer verifies as needing recovery. */
+  async revalidatedAccess(access) {
+    if (!access || ["retiring", "retired"].includes(access.state)) return access;
+    try {
+      const stored = await this.loadSession(access.sessionId);
+      if (!stored) throw new Error();
+      this.credentials(stored);
+      return access;
+    } catch {
+      await this.setActiveState(access.sessionId, "recovery_required").catch(() => void 0);
+      return this.access.findOneBy({ sessionId: access.sessionId });
+    }
+  }
+  /** Live automatic SSH-completion progress, or the prerequisite it is still waiting for. */
+  async managementSetup(access, controller, controllerId) {
+    return this.enrolmentProgress.get(controllerId ?? 0) ?? {
+      state: "waiting",
+      reason: controller ? await this.enrolmentWaitReason(controller, await this.sessions.findOneBy({ id: access.sessionId })) ?? "scheduled" : "connection"
+    };
+  }
+  /** Running versus desired runtime image for the controller's latest heartbeat. */
+  runtimeStatus(controller, desired) {
+    const heartbeat = this.heartbeats.get(controller.id);
+    return {
+      runningVersion: controller.runtimeVersion,
+      runningImageId: heartbeat?.imageId || null,
+      desiredVersion: desired?.manifest.runtimeVersion ?? null,
+      desiredImageId: desired && "imageId" in desired ? runtimeTargetImageId(desired, {
+        imageId: heartbeat?.imageId ?? "",
+        runtimeVersion: heartbeat?.runtimeVersion ?? controller.runtimeVersion
+      }) : null
+    };
+  }
+  /** Runtime update demand and the last reconciliation blocker for a bound controller. */
+  runtimeAttention(controllerId) {
+    return {
+      ...controllerId && this.wago.isRuntimeUpdateRequired ? { runtimeUpdateRequired: this.wago.isRuntimeUpdateRequired(controllerId) } : {},
+      ...controllerId && this.reconciliationFailures.has(controllerId) ? { blocker: this.reconciliationFailures.get(controllerId) } : {}
+    };
+  }
   async sessionStatus(sessionId) {
     return this.publicStatus(await this.access.findOneBy({ sessionId }));
   }
@@ -10797,14 +10873,9 @@ var WagoManagedRuntimeService = class extends WagoManagedRuntimeReconciliation {
     super(context, wago, artifacts, readiness);
   }
   async completeEnrolment(controller) {
-    if (!controller.mqttServerId) return false;
-    const bound = await this.access.findOne({ where: { controllerId: controller.id }, order: { sessionId: "DESC" } });
-    if (!bound) return false;
-    const session = await this.sessions.findOneBy({ id: bound.sessionId });
-    if (!session || !["awaiting_verification", "completed"].includes(session.state)) return false;
-    if (session.hardwareId !== controller.hardwareId || session.mqttServerId !== controller.mqttServerId) return false;
-    let access = await this.loadSession(session.id);
-    if (!access || ["retiring", "retired", "pending"].includes(access.state)) return false;
+    const candidate = await this.enrolmentCandidate(controller);
+    if (!candidate) return false;
+    const { bound, session, access } = candidate;
     try {
       if (this.credentials(access).hardwareId !== controller.hardwareId) throw new Error();
     } catch {
@@ -10820,129 +10891,172 @@ var WagoManagedRuntimeService = class extends WagoManagedRuntimeReconciliation {
     const owner = (0, import_node_crypto17.randomBytes)(16).toString("hex");
     if (!await this.operations.acquire(access.fingerprint, owner, Date.now(), Date.now() + 22 * 6e4)) return false;
     const operation = new AbortController();
-    let timer = setTimeout(() => operation.abort(), 18 * 6e4).unref();
-    let stage = "status";
-    const operationId = (0, import_node_crypto17.randomUUID)();
-    let principal = null;
-    let attempted = false;
+    const attempt = {
+      controller,
+      session,
+      owner,
+      operation,
+      // Key confirmation, acceptance and cutover can each wait 310s for a
+      // supervisor gate. The rollback window starts only once SSH actually changes.
+      timer: setTimeout(() => operation.abort(), 18 * 6e4).unref(),
+      stage: "status",
+      operationId: (0, import_node_crypto17.randomUUID)(),
+      principal: null,
+      attempted: false
+    };
     this.enrolmentProgress.set(controller.id, { state: "running", reason: "preparation" });
     try {
-      await this.operations.assertOwned(access.fingerprint, owner);
-      access = await this.loadSession(session.id);
-      if (!access || ["retiring", "retired", "pending"].includes(access.state)) return false;
-      const remoteStatus = await this.connection(access, `access-status ${access.token}`, operation.signal);
-      if (remoteStatus === "cutover\n" && access.state !== "recovery_required") return false;
-      if (!["open\n", "committed\n", "cutover\n"].includes(remoteStatus)) throw new Error("Unknown management receipt");
-      const committed = remoteStatus === "committed\n";
-      if (committed) {
-        clearTimeout(timer);
-        timer = setTimeout(() => operation.abort(), 18e4).unref();
-      }
-      stage = "audit";
-      principal = JSON.parse(session.initiatingPrincipal ?? "null");
-      if (!principal) throw new Error("Management audit initiator unavailable");
-      await this.securityAudit(session.id, "security_apply", principal, operationId, "attempted");
-      attempted = true;
-      await this.sessions.update(session.id, { updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
-      await this.access.update(access.sessionId, { controllerId: controller.id });
-      if (remoteStatus === "cutover\n") {
-        stage = "rollback";
-        clearTimeout(timer);
-        timer = setTimeout(() => operation.abort(), 5e4).unref();
-        await this.connection(access, `access-restore ${access.token}`, operation.signal);
-        await this.securityAudit(session.id, "security_apply", principal, operationId, "failed");
-        return false;
-      }
-      if (!committed) {
-        stage = "ownership";
-        if (!session.deliveryToken || !session.dockerProvisionToken)
-          throw new Error("Commissioning ownership unavailable");
-        stage = "proof";
-        await this.prove(access, operation.signal);
-        stage = "recovery_login";
-        if (!await this.rootProbe(access.host, access.fingerprint, this.credentials(access).recoveryPassword))
-          throw new Error("Root recovery path is unverified");
-        await this.setActiveState(access.sessionId, "verified");
-        stage = "key_commit";
-        await this.connection(access, `access-key-commit ${access.token}`, operation.signal);
-        stage = "proof";
-        await this.prove(access, operation.signal);
-        stage = "acceptance";
-        if (this.rootAcceptance) {
-          await this.rootAcceptance(
-            access.host,
-            access.fingerprint,
-            this.credentials(access).recoveryPassword,
-            session.deliveryToken,
-            {
-              assertOwned: () => this.operations.assertOwned(access.fingerprint, owner),
-              signal: operation.signal,
-              deadline: Date.now() + 12 * 6e4
-            },
-            { token: access.token, helper: managedHostHelper(await this.desired()), watchdog: managedWatchdogScript() }
-          );
-        } else await this.connection(access, `commissioning-accept ${session.deliveryToken}`, operation.signal);
-        stage = "cutover";
-        this.enrolmentProgress.set(controller.id, { state: "running", reason: "ssh_cutover" });
-        await this.connection(access, `access-cutover ${access.token}`, operation.signal);
-        clearTimeout(timer);
-        timer = setTimeout(() => operation.abort(), 18e4).unref();
-        await new Promise((resolve2) => setTimeout(resolve2, 3e3));
-      }
-      stage = "policy";
-      await this.prove(access, operation.signal);
-      if (await this.connection(access, `access-policy ${access.token}`, operation.signal) !== "OK\n")
-        throw new Error("Managed SSH policy is unverified");
-      stage = "root_login";
-      if (await this.rootProbe(access.host, access.fingerprint, this.credentials(access).recoveryPassword))
-        throw new Error("Root SSH remains enabled");
-      await this.prove(access, operation.signal);
-      if (!committed) {
-        this.enrolmentProgress.set(controller.id, { state: "running", reason: "reboot" });
-        stage = "boot";
-        const boot = await this.connection(access, `access-boot ${access.token}`, operation.signal);
-        if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}\n$/.test(boot))
-          throw new Error("Controller boot identity unavailable");
-        stage = "reboot";
-        await this.connection(access, `access-reboot ${access.token}`, operation.signal).catch(() => void 0);
-        let rebootVerified = false;
-        for (let attempt = 0; attempt < 60; attempt++) {
-          operation.signal.throwIfAborted();
-          await new Promise((resolve2) => setTimeout(resolve2, 1e3));
-          try {
-            const next = await this.connection(access, `access-boot ${access.token}`, operation.signal);
-            if (next !== boot && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}\n$/.test(next)) {
-              await this.prove(access, operation.signal);
-              if (await this.connection(access, `access-policy ${access.token}`, operation.signal) !== "OK\n")
-                throw new Error("Post-reboot SSH policy unverified");
-              if (await this.rootProbe(access.host, access.fingerprint, this.credentials(access).recoveryPassword))
-                throw new Error("Root SSH enabled after reboot");
-              await this.prove(access, operation.signal);
-              rebootVerified = true;
-              break;
-            }
-          } catch {
-          }
-        }
-        if (!rebootVerified) throw new Error("Managed reboot verification failed");
-      }
-      await this.operations.assertOwned(access.fingerprint, owner);
-      stage = "confirmation";
-      this.enrolmentProgress.set(controller.id, { state: "running", reason: "confirmation" });
-      if (!committed) await this.connection(access, `access-commit ${access.token}`, operation.signal);
-      await this.setActiveState(access.sessionId, "managed");
-      await this.finishSession(session.id);
-      await this.securityAudit(session.id, "security_apply", principal, operationId, "succeeded");
-      return true;
+      return await this.runEnrolment(attempt, access.fingerprint);
     } catch (error) {
-      return await this.failEnrolment(session, error, stage, attempted, principal, operationId, operation);
+      return await this.failEnrolment(
+        session,
+        error,
+        attempt.stage,
+        attempt.attempted,
+        attempt.principal,
+        attempt.operationId,
+        operation
+      );
     } finally {
       this.enrolmentProgress.delete(controller.id);
-      clearTimeout(timer);
+      clearTimeout(attempt.timer);
       operation.abort();
       await this.operations.release(bound.fingerprint, owner);
     }
   }
+  /** Bound, unretired access whose commissioning session still matches this controller. */
+  async enrolmentCandidate(controller) {
+    if (!controller.mqttServerId) return null;
+    const bound = await this.access.findOne({ where: { controllerId: controller.id }, order: { sessionId: "DESC" } });
+    if (!bound) return null;
+    const session = await this.sessions.findOneBy({ id: bound.sessionId });
+    if (!session || !["awaiting_verification", "completed"].includes(session.state)) return null;
+    if (session.hardwareId !== controller.hardwareId || session.mqttServerId !== controller.mqttServerId) return null;
+    const access = await this.loadSession(session.id);
+    if (!access || ["retiring", "retired", "pending"].includes(access.state)) return null;
+    return { bound, session, access };
+  }
+  /** Probes the pinned bootstrap root login with the encrypted recovery password. completeEnrolment
+   * only starts an attempt once a probe is registered; probes are never unregistered. */
+  async rootLoginAccepted(access) {
+    const probe = this.rootProbe;
+    if (!probe) throw new Error("Root recovery probe unavailable");
+    return probe(access.host, access.fingerprint, this.credentials(access).recoveryPassword);
+  }
+  /** Replaces the attempt's operation deadline; called whenever a new bounded phase starts. */
+  restartEnrolmentTimer(attempt, ms) {
+    clearTimeout(attempt.timer);
+    attempt.timer = setTimeout(() => attempt.operation.abort(), ms).unref();
+  }
+  /** Runs the leased enrolment attempt; `attempt` records the stage and audit state for failure handling. */
+  async runEnrolment(attempt, fingerprint2) {
+    const { controller, session, owner, operation, operationId } = attempt;
+    await this.operations.assertOwned(fingerprint2, owner);
+    const access = await this.loadSession(session.id);
+    if (!access || ["retiring", "retired", "pending"].includes(access.state)) return false;
+    const remoteStatus = await this.connection(access, `access-status ${access.token}`, operation.signal);
+    if (remoteStatus === "cutover\n" && access.state !== "recovery_required") return false;
+    if (!["open\n", "committed\n", "cutover\n"].includes(remoteStatus)) throw new Error("Unknown management receipt");
+    const committed = remoteStatus === "committed\n";
+    if (committed) this.restartEnrolmentTimer(attempt, 18e4);
+    attempt.stage = "audit";
+    const principal = JSON.parse(session.initiatingPrincipal ?? "null");
+    attempt.principal = principal;
+    if (!principal) throw new Error("Management audit initiator unavailable");
+    await this.securityAudit(session.id, "security_apply", principal, operationId, "attempted");
+    attempt.attempted = true;
+    await this.sessions.update(session.id, { updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    await this.access.update(access.sessionId, { controllerId: controller.id });
+    if (remoteStatus === "cutover\n") {
+      attempt.stage = "rollback";
+      this.restartEnrolmentTimer(attempt, 5e4);
+      await this.connection(access, `access-restore ${access.token}`, operation.signal);
+      await this.securityAudit(session.id, "security_apply", principal, operationId, "failed");
+      return false;
+    }
+    if (!committed) await this.cutOverEnrolment(attempt, access);
+    attempt.stage = "policy";
+    await this.prove(access, operation.signal);
+    if (await this.connection(access, `access-policy ${access.token}`, operation.signal) !== "OK\n")
+      throw new Error("Managed SSH policy is unverified");
+    attempt.stage = "root_login";
+    if (await this.rootLoginAccepted(access)) throw new Error("Root SSH remains enabled");
+    await this.prove(access, operation.signal);
+    if (!committed) await this.verifyEnrolmentReboot(attempt, access);
+    await this.operations.assertOwned(access.fingerprint, owner);
+    attempt.stage = "confirmation";
+    this.enrolmentProgress.set(controller.id, { state: "running", reason: "confirmation" });
+    if (!committed) await this.connection(access, `access-commit ${access.token}`, operation.signal);
+    await this.setActiveState(access.sessionId, "managed");
+    await this.finishSession(session.id);
+    await this.securityAudit(session.id, "security_apply", principal, operationId, "succeeded");
+    return true;
+  }
+  /** First attempt: prove recovery, commit the key, accept commissioning and switch SSH policy. */
+  async cutOverEnrolment(attempt, access) {
+    const { controller, session, owner, operation } = attempt;
+    attempt.stage = "ownership";
+    if (!session.deliveryToken || !session.dockerProvisionToken) throw new Error("Commissioning ownership unavailable");
+    attempt.stage = "proof";
+    await this.prove(access, operation.signal);
+    attempt.stage = "recovery_login";
+    if (!await this.rootLoginAccepted(access)) throw new Error("Root recovery path is unverified");
+    await this.setActiveState(access.sessionId, "verified");
+    attempt.stage = "key_commit";
+    await this.connection(access, `access-key-commit ${access.token}`, operation.signal);
+    attempt.stage = "proof";
+    await this.prove(access, operation.signal);
+    attempt.stage = "acceptance";
+    if (this.rootAcceptance) {
+      await this.rootAcceptance(
+        access.host,
+        access.fingerprint,
+        this.credentials(access).recoveryPassword,
+        session.deliveryToken,
+        {
+          assertOwned: () => this.operations.assertOwned(access.fingerprint, owner),
+          signal: operation.signal,
+          deadline: Date.now() + 12 * 6e4
+        },
+        { token: access.token, helper: managedHostHelper(await this.desired()), watchdog: managedWatchdogScript() }
+      );
+    } else await this.connection(access, `commissioning-accept ${session.deliveryToken}`, operation.signal);
+    attempt.stage = "cutover";
+    this.enrolmentProgress.set(controller.id, { state: "running", reason: "ssh_cutover" });
+    await this.connection(access, `access-cutover ${access.token}`, operation.signal);
+    this.restartEnrolmentTimer(attempt, 18e4);
+    await new Promise((resolve2) => setTimeout(resolve2, 3e3));
+  }
+  /** First attempt: reboot and require the new boot to keep the hardened policy. */
+  async verifyEnrolmentReboot(attempt, access) {
+    const { controller, operation } = attempt;
+    this.enrolmentProgress.set(controller.id, { state: "running", reason: "reboot" });
+    attempt.stage = "boot";
+    const boot = await this.connection(access, `access-boot ${access.token}`, operation.signal);
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}\n$/.test(boot))
+      throw new Error("Controller boot identity unavailable");
+    attempt.stage = "reboot";
+    await this.connection(access, `access-reboot ${access.token}`, operation.signal).catch(() => void 0);
+    let rebootVerified = false;
+    for (let poll = 0; poll < 60; poll++) {
+      operation.signal.throwIfAborted();
+      await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+      try {
+        const next = await this.connection(access, `access-boot ${access.token}`, operation.signal);
+        if (next !== boot && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}\n$/.test(next)) {
+          await this.prove(access, operation.signal);
+          if (await this.connection(access, `access-policy ${access.token}`, operation.signal) !== "OK\n")
+            throw new Error("Post-reboot SSH policy unverified");
+          if (await this.rootLoginAccepted(access)) throw new Error("Root SSH enabled after reboot");
+          await this.prove(access, operation.signal);
+          rebootVerified = true;
+          break;
+        }
+      } catch {
+      }
+    }
+    if (!rebootVerified) throw new Error("Managed reboot verification failed");
+  }
   async failEnrolment(session, error, stage, attempted, principal, operationId, operation) {
     if (attempted && principal)
       await this.securityAudit(session.id, "security_apply", principal, operationId, "failed").catch(() => void 0);
@@ -15623,6 +15737,14 @@ function networkChangeInput(body) {
     throw new import_common35.BadRequestException("Select a configured MQTT server or update only the address.");
   return { targetHost: input.targetHost, mqttServerId: input.mqttServerId };
 }
+function assertNoUnfinishedChange(row) {
+  if (row && row.phase !== "completed" && !(row.phase === "connecting" && row.failure))
+    throw new import_common35.ConflictException("Retry the pending MQTT/address change before starting another.");
+}
+function assertSameManagedIdentity(row, access) {
+  if (!row || row.sessionId !== access.sessionId || row.fingerprint !== access.fingerprint)
+    throw new import_common35.ConflictException("Pending change belongs to another managed identity.");
+}
 
 // backend/network/service.ts
 var import_promises10 = require("node:dns/promises");
@@ -15659,31 +15781,10 @@ var WagoNetworkChangeService = class {
         throw new import_common36.ConflictException("Managed enrolled controller required.");
       row = await this.repository.createQueryBuilder("change").addSelect("change.encryptedPayload").where("change.controllerId = :controllerId", { controllerId }).getOne();
       if (retry && (!row || row.phase === "completed")) return this.status(controllerId);
-      if (!retry && row && row.phase !== "completed" && !(row.phase === "connecting" && row.failure))
-        throw new import_common36.ConflictException("Retry the pending MQTT/address change before starting another.");
-      const rotation = await this.context.getRepository(WagoCredentialRotationEntity).findOneBy({ controllerId });
-      const update = await this.context.getRepository(WagoRuntimeUpdateEntity).findOneBy({ controllerId });
-      if (rotation && rotation.phase !== "completed" || update?.metadata && JSON.parse(update.metadata).token)
-        throw new import_common36.ConflictException(
-          "Finish credential rotation or runtime update recovery before changing MQTT/address settings."
-        );
-      if (!retry) {
-        if (!input) throw new import_common36.BadRequestException("Invalid MQTT/address change");
-        row = this.repository.create({
-          controllerId,
-          sessionId: access.sessionId,
-          fingerprint: access.fingerprint,
-          ...input,
-          phase: "connecting",
-          failure: null,
-          encryptedPayload: null,
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
-        await assertOwned();
-        await this.repository.save(row);
-      }
-      if (!row || row.sessionId !== access.sessionId || row.fingerprint !== access.fingerprint)
-        throw new import_common36.ConflictException("Pending change belongs to another managed identity.");
+      if (!retry) assertNoUnfinishedChange(row);
+      await this.assertNoPendingRecovery(controllerId);
+      if (!retry) row = await this.savePendingChange(controllerId, access, input, assertOwned);
+      assertSameManagedIdentity(row, access);
       await lifecycle.attempt();
       audited = true;
       await assertOwned();
@@ -15695,10 +15796,7 @@ var WagoNetworkChangeService = class {
       if (row.mqttServerId !== null) {
         await this.applyBrokerChange(controllerId, row, controller, host, abort, assertOwned, retry);
       } else {
-        if (await host.command(`mqtt-address ${host.managementToken}`) !== "OK\n")
-          throw new RuntimeUpdateError("recovery");
-        await this.phase(row, "saving", assertOwned);
-        await this.saveBindings(row, host.encryptedCredentials, null, assertOwned);
+        await this.applyAddressChange(row, host, assertOwned);
       }
       row.encryptedPayload = null;
       await this.phase(row, "completed", assertOwned);
@@ -15707,10 +15805,7 @@ var WagoNetworkChangeService = class {
       audited = false;
       return this.status(controllerId);
     } catch (error) {
-      if (row && row.phase !== "completed") {
-        row.failure = error instanceof RuntimeUpdateError || error instanceof NetworkChangeError ? error.failure : "interrupted";
-        await assertOwned().then(() => this.repository.save(row)).catch(() => void 0);
-      }
+      if (row && row.phase !== "completed") await this.recordFailure(row, error, assertOwned);
       if (audited) await lifecycle.finish("failed");
       throw new import_common36.ConflictException("MQTT/address change is incomplete. Check its status and retry the saved operation.");
     } finally {
@@ -15720,6 +15815,44 @@ var WagoNetworkChangeService = class {
       await operations.release(access.fingerprint, owner);
     }
   }
+  /** Network changes must not race credential rotation or runtime update recovery. */
+  async assertNoPendingRecovery(controllerId) {
+    const rotation = await this.context.getRepository(WagoCredentialRotationEntity).findOneBy({ controllerId });
+    const update = await this.context.getRepository(WagoRuntimeUpdateEntity).findOneBy({ controllerId });
+    if (rotation && rotation.phase !== "completed" || update?.metadata && JSON.parse(update.metadata).token)
+      throw new import_common36.ConflictException(
+        "Finish credential rotation or runtime update recovery before changing MQTT/address settings."
+      );
+  }
+  /** Durably record a new change intent before contacting the controller. */
+  async savePendingChange(controllerId, access, input, assertOwned) {
+    if (!input) throw new import_common36.BadRequestException("Invalid MQTT/address change");
+    const row = this.repository.create({
+      controllerId,
+      sessionId: access.sessionId,
+      fingerprint: access.fingerprint,
+      ...input,
+      phase: "connecting",
+      failure: null,
+      encryptedPayload: null,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await assertOwned();
+    await this.repository.save(row);
+    return row;
+  }
+  /** Apply an address-only change; the broker binding stays unchanged. */
+  async applyAddressChange(row, host, assertOwned) {
+    if (await host.command(`mqtt-address ${host.managementToken}`) !== "OK\n")
+      throw new RuntimeUpdateError("recovery");
+    await this.phase(row, "saving", assertOwned);
+    await this.saveBindings(row, host.encryptedCredentials, null, assertOwned);
+  }
+  /** Keep the durable intent for an explicit retry, recording only a safe failure code. */
+  async recordFailure(row, error, assertOwned) {
+    row.failure = error instanceof RuntimeUpdateError || error instanceof NetworkChangeError ? error.failure : "interrupted";
+    await assertOwned().then(() => this.repository.save(row)).catch(() => void 0);
+  }
   async applyBrokerChange(controllerId, row, controller, host, abort, assertOwned, retry) {
     let superseded;
     let connection;