@zlink-systems/framework 0.29.1 → 0.30.1

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

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApplicationJobQueue = exports.ApplicationJobQueuePermit = void 0;
 exports.resolveApplicationJobQueueConfiguration = resolveApplicationJobQueueConfiguration;
 exports.nodeEffectiveProcessorCount = nodeEffectiveProcessorCount;
+const api_logs_1 = require("@opentelemetry/api-logs");
+const message_flow_1 = require("../diagnostics/message-flow");
 const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 const Dispatch_1 = require("../../contracts/Dispatch");
 const Registration_1 = require("../../contracts/Configuration/Registration");
@@ -50,9 +52,32 @@ function resolveApplicationJobQueueConfiguration(options = {}, effectiveProcesso
 }
 class ApplicationJobQueuePermit {
     owner;
-    state = 'reserved';
-    constructor(owner) {
+    origin;
+    reusable;
+    detachedForHandlerTurn = false;
+    state;
+    constructor(owner, origin, reusable = false) {
         this.owner = owner;
+        this.origin = origin;
+        this.reusable = reusable;
+        this.state = reusable ? 'idle' : 'reserved';
+    }
+    reserveStorage() {
+        if (this.state !== 'idle')
+            return false;
+        this.state = 'reserved';
+        this.detachedForHandlerTurn = false;
+        return true;
+    }
+    releaseStorage() {
+        if (!this.reusable || this.state === 'idle')
+            return;
+        if (this.state !== 'released')
+            throw new Error('Reservation storage still owns queue capacity.');
+        this.state = 'idle';
+    }
+    detachForHandlerTurn() {
+        this.detachedForHandlerTurn = true;
     }
     markApplicationQueued() {
         if (this.state !== 'reserved') {
@@ -64,19 +89,75 @@ 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. */
+class ApplicationJobReceiveRotation {
+    owner;
+    capacity;
+    origin;
+    storage = [];
+    grants;
+    granted = 0;
+    consumed = 0;
+    constructor(owner, capacity, origin) {
+        this.owner = owner;
+        this.capacity = capacity;
+        this.origin = origin;
+        this.grants = new Array(capacity);
+        this.prepareStorage();
+    }
+    prepareStorage() {
+        for (let index = 0; index < this.capacity; index++)
+            this.storage.push(new ApplicationJobQueuePermit(this.owner, this.origin, true));
+    }
+    reserve() {
+        this.releaseUnused();
+        const count = this.owner.receiveRotationCapacity(this.capacity);
+        if (count === 0)
+            return;
+        for (let index = 0; index < this.storage.length; index++) {
+            const permit = this.storage[index];
+            if (permit.reserveStorage())
+                this.grants[this.granted++] = permit;
+            if (this.granted === count)
+                break;
+        }
+        if (this.granted < count) {
+            const start = this.storage.length;
+            this.prepareStorage();
+            for (let index = start; this.granted < count; index++) {
+                const permit = this.storage[index];
+                permit.reserveStorage();
+                this.grants[this.granted++] = permit;
+            }
+        }
+        this.owner.reserveReceiveRotation(count);
+    }
+    take() {
+        if (this.consumed === this.granted)
+            return undefined;
+        return this.grants[this.consumed++];
+    }
+    releaseUnused() {
+        this.owner.releaseUnusedReceiveRotation(this.grants, this.consumed, this.granted);
+        // Keep the prepared grant slots and reset only the logical count.
+        this.granted = 0;
+        this.consumed = 0;
+    }
+}
 /**
  * Host-instance owner of the ordinary-ingress queue permit lifecycle.
  * It reserves capacity before receive/claim and transfers released capacity
@@ -86,9 +167,14 @@ class ApplicationJobQueue {
     configuration;
     nowMs;
     handlerStartGate;
-    reservedSupplyPermits = 0n;
-    queuedApplicationJobs = 0n;
-    peakPermitsInUse = 0n;
+    loggerFailureReporter;
+    localWaiters = 0;
+    localBacklogLogged = false;
+    // 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;
@@ -104,15 +190,32 @@ class ApplicationJobQueue {
     waiters = [];
     receiveFlowTargets = new Map();
     receiveFlowController;
-    constructor(configuration, nowMs = () => performance.now(), handlerStartGate) {
+    constructor(configuration, nowMs = () => performance.now(), handlerStartGate, loggerFailureReporter) {
         this.configuration = configuration;
         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 = {
@@ -153,15 +256,24 @@ class ApplicationJobQueue {
         this.receiveFlowTargets.delete(identity);
         this.receiveFlowController.unregister(target);
     }
-    acquire(signal) {
+    acquire(signal, origin) {
+        return new Promise((resolve, reject) => {
+            const permit = this.acquireOrResume(resolve, reject, signal, origin);
+            if (permit !== undefined)
+                resolve(permit);
+        });
+    }
+    acquireOrResume(resume, reject, signal, origin) {
         if (signal?.aborted === true) {
-            return Promise.reject(abortReason(signal));
+            reject(abortReason(signal));
+            return undefined;
         }
-        if (this.waiters.length === 0 && this.permitsInUse() < this.limit()) {
-            return Promise.resolve(this.reserve());
+        if (this.waiters.length === 0 && this.permitsInUse() < this.limitCount) {
+            return this.reserve(origin);
         }
-        return new Promise((resolve, reject) => {
+        new Promise((resolve, reject) => {
             const waiter = {
+                origin,
                 resolve,
                 reject,
                 signal,
@@ -172,19 +284,25 @@ class ApplicationJobQueue {
             };
             this.waiters.push(waiter);
             this.capacityWaitCount += 1n;
+            const warningCount = this.updateLocalWaiters(origin, 1);
             signal?.addEventListener('abort', waiter.abort, { once: true });
             this.drainWaiters();
-        });
+            if (warningCount !== undefined)
+                this.logLocalBacklog(warningCount);
+        })
+            .then(resume)
+            .catch(reject);
+        return undefined;
     }
     snapshot() {
         const permitsInUse = this.permitsInUse();
         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,
@@ -198,7 +316,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;
@@ -225,25 +343,37 @@ 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;
-    }
-    release(state) {
-        if (state === 'reserved') {
-            if (this.reservedSupplyPermits === 0n) {
-                throw new Error('Application job queue reserved permit accounting underflow.');
-            }
-            this.reservedSupplyPermits -= 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(grants, consumed, granted) {
+        const count = granted - consumed;
+        if (count === 0)
+            return;
+        // Unconsumed grants still belong to this receive round; no record has acquired them.
+        for (let index = consumed; index < granted; index++) {
+            const permit = grants[index];
+            permit.takeReleaseState();
+            permit.releaseStorage();
         }
-        else {
-            if (this.queuedApplicationJobs === 0n) {
-                throw new Error('Application job queue queued permit accounting underflow.');
-            }
-            this.queuedApplicationJobs -= 1n;
+        this.release('reserved', count);
+    }
+    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();
     }
@@ -251,26 +381,28 @@ class ApplicationJobQueue {
         return this.configuration.effectiveMaxQueuedApplicationJobs;
     }
     permitsInUse() {
-        return this.reservedSupplyPermits + this.queuedApplicationJobs;
+        return (this.permitCounts[0 /* QueuePermitCount.Reserved */] + this.permitCounts[1 /* QueuePermitCount.Queued */]);
     }
-    reserve(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();
-        return new ApplicationJobQueuePermit(this);
+    }
+    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;
             waiter.active = false;
             waiter.signal?.removeEventListener('abort', waiter.abort);
             this.recordCompletedWait(waiter);
-            waiter.resolve(this.reserve(false));
+            waiter.resolve(this.reserve(waiter.origin, false));
         }
     }
     cancel(waiter) {
@@ -286,18 +418,50 @@ class ApplicationJobQueue {
         this.drainWaiters();
     }
     recordCompletedWait(waiter) {
+        this.updateLocalWaiters(waiter.origin, -1);
         if (waiter.metricsEpoch !== this.metricsEpoch)
             return;
         const durationMs = Math.max(0, this.nowMs() - waiter.startedAtMs);
         this.capacityWaitDurationSeconds += durationMs / runtime_metrics_1.MILLISECONDS_PER_SECOND;
     }
+    updateLocalWaiters(origin, delta) {
+        if (origin !== 'local')
+            return undefined;
+        this.localWaiters += delta;
+        if (this.localWaiters === 0)
+            this.localBacklogLogged = false;
+        if (!this.localBacklogLogged && this.localWaiters > Number(this.limit())) {
+            this.localBacklogLogged = true;
+            return this.localWaiters;
+        }
+        return undefined;
+    }
+    logLocalBacklog(localWaiters) {
+        try {
+            message_flow_1.telemetryLogger.emit({
+                eventName: 'zlink.runtime.host.local_job_backlog_exceeded',
+                timestamp: new Date(),
+                severityNumber: api_logs_1.SeverityNumber.WARN,
+                severityText: 'WARN',
+                body: 'Same-host jobs waiting for a host permit exceeded the application job queue maximum.',
+                attributes: {
+                    source_kind: 'host',
+                    source_name: 'zlink.runtime.host',
+                    local_waiters: localWaiters,
+                    effective_maximum: Number(this.limit())
+                }
+            });
+        }
+        catch (error) {
+            this.loggerFailureReporter?.(error);
+        }
+    }
     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;
@@ -66,7 +69,7 @@ class ZLinkEntryActorRuntimeService {
         }
         return {
             handled: true,
-            response: await spotManager.dispatchRoutedActorPacket(spotId, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef)
+            response: await spotManager.dispatchRoutedActorPacket('remote', spotId, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef)
         };
     }
     requireActorManager() {

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?;
@@ -95,6 +95,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     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 +110,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private recordRelocationResult;
     private completeTermination;
     private setRuntimeState;
+    private publishCurrentRuntimeStatus;
     private publishRuntimeStatus;
     private notifyTopologyHostStateChanged;
     private stopTopologyObservers;
@@ -163,7 +165,11 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private actorRuntimeOptionsFactory;
     private createChannelRuntimeOptions;
     private createSpotNodeRuntimeOptions;
+    private dispatchMeshNodeRecord;
+    private dispatchMeshNodePayload;
+    private completeFormalSourceLeave;
     private dispatchMeshRecord;
+    private dispatchMeshActorBinding;
     private submitLocalMeshRoute;
     private dispatchMeshSpotRecord;
     private createDispatchErrorReporter;