@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-serial-turn-executor.d.ts

@@ -0,0 +1,54 @@
+import { ZLinkExecutionBarrier, ZLinkSpotSerialTurn } from '../execution';
+import type { SpotId } from '../../contracts';
+import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+export declare class ZLinkSpotSerialTurnExecutor {
+    private readonly yieldAllowed;
+    readonly sourceSpotId?: SpotId | undefined;
+    private readonly scheduler;
+    private depth;
+    private turnSequence;
+    private executionBarrier;
+    private resumedOwnerTurn;
+    private lastActivityAtMs;
+    activeTurnId: number;
+    constructor(yieldAllowed?: boolean, sourceSpotId?: SpotId | undefined, schedulerOptions?: ZLinkSerialSchedulerOptions);
+    get isExecuting(): boolean;
+    get isCurrentTurn(): boolean;
+    get hasPendingWork(): boolean;
+    get lastActivityAt(): number;
+    get currentTurn(): ZLinkSpotSerialTurn | undefined;
+    /** Stops new turns while allowing turns accepted before close to complete. */
+    close(): Promise<void>;
+    /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
+    isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean;
+    setExecutionBarrier(barrier: ZLinkExecutionBarrier): void;
+    /** Runs `operation` in serial order, one turn at a time. */
+    execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    /**
+     * Always enqueues `operation` as its own serial turn, even when called
+     * from within the currently active turn. Detached completion callbacks use
+     * this so they never run inline inside another callback's turn.
+     */
+    post<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    /**
+     * Queues a one-way turn in serial order. Handler completion is reported
+     * through `onError` and never blocks the sender turn.
+     */
+    postOneWay(operation: () => Promise<unknown> | unknown, onError: (error: unknown) => void, workOptions?: ZLinkSerialWorkOptions, admission?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Enqueues the framework-owned turn that completes a boundary while normal
+     * application admission remains sealed. Callers must release the matching
+     * barrier seal after this turn finishes.
+     */
+    postBarrierTurn<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    private enqueueApplicationTurn;
+    private enqueueFrameworkTurn;
+    private enqueueContinuationTurn;
+    private submitQueuedTurn;
+    private runQueuedRecord;
+    yieldPromise<T>(pending: Promise<T>): Promise<T>;
+    private runTurn;
+    private postResume;
+}

package/dist/runtime/spots/spot-serial-turn-executor.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotSerialTurnExecutor = void 0;
+const execution_1 = require("../execution");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const serial_execution_queue_1 = require("../execution/serial-execution-queue");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+class ZLinkSpotSerialTurnExecutor {
+    yieldAllowed;
+    sourceSpotId;
+    scheduler;
+    depth = 0;
+    turnSequence = 0;
+    executionBarrier;
+    resumedOwnerTurn;
+    lastActivityAtMs = performance.now();
+    activeTurnId = 0;
+    constructor(yieldAllowed = true, sourceSpotId, schedulerOptions) {
+        this.yieldAllowed = yieldAllowed;
+        this.sourceSpotId = sourceSpotId;
+        this.scheduler = new serial_execution_queue_1.ZLinkSerialExecutionQueue((record) => this.runQueuedRecord(record), {
+            ...schedulerOptions,
+            capacityError: schedulerOptions?.capacityError ?? (() => (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerQueueFull, 'Spot execution queue capacity was exceeded.'))
+        });
+    }
+    get isExecuting() {
+        return this.depth > 0;
+    }
+    get isCurrentTurn() {
+        return this.depth > 0 && (0, execution_1.isCurrentZLinkSpotSerialTurn)(this);
+    }
+    get hasPendingWork() {
+        return this.scheduler.hasPendingWork;
+    }
+    get lastActivityAt() {
+        return this.lastActivityAtMs;
+    }
+    get currentTurn() {
+        return (0, execution_1.captureZLinkSpotSerialTurn)(this);
+    }
+    /** Stops new turns while allowing turns accepted before close to complete. */
+    close() {
+        return this.scheduler.close();
+    }
+    /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
+    isActiveTurn(turn, turnId) {
+        return this.depth > 0
+            && (this.resumedOwnerTurn === turn
+                || (turnId === this.activeTurnId && !turn.isSuspended));
+    }
+    setExecutionBarrier(barrier) {
+        if (this.executionBarrier !== undefined
+            && this.executionBarrier !== barrier) {
+            throw new Error('ZLink Spot serial executor already belongs to another execution barrier.');
+        }
+        if (this.turnSequence !== 0 && this.executionBarrier === undefined) {
+            throw new Error('ZLink execution barrier must be attached before the first serial turn.');
+        }
+        this.executionBarrier = barrier;
+    }
+    /** Runs `operation` in serial order, one turn at a time. */
+    execute(operation, workOptions) {
+        if (this.isCurrentTurn) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'A Spot serial turn cannot implicitly execute another turn for the same owner.');
+        }
+        return this.enqueueApplicationTurn(operation, workOptions);
+    }
+    /**
+     * Always enqueues `operation` as its own serial turn, even when called
+     * from within the currently active turn. Detached completion callbacks use
+     * this so they never run inline inside another callback's turn.
+     */
+    post(operation, workOptions) {
+        return this.enqueueApplicationTurn(operation, workOptions);
+    }
+    /**
+     * Queues a one-way turn in serial order. Handler completion is reported
+     * through `onError` and never blocks the sender turn.
+     */
+    async postOneWay(operation, onError, workOptions = {}, admission = {}) {
+        this.lastActivityAtMs = performance.now();
+        let barrierClaim;
+        try {
+            barrierClaim = await this.executionBarrier?.enter();
+            if (admission.signal?.aborted === true) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            const options = {
+                ...workOptions,
+                lane: workOptions.lane ?? 'application'
+            };
+            const boundOperation = (0, application_job_queue_scope_1.bindApplicationJobPermit)(operation);
+            const submitted = (0, application_job_queue_scope_1.hasApplicationJobPermit)()
+                ? this.scheduler.submitPreAdmitted(boundOperation, options, barrierClaim)
+                : this.scheduler.submit(boundOperation, options, barrierClaim);
+            void submitted.catch(error => {
+                barrierClaim?.release();
+                onError(error);
+            });
+            // Let an empty owner queue begin its terminal handler turn before the
+            // ingress record is allowed to advance to the next owner.
+            await Promise.resolve();
+        }
+        catch (error) {
+            barrierClaim?.release();
+            throw error;
+        }
+    }
+    /**
+     * Enqueues the framework-owned turn that completes a boundary while normal
+     * application admission remains sealed. Callers must release the matching
+     * barrier seal after this turn finishes.
+     */
+    postBarrierTurn(operation, workOptions) {
+        return this.enqueueFrameworkTurn(operation, workOptions);
+    }
+    async enqueueApplicationTurn(operation, workOptions = {}) {
+        this.lastActivityAtMs = performance.now();
+        let barrierClaim;
+        try {
+            barrierClaim = await this.executionBarrier?.enter();
+            return await this.submitQueuedTurn(operation, workOptions, barrierClaim);
+        }
+        catch (error) {
+            barrierClaim?.release();
+            throw error;
+        }
+    }
+    async enqueueFrameworkTurn(operation, workOptions = {}) {
+        this.lastActivityAtMs = performance.now();
+        // Application admission crosses the async barrier boundary before it
+        // reaches the scheduler. Give an already-authorized framework turn that
+        // same boundary so it cannot overtake admitted application records.
+        await Promise.resolve();
+        return await this.submitQueuedTurn(operation, workOptions);
+    }
+    async enqueueContinuationTurn(operation) {
+        this.lastActivityAtMs = performance.now();
+        await Promise.resolve();
+        return await this.scheduler.submitContinuation(operation);
+    }
+    submitQueuedTurn(operation, workOptions, barrierClaim) {
+        const options = {
+            ...workOptions,
+            lane: workOptions.lane ?? 'application'
+        };
+        const boundOperation = (0, application_job_queue_scope_1.bindApplicationJobPermit)(operation);
+        return (0, application_job_queue_scope_1.hasApplicationJobPermit)()
+            ? this.scheduler.submitPreAdmitted(boundOperation, options, barrierClaim)
+            : this.scheduler.submit(boundOperation, options, barrierClaim);
+    }
+    runQueuedRecord(record) {
+        return this.runTurn(record.operation, (value) => record.resolve(value), (error) => record.reject(error), record.context, record.release);
+    }
+    yieldPromise(pending) {
+        const turn = this.currentTurn;
+        if (turn === undefined) {
+            throw new Error('yield requires a framework Spot handler turn.');
+        }
+        return turn.yieldPromise(pending);
+    }
+    runTurn(operation, resolve, reject, barrierClaim, release) {
+        const turn = new execution_1.ZLinkSpotSerialTurn((resumeTurn, resume, resumeReject) => this.postResume(resumeTurn, resume, resumeReject), barrierClaim, this.yieldAllowed);
+        const wrapped = async () => {
+            this.depth += 1;
+            this.lastActivityAtMs = performance.now();
+            this.turnSequence += 1;
+            const turnId = this.turnSequence;
+            this.activeTurnId = turnId;
+            try {
+                return await (0, execution_1.runZLinkSpotSerialTurn)(this, turnId, turn, operation);
+            }
+            finally {
+                this.depth -= 1;
+                this.activeTurnId = 0;
+            }
+        };
+        const owner = wrapped();
+        turn.bindOwner(owner);
+        owner.then(() => {
+            turn.releaseBoundExecutionClaim();
+            release?.();
+        }, () => {
+            turn.releaseBoundExecutionClaim();
+            release?.();
+        });
+        owner.then(resolve, reject);
+        return Promise.race([
+            owner.then(() => undefined, () => undefined),
+            turn.suspended
+        ]);
+    }
+    postResume(turn, resume, reject) {
+        const barrier = this.executionBarrier;
+        const resumeClaim = barrier?.tryEnter();
+        if (barrier !== undefined && resumeClaim === undefined) {
+            reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'The yielded Spot turn cannot resume after its execution unit was sealed.'));
+            return true;
+        }
+        turn.bindExecutionClaim(resumeClaim);
+        void this.enqueueContinuationTurn(async () => {
+            this.resumedOwnerTurn = turn;
+            try {
+                turn.resetSuspension();
+                resume();
+                await turn.resumeOwnerUntilNextYield();
+            }
+            finally {
+                if (this.resumedOwnerTurn === turn)
+                    this.resumedOwnerTurn = undefined;
+            }
+        }).catch((error) => {
+            turn.releaseBoundExecutionClaim();
+            reject(error);
+        });
+        return true;
+    }
+}
+exports.ZLinkSpotSerialTurnExecutor = ZLinkSpotSerialTurnExecutor;

package/dist/runtime/spots/spot-subscription-dispatch.d.ts

@@ -0,0 +1,32 @@
+import type { RoutingId, ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendSpot, ZLinkBackendTopicMessage } from '../backend/contracts';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+interface ZLinkSpotSubscriptionDispatchOptions {
+    readonly nativeSpot: ZLinkBackendSpot;
+    readonly createTopicMessage: () => ZLinkBackendTopicMessage;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly getTarget: () => ZLinkSpot;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly waitIdle: () => Promise<void>;
+}
+export declare class ZLinkSpotSubscriptionDispatch {
+    private readonly options;
+    private draining;
+    private redrainRequested;
+    private readonly handlers;
+    constructor(options: ZLinkSpotSubscriptionDispatchOptions);
+    private channelCodecs;
+    configure(registrations: readonly ZLinkSpotHandlerRegistration[]): void;
+    drain(): Promise<void>;
+    private redrainWasRequested;
+    dispatchRecord(topic: string, parts: readonly Message[], sourceRid: RoutingId | null): Promise<void>;
+    private drainAvailable;
+    private dispatch;
+}
+export {};

package/dist/runtime/spots/spot-subscription-dispatch.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotSubscriptionDispatch = void 0;
+const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const flow_context_1 = require("../diagnostics/flow-context");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const spot_native_flags_1 = require("./spot-native-flags");
+const serial_work_size_1 = require("../execution/serial-work-size");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+class ZLinkSpotSubscriptionDispatch {
+    options;
+    draining = false;
+    redrainRequested = false;
+    handlers = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    channelCodecs() {
+        return this.options.messageSerializers === undefined
+            ? undefined
+            : { serializers: this.options.messageSerializers };
+    }
+    configure(registrations) {
+        for (const registration of registrations) {
+            if (registration.kind !== 'subscribe'
+                || registration.channelName === undefined
+                || registration.topic === undefined) {
+                continue;
+            }
+            const key = subscriptionKey(registration.channelName, registration.topic);
+            const existing = this.handlers.get(key) ?? [];
+            if (existing.some((entry) => entry.handlerType === registration.handlerType)) {
+                continue;
+            }
+            existing.push(registration);
+            this.handlers.set(key, existing);
+            this.options.nativeSpot.setSubscription(registration.channelName, registration.topic);
+        }
+    }
+    async drain() {
+        if (this.draining) {
+            this.redrainRequested = true;
+            return;
+        }
+        this.draining = true;
+        try {
+            do {
+                this.redrainRequested = false;
+                await this.drainAvailable();
+            } while (this.redrainWasRequested());
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    redrainWasRequested() {
+        return this.redrainRequested;
+    }
+    async dispatchRecord(topic, parts, sourceRid) {
+        await this.dispatch({
+            topic,
+            parts,
+            routingId: sourceRid
+        });
+    }
+    async drainAvailable() {
+        let message = this.options.createTopicMessage();
+        try {
+            for (;;) {
+                if (!this.options.nativeSpot.subscribe(message, spot_native_flags_1.ZLINK_RECV_DONT_WAIT)) {
+                    message.close();
+                    await this.options.waitIdle();
+                    return;
+                }
+                try {
+                    await this.dispatch(message);
+                }
+                finally {
+                    message.close();
+                }
+                message = this.options.createTopicMessage();
+            }
+        }
+        finally {
+            message.close();
+        }
+    }
+    async dispatch(message) {
+        if (message.parts.length === 0) {
+            this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
+                messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+                action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                topic: message.topic,
+                sourceRid: message.routingId === null ? undefined : String(message.routingId)
+            });
+            return;
+        }
+        const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(message.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        if (envelope.header.kind !== 4 /* ZLinkChannelMessageKind.Publish */) {
+            this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
+                messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+                action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                packetName: envelope.packetName,
+                channelName: envelope.header.channelName,
+                topic: message.topic,
+                sourceRid: message.routingId === null ? undefined : String(message.routingId),
+                correlationId: envelope.header.correlationId ?? undefined
+            });
+            return;
+        }
+        const registrations = this.handlers.get(subscriptionKey(envelope.header.channelName, message.topic));
+        if (registrations === undefined || registrations.length === 0) {
+            this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
+                messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing,
+                action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                packetName: envelope.packetName,
+                channelName: envelope.header.channelName,
+                topic: message.topic,
+                sourceRid: message.routingId === null ? undefined : String(message.routingId),
+                correlationId: envelope.header.correlationId ?? undefined
+            });
+            return;
+        }
+        const spot = this.options.getTarget();
+        const subSource = message.routingId === null ? undefined : String(message.routingId);
+        const inboundFlow = (0, flow_context_1.createInboundFlow)(envelope.header.flowId, envelope.header.flowOrigin, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        try {
+            await this.options.serial.execute(() => (0, flow_context_1.runWithFlow)(inboundFlow, async () => {
+                // Payload deserialization belongs to the Spot serial turn. Queue
+                // admission and execution authority therefore precede this work.
+                const event = (0, channel_envelope_1.decodeChannelPayload)(envelope, this.channelCodecs());
+                for (const registration of registrations) {
+                    const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(spot, registration.handlerType, this.options.providerResolver);
+                    try {
+                        await handler.handle(spot, event, {
+                            channelName: envelope.header.channelName,
+                            contentType: envelope.header.contentType,
+                            packetName: envelope.packetName,
+                            topic: message.topic,
+                            source: subSource,
+                            metadata: (0, contracts_1.zlinkMessageMetadata)(envelope.header.metadata),
+                            correlationId: envelope.header.correlationId ?? undefined
+                        });
+                    }
+                    catch (error) {
+                        this.options.dispatchErrors?.report({
+                            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
+                            messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                            action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                            packetName: envelope.packetName,
+                            channelName: envelope.header.channelName,
+                            topic: message.topic,
+                            sourceRid: message.routingId === null ? undefined : String(message.routingId),
+                            correlationId: envelope.header.correlationId ?? undefined,
+                            error
+                        });
+                        throw error;
+                    }
+                }
+            }), (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, (0, serial_work_size_1.zlinkMetadataByteLength)(envelope.header.metadata)));
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ZLinkFrameworkException
+                && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed) {
+                this.options.dispatchErrors?.report({
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
+                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                    reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed,
+                    action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                    packetName: envelope.packetName,
+                    channelName: envelope.header.channelName,
+                    topic: message.topic,
+                    sourceRid: message.routingId === null ? undefined : String(message.routingId),
+                    correlationId: envelope.header.correlationId ?? undefined,
+                    error
+                });
+            }
+            throw error;
+        }
+    }
+}
+exports.ZLinkSpotSubscriptionDispatch = ZLinkSpotSubscriptionDispatch;
+function subscriptionKey(channelName, topic) {
+    return `${channelName}\u0000${topic}`;
+}

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

@@ -0,0 +1,110 @@
+import type { SpotId, Type, ZLinkEntrySpot, ZLinkSpot, ZLinkSpotTimerHandler, ZLinkTimer, ZLinkTimerOptions, ZLinkTimerTick } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import { ZLinkSpotEventKind } from '../diagnostics/internal-event-contracts';
+import type { ZLinkEntrySpotTimerHandlerRegistration, ZLinkSpotTimerHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
+import { ZLinkTimerOverrunPolicy } from '../../contracts';
+import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkExecutionBarrier } from '../execution';
+import type { OperationClock } from '../foundation/operation-registry';
+export interface ZLinkTimerClock extends OperationClock {
+    now(): number;
+    utcNow(): number;
+}
+type ZLinkTimerOwnerSpot = ZLinkSpot | ZLinkEntrySpot;
+type ZLinkTimerFailureReporter = (tick: ZLinkTimerTick, cause: unknown, event?: ZLinkSpotEventKind.TimerHandlerFailed | ZLinkSpotEventKind.TimerStoppedAfterUnhandledException) => Promise<void> | void;
+export interface ZLinkTimerRelocationState {
+    readonly name: string;
+    readonly handlerType: string;
+    readonly periodMs: number;
+    readonly overrunPolicy: ZLinkTimerOverrunPolicy;
+    readonly maxCatchUpTicks: number;
+    readonly stopOnUnhandledException: boolean;
+    readonly startedAtUnixMs: number;
+    readonly deliveryIndex: bigint;
+    readonly lastScheduledIndex: bigint;
+    readonly nextDueAtUnixMs: number;
+    readonly pendingTicks: readonly ZLinkTimerRelocationPendingTick[];
+}
+export interface ZLinkTimerRelocationPendingTick {
+    readonly deliveryIndex: bigint;
+    readonly scheduledIndex: bigint;
+    readonly scheduledAtUnixMs: number;
+    readonly skippedTicks: bigint;
+}
+export declare class ZLinkSpotTimerRegistry {
+    private readonly flowCreationEnabled;
+    private readonly executionSerialForTimer?;
+    private readonly executionAllowed;
+    private readonly executeTimer?;
+    private readonly isTimerExecuting?;
+    private readonly clock?;
+    private readonly lane;
+    private readonly timers;
+    private readonly generations;
+    private executionBarrier;
+    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>;
+    dispose(): Promise<void>;
+    captureRelocation(): Promise<readonly ZLinkTimerRelocationState[]>;
+    restoreRelocation(states: readonly ZLinkTimerRelocationState[]): void;
+    abortRelocation(states: readonly ZLinkTimerRelocationState[]): void;
+    commitRelocation(): Promise<void>;
+    cancel(name: string, generation: bigint, timer: ZLinkManagedTimer, signal?: AbortSignal): Promise<void>;
+    private prepareAddCore;
+    private completeAddCore;
+    private cancelCore;
+}
+export declare class ZLinkManagedTimer implements ZLinkTimer {
+    private readonly name;
+    private readonly periodMs;
+    private readonly options;
+    private readonly onTick;
+    private readonly onFailure?;
+    private readonly shouldWaitForRunningOnCancel;
+    private readonly clock;
+    private readonly lane;
+    private disposed;
+    private pausedForRelocation;
+    private startedAtMs;
+    private startedAtUnixMs;
+    private deliveryIndex;
+    private lastScheduledIndex;
+    private timeout;
+    private running;
+    constructor(name: string, periodMs: number, options: Required<ZLinkTimerOptions>, onTick: (tick: ZLinkTimerTick) => Promise<void>, onFailure?: ZLinkTimerFailureReporter | undefined, shouldWaitForRunningOnCancel?: () => boolean, clock?: ZLinkTimerClock);
+    get isDisposed(): boolean;
+    cancel(_signal?: AbortSignal): Promise<void>;
+    dispose(): Promise<void>;
+    captureRelocation(handlerType?: string): Promise<ZLinkTimerRelocationState>;
+    restoreRelocation(state: ZLinkTimerRelocationState, handlerType?: string): void;
+    private scheduleNext;
+    private fire;
+    private cancelCore;
+    private prepareCaptureCore;
+    private prepareFireCore;
+    private completeFireCore;
+    private selectScheduledIndex;
+    private elapsedMs;
+}
+export declare function createTimerDiagnostics(sourceName: string, spotId: SpotId, isEntrySpot: boolean, timerName: string, handlerType: Type, publisher: ZLinkRuntimeEventPublisher | undefined): ZLinkTimerFailureReporter | undefined;
+interface ZLinkEntrySpotTimerRegistrationSet {
+    readonly timerHandlers?: readonly ZLinkEntrySpotTimerHandlerRegistration[];
+}
+interface ZLinkUserSpotTimerRegistrationSet {
+    readonly timerHandlers?: readonly ZLinkSpotTimerHandlerRegistration[];
+}
+export declare function addEntrySpotTimerRegistrations(timers: ZLinkSpotTimerRegistry, entrySpotType: Type<ZLinkEntrySpot>, entrySpot: ZLinkEntrySpot, serial: ZLinkSpotSerialTurnExecutor, registrations: ZLinkEntrySpotTimerRegistrationSet, options: {
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly spotNodeName: string;
+    readonly spotId: SpotId;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+}): Promise<void>;
+export declare function addSpotTimerRegistrations(timers: ZLinkSpotTimerRegistry, spotType: Type<ZLinkSpot>, spotId: SpotId, spot: ZLinkSpot, serial: ZLinkSpotSerialTurnExecutor, registrations: ZLinkUserSpotTimerRegistrationSet, options: {
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly signal?: AbortSignal;
+}): Promise<void>;
+export {};