@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -67,6 +67,38 @@ export interface ServiceCanonicalActorJoinCandidate {
         readonly transferId: string;
     };
 }
+/**
+ * Session–Actor binding §4: the owner ID and owner lease generation of a
+ * Session owner identity are the host's `(OwnerId, LeaseGeneration)` published
+ * in its MeshNode descriptor.
+ */
+export interface ServiceSessionOwnerToken {
+    readonly ownerId: string;
+    readonly leaseGeneration: bigint;
+}
+/** The descriptor source of the Session owner identity (§4). */
+export interface ServiceSessionOwnerDescriptors {
+    /** This host's published token, or undefined while it has no live descriptor. */
+    local(): ServiceSessionOwnerToken | undefined;
+    /**
+     * The token of the admitted peer descriptor with this exact RID and
+     * lifecycle generation that passed the Location runtime §4.1 owner lease
+     * check, or undefined when no such descriptor exists.
+     */
+    peer(nodeRid: string, nodeGeneration: bigint): Promise<ServiceSessionOwnerToken | undefined>;
+}
+/** The four values of one Session owner identity (§4). */
+export interface ServiceSessionOwnerIdentity {
+    readonly nodeRid: string;
+    readonly nodeGeneration: bigint;
+    readonly ownerId: string;
+    readonly leaseGeneration: bigint;
+}
+/**
+ * The receiving Session owner compares the identity carried by command 42,
+ * 51 or 54 with its current values exactly (§4).
+ */
+export declare function sessionOwnerFenceMatches(local: ServiceSessionOwnerIdentity, fence: Pick<ServiceRetiredBoundSessionRouteFence, 'sessionOwnerNodeRid' | 'sessionOwnerNodeGeneration' | 'sessionOwnerId' | 'sessionOwnerLeaseGeneration'>): boolean;
 export interface ServiceSessionDelivery {
     readonly binding: ServiceSessionBinding;
     /**
@@ -74,6 +106,7 @@ export interface ServiceSessionDelivery {
      * been validated. The stream adapter owns multipart decoding at that point.
      */
     readonly deliver: (sessionRid: string, payloadFrame: Uint8Array) => Promise<boolean>;
+    readonly close?: () => Promise<void>;
     /** Enqueues the replacement lifecycle callback on the owning STREAM session. */
     readonly onBindingReplaced?: (actorId: string, retiredSession: ServiceRetiredBoundSessionRouteFence, actor: ServiceActorRef) => void;
 }
@@ -92,6 +125,7 @@ export interface ServiceInstanceApplicationLifecycle {
     isIdleEvicting?(target: ServiceInstanceApplicationIdentity): boolean;
     beginIdleEviction?(target: ServiceInstanceApplicationIdentity): boolean;
     materialize(target: ServiceInstanceApplicationIdentity, objectGeneration: bigint): Promise<void>;
+    publish?(target: ServiceInstanceApplicationTarget): void;
     discard(target: ServiceInstanceActivationTarget): Promise<void>;
     beginTerminal(target: ServiceInstanceApplicationTarget): void;
     completeTerminal(target: ServiceInstanceApplicationTarget): Promise<boolean>;
@@ -211,9 +245,11 @@ export declare class ServiceStatefulRuntime {
     private asyncInstanceAuthority?;
     private instanceApplicationLifecycle?;
     private userSpotOperationHandler?;
+    private requestSourceAcceptance?;
     private messageFollowHandler?;
     private mailboxDropHandler?;
     private dispatchErrors?;
+    private sessionOwnerDescriptors?;
     private dispatchErrorMeshName?;
     private readonly admittedUserSpotOperations;
     private readonly pendingInstanceActivations;
@@ -223,6 +259,16 @@ export declare class ServiceStatefulRuntime {
         readonly kind: 'spot_multicast' | 'actor_control' | 'actor_binding';
         readonly owner: string;
     }) => void): void;
+    setSessionOwnerDescriptors(source: ServiceSessionOwnerDescriptors): void;
+    /** §4: this host's Session owner identity, taken from its own descriptor. */
+    private localSessionOwner;
+    /**
+     * §4: the identity of the Session owner that requested a bind. It is this
+     * host's own descriptor, or the admitted peer descriptor of that exact
+     * lifecycle that passed the owner lease check. Without one the bind is
+     * rejected instead of storing a guessed identity.
+     */
+    private sessionOwnerOf;
     setDispatchErrorReporter(reporter: ZLinkDispatchErrorReporter, meshName: string): void;
     createSpot(routingId?: string, kind?: 'user' | 'instance', stableType?: "user" | "instance"): ServiceSpotState;
     restoreUserSpotAuthority(spotId: string, stableType: string, generation: bigint, authorityOwnerGeneration: bigint): ServiceSpotState;
@@ -260,9 +306,17 @@ export declare class ServiceStatefulRuntime {
     rememberSpotRoute(route: ServiceDirectSpotRouteFence, expectedCurrentRoute?: ServiceDirectSpotRouteFence | null): void;
     sendMessageFollowNotification(targetNodeRid: string, record: Omit<import('./service-stateful-wire-codec').ServiceMessageFollowRecord, 'kind'>): Promise<boolean>;
     setMessageFollowHandler(handler: (record: import('./service-stateful-wire-codec').ServiceMessageFollowRecord) => void): void;
+    setRequestSourceAcceptance(acceptance: import('../backend/contracts').ZLinkBackendRequestSourceAcceptance): void;
+    /**
+     * Location runtime §9.3: the first accepting owner reads the sender's owner values once. A
+     * sender without a live descriptor ends the request Unavailable (Session·Actor binding §4). The
+     * polled descriptors answer without a promise; only a Store read returns one.
+     */
+    private acceptRequestSource;
+    private recordRequestSource;
     sealSpotMessageFollowIngress(source: ServiceDirectSpotRouteFence): ServiceSpotMessageFollowSeal | undefined;
     abortSpotMessageFollowIngress(seal: ServiceSpotMessageFollowSeal): boolean;
-    commitSpotMessageFollowIngress(seal: ServiceSpotMessageFollowSeal, target: ServiceDirectSpotRouteFence, durationMs: number): Promise<boolean>;
+    commitSpotMessageFollowIngress(seal: ServiceSpotMessageFollowSeal, target: ServiceDirectSpotRouteFence | null, durationMs: number): Promise<boolean>;
     forgetSpotRoute(spot: ServiceSpotRef, authorityOwnerGeneration: bigint, storeVersion?: string): void;
     actor(actorId: string): ServiceActorState | undefined;
     setSubscription(spot: ServiceSpotState, channelName: string, topicFilter: string): void;
@@ -270,21 +324,25 @@ 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;
-    sendToActor(target: ServiceActorRef, _targetNodeGeneration: bigint, _authorityOwnerGeneration: bigint, payload: ServiceApplicationPayload, sourceActor?: ServiceActorRef, boundSession?: {
+    requestToSpot(sourceSpotId: string, requested: ServiceDirectSpotRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, onAdmitted?: () => void): ServiceStatefulPendingOperation;
+    sendToActor(target: ServiceActorRef, payload: ServiceApplicationPayload, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
-    }): Promise<number>;
-    requestToActor(target: ServiceActorRef, _targetNodeGeneration: bigint, _authorityOwnerGeneration: bigint, payload: ServiceApplicationPayload, timeoutMs: number, sourceActor?: ServiceActorRef, boundSession?: {
+    }, routeFence?: ServiceActorRouteFence): Promise<number>;
+    requestToActor(target: ServiceActorRef, payload: ServiceApplicationPayload, timeoutMs: number, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
-    }): ServiceStatefulPendingOperation;
+    }, onAdmitted?: () => void, routeFence?: ServiceActorRouteFence): ServiceStatefulPendingOperation;
+    acceptRelocatedActorTerminal(operation: {
+        readonly high: bigint;
+        readonly low: bigint;
+    }, replyRouteId: bigint, result: ServiceStatefulResult): 'terminalReceived' | 'alreadyTerminal' | undefined;
     sendToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean): Promise<number>;
     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): ServiceStatefulPendingOperation;
+    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): 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;
@@ -292,7 +350,8 @@ export declare class ServiceStatefulRuntime {
     joinActorEntrySpot(actor: ServiceActorRef, targetNodeRid: string, payload: ServiceApplicationPayload | undefined, timeoutMs: number): ServiceStatefulPendingOperation;
     joinActorEntrySpotCanonical(actor: ServiceActorRef, targetNodeRid: string, request: ServiceApplicationPayload, actorFence: ServiceCanonicalActorJoinCandidate['actorFence'], local: ServiceCanonicalActorJoinCandidate['local'], timeoutMs: number): ServiceStatefulPendingOperation;
     leaveActor(actor: ServiceActorRef, expectedMembershipEpoch: bigint, timeoutMs: number): ServiceStatefulPendingOperation;
-    bindSession(sessionRid: string, actor: ServiceActorRef, timeoutMs: number, deliver: ServiceSessionDelivery['deliver'], onBindingReplaced?: ServiceSessionDelivery['onBindingReplaced'], actorAuthority?: StreamSessionActorAuthorityFence): ServiceStatefulPendingOperation;
+    bindSession(sessionRid: string, actor: ServiceActorRef, timeoutMs: number, deliver: ServiceSessionDelivery['deliver'], onBindingReplaced?: ServiceSessionDelivery['onBindingReplaced'], actorAuthority?: StreamSessionActorAuthorityFence, close?: () => Promise<void>): ServiceStatefulPendingOperation;
+    closeBoundSession(actor: ServiceActorRef, expectedBindingGeneration: bigint, timeoutMs: number): ServiceStatefulPendingOperation;
     unbindSession(sessionRid: string, actor: ServiceActorRef, expectedBindingGeneration: bigint, timeoutMs: number): ServiceStatefulPendingOperation;
     sessionBindings(sessionRid: string): readonly ServiceStreamSessionBinding[];
     allSessionBindings(): readonly ServiceSessionBinding[];
@@ -300,7 +359,10 @@ export declare class ServiceStatefulRuntime {
     sendBoundSession(actor: ServiceActorRef, expectedBindingGeneration: bigint, payload: ServiceApplicationPayload): Promise<number>;
     expireOperations(nowMs: number, turnDeadlineMs: number): number;
     get pendingOperationCount(): number;
+    /** The next stateful request expiry, as a lower bound. */
+    nextMaintenanceDeadlineMs(): number;
     close(): void;
+    cancelPendingOperations(reason: unknown): void;
     private ingress;
     private handleIngress;
     private enqueueInstanceSpot;
@@ -327,6 +389,7 @@ export declare class ServiceStatefulRuntime {
     private localReadyInstance;
     private activateMissingInstanceAsync;
     private runMissingInstanceActivation;
+    private runMissingInstanceActivationCore;
     private acceptsLocalMissingInstancePlacement;
     private reconcileReadyInstanceProjection;
     private publishCommittedInstanceRoute;
@@ -336,6 +399,7 @@ export declare class ServiceStatefulRuntime {
     private replyLookup;
     private replyDestroy;
     private replySessionBind;
+    private handleBoundSessionClose;
     /**
      * Handles the replacement notice at the retired session owner.  This path
      * intentionally never calls validateActorFence(): the notice is authorized
@@ -348,6 +412,8 @@ export declare class ServiceStatefulRuntime {
     private enqueueSessionBindingRetirement;
     private deliverBoundSession;
     private traceRejectedBoundSessionSend;
+    private prepareRequestSource;
+    prepareDispatch(record: ServiceMailboxRecord, signal: AbortSignal): boolean | Promise<boolean>;
     private enqueueApplicationFrame;
     private enqueueLifecycleFrame;
     private enqueueFrame;