@zlink-systems/framework 0.30.1 → 0.30.2

package/dist/runtime/spots/spot-timer.d.ts

@@ -27,6 +27,12 @@ export interface ZLinkTimerRelocationState {
     readonly nextDueAtUnixMs: number;
     readonly pendingTicks: readonly ZLinkTimerRelocationPendingTick[];
 }
+export interface ZLinkManagedTimerStart {
+    /** Created paused; the owner starts it with `resume()`. */
+    readonly paused?: boolean;
+    /** Relocated logical schedule the timer continues from. */
+    readonly cursor?: ZLinkTimerRelocationState;
+}
 export interface ZLinkTimerRelocationPendingTick {
     readonly deliveryIndex: bigint;
     readonly scheduledIndex: bigint;
@@ -44,23 +50,58 @@ export declare class ZLinkSpotTimerRegistry {
     private readonly timers;
     private readonly generations;
     private executionBarrier;
+    /** Frozen from the source capture or the target restore until abort or Ready. */
+    private frozen;
+    /**
+     * The lifecycle owner opens this window around the target's Configure and
+     * pre-Ready OnInitialize only (Spot timer §1). A registration captures it at
+     * the call, so a registration started inside the window reattaches a
+     * restored key even when its asynchronous part finishes after the window.
+     */
+    private initializing;
+    /**
+     * Handler constructors the target Spot announced with `addTimer(...)` during
+     * Configure. Together with `handlers.addTimerHandler(...)` they form the
+     * table that resolves a restored timer's handler by name.
+     */
+    private readonly configureTimerHandlers;
+    private relocationHandlersResolved;
     constructor(_metrics?: import('../diagnostics').ZLinkRuntimeMetrics, flowCreationEnabled?: () => boolean, executionSerialForTimer?: ((name: string, fallback: ZLinkSpotSerialTurnExecutor) => ZLinkSpotSerialTurnExecutor) | undefined, executionAllowed?: () => boolean, executeTimer?: (<T>(name: string, operation: () => Promise<T> | T) => Promise<T>) | undefined, isTimerExecuting?: ((name: string) => boolean) | undefined, clock?: ZLinkTimerClock | undefined);
     setExecutionBarrier(barrier: ZLinkExecutionBarrier): void;
     get hasActiveTimers(): boolean;
     add<TSpot extends ZLinkTimerOwnerSpot, THandler extends ZLinkSpotTimerHandler<TSpot>>(name: string, periodMs: number, options: ZLinkTimerOptions | undefined, handlerType: Type<THandler>, serial: ZLinkSpotSerialTurnExecutor, spot: TSpot, providerResolver?: ZLinkProviderResolver, signal?: AbortSignal, reportFailure?: ZLinkTimerFailureReporter): Promise<ZLinkTimer>;
+    /**
+     * Stages the source payload on a fresh relocation target before Configure.
+     * The restored registrations keep their schedule and stay frozen until Ready.
+     */
+    stageRelocation(states: readonly ZLinkTimerRelocationState[]): void;
+    /** Runs one relocation-target initialization callback inside the reattach window. */
+    runRelocationInitialization<T>(operation: () => Promise<T> | T): Promise<T>;
+    /**
+     * After Configure, resolves every restored timer's handler constructor by
+     * name among the constructors the Spot announced in Configure: `addTimer(...)`
+     * there or `handlers.addTimerHandler(...)`. A restored key that Configure did
+     * not reattach is registered with the resolved constructor so it survives
+     * Ready without re-registration. No match or more than one match fails the
+     * target restore.
+     */
+    resolveRelocationHandlers(declared: readonly Type[], register: (name: string, periodMs: number, handlerType: Type) => Promise<unknown>): Promise<void>;
+    /** Ready: starts the restored and newly registered timers. */
+    publishRelocation(): Promise<void>;
     dispose(): Promise<void>;
     captureRelocation(): Promise<readonly ZLinkTimerRelocationState[]>;
-    restoreRelocation(states: readonly ZLinkTimerRelocationState[]): void;
-    abortRelocation(states: readonly ZLinkTimerRelocationState[]): void;
+    /** Source abort: the captured timers continue from their own unchanged cursor. */
+    abortRelocation(): void;
     commitRelocation(): Promise<void>;
     cancel(name: string, generation: bigint, timer: ZLinkManagedTimer, signal?: AbortSignal): Promise<void>;
+    private createTimer;
     private prepareAddCore;
     private completeAddCore;
     private cancelCore;
 }
 export declare class ZLinkManagedTimer implements ZLinkTimer {
     private readonly name;
-    private readonly periodMs;
+    readonly periodMs: number;
     private readonly options;
     private readonly onTick;
     private readonly onFailure?;
@@ -71,24 +112,35 @@ export declare class ZLinkManagedTimer implements ZLinkTimer {
     private pausedForRelocation;
     private startedAtMs;
     private startedAtUnixMs;
+    /** DeliveryIndex and ScheduledIndex of the last completed tick. */
     private deliveryIndex;
     private lastScheduledIndex;
+    /**
+     * The selected tick whose callback has not completed (Spot timer §1). It is
+     * the only pending tick a relocation captures, and a restored timer delivers
+     * it before it selects another tick.
+     */
+    private pendingScheduledIndex;
     private timeout;
+    /** The dispatch in flight, from its timer callback until `completeFireCore`. */
     private running;
     private dispatchFailure;
     private finalization;
-    constructor(name: string, periodMs: number, options: Required<ZLinkTimerOptions>, onTick: (tick: ZLinkTimerTick) => Promise<void>, onFailure?: ZLinkTimerFailureReporter | undefined, shouldWaitForRunningOnCancel?: () => boolean, clock?: ZLinkTimerClock);
+    constructor(name: string, periodMs: number, options: Required<ZLinkTimerOptions>, onTick: (tick: ZLinkTimerTick) => Promise<void>, onFailure?: ZLinkTimerFailureReporter | undefined, shouldWaitForRunningOnCancel?: () => boolean, clock?: ZLinkTimerClock, start?: ZLinkManagedTimerStart);
     get isDisposed(): boolean;
     cancel(_signal?: AbortSignal): Promise<void>;
     dispose(): Promise<void>;
     captureRelocation(handlerType?: string): Promise<ZLinkTimerRelocationState>;
-    restoreRelocation(state: ZLinkTimerRelocationState, handlerType?: string): void;
+    /** Starts a timer created paused, or continues one paused by a relocation capture. */
+    resume(): void;
     private scheduleNext;
     private fire;
     private cancelCore;
     private completeFinalization;
     private prepareCaptureCore;
     private prepareFireCore;
+    /** The tick info of the pending tick at `scheduledIndex` after the completed cursor. */
+    private pendingTick;
     private completeFireCore;
     private selectScheduledIndex;
     private elapsedMs;

package/dist/runtime/spots/spot-timer.js

@@ -8,11 +8,10 @@ const internal_event_contracts_1 = require("../diagnostics/internal-event-contra
 const contracts_1 = require("../../contracts");
 const TimerRegistrationValidator_1 = require("../../contracts/Configuration/TimerRegistrationValidator");
 const abort_1 = require("../abort");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
 const flow_context_1 = require("../diagnostics/flow-context");
 const state_lane_1 = require("../execution/state-lane");
-const node_async_hooks_1 = require("node:async_hooks");
-const detachedTimerStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:spot-timer');
 const systemTimerClock = {
     now: () => performance.now(),
     utcNow: () => Date.now(),
@@ -30,6 +29,22 @@ class ZLinkSpotTimerRegistry {
     timers = new Map();
     generations = new Map();
     executionBarrier;
+    /** Frozen from the source capture or the target restore until abort or Ready. */
+    frozen = false;
+    /**
+     * The lifecycle owner opens this window around the target's Configure and
+     * pre-Ready OnInitialize only (Spot timer §1). A registration captures it at
+     * the call, so a registration started inside the window reattaches a
+     * restored key even when its asynchronous part finishes after the window.
+     */
+    initializing = false;
+    /**
+     * Handler constructors the target Spot announced with `addTimer(...)` during
+     * Configure. Together with `handlers.addTimerHandler(...)` they form the
+     * table that resolves a restored timer's handler by name.
+     */
+    configureTimerHandlers = new Set();
+    relocationHandlersResolved = false;
     constructor(_metrics, flowCreationEnabled = () => true, executionSerialForTimer, executionAllowed = () => true, executeTimer, isTimerExecuting, clock) {
         this.flowCreationEnabled = flowCreationEnabled;
         this.executionSerialForTimer = executionSerialForTimer;
@@ -49,44 +64,135 @@ class ZLinkSpotTimerRegistry {
     }
     async add(name, periodMs, options, handlerType, serial, spot, providerResolver, signal, reportFailure) {
         (0, TimerRegistrationValidator_1.validateTimerRegistration)(name, periodMs, options);
+        const initializing = this.initializing;
+        if (initializing && !this.relocationHandlersResolved) {
+            this.configureTimerHandlers.add(handlerType);
+        }
         (0, abort_1.throwIfAborted)(signal);
         (0, handler_instance_scope_1.prepareHandlerInstance)(providerResolver, handlerType);
         const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(spot, handlerType, providerResolver);
-        const prepared = await this.lane.run(() => this.prepareAddCore(name));
-        if (prepared.previous !== undefined)
-            await prepared.previous.timer.cancel(signal);
         const executionSerial = this.executeTimer === undefined
             ? (this.executionSerialForTimer?.(name, serial) ?? serial)
             : undefined;
         if (this.executionBarrier !== undefined)
             executionSerial?.setExecutionBarrier(this.executionBarrier);
-        let callbackStarted = false;
-        const timer = startOutsideStateLane(() => new ZLinkManagedTimer(name, periodMs, normalizeTimerOptions(options), async (tick) => {
-            callbackStarted = false;
-            const timerFlow = (0, flow_context_1.createInboundFlow)(undefined, 'Timer', this.flowCreationEnabled(), undefined);
-            const operation = () => {
-                const current = this.timers.get(name);
-                if (current === undefined ||
-                    current.generation !== prepared.generation ||
-                    current.timer !== timer) {
-                    return undefined;
-                }
-                if (!this.executionAllowed())
-                    return undefined;
-                callbackStarted = true;
-                return (0, flow_context_1.runWithFlow)(timerFlow, () => handler.handle(spot, tick));
+        const binding = {
+            handler: handler,
+            spot,
+            executionSerial,
+            reportFailure
+        };
+        const prepared = await this.lane.run(() => this.prepareAddCore(name, handlerType.name, initializing, binding));
+        if (prepared.kind === 'reattached')
+            return prepared.handle;
+        if (prepared.previous !== undefined)
+            await prepared.previous.timer.cancel(signal);
+        const slot = { binding };
+        const timer = this.createTimer(name, prepared.generation, periodMs, options, slot);
+        const handle = new ZLinkRegisteredTimer(this, name, prepared.generation, timer);
+        const registered = await this.lane.run(() => this.completeAddCore(name, {
+            generation: prepared.generation,
+            handlerType: handlerType.name,
+            timer,
+            handle,
+            restored: false,
+            slot
+        }));
+        if (!registered)
+            await timer.cancel(signal);
+        return handle;
+    }
+    /**
+     * Stages the source payload on a fresh relocation target before Configure.
+     * The restored registrations keep their schedule and stay frozen until Ready.
+     */
+    stageRelocation(states) {
+        if (this.frozen || this.timers.size !== 0) {
+            throw new Error('Timer relocation can only be restored into a fresh registry.');
+        }
+        const restored = states.map((state) => {
+            if (states.some((other) => other !== state && other.name === state.name)) {
+                throw new Error(`Timer '${state.name}' appears twice in relocation state.`);
+            }
+            const options = {
+                overrunPolicy: state.overrunPolicy,
+                maxCatchUpTicks: state.maxCatchUpTicks,
+                stopOnUnhandledException: state.stopOnUnhandledException
             };
-            if (this.executeTimer !== undefined) {
-                await this.executeTimer(name, operation);
+            (0, TimerRegistrationValidator_1.validateTimerRegistration)(state.name, state.periodMs, options);
+            const slot = { binding: undefined };
+            const timer = this.createTimer(state.name, 1n, state.periodMs, options, slot, state);
+            return [
+                state.name,
+                {
+                    generation: 1n,
+                    handlerType: state.handlerType,
+                    timer,
+                    handle: new ZLinkRegisteredTimer(this, state.name, 1n, timer),
+                    restored: true,
+                    slot
+                }
+            ];
+        });
+        this.frozen = true;
+        for (const [name, entry] of restored) {
+            this.generations.set(name, entry.generation);
+            this.timers.set(name, entry);
+        }
+    }
+    /** Runs one relocation-target initialization callback inside the reattach window. */
+    async runRelocationInitialization(operation) {
+        if (!this.frozen || this.initializing) {
+            throw new Error('Timer relocation initialization is not active.');
+        }
+        this.initializing = true;
+        try {
+            return await operation();
+        }
+        finally {
+            this.initializing = false;
+        }
+    }
+    /**
+     * After Configure, resolves every restored timer's handler constructor by
+     * name among the constructors the Spot announced in Configure: `addTimer(...)`
+     * there or `handlers.addTimerHandler(...)`. A restored key that Configure did
+     * not reattach is registered with the resolved constructor so it survives
+     * Ready without re-registration. No match or more than one match fails the
+     * target restore.
+     */
+    async resolveRelocationHandlers(declared, register) {
+        if (!this.frozen || !this.initializing || this.relocationHandlersResolved) {
+            throw new Error('Timer relocation handler resolution is not active.');
+        }
+        this.relocationHandlersResolved = true;
+        const constructors = [...new Set([...declared, ...this.configureTimerHandlers])];
+        const restored = await this.lane.run(() => [...this.timers.entries()].filter(([, entry]) => entry.restored));
+        for (const [name, entry] of restored) {
+            const matches = constructors.filter((type) => type.name === entry.handlerType);
+            if (matches.length !== 1) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RelocationFailed, matches.length === 0
+                    ? `Timer '${name}' handler '${entry.handlerType}' is not declared. Register its timer with context.addTimer(...) in configure(), or declare it with context.handlers.addTimerHandler(Handler) in configure().`
+                    : `Timer '${name}' handler '${entry.handlerType}' is ambiguous: ${matches.length} declared constructors share the name.`);
             }
-            else {
-                await executionSerial.execute(operation);
+            if (entry.slot.binding === undefined) {
+                await register(name, entry.timer.periodMs, matches[0]);
             }
-        }, reportFailure, () => callbackStarted, this.clock));
-        const registered = await this.lane.run(() => this.completeAddCore(name, prepared.generation, handlerType.name, timer));
-        if (!registered)
-            await timer.cancel(signal);
-        return new ZLinkRegisteredTimer(this, name, prepared.generation, timer);
+        }
+    }
+    /** Ready: starts the restored and newly registered timers. */
+    async publishRelocation() {
+        await this.lane.run(() => {
+            for (const [name, entry] of this.timers) {
+                if (entry.slot.binding === undefined) {
+                    throw new Error(`Restored timer '${name}' has no resolved handler at Ready.`);
+                }
+            }
+            this.frozen = false;
+            for (const entry of this.timers.values()) {
+                (0, state_lane_1.startOutsideStateLane)(() => entry.timer.resume());
+            }
+        });
     }
     async dispose() {
         const timers = await this.lane.run(() => {
@@ -102,7 +208,10 @@ class ZLinkSpotTimerRegistry {
         await Promise.all(finalizations.filter((_, index) => timers[index].wait));
     }
     async captureRelocation() {
-        const timers = await this.lane.run(() => [...this.timers.entries()].sort(([left], [right]) => left.localeCompare(right)));
+        const timers = await this.lane.run(() => {
+            this.frozen = true;
+            return [...this.timers.entries()].sort(([left], [right]) => left.localeCompare(right));
+        });
         const states = [];
         for (const [name, entry] of timers) {
             const state = await entry.timer.captureRelocation(entry.handlerType);
@@ -112,21 +221,12 @@ class ZLinkSpotTimerRegistry {
         }
         return states;
     }
-    restoreRelocation(states) {
-        const byName = new Map(states.map((state) => [state.name, state]));
-        if (byName.size !== states.length || byName.size !== this.timers.size) {
-            throw new Error('Timer relocation inventory does not match registered handlers.');
+    /** Source abort: the captured timers continue from their own unchanged cursor. */
+    abortRelocation() {
+        this.frozen = false;
+        for (const entry of this.timers.values()) {
+            (0, state_lane_1.startOutsideStateLane)(() => entry.timer.resume());
         }
-        for (const [name, entry] of this.timers) {
-            const state = byName.get(name);
-            if (state === undefined) {
-                throw new Error(`Timer '${name}' is missing from relocation state.`);
-            }
-            entry.timer.restoreRelocation(state, entry.handlerType);
-        }
-    }
-    abortRelocation(states) {
-        this.restoreRelocation(states);
     }
     async commitRelocation() {
         await this.dispose();
@@ -136,17 +236,58 @@ class ZLinkSpotTimerRegistry {
         await this.lane.run(() => this.cancelCore(name, generation, timer));
         await timer.cancel(signal);
     }
-    prepareAddCore(name) {
+    createTimer(name, generation, periodMs, options, slot, cursor) {
+        let callbackStarted = false;
+        const timer = (0, state_lane_1.startOutsideStateLane)(() => new ZLinkManagedTimer(name, periodMs, normalizeTimerOptions(options), async (tick) => {
+            callbackStarted = false;
+            const binding = slot.binding;
+            if (binding === undefined)
+                return;
+            const timerFlow = (0, flow_context_1.createInboundFlow)(undefined, 'Timer', this.flowCreationEnabled(), undefined);
+            const operation = () => {
+                const current = this.timers.get(name);
+                if (current === undefined ||
+                    current.generation !== generation ||
+                    current.timer !== timer) {
+                    return undefined;
+                }
+                if (!this.executionAllowed())
+                    return undefined;
+                callbackStarted = true;
+                return (0, flow_context_1.runWithFlow)(timerFlow, () => binding.handler.handle(binding.spot, tick));
+            };
+            if (this.executeTimer !== undefined) {
+                await this.executeTimer(name, operation);
+            }
+            else {
+                await binding.executionSerial.execute(operation);
+            }
+        }, (tick, cause, event) => slot.binding?.reportFailure?.(tick, cause, event), () => callbackStarted, this.clock, { paused: true, cursor }));
+        return timer;
+    }
+    prepareAddCore(name, handlerType, initializing, binding) {
+        if (this.frozen && !initializing) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Timer '${name}' registration is sealed for relocation.`);
+        }
         const previous = this.timers.get(name);
+        if (initializing && previous?.restored === true) {
+            if (previous.handlerType !== handlerType) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Timer '${name}' was restored with handler '${previous.handlerType}', not '${handlerType}'.`);
+            }
+            previous.slot.binding = binding;
+            return { kind: 'reattached', handle: previous.handle };
+        }
         this.timers.delete(name);
         const generation = (this.generations.get(name) ?? 0n) + 1n;
         this.generations.set(name, generation);
-        return { previous, generation };
+        return { kind: 'registered', previous, generation };
     }
-    completeAddCore(name, generation, handlerType, timer) {
-        if (this.generations.get(name) !== generation)
+    completeAddCore(name, entry) {
+        if (this.generations.get(name) !== entry.generation)
             return false;
-        this.timers.set(name, { generation, handlerType, timer });
+        this.timers.set(name, entry);
+        if (!this.frozen)
+            (0, state_lane_1.startOutsideStateLane)(() => entry.timer.resume());
         return true;
     }
     cancelCore(name, generation, timer) {
@@ -201,13 +342,21 @@ class ZLinkManagedTimer {
     pausedForRelocation = false;
     startedAtMs;
     startedAtUnixMs;
+    /** DeliveryIndex and ScheduledIndex of the last completed tick. */
     deliveryIndex = 0n;
     lastScheduledIndex = 0n;
+    /**
+     * The selected tick whose callback has not completed (Spot timer §1). It is
+     * the only pending tick a relocation captures, and a restored timer delivers
+     * it before it selects another tick.
+     */
+    pendingScheduledIndex;
     timeout;
-    running = Promise.resolve();
+    /** The dispatch in flight, from its timer callback until `completeFireCore`. */
+    running;
     dispatchFailure;
     finalization;
-    constructor(name, periodMs, options, onTick, onFailure, shouldWaitForRunningOnCancel = () => true, clock = systemTimerClock) {
+    constructor(name, periodMs, options, onTick, onFailure, shouldWaitForRunningOnCancel = () => true, clock = systemTimerClock, start = {}) {
         this.name = name;
         this.periodMs = periodMs;
         this.options = options;
@@ -215,8 +364,20 @@ class ZLinkManagedTimer {
         this.onFailure = onFailure;
         this.shouldWaitForRunningOnCancel = shouldWaitForRunningOnCancel;
         this.clock = clock;
-        this.startedAtMs = clock.now();
-        this.startedAtUnixMs = clock.utcNow();
+        const cursor = start.cursor;
+        if (cursor === undefined) {
+            this.startedAtMs = clock.now();
+            this.startedAtUnixMs = clock.utcNow();
+        }
+        else {
+            validateRelocationCursor(name, periodMs, cursor);
+            this.startedAtUnixMs = cursor.startedAtUnixMs;
+            this.startedAtMs = clock.now() - Math.max(0, clock.utcNow() - cursor.startedAtUnixMs);
+            this.deliveryIndex = cursor.deliveryIndex;
+            this.lastScheduledIndex = cursor.lastScheduledIndex;
+            this.pendingScheduledIndex = cursor.pendingTicks[0]?.scheduledIndex;
+        }
+        this.pausedForRelocation = start.paused === true;
         this.scheduleNext();
     }
     get isDisposed() {
@@ -261,51 +422,34 @@ class ZLinkManagedTimer {
             deliveryIndex: this.deliveryIndex,
             lastScheduledIndex: this.lastScheduledIndex,
             nextDueAtUnixMs: this.startedAtUnixMs + Number(this.lastScheduledIndex + 1n) * this.periodMs,
-            pendingTicks: []
+            pendingTicks: this.pendingScheduledIndex === undefined
+                ? []
+                : [this.pendingTick(this.pendingScheduledIndex)]
         }));
     }
-    restoreRelocation(state, handlerType = '') {
-        if (this.disposed)
-            throw new Error(`Timer '${this.name}' is disposed.`);
-        if (state.name !== this.name ||
-            state.handlerType !== handlerType ||
-            state.periodMs !== this.periodMs ||
-            state.overrunPolicy !== this.options.overrunPolicy ||
-            state.maxCatchUpTicks !== this.options.maxCatchUpTicks ||
-            state.stopOnUnhandledException !== this.options.stopOnUnhandledException ||
-            !Number.isSafeInteger(state.startedAtUnixMs) ||
-            state.deliveryIndex < 0n ||
-            state.lastScheduledIndex < 0n ||
-            !Number.isSafeInteger(state.nextDueAtUnixMs) ||
-            state.nextDueAtUnixMs !==
-                state.startedAtUnixMs + Number(state.lastScheduledIndex + 1n) * state.periodMs ||
-            state.pendingTicks.length !== 0) {
-            throw new Error(`Timer '${this.name}' relocation contract does not match its registration.`);
-        }
-        if (this.timeout !== undefined)
-            this.clock.clearTimeout(this.timeout);
-        this.timeout = undefined;
-        this.startedAtUnixMs = state.startedAtUnixMs;
-        this.startedAtMs = this.clock.now() - Math.max(0, this.clock.utcNow() - state.startedAtUnixMs);
-        this.deliveryIndex = state.deliveryIndex;
-        this.lastScheduledIndex = state.lastScheduledIndex;
+    /** Starts a timer created paused, or continues one paused by a relocation capture. */
+    resume() {
+        if (this.disposed || !this.pausedForRelocation)
+            return;
         this.pausedForRelocation = false;
         this.scheduleNext();
     }
     scheduleNext() {
-        if (this.disposed || this.pausedForRelocation) {
+        // The dispatch in flight schedules the next tick when it completes.
+        if (this.disposed || this.pausedForRelocation || this.running !== undefined) {
             return;
         }
-        const delayMs = this.options.overrunPolicy === contracts_1.ZLinkTimerOverrunPolicy.DelayNextTick
-            ? this.periodMs
-            : Math.max(0, Number(this.lastScheduledIndex + 1n) * this.periodMs - this.elapsedMs());
-        this.timeout = this.clock.setTimeout(() => {
+        const delayMs = this.pendingScheduledIndex !== undefined
+            ? 0
+            : this.options.overrunPolicy === contracts_1.ZLinkTimerOverrunPolicy.DelayNextTick
+                ? this.periodMs
+                : Math.max(0, Number(this.lastScheduledIndex + 1n) * this.periodMs - this.elapsedMs());
+        this.timeout = (0, state_lane_1.startOutsideStateLane)(() => this.clock.setTimeout(() => {
             this.timeout = undefined;
-            const execution = startOutsideStateLane(() => this.fire());
-            this.running = execution.then(() => undefined, (cause) => this.lane.run(() => {
+            this.running = this.fire().then(() => undefined, (cause) => this.lane.run(() => {
                 this.dispatchFailure ??= { cause };
             }));
-        }, delayMs);
+        }, delayMs));
     }
     async fire() {
         const prepared = await this.lane.run(() => this.prepareFireCore());
@@ -316,12 +460,18 @@ class ZLinkManagedTimer {
             await this.onTick(prepared.tick);
         }
         catch (cause) {
+            // A tick whose callback had not started when a relocation captured it
+            // belongs to the capture: the target delivers it, so the source neither
+            // reports nor completes it.
+            const started = this.shouldWaitForRunningOnCancel();
+            if (!started && (await this.lane.run(() => this.pausedForRelocation)))
+                return;
             shouldContinue = !this.options.stopOnUnhandledException;
             await this.onFailure?.(prepared.tick, cause, shouldContinue
                 ? internal_event_contracts_1.ZLinkSpotEventKind.TimerHandlerFailed
                 : internal_event_contracts_1.ZLinkSpotEventKind.TimerStoppedAfterUnhandledException);
         }
-        await this.lane.run(() => this.completeFireCore(prepared.scheduledIndex, shouldContinue));
+        await this.lane.run(() => this.completeFireCore(shouldContinue));
     }
     cancelCore() {
         this.disposed = true;
@@ -329,7 +479,7 @@ class ZLinkManagedTimer {
         this.timeout = undefined;
         return {
             timeout,
-            running: this.shouldWaitForRunningOnCancel() ? this.running : Promise.resolve()
+            running: this.shouldWaitForRunningOnCancel() ? this.running : undefined
         };
     }
     async completeFinalization(start, finalization) {
@@ -369,34 +519,39 @@ class ZLinkManagedTimer {
             this.clock.clearTimeout(this.timeout);
             this.timeout = undefined;
         }
-        return { running: this.shouldWaitForRunningOnCancel() ? this.running : Promise.resolve() };
+        return { running: this.shouldWaitForRunningOnCancel() ? this.running : undefined };
     }
     prepareFireCore() {
         if (this.disposed)
             return undefined;
-        const scheduledIndex = this.selectScheduledIndex();
-        const skippedTicks = scheduledIndex - this.lastScheduledIndex - 1n;
+        this.pendingScheduledIndex ??= this.selectScheduledIndex();
+        const pending = this.pendingTick(this.pendingScheduledIndex);
         const startedElapsedMs = this.elapsedMs();
-        const scheduledElapsedMs = Number(scheduledIndex) * this.periodMs;
-        this.deliveryIndex += 1n;
+        const scheduledElapsedMs = Number(pending.scheduledIndex) * this.periodMs;
         return {
-            scheduledIndex,
             tick: {
                 name: this.name,
-                deliveryIndex: this.deliveryIndex,
-                scheduledIndex,
+                deliveryIndex: pending.deliveryIndex,
+                scheduledIndex: pending.scheduledIndex,
                 periodMs: this.periodMs,
-                scheduledAt: new Date(this.startedAtUnixMs + scheduledElapsedMs),
+                scheduledAt: new Date(pending.scheduledAtUnixMs),
                 startedAt: new Date(this.clock.utcNow()),
                 scheduledElapsedMs,
                 startedElapsedMs,
                 delayMs: startedElapsedMs - scheduledElapsedMs,
-                skippedTicks
+                skippedTicks: pending.skippedTicks
             }
         };
     }
-    completeFireCore(scheduledIndex, shouldContinue) {
-        this.lastScheduledIndex = scheduledIndex;
+    /** The tick info of the pending tick at `scheduledIndex` after the completed cursor. */
+    pendingTick(scheduledIndex) {
+        return relocationPendingTick(this.startedAtUnixMs, this.periodMs, this.deliveryIndex, this.lastScheduledIndex, scheduledIndex);
+    }
+    completeFireCore(shouldContinue) {
+        this.deliveryIndex += 1n;
+        this.lastScheduledIndex = this.pendingScheduledIndex;
+        this.pendingScheduledIndex = undefined;
+        this.running = undefined;
         if (!shouldContinue) {
             this.disposed = true;
             return;
@@ -428,8 +583,37 @@ class ZLinkManagedTimer {
     }
 }
 exports.ZLinkManagedTimer = ZLinkManagedTimer;
-function startOutsideStateLane(work) {
-    return detachedTimerStateLaneResource.runInAsyncScope(work);
+function validateRelocationCursor(name, periodMs, state) {
+    if (state.name !== name ||
+        state.periodMs !== periodMs ||
+        !Number.isSafeInteger(state.startedAtUnixMs) ||
+        state.deliveryIndex < 0n ||
+        state.lastScheduledIndex < 0n ||
+        !Number.isSafeInteger(state.nextDueAtUnixMs) ||
+        state.nextDueAtUnixMs !==
+            state.startedAtUnixMs + Number(state.lastScheduledIndex + 1n) * state.periodMs ||
+        state.pendingTicks.length > 1 ||
+        state.pendingTicks.some((pending) => {
+            const expected = relocationPendingTick(state.startedAtUnixMs, state.periodMs, state.deliveryIndex, state.lastScheduledIndex, pending.scheduledIndex);
+            return (pending.scheduledIndex <= state.lastScheduledIndex ||
+                pending.deliveryIndex !== expected.deliveryIndex ||
+                pending.scheduledAtUnixMs !== expected.scheduledAtUnixMs ||
+                pending.skippedTicks !== expected.skippedTicks);
+        })) {
+        throw new Error(`Timer '${name}' relocation state is invalid.`);
+    }
+}
+/**
+ * Spot timer §1: the tick info that follows the completed cursor. A timer holds
+ * at most one pending tick, so its DeliveryIndex is the next one.
+ */
+function relocationPendingTick(startedAtUnixMs, periodMs, deliveryIndex, lastScheduledIndex, scheduledIndex) {
+    return {
+        deliveryIndex: deliveryIndex + 1n,
+        scheduledIndex,
+        scheduledAtUnixMs: startedAtUnixMs + Number(scheduledIndex) * periodMs,
+        skippedTicks: scheduledIndex - lastScheduledIndex - 1n
+    };
 }
 function createTimerDiagnostics(sourceName, spotId, isEntrySpot, timerName, handlerType, publisher) {
     if (publisher === undefined) {