@zlink-systems/framework 0.29.1 → 0.30.1

package/dist/runtime/foundation/service-liveness-registry.d.ts

@@ -1,6 +1,6 @@
 export interface ServiceProbe {
     readonly nodeRoutingId: string;
-    readonly connectionId: string;
+    readonly connectionId: string | bigint;
     readonly probeId: bigint;
 }
 export interface ServiceLivenessTick {
@@ -9,6 +9,19 @@ export interface ServiceLivenessTick {
 }
 export declare const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5000;
 export declare const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15000;
+export declare class ServiceLivenessConnection {
+    readonly connectionId: string | bigint;
+    private readonly probeIntervalMs;
+    private readonly peerTimeoutMs;
+    deadlineMs: number;
+    nextProbeMs: number;
+    outstandingProbe?: bigint;
+    constructor(connectionId: string | bigint, nowMs: number, probeIntervalMs?: number, peerTimeoutMs?: number);
+    readonly recordReceived: (nowMs?: number) => void;
+    isExpired(nowMs: number): boolean;
+    tryGetProbe(nowMs: number, allocateProbeId: () => bigint): bigint | undefined;
+    acknowledge(probeId: bigint, nowMs: number): boolean;
+}
 /** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
 export declare class ServiceLivenessRegistry {
     private readonly probeIntervalMs;
@@ -16,13 +29,12 @@ export declare class ServiceLivenessRegistry {
     private readonly peers;
     private nextProbeId;
     constructor(probeIntervalMs?: number, peerTimeoutMs?: number);
-    admit(nodeRoutingId: string, connectionId: string, nowMs: number): void;
-    requestProbe(nodeRoutingId: string, connectionId: string, nowMs: number): boolean;
-    disconnect(nodeRoutingId: string, connectionId: string): boolean;
-    acknowledge(nodeRoutingId: string, connectionId: string, probeId: bigint, nowMs: number): boolean;
-    acknowledgeProbe(nodeRoutingId: string, connectionId: string, probeId: bigint): ServiceProbe | undefined;
+    admit(nodeRoutingId: string, connectionId: string | bigint, nowMs: number): ServiceLivenessConnection;
+    recordReceived(connection: ServiceLivenessConnection, nowMs: number): void;
+    disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean;
+    acknowledge(nodeRoutingId: string, connectionId: string | bigint, probeId: bigint, nowMs: number): boolean;
+    acknowledgeProbe(nodeRoutingId: string, connectionId: string | bigint, probeId: bigint): ServiceProbe | undefined;
     tick(nowMs: number): ServiceLivenessTick;
     get size(): number;
-    isReady(nodeRoutingId: string, connectionId: string): boolean;
-    private allocateProbeId;
+    private readonly allocateProbeId;
 }

package/dist/runtime/foundation/service-liveness-registry.js

@@ -1,9 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceLivenessRegistry = exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS = exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS = void 0;
+exports.ServiceLivenessRegistry = exports.ServiceLivenessConnection = exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS = exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS = void 0;
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
 exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+class ServiceLivenessConnection {
+    connectionId;
+    probeIntervalMs;
+    peerTimeoutMs;
+    deadlineMs;
+    nextProbeMs;
+    outstandingProbe;
+    constructor(connectionId, nowMs, probeIntervalMs = exports.DEFAULT_SERVICE_PROBE_INTERVAL_MS, peerTimeoutMs = exports.DEFAULT_SERVICE_PEER_TIMEOUT_MS) {
+        this.connectionId = connectionId;
+        this.probeIntervalMs = probeIntervalMs;
+        this.peerTimeoutMs = peerTimeoutMs;
+        this.deadlineMs = nowMs + peerTimeoutMs;
+        this.nextProbeMs = nowMs;
+    }
+    recordReceived = (nowMs = performance.now()) => {
+        this.deadlineMs = Math.max(this.deadlineMs, nowMs + this.peerTimeoutMs);
+    };
+    isExpired(nowMs) {
+        return nowMs >= this.deadlineMs;
+    }
+    tryGetProbe(nowMs, allocateProbeId) {
+        if (nowMs < this.nextProbeMs)
+            return undefined;
+        this.outstandingProbe ??= allocateProbeId();
+        do {
+            this.nextProbeMs += this.probeIntervalMs;
+        } while (this.nextProbeMs <= nowMs);
+        return this.outstandingProbe;
+    }
+    acknowledge(probeId, nowMs) {
+        this.recordReceived(nowMs);
+        if (this.outstandingProbe !== probeId)
+            return false;
+        this.outstandingProbe = undefined;
+        return true;
+    }
+}
+exports.ServiceLivenessConnection = ServiceLivenessConnection;
 /** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
 class ServiceLivenessRegistry {
     probeIntervalMs;
@@ -22,26 +60,19 @@ class ServiceLivenessRegistry {
     }
     admit(nodeRoutingId, connectionId, nowMs) {
         requireIdentity(nodeRoutingId, 'nodeRoutingId');
-        requireIdentity(connectionId, 'connectionId');
+        if (typeof connectionId === 'string')
+            requireIdentity(connectionId, 'connectionId');
+        else if (connectionId === 0n)
+            throw new TypeError('connectionId must be nonzero.');
         const current = this.peers.get(nodeRoutingId);
         if (current?.connectionId === connectionId)
-            return;
-        this.peers.set(nodeRoutingId, {
-            connectionId,
-            deadlineMs: nowMs + this.peerTimeoutMs,
-            nextProbeMs: nowMs + this.probeIntervalMs,
-            ready: false
-        });
+            return current;
+        const admitted = new ServiceLivenessConnection(connectionId, nowMs, this.probeIntervalMs, this.peerTimeoutMs);
+        this.peers.set(nodeRoutingId, admitted);
+        return admitted;
     }
-    requestProbe(nodeRoutingId, connectionId, nowMs) {
-        const current = this.peers.get(nodeRoutingId);
-        if (current === undefined ||
-            current.connectionId !== connectionId ||
-            current.ready ||
-            current.outstandingProbe !== undefined)
-            return false;
-        current.nextProbeMs = Math.min(current.nextProbeMs, nowMs);
-        return true;
+    recordReceived(connection, nowMs) {
+        connection.recordReceived(nowMs);
     }
     disconnect(nodeRoutingId, connectionId) {
         const current = this.peers.get(nodeRoutingId);
@@ -52,15 +83,9 @@ class ServiceLivenessRegistry {
     }
     acknowledge(nodeRoutingId, connectionId, probeId, nowMs) {
         const current = this.peers.get(nodeRoutingId);
-        if (current === undefined ||
-            current.connectionId !== connectionId ||
-            current.outstandingProbe !== probeId) {
+        if (current === undefined || current.connectionId !== connectionId)
             return false;
-        }
-        current.outstandingProbe = undefined;
-        current.deadlineMs = nowMs + this.peerTimeoutMs;
-        current.ready = true;
-        return true;
+        return current.acknowledge(probeId, nowMs);
     }
     acknowledgeProbe(nodeRoutingId, connectionId, probeId) {
         const current = this.peers.get(nodeRoutingId);
@@ -73,22 +98,14 @@ class ServiceLivenessRegistry {
         const probes = [];
         const timedOutNodes = [];
         for (const [nodeRoutingId, peer] of this.peers) {
-            if (peer.deadlineMs <= nowMs) {
+            if (peer.isExpired(nowMs)) {
                 timedOutNodes.push(nodeRoutingId);
                 this.peers.delete(nodeRoutingId);
                 continue;
             }
-            if (peer.nextProbeMs > nowMs)
-                continue;
-            peer.outstandingProbe ??= this.allocateProbeId();
-            probes.push({
-                nodeRoutingId,
-                connectionId: peer.connectionId,
-                probeId: peer.outstandingProbe
-            });
-            do {
-                peer.nextProbeMs += this.probeIntervalMs;
-            } while (peer.nextProbeMs <= nowMs);
+            const probeId = peer.tryGetProbe(nowMs, this.allocateProbeId);
+            if (probeId !== undefined)
+                probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId });
         }
         timedOutNodes.sort();
         return { probes, timedOutNodes };
@@ -96,16 +113,12 @@ class ServiceLivenessRegistry {
     get size() {
         return this.peers.size;
     }
-    isReady(nodeRoutingId, connectionId) {
-        const current = this.peers.get(nodeRoutingId);
-        return current?.connectionId === connectionId && current.ready;
-    }
-    allocateProbeId() {
+    allocateProbeId = () => {
         const result = this.nextProbeId++;
         if (this.nextProbeId > stream_wire_1.UINT64_MAX)
             this.nextProbeId = 1n;
         return result;
-    }
+    };
 }
 exports.ServiceLivenessRegistry = ServiceLivenessRegistry;
 function requireIdentity(value, field) {

package/dist/runtime/foundation/service-mailbox.d.ts

@@ -1,4 +1,5 @@
 import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
+import type { ReceiveRecord } from './service-runtime-contracts';
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 export interface ServiceMailboxRecord {
     readonly owner: string;
@@ -17,6 +18,8 @@ export interface ServiceMailboxRecord {
     readonly stateful?: unknown;
     /** Host queue permit plus its ordinary Framework-owned ingress record. */
     readonly applicationJob?: ApplicationJobRecordLease;
+    /** Unregistered raw-pull terminal, retained by the existing mailbox owner. */
+    readonly completion?: ReceiveRecord;
 }
 export interface ServiceMailboxClaim {
     readonly owner: string;

package/dist/runtime/foundation/service-mailbox.js

@@ -24,7 +24,8 @@ class ServiceMailbox {
         record.parts = [];
     }
     tryEnqueue(record) {
-        if (record.owner.length === 0 || record.parts.length === 0) {
+        if (record.owner.length === 0 ||
+            (record.parts.length === 0 && record.completion === undefined)) {
             throw new TypeError('Mailbox records require an owner and retained payload.');
         }
         const target = this.domain(record.domain);

package/dist/runtime/foundation/service-relocation-object-owner.d.ts

@@ -3,6 +3,7 @@ import type { ServiceRelocationRestoreOwner, ServiceRelocationStaging } from './
 import type { ServiceRelocationEnvelope, ServiceRelocationMembership, ServiceRelocationParticipant, ServiceRelocationQueuedMessage, ServiceRelocationTimer } from './service-relocation-runtime';
 export interface ServiceRelocationSealedWork {
     readonly boundSessionState: Uint8Array;
+    readonly sessionBinding?: ServiceRelocationParticipant['sessionBinding'];
     readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
     readonly timers: readonly ServiceRelocationTimer[];
 }

package/dist/runtime/foundation/service-relocation-object-owner.js

@@ -102,6 +102,7 @@ class ServiceRelocationObjectCaptureOwner {
                 authorityOwnerGeneration: unit.authorityOwnerGeneration,
                 applicationState: Buffer.from(await unit.captureApplicationState(signal)),
                 boundSessionState: Buffer.from(work.boundSessionState),
+                ...(work.sessionBinding === undefined ? {} : { sessionBinding: work.sessionBinding }),
                 queuedMessages: work.queuedMessages.map((message) => ({
                     sequence: message.sequence,
                     payload: Buffer.from(message.payload)

package/dist/runtime/foundation/service-relocation-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { ZLinkPlacementObjectKind } from '../locations/internal-location-contracts';
+import { type RelocationEnvelopeV1 as GeneratedRelocationEnvelopeV1 } from '../protocol/service_wire_pilot_codec.generated';
 export interface ServiceRelocationParticipant {
     /** Wire-local participant ordinal; identity is projected from Location Store. */
     readonly participantId?: bigint;
@@ -17,6 +18,7 @@ export interface ServiceRelocationParticipant {
     readonly applicationStatePresent?: boolean;
     readonly applicationState: Uint8Array;
     readonly boundSessionState: Uint8Array;
+    readonly sessionBinding?: GeneratedRelocationEnvelopeV1['sessionBindings'][number];
     readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
     readonly timers: readonly ServiceRelocationTimer[];
 }

package/dist/runtime/foundation/service-relocation-runtime.js

@@ -480,6 +480,9 @@ function encodeServiceRelocationEnvelope(envelope, applicationVersion) {
             lastCompletedScheduledIndex: nonNegativeBigInt(timer.lastScheduledIndex, 'timer scheduled index'),
             nextScheduledAtUnixMilliseconds: nonNegativeUnixMilliseconds(timer.dueAtUnixMs, 'timer due time')
         })),
+        sessionBindings: participants.flatMap((participant, index) => participant.sessionBinding === undefined
+            ? []
+            : [{ ...participant.sessionBinding, participantId: BigInt(index + 1) }]),
         pendingTimerTicks: pending.map((value) => ({
             participantId: value.participantId,
             order: value.order,
@@ -510,11 +513,20 @@ function decodeServiceRelocationEnvelope(payload, aggregateGeneration) {
     if (aggregateId === undefined)
         throw new TypeError('Invalid relocation identity.');
     positiveBigInt(aggregateGeneration, 'aggregate generation');
+    const bindings = new Map(generated.sessionBindings.map((binding) => [binding.participantId, binding]));
+    for (const id of bindings.keys()) {
+        if (id > BigInt(generated.applicationStates.length))
+            throw new TypeError('Session binding participant is outside its inventory.');
+    }
     const participants = generated.applicationStates.map((state, index) => {
         if (state.participantId !== BigInt(index + 1)) {
             throw new TypeError('Application state participant order is invalid.');
         }
-        return wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload));
+        const binding = bindings.get(state.participantId);
+        return {
+            ...wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload)),
+            ...(binding === undefined ? {} : { sessionBinding: binding })
+        };
     });
     const byId = new Map(participants.map((value) => [value.participantId, value]));
     for (const work of generated.savedWork) {

package/dist/runtime/foundation/service-runtime-contracts.d.ts

@@ -343,6 +343,7 @@ export interface ServiceSpot {
         flags?: number;
         timeoutMs?: number;
         applicationMetadata?: Buffer;
+        onAdmitted?: () => void;
     }): MeshOperationId;
     sendToSpot(targetNodeRid: unknown, targetSpotId: unknown, targetSpotGeneration: bigint, parts: MessageLike | readonly MessageLike[], options?: {
         flags?: number;
@@ -354,6 +355,7 @@ export interface ServiceSpot {
         timeoutMs?: number;
         applicationMetadata?: Buffer;
         routeFence?: ServiceDirectSpotRouteFence;
+        onAdmitted?: () => void;
         entrySpot?: boolean;
     }): MeshOperationId;
     publish(channelName: string, topic: string, parts: MessageLike | readonly MessageLike[], options?: {

package/dist/runtime/foundation/service-stateful-runtime.d.ts

@@ -5,7 +5,7 @@ import type { ServiceInstanceActivationRecoveryEnvelope } from './service-instan
 import type { ServiceMailboxRecord } from './service-mailbox';
 import { type ReceiveKindData, type ServiceStreamSessionBinding, type StreamSessionActorAuthorityFence } from './service-runtime-contracts';
 import { ServiceStatefulRegistry, type ServiceActorRef, type ServiceActorState, type ServiceSessionBinding, type ServiceSpotRef, type ServiceSpotState } from './service-stateful-registry';
-import { type ServiceActorCreateRecord, type ServiceActorRouteFence, type ServiceDirectSpotRouteFence, type ServiceInstanceActivationTarget, type ServiceInstanceRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceStatefulReplyTail, type ServiceStatefulWireRecord, type ServiceUserSpotCloseRecord, type ServiceUserSpotCreateRecord } from './service-stateful-wire-codec';
+import { type ServiceActorCreateRecord, type ServiceActorRouteFence, type ServiceDirectSpotRouteFence, type ServiceInstanceActivationTarget, type ServiceInstanceColdActivationTarget, type ServiceInstanceRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceStatefulReplyTail, type ServiceStatefulWireRecord, type ServiceUserSpotCloseRecord, type ServiceUserSpotCreateRecord } from './service-stateful-wire-codec';
 import { type ServiceApplicationPayload } from './service-wire-m6a-codec';
 export interface ServiceSpotMessageFollowSeal {
     readonly key: string;
@@ -148,7 +148,7 @@ export interface ServiceInstanceActivationAuthority {
  * operation completes; the binding callback itself never blocks.
  */
 export interface ServiceAsyncInstanceActivationAuthority {
-    read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
+    read(target: ServiceInstanceActivationTarget, instanceIntent?: true, activation?: ServiceInstanceActivationRecoveryEnvelope, acceptsLocal?: (route: ServiceInstanceRouteFence) => boolean): Promise<ServiceInstanceAuthorityRead>;
     reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>, signal?: AbortSignal): Promise<ServiceInstanceAuthorityReserve>;
     resume(target: ServiceInstanceActivationTarget, pending: ServicePendingInstanceActivation): Promise<ServiceInstanceActivationReservation>;
     commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState, deadlineUnixMs?: bigint): Promise<{
@@ -270,7 +270,7 @@ export declare class ServiceStatefulRuntime {
     clearSubscriptions(spotId: string): void;
     publishLogicalMulticast(channelName: string, topic: string, payload: ServiceApplicationPayload, sourceSpotId?: string): Promise<void>;
     sendToSpot(sourceSpotId: string, requested: ServiceDirectSpotRouteFence, payload: ServiceApplicationPayload): Promise<number>;
-    requestToSpot(sourceSpotId: string, requested: ServiceDirectSpotRouteFence, payload: ServiceApplicationPayload, timeoutMs: number): ServiceStatefulPendingOperation;
+    requestToSpot(sourceSpotId: string, requested: ServiceDirectSpotRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, onAdmitted?: () => void): ServiceStatefulPendingOperation;
     sendToActor(target: ServiceActorRef, _targetNodeGeneration: bigint, _authorityOwnerGeneration: bigint, payload: ServiceApplicationPayload, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
@@ -278,13 +278,13 @@ export declare class ServiceStatefulRuntime {
     requestToActor(target: ServiceActorRef, _targetNodeGeneration: bigint, _authorityOwnerGeneration: bigint, payload: ServiceApplicationPayload, timeoutMs: number, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
-    }): ServiceStatefulPendingOperation;
+    }, onAdmitted?: () => void): ServiceStatefulPendingOperation;
     sendToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean): Promise<number>;
-    sendToMissingInstanceSpot(target: ServiceInstanceActivationTarget, payload: ServiceApplicationPayload, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
-    sendToMissingInstanceSpotFrame(target: ServiceInstanceActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
-    requestToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean): ServiceStatefulPendingOperation;
-    requestToMissingInstanceSpot(target: ServiceInstanceActivationTarget, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
-    requestToMissingInstanceSpotFrame(target: ServiceInstanceActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
+    sendToMissingInstanceSpot(target: ServiceInstanceColdActivationTarget, payload: ServiceApplicationPayload, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
+    sendToMissingInstanceSpotFrame(target: ServiceInstanceColdActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
+    requestToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean, onAdmitted?: () => void): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpot(target: ServiceInstanceColdActivationTarget, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpotFrame(target: ServiceInstanceColdActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array, onAdmitted?: () => void): ServiceStatefulPendingOperation;
     lookupRemoteActor(targetNodeRid: string, actorId: string, timeoutMs: number): ServiceStatefulPendingOperation;
     destroyActor(actor: ServiceActorRef, timeoutMs: number): ServiceStatefulPendingOperation;
     joinActor(actor: ServiceActorRef, targetNodeRid: string, targetSpot: ServiceSpotRef, targetSpotGeneration: bigint, payload: ServiceApplicationPayload | undefined, timeoutMs: number): ServiceStatefulPendingOperation;
@@ -324,6 +324,7 @@ export declare class ServiceStatefulRuntime {
     private requireReadyInstanceApplicationRoute;
     private validateInstanceIngress;
     private activateMissingInstance;
+    private localReadyInstance;
     private activateMissingInstanceAsync;
     private runMissingInstanceActivation;
     private acceptsLocalMissingInstancePlacement;