@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,9 @@
+export * from './contracts';
+export * from './runtime-message';
+export * from './runtime-values';
+export * from './node/node-dealer-channel-client-transport';
+export * from './mesh-dispatch-pump';
+export * from './mesh-completion-table';
+export * from './mesh-actor-session-node-adapter';
+export * from './mesh-record-dispatcher';
+export * from './node';

package/dist/runtime/backend/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contracts"), exports);
+__exportStar(require("./runtime-message"), exports);
+__exportStar(require("./runtime-values"), exports);
+__exportStar(require("./node/node-dealer-channel-client-transport"), exports);
+__exportStar(require("./mesh-dispatch-pump"), exports);
+__exportStar(require("./mesh-completion-table"), exports);
+__exportStar(require("./mesh-actor-session-node-adapter"), exports);
+__exportStar(require("./mesh-record-dispatcher"), exports);
+__exportStar(require("./node"), exports);

package/dist/runtime/backend/mesh-actor-session-node-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ZLinkBackendActorSessionNode, ZLinkBackendMeshNode } from './contracts';
+import { type ZLinkMeshCompletionTable } from './mesh-completion-table';
+export declare function meshActorSessionNodeAdapter(node: ZLinkBackendMeshNode, completions?: ZLinkMeshCompletionTable): ZLinkBackendActorSessionNode;

package/dist/runtime/backend/mesh-actor-session-node-adapter.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meshActorSessionNodeAdapter = meshActorSessionNodeAdapter;
+const runtime_values_1 = require("./runtime-values");
+const submission_result_1 = require("../messaging/submission-result");
+const mesh_completion_table_1 = require("./mesh-completion-table");
+const routing_id_1 = require("../routing-id");
+function meshActorSessionNodeAdapter(node, completions) {
+    return {
+        actorNodeGeneration(actor) {
+            const status = node.status();
+            return (0, routing_id_1.routingIdsEqual)(status.routingId, actor.nodeRid)
+                ? status.lifecycleGeneration
+                : undefined;
+        },
+        async sendActorBoundSession(actor, expectedBindingGeneration, parts, flags, actorFence) {
+            const result = await node.sendActorBoundSession(actor, expectedBindingGeneration, parts, flags, actorFence);
+            switch (result) {
+                case runtime_values_1.SubmitResult.Ok:
+                    return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+                case runtime_values_1.SubmitResult.Backpressured:
+                case runtime_values_1.SubmitResult.NotAdmitted:
+                    return { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
+                case runtime_values_1.SubmitResult.NotFound:
+                case runtime_values_1.SubmitResult.InvalidState:
+                    return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+                case runtime_values_1.SubmitResult.NotConnected:
+                    return { status: submission_result_1.ZLinkSubmitStatus.RouteNotConnected };
+                case runtime_values_1.SubmitResult.Terminated:
+                    return { status: submission_result_1.ZLinkSubmitStatus.Shutdown };
+                default:
+                    throw new Error(`Actor bound-session send failed with result '${result}'.`);
+            }
+        },
+        async closeActorBoundSession(actor, expectedBindingGeneration, timeoutMs, signal) {
+            if (completions === undefined) {
+                throw new Error('MeshNode completion runtime is not started.');
+            }
+            const completion = await completions.submit(() => node.closeActorBoundSession(actor, expectedBindingGeneration, timeoutMs), signal);
+            try {
+                if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+                    throw new Error(`Actor '${actor.actorId}' bound-session close failed with result ` +
+                        `'${completion.terminalResult}' and errno '${completion.failureErrno}'.`);
+                }
+            }
+            finally {
+                (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+            }
+        }
+    };
+}

package/dist/runtime/backend/mesh-completion-table.d.ts

@@ -0,0 +1,34 @@
+import { ZLinkBufferMessage as Message } from './runtime-message';
+import type { MeshOperationId, ReceiveKindData, ReceiveRecord } from '../foundation/service-runtime-contracts';
+export declare const ZLINK_MESH_COMPLETION_CAPACITY = 4096;
+export interface ZLinkMeshCompletionDiagnostic {
+    readonly kind: 'unknownOrLate';
+    readonly operationId: MeshOperationId;
+    readonly terminalResult: number;
+}
+export interface ZLinkMeshCompletion {
+    readonly terminalResult: number;
+    readonly failureErrno: number;
+    readonly operationKind: number;
+    readonly kindData: ReceiveKindData | null;
+    readonly parts: Message[];
+}
+export declare class ZLinkMeshCompletionTable {
+    private readonly maxPendingOperations;
+    private readonly onDiagnostic?;
+    private readonly pending;
+    private disposed;
+    constructor(maxPendingOperations?: number, onDiagnostic?: ((diagnostic: ZLinkMeshCompletionDiagnostic) => void) | undefined);
+    /**
+     * Submits and registers without yielding control to the event loop. Mesh
+     * completion dispatch is asynchronous, so a completion cannot overtake the
+     * registration. The table therefore does not need to retain responses that
+     * arrived before their waiter.
+     */
+    submit(operation: () => MeshOperationId, signal?: AbortSignal): Promise<ZLinkMeshCompletion>;
+    private isDisposed;
+    complete(record: ReceiveRecord): void;
+    dispose(reason?: unknown): void;
+    get pendingCount(): number;
+}
+export declare function closeMeshCompletion(completion: ZLinkMeshCompletion): void;

package/dist/runtime/backend/mesh-completion-table.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkMeshCompletionTable = exports.ZLINK_MESH_COMPLETION_CAPACITY = void 0;
+exports.closeMeshCompletion = closeMeshCompletion;
+const runtime_message_1 = require("./runtime-message");
+const operation_identity_1 = require("../foundation/operation-identity");
+const contracts_1 = require("../../contracts");
+exports.ZLINK_MESH_COMPLETION_CAPACITY = 4_096;
+class ZLinkMeshCompletionTable {
+    maxPendingOperations;
+    onDiagnostic;
+    pending = new Map();
+    disposed = false;
+    constructor(maxPendingOperations = exports.ZLINK_MESH_COMPLETION_CAPACITY, onDiagnostic) {
+        this.maxPendingOperations = maxPendingOperations;
+        this.onDiagnostic = onDiagnostic;
+        if (!Number.isSafeInteger(maxPendingOperations) || maxPendingOperations <= 0) {
+            throw new RangeError('maxPendingOperations must be a positive safe integer.');
+        }
+    }
+    /**
+     * Submits and registers without yielding control to the event loop. Mesh
+     * completion dispatch is asynchronous, so a completion cannot overtake the
+     * registration. The table therefore does not need to retain responses that
+     * arrived before their waiter.
+     */
+    submit(operation, signal) {
+        if (this.isDisposed()) {
+            return Promise.reject(new Error('Mesh completion table is disposed.'));
+        }
+        if (signal?.aborted === true) {
+            return Promise.reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+        }
+        if (this.pending.size >= this.maxPendingOperations) {
+            return Promise.reject(new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.CapacityExceeded, `Mesh completion capacity ${this.maxPendingOperations} is exhausted.`));
+        }
+        const operationId = operation();
+        // The backend submission callback can synchronously re-enter `dispose()`.
+        // TypeScript's control-flow analysis cannot observe mutation through it.
+        if (this.disposed) {
+            return Promise.reject(new Error('Mesh completion table is disposed.'));
+        }
+        const key = (0, operation_identity_1.operationIdentityKey)(operationId);
+        if (this.pending.has(key)) {
+            return Promise.reject(new Error(`Mesh operation '${key}' is already pending.`));
+        }
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                this.pending.delete(key);
+                reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+            };
+            if (signal?.aborted === true) {
+                abort();
+                return;
+            }
+            signal?.addEventListener('abort', abort, { once: true });
+            this.pending.set(key, {
+                resolve,
+                reject,
+                removeAbort: signal === undefined
+                    ? undefined
+                    : () => signal.removeEventListener('abort', abort)
+            });
+        });
+    }
+    isDisposed() {
+        return this.disposed;
+    }
+    complete(record) {
+        const key = (0, operation_identity_1.operationIdentityKey)(record.operationId);
+        const pending = this.pending.get(key);
+        if (pending === undefined) {
+            this.onDiagnostic?.({
+                kind: 'unknownOrLate',
+                operationId: Object.freeze({ ...record.operationId }),
+                terminalResult: record.terminalResult
+            });
+            return;
+        }
+        this.pending.delete(key);
+        pending.removeAbort?.();
+        try {
+            pending.resolve(copyCompletion(record));
+        }
+        catch (error) {
+            pending.reject(error);
+        }
+    }
+    dispose(reason = new Error('Mesh completion table is disposed.')) {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        const pending = [...this.pending.values()];
+        this.pending.clear();
+        for (const entry of pending) {
+            entry.removeAbort?.();
+        }
+        for (const entry of pending) {
+            entry.reject(reason);
+        }
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+}
+exports.ZLinkMeshCompletionTable = ZLinkMeshCompletionTable;
+function copyCompletion(record) {
+    return {
+        terminalResult: record.terminalResult,
+        failureErrno: record.failureErrno,
+        operationKind: record.operationKind,
+        kindData: record.kindData,
+        parts: record.parts.map((part) => runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(part.data())))
+    };
+}
+function closeMeshCompletion(completion) {
+    closeParts(completion.parts);
+}
+function closeParts(parts) {
+    for (const part of parts) {
+        part.close();
+    }
+}

package/dist/runtime/backend/mesh-dispatch-pump.d.ts

@@ -0,0 +1,48 @@
+import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import type { ZLinkBackendMeshNode } from './contracts';
+import type { ApplicationJobQueuePort } from '../application-jobs/contracts';
+export interface ZLinkMeshDispatchPumpOptions {
+    readonly readyCapacity?: number;
+    readonly messageCapacity?: number;
+    readonly partCapacity?: number;
+    readonly dispatch: (owner: ReadyRecord, record: ReceiveRecord) => void | Promise<void>;
+    readonly applicationJobQueue: ApplicationJobQueuePort;
+    readonly reportError?: (error: unknown, context?: ZLinkMeshDispatchFailureContext) => void;
+    readonly monotonicNowMs?: () => number;
+}
+export interface ZLinkMeshDispatchFailureContext {
+    readonly receiveKind: number;
+    readonly operationKind: number;
+    readonly packetName?: string;
+    readonly sourceNodeRid?: string;
+    readonly commandId?: number;
+}
+export declare class ZLinkMeshDispatchPump {
+    private readonly node;
+    private readonly options;
+    private pendingDomains;
+    private scheduled;
+    private infrastructureScheduled;
+    private disposed;
+    private drainPromise?;
+    private infrastructureDrainPromise?;
+    private readonly activeDrains;
+    private readonly capacityStop;
+    constructor(node: ZLinkBackendMeshNode, options: ZLinkMeshDispatchPumpOptions);
+    start(): void;
+    dispose(): Promise<void>;
+    private schedule;
+    /**
+     * Infrastructure controls must not wait for an application permit. During
+     * source draining an application claim can legitimately remain parked at
+     * `acquirePermit`; sharing that turn would strand Ready/State/Cutover in
+     * the infrastructure mailbox and prevent the relocation coordinator from
+     * completing the drain that releases the application work.
+     */
+    private scheduleInfrastructure;
+    private drain;
+    private drainInfrastructure;
+    private drainDomain;
+    private nowMs;
+    private acquirePermit;
+}

package/dist/runtime/backend/mesh-dispatch-pump.js

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkMeshDispatchPump = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const runtime_values_1 = require("./runtime-values");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const execution_1 = require("../execution");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const MESH_DISPATCH_TIMER_YIELD_BATCHES = 16;
+const MESH_DISPATCH_TIMER_YIELD_INTERVAL_MS = 2;
+const MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET = 4;
+// Captured while the runtime module is loaded, before any application owner
+// exists. A ready callback may run inside a Spot turn; the shared Mesh pump
+// must enter like an independent receive-loop task, without inheriting that
+// owner's AsyncLocalStorage identity.
+const detachedMeshDispatchScope = node_async_hooks_1.AsyncLocalStorage.snapshot();
+class ZLinkMeshDispatchFailure extends Error {
+    context;
+    dispatchCause;
+    constructor(context, dispatchCause) {
+        super('Mesh record dispatch failed.', { cause: dispatchCause });
+        this.context = context;
+        this.dispatchCause = dispatchCause;
+        this.name = 'ZLinkMeshDispatchFailure';
+    }
+}
+class ZLinkMeshDispatchPump {
+    node;
+    options;
+    pendingDomains = service_runtime_contracts_1.ReadyDomain.None;
+    scheduled = false;
+    infrastructureScheduled = false;
+    disposed = false;
+    drainPromise;
+    infrastructureDrainPromise;
+    activeDrains = new Set();
+    capacityStop = new AbortController();
+    constructor(node, options) {
+        this.node = node;
+        this.options = options;
+    }
+    start() {
+        this.node.setReadyHandler((domains) => {
+            if (this.disposed) {
+                return service_runtime_contracts_1.ReadyDomain.None;
+            }
+            this.pendingDomains |= domains;
+            this.schedule();
+            return domains;
+        });
+    }
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.capacityStop.abort();
+        this.pendingDomains = service_runtime_contracts_1.ReadyDomain.None;
+        while (this.activeDrains.size > 0) {
+            await Promise.all([...this.activeDrains]);
+        }
+    }
+    schedule() {
+        if ((this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Infrastructure) !== 0) {
+            this.scheduleInfrastructure();
+        }
+        if ((this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Application) === 0) {
+            return;
+        }
+        if (this.scheduled) {
+            return;
+        }
+        this.scheduled = true;
+        const drain = yieldToEventLoop()
+            .then(() => detachedMeshDispatchScope(() => this.drain()))
+            .catch((error) => {
+            if (error instanceof ZLinkMeshDispatchFailure) {
+                this.options.reportError?.(error.dispatchCause, error.context);
+                return;
+            }
+            this.options.reportError?.(error);
+        });
+        this.activeDrains.add(drain);
+        this.drainPromise = drain;
+        void drain.finally(() => {
+            this.activeDrains.delete(drain);
+            if (this.drainPromise === drain) {
+                this.drainPromise = undefined;
+                this.scheduled = false;
+                if (!this.disposed && this.pendingDomains !== service_runtime_contracts_1.ReadyDomain.None) {
+                    this.schedule();
+                }
+            }
+        });
+    }
+    /**
+     * Infrastructure controls must not wait for an application permit. During
+     * source draining an application claim can legitimately remain parked at
+     * `acquirePermit`; sharing that turn would strand Ready/State/Cutover in
+     * the infrastructure mailbox and prevent the relocation coordinator from
+     * completing the drain that releases the application work.
+     */
+    scheduleInfrastructure() {
+        if (this.infrastructureScheduled) {
+            return;
+        }
+        this.infrastructureScheduled = true;
+        const drain = yieldToEventLoop()
+            .then(() => detachedMeshDispatchScope(() => this.drainInfrastructure()))
+            .catch((error) => {
+            if (error instanceof ZLinkMeshDispatchFailure) {
+                this.options.reportError?.(error.dispatchCause, error.context);
+                return;
+            }
+            this.options.reportError?.(error);
+        });
+        this.activeDrains.add(drain);
+        this.infrastructureDrainPromise = drain;
+        void drain.finally(() => {
+            this.activeDrains.delete(drain);
+            if (this.infrastructureDrainPromise === drain) {
+                this.infrastructureDrainPromise = undefined;
+                this.infrastructureScheduled = false;
+                if (!this.disposed && (this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Infrastructure) !== 0) {
+                    this.scheduleInfrastructure();
+                }
+            }
+        });
+    }
+    async drain() {
+        while (!this.disposed) {
+            if ((this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Application) === 0) {
+                return;
+            }
+            this.pendingDomains &= ~service_runtime_contracts_1.ReadyDomain.Application;
+            await this.drainDomain(service_runtime_contracts_1.ReadyDomain.Application);
+        }
+    }
+    async drainInfrastructure() {
+        while (!this.disposed) {
+            if ((this.pendingDomains & service_runtime_contracts_1.ReadyDomain.Infrastructure) === 0) {
+                return;
+            }
+            this.pendingDomains &= ~service_runtime_contracts_1.ReadyDomain.Infrastructure;
+            const lifecycleBudgetExhausted = await this.drainDomain(service_runtime_contracts_1.ReadyDomain.Infrastructure, MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET);
+            if (lifecycleBudgetExhausted) {
+                this.pendingDomains |= service_runtime_contracts_1.ReadyDomain.Infrastructure;
+            }
+        }
+    }
+    async drainDomain(domain, claimBudget) {
+        const readyCapacity = domain === service_runtime_contracts_1.ReadyDomain.Application
+            ? 1
+            : claimBudget === undefined
+                ? (this.options.readyCapacity ?? 32)
+                : Math.min(this.options.readyCapacity ?? 32, claimBudget);
+        const readyBatch = this.node.createReadyBatch(readyCapacity);
+        // One record per claim receive keeps one ordinary-ingress permit paired
+        // with exactly one dispatch turn. Terminal completion claims bypass it.
+        const receiveBatch = this.node.createReceiveBatch(1, this.options.partCapacity ?? 256);
+        let receiveBatchesSinceTimerYield = 0;
+        let timerYieldStartedAtMs = this.nowMs();
+        let claimsDrained = 0;
+        try {
+            for (;;) {
+                if (claimBudget !== undefined && claimsDrained >= claimBudget) {
+                    // Lifecycle work has priority, but a bounded turn lets application
+                    // work make progress when lifecycle records keep arriving.
+                    return true;
+                }
+                readyBatch.reset();
+                const drained = this.node.drainReady(domain, readyBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
+                if (!drained.ok || drained.records.length === 0) {
+                    return false;
+                }
+                if (domain === service_runtime_contracts_1.ReadyDomain.Application && drained.hasResidue) {
+                    this.pendingDomains |= service_runtime_contracts_1.ReadyDomain.Application;
+                }
+                for (let index = 0; index < drained.records.length; index += 1) {
+                    const claim = readyBatch.takeClaim(index);
+                    claimsDrained += 1;
+                    try {
+                        receiveBatch.reset();
+                        for (;;) {
+                            const owner = drained.records[index];
+                            const claimPermit = owner.terminalCompletion === true
+                                || owner.ordinaryIngressPreAdmitted === true
+                                || domain === service_runtime_contracts_1.ReadyDomain.Infrastructure
+                                ? undefined
+                                : await this.acquirePermit();
+                            if (claimPermit === undefined
+                                && this.disposed
+                                && owner.terminalCompletion !== true
+                                && owner.ordinaryIngressPreAdmitted !== true)
+                                return false;
+                            const received = claim.recvBatch(receiveBatch, runtime_values_1.ZLINK_BACKEND_RECV_DONT_WAIT);
+                            if (!received.ok) {
+                                claimPermit?.releaseAfterInternalProcessing();
+                                break;
+                            }
+                            if (received.records.length === 0) {
+                                claimPermit?.releaseAfterInternalProcessing();
+                            }
+                            for (const record of received.records) {
+                                const permit = record.applicationJobPermit ?? claimPermit;
+                                if (owner.ordinaryIngressPreAdmitted === true && permit === undefined) {
+                                    record.releaseRetainedIngress?.();
+                                    throw new Error('Pre-admitted raw ingress record lost its Application Job Queue permit.');
+                                }
+                                try {
+                                    // A handler may synchronously submit an operation whose
+                                    // control/completion is owned by this same MeshNode (e.g. a
+                                    // native Completion record fed back through this node's own
+                                    // Infrastructure claim). The active lane's scheduling state
+                                    // must be released here, or a nested re-entrant drain can
+                                    // never start to deliver that completion, and the awaiting
+                                    // handler deadlocks against its own claim (spec
+                                    // 46-internal-dispatch-loop, receive/dispatch wake/ordering).
+                                    this.scheduled = false;
+                                    this.drainPromise = undefined;
+                                    if (domain === service_runtime_contracts_1.ReadyDomain.Infrastructure) {
+                                        this.infrastructureScheduled = false;
+                                        this.infrastructureDrainPromise = undefined;
+                                    }
+                                    if (this.pendingDomains !== service_runtime_contracts_1.ReadyDomain.None) {
+                                        this.schedule();
+                                    }
+                                    const dispatch = () => (0, execution_1.runZLinkExecutionArea)(domain === service_runtime_contracts_1.ReadyDomain.Infrastructure ? 'infrastructure' : 'application', async () => {
+                                        try {
+                                            await this.options.dispatch(drained.records[index], record);
+                                        }
+                                        catch (error) {
+                                            throw new ZLinkMeshDispatchFailure(meshDispatchFailureContext(record), error);
+                                        }
+                                        await record.onTerminalCompletion?.();
+                                    });
+                                    if (permit === undefined) {
+                                        await dispatch();
+                                    }
+                                    else {
+                                        if (domain === service_runtime_contracts_1.ReadyDomain.Application
+                                            && record.applicationJobPermit === undefined)
+                                            permit.markApplicationQueued();
+                                        await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(permit, dispatch);
+                                    }
+                                }
+                                finally {
+                                    for (const part of record.parts) {
+                                        part.close();
+                                    }
+                                    record.releaseRetainedIngress?.();
+                                }
+                            }
+                            // A continuously readable owner must not keep the timers phase
+                            // from running, but a timer turn for every single record adds a
+                            // Promise, closure, and timer allocation to the hot path.
+                            receiveBatchesSinceTimerYield += 1;
+                            if (receiveBatchesSinceTimerYield >= MESH_DISPATCH_TIMER_YIELD_BATCHES
+                                || this.nowMs() - timerYieldStartedAtMs >= MESH_DISPATCH_TIMER_YIELD_INTERVAL_MS) {
+                                receiveBatchesSinceTimerYield = 0;
+                                await yieldToTimers();
+                                timerYieldStartedAtMs = this.nowMs();
+                            }
+                            receiveBatch.reset();
+                        }
+                    }
+                    finally {
+                        claim.release();
+                    }
+                }
+                await yieldToTimers();
+                receiveBatchesSinceTimerYield = 0;
+                timerYieldStartedAtMs = this.nowMs();
+                if (!drained.hasResidue) {
+                    return false;
+                }
+            }
+        }
+        finally {
+            receiveBatch.close();
+            readyBatch.close();
+        }
+    }
+    nowMs() {
+        return this.options.monotonicNowMs?.() ?? performance.now();
+    }
+    async acquirePermit() {
+        try {
+            return await this.options.applicationJobQueue.acquire(this.capacityStop.signal);
+        }
+        catch (error) {
+            if (this.disposed || this.capacityStop.signal.aborted)
+                return undefined;
+            throw error;
+        }
+    }
+}
+exports.ZLinkMeshDispatchPump = ZLinkMeshDispatchPump;
+function meshDispatchFailureContext(record) {
+    const commandId = serviceWireCommand(record);
+    return {
+        receiveKind: record.kind,
+        operationKind: record.operationKind,
+        ...(record.packetName === undefined ? {} : { packetName: record.packetName }),
+        ...(record.sourceNodeRid === null ? {} : { sourceNodeRid: String(record.sourceNodeRid) }),
+        ...(commandId === undefined ? {} : { commandId })
+    };
+}
+function serviceWireCommand(record) {
+    if (record.parts.length !== 1)
+        return undefined;
+    const bytes = record.parts[0].data();
+    return bytes.byteLength >= 5 && bytes[0] === 0x5a && bytes[1] === 0x4d && bytes[2] === 1
+        ? bytes[3]
+        : undefined;
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+function yieldToTimers() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}

package/dist/runtime/backend/mesh-record-dispatcher.d.ts

@@ -0,0 +1,19 @@
+import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+export interface ZLinkMeshRecordDispatchPorts {
+    readonly node: (record: ReceiveRecord) => void | Promise<void>;
+    readonly spot: (owner: ReadyRecord, record: ReceiveRecord) => void | Promise<void>;
+    readonly actor: (owner: ReadyRecord, record: ReceiveRecord) => void | Promise<void>;
+    readonly completion: (record: ReceiveRecord) => void | Promise<void>;
+    readonly sendReady: (record: ReceiveRecord) => void | Promise<void>;
+    readonly transferControl: (record: ReceiveRecord) => void | Promise<void>;
+}
+/**
+ * Routes one pulled Core record to the framework component that owns its
+ * lifecycle. The pump retains the record until the returned promise settles.
+ */
+export declare class ZLinkMeshRecordDispatcher {
+    private readonly ports;
+    constructor(ports: ZLinkMeshRecordDispatchPorts);
+    dispatch(owner: ReadyRecord, record: ReceiveRecord): void | Promise<void>;
+    private requireOwner;
+}