@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/host/application-job-queue.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationJobOrigin, ApplicationJobPermitPort, ApplicationJobQueuePort } from '../application-jobs/contracts';
+import type { ApplicationJobOrigin, ApplicationJobPermitPort, ApplicationJobReceiveRotationPort, ApplicationJobQueuePort } from '../application-jobs/contracts';
 export type ApplicationJobQueueProfileValue = 'compact' | 'low_latency' | 'balanced' | 'throughput';
 export interface ApplicationJobQueueOptions {
     readonly profile?: ApplicationJobQueueProfileValue;
@@ -40,12 +40,37 @@ export declare function resolveApplicationJobQueueConfiguration(options?: Applic
 export declare class ApplicationJobQueuePermit implements ApplicationJobPermitPort {
     private readonly owner;
     readonly origin: ApplicationJobOrigin;
+    private readonly storage?;
+    detachedForHandlerTurn: boolean;
     private state;
-    constructor(owner: ApplicationJobQueue, origin: ApplicationJobOrigin);
+    constructor(owner: ApplicationJobQueue, origin: ApplicationJobOrigin, storage?: ApplicationJobReceiveRotation | undefined);
+    reserveStorage(): boolean;
+    reacquire(signal: AbortSignal): Promise<ApplicationJobPermitPort>;
+    releaseStorage(): void;
+    detachForHandlerTurn(): void;
     markApplicationQueued(): void;
     releaseBeforeHandler(): void;
     releaseAfterInternalProcessing(): void;
-    private release;
+    takeReleaseState(): 'reserved' | 'queued' | undefined;
+}
+/**
+ * Connection-owned storage; queue accounting remains with the host queue.
+ * The rotation budget is a count reserved from the queue. Only a record that
+ * is actually received takes a permit, from the idle storage stack, so a
+ * rotation that receives one record touches one permit.
+ */
+declare class ApplicationJobReceiveRotation implements ApplicationJobReceiveRotationPort {
+    private readonly owner;
+    private readonly capacity;
+    private readonly origin;
+    private readonly idle;
+    private granted;
+    private consumed;
+    constructor(owner: ApplicationJobQueue, capacity: number, origin: ApplicationJobOrigin);
+    reserve(): void;
+    take(): ApplicationJobQueuePermit | undefined;
+    releaseUnused(): void;
+    returnIdle(permit: ApplicationJobQueuePermit): void;
 }
 /**
  * Host-instance owner of the ordinary-ingress queue permit lifecycle.
@@ -59,9 +84,10 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private readonly loggerFailureReporter?;
     private localWaiters;
     private localBacklogLogged;
-    private reservedSupplyPermits;
-    private queuedApplicationJobs;
-    private peakPermitsInUse;
+    private readonly permitCounts;
+    private readonly limitCount;
+    private readonly pauseCount;
+    private readonly resumeCount;
     private capacityWaitCount;
     private capacityWaitDurationSeconds;
     private metricsEpoch;
@@ -79,6 +105,9 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private readonly receiveFlowController;
     constructor(configuration: ApplicationJobQueueConfiguration, nowMs?: () => number, handlerStartGate?: (() => boolean) | undefined, loggerFailureReporter?: ((error: unknown) => void) | undefined);
     shouldHoldPermitBeforeHandler(): boolean;
+    createReceiveRotation(capacity: number, origin: ApplicationJobOrigin): ApplicationJobReceiveRotationPort;
+    receiveRotationCapacity(capacity: number): number;
+    reserveReceiveRotation(count: number): void;
     registerReceiveFlowTarget(identity: object, applyState: (state: ApplicationJobQueuePressureState) => void, failureSink?: (error: unknown) => void): boolean;
     unregisterReceiveFlowTarget(identity: object): void;
     acquire(signal: AbortSignal | undefined, origin: ApplicationJobOrigin): Promise<ApplicationJobQueuePermit>;
@@ -90,9 +119,12 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     onPressureStateChange(listener: (state: ApplicationJobQueuePressureState, sequence: bigint) => void): () => void;
     recordFlowStateConfigFailure(): void;
     markQueued(): void;
-    release(state: 'reserved' | 'queued'): void;
+    releasePermit(permit: ApplicationJobQueuePermit): void;
+    releaseUnusedReceiveRotation(count: number): void;
+    release(state: 'reserved' | 'queued', count?: number): void;
     private limit;
     private permitsInUse;
+    private reserveSupply;
     private reserve;
     private drainWaiters;
     private cancel;
@@ -104,3 +136,4 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private cumulativePauseDurationAt;
 }
 export declare function nodeEffectiveProcessorCount(explicitExecutorMaximum?: number, runtimeConstrainedLogicalCount?: number, readSystemText?: (path: string) => string | undefined): bigint;
+export {};

package/dist/runtime/host/application-job-queue.js

@@ -53,10 +53,35 @@ function resolveApplicationJobQueueConfiguration(options = {}, effectiveProcesso
 class ApplicationJobQueuePermit {
     owner;
     origin;
-    state = 'reserved';
-    constructor(owner, origin) {
+    storage;
+    detachedForHandlerTurn = false;
+    state;
+    constructor(owner, origin, storage) {
         this.owner = owner;
         this.origin = origin;
+        this.storage = storage;
+        this.state = storage === undefined ? 'reserved' : 'idle';
+    }
+    reserveStorage() {
+        if (this.state !== 'idle')
+            return false;
+        this.state = 'reserved';
+        this.detachedForHandlerTurn = false;
+        return true;
+    }
+    reacquire(signal) {
+        return this.owner.acquire(signal, this.origin);
+    }
+    releaseStorage() {
+        if (this.storage === undefined || this.state === 'idle')
+            return;
+        if (this.state !== 'released')
+            throw new Error('Reservation storage still owns queue capacity.');
+        this.state = 'idle';
+        this.storage.returnIdle(this);
+    }
+    detachForHandlerTurn() {
+        this.detachedForHandlerTurn = true;
     }
     markApplicationQueued() {
         if (this.state !== 'reserved') {
@@ -68,19 +93,64 @@ class ApplicationJobQueuePermit {
     releaseBeforeHandler() {
         if (this.owner.shouldHoldPermitBeforeHandler())
             return;
-        this.release();
+        this.owner.releasePermit(this);
     }
     releaseAfterInternalProcessing() {
-        this.release();
+        this.owner.releasePermit(this);
     }
-    release() {
-        if (this.state === 'released')
-            return;
-        this.owner.release(this.state);
+    takeReleaseState() {
+        if (this.state === 'released' || this.state === 'idle')
+            return undefined;
+        const state = this.state;
         this.state = 'released';
+        return state;
     }
 }
 exports.ApplicationJobQueuePermit = ApplicationJobQueuePermit;
+/**
+ * Connection-owned storage; queue accounting remains with the host queue.
+ * The rotation budget is a count reserved from the queue. Only a record that
+ * is actually received takes a permit, from the idle storage stack, so a
+ * rotation that receives one record touches one permit.
+ */
+class ApplicationJobReceiveRotation {
+    owner;
+    capacity;
+    origin;
+    idle = [];
+    granted = 0;
+    consumed = 0;
+    constructor(owner, capacity, origin) {
+        this.owner = owner;
+        this.capacity = capacity;
+        this.origin = origin;
+    }
+    reserve() {
+        this.releaseUnused();
+        const count = this.owner.receiveRotationCapacity(this.capacity);
+        if (count === 0)
+            return;
+        this.granted = count;
+        this.owner.reserveReceiveRotation(count);
+    }
+    take() {
+        if (this.consumed === this.granted)
+            return undefined;
+        this.consumed++;
+        const permit = this.idle.pop() ?? new ApplicationJobQueuePermit(this.owner, this.origin, this);
+        permit.reserveStorage();
+        return permit;
+    }
+    releaseUnused() {
+        // Unconsumed budget never became a permit; it returns as a count.
+        this.owner.releaseUnusedReceiveRotation(this.granted - this.consumed);
+        this.granted = 0;
+        this.consumed = 0;
+    }
+    returnIdle(permit) {
+        this.idle.push(permit);
+    }
+}
 /**
  * Host-instance owner of the ordinary-ingress queue permit lifecycle.
  * It reserves capacity before receive/claim and transfers released capacity
@@ -93,9 +163,11 @@ class ApplicationJobQueue {
     loggerFailureReporter;
     localWaiters = 0;
     localBacklogLogged = false;
-    reservedSupplyPermits = 0n;
-    queuedApplicationJobs = 0n;
-    peakPermitsInUse = 0n;
+    // The contract bounds capacity by INT32_MAX; public snapshots remain bigint.
+    permitCounts = new Uint32Array(3 /* QueuePermitCount.Size */);
+    limitCount;
+    pauseCount;
+    resumeCount;
     capacityWaitCount = 0n;
     capacityWaitDurationSeconds = 0;
     metricsEpoch = 0n;
@@ -116,11 +188,27 @@ class ApplicationJobQueue {
         this.nowMs = nowMs;
         this.handlerStartGate = handlerStartGate;
         this.loggerFailureReporter = loggerFailureReporter;
+        this.limitCount = Number(configuration.effectiveMaxQueuedApplicationJobs);
+        this.pauseCount = Number(configuration.pausePermitCount);
+        this.resumeCount = Number(configuration.resumePermitCount);
         this.receiveFlowController = new receive_flow_controller_1.ApplicationJobReceiveFlowController(this, (state) => state);
     }
     shouldHoldPermitBeforeHandler() {
         return this.handlerStartGate?.() === true;
     }
+    createReceiveRotation(capacity, origin) {
+        if (!Number.isSafeInteger(capacity) || capacity < 1)
+            throw new RangeError('Receive capacity must be positive.');
+        return new ApplicationJobReceiveRotation(this, capacity, origin);
+    }
+    receiveRotationCapacity(capacity) {
+        if (this.waiters.length !== 0)
+            return 0;
+        return Math.min(capacity, this.limitCount - this.permitsInUse());
+    }
+    reserveReceiveRotation(count) {
+        this.reserveSupply(count);
+    }
     registerReceiveFlowTarget(identity, applyState, failureSink) {
         this.unregisterReceiveFlowTarget(identity);
         const target = {
@@ -173,7 +261,7 @@ class ApplicationJobQueue {
             reject(abortReason(signal));
             return undefined;
         }
-        if (this.waiters.length === 0 && this.permitsInUse() < this.limit()) {
+        if (this.waiters.length === 0 && this.permitsInUse() < this.limitCount) {
             return this.reserve(origin);
         }
         new Promise((resolve, reject) => {
@@ -204,10 +292,10 @@ class ApplicationJobQueue {
         const now = this.nowMs();
         return Object.freeze({
             ...this.configuration,
-            reservedSupplyPermits: this.reservedSupplyPermits,
-            queuedApplicationJobs: this.queuedApplicationJobs,
-            permitsInUse,
-            peakPermitsInUse: this.peakPermitsInUse,
+            reservedSupplyPermits: BigInt(this.permitCounts[0 /* QueuePermitCount.Reserved */]),
+            queuedApplicationJobs: BigInt(this.permitCounts[1 /* QueuePermitCount.Queued */]),
+            permitsInUse: BigInt(permitsInUse),
+            peakPermitsInUse: BigInt(this.permitCounts[2 /* QueuePermitCount.Peak */]),
             capacityWaiters: BigInt(this.waiters.length),
             capacityWaitCount: this.capacityWaitCount,
             capacityWaitDurationSeconds: this.capacityWaitDurationSeconds,
@@ -221,7 +309,7 @@ class ApplicationJobQueue {
     }
     resetMetrics() {
         this.metricsEpoch += 1n;
-        this.peakPermitsInUse = this.permitsInUse();
+        this.permitCounts[2 /* QueuePermitCount.Peak */] = this.permitsInUse();
         this.capacityWaitCount = 0n;
         this.capacityWaitDurationSeconds = 0;
         this.runningTransitionCount = 0n;
@@ -248,25 +336,31 @@ class ApplicationJobQueue {
         this.flowStateConfigFailureCount += 1n;
     }
     markQueued() {
-        if (this.reservedSupplyPermits === 0n) {
+        if (this.permitCounts[0 /* QueuePermitCount.Reserved */] === 0) {
             throw new Error('Application job queue has no reserved supply permit.');
         }
-        this.reservedSupplyPermits -= 1n;
-        this.queuedApplicationJobs += 1n;
+        this.permitCounts[0 /* QueuePermitCount.Reserved */] =
+            this.permitCounts[0 /* QueuePermitCount.Reserved */] - 1;
+        this.permitCounts[1 /* QueuePermitCount.Queued */] = this.permitCounts[1 /* QueuePermitCount.Queued */] + 1;
+    }
+    releasePermit(permit) {
+        const state = permit.takeReleaseState();
+        if (state !== undefined)
+            this.release(state);
+    }
+    releaseUnusedReceiveRotation(count) {
+        // Unconsumed budget still belongs to this receive round; no record has acquired it.
+        if (count === 0)
+            return;
+        this.release('reserved', count);
     }
-    release(state) {
-        if (state === 'reserved') {
-            if (this.reservedSupplyPermits === 0n) {
-                throw new Error('Application job queue reserved permit accounting underflow.');
-            }
-            this.reservedSupplyPermits -= 1n;
-        }
-        else {
-            if (this.queuedApplicationJobs === 0n) {
-                throw new Error('Application job queue queued permit accounting underflow.');
-            }
-            this.queuedApplicationJobs -= 1n;
+    release(state, count = 1) {
+        const index = state === 'reserved' ? 0 /* QueuePermitCount.Reserved */ : 1 /* QueuePermitCount.Queued */;
+        const available = this.permitCounts[index];
+        if (available < count) {
+            throw new Error(`Application job queue ${state} permit accounting underflow.`);
         }
+        this.permitCounts[index] = available - count;
         this.drainWaiters();
         this.evaluatePressure();
     }
@@ -274,19 +368,21 @@ class ApplicationJobQueue {
         return this.configuration.effectiveMaxQueuedApplicationJobs;
     }
     permitsInUse() {
-        return this.reservedSupplyPermits + this.queuedApplicationJobs;
+        return (this.permitCounts[0 /* QueuePermitCount.Reserved */] + this.permitCounts[1 /* QueuePermitCount.Queued */]);
     }
-    reserve(origin, evaluatePressure = true) {
-        this.reservedSupplyPermits += 1n;
-        const current = this.permitsInUse();
-        if (current > this.peakPermitsInUse)
-            this.peakPermitsInUse = current;
+    reserveSupply(count, evaluatePressure = true) {
+        this.permitCounts[0 /* QueuePermitCount.Reserved */] =
+            this.permitCounts[0 /* QueuePermitCount.Reserved */] + count;
+        this.permitCounts[2 /* QueuePermitCount.Peak */] = Math.max(this.permitCounts[2 /* QueuePermitCount.Peak */], this.permitsInUse());
         if (evaluatePressure)
             this.evaluatePressure();
+    }
+    reserve(origin, evaluatePressure = true) {
+        this.reserveSupply(1, evaluatePressure);
         return new ApplicationJobQueuePermit(this, origin);
     }
     drainWaiters() {
-        while (this.waiters.length > 0 && this.permitsInUse() < this.limit()) {
+        while (this.waiters.length > 0 && this.permitsInUse() < this.limitCount) {
             const waiter = this.waiters.shift();
             if (!waiter.active)
                 continue;
@@ -348,12 +444,11 @@ class ApplicationJobQueue {
         }
     }
     evaluatePressure() {
-        const permitsInUse = this.permitsInUse();
         const next = this.pressureStateValue === 'running'
-            ? permitsInUse >= this.configuration.pausePermitCount
+            ? this.permitsInUse() >= this.pauseCount
                 ? 'paused'
                 : 'running'
-            : permitsInUse <= this.configuration.resumePermitCount
+            : this.permitsInUse() <= this.resumeCount
                 ? 'running'
                 : 'paused';
         if (next === this.pressureStateValue)

package/dist/runtime/host/entry-actor-runtime.d.ts

@@ -20,6 +20,7 @@ export declare class ZLinkEntryActorRuntimeService implements ZLinkEntryActorRun
     private readonly binder;
     constructor(options: ZLinkEntryActorRuntimeOptions);
     resolveActor(actorId: string): ZLinkActor | undefined;
+    releaseMembers(meshName: string): Promise<void>;
     commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
     destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: ActorRef['nodeRid'], actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     routePacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<{

package/dist/runtime/host/entry-actor-runtime.js

@@ -16,6 +16,9 @@ class ZLinkEntryActorRuntimeService {
     resolveActor(actorId) {
         return this.options.actorManager()?.getState(actorId)?.actor;
     }
+    async releaseMembers(meshName) {
+        await this.options.actorManager()?.releaseSpotActorMembers(meshName);
+    }
     async commitActorTransaction(actor, onJoined) {
         const state = this.options.actorManager()?.getState(actor.context.actorId);
         const entryNode = this.options.spotNodeRuntime()?.primaryMeshNode;

package/dist/runtime/host/index.d.ts

@@ -30,7 +30,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private readonly lifecycleSink?;
     private executionState?;
     private runtimeState;
-    private runtimeSequence;
+    private runtimeStatus?;
     private readonly runtimeObservationSource;
     private runtimeDeadline?;
     private shutdownDeadline?;
@@ -91,10 +91,12 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     readonly routeMeshRuntime: ZLinkRouteMeshRuntime;
     readonly clientServerRuntime: ZLinkClientServerRuntime;
     readonly fanoutRuntime: ZLinkFanoutRuntime;
+    private readonly relocationStore?;
     private readonly routeMeshCoordinator;
     constructor(options: ZLinkFrameworkRuntimeHostOptions, internalOptions?: unknown);
     get isStarted(): boolean;
     get status(): ZLinkFrameworkRuntimeStatus;
+    private buildRuntimeStatus;
     private listenerRecords;
     getListenerStatus(kind: ZLinkListenerKind, name: string): ZLinkListenerStatus;
     observe(signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkFrameworkRuntimeStatus>>;
@@ -109,6 +111,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private recordRelocationResult;
     private completeTermination;
     private setRuntimeState;
+    private publishCurrentRuntimeStatus;
     private publishRuntimeStatus;
     private notifyTopologyHostStateChanged;
     private stopTopologyObservers;
@@ -133,6 +136,9 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private stopCore;
     private installOwnerLeaseRecoveryPublication;
     private resumeOwnerLeaseOwnedWork;
+    private enterServing;
+    private publishOrStayPreparing;
+    private startStatefulAuthority;
     private createStatefulAuthorityRoutes;
     private requiresStatefulAuthorityRuntime;
     private installLocationBackedAuthorities;
@@ -151,7 +157,6 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private publishHostRelocated;
     private publishHostDraining;
     private cleanupOwnerForDrain;
-    private forceStopMesh;
     private registerInstanceApplicationLifecycle;
     setActorManager(actorManager: DefaultZLinkActorManager): void;
     setSpotManager(spotManager: DefaultZLinkSpotManager): void;
@@ -163,7 +168,12 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private actorRuntimeOptionsFactory;
     private createChannelRuntimeOptions;
     private createSpotNodeRuntimeOptions;
+    private dispatchMeshNodeRecord;
+    private dispatchMeshNodePayload;
+    private completeFormalSourceLeave;
     private dispatchMeshRecord;
+    private admitMeshDispatch;
+    private dispatchMeshActorBinding;
     private submitLocalMeshRoute;
     private dispatchMeshSpotRecord;
     private createDispatchErrorReporter;