@marcel2215/homebridge-supla-plugin 2.1.28 → 2.1.30

package/dist/Accesories/FrontGateFsm.js

@@ -1,53 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FrontGateFsm = exports.DEFAULT_FRONT_GATE_TIMINGS = void 0;
-exports.DEFAULT_FRONT_GATE_TIMINGS = {
+exports.FrontGateFsm = exports.FrontGateError = exports.DEFAULT_FRONT_GATE_CONFIG = void 0;
+exports.DEFAULT_FRONT_GATE_CONFIG = {
     fullTravelMs: 25000,
     reversePauseMs: 3000,
-    wrongDirectionRunMs: 0,
     minimumPulseGapMs: 3000,
-    closeRetryLimit: 0,
+    unknownOpenPolicy: 'reject',
+    unknownClosePolicy: 'reject',
+    seekClosedMaxPulses: 3,
+    assumeOpenAfterTravel: false,
 };
-function delay(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+class FrontGateError extends Error {
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'FrontGateError';
+    }
 }
-function clampInt(value, min, max) {
+exports.FrontGateError = FrontGateError;
+const SYSTEM_SCHEDULER = {
+    now: () => Date.now(),
+    schedule: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs);
+        return () => clearTimeout(timer);
+    },
+};
+function clampInt(value, fallback, min, max) {
     if (!Number.isFinite(value)) {
-        return min;
+        return fallback;
     }
     return Math.min(max, Math.max(min, Math.round(value)));
 }
-function oppositeDirection(direction) {
-    return direction === 'opening' ? 'closing' : 'opening';
+function targetForDirection(direction) {
+    return direction === 'opening' ? 'open' : 'closed';
 }
 class FrontGateFsm {
-    constructor(io, timings = exports.DEFAULT_FRONT_GATE_TIMINGS, _persisted = {}) {
+    constructor(io, config = exports.DEFAULT_FRONT_GATE_CONFIG, scheduler = SYSTEM_SCHEDULER) {
         this.io = io;
         this.facts = {
+            transportConnected: false,
             controlConnected: null,
             sensorConnected: null,
             closedSensor: null,
         };
-        this.sensorFreshSinceOnline = false;
-        this.requestedTarget = null;
-        this.idleNotClosedMode = 'openishUnknown';
-        this.idleNextPulseDirection = 'unknown';
-        this.plan = { kind: 'idle' };
-        this.lastPulseLikeActivityAt = 0;
-        this.movementTimerToken = 0;
-        this.phaseTimerToken = 0;
+        this.observationEpoch = 1;
+        this.sensorSampleEpoch = null;
+        this.previousSensorInEpoch = null;
+        this.desiredTarget = null;
+        this.position = { kind: 'notClosedUnknown' };
+        this.positionGeneration = 0;
+        this.operation = { kind: 'none' };
+        this.nextOperationId = 0;
+        this.lastPublishedPulseAt = 0;
         this.sequence = Promise.resolve(undefined);
         this.disposed = false;
-        this.travelMs = clampInt(timings.fullTravelMs || exports.DEFAULT_FRONT_GATE_TIMINGS.fullTravelMs, 5000, 120000);
-        this.pulseGapMs = Math.max(3000, clampInt(timings.minimumPulseGapMs || exports.DEFAULT_FRONT_GATE_TIMINGS.minimumPulseGapMs, 0, 15000), clampInt(timings.reversePauseMs || exports.DEFAULT_FRONT_GATE_TIMINGS.reversePauseMs, 0, 15000));
+        this.config = {
+            fullTravelMs: clampInt(config.fullTravelMs ?? exports.DEFAULT_FRONT_GATE_CONFIG.fullTravelMs, exports.DEFAULT_FRONT_GATE_CONFIG.fullTravelMs, 1, 120000),
+            reversePauseMs: clampInt(config.reversePauseMs ?? exports.DEFAULT_FRONT_GATE_CONFIG.reversePauseMs, exports.DEFAULT_FRONT_GATE_CONFIG.reversePauseMs, 0, 15000),
+            minimumPulseGapMs: clampInt(config.minimumPulseGapMs ?? exports.DEFAULT_FRONT_GATE_CONFIG.minimumPulseGapMs, exports.DEFAULT_FRONT_GATE_CONFIG.minimumPulseGapMs, 0, 15000),
+            unknownOpenPolicy: config.unknownOpenPolicy ?? exports.DEFAULT_FRONT_GATE_CONFIG.unknownOpenPolicy,
+            unknownClosePolicy: config.unknownClosePolicy ?? exports.DEFAULT_FRONT_GATE_CONFIG.unknownClosePolicy,
+            seekClosedMaxPulses: clampInt(config.seekClosedMaxPulses ?? exports.DEFAULT_FRONT_GATE_CONFIG.seekClosedMaxPulses, exports.DEFAULT_FRONT_GATE_CONFIG.seekClosedMaxPulses, 1, 3),
+            assumeOpenAfterTravel: config.assumeOpenAfterTravel ?? exports.DEFAULT_FRONT_GATE_CONFIG.assumeOpenAfterTravel,
+        };
+        this.scheduler = scheduler;
         this.emitSnapshot('fsm-initialized');
     }
     dispose() {
         this.disposed = true;
-        this.clearTimers();
+        this.clearMovementTimer();
+        this.clearOperation();
     }
-    handleConnectedChange(connected) {
-        this.handleControlConnectedChange(connected);
+    handleTransportConnectedChange(connected) {
+        void this.enqueue(`transport-connected=${connected}`, () => {
+            this.applyTransportConnectedChange(connected);
+        });
     }
     handleControlConnectedChange(connected) {
         void this.enqueue(`control-connected=${connected}`, () => {
@@ -59,17 +86,26 @@ class FrontGateFsm {
             this.applySensorConnectedChange(connected);
         });
     }
-    handleClosedSensorChange(closed) {
+    handleClosedSensorChange(closed, evidence = {}) {
         void this.enqueue(`closed-sensor=${closed}`, () => {
-            this.applyClosedSensorChange(closed);
+            this.applyClosedSensorChange(closed, evidence);
         });
     }
+    restoreCommandUncertainty() {
+        if (this.disposed) {
+            return;
+        }
+        this.clearOperation();
+        this.desiredTarget = null;
+        this.setPosition({ kind: 'commandUncertain' });
+        this.emitSnapshot('command-uncertainty-restored');
+    }
     handleObservedExternalPulse(reason = 'mqtt-execute_action') {
         void this.enqueue(`external-pulse=${reason}`, () => {
             this.applyObservedExternalPulse(reason);
         });
     }
-    async requestHomeKitTarget(target) {
+    requestHomeKitTarget(target) {
         return this.enqueue(`homekit-target=${target}`, async () => {
             await this.applyHomeKitTarget(target);
         });
@@ -77,15 +113,17 @@ class FrontGateFsm {
     getSnapshot() {
         return this.buildSnapshot('snapshot-requested');
     }
+    whenIdle() {
+        return this.sequence;
+    }
     enqueue(label, task) {
         if (this.disposed) {
             return Promise.resolve();
         }
         const run = this.sequence.then(async () => {
-            if (this.disposed) {
-                return;
+            if (!this.disposed) {
+                await task();
             }
-            await task();
         });
         this.sequence = run.catch(error => {
             const message = error instanceof Error ? error.message : String(error);
@@ -93,21 +131,31 @@ class FrontGateFsm {
         });
         return run;
     }
+    applyTransportConnectedChange(connected) {
+        if (this.facts.transportConnected === connected) {
+            return;
+        }
+        this.facts.transportConnected = connected;
+        if (!connected) {
+            this.facts.controlConnected = null;
+            this.facts.sensorConnected = null;
+            this.advanceObservationEpoch('mqtt-transport-offline');
+            return;
+        }
+        this.io.log.info('front gate MQTT transport connected');
+        this.emitSnapshot('mqtt-transport-online-awaiting-channel-state');
+    }
     applyControlConnectedChange(connected) {
         if (this.facts.controlConnected === connected) {
             return;
         }
         this.facts.controlConnected = connected;
         if (!connected) {
-            this.io.log.warn('front gate control channel went offline');
-            this.enterUnavailable('control-offline');
+            this.advanceObservationEpoch('control-channel-offline');
             return;
         }
         this.io.log.info('front gate control channel connected');
-        this.clearTimers();
-        this.plan = { kind: 'idle' };
-        this.sensorFreshSinceOnline = false;
-        this.emitSnapshot('control-online-awaiting-fresh-sensor');
+        this.emitSnapshot('control-channel-online');
     }
     applySensorConnectedChange(connected) {
         if (this.facts.sensorConnected === connected) {
@@ -115,474 +163,586 @@ class FrontGateFsm {
         }
         this.facts.sensorConnected = connected;
         if (!connected) {
-            this.io.log.warn('front gate sensor channel went offline');
-            this.enterUnavailable('sensor-offline');
+            this.advanceObservationEpoch('sensor-channel-offline');
             return;
         }
         this.io.log.info('front gate sensor channel connected');
-        this.clearTimers();
-        this.plan = { kind: 'idle' };
-        this.sensorFreshSinceOnline = false;
-        this.emitSnapshot('sensor-online-awaiting-fresh-state');
-    }
-    applyClosedSensorChange(closed) {
-        const previous = this.facts.closedSensor;
-        const wasFresh = this.sensorFreshSinceOnline;
-        this.facts.closedSensor = closed;
-        if (this.facts.controlConnected === true && this.facts.sensorConnected === true) {
-            this.sensorFreshSinceOnline = true;
-        }
-        const becameFresh = !wasFresh && this.sensorFreshSinceOnline;
-        if (previous === closed && !becameFresh) {
+        this.emitSnapshot('sensor-channel-online');
+    }
+    applyClosedSensorChange(closed, evidence) {
+        if (this.position.kind === 'commandUncertain' && evidence.retained === true) {
+            this.io.log.warn('ignoring retained closed-sensor replay while command outcome is uncertain');
+            this.emitSnapshot('command-uncertain-retained-sensor-ignored');
             return;
         }
-        if (closed) {
-            this.io.log.info('closed sensor is TRUE -> gate is fully closed');
-            this.clearTimers();
-            this.plan = { kind: 'idle' };
-            this.idleNextPulseDirection = 'opening';
-            this.idleNotClosedMode = 'openishUnknown';
-            if (this.requestedTarget === 'open' && this.isAvailableForHomeKit()) {
-                this.emitSnapshot('closed-sensor-true-but-open-still-requested');
-                void this.enqueue('auto-open-after-closed', async () => {
-                    await this.startOpeningFromClosed('auto-open-after-closed');
-                });
-                return;
+        const hadSampleInEpoch = this.sensorSampleEpoch === this.observationEpoch;
+        const previous = hadSampleInEpoch ? this.previousSensorInEpoch : null;
+        this.facts.closedSensor = closed;
+        this.sensorSampleEpoch = this.observationEpoch;
+        this.previousSensorInEpoch = closed;
+        if (this.position.kind === 'commandUncertain') {
+            this.clearOperation();
+            if (closed) {
+                this.setPosition({ kind: 'closed' });
             }
-            this.requestedTarget = null;
-            this.emitSnapshot('closed-sensor-true');
+            else {
+                this.desiredTarget = null;
+                this.setPosition({ kind: 'notClosedUnknown' });
+            }
+            this.emitSnapshot('command-uncertainty-cleared-by-fresh-sensor');
             return;
         }
-        this.io.log.info('closed sensor is FALSE -> gate is not fully closed');
-        if (previous === true) {
-            // Leaving the closed end-stop is the one fully reliable motion signal we have:
-            // the gate is opening.
-            this.lastPulseLikeActivityAt = Date.now();
-            if (this.requestedTarget !== 'open') {
-                this.requestedTarget = null;
+        if (!hadSampleInEpoch) {
+            this.clearOperation();
+            if (closed) {
+                this.setPosition({ kind: 'closed' });
             }
-            this.startOpeningMotion(this.requestedTarget === 'open' ? 'homekit' : 'external', 'closed-sensor-fell-from-true-to-false');
+            else {
+                this.setPosition({ kind: 'notClosedUnknown' });
+            }
+            this.emitSnapshot('sensor-baseline-established');
+            return;
+        }
+        if (previous === closed) {
             return;
         }
-        if (this.plan.kind === 'idle' && this.requestedTarget === 'open') {
-            this.requestedTarget = null;
+        this.clearOperation();
+        if (closed) {
+            this.io.log.info('closed sensor is TRUE -> gate is fully closed');
+            this.setPosition({ kind: 'closed' });
+            this.emitSnapshot('closed-sensor-true');
+            return;
         }
-        this.emitSnapshot('closed-sensor-false');
+        this.io.log.info('closed sensor changed TRUE -> FALSE in the current observation epoch');
+        this.setKnownMovement('opening');
+        this.emitSnapshot('closed-sensor-opening-edge');
     }
     async applyHomeKitTarget(target) {
         if (!this.isAvailableForHomeKit()) {
-            throw new Error('front gate controller is not available');
+            throw new FrontGateError('unavailable', 'front gate controller is not available');
         }
-        this.requestedTarget = target;
-        if (target === 'open') {
-            await this.handleOpenRequest();
-            return;
-        }
-        await this.handleCloseRequest();
-    }
-    async handleOpenRequest() {
-        if (this.facts.closedSensor === true) {
-            if (this.plan.kind === 'moving' && this.plan.direction === 'opening') {
-                this.emitSnapshot('open-request-already-opening-from-closed');
+        if (this.operation.kind !== 'none') {
+            if (this.operation.target === target) {
+                this.desiredTarget = target;
+                this.emitSnapshot(`homekit-${target}-already-accepted`);
                 return;
             }
-            if (this.plan.kind === 'waitingSecondPulse' && this.plan.finalDirection === 'opening') {
-                this.emitSnapshot('open-request-already-reversing-to-open');
-                return;
-            }
-            await this.startOpeningFromClosed('homekit-open-from-closed');
+            this.cancelConflictingOperation();
+        }
+        const previousTarget = this.desiredTarget;
+        try {
+            const note = target === 'open'
+                ? await this.acceptOpenRequest()
+                : await this.acceptCloseRequest();
+            this.desiredTarget = this.position.kind === 'closed' && target === 'closed' ? null : target;
+            this.emitSnapshot(note);
+        }
+        catch (error) {
+            this.desiredTarget = this.position.kind === 'closed' ? null : previousTarget;
+            this.emitSnapshot(`homekit-${target}-rejected`);
+            throw error;
+        }
+    }
+    async acceptOpenRequest() {
+        switch (this.position.kind) {
+            case 'closed':
+                return this.acceptPulse({ kind: 'startOpening' }, 'open');
+            case 'openingKnown':
+            case 'openAssumed':
+                return 'open-request-already-satisfied-or-in-progress';
+            case 'closingKnown':
+                return this.acceptPulse({ kind: 'stopAndReverse', finalDirection: 'opening' }, 'open');
+            case 'reversalPause':
+            case 'commandUncertain':
+            case 'notClosedUnknown':
+                if (this.config.unknownOpenPolicy === 'accept_non_closed') {
+                    return 'unknown-open-request-accepted-as-non-closed';
+                }
+                throw new FrontGateError('not_allowed', 'cannot safely open the front gate because its direction and position are unknown');
+        }
+    }
+    async acceptCloseRequest() {
+        switch (this.position.kind) {
+            case 'closed':
+                return 'close-request-already-satisfied';
+            case 'closingKnown':
+                return 'close-request-already-in-progress';
+            case 'openingKnown':
+                if (this.facts.closedSensor === true) {
+                    return this.acceptPulse({ kind: 'stopOpeningAtClosed' }, 'closed');
+                }
+                return this.acceptPulse({ kind: 'stopAndReverse', finalDirection: 'closing' }, 'closed');
+            case 'openAssumed':
+                return this.acceptPulse({ kind: 'startClosing' }, 'closed');
+            case 'reversalPause':
+            case 'commandUncertain':
+            case 'notClosedUnknown':
+                return this.acceptUnknownCloseRequest();
+        }
+    }
+    async acceptUnknownCloseRequest() {
+        if (this.desiredTarget === 'closed') {
+            throw new FrontGateError('not_allowed', 'the previous close request remains unconfirmed; refusing to repeat a non-idempotent toggle');
+        }
+        switch (this.config.unknownClosePolicy) {
+            case 'single_pulse_best_effort':
+                return this.acceptPulse({ kind: 'bestEffortClose' }, 'closed');
+            case 'seek_closed':
+                return this.acceptPulse({
+                    kind: 'seekClosed',
+                    pulseNumber: 1,
+                    maxPulses: this.config.seekClosedMaxPulses,
+                }, 'closed');
+            case 'reject':
+                throw new FrontGateError('not_allowed', 'cannot safely close the front gate because its direction and position are unknown');
+        }
+    }
+    async acceptPulse(purpose, target) {
+        const now = this.scheduler.now();
+        const dueAt = Math.max(now, this.lastPublishedPulseAt + this.config.minimumPulseGapMs);
+        const operation = {
+            kind: 'scheduledPulse',
+            id: ++this.nextOperationId,
+            epoch: this.observationEpoch,
+            dueAt,
+            target,
+            expectedPosition: this.position.kind,
+            purpose,
+        };
+        this.setOperation(operation);
+        if (dueAt > now) {
+            this.scheduleOperationTimer(operation);
+            return `${purpose.kind}-scheduled`;
+        }
+        await this.executeScheduledPulse(operation, true);
+        return `${purpose.kind}-published`;
+    }
+    async executeScheduledPulse(operation, propagateError) {
+        if (!this.validateScheduledPulse(operation, !propagateError)) {
             return;
         }
-        if (this.plan.kind === 'moving') {
-            if (this.plan.direction === 'opening') {
-                this.emitSnapshot('open-request-already-opening');
+        try {
+            this.io.log.info(`motor pulse -> ${operation.purpose.kind}`);
+            await this.io.pulseMotor(operation.purpose.kind);
+            if (this.disposed || !this.hasCurrentOperation(operation.id)) {
                 return;
             }
-            if (this.plan.certainty === 'known') {
-                await this.reverseKnownMotion('opening', 'homekit-reverse-known-closing-to-open');
-                return;
+            this.lastPublishedPulseAt = this.scheduler.now();
+            this.applySuccessfulPulse(operation);
+            if (!propagateError) {
+                this.emitSnapshot(`${operation.purpose.kind}-published`);
             }
-            this.io.log.warn('open requested during ambiguous close attempt; not sending more pulses because the actual motion direction is unknown');
-            this.clearTimers();
-            this.plan = { kind: 'idle' };
-            this.idleNotClosedMode = 'openishUnknown';
-            this.idleNextPulseDirection = 'unknown';
-            this.requestedTarget = null;
-            this.emitSnapshot('open-request-during-ambiguous-close-attempt');
-            return;
         }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            if (this.plan.finalDirection === 'opening') {
-                this.emitSnapshot('open-request-already-reversing-to-open');
-                return;
+        catch (error) {
+            if (!this.disposed && this.hasCurrentOperation(operation.id)) {
+                this.clearOperation();
+                if (this.isAmbiguousPulseFailure(error)) {
+                    this.desiredTarget = null;
+                    this.setPosition({ kind: 'commandUncertain' });
+                }
+                else if (operation.purpose.kind === 'stopAndReverse' || this.facts.closedSensor !== true) {
+                    this.setPosition({ kind: 'notClosedUnknown' });
+                }
+                else {
+                    this.setPosition({ kind: 'closed' });
+                }
+                if (!propagateError) {
+                    this.io.log.warn(`scheduled front-gate pulse failed: ${this.errorMessage(error)}`);
+                    this.emitSnapshot(`${operation.purpose.kind}-publish-failed`);
+                }
+            }
+            if (propagateError) {
+                if (error instanceof FrontGateError) {
+                    throw error;
+                }
+                throw new FrontGateError('communication_failure', `failed to publish front-gate pulse: ${this.errorMessage(error)}`, { cause: error });
             }
-            // We already stopped an opening run, so the next pulse can only start closing.
-            // To honor the latest OPEN request without leaving the gate stopped in the middle,
-            // keep the pending close, let the gate reach the closed end-stop, then auto-open.
-            this.io.log.info('open requested while waiting to restart towards close; keeping the pending close and will auto-open from closed');
-            this.emitSnapshot('open-request-deferred-until-closed');
-            return;
-        }
-        if (this.idleNextPulseDirection === 'opening') {
-            await this.startOpeningFromStoppedState('homekit-open-from-stopped-after-closing');
-            return;
         }
-        this.requestedTarget = null;
-        this.emitSnapshot('open-request-already-satisfied-openish');
     }
-    async handleCloseRequest() {
-        if (this.facts.closedSensor === true) {
-            if (this.plan.kind === 'moving' && this.plan.direction === 'opening') {
-                // We are still physically on the closed end-stop, so a single pulse cleanly
-                // cancels the opening attempt and leaves the gate closed.
-                await this.pulseMotor('cancel-opening-while-still-closed');
-                this.clearTimers();
-                this.plan = { kind: 'idle' };
-                this.idleNextPulseDirection = 'opening';
-                this.requestedTarget = null;
-                this.emitSnapshot('opening-cancelled-before-leaving-closed');
+    applySuccessfulPulse(operation) {
+        switch (operation.purpose.kind) {
+            case 'startOpening':
+                this.clearOperation();
+                this.setKnownMovement('opening');
                 return;
-            }
-            this.requestedTarget = null;
-            this.emitSnapshot('close-request-already-satisfied');
-            return;
-        }
-        if (this.plan.kind === 'moving') {
-            if (this.plan.direction === 'closing') {
-                this.emitSnapshot(this.plan.certainty === 'known' ? 'close-request-already-closing' : 'close-request-already-close-seeking');
+            case 'startClosing':
+                this.clearOperation();
+                this.setKnownMovement('closing');
                 return;
-            }
-            await this.reverseKnownMotion('closing', 'homekit-reverse-known-opening-to-close');
-            return;
-        }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            if (this.plan.finalDirection === 'closing') {
-                this.emitSnapshot('close-request-already-reversing-to-close');
+            case 'bestEffortClose':
+                this.clearOperation();
+                this.setPosition({ kind: 'notClosedUnknown' });
                 return;
-            }
-            // We already stopped a closing run, so the next pulse can only start opening.
-            // To honor the latest CLOSE request without leaving the gate stopped in the middle,
-            // keep the pending open, let the gate become fully open-ish by timeout, then auto-close.
-            this.io.log.info('close requested while waiting to restart towards open; keeping the pending open and will auto-close after the opening run settles');
-            this.emitSnapshot('close-request-deferred-until-open');
+            case 'stopOpeningAtClosed':
+                this.clearOperation();
+                this.setPosition({ kind: 'closed' });
+                return;
+            case 'stopAndReverse':
+                this.startReversalPause(operation.purpose.finalDirection, operation.target);
+                return;
+            case 'seekClosed':
+                this.setPosition({ kind: 'notClosedUnknown' });
+                this.startSeekClosedWait(operation.purpose.pulseNumber, operation.purpose.maxPulses);
+        }
+    }
+    startReversalPause(finalDirection, target) {
+        this.setPosition({ kind: 'reversalPause' });
+        const now = this.scheduler.now();
+        const operation = {
+            kind: 'reversalPause',
+            id: ++this.nextOperationId,
+            epoch: this.observationEpoch,
+            dueAt: Math.max(now + this.config.reversePauseMs, this.lastPublishedPulseAt + this.config.minimumPulseGapMs),
+            target,
+            finalDirection,
+        };
+        this.setOperation(operation);
+        this.scheduleOperationTimer(operation);
+    }
+    startSeekClosedWait(pulsesUsed, maxPulses) {
+        const operation = {
+            kind: 'seekClosed',
+            id: ++this.nextOperationId,
+            epoch: this.observationEpoch,
+            dueAt: this.scheduler.now() + this.config.fullTravelMs,
+            target: 'closed',
+            pulsesUsed,
+            maxPulses,
+        };
+        this.setOperation(operation);
+        this.scheduleOperationTimer(operation);
+    }
+    scheduleOperationTimer(operation) {
+        this.clearOperationTimer();
+        const delayMs = Math.max(0, operation.dueAt - this.scheduler.now());
+        this.cancelOperationTimer = this.scheduler.schedule(() => {
+            void this.enqueue(`operation-timer-${operation.id}`, async () => {
+                await this.handleOperationTimer(operation.id);
+            });
+        }, delayMs);
+    }
+    async handleOperationTimer(operationId) {
+        if (this.operation.kind === 'none' || this.operation.id !== operationId) {
             return;
         }
-        if (this.idleNotClosedMode === 'openKnown' || this.idleNextPulseDirection === 'closing') {
-            await this.startKnownCloseFromIdle('homekit-close-from-openish-known');
+        const operation = this.operation;
+        if (!this.validateOperationContext(operation)) {
+            this.cancelInvalidOperation('scheduled-operation-guard-failed');
             return;
         }
-        if (this.idleNextPulseDirection === 'opening') {
-            this.io.log.warn('close requested while the gate is stopped after a closing run; the next pulse would open, so no corrective pulse is sent');
-            this.requestedTarget = null;
-            this.emitSnapshot('close-request-not-directly-actionable-from-stopped-closing');
+        if (operation.kind === 'scheduledPulse') {
+            await this.executeScheduledPulse(operation, false);
             return;
         }
-        await this.startAmbiguousCloseAttempt('homekit-close-from-openish-ambiguous');
-    }
-    async startOpeningFromClosed(reason) {
-        if (this.facts.closedSensor !== true) {
-            this.requestedTarget = null;
-            this.emitSnapshot(`${reason}-already-openish`);
+        if (operation.kind === 'reversalPause') {
+            await this.executeReversalPulse(operation);
             return;
         }
-        await this.pulseMotor(reason);
-        this.startOpeningMotion('homekit', `${reason}-pulse-sent`);
+        await this.advanceSeekClosed(operation);
     }
-    async startOpeningFromStoppedState(reason) {
-        if (this.facts.closedSensor === true) {
-            await this.startOpeningFromClosed(`${reason}-closed-fallback`);
+    async executeReversalPulse(operation) {
+        if (this.position.kind !== 'reversalPause') {
+            this.cancelInvalidOperation('reversal-position-changed');
             return;
         }
-        await this.pulseMotor(reason);
-        this.startOpeningMotion('homekit', `${reason}-pulse-sent`);
-    }
-    async startKnownCloseFromIdle(reason) {
-        if (this.facts.closedSensor === true) {
-            this.requestedTarget = null;
-            this.emitSnapshot(`${reason}-already-closed`);
-            return;
+        try {
+            this.io.log.info(`motor pulse -> finish-reversal-${operation.finalDirection}`);
+            await this.io.pulseMotor(`finish-reversal-${operation.finalDirection}`);
+            if (this.disposed || !this.hasCurrentOperation(operation.id)) {
+                return;
+            }
+            this.lastPublishedPulseAt = this.scheduler.now();
+            this.clearOperation();
+            this.setKnownMovement(operation.finalDirection);
+            this.emitSnapshot(`reversal-second-pulse-${operation.finalDirection}`);
+        }
+        catch (error) {
+            if (this.disposed || !this.hasCurrentOperation(operation.id)) {
+                return;
+            }
+            this.io.log.warn(`front-gate reversal pulse failed: ${this.errorMessage(error)}`);
+            this.clearOperation();
+            if (this.isAmbiguousPulseFailure(error)) {
+                this.desiredTarget = null;
+                this.setPosition({ kind: 'commandUncertain' });
+            }
+            else {
+                this.setPosition({ kind: 'notClosedUnknown' });
+            }
+            this.emitSnapshot('reversal-second-pulse-failed');
         }
-        await this.pulseMotor(reason);
-        this.startClosingMotion('known', 'homekit', `${reason}-pulse-sent`);
     }
-    async startAmbiguousCloseAttempt(reason) {
+    async advanceSeekClosed(operation) {
         if (this.facts.closedSensor === true) {
-            this.requestedTarget = null;
-            this.emitSnapshot(`${reason}-already-closed`);
-            return;
+            this.clearOperation();
+            this.setPosition({ kind: 'closed' });
+            this.emitSnapshot('seek-closed-succeeded');
+            return;
+        }
+        if (operation.pulsesUsed >= operation.maxPulses) {
+            this.io.log.warn(`seek-closed exhausted ${operation.maxPulses} pulse(s) without reaching the sensor`);
+            this.clearOperation();
+            this.setPosition({ kind: 'notClosedUnknown' });
+            this.emitSnapshot('seek-closed-exhausted');
+            return;
+        }
+        try {
+            await this.acceptPulse({
+                kind: 'seekClosed',
+                pulseNumber: operation.pulsesUsed + 1,
+                maxPulses: operation.maxPulses,
+            }, 'closed');
+            this.emitSnapshot('seek-closed-next-pulse-accepted');
+        }
+        catch (error) {
+            this.io.log.warn(`seek-closed pulse failed: ${this.errorMessage(error)}`);
+            this.clearOperation();
+            if (this.isAmbiguousPulseFailure(error)) {
+                this.desiredTarget = null;
+                this.setPosition({ kind: 'commandUncertain' });
+            }
+            else if (this.position.kind !== 'commandUncertain') {
+                this.setPosition({ kind: 'notClosedUnknown' });
+            }
+            this.emitSnapshot('seek-closed-pulse-failed');
         }
-        await this.pulseMotor(reason);
-        this.startClosingMotion('goalOnly', 'homekit', `${reason}-pulse-sent`);
     }
-    async reverseKnownMotion(finalDirection, reason) {
-        if (this.plan.kind !== 'moving') {
-            return;
+    validateScheduledPulse(operation, requireCommittedTarget) {
+        if (this.disposed || this.operation.kind !== 'scheduledPulse' || this.operation.id !== operation.id) {
+            return false;
         }
-        const stoppedFrom = this.plan.direction;
-        await this.pulseMotor(`${reason}-stop-current-motion`);
-        const deadlineAt = Date.now() + this.pulseGapMs + this.travelMs;
-        this.clearMovementTimer();
-        this.plan = {
-            kind: 'waitingSecondPulse',
-            stoppedFrom,
-            finalDirection,
-            source: 'homekit',
-            dueAt: Date.now() + this.pulseGapMs,
-            deadlineAt,
-            reason: finalDirection === 'opening' ? 'reverseToOpen' : 'reverseToClose',
-        };
-        this.schedulePhaseTimer(this.plan.dueAt);
-        this.emitSnapshot(`${reason}-waiting-second-pulse`);
-    }
-    startOpeningMotion(source, note) {
-        this.clearPhaseTimer();
-        this.plan = {
-            kind: 'moving',
-            direction: 'opening',
-            certainty: 'known',
-            source,
-            startedAt: Date.now(),
-            deadlineAt: Date.now() + this.travelMs,
-        };
-        this.scheduleMovementTimer(this.plan.deadlineAt);
-        this.emitSnapshot(note);
-    }
-    startClosingMotion(certainty, source, note) {
-        this.clearPhaseTimer();
-        this.plan = {
-            kind: 'moving',
-            direction: 'closing',
-            certainty,
-            source,
-            startedAt: Date.now(),
-            deadlineAt: Date.now() + this.travelMs,
-        };
-        this.scheduleMovementTimer(this.plan.deadlineAt);
-        this.emitSnapshot(note);
-    }
-    scheduleMovementTimer(deadlineAt) {
-        this.clearMovementTimer();
-        const delayMs = Math.max(0, deadlineAt - Date.now());
-        const token = ++this.movementTimerToken;
-        this.movementTimer = setTimeout(() => {
-            void this.enqueue(`movement-timeout-${token}`, async () => {
-                if (token !== this.movementTimerToken) {
-                    return;
+        if (!this.validateOperationContext(operation, requireCommittedTarget)) {
+            this.cancelInvalidOperation('scheduled-pulse-context-invalid');
+            return false;
+        }
+        if (this.position.kind !== operation.expectedPosition) {
+            this.cancelInvalidOperation('scheduled-pulse-position-invalid');
+            return false;
+        }
+        switch (operation.purpose.kind) {
+            case 'startOpening':
+            case 'stopOpeningAtClosed':
+                if (this.facts.closedSensor !== true) {
+                    this.cancelInvalidOperation('scheduled-pulse-closed-sensor-invalid');
+                    return false;
                 }
-                await this.handleMovementTimeout();
-            });
-        }, delayMs);
-    }
-    schedulePhaseTimer(dueAt) {
-        this.clearPhaseTimer();
-        const delayMs = Math.max(0, dueAt - Date.now());
-        const token = ++this.phaseTimerToken;
-        this.phaseTimer = setTimeout(() => {
-            void this.enqueue(`phase-timer-${token}`, async () => {
-                if (token !== this.phaseTimerToken) {
-                    return;
+                break;
+            case 'startClosing':
+            case 'bestEffortClose':
+            case 'stopAndReverse':
+            case 'seekClosed':
+                if (this.facts.closedSensor !== false) {
+                    this.cancelInvalidOperation('scheduled-pulse-not-closed-sensor-invalid');
+                    return false;
                 }
-                await this.handlePhaseTimer();
-            });
-        }, delayMs);
+                break;
+        }
+        return true;
     }
-    clearMovementTimer() {
-        if (this.movementTimer) {
-            clearTimeout(this.movementTimer);
-            this.movementTimer = undefined;
+    validateOperationContext(operation, requireCommittedTarget = true) {
+        return !this.disposed
+            && operation.epoch === this.observationEpoch
+            && this.isAvailableForHomeKit()
+            && (!requireCommittedTarget || this.desiredTarget === operation.target);
+    }
+    hasCurrentOperation(operationId) {
+        return this.operation.kind !== 'none' && this.operation.id === operationId;
+    }
+    cancelConflictingOperation() {
+        const operation = this.operation;
+        this.clearOperation();
+        if (operation.kind === 'reversalPause') {
+            this.setPosition({ kind: 'notClosedUnknown' });
         }
-        this.movementTimerToken += 1;
     }
-    clearPhaseTimer() {
-        if (this.phaseTimer) {
-            clearTimeout(this.phaseTimer);
-            this.phaseTimer = undefined;
+    cancelInvalidOperation(note) {
+        const operation = this.operation;
+        this.clearOperation();
+        if (operation.kind === 'reversalPause') {
+            this.setPosition({ kind: 'notClosedUnknown' });
         }
-        this.phaseTimerToken += 1;
+        this.io.log.warn(`front-gate scheduled operation cancelled: ${note}`);
+        this.emitSnapshot(note);
     }
-    clearTimers() {
-        this.clearMovementTimer();
-        this.clearPhaseTimer();
+    applyObservedExternalPulse(reason) {
+        if (this.position.kind === 'commandUncertain') {
+            this.io.log.warn('ignoring command-topic pulse evidence while awaiting a fresh physical sensor sample');
+            this.emitSnapshot(`command-uncertain-awaiting-sensor-${reason}`);
+            return;
+        }
+        this.clearOperation();
+        this.desiredTarget = null;
+        if (this.facts.closedSensor === true && this.sensorSampleEpoch === this.observationEpoch) {
+            this.setKnownMovement('opening');
+            this.emitSnapshot(`external-pulse-from-closed-${reason}`);
+            return;
+        }
+        this.setPosition({ kind: 'notClosedUnknown' });
+        this.emitSnapshot(`external-pulse-direction-unknown-${reason}`);
+    }
+    advanceObservationEpoch(note) {
+        const preserveCommandUncertainty = this.position.kind === 'commandUncertain';
+        this.observationEpoch += 1;
+        this.sensorSampleEpoch = null;
+        this.previousSensorInEpoch = null;
+        this.desiredTarget = null;
+        this.clearOperation();
+        // A transport/channel epoch can invalidate ordinary position estimates, but
+        // it is not physical evidence about an ambiguous non-idempotent command.
+        // Only a fresh, non-retained sensor sample may clear commandUncertain.
+        this.setPosition(preserveCommandUncertainty
+            ? { kind: 'commandUncertain' }
+            : { kind: 'notClosedUnknown' });
+        this.io.log.warn(`front-gate observation epoch invalidated: ${note}`);
+        this.emitSnapshot(note);
     }
-    async handlePhaseTimer() {
-        if (this.plan.kind !== 'waitingSecondPulse') {
-            return;
+    setKnownMovement(direction) {
+        const now = this.scheduler.now();
+        this.setPosition(direction === 'opening'
+            ? { kind: 'openingKnown', startedAt: now, epoch: this.observationEpoch }
+            : { kind: 'closingKnown', startedAt: now, epoch: this.observationEpoch });
+    }
+    setPosition(position) {
+        this.clearMovementTimer();
+        // A TRUE end-stop is authoritative and supersedes every stale target
+        // intent. Delayed opening requests remain valid because they set their
+        // target after scheduling, without re-entering the closed position.
+        if (position.kind === 'closed') {
+            this.desiredTarget = null;
         }
-        const finalDirection = this.plan.finalDirection;
-        await this.pulseMotor(`second-pulse-${finalDirection}`);
-        this.clearPhaseTimer();
-        if (finalDirection === 'opening') {
-            this.startOpeningMotion(this.plan.source, `second-pulse-fired-${finalDirection}`);
+        this.position = position;
+        const generation = ++this.positionGeneration;
+        if (position.kind !== 'openingKnown' && position.kind !== 'closingKnown') {
             return;
         }
-        this.startClosingMotion('known', this.plan.source, `second-pulse-fired-${finalDirection}`);
+        const epoch = position.epoch;
+        this.cancelMovementTimer = this.scheduler.schedule(() => {
+            void this.enqueue(`movement-timer-${generation}`, () => {
+                this.handleMovementTimeout(generation, epoch);
+            });
+        }, this.config.fullTravelMs);
     }
-    async handleMovementTimeout() {
-        if (this.plan.kind !== 'moving') {
+    handleMovementTimeout(generation, epoch) {
+        if (generation !== this.positionGeneration
+            || epoch !== this.observationEpoch
+            || (this.position.kind !== 'openingKnown' && this.position.kind !== 'closingKnown')) {
             return;
         }
+        const direction = this.position.kind === 'openingKnown' ? 'opening' : 'closing';
+        this.clearOperation();
         if (this.facts.closedSensor === true) {
-            this.clearTimers();
-            this.plan = { kind: 'idle' };
-            this.idleNextPulseDirection = 'opening';
-            this.requestedTarget = null;
-            this.emitSnapshot('movement-timeout-but-already-closed');
+            this.setPosition({ kind: 'closed' });
+            this.emitSnapshot(`${direction}-timeout-at-closed-sensor`);
             return;
         }
-        if (this.plan.direction === 'opening') {
-            // Fully-open and partially-open look identical to us. Once the opening window
-            // expires without any contrary evidence, collapse to the stable open state.
-            this.clearTimers();
-            this.plan = { kind: 'idle' };
-            this.idleNotClosedMode = 'openKnown';
-            this.idleNextPulseDirection = 'closing';
-            if (this.requestedTarget === 'closed' && this.isAvailableForHomeKit()) {
-                this.emitSnapshot('opening-window-elapsed-but-close-still-requested');
-                void this.enqueue('auto-close-after-open', async () => {
-                    await this.startKnownCloseFromIdle('auto-close-after-open');
-                });
-                return;
-            }
-            this.requestedTarget = null;
-            this.emitSnapshot('opening-window-elapsed-open');
+        if (direction === 'opening' && this.config.assumeOpenAfterTravel) {
+            this.setPosition({ kind: 'openAssumed' });
+            this.emitSnapshot('opening-timeout-open-assumed');
             return;
         }
-        this.io.log.warn(this.plan.certainty === 'known'
-            ? 'closing window elapsed without reaching the closed sensor; leaving gate in generic open-ish state'
-            : 'ambiguous close attempt elapsed without reaching the closed sensor; leaving gate in generic open-ish state');
-        this.clearTimers();
-        this.plan = { kind: 'idle' };
-        this.idleNotClosedMode = 'openishUnknown';
-        this.idleNextPulseDirection = 'unknown';
-        this.requestedTarget = null;
-        this.emitSnapshot('closing-window-elapsed-openish');
+        this.setPosition({ kind: 'notClosedUnknown' });
+        this.emitSnapshot(`${direction}-timeout-position-unknown`);
     }
-    applyObservedExternalPulse(reason) {
-        this.lastPulseLikeActivityAt = Date.now();
-        this.requestedTarget = null;
-        if (this.facts.closedSensor === true) {
-            this.startOpeningMotion('external', `external-pulse-observed-while-closed-${reason}`);
-            return;
-        }
-        if (this.plan.kind === 'moving') {
-            const currentDirection = this.plan.direction;
-            const currentCertainty = this.plan.certainty;
-            this.clearTimers();
-            this.plan = { kind: 'idle' };
-            this.idleNotClosedMode = 'openishUnknown';
-            this.idleNextPulseDirection = currentCertainty === 'known'
-                ? oppositeDirection(currentDirection)
-                : 'unknown';
-            this.emitSnapshot(`external-pulse-stopped-${currentDirection}-${reason}`);
-            return;
-        }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            const finalDirection = this.plan.finalDirection;
-            this.clearTimers();
-            if (finalDirection === 'opening') {
-                this.startOpeningMotion('external', `external-pulse-fired-pending-opening-${reason}`);
-                return;
-            }
-            this.startClosingMotion('known', 'external', `external-pulse-fired-pending-closing-${reason}`);
-            return;
-        }
-        if (this.idleNextPulseDirection === 'opening') {
-            this.startOpeningMotion('external', `external-pulse-started-opening-${reason}`);
-            return;
-        }
-        if (this.idleNextPulseDirection === 'closing') {
-            this.startClosingMotion('known', 'external', `external-pulse-started-closing-${reason}`);
-            return;
+    setOperation(operation) {
+        this.clearOperationTimer();
+        this.operation = operation;
+    }
+    clearOperation() {
+        this.clearOperationTimer();
+        this.operation = { kind: 'none' };
+    }
+    clearMovementTimer() {
+        if (this.cancelMovementTimer) {
+            this.cancelMovementTimer();
+            this.cancelMovementTimer = undefined;
         }
-        this.emitSnapshot(`external-pulse-observed-direction-unknown-${reason}`);
     }
-    enterUnavailable(note) {
-        this.clearTimers();
-        this.plan = { kind: 'idle' };
-        this.requestedTarget = null;
-        this.sensorFreshSinceOnline = false;
-        this.idleNotClosedMode = 'openishUnknown';
-        this.idleNextPulseDirection = 'unknown';
-        this.emitSnapshot(note);
+    clearOperationTimer() {
+        if (this.cancelOperationTimer) {
+            this.cancelOperationTimer();
+            this.cancelOperationTimer = undefined;
+        }
     }
     isAvailableForHomeKit() {
-        return this.facts.controlConnected === true
+        return this.facts.transportConnected
+            && this.facts.controlConnected === true
             && this.facts.sensorConnected === true
-            && this.sensorFreshSinceOnline
-            && this.facts.closedSensor !== null;
-    }
-    async pulseMotor(reason) {
-        const elapsed = Date.now() - this.lastPulseLikeActivityAt;
-        if (elapsed < this.pulseGapMs) {
-            await delay(this.pulseGapMs - elapsed);
-        }
-        this.io.log.info(`motor pulse -> ${reason}`);
-        await this.io.pulseMotor(reason);
-        this.lastPulseLikeActivityAt = Date.now();
+            && this.sensorSampleEpoch === this.observationEpoch
+            && this.facts.closedSensor !== null
+            && this.position.kind !== 'commandUncertain';
     }
     emitSnapshot(note) {
-        if (this.disposed) {
-            return;
+        if (!this.disposed) {
+            this.io.publishSnapshot(this.buildSnapshot(note));
         }
-        this.io.publishSnapshot(this.buildSnapshot(note));
     }
     buildSnapshot(note) {
         const available = this.isAvailableForHomeKit();
         return {
             available,
+            transportConnected: this.facts.transportConnected,
             controlConnected: this.facts.controlConnected,
             sensorConnected: this.facts.sensorConnected,
             closedSensor: this.facts.closedSensor,
-            sensorFreshSinceOnline: this.sensorFreshSinceOnline,
+            observationEpoch: this.observationEpoch,
+            sensorSampleEpoch: this.sensorSampleEpoch,
             currentDoorState: available ? this.computeCurrentDoorState() : undefined,
             targetDoorState: available ? this.computeTargetDoorState() : undefined,
-            requestedTarget: this.requestedTarget,
+            desiredTarget: this.desiredTarget,
+            positionEstimate: this.position.kind,
             motionDirection: this.getMotionDirection(),
-            motionCertainty: this.getMotionCertainty(),
-            planKind: this.plan.kind,
-            idleNotClosedMode: this.idleNotClosedMode,
-            nextPulseDirection: this.idleNextPulseDirection,
+            operationKind: this.operation.kind,
+            closedAfterTravelTimeout: this.position.kind === 'closed'
+                && note.endsWith('-timeout-at-closed-sensor'),
             note,
         };
     }
     getMotionDirection() {
-        if (this.plan.kind === 'moving') {
-            return this.plan.direction;
+        if (this.position.kind === 'openingKnown') {
+            return 'opening';
         }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            return this.plan.finalDirection;
-        }
-        return 'none';
-    }
-    getMotionCertainty() {
-        if (this.plan.kind === 'moving') {
-            return this.plan.certainty;
-        }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            return 'known';
+        if (this.position.kind === 'closingKnown') {
+            return 'closing';
         }
         return 'none';
     }
     computeCurrentDoorState() {
-        if (this.plan.kind === 'moving') {
-            return this.plan.direction === 'closing' ? 3 /* DoorCurrentState.CLOSING */ : 2 /* DoorCurrentState.OPENING */;
-        }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            return this.plan.finalDirection === 'closing' ? 3 /* DoorCurrentState.CLOSING */ : 2 /* DoorCurrentState.OPENING */;
+        switch (this.position.kind) {
+            case 'closed':
+                return 1 /* DoorCurrentState.CLOSED */;
+            case 'openingKnown':
+                return 2 /* DoorCurrentState.OPENING */;
+            case 'closingKnown':
+                return 3 /* DoorCurrentState.CLOSING */;
+            case 'openAssumed':
+                return 0 /* DoorCurrentState.OPEN */;
+            case 'reversalPause':
+            case 'commandUncertain':
+            case 'notClosedUnknown':
+                return 4 /* DoorCurrentState.STOPPED */;
         }
-        return this.facts.closedSensor ? 1 /* DoorCurrentState.CLOSED */ : 0 /* DoorCurrentState.OPEN */;
     }
     computeTargetDoorState() {
-        if (this.requestedTarget) {
-            return this.requestedTarget === 'closed' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
+        if (this.desiredTarget) {
+            return this.desiredTarget === 'closed' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
         }
-        if (this.plan.kind === 'moving') {
-            return this.plan.direction === 'closing' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
+        if (this.position.kind === 'closed') {
+            return 1 /* DoorTargetState.CLOSED */;
         }
-        if (this.plan.kind === 'waitingSecondPulse') {
-            return this.plan.finalDirection === 'closing' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
+        if (this.position.kind === 'openingKnown' || this.position.kind === 'closingKnown') {
+            return targetForDirection(this.position.kind === 'openingKnown' ? 'opening' : 'closing') === 'closed'
+                ? 1 /* DoorTargetState.CLOSED */
+                : 0 /* DoorTargetState.OPEN */;
         }
-        return this.facts.closedSensor ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
+        return 0 /* DoorTargetState.OPEN */;
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    isAmbiguousPulseFailure(error) {
+        return (error instanceof FrontGateError && error.code === 'operation_timed_out')
+            || (error instanceof Error
+                && error.mqttPublishFailureKind === 'completion_unknown');
     }
 }
 exports.FrontGateFsm = FrontGateFsm;