@zlink-systems/framework 0.28.0 → 0.29.1

package/dist/contracts/Configuration/Builders.d.ts

@@ -142,6 +142,8 @@ export interface ZLinkFanoutChannelBuilder {
     subscriberConnections(): ZLinkEndpointConnections;
 }
 export interface ZLinkStreamNodeBuilder {
+    setHeartbeat(intervalMs: number, timeoutMs: number): this;
+    setIdleTimeout(timeoutMs: number): this;
     bind(endpointOrPort?: string | number): this;
     setBindHost(bindHost: string): this;
     setAdvertiseHost(advertiseHost: string): this;

package/dist/contracts/Configuration/InternalDefaults.d.ts

@@ -12,3 +12,6 @@ export declare const ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = 4096;
 export declare const AUTHORITY_ENVELOPE_MAX_BYTES: number;
 export declare const CREATION_INTENT_MAX_BYTES: number;
 export declare const CREATION_TERMINAL_ENVELOPE_MAX_BYTES: number;
+export declare const DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS = 1000;
+export declare const DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS = 5000;
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 0;

package/dist/contracts/Configuration/InternalDefaults.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CREATION_TERMINAL_ENVELOPE_MAX_BYTES = exports.CREATION_INTENT_MAX_BYTES = exports.AUTHORITY_ENVELOPE_MAX_BYTES = exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = exports.DEFAULT_WORKER_IDLE_TIMEOUT_MS = exports.DEFAULT_WORKER_MIN_THREADS = exports.DEFAULT_ACTIVATION_CONCURRENCY_LIMIT = exports.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = exports.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE = void 0;
+exports.DEFAULT_STREAM_IDLE_TIMEOUT_MS = exports.DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS = exports.DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS = exports.CREATION_TERMINAL_ENVELOPE_MAX_BYTES = exports.CREATION_INTENT_MAX_BYTES = exports.AUTHORITY_ENVELOPE_MAX_BYTES = exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = exports.DEFAULT_WORKER_IDLE_TIMEOUT_MS = exports.DEFAULT_WORKER_MIN_THREADS = exports.DEFAULT_ACTIVATION_CONCURRENCY_LIMIT = exports.RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = exports.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE = void 0;
 exports.defaultWorkerMaxThreads = defaultWorkerMaxThreads;
 const os = __importStar(require("node:os"));
 /** Default complete header plus payload size accepted by a StreamNode. */
@@ -52,3 +52,6 @@ exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = 4096;
 exports.AUTHORITY_ENVELOPE_MAX_BYTES = 1024 * 1024;
 exports.CREATION_INTENT_MAX_BYTES = 1024 * 1024;
 exports.CREATION_TERMINAL_ENVELOPE_MAX_BYTES = 1024 * 1024;
+exports.DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS = 1_000;
+exports.DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
+exports.DEFAULT_STREAM_IDLE_TIMEOUT_MS = 0;

package/dist/contracts/Configuration/RegistrationBuilders.js

@@ -522,6 +522,15 @@ class DefaultClientServerChannelServerBuilder {
 }
 class DefaultStreamNodeBuilder {
     streamNode;
+    setHeartbeat(intervalMs, timeoutMs) {
+        this.streamNode.heartbeatIntervalMs = intervalMs;
+        this.streamNode.heartbeatTimeoutMs = timeoutMs;
+        return this;
+    }
+    setIdleTimeout(timeoutMs) {
+        this.streamNode.idleTimeoutMs = timeoutMs;
+        return this;
+    }
     constructor(streamNode) {
         this.streamNode = streamNode;
     }

package/dist/contracts/Configuration/RegistrationNormalizers.d.ts

@@ -4,6 +4,7 @@ import type { ZLinkNetworkOptions } from './Builders';
 export declare function normalizeWorkerOptions(value: ZLinkFrameworkRegistrationOptions['worker']): ZLinkWorkerOptions | undefined;
 export declare function normalizeNetworkOptions(value: ZLinkFrameworkRegistrationOptions['network']): ZLinkNetworkOptions;
 export declare function toChannelMap(channels: ZLinkFrameworkRegistrationOptions['channels'], network: ZLinkNetworkOptions): Map<string, ZLinkChannelOptions>;
+export declare function normalizeStreamLiveness(options: ZLinkStreamNodeOptions): Required<Pick<ZLinkStreamNodeOptions, 'heartbeatIntervalMs' | 'heartbeatTimeoutMs' | 'idleTimeoutMs'>>;
 export declare function toStreamNodeMap(streamNodes: ZLinkFrameworkRegistrationOptions['streamNodes'], network: ZLinkNetworkOptions): Map<string, ZLinkStreamNodeOptions>;
 export declare function toRouteChannelOptions(options: ZLinkFrameworkRegistrationOptions): Map<string, ZLinkRouteChannelOptions>;
 export declare function requirePositiveInteger(label: string, value: number | undefined): void;

package/dist/contracts/Configuration/RegistrationNormalizers.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeWorkerOptions = normalizeWorkerOptions;
 exports.normalizeNetworkOptions = normalizeNetworkOptions;
 exports.toChannelMap = toChannelMap;
+exports.normalizeStreamLiveness = normalizeStreamLiveness;
 exports.toStreamNodeMap = toStreamNodeMap;
 exports.toRouteChannelOptions = toRouteChannelOptions;
 exports.requirePositiveInteger = requirePositiveInteger;
@@ -60,6 +61,20 @@ function toChannelMap(channels, network) {
         ];
     }));
 }
+function normalizeStreamLiveness(options) {
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? InternalDefaults_1.DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS;
+    const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? InternalDefaults_1.DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS;
+    const idleTimeoutMs = options.idleTimeoutMs ?? InternalDefaults_1.DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+    if (!Number.isFinite(heartbeatIntervalMs) || heartbeatIntervalMs <= 0)
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM heartbeat interval must be positive.');
+    if (!Number.isFinite(heartbeatTimeoutMs) || heartbeatTimeoutMs <= 0)
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM heartbeat timeout must be positive.');
+    if (heartbeatTimeoutMs <= heartbeatIntervalMs)
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM heartbeat timeout must be greater than interval.');
+    if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 0)
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM idle timeout must not be negative.');
+    return { heartbeatIntervalMs, heartbeatTimeoutMs, idleTimeoutMs };
+}
 function toStreamNodeMap(streamNodes, network) {
     return new Map(Object.entries(streamNodes ?? {}).map(([name, streamNode]) => {
         const normalized = normalizeListener(streamNode, network);
@@ -67,6 +82,7 @@ function toStreamNodeMap(streamNodes, network) {
             name,
             {
                 ...normalized,
+                ...normalizeStreamLiveness(streamNode),
                 maxMessageSize: streamNode.maxMessageSize ?? InternalDefaults_1.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE
             }
         ];

package/dist/contracts/Configuration/RegistrationTypes.d.ts

@@ -201,6 +201,9 @@ export interface ZLinkRouteChannelOptions {
     readonly handlers?: readonly ZLinkRouteChannelHandlerOptions[];
 }
 export interface ZLinkStreamNodeOptions {
+    readonly heartbeatIntervalMs?: number;
+    readonly heartbeatTimeoutMs?: number;
+    readonly idleTimeoutMs?: number;
     readonly bind?: string;
     readonly bindHost?: string;
     readonly advertiseHost?: string;

package/dist/runtime/actors/actor-mailbox.d.ts

@@ -1,9 +1,9 @@
-import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+import { ZLinkSerialExecutionQueue, type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
 export declare class ZLinkActorSerialExecutor {
     private readonly actorId;
     private readonly sourceSpotId;
     private readonly scheduler;
-    constructor(actorId: string, sourceSpotId: unknown, options?: ZLinkSerialSchedulerOptions);
+    constructor(actorId: string, sourceSpotId: unknown, options?: ZLinkSerialSchedulerOptions, sharedOwner?: ZLinkSerialExecutionQueue);
     execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
     close(): Promise<void>;
     private runRecord;

package/dist/runtime/actors/actor-mailbox.js

@@ -8,10 +8,10 @@ class ZLinkActorSerialExecutor {
     actorId;
     sourceSpotId;
     scheduler;
-    constructor(actorId, sourceSpotId, options) {
+    constructor(actorId, sourceSpotId, options, sharedOwner) {
         this.actorId = actorId;
         this.sourceSpotId = sourceSpotId;
-        this.scheduler = new serial_execution_queue_1.ZLinkSerialExecutionQueue((record) => this.runRecord(record), options);
+        this.scheduler = new serial_execution_queue_1.ZLinkSerialExecutionQueue((record) => this.runRecord(record), options, sharedOwner);
     }
     execute(operation, workOptions) {
         const boundOperation = (0, application_job_queue_scope_1.bindApplicationJobPermit)(() => (0, actor_execution_context_1.runZLinkActorExecution)(this.actorId, this.sourceSpotId, operation));

package/dist/runtime/actors/actor-runtime-contracts.d.ts

@@ -27,6 +27,7 @@ export interface ZLinkActorManagerOptions {
     readonly actorRefResolver?: ZLinkActorRuntimeLocationLookup;
     readonly actorCreatedNotifier?: (nodeRid: RoutingId, actor: ZLinkActor, createRequest: ZLinkMessage, signal?: AbortSignal) => Promise<ZLinkActorCreateResponse | undefined>;
     readonly actorDestroyedCleanup?: (actorId: string) => void;
+    readonly terminateActorActivation?: (actor: ZLinkActor, terminal: () => Promise<void>) => Promise<void>;
     readonly publishActorAuthority?: (actorType: string, actorRef: ActorRef, ownerNodeGeneration: bigint, signal?: AbortSignal) => Promise<void>;
     readonly locationLifecycle?: ZLinkLocationLifecycle;
     readonly boundSessionFactory?: ZLinkActorBoundSessionFactory;

package/dist/runtime/actors/index.d.ts

@@ -55,6 +55,8 @@ export declare class DefaultZLinkActorManager implements ZLinkActorManager {
     completeCoreRelocationSource(actorId: string): Promise<void>;
     private finalizeActorState;
     private finalizeDestroyedActor;
+    private terminateActor;
+    private awaitActorDestroy;
     getOrCreateActor(actorId: string, actorType: string, signal?: AbortSignal): Promise<ZLinkActor>;
     getOrCreateWithNativeRef(actorId: string, actorType: string, actorRef: ZLinkBackendActorRef, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActor>;
     getOrCreateActorResult(actorId: string, actorType: string, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActorLocalCreateResult>;

package/dist/runtime/actors/index.js

@@ -11,6 +11,7 @@ const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 const execution_1 = require("../execution");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const actor_execution_context_1 = require("./actor-execution-context");
 const payload_codec_1 = require("../messaging/payload-codec");
 const actor_creation_1 = require("./actor-creation");
 const actor_runtime_state_1 = require("./actor-runtime-state");
@@ -139,7 +140,7 @@ class DefaultZLinkActorManager {
         const entryNodeRid = state.entryNodeRid ?? current.nodeRid;
         if (node === undefined || completions === undefined)
             return false;
-        const destroyTask = state.getOrStartDestroy(entryNodeRid, async (nativeRef) => {
+        const destroyTask = state.getOrStartDestroy(entryNodeRid, (nativeRef) => this.terminateActor(state, async () => {
             if (nativeRef !== undefined) {
                 const completion = await completions.submit(() => node.destroyActor(nativeRef, 0), signal);
                 try {
@@ -161,9 +162,9 @@ class DefaultZLinkActorManager {
                 await this.options.locationLifecycle?.releaseActor(state.actorType, actor.actorId, current);
             }
             await this.finalizeDestroyedActor(actor.actorId, state);
-        });
+        }));
         try {
-            await destroyTask;
+            await this.awaitActorDestroy(state, destroyTask);
         }
         catch (error) {
             state.clearFailedDestroy(destroyTask);
@@ -381,6 +382,20 @@ class DefaultZLinkActorManager {
             this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.ActorCount, -1);
         }
     }
+    terminateActor(state, terminal) {
+        const actor = state.actor;
+        const completion = actor === undefined || this.options.terminateActorActivation === undefined
+            ? terminal()
+            : this.options.terminateActorActivation(actor, terminal);
+        return completion;
+    }
+    awaitActorDestroy(state, completion) {
+        if ((0, actor_execution_context_1.currentZLinkActorExecution)()?.actorId === state.actorId) {
+            this.detachedTaskRunner.runDetached('Actor terminal cleanup', () => completion);
+            return Promise.resolve();
+        }
+        return completion;
+    }
     async getOrCreateActor(actorId, actorType, signal) {
         this.rememberActorMeshFromType(actorId, actorType);
         const result = await this.createOrGet(actorId, actorType, false, undefined, signal);
@@ -429,7 +444,7 @@ class DefaultZLinkActorManager {
         if (state.isJoined) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.context.actorId}' must leave its current SPOT before destroy.`);
         }
-        const destroyTask = state.getOrStartDestroy(entryNodeRid, async (actorRef) => {
+        const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) => this.terminateActor(state, async () => {
             const destroyedActorRef = actorRef === undefined ? undefined : (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, state.meshName ?? '');
             if (actorRef !== undefined) {
                 await node.destroyActor(actorRef, 0, destroySignal);
@@ -439,9 +454,9 @@ class DefaultZLinkActorManager {
                 await this.options.locationLifecycle?.releaseActor(state.actorType, actor.context.actorId, destroyedActorRef);
             }
             await this.finalizeDestroyedActor(actor.context.actorId, state);
-        });
+        }));
         try {
-            await destroyTask;
+            await this.awaitActorDestroy(state, destroyTask);
         }
         catch (error) {
             state.clearFailedDestroy(destroyTask);

package/dist/runtime/backend/node/node-raw-mesh-backend.js

@@ -147,12 +147,10 @@ class ZLinkNodeRawMeshBackend {
     selectObjectPlacement(stableType) {
         const runtime = this.requireRuntime();
         const localNodeRid = runtime.topology.localDescriptor().nodeRoutingId;
-        const status = runtime.topology.objectPlacementStatus(stableType, (candidate) => candidate.nodeRoutingId === localNodeRid ||
+        const { status, descriptor } = runtime.topology.selectObjectPlacementWithStatus(stableType, (candidate) => candidate.nodeRoutingId === localNodeRid ||
             runtime.isPeerRouteReady(candidate.nodeRoutingId));
         if (status !== 'available')
             return { kind: status };
-        const descriptor = runtime.topology.selectObjectPlacement(stableType, (candidate) => candidate.nodeRoutingId === localNodeRid ||
-            runtime.isPeerRouteReady(candidate.nodeRoutingId));
         return descriptor === undefined
             ? { kind: 'unavailable' }
             : {

package/dist/runtime/execution/serial-execution-queue.d.ts

@@ -36,20 +36,23 @@ export interface ZLinkSerialWorkPreparation {
  */
 export declare class ZLinkSerialExecutionQueue {
     private readonly executeRecord;
+    private readonly sharedOwner?;
     private readonly application;
     private readonly lifecycle;
     private activeLifecycle?;
+    private activeRecord?;
+    /** The admitted node itself owns ready membership; no second readiness flag. */
+    private ownerMembership?;
     private readonly ownerTimeBudget;
     private readonly lifecycleBurstLimit;
     private nextAcceptedSequence;
-    private draining;
-    private drainScheduled;
+    private readonly consumer?;
     private lifecycleStreak;
     private lifecycleDebt;
     private claimStartedAt?;
     private closed;
     private readonly idleWaiters;
-    constructor(executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>, options?: ZLinkSerialSchedulerOptions);
+    constructor(executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>, options?: ZLinkSerialSchedulerOptions, sharedOwner?: ZLinkSerialExecutionQueue | undefined);
     submit<T>(operation: () => Promise<T> | T, options?: ZLinkSerialWorkOptions, context?: unknown): Promise<T>;
     submitDetached<T>(operation: () => Promise<T> | T, onError: (error: unknown) => void, options?: ZLinkSerialWorkOptions, context?: unknown): void;
     /**
@@ -73,7 +76,13 @@ export declare class ZLinkSerialExecutionQueue {
     get admissionClosed(): boolean;
     private admit;
     private scheduleDrain;
+    /** Notifications carry no payload, admission sequence, result Promise, or host permit. */
+    private enqueueMailboxTurn;
+    /** Called only by the shared scheduler's consumer, never by a producer. */
+    private consumeMailbox;
+    private finishMailbox;
     private drain;
+    private prepareSelected;
     private selectNext;
     private takeSelected;
     private takeLifecycle;

package/dist/runtime/execution/serial-execution-queue.js

@@ -13,21 +13,25 @@ exports.ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS = Object.freeze({
  */
 class ZLinkSerialExecutionQueue {
     executeRecord;
+    sharedOwner;
     application;
     lifecycle;
     activeLifecycle;
+    activeRecord;
+    /** The admitted node itself owns ready membership; no second readiness flag. */
+    ownerMembership;
     ownerTimeBudget;
     lifecycleBurstLimit;
     nextAcceptedSequence = 1n;
-    draining = false;
-    drainScheduled = false;
+    consumer;
     lifecycleStreak = 0;
     lifecycleDebt = false;
     claimStartedAt;
     closed = false;
     idleWaiters = [];
-    constructor(executeRecord, options = {}) {
+    constructor(executeRecord, options = {}, sharedOwner) {
         this.executeRecord = executeRecord;
+        this.sharedOwner = sharedOwner;
         const configured = { ...exports.ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS, ...options };
         validateNonNegative(configured.ownerTimeBudget, 'ownerTimeBudget');
         validatePositive(configured.lifecycleBurstLimit, 'lifecycleBurstLimit');
@@ -35,6 +39,8 @@ class ZLinkSerialExecutionQueue {
         this.lifecycle = createLane();
         this.ownerTimeBudget = configured.ownerTimeBudget;
         this.lifecycleBurstLimit = configured.lifecycleBurstLimit;
+        if (sharedOwner === undefined)
+            this.consumer = { running: false, scheduled: false };
     }
     submit(operation, options = {}, context) {
         try {
@@ -79,11 +85,14 @@ class ZLinkSerialExecutionQueue {
         return this.admit(operation, { lane: 'lifecycle' }, context, undefined, true);
     }
     visitPendingApplication(visitor) {
-        for (const record of this.application.records)
-            visitor(record);
+        for (const record of this.application.records) {
+            if (record.mailbox === undefined)
+                visitor(record);
+        }
     }
     get hasPendingWork() {
-        return (this.draining ||
+        return (this.consumer?.running === true ||
+            this.activeRecord !== undefined ||
             this.activeLifecycle !== undefined ||
             this.application.records.length > 0 ||
             this.lifecycle.records.length > 0);
@@ -127,7 +136,7 @@ class ZLinkSerialExecutionQueue {
                 if (this.application.records.length > 0 || this.lifecycle.records.length > 0) {
                     this.scheduleDrain();
                 }
-                else if (!this.draining) {
+                else if (this.consumer?.running !== true) {
                     this.resolveIdleWaiters();
                 }
             }
@@ -176,18 +185,90 @@ class ZLinkSerialExecutionQueue {
         return result;
     }
     scheduleDrain() {
-        if (this.drainScheduled || this.draining)
+        if (this.sharedOwner !== undefined) {
+            if (this.activeRecord !== undefined)
+                return;
+            // Ready membership in the existing owner queue is the only notification state.
+            if (this.ownerMembership !== undefined)
+                return;
+            this.enqueueMailboxTurn(() => this.consumeMailbox());
+            return;
+        }
+        const consumer = this.consumer;
+        if (consumer.scheduled || consumer.running)
             return;
-        this.drainScheduled = true;
+        consumer.scheduled = true;
         queueMicrotask(() => {
-            this.drainScheduled = false;
+            consumer.scheduled = false;
             void this.drain();
         });
     }
+    /** Notifications carry no payload, admission sequence, result Promise, or host permit. */
+    enqueueMailboxTurn(operation) {
+        const entry = {
+            acceptedSequence: 0n,
+            lane: 'application',
+            mailbox: this,
+            operation,
+            operationEnvelope: false,
+            preparationState: 'ready',
+            resolve: unexpectedMailboxSettlement,
+            reject: unexpectedMailboxSettlement,
+            release: unexpectedMailboxSettlement,
+            fail: unexpectedMailboxSettlement
+        };
+        const owner = this.sharedOwner;
+        owner.application.records.push(entry);
+        this.ownerMembership = entry;
+        owner.scheduleDrain();
+    }
+    /** Called only by the shared scheduler's consumer, never by a producer. */
+    consumeMailbox() {
+        const selection = this.selectNext();
+        if (selection === undefined) {
+            if (!this.hasPendingWork)
+                this.resolveIdleWaiters();
+            return;
+        }
+        const record = selection.record;
+        if (!this.prepareSelected(selection))
+            return;
+        this.takeSelected(selection);
+        if (record.preparationState === 'failed') {
+            record.preparation?.cancel();
+            record.fail(record.preparationError);
+            this.scheduleDrain();
+            return;
+        }
+        this.activeRecord = record;
+        // The operation can submit Spot turns, including Yield continuations. Its
+        // Actor claim remains held until terminal settlement returns to this gate.
+        let terminal;
+        try {
+            terminal = Promise.resolve(record.operation());
+        }
+        catch (error) {
+            terminal = Promise.reject(error);
+        }
+        void terminal.then((value) => this.finishMailbox(record, () => record.resolve(value)), (error) => this.finishMailbox(record, () => record.reject(error)));
+    }
+    finishMailbox(record, settle) {
+        this.enqueueMailboxTurn(() => {
+            settle();
+            record.release();
+            record.preparation?.cancel();
+            this.activeRecord = undefined;
+            if (this.selectNext() !== undefined)
+                this.scheduleDrain();
+            else if (!this.hasPendingWork)
+                this.resolveIdleWaiters();
+        });
+    }
     async drain() {
-        if (this.draining)
+        const consumer = this.consumer;
+        if (consumer.running)
             return;
-        this.draining = true;
+        consumer.running = true;
         let waitingForPreparation = false;
         try {
             for (;;) {
@@ -195,20 +276,7 @@ class ZLinkSerialExecutionQueue {
                 if (selection === undefined)
                     break;
                 const record = selection.record;
-                if (selection.lane === 'lifecycle') {
-                    const applicationHead = this.application.records[0];
-                    if (this.application.records.length > 0 &&
-                        !this.cancelPreparationForRearbitration(applicationHead)) {
-                        waitingForPreparation = true;
-                        break;
-                    }
-                }
-                if (record.preparationState === 'idle') {
-                    this.startPreparation(record);
-                    waitingForPreparation = true;
-                    break;
-                }
-                if (record.preparationState === 'pending' || record.preparationState === 'canceling') {
+                if (!this.prepareSelected(selection)) {
                     waitingForPreparation = true;
                     break;
                 }
@@ -220,7 +288,10 @@ class ZLinkSerialExecutionQueue {
                 }
                 this.claimStartedAt ??= performance.now();
                 try {
-                    if (record.operationEnvelope) {
+                    if (record.mailbox !== undefined) {
+                        record.operation();
+                    }
+                    else if (record.operationEnvelope) {
                         try {
                             const outcome = record.operation();
                             void Promise.resolve(outcome).then((value) => {
@@ -240,6 +311,8 @@ class ZLinkSerialExecutionQueue {
                     }
                 }
                 catch (error) {
+                    if (record.mailbox !== undefined)
+                        throw error;
                     record.fail(error);
                 }
                 finally {
@@ -252,7 +325,7 @@ class ZLinkSerialExecutionQueue {
             }
         }
         finally {
-            this.draining = false;
+            consumer.running = false;
             this.claimStartedAt = undefined;
             if (!waitingForPreparation && this.selectNext() !== undefined) {
                 this.scheduleDrain();
@@ -264,6 +337,16 @@ class ZLinkSerialExecutionQueue {
             }
         }
     }
+    prepareSelected(selection) {
+        if (selection.lane === 'lifecycle' &&
+            this.application.records.length > 0 &&
+            !this.cancelPreparationForRearbitration(this.application.records[0]))
+            return false;
+        const record = selection.record;
+        if (record.preparationState === 'idle')
+            this.startPreparation(record);
+        return record.preparationState !== 'pending' && record.preparationState !== 'canceling';
+    }
     selectNext() {
         const lifecycleOwner = this.activeLifecycle?.context;
         const applicationRecord = lifecycleOwner === undefined
@@ -291,6 +374,8 @@ class ZLinkSerialExecutionQueue {
         if (record !== selection.record) {
             throw new Error('The selected serial work record changed before owner claim.');
         }
+        if (selection.record.mailbox !== undefined)
+            selection.record.mailbox.ownerMembership = undefined;
         return record;
     }
     takeLifecycle() {
@@ -402,6 +487,9 @@ function createLane() {
         records: []
     };
 }
+function unexpectedMailboxSettlement() {
+    throw new Error('A mailbox notification has no independent terminal result.');
+}
 function validatePositive(value, field) {
     if (!Number.isSafeInteger(value) || value < 1) {
         throw new RangeError(`${field} must be a positive safe integer.`);

package/dist/runtime/foundation/operation-registry.d.ts

@@ -14,7 +14,7 @@ export interface PendingOperation<T> {
     readonly promise: Promise<T>;
 }
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
-export declare class OperationRegistry<T> {
+export declare class OperationRegistry<T, Context = unknown> {
     private readonly clock;
     private readonly onPendingChanged?;
     private readonly entries;
@@ -22,11 +22,12 @@ export declare class OperationRegistry<T> {
     private deadlineCursor?;
     private closed;
     constructor(clock?: OperationClock, onPendingChanged?: (() => void) | undefined);
-    register(timeoutMs: number, timeoutOwner?: 'registry' | 'sender'): PendingOperation<T>;
+    register(timeoutMs: number, timeoutOwner?: 'registry' | 'sender', context?: Context): PendingOperation<T>;
     complete(id: bigint, value: T): boolean;
     fail(id: bigint, reason: unknown): boolean;
     cancel(id: bigint, message?: string): boolean;
     isPending(id: bigint): boolean;
+    context(id: bigint): Context | undefined;
     close(reason?: string): void;
     get size(): number;
     expire(nowMs: number, turnDeadlineMs: number): number;

package/dist/runtime/foundation/operation-registry.js

@@ -34,7 +34,7 @@ class OperationRegistry {
         this.clock = clock;
         this.onPendingChanged = onPendingChanged;
     }
-    register(timeoutMs, timeoutOwner = 'registry') {
+    register(timeoutMs, timeoutOwner = 'registry', context) {
         if (this.closed)
             throw new Error('Operation registry is closed.');
         if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -48,6 +48,7 @@ class OperationRegistry {
             reject = onReject;
         });
         const entry = {
+            context,
             deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
             resolve,
             reject
@@ -77,6 +78,9 @@ class OperationRegistry {
     isPending(id) {
         return this.entries.has(id);
     }
+    context(id) {
+        return this.entries.get(id)?.context;
+    }
     close(reason = 'Operation registry closed.') {
         if (this.closed)
             return;

package/dist/runtime/foundation/service-authority-payload-codec.d.ts

@@ -42,8 +42,6 @@ export interface ServiceUserSpotAuthorityPayload {
     readonly ownerNodeRid: string;
     readonly ownerNodeGeneration: bigint;
 }
-/** Replaces only authority-relocation-state and preserves the canonical owner payload. */
-export declare function replaceServiceAuthorityRelocationState(payload: Uint8Array, relocationState: Uint8Array): Buffer;
 export declare function encodeServiceUserSpotAuthorityPayload(value: ServiceUserSpotAuthorityPayload): Buffer;
 export declare function encodeServiceInstanceAuthorityPayload(value: ServiceInstanceAuthorityPayload): Buffer;
 export declare function decodeServiceReadySpotAuthority(payload: Uint8Array): ServiceReadySpotAuthority | undefined;

package/dist/runtime/foundation/service-authority-payload-codec.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.replaceServiceAuthorityRelocationState = replaceServiceAuthorityRelocationState;
 exports.encodeServiceUserSpotAuthorityPayload = encodeServiceUserSpotAuthorityPayload;
 exports.encodeServiceInstanceAuthorityPayload = encodeServiceInstanceAuthorityPayload;
 exports.decodeServiceReadySpotAuthority = decodeServiceReadySpotAuthority;
@@ -21,48 +20,6 @@ const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_FORMAT_VERSION = 1;
 const AUTHORITY_FLAGS = 0;
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
-/** Replaces only authority-relocation-state and preserves the canonical owner payload. */
-function replaceServiceAuthorityRelocationState(payload, relocationState) {
-    const bytes = Buffer.from(payload);
-    const reader = new AuthorityReader(bytes);
-    reader.expect(AUTHORITY_MAGIC);
-    if (reader.u8() !== AUTHORITY_FORMAT_VERSION || reader.u16() !== AUTHORITY_FLAGS) {
-        throw new TypeError('Authority payload header is invalid.');
-    }
-    const bodyLength = reader.u32();
-    const body = reader.takeReader(bodyLength);
-    const checksumOffset = reader.offset;
-    const checksum = reader.u32();
-    if (!reader.done || (0, service_relocation_runtime_1.crc32c)(bytes.subarray(0, checksumOffset)) !== checksum) {
-        throw new TypeError('Authority payload checksum is invalid.');
-    }
-    body.u8();
-    body.u8();
-    body.skip(body.u16());
-    body.text8();
-    body.nonZeroU64();
-    body.text8();
-    body.rid();
-    body.nonZeroU64();
-    const relocationOffset = body.offset;
-    body.bool8();
-    body.skip(body.u32());
-    const relocationEnd = body.offset;
-    const currentBody = bytes.subarray(11, 11 + bodyLength);
-    const nextBody = Buffer.concat([
-        currentBody.subarray(0, relocationOffset),
-        Buffer.from(relocationState),
-        currentBody.subarray(relocationEnd)
-    ]);
-    const envelope = Buffer.concat([
-        AUTHORITY_MAGIC,
-        Buffer.of(AUTHORITY_FORMAT_VERSION),
-        u16(AUTHORITY_FLAGS),
-        u32(nextBody.byteLength),
-        nextBody
-    ]);
-    return Buffer.concat([envelope, u32((0, service_relocation_runtime_1.crc32c)(envelope))]);
-}
 function encodeServiceUserSpotAuthorityPayload(value) {
     const spot = conditional(2, concat(rid(value.spotId, 'spotId'), text8(value.stableType, 'stableType'), Buffer.of(1)));
     const object = conditional(2, spot);