@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceTerminalOperationRegistry = exports.ServiceStatefulRegistry = exports.ServiceStaleGenerationError = void 0;
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const operation_registry_1 = require("./operation-registry");
 class ServiceStaleGenerationError extends Error {
     objectKind;
@@ -184,6 +185,7 @@ class ServiceStatefulRegistry {
         this.actorGenerations.set(actor.actorId, max(this.actorGenerations.get(actor.actorId) ?? 0n, actor.generation));
         this.actorTypes.set(actor.actorId, stableType);
         this.actors.set(actor.actorId, restored);
+        this.updateBindingMembership(restored);
         return restored;
     }
     actor(actorId) {
@@ -443,6 +445,12 @@ class ServiceTerminalOperationRegistry {
     isPending(id) {
         return this.operations.isPending(id);
     }
+    get size() {
+        return this.operations.size;
+    }
+    expire(nowMs, turnDeadlineMs) {
+        return this.operations.expire(nowMs, turnDeadlineMs);
+    }
     close() {
         this.operations.close('Stateful runtime closed.');
     }
@@ -453,8 +461,8 @@ function actorKey(actor) {
 }
 function requireText(value, name) {
     const bytes = Buffer.byteLength(value);
-    if (bytes < 1 || bytes > 255 || value.includes('\0')) {
-        throw new RangeError(`${name} must be 1..255 UTF-8 bytes without NUL.`);
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_IDENTITY_TEXT_BYTES || value.includes('\0')) {
+        throw new RangeError(`${name} must be 1..${CoreTypes_1.ZLINK_MAX_IDENTITY_TEXT_BYTES} UTF-8 bytes without NUL.`);
     }
 }
 function requirePositive(value, name) {

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

@@ -1,13 +1,12 @@
+import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
 import type { ZLinkDispatchErrorReporter } from '../channels/dispatch-error-reporter';
 import type { RawServiceMeshRuntime } from './raw-service-mesh-runtime';
-import { type ReceiveKindData, type StreamSessionActorAuthorityFence } from './service-runtime-contracts';
+import type { ServiceInstanceActivationRecoveryEnvelope } from './service-instance-activation-recovery-codec';
 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 ServiceActorRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceActorCreateRecord, type ServiceInstanceActivationTarget, type ServiceInstanceRouteFence, type ServiceDirectSpotRouteFence, type ServiceStatefulReplyTail, type ServiceUserSpotCloseRecord, type ServiceUserSpotCreateRecord } from './service-stateful-wire-codec';
+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 ServiceApplicationPayload } from './service-wire-m6a-codec';
-import type { ServiceInstanceActivationRecoveryEnvelope } from './service-instance-activation-recovery-codec';
-import type { ServiceSessionBindingIngressPort } from './service-session-binding-ingress-port';
-import { ZLinkFrameworkRuntimeState } from '../../contracts/Locations';
 export interface ServiceSpotMessageFollowSeal {
     readonly key: string;
     readonly serial: bigint;
@@ -46,7 +45,11 @@ export interface ServiceStatefulMailboxData {
     readonly isPending?: () => boolean;
     /** Carries the local operation deadline into the lifecycle dispatch lane. */
     readonly deadlineUnixMs?: bigint;
+    readonly activationRecord?: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+    }>;
     readonly onTerminalCompletion?: () => void | Promise<void>;
+    readonly onHandlerTurnStarted?: () => void;
     /** Decoded only by the canonical command-28 generator path. */
     readonly canonicalApplicationPayload?: ServiceApplicationPayload;
     readonly reply?: (terminalResult: number, failureCode: number, payload?: ServiceApplicationPayload, tail?: ServiceStatefulReplyTail) => boolean;
@@ -66,9 +69,8 @@ export interface ServiceCanonicalActorJoinCandidate {
 }
 export interface ServiceSessionDelivery {
     readonly binding: ServiceSessionBinding;
-    readonly bindingIngress?: ServiceSessionBindingIngressPort;
     /**
-     * Delivers the retained M6A application frame after the binding fence has
+     * Delivers the M6A application frame after the binding fence has
      * been validated. The stream adapter owns multipart decoding at that point.
      */
     readonly deliver: (sessionRid: string, payloadFrame: Uint8Array) => Promise<boolean>;
@@ -87,7 +89,6 @@ export type ServiceInstanceApplicationTarget = ServiceInstanceApplicationIdentit
 export interface ServiceInstanceApplicationLifecycle {
     isMaterialized(target: ServiceInstanceApplicationIdentity): boolean;
     isMaterializing?(target: ServiceInstanceApplicationIdentity): boolean;
-    isClosing?(target: ServiceInstanceApplicationIdentity): boolean;
     isIdleEvicting?(target: ServiceInstanceApplicationIdentity): boolean;
     beginIdleEviction?(target: ServiceInstanceApplicationIdentity): boolean;
     materialize(target: ServiceInstanceApplicationIdentity, objectGeneration: bigint): Promise<void>;
@@ -115,9 +116,11 @@ export type ServiceInstanceAuthorityRead = {
     readonly kind: 'creating';
     readonly objectGeneration: bigint;
     readonly authorityOwnerGeneration: bigint;
+    readonly authority?: ZLinkAuthoritySnapshot;
 } | {
     readonly kind: 'ready';
     readonly route: ServiceInstanceRouteFence;
+    readonly authority?: ZLinkAuthoritySnapshot;
 };
 export type ServiceInstanceAuthorityReserve = {
     readonly kind: 'reserved';
@@ -149,9 +152,9 @@ export interface ServiceInstanceActivationAuthority {
  */
 export interface ServiceAsyncInstanceActivationAuthority {
     read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
-    reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>): Promise<ServiceInstanceAuthorityReserve>;
+    reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>, signal?: AbortSignal): Promise<ServiceInstanceAuthorityReserve>;
     resume(target: ServiceInstanceActivationTarget, pending: ServicePendingInstanceActivation): Promise<ServiceInstanceActivationReservation>;
-    commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState): Promise<{
+    commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState, deadlineUnixMs?: bigint): Promise<{
         readonly kind: 'committed' | 'lost';
         readonly route: ServiceInstanceRouteFence;
     }>;
@@ -197,7 +200,6 @@ export declare class ServiceStatefulRuntime {
     private readonly subscriptions;
     private readonly instanceIntents;
     private readonly admittedInstanceOperations;
-    private readonly pendingInstanceTerminals;
     private readonly pendingInstanceAuthorityTerminals;
     private readonly instanceApplicationWaiters;
     private readonly canonicalActorJoinHandoffs;
@@ -219,17 +221,11 @@ export declare class ServiceStatefulRuntime {
     private messageFollowHandler?;
     private mailboxDropHandler?;
     private dispatchErrors?;
-    private spotAdmissionProvider?;
     private dispatchErrorMeshName?;
     private readonly admittedUserSpotOperations;
     private readonly pendingInstanceActivations;
     private closed;
-    constructor(raw: RawServiceMeshRuntime, nodeRid: string, nodeGeneration: bigint);
-    setSpotAdmissionProvider(provider: {
-        readonly isClosing: (spotId: string) => boolean;
-        readonly runtimeState: () => ZLinkFrameworkRuntimeState;
-        readonly awaitCloseDecision?: (spotId: string) => Promise<void> | undefined;
-    }): void;
+    constructor(raw: RawServiceMeshRuntime, nodeRid: string, nodeGeneration: bigint, onPendingOperationsChanged?: () => void);
     setMailboxDropHandler(handler: (record: {
         readonly kind: 'spot_multicast' | 'actor_control' | 'actor_binding';
         readonly owner: string;
@@ -265,6 +261,7 @@ export declare class ServiceStatefulRuntime {
     private finishRecoveredInstanceActivation;
     recoverPendingInstanceActivation(envelope: ServiceInstanceActivationRecoveryEnvelope, pending: ServicePendingInstanceActivation, expectedCurrentRoute?: ServiceInstanceRouteFence | null): Promise<boolean>;
     completeRecoveredInstanceActivation(target: ServiceInstanceActivationTarget, route: ServiceInstanceRouteFence, expectedCurrentRoute?: ServiceInstanceRouteFence | null): Promise<ServiceInstanceRouteFence | undefined>;
+    /** Resolves once every first terminal record of an activated Instance message is durable. */
     waitForInstanceApplicationQuiescence(spotId: string, signal?: AbortSignal): Promise<void>;
     rememberActorRoute(route: ServiceActorRouteFence): void;
     rememberSpotRoute(route: ServiceDirectSpotRouteFence, expectedCurrentRoute?: ServiceDirectSpotRouteFence | null): void;
@@ -289,10 +286,10 @@ export declare class ServiceStatefulRuntime {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
     }): ServiceStatefulPendingOperation;
-    sendToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, sourceSpotId?: string, metadataFrame?: Uint8Array): Promise<number>;
+    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): ServiceStatefulPendingOperation;
+    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;
     lookupRemoteActor(targetNodeRid: string, actorId: string, timeoutMs: number): ServiceStatefulPendingOperation;
@@ -302,12 +299,14 @@ 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'], bindingIngress?: ServiceSessionBindingIngressPort, actorAuthority?: StreamSessionActorAuthorityFence): ServiceStatefulPendingOperation;
+    bindSession(sessionRid: string, actor: ServiceActorRef, timeoutMs: number, deliver: ServiceSessionDelivery['deliver'], onBindingReplaced?: ServiceSessionDelivery['onBindingReplaced'], actorAuthority?: StreamSessionActorAuthorityFence): ServiceStatefulPendingOperation;
     unbindSession(sessionRid: string, actor: ServiceActorRef, expectedBindingGeneration: bigint, timeoutMs: number): ServiceStatefulPendingOperation;
-    sessionBindings(sessionRid: string): readonly ServiceSessionBinding[];
+    sessionBindings(sessionRid: string): readonly ServiceStreamSessionBinding[];
     allSessionBindings(): readonly ServiceSessionBinding[];
     sendSessionToActor(sessionRid: string, actor: ServiceActorRef, payload: ServiceApplicationPayload): Promise<number>;
     sendBoundSession(actor: ServiceActorRef, expectedBindingGeneration: bigint, payload: ServiceApplicationPayload): Promise<number>;
+    expireOperations(nowMs: number, turnDeadlineMs: number): number;
+    get pendingOperationCount(): number;
     close(): void;
     private ingress;
     private handleIngress;
@@ -316,12 +315,15 @@ export declare class ServiceStatefulRuntime {
     private enqueueActivatedInstanceSpot;
     private continueMissingInstanceActivation;
     private continueReadyInstanceMaterialization;
+    /**
+     * Spot messaging §4 step 12 with §7 step 1: a Close waits for the first terminal
+     * record only of a message whose handler turn started before it; a message queued
+     * behind that Close is not counted, so it cannot hold the Close it follows.
+     */
     private activationTerminalCompletion;
     private instanceApplicationTerminalCompletion;
     private instanceApplicationTarget;
-    private beginInstanceApplicationOperation;
     private beginInstanceAuthorityOperation;
-    private completeInstanceApplicationOperation;
     private completeInstanceAuthorityOperation;
     private completeInstanceApplicationWaitersIfQuiescent;
     private relayMissingInstanceActivation;
@@ -377,7 +379,6 @@ export declare class ServiceStatefulRuntime {
     private validateActorMessageFence;
     private validateSpotFence;
     private validateDirectSpotFence;
-    private requireDirectSpotAdmission;
     private holdOrRelaySpotMessage;
     private restoreSpotMessageFollowRecord;
     private drainSpotMessageFollow;