@marcel2215/homebridge-supla-plugin 2.1.32 → 2.1.33

package/dist/Accesories/FrontGateFsm.js

@@ -1,80 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FrontGateFsm = exports.FrontGateError = exports.DEFAULT_FRONT_GATE_CONFIG = void 0;
-exports.DEFAULT_FRONT_GATE_CONFIG = {
+exports.FrontGateFsm = exports.DEFAULT_FRONT_GATE_TIMINGS = void 0;
+exports.DEFAULT_FRONT_GATE_TIMINGS = {
     fullTravelMs: 25000,
     reversePauseMs: 3000,
+    wrongDirectionRunMs: 0,
     minimumPulseGapMs: 3000,
-    unknownOpenPolicy: 'reject',
-    unknownClosePolicy: 'reject',
-    seekClosedMaxPulses: 3,
-    assumeOpenAfterTravel: false,
+    closeRetryLimit: 0,
 };
-class FrontGateError extends Error {
-    constructor(code, message, options) {
-        super(message, options);
-        this.code = code;
-        this.name = 'FrontGateError';
-    }
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
 }
-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) {
+function clampInt(value, min, max) {
     if (!Number.isFinite(value)) {
-        return fallback;
+        return min;
     }
     return Math.min(max, Math.max(min, Math.round(value)));
 }
-function targetForDirection(direction) {
-    return direction === 'opening' ? 'open' : 'closed';
+function oppositeDirection(direction) {
+    return direction === 'opening' ? 'closing' : 'opening';
 }
 class FrontGateFsm {
-    constructor(io, config = exports.DEFAULT_FRONT_GATE_CONFIG, scheduler = SYSTEM_SCHEDULER) {
+    constructor(io, timings = exports.DEFAULT_FRONT_GATE_TIMINGS, _persisted = {}) {
         this.io = io;
         this.facts = {
-            transportConnected: false,
             controlConnected: null,
             sensorConnected: null,
             closedSensor: null,
         };
-        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.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.sequence = Promise.resolve(undefined);
         this.disposed = false;
-        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.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.emitSnapshot('fsm-initialized');
     }
     dispose() {
         this.disposed = true;
-        this.clearMovementTimer();
-        this.clearOperation();
+        this.clearTimers();
     }
-    handleTransportConnectedChange(connected) {
-        void this.enqueue(`transport-connected=${connected}`, () => {
-            this.applyTransportConnectedChange(connected);
-        });
+    handleConnectedChange(connected) {
+        this.handleControlConnectedChange(connected);
     }
     handleControlConnectedChange(connected) {
         void this.enqueue(`control-connected=${connected}`, () => {
@@ -86,26 +59,17 @@ class FrontGateFsm {
             this.applySensorConnectedChange(connected);
         });
     }
-    handleClosedSensorChange(closed, evidence = {}) {
+    handleClosedSensorChange(closed) {
         void this.enqueue(`closed-sensor=${closed}`, () => {
-            this.applyClosedSensorChange(closed, evidence);
+            this.applyClosedSensorChange(closed);
         });
     }
-    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);
         });
     }
-    requestHomeKitTarget(target) {
+    async requestHomeKitTarget(target) {
         return this.enqueue(`homekit-target=${target}`, async () => {
             await this.applyHomeKitTarget(target);
         });
@@ -113,17 +77,15 @@ 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) {
-                await task();
+            if (this.disposed) {
+                return;
             }
+            await task();
         });
         this.sequence = run.catch(error => {
             const message = error instanceof Error ? error.message : String(error);
@@ -131,31 +93,21 @@ 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.advanceObservationEpoch('control-channel-offline');
+            this.io.log.warn('front gate control channel went offline');
+            this.enterUnavailable('control-offline');
             return;
         }
         this.io.log.info('front gate control channel connected');
-        this.emitSnapshot('control-channel-online');
+        this.clearTimers();
+        this.plan = { kind: 'idle' };
+        this.sensorFreshSinceOnline = false;
+        this.emitSnapshot('control-online-awaiting-fresh-sensor');
     }
     applySensorConnectedChange(connected) {
         if (this.facts.sensorConnected === connected) {
@@ -163,586 +115,474 @@ class FrontGateFsm {
         }
         this.facts.sensorConnected = connected;
         if (!connected) {
-            this.advanceObservationEpoch('sensor-channel-offline');
+            this.io.log.warn('front gate sensor channel went offline');
+            this.enterUnavailable('sensor-offline');
             return;
         }
         this.io.log.info('front gate sensor channel connected');
-        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;
-        }
-        const hadSampleInEpoch = this.sensorSampleEpoch === this.observationEpoch;
-        const previous = hadSampleInEpoch ? this.previousSensorInEpoch : null;
+        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;
-        this.sensorSampleEpoch = this.observationEpoch;
-        this.previousSensorInEpoch = closed;
-        if (this.position.kind === 'commandUncertain') {
-            this.clearOperation();
-            if (closed) {
-                this.setPosition({ kind: 'closed' });
-            }
-            else {
-                this.desiredTarget = null;
-                this.setPosition({ kind: 'notClosedUnknown' });
-            }
-            this.emitSnapshot('command-uncertainty-cleared-by-fresh-sensor');
-            return;
+        if (this.facts.controlConnected === true && this.facts.sensorConnected === true) {
+            this.sensorFreshSinceOnline = true;
         }
-        if (!hadSampleInEpoch) {
-            this.clearOperation();
-            if (closed) {
-                this.setPosition({ kind: 'closed' });
-            }
-            else {
-                this.setPosition({ kind: 'notClosedUnknown' });
-            }
-            this.emitSnapshot('sensor-baseline-established');
-            return;
-        }
-        if (previous === closed) {
+        const becameFresh = !wasFresh && this.sensorFreshSinceOnline;
+        if (previous === closed && !becameFresh) {
             return;
         }
-        this.clearOperation();
         if (closed) {
             this.io.log.info('closed sensor is TRUE -> gate is fully closed');
-            this.setPosition({ kind: '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;
+            }
+            this.requestedTarget = null;
             this.emitSnapshot('closed-sensor-true');
             return;
         }
-        this.io.log.info('closed sensor changed TRUE -> FALSE in the current observation epoch');
-        this.setKnownMovement('opening');
-        this.emitSnapshot('closed-sensor-opening-edge');
+        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;
+            }
+            this.startOpeningMotion(this.requestedTarget === 'open' ? 'homekit' : 'external', 'closed-sensor-fell-from-true-to-false');
+            return;
+        }
+        if (this.plan.kind === 'idle' && this.requestedTarget === 'open') {
+            this.requestedTarget = null;
+        }
+        this.emitSnapshot('closed-sensor-false');
     }
     async applyHomeKitTarget(target) {
         if (!this.isAvailableForHomeKit()) {
-            throw new FrontGateError('unavailable', 'front gate controller is not available');
+            throw new Error('front gate controller is not available');
         }
-        if (this.operation.kind !== 'none') {
-            if (this.operation.target === target) {
-                this.desiredTarget = target;
-                this.emitSnapshot(`homekit-${target}-already-accepted`);
-                return;
-            }
-            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`;
+        this.requestedTarget = target;
+        if (target === 'open') {
+            await this.handleOpenRequest();
+            return;
         }
-        await this.executeScheduledPulse(operation, true);
-        return `${purpose.kind}-published`;
+        await this.handleCloseRequest();
     }
-    async executeScheduledPulse(operation, propagateError) {
-        if (!this.validateScheduledPulse(operation, !propagateError)) {
+    async handleOpenRequest() {
+        if (this.facts.closedSensor === true) {
+            if (this.plan.kind === 'moving' && this.plan.direction === 'opening') {
+                this.emitSnapshot('open-request-already-opening-from-closed');
+                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');
             return;
         }
-        try {
-            this.io.log.info(`motor pulse -> ${operation.purpose.kind}`);
-            await this.io.pulseMotor(operation.purpose.kind);
-            if (this.disposed || !this.hasCurrentOperation(operation.id)) {
+        if (this.plan.kind === 'moving') {
+            if (this.plan.direction === 'opening') {
+                this.emitSnapshot('open-request-already-opening');
                 return;
             }
-            this.lastPublishedPulseAt = this.scheduler.now();
-            this.applySuccessfulPulse(operation);
-            if (!propagateError) {
-                this.emitSnapshot(`${operation.purpose.kind}-published`);
+            if (this.plan.certainty === 'known') {
+                await this.reverseKnownMotion('opening', 'homekit-reverse-known-closing-to-open');
+                return;
             }
+            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;
         }
-        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 });
+        if (this.plan.kind === 'waitingSecondPulse') {
+            if (this.plan.finalDirection === 'opening') {
+                this.emitSnapshot('open-request-already-reversing-to-open');
+                return;
             }
+            // 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');
     }
-    applySuccessfulPulse(operation) {
-        switch (operation.purpose.kind) {
-            case 'startOpening':
-                this.clearOperation();
-                this.setKnownMovement('opening');
-                return;
-            case 'startClosing':
-                this.clearOperation();
-                this.setKnownMovement('closing');
-                return;
-            case 'bestEffortClose':
-                this.clearOperation();
-                this.setPosition({ kind: 'notClosedUnknown' });
-                return;
-            case 'stopOpeningAtClosed':
-                this.clearOperation();
-                this.setPosition({ kind: 'closed' });
+    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');
                 return;
-            case 'stopAndReverse':
-                this.startReversalPause(operation.purpose.finalDirection, operation.target);
+            }
+            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');
                 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) {
+            }
+            await this.reverseKnownMotion('closing', 'homekit-reverse-known-opening-to-close');
             return;
         }
-        const operation = this.operation;
-        if (!this.validateOperationContext(operation)) {
-            this.cancelInvalidOperation('scheduled-operation-guard-failed');
+        if (this.plan.kind === 'waitingSecondPulse') {
+            if (this.plan.finalDirection === 'closing') {
+                this.emitSnapshot('close-request-already-reversing-to-close');
+                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');
             return;
         }
-        if (operation.kind === 'scheduledPulse') {
-            await this.executeScheduledPulse(operation, false);
+        if (this.idleNotClosedMode === 'openKnown' || this.idleNextPulseDirection === 'closing') {
+            await this.startKnownCloseFromIdle('homekit-close-from-openish-known');
             return;
         }
-        if (operation.kind === 'reversalPause') {
-            await this.executeReversalPulse(operation);
+        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');
             return;
         }
-        await this.advanceSeekClosed(operation);
+        await this.startAmbiguousCloseAttempt('homekit-close-from-openish-ambiguous');
     }
-    async executeReversalPulse(operation) {
-        if (this.position.kind !== 'reversalPause') {
-            this.cancelInvalidOperation('reversal-position-changed');
+    async startOpeningFromClosed(reason) {
+        if (this.facts.closedSensor !== true) {
+            this.requestedTarget = null;
+            this.emitSnapshot(`${reason}-already-openish`);
             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.startOpeningMotion('homekit', `${reason}-pulse-sent`);
     }
-    async advanceSeekClosed(operation) {
+    async startOpeningFromStoppedState(reason) {
         if (this.facts.closedSensor === true) {
-            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.startOpeningFromClosed(`${reason}-closed-fallback`);
+            return;
         }
+        await this.pulseMotor(reason);
+        this.startOpeningMotion('homekit', `${reason}-pulse-sent`);
     }
-    validateScheduledPulse(operation, requireCommittedTarget) {
-        if (this.disposed || this.operation.kind !== 'scheduledPulse' || this.operation.id !== operation.id) {
-            return false;
-        }
-        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;
-                }
-                break;
-            case 'startClosing':
-            case 'bestEffortClose':
-            case 'stopAndReverse':
-            case 'seekClosed':
-                if (this.facts.closedSensor !== false) {
-                    this.cancelInvalidOperation('scheduled-pulse-not-closed-sensor-invalid');
-                    return false;
-                }
-                break;
+    async startKnownCloseFromIdle(reason) {
+        if (this.facts.closedSensor === true) {
+            this.requestedTarget = null;
+            this.emitSnapshot(`${reason}-already-closed`);
+            return;
         }
-        return true;
-    }
-    validateOperationContext(operation, requireCommittedTarget = true) {
-        return !this.disposed
-            && operation.epoch === this.observationEpoch
-            && this.isAvailableForHomeKit()
-            && (!requireCommittedTarget || this.desiredTarget === operation.target);
+        await this.pulseMotor(reason);
+        this.startClosingMotion('known', 'homekit', `${reason}-pulse-sent`);
     }
-    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' });
+    async startAmbiguousCloseAttempt(reason) {
+        if (this.facts.closedSensor === true) {
+            this.requestedTarget = null;
+            this.emitSnapshot(`${reason}-already-closed`);
+            return;
         }
+        await this.pulseMotor(reason);
+        this.startClosingMotion('goalOnly', 'homekit', `${reason}-pulse-sent`);
     }
-    cancelInvalidOperation(note) {
-        const operation = this.operation;
-        this.clearOperation();
-        if (operation.kind === 'reversalPause') {
-            this.setPosition({ kind: 'notClosedUnknown' });
+    async reverseKnownMotion(finalDirection, reason) {
+        if (this.plan.kind !== 'moving') {
+            return;
         }
-        this.io.log.warn(`front-gate scheduled operation cancelled: ${note}`);
+        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);
     }
-    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}`);
+    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);
     }
-    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 });
+    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;
+                }
+                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;
+                }
+                await this.handlePhaseTimer();
+            });
+        }, delayMs);
+    }
+    clearMovementTimer() {
+        if (this.movementTimer) {
+            clearTimeout(this.movementTimer);
+            this.movementTimer = undefined;
+        }
+        this.movementTimerToken += 1;
+    }
+    clearPhaseTimer() {
+        if (this.phaseTimer) {
+            clearTimeout(this.phaseTimer);
+            this.phaseTimer = undefined;
+        }
+        this.phaseTimerToken += 1;
     }
-    setPosition(position) {
+    clearTimers() {
         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;
+        this.clearPhaseTimer();
+    }
+    async handlePhaseTimer() {
+        if (this.plan.kind !== 'waitingSecondPulse') {
+            return;
         }
-        this.position = position;
-        const generation = ++this.positionGeneration;
-        if (position.kind !== 'openingKnown' && position.kind !== 'closingKnown') {
+        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}`);
             return;
         }
-        const epoch = position.epoch;
-        this.cancelMovementTimer = this.scheduler.schedule(() => {
-            void this.enqueue(`movement-timer-${generation}`, () => {
-                this.handleMovementTimeout(generation, epoch);
-            });
-        }, this.config.fullTravelMs);
+        this.startClosingMotion('known', this.plan.source, `second-pulse-fired-${finalDirection}`);
     }
-    handleMovementTimeout(generation, epoch) {
-        if (generation !== this.positionGeneration
-            || epoch !== this.observationEpoch
-            || (this.position.kind !== 'openingKnown' && this.position.kind !== 'closingKnown')) {
+    async handleMovementTimeout() {
+        if (this.plan.kind !== 'moving') {
             return;
         }
-        const direction = this.position.kind === 'openingKnown' ? 'opening' : 'closing';
-        this.clearOperation();
         if (this.facts.closedSensor === true) {
-            this.setPosition({ kind: 'closed' });
-            this.emitSnapshot(`${direction}-timeout-at-closed-sensor`);
+            this.clearTimers();
+            this.plan = { kind: 'idle' };
+            this.idleNextPulseDirection = 'opening';
+            this.requestedTarget = null;
+            this.emitSnapshot('movement-timeout-but-already-closed');
             return;
         }
-        if (direction === 'opening' && this.config.assumeOpenAfterTravel) {
-            this.setPosition({ kind: 'openAssumed' });
-            this.emitSnapshot('opening-timeout-open-assumed');
+        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');
             return;
         }
-        this.setPosition({ kind: 'notClosedUnknown' });
-        this.emitSnapshot(`${direction}-timeout-position-unknown`);
-    }
-    setOperation(operation) {
-        this.clearOperationTimer();
-        this.operation = operation;
-    }
-    clearOperation() {
-        this.clearOperationTimer();
-        this.operation = { kind: 'none' };
+        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');
     }
-    clearMovementTimer() {
-        if (this.cancelMovementTimer) {
-            this.cancelMovementTimer();
-            this.cancelMovementTimer = undefined;
+    applyObservedExternalPulse(reason) {
+        this.lastPulseLikeActivityAt = Date.now();
+        this.requestedTarget = null;
+        if (this.facts.closedSensor === true) {
+            this.startOpeningMotion('external', `external-pulse-observed-while-closed-${reason}`);
+            return;
         }
-    }
-    clearOperationTimer() {
-        if (this.cancelOperationTimer) {
-            this.cancelOperationTimer();
-            this.cancelOperationTimer = undefined;
+        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;
+        }
+        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);
     }
     isAvailableForHomeKit() {
-        return this.facts.transportConnected
-            && this.facts.controlConnected === true
+        return this.facts.controlConnected === true
             && this.facts.sensorConnected === true
-            && this.sensorSampleEpoch === this.observationEpoch
-            && this.facts.closedSensor !== null
-            && this.position.kind !== 'commandUncertain';
+            && 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();
     }
     emitSnapshot(note) {
-        if (!this.disposed) {
-            this.io.publishSnapshot(this.buildSnapshot(note));
+        if (this.disposed) {
+            return;
         }
+        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,
-            observationEpoch: this.observationEpoch,
-            sensorSampleEpoch: this.sensorSampleEpoch,
+            sensorFreshSinceOnline: this.sensorFreshSinceOnline,
             currentDoorState: available ? this.computeCurrentDoorState() : undefined,
             targetDoorState: available ? this.computeTargetDoorState() : undefined,
-            desiredTarget: this.desiredTarget,
-            positionEstimate: this.position.kind,
+            requestedTarget: this.requestedTarget,
             motionDirection: this.getMotionDirection(),
-            operationKind: this.operation.kind,
-            closedAfterTravelTimeout: this.position.kind === 'closed'
-                && note.endsWith('-timeout-at-closed-sensor'),
+            motionCertainty: this.getMotionCertainty(),
+            planKind: this.plan.kind,
+            idleNotClosedMode: this.idleNotClosedMode,
+            nextPulseDirection: this.idleNextPulseDirection,
             note,
         };
     }
     getMotionDirection() {
-        if (this.position.kind === 'openingKnown') {
-            return 'opening';
+        if (this.plan.kind === 'moving') {
+            return this.plan.direction;
         }
-        if (this.position.kind === 'closingKnown') {
-            return 'closing';
+        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';
         }
         return 'none';
     }
     computeCurrentDoorState() {
-        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 */;
+        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 */;
         }
+        return this.facts.closedSensor ? 1 /* DoorCurrentState.CLOSED */ : 0 /* DoorCurrentState.OPEN */;
     }
     computeTargetDoorState() {
-        if (this.desiredTarget) {
-            return this.desiredTarget === 'closed' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
+        if (this.requestedTarget) {
+            return this.requestedTarget === 'closed' ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
         }
-        if (this.position.kind === 'closed') {
-            return 1 /* DoorTargetState.CLOSED */;
+        if (this.plan.kind === 'moving') {
+            return this.plan.direction === '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 */;
+        if (this.plan.kind === 'waitingSecondPulse') {
+            return this.plan.finalDirection === 'closing' ? 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');
+        return this.facts.closedSensor ? 1 /* DoorTargetState.CLOSED */ : 0 /* DoorTargetState.OPEN */;
     }
 }
 exports.FrontGateFsm = FrontGateFsm;