@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -14,6 +14,7 @@ class ZLinkSpotSerialTurnExecutor {
     executionBarrier;
     resumedOwnerTurn;
     lastActivityAtMs = performance.now();
+    lifecycleAdmissionClosed = false;
     activeTurnId = 0;
     constructor(yieldAllowed = true, sourceSpotId, schedulerOptions) {
         this.yieldAllowed = yieldAllowed;
@@ -35,9 +36,31 @@ class ZLinkSpotSerialTurnExecutor {
     get currentTurn() {
         return (0, execution_1.captureZLinkSpotSerialTurn)(this);
     }
-    /** Stops new turns while allowing turns accepted before close to complete. */
-    close() {
-        return this.scheduler.close();
+    /** Waits for turns admitted through the execution barrier to complete. */
+    whenIdle() {
+        return this.scheduler.whenIdle();
+    }
+    closeAdmission() {
+        this.scheduler.closeAdmission();
+    }
+    /**
+     * Spot messaging §7 step 3: after Close ends this queue's admission, an Instance
+     * intent message is refused before admission as a released owner fence, and any
+     * other message finds no incarnation. Undefined while admission is open.
+     */
+    applicationAdmissionRefusal(instanceIntent) {
+        if (!this.scheduler.admissionClosed)
+            return undefined;
+        return instanceIntent
+            ? (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'The Spot incarnation released its authority before admitting this Instance intent message.')
+            : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, 'The Spot incarnation is closed.');
+    }
+    /**
+     * Spot messaging §7: once Close commits Closing, membership work can no longer
+     * enter this incarnation while Instance intent messages still queue behind Close.
+     */
+    setLifecycleAdmissionClosed(closed) {
+        this.lifecycleAdmissionClosed = closed;
     }
     /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
     isActiveTurn(turn, turnId) {
@@ -54,11 +77,11 @@ class ZLinkSpotSerialTurnExecutor {
         this.executionBarrier = barrier;
     }
     /** Runs `operation` in serial order, one turn at a time. */
-    execute(operation, workOptions) {
+    execute(operation, workOptions, replay) {
         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);
+        return this.enqueueApplicationTurn(operation, workOptions, replay);
     }
     /**
      * Always enqueues `operation` as its own serial turn, even when called
@@ -72,11 +95,18 @@ class ZLinkSpotSerialTurnExecutor {
      * 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 = {}) {
+    async postOneWay(operation, onError, workOptions = {}, admission = {}, replay) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
-            barrierClaim = await this.executionBarrier?.enter();
+            const entry = this.executionBarrier?.enter();
+            barrierClaim = entry instanceof Promise ? await entry : entry;
+            const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+            if (refusal !== undefined)
+                throw refusal;
+            if (barrierClaim !== undefined && replay !== undefined) {
+                Object.assign(barrierClaim, { replay: (0, application_job_queue_scope_1.bindApplicationJobPermit)(replay) });
+            }
             if (admission.signal?.aborted === true) {
                 throw new DOMException('The operation was aborted.', 'AbortError');
             }
@@ -109,11 +139,55 @@ class ZLinkSpotSerialTurnExecutor {
     postBarrierTurn(operation, workOptions) {
         return this.enqueueFrameworkTurn(operation, workOptions);
     }
-    async enqueueApplicationTurn(operation, workOptions = {}) {
+    /** Admits membership work and holds the lifecycle FIFO until its result settles. */
+    executeLifecycleOperation(operation) {
+        let entry;
+        try {
+            if (this.lifecycleAdmissionClosed) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'Spot lifecycle admission is closed by a committed Close.');
+            }
+            entry = this.executionBarrier?.enter();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const submit = (claim) => {
+            try {
+                return this.scheduler.submitLifecycleOperation(operation);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            finally {
+                claim?.release();
+            }
+        };
+        return entry instanceof Promise ? entry.then(submit) : submit(entry);
+    }
+    /** Runs owner control work that establishes or completes its own admission seal. */
+    executeControlLifecycleOperation(operation, context) {
+        try {
+            return this.scheduler.submitLifecycleOperation(operation, context);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    visitPendingApplication(visitor) {
+        this.scheduler.visitPendingApplication(visitor);
+    }
+    async enqueueApplicationTurn(operation, workOptions = {}, replay) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
-            barrierClaim = await this.executionBarrier?.enter();
+            const entry = this.executionBarrier?.enter();
+            barrierClaim = entry instanceof Promise ? await entry : entry;
+            const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+            if (refusal !== undefined)
+                throw refusal;
+            if (barrierClaim !== undefined && replay !== undefined) {
+                Object.assign(barrierClaim, { replay: (0, application_job_queue_scope_1.bindApplicationJobPermit)(replay) });
+            }
             return await this.submitQueuedTurn(operation, workOptions, barrierClaim);
         }
         catch (error) {
@@ -145,6 +219,11 @@ class ZLinkSpotSerialTurnExecutor {
             : this.scheduler.submit(boundOperation, options, barrierClaim);
     }
     runQueuedRecord(record) {
+        const context = record.context;
+        if (context?.replay !== undefined && record.operation === context.replay) {
+            context.release();
+            return Promise.resolve(this.executionBarrier?.enter()).then((claim) => this.runTurn(record.operation, (value) => record.resolve(value), (error) => record.reject(error), claim, record.release));
+        }
         return this.runTurn(record.operation, (value) => record.resolve(value), (error) => record.reject(error), record.context, record.release);
     }
     yieldPromise(pending) {
@@ -186,13 +265,10 @@ class ZLinkSpotSerialTurnExecutor {
         ]);
     }
     postResume(turn, resume, reject) {
-        const barrier = this.executionBarrier;
-        const resumeClaim = barrier?.tryEnter();
-        if (barrier !== undefined && resumeClaim === undefined) {
+        if (!turn.resumeExecutionClaim()) {
             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 {

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

@@ -6,10 +6,11 @@ import type { ZLinkEntrySpotTimerHandlerRegistration, ZLinkSpotTimerHandlerRegis
 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 {
+export interface ZLinkTimerClock {
     now(): number;
     utcNow(): number;
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
 }
 type ZLinkTimerOwnerSpot = ZLinkSpot | ZLinkEntrySpot;
 type ZLinkTimerFailureReporter = (tick: ZLinkTimerTick, cause: unknown, event?: ZLinkSpotEventKind.TimerHandlerFailed | ZLinkSpotEventKind.TimerStoppedAfterUnhandledException) => Promise<void> | void;

package/dist/runtime/streams/actor-session-binding-registry.d.ts

@@ -1,6 +1,10 @@
-import type { ServiceSessionBindingAdmissionClaim, ServiceSessionBindingAdmissionResult } from '../foundation/service-session-binding-ingress-port';
+export declare const DEFAULT_TERMINAL_RELOCATION_CAPACITY = 4096;
 export interface ZLinkActorSessionBindingActor {
     readonly actorId: string;
+    readonly ref: {
+        readonly actorId: string;
+        readonly bindingGeneration?: bigint;
+    };
 }
 export interface ZLinkActorSessionBindingContext<TActor extends ZLinkActorSessionBindingActor> {
     readonly routingId?: unknown;
@@ -30,18 +34,6 @@ export interface ZLinkActorSessionRelocationClaim {
     readonly actorNodeGeneration?: bigint;
     readonly sealId: string;
 }
-export interface ZLinkActorSessionRetainedOutbound {
-    deliver(): Promise<boolean>;
-    fail(error: unknown): void;
-}
-export interface ZLinkActorSessionAcceptedProducerProof {
-    readonly actorId: string;
-    readonly objectGeneration: bigint;
-    readonly actorNodeRid: string;
-    readonly actorNodeGeneration: bigint;
-    readonly sessionIdentity: string;
-    readonly bindingGeneration: bigint;
-}
 export interface ZLinkActorSessionRelocationSnapshot extends ZLinkActorSessionRelocationClaim {
     readonly phase: 'sealed' | 'applying' | 'applied' | 'terminal';
     readonly applyFingerprint?: string;
@@ -79,7 +71,6 @@ export declare enum ZLinkActorSessionBindingTermination {
 }
 export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActorSessionBindingContext<TActor>, TActor extends ZLinkActorSessionBindingActor> {
     private readonly terminalRelocationCapacity;
-    private readonly outboundCapacity;
     private readonly sealWaitTimeoutMs;
     private readonly errorSink?;
     private readonly lane;
@@ -89,7 +80,7 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     private readonly activeFrameWaiters;
     private readonly relocations;
     private readonly terminalRelocations;
-    constructor(terminalRelocationCapacity?: number, outboundCapacity?: number, sealWaitTimeoutMs?: number, errorSink?: (() => {
+    constructor(terminalRelocationCapacity?: number, sealWaitTimeoutMs?: number, errorSink?: (() => {
         reportRuntimeTaskException(taskName: string, error: unknown): void;
     } | undefined) | undefined);
     bind(context: TContext, actor: TActor, bindingToken: string, authorityFence?: ZLinkActorSessionAuthorityFence, sessionIdentity?: string, commitActor?: () => void): Promise<void>;
@@ -101,12 +92,15 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     find(actorId: string): Promise<TActor | undefined>;
     private findCore;
     route(actorId: string): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined>;
+    /** Selects the route only when it is the exact Session binding (§8.1 validation values). */
+    routeForSessionBinding(actorId: string, sessionRid: string, bindingGeneration?: bigint): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined>;
     private routeCore;
     capturePendingReplyClaim(actorId: string, actor: ZLinkActorSessionBindingActor, bindingToken: string): Promise<{
         readonly context: TContext;
     } | undefined>;
     private capturePendingReplyClaimCore;
     unbind(actorId: string, context: TContext, bindingToken: string, termination?: ZLinkActorSessionBindingTermination): Promise<void>;
+    /** Fixes the unbind order in the lane; the caller awaits transport completion outside it. */
     private unbindCore;
     unbindActor(actorId: string): Promise<void>;
     private unbindActorCore;
@@ -118,6 +112,10 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     private requireCurrentTokenCore;
     accept(actorId: string, bindingToken: string): Promise<void>;
     private acceptCore;
+    acceptOneWay(actorId: string, bindingToken: string, prepare: () => {
+        readonly deliver: () => Promise<void>;
+        readonly drop: (reason: 'stale_target' | 'target_closed' | 'shutdown', error?: unknown) => void;
+    }): Promise<boolean>;
     /**
      * Holds Session ingress accepted after a relocation seal until the target
      * route is published and the seal is released. The caller keeps the
@@ -137,23 +135,15 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     private prepareRelocationSeal;
     relocationSnapshot(actorId: string, sealId: string): Promise<ZLinkActorSessionRelocationSnapshot | undefined>;
     private relocationSnapshotCore;
-    retainRelocationOutbound(actorId: string, operation: ZLinkActorSessionRetainedOutbound, sealId?: string): Promise<ServiceSessionBindingAdmissionResult>;
-    private retainRelocationOutboundCorePublic;
-    admitRelocationOutbound(claim: ServiceSessionBindingAdmissionClaim, operation: ZLinkActorSessionRetainedOutbound): Promise<ServiceSessionBindingAdmissionResult>;
-    private admitRelocationOutboundCore;
-    private retainRelocationOutboundCore;
-    discardRelocationOutbound(actorId: string, sealId: string, error: unknown): Promise<void>;
-    private discardRelocationOutboundCore;
-    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, action: 'commit' | 'abort', commitOwnerTransition: () => Promise<void>, acceptedProducerProof?: ZLinkActorSessionAcceptedProducerProof): Promise<void>;
+    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, commitOwnerTransition: () => Promise<void>): Promise<void>;
     private prepareRelocationApply;
     private completeRelocationApply;
     private failRelocationApply;
-    private currentProducerProof;
     observeRelocationTerminal(actorId: string, sealId: string, applyFingerprint: string): Promise<void>;
     private observeRelocationTerminalCore;
     /**
      * Actor-wide relocation teardown: every seal (active and terminal-retained)
-     * and every held outbound entry for `actorId` is discarded unconditionally.
+     * for `actorId` is discarded unconditionally.
      * Reserved for paths where the Actor itself is gone or being torn down
      * (destroy, ownership clear, relocation-seal expiry/failure) — never for a
      * single physical route's disconnect, which must not disturb a relocation
@@ -165,7 +155,7 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
      * Spec 48 §137: a relocation seal's lifecycle is independent of any single
      * physical route's binding. Unbinding one physical route (a disconnect)
      * must retire only the still-open (nonterminal) relocation seal that this
-     * exact route's Session owns, and the outbound held against that seal — it
+     * exact route's Session owns — it
      * must never reach into a seal that has already reached 'terminal' (its
      * bounded retention exists precisely so a late same-seal relay can still
      * pass on a successor route) nor into a different Session's active seal
@@ -188,16 +178,11 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     private waitForActiveFramesCore;
     private resolveActiveFrameWaiters;
     private rejectActiveFrameWaiters;
-    private startOutboundDrain;
-    private reserveOutbound;
-    private settleOutbound;
-    private failOutbound;
-    private outboundAdmissionError;
-    private matchesCurrentProducerNode;
     private rememberTerminalRelocation;
     private deleteEmptyRelocationQueue;
     private resolveSealWaiters;
     private rejectSealWaiters;
+    private startHeldOneWayDrain;
 }
 export interface ZLinkActorSessionRouteFence {
     readonly objectGeneration: bigint;