@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,11 +1,15 @@
+import type { PendingOperation } from './operation-registry';
+import type { RequestRuntime } from './request-runtime';
+import { inspectRuntime } from '../internal-observation';
 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 ActorJoin28 } from '../protocol/service_wire_pilot_codec.generated';
+import type { RawServiceIngressRecord, RawServiceMeshRuntime, RawServicePumpResult } from './raw-service-mesh-runtime';
 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 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 { ServiceStatefulRegistry, ServiceTerminalOperationRegistry, type ServiceActorRef, type ServiceActorState, type ServiceSessionBinding, type ServiceSpotRef, type ServiceSpotState } from './service-stateful-registry';
+import { type ServiceActorCreateRecord, type ServiceActorRouteFence, type ServiceDirectSpotRouteFence, type ServiceInstanceActivationTarget, type ServiceInstanceColdActivationTarget, type ServiceInstanceRouteFence, type ServiceRetiredBoundSessionRouteFence, type ServiceSpotRouteFence, 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;
@@ -14,6 +18,7 @@ export interface ServiceSpotMessageFollowSeal {
 export interface ServiceStatefulResult {
     readonly terminalResult: number;
     readonly failureCode: number;
+    readonly failureMessage?: string;
     readonly payload?: ServiceApplicationPayload;
     readonly kindData?: ReceiveKindData;
     readonly applicationMetadata?: Buffer;
@@ -23,7 +28,7 @@ export interface ServiceStatefulResult {
         readonly authorityOwnerGeneration: bigint;
     };
 }
-export interface ServiceStatefulPendingOperation {
+export interface ServiceStatefulPendingOperation extends PendingOperation<ServiceStatefulResult> {
     readonly id: bigint;
     readonly promise: Promise<ServiceStatefulResult>;
 }
@@ -213,9 +218,39 @@ export declare class ServiceStatefulRuntime {
     private readonly raw;
     readonly nodeRid: string;
     readonly nodeGeneration: bigint;
+    private readonly requests?;
+    [inspectRuntime](): Readonly<{
+        canonicalActorJoinHandoffs: number;
+        spotRoutes: number;
+        instanceRoute: (spotId: string) => Readonly<{
+            targetNodeRid: string;
+            targetNodeGeneration: bigint;
+            targetSpotId: string;
+            objectGeneration: bigint;
+            ownerId: string;
+            authorityOwnerGeneration: bigint;
+            leaseGeneration: bigint;
+            storeVersion: string;
+        }> | undefined;
+        directSpotRoute: (spotId: string) => Readonly<{
+            spot: Readonly<{
+                spotId: string;
+                generation: bigint;
+            }>;
+            ownerLeaseGeneration: bigint;
+            storeVersion: string;
+            targetNodeRid: string;
+            targetNodeGeneration: bigint;
+            authorityOwnerGeneration: bigint;
+        }> | undefined;
+        spotMessageFollow: readonly Readonly<{
+            queuedCount: number;
+            queuedBytes: number;
+        }>[];
+    }>;
     private static readonly detachedIngressScope;
     readonly registry: ServiceStatefulRegistry;
-    private readonly operations;
+    readonly operations: ServiceTerminalOperationRegistry<ServiceStatefulResult, bigint>;
     private readonly sessionDeliveries;
     /**
      * A local Actor owner can replace its own session binding before the
@@ -251,10 +286,15 @@ export declare class ServiceStatefulRuntime {
     private dispatchErrors?;
     private sessionOwnerDescriptors?;
     private dispatchErrorMeshName?;
-    private readonly admittedUserSpotOperations;
+    readonly admittedUserSpotOperations: Map<string, {
+        readonly request: string;
+        readonly replayExpiresAtMs: number;
+        readonly result: Promise<ServiceUserSpotOperationResult>;
+        settled: boolean;
+    }>;
     private readonly pendingInstanceActivations;
     private closed;
-    constructor(raw: RawServiceMeshRuntime, nodeRid: string, nodeGeneration: bigint, onPendingOperationsChanged?: () => void);
+    constructor(raw: RawServiceMeshRuntime, nodeRid: string, nodeGeneration: bigint, onPendingOperationsChanged?: () => void, requests?: RequestRuntime | undefined);
     setMailboxDropHandler(handler: (record: {
         readonly kind: 'spot_multicast' | 'actor_control' | 'actor_binding';
         readonly owner: string;
@@ -324,7 +364,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, onAdmitted?: () => void): ServiceStatefulPendingOperation;
+    requestToSpot(sourceSpotId: string, requested: ServiceDirectSpotRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, onAdmitted?: () => void, requestOperation?: PendingOperation<unknown>, receiver?: import('./operation-registry').OperationObserver<unknown, unknown>): ServiceStatefulPendingOperation;
     sendToActor(target: ServiceActorRef, payload: ServiceApplicationPayload, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
@@ -332,7 +372,7 @@ export declare class ServiceStatefulRuntime {
     requestToActor(target: ServiceActorRef, payload: ServiceApplicationPayload, timeoutMs: number, sourceActor?: ServiceActorRef, boundSession?: {
         readonly sessionRid: string;
         readonly bindingGeneration: bigint;
-    }, onAdmitted?: () => void, routeFence?: ServiceActorRouteFence): ServiceStatefulPendingOperation;
+    }, onAdmitted?: () => void, routeFence?: ServiceActorRouteFence, requestOperation?: PendingOperation<unknown>, receiver?: import('./operation-registry').OperationObserver<unknown, unknown>): ServiceStatefulPendingOperation;
     acceptRelocatedActorTerminal(operation: {
         readonly high: bigint;
         readonly low: bigint;
@@ -340,9 +380,9 @@ export declare class ServiceStatefulRuntime {
     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, 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;
+    requestToInstanceSpot(route: ServiceInstanceRouteFence, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array, instanceIntent?: boolean, onAdmitted?: () => void, requestOperation?: PendingOperation<unknown>, receiver?: import('./operation-registry').OperationObserver<unknown, unknown>): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpot(target: ServiceInstanceColdActivationTarget, payload: ServiceApplicationPayload, timeoutMs: number, sourceSpotId?: string, metadataFrame?: Uint8Array, requestOperation?: PendingOperation<unknown>): ServiceStatefulPendingOperation;
+    requestToMissingInstanceSpotFrame(target: ServiceInstanceColdActivationTarget, payloadFrame: Buffer, deadlineUnixMs: bigint, sourceSpotId?: string, metadataFrame?: Uint8Array, onAdmitted?: () => void, requestOperation?: PendingOperation<unknown>): 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;
@@ -364,31 +404,56 @@ export declare class ServiceStatefulRuntime {
     close(): void;
     cancelPendingOperations(reason: unknown): void;
     private ingress;
-    private handleIngress;
+    handleIngress(ingress: RawServiceIngressRecord, record: ServiceStatefulWireRecord, payloadFrame: Buffer | undefined, metadataFrame?: Buffer, canonicalActorJoin?: ActorJoin28, canonicalActorJoinPayload?: ServiceApplicationPayload): Promise<RawServicePumpResult>;
     private enqueueInstanceSpot;
     private needsInstanceApplicationMaterialization;
-    private enqueueActivatedInstanceSpot;
-    private continueMissingInstanceActivation;
+    enqueueActivatedInstanceSpot(ingress: RawServiceIngressRecord, record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+    }>, payloadFrame: Buffer, spot: Pick<ServiceSpotState, 'ref'>, localReply?: NonNullable<ServiceStatefulMailboxData['reply']>, onTerminalCompletion?: NonNullable<ServiceStatefulMailboxData['onTerminalCompletion']>, metadataFrame?: Buffer, onHandlerTurnStarted?: () => void, applicationTargetOverride?: ServiceInstanceApplicationTarget): RawServicePumpResult;
+    continueMissingInstanceActivation(ingress: RawServiceIngressRecord, record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+        readonly activation: 'missing';
+    }>, payloadFrame: Buffer, localReply?: NonNullable<ServiceStatefulMailboxData['reply']>, metadataFrame?: Buffer): Promise<void>;
     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;
+    activationTerminalCompletion(target: ServiceInstanceActivationTarget, route: ServiceInstanceRouteFence): {
+        readonly onTerminalCompletion: () => Promise<void>;
+        readonly onHandlerTurnStarted: () => void;
+    };
+    instanceApplicationTerminalCompletion(target: ServiceInstanceApplicationTarget): (() => Promise<void>) | undefined;
     private instanceApplicationTarget;
     private beginInstanceAuthorityOperation;
     private completeInstanceAuthorityOperation;
     private completeInstanceApplicationWaitersIfQuiescent;
-    private finishMissingInstanceActivationFailure;
+    finishMissingInstanceActivationFailure(ingress: RawServiceIngressRecord, record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+        readonly activation: 'missing';
+    }>, error: unknown, localReply?: NonNullable<ServiceStatefulMailboxData['reply']>, payloadFrame?: Buffer): void;
     private requireInstanceActivation;
     private requireReadyInstanceApplicationRoute;
-    private validateInstanceIngress;
+    validateInstanceIngress(ingress: RawServiceIngressRecord, record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+    }>): void;
     private activateMissingInstance;
     private localReadyInstance;
-    private activateMissingInstanceAsync;
-    private runMissingInstanceActivation;
+    activateMissingInstanceAsync(record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+        readonly activation: 'missing';
+    }>, payloadFrame: Buffer, metadataFrame: Buffer | undefined, admit: (activation: {
+        readonly spot: Pick<ServiceSpotState, 'ref'>;
+        readonly route: ServiceInstanceRouteFence;
+    }) => void): Promise<unknown>;
+    runMissingInstanceActivation(record: Extract<ServiceStatefulWireRecord, {
+        readonly kind: 'instanceSpot';
+        readonly activation: 'missing';
+    }>, payloadFrame: Buffer, metadataFrame?: Buffer): Promise<{
+        readonly spot: Pick<ServiceSpotState, 'ref'>;
+        readonly route: ServiceInstanceRouteFence;
+    }>;
     private runMissingInstanceActivationCore;
     private acceptsLocalMissingInstancePlacement;
     private reconcileReadyInstanceProjection;
@@ -414,7 +479,7 @@ export declare class ServiceStatefulRuntime {
     private traceRejectedBoundSessionSend;
     private prepareRequestSource;
     prepareDispatch(record: ServiceMailboxRecord, signal: AbortSignal): boolean | Promise<boolean>;
-    private enqueueApplicationFrame;
+    enqueueApplicationFrame(ingress: RawServiceIngressRecord, owner: string, payloadFrame: Buffer, stateful: ServiceStatefulMailboxData): RawServicePumpResult;
     private enqueueLifecycleFrame;
     private enqueueFrame;
     private enqueueLogicalMulticast;
@@ -432,13 +497,13 @@ export declare class ServiceStatefulRuntime {
     private submitOneWay;
     private submitRequest;
     private submitActorJoin;
-    private submitLocalRequest;
+    submitLocalRequest(ingress: RawServiceIngressRecord, pending: ServiceStatefulPendingOperation, operationKind: 'spotRequest' | 'actorRequest' | 'actorLookup' | 'actorDestroy' | 'actorJoin' | 'streamBind' | 'streamUnbind' | 'instanceSpotRequest', actor?: ServiceActorRef, deadlineUnixMs?: bigint, receiver?: import('./operation-registry').OperationObserver<unknown, unknown>): Promise<void>;
     private completeRemoteReply;
     private resultFromReply;
-    private validateActorFence;
-    private validateActorMessageFence;
+    validateActorFence(fence: ServiceActorRouteFence): ServiceActorState;
+    validateActorMessageFence(fence: ServiceActorRouteFence): ServiceActorState;
     private validateSpotFence;
-    private validateDirectSpotFence;
+    validateDirectSpotFence(fence: ServiceSpotRouteFence): ServiceSpotState;
     private holdOrRelaySpotMessage;
     private restoreSpotMessageFollowRecord;
     private drainSpotMessageFollow;