@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -21,6 +21,7 @@ class ZLinkSpotSerialExecutor {
     executionBarrier;
     closing = false;
     closePromise;
+    preparation;
     constructor(spotSerial, executionMode, sourceSpotId, actorOptions) {
         this.spotSerial = spotSerial;
         this.executionMode = executionMode;
@@ -38,6 +39,49 @@ class ZLinkSpotSerialExecutor {
         for (const serial of this.timerSerials.values())
             serial.setExecutionBarrier(barrier);
     }
+    get isPreparing() {
+        return this.preparation !== undefined;
+    }
+    beginPreparation(kind = 'activation') {
+        if (this.preparation !== undefined || this.executionBarrier === undefined)
+            throw new Error('Activation preparation requires one unowned execution barrier.');
+        const barrier = this.executionBarrier;
+        const seal = barrier.seal(kind);
+        let complete;
+        const terminal = new Promise((resolve) => {
+            complete = resolve;
+        });
+        // The staging seal itself owns target preparation. No normal preparation
+        // item is admitted in addition to this lifecycle owner.
+        const execution = this.spotSerial.executeControlLifecycleOperation(async () => {
+            const finish = await terminal;
+            await finish?.();
+        }, {
+            canExecuteApplication: (record) => record.context === undefined || !barrier.isCurrent(seal)
+        });
+        this.preparation = { seal, complete, execution };
+    }
+    openPreparationAdmission() {
+        if (this.preparation !== undefined)
+            this.executionBarrier.abort(this.preparation.seal);
+    }
+    async finishPreparation(terminal) {
+        const preparation = this.preparation;
+        if (preparation === undefined) {
+            await terminal?.();
+            return;
+        }
+        preparation.complete(terminal);
+        try {
+            await preparation.execution;
+        }
+        finally {
+            if (this.preparation === preparation) {
+                this.executionBarrier.abort(preparation.seal);
+                this.preparation = undefined;
+            }
+        }
+    }
     executeSpot(operation, workOptions) {
         return this.spotSerial.execute(operation, workOptions);
     }
@@ -45,17 +89,26 @@ class ZLinkSpotSerialExecutor {
         const serial = this.actorSerial(actorId);
         return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
     }
-    /** @internal Restores a durable Actor FIFO prefix without starting it. */
-    admitActorDurablePrefix(actorId, records) {
+    executeTimer(timerName, operation, workOptions) {
+        return this.timerSerial(timerName).post(operation, workOptions);
+    }
+    /** Admits held packets through the same Actor FIFO as ordinary ingress. */
+    admitActorPacketPrefix(actorId, records, dispatch) {
         const serial = this.actorSerial(actorId);
-        return this.actorExecutor(actorId).admitDurablePrefix(records.map((record) => ({
-            operation: (executeChild) => record.operation((child) => executeChild(() => child(serial))),
+        const terminals = this.actorExecutor(actorId).admitDurablePrefix(records.map((record) => ({
+            operation: (executeChild) => record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => executeChild(() => dispatch(serial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef))),
             preparation: record.preparation,
-            workOptions: record.workOptions
+            workOptions: { payloadBytes: record.payloadBytes, onWithdrawable: record.onWithdrawable }
         })));
-    }
-    executeTimer(timerName, operation, workOptions) {
-        return this.timerSerial(timerName).execute(operation, workOptions);
+        const terminal = Promise.allSettled(terminals).then((outcomes) => {
+            const errors = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1) {
+                throw new AggregateError(errors, `Actor '${actorId}' durable prefix replay failed.`);
+            }
+        });
+        return { terminal };
     }
     isTimerExecuting(timerName) {
         if (this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide) {

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

@@ -94,7 +94,7 @@ class ZLinkSpotSerialTurnExecutor {
      * this so they never run inline inside another callback's turn.
      */
     post(operation, workOptions) {
-        return this.enqueueApplicationTurn(operation, workOptions);
+        return this.enqueueApplicationTurn(operation, workOptions, undefined, true);
     }
     /**
      * Queues a one-way turn in serial order. Handler completion is reported
@@ -181,11 +181,22 @@ class ZLinkSpotSerialTurnExecutor {
     visitPendingApplication(visitor) {
         this.scheduler.visitPendingApplication(visitor);
     }
-    async enqueueApplicationTurn(operation, workOptions = {}, replay) {
+    async enqueueApplicationTurn(operation, workOptions = {}, replay, retainWhilePreparing = false) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
             const entry = this.executionBarrier?.enter();
+            if (entry instanceof Promise &&
+                retainWhilePreparing &&
+                this.scheduler.retainsApplicationForLifecycle) {
+                try {
+                    return await this.submitQueuedTurn(operation, workOptions, entry);
+                }
+                catch (error) {
+                    (await entry).release();
+                    throw error;
+                }
+            }
             barrierClaim = entry instanceof Promise ? await entry : entry;
             const refusal = this.applicationAdmissionRefusal(replay !== undefined);
             if (refusal !== undefined)
@@ -224,6 +235,12 @@ class ZLinkSpotSerialTurnExecutor {
             : this.scheduler.submit(boundOperation, options, barrierClaim);
     }
     runQueuedRecord(record) {
+        if (record.context instanceof Promise) {
+            return record.context.then((claim) => {
+                Object.assign(record, { context: claim });
+                return this.runQueuedRecord(record);
+            });
+        }
         const context = record.context;
         if (context?.replay !== undefined && record.operation === context.replay) {
             context.release();

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

@@ -31,9 +31,6 @@ class ZLinkSpotSubscriptionDispatch {
             }
             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);
@@ -133,7 +130,7 @@ class ZLinkSpotSubscriptionDispatch {
         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, undefined);
         try {
-            await this.options.serial.execute(() => (0, flow_context_1.runWithFlow)(inboundFlow, async () => {
+            await this.options.serial.post(() => (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());

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;