@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/foundation/event-loop-resources.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventLoopWorkQueues = exports.EventLoopResourceStack = void 0;
-const execution_1 = require("../execution");
+exports.EventLoopResourceStack = void 0;
+exports.closeResources = closeResources;
+exports.finishResourceCleanup = finishResourceCleanup;
 /** Closes owned runtime resources once, in reverse acquisition order. */
 class EventLoopResourceStack {
     resources = [];
@@ -31,124 +32,10 @@ async function closeResources(resources) {
             failures.push(error);
         }
     }
+    finishResourceCleanup(failures);
+}
+function finishResourceCleanup(failures) {
     if (failures.length > 0) {
         throw new AggregateError(failures, 'Event-loop resource cleanup failed.');
     }
 }
-/** Keeps infrastructure progress independent from awaiting application handlers. */
-class EventLoopWorkQueues {
-    infrastructure = [];
-    infrastructureHead = 0;
-    infrastructureCount = 0;
-    application = [];
-    applicationHead = 0;
-    applicationCount = 0;
-    infrastructureScheduled = false;
-    applicationScheduled = false;
-    accepting = true;
-    submitInfrastructure(task) {
-        if (!this.accepting)
-            return false;
-        this.infrastructure.push(task);
-        this.infrastructureCount += 1;
-        this.scheduleInfrastructure();
-        return true;
-    }
-    submitApplication(task) {
-        if (!this.accepting)
-            return false;
-        this.application.push(task);
-        this.applicationCount += 1;
-        this.scheduleApplication();
-        return true;
-    }
-    stopAdmission() {
-        this.accepting = false;
-    }
-    scheduleInfrastructure() {
-        if (this.infrastructureScheduled)
-            return;
-        this.infrastructureScheduled = true;
-        queueMicrotask(() => this.drainInfrastructure());
-    }
-    drainInfrastructure() {
-        this.infrastructureScheduled = false;
-        const task = this.takeInfrastructure();
-        if (task === undefined)
-            return;
-        try {
-            const result = (0, execution_1.runZLinkExecutionArea)('infrastructure', task);
-            if (result instanceof Promise)
-                void result.catch(() => undefined);
-        }
-        finally {
-            if (this.infrastructureCount > 0)
-                this.scheduleInfrastructure();
-        }
-    }
-    scheduleApplication() {
-        if (this.applicationScheduled)
-            return;
-        this.applicationScheduled = true;
-        queueMicrotask(() => void this.drainApplication());
-    }
-    async drainApplication() {
-        try {
-            const task = this.takeApplication();
-            if (task !== undefined) {
-                await (0, execution_1.runZLinkExecutionArea)('application', task);
-            }
-        }
-        catch {
-            // Handler failure is reported by the dispatch owner; it does not stop this queue.
-        }
-        finally {
-            this.applicationScheduled = false;
-            if (this.applicationCount > 0)
-                this.scheduleApplication();
-        }
-    }
-    takeInfrastructure() {
-        const task = this.infrastructure[this.infrastructureHead];
-        if (task === undefined)
-            return undefined;
-        this.infrastructure[this.infrastructureHead] = undefined;
-        this.infrastructureHead += 1;
-        this.infrastructureCount -= 1;
-        this.compactInfrastructure();
-        return task;
-    }
-    takeApplication() {
-        const task = this.application[this.applicationHead];
-        if (task === undefined)
-            return undefined;
-        this.application[this.applicationHead] = undefined;
-        this.applicationHead += 1;
-        this.applicationCount -= 1;
-        this.compactApplication();
-        return task;
-    }
-    compactInfrastructure() {
-        if (this.infrastructureCount === 0) {
-            this.infrastructure.length = 0;
-            this.infrastructureHead = 0;
-        }
-        else if (this.infrastructureHead >= 1024 &&
-            this.infrastructureHead * 2 >= this.infrastructure.length) {
-            this.infrastructure.splice(0, this.infrastructureHead);
-            this.infrastructureHead = 0;
-        }
-    }
-    compactApplication() {
-        if (this.applicationCount === 0) {
-            this.application.length = 0;
-            this.applicationHead = 0;
-        }
-        else if (this.applicationHead >= 1024 &&
-            this.applicationHead * 2 >= this.application.length) {
-            this.application.splice(0, this.applicationHead);
-            this.applicationHead = 0;
-        }
-    }
-}
-exports.EventLoopWorkQueues = EventLoopWorkQueues;

package/dist/runtime/foundation/listener-records.d.ts

@@ -0,0 +1,11 @@
+import type { ZLinkListenerKind } from '../../contracts/RouteMesh/RuntimeTopology';
+/**
+ * Bound listener records of one runtime generation (spec 04 §3.1). A listener writes its
+ * record when it finishes binding. The listener status query reads only this object.
+ */
+export declare class ZLinkListenerRecords {
+    private readonly endpoints;
+    record(kind: ZLinkListenerKind, name: string, endpoint: string): void;
+    clear(): void;
+    endpoint(kind: ZLinkListenerKind, name: string): string | undefined;
+}

package/dist/runtime/foundation/listener-records.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkListenerRecords = void 0;
+/**
+ * Bound listener records of one runtime generation (spec 04 §3.1). A listener writes its
+ * record when it finishes binding. The listener status query reads only this object.
+ */
+class ZLinkListenerRecords {
+    endpoints = new Map();
+    record(kind, name, endpoint) {
+        this.endpoints.set(`${kind}:${name}`, endpoint);
+    }
+    clear() {
+        this.endpoints.clear();
+    }
+    endpoint(kind, name) {
+        return this.endpoints.get(`${kind}:${name}`);
+    }
+}
+exports.ZLinkListenerRecords = ZLinkListenerRecords;

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

@@ -1,3 +1,5 @@
+export declare const OPERATION_IDENTITY_BYTES = 16;
+export declare const ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE = 2n;
 export interface ZLinkOperationIdentity128 {
     readonly high: bigint;
     readonly low: bigint;

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

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE = exports.OPERATION_IDENTITY_BYTES = void 0;
 exports.operationIdentityKey = operationIdentityKey;
 exports.createRandomOperationIdentity = createRandomOperationIdentity;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
+exports.OPERATION_IDENTITY_BYTES = 16;
+exports.ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE = 2n;
 function operationIdentityKey(operationId) {
     requireUnsigned64(operationId.high, 'operationId.high');
     requireUnsigned64(operationId.low, 'operationId.low');
@@ -13,13 +17,13 @@ function operationIdentityKey(operationId) {
 }
 function createRandomOperationIdentity(source = node_crypto_1.randomBytes) {
     for (;;) {
-        const bytes = source(16);
-        if (bytes.length !== 16) {
-            throw new RangeError('Operation identity entropy source must return exactly 16 bytes.');
+        const bytes = source(exports.OPERATION_IDENTITY_BYTES);
+        if (bytes.length !== exports.OPERATION_IDENTITY_BYTES) {
+            throw new RangeError(`Operation identity entropy source must return exactly ${exports.OPERATION_IDENTITY_BYTES} bytes.`);
         }
         const operationId = {
             high: bytes.readBigUInt64BE(0),
-            low: bytes.readBigUInt64BE(8)
+            low: bytes.readBigUInt64BE(stream_wire_1.UINT64_BYTES)
         };
         if (operationId.high !== 0n || operationId.low !== 0n) {
             return operationId;
@@ -27,7 +31,7 @@ function createRandomOperationIdentity(source = node_crypto_1.randomBytes) {
     }
 }
 function requireUnsigned64(value, name) {
-    if (typeof value !== 'bigint' || value < 0n || value > 0xffffffffffffffffn) {
+    if (typeof value !== 'bigint' || value < 0n || value > stream_wire_1.UINT64_MAX) {
         throw new RangeError(`${name} must be an unsigned 64-bit integer.`);
     }
 }

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

@@ -1,6 +1,5 @@
 export interface OperationClock {
-    setTimeout(callback: () => void, delayMs: number): unknown;
-    clearTimeout(handle: unknown): void;
+    now(): number;
 }
 export declare class OperationTimeoutError extends Error {
     readonly operationId: bigint;
@@ -17,20 +16,19 @@ export interface PendingOperation<T> {
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
 export declare class OperationRegistry<T> {
     private readonly clock;
+    private readonly onPendingChanged?;
     private readonly entries;
     private nextId;
-    private generation;
+    private deadlineCursor?;
     private closed;
-    constructor(clock?: OperationClock);
+    constructor(clock?: OperationClock, onPendingChanged?: (() => void) | undefined);
     register(timeoutMs: number, timeoutOwner?: 'registry' | 'sender'): PendingOperation<T>;
     complete(id: bigint, value: T): boolean;
     fail(id: bigint, reason: unknown): boolean;
-    private failCore;
     cancel(id: bigint, message?: string): boolean;
     isPending(id: bigint): boolean;
     close(reason?: string): void;
     get size(): number;
-    private rejectIfCurrent;
+    expire(nowMs: number, turnDeadlineMs: number): number;
     private take;
-    private clearTimer;
 }

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

@@ -20,25 +20,19 @@ class OperationCancelledError extends Error {
 }
 exports.OperationCancelledError = OperationCancelledError;
 const systemClock = {
-    setTimeout(callback, delayMs) {
-        // A request promise is live work.  Raw RouteMesh polling deliberately
-        // uses unref'ed timers, so this deadline is the handle that keeps a
-        // submit() caller alive until a reply, cancellation, or deadline settles.
-        return setTimeout(callback, delayMs);
-    },
-    clearTimeout(handle) {
-        clearTimeout(handle);
-    }
+    now: () => performance.now()
 };
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
 class OperationRegistry {
     clock;
+    onPendingChanged;
     entries = new Map();
     nextId = 1n;
-    generation = 1n;
+    deadlineCursor;
     closed = false;
-    constructor(clock = systemClock) {
+    constructor(clock = systemClock, onPendingChanged) {
         this.clock = clock;
+        this.onPendingChanged = onPendingChanged;
     }
     register(timeoutMs, timeoutOwner = 'registry') {
         if (this.closed)
@@ -47,20 +41,20 @@ class OperationRegistry {
             throw new RangeError('timeoutMs must be a non-negative finite number.');
         }
         const id = this.nextId++;
-        const generation = this.generation;
         let resolve;
         let reject;
         const promise = new Promise((onResolve, onReject) => {
             resolve = onResolve;
             reject = onReject;
         });
-        const entry = { generation, resolve, reject };
+        const entry = {
+            deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
+            resolve,
+            reject
+        };
         this.entries.set(id, entry);
-        // Durable senders classify exhaustion from admission history. Keep their
-        // identity and cancellation here without racing that decision with a timer.
-        if (timeoutOwner === 'registry') {
-            entry.timer = this.clock.setTimeout(() => this.rejectIfCurrent(id, generation, new OperationTimeoutError(id)), timeoutMs);
-        }
+        if (this.entries.size === 1)
+            this.onPendingChanged?.();
         return { id, promise };
     }
     complete(id, value) {
@@ -71,9 +65,6 @@ class OperationRegistry {
         return true;
     }
     fail(id, reason) {
-        return this.failCore(id, reason);
-    }
-    failCore(id, reason) {
         const entry = this.take(id);
         if (entry === undefined)
             return false;
@@ -81,7 +72,7 @@ class OperationRegistry {
         return true;
     }
     cancel(id, message) {
-        return this.failCore(id, new OperationCancelledError(id, message));
+        return this.fail(id, new OperationCancelledError(id, message));
     }
     isPending(id) {
         return this.entries.has(id);
@@ -90,39 +81,38 @@ class OperationRegistry {
         if (this.closed)
             return;
         this.closed = true;
-        this.generation++;
-        const pending = [...this.entries.entries()];
-        this.entries.clear();
-        for (const [, entry] of pending)
-            this.clearTimer(entry);
-        for (const [id, entry] of pending) {
-            entry.reject(new OperationCancelledError(id, reason));
-        }
+        for (const id of this.entries.keys())
+            this.cancel(id, reason);
+        this.deadlineCursor = undefined;
     }
     get size() {
         return this.entries.size;
     }
-    rejectIfCurrent(id, generation, reason) {
-        const entry = this.entries.get(id);
-        if (entry === undefined || entry.generation !== generation)
-            return;
-        this.entries.delete(id);
-        this.clearTimer(entry);
-        entry.reject(reason);
+    expire(nowMs, turnDeadlineMs) {
+        let expired = 0;
+        while (this.clock.now() < turnDeadlineMs) {
+            this.deadlineCursor ??= this.entries.entries();
+            const current = this.deadlineCursor.next();
+            if (current.done === true) {
+                this.deadlineCursor = undefined;
+                break;
+            }
+            const [id, entry] = current.value;
+            if (entry.deadlineMs !== undefined && entry.deadlineMs <= nowMs) {
+                if (this.fail(id, new OperationTimeoutError(id)))
+                    expired++;
+            }
+        }
+        return expired;
     }
     take(id) {
         const entry = this.entries.get(id);
         if (entry === undefined)
             return undefined;
         this.entries.delete(id);
-        this.clearTimer(entry);
+        if (this.entries.size === 0)
+            this.onPendingChanged?.();
         return entry;
     }
-    clearTimer(entry) {
-        if (entry.timer === undefined)
-            return;
-        this.clock.clearTimeout(entry.timer);
-        entry.timer = undefined;
-    }
 }
 exports.OperationRegistry = OperationRegistry;

package/dist/runtime/foundation/raw-service-mesh-runtime.d.ts

@@ -1,7 +1,7 @@
+import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
+import type { ApplicationJobQueuePort } from '../application-jobs/contracts';
 import type { ZLinkRawBindingPort } from '../backend/raw-binding-port';
 import { SubmitResult } from '../backend/runtime-values';
-import type { ApplicationJobQueuePort } from '../application-jobs/contracts';
-import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
 import { type PendingOperation } from './operation-registry';
 import { ServiceLivenessRegistry, type ServiceLivenessTick } from './service-liveness-registry';
 import { ServiceMailbox, type ServiceMailboxRecord } from './service-mailbox';
@@ -29,6 +29,7 @@ export interface RawServiceIngressRecord {
 }
 export type RawServiceIngressHandler = (record: RawServiceIngressRecord) => RawServicePumpResult | undefined | Promise<RawServicePumpResult | undefined>;
 export interface RawServiceMeshRuntimeOptions {
+    readonly onPendingOperationsChanged?: () => void;
     readonly descriptor: ServiceNodeDescriptor;
     readonly resolveAdvertisedEndpoint?: (boundEndpoint: string) => string;
     readonly probeIntervalMs?: number;
@@ -47,6 +48,7 @@ export interface RawServiceMeshRuntimeOptions {
         readonly command?: number;
     }) => void;
 }
+export declare const RAW_MESH_RECEIVE_TIME_BUDGET_MS = 2;
 /**
  * RouteMesh M6A runtime built only on the public raw binding package.
  * It owns protocol, admission, mailbox, request and liveness state.
@@ -59,17 +61,11 @@ export declare class RawServiceMeshRuntime {
     private readonly expectedPeers;
     private readonly endpointOnlyPeers;
     private readonly peerConnectionIntentRemoved;
-    private readonly connectionCandidates;
-    private readonly unresolvedConnectionCandidates;
-    private readonly connectionIds;
     /**
-     * The monitor drain updates this fence before the event reaches the
-     * normal runtime handler. `null` means that the last observed pair is no
-     * longer usable by the application route.
+     * The last observed Core selected route of each RID (Core ROUTER §10.1):
+     * RID -> route generation. Only `observeSelectedRoutes` replaces it.
      */
-    private readonly monitorConnectionStates;
-    private monitorEvents;
-    private monitorDrainBuffer;
+    private selectedRoutes;
     private readonly bindingPort;
     private readonly applicationJobQueue;
     private readonly peerAdmissionSealed?;
@@ -82,7 +78,6 @@ export declare class RawServiceMeshRuntime {
     private descriptor;
     private host?;
     private router?;
-    private monitor?;
     private nextCorrelation;
     private serviceIngress?;
     private closed;
@@ -112,7 +107,6 @@ export declare class RawServiceMeshRuntime {
     requestToNode(targetNodeRoutingId: string, payload: ServiceApplicationPayloadInput, timeoutMs: number): PendingOperation<RawServiceRequestResult>;
     requestToChannel(channelName: string, payload: ServiceApplicationPayloadInput, timeoutMs: number): PendingOperation<RawServiceRequestResult>;
     private selectChannelTarget;
-    private isLocalOrReadyPeer;
     setServiceIngress(handler: RawServiceIngressHandler): void;
     reserveLocalIngress(signal?: AbortSignal): Promise<ApplicationIngressRecordOwner>;
     sendService(targetNodeRoutingId: string, parts: readonly Uint8Array[]): Promise<boolean>;
@@ -120,16 +114,23 @@ export declare class RawServiceMeshRuntime {
     replyService(record: Pick<RawServiceIngressRecord, 'sourceRoutingId' | 'sourceRoute' | 'requestSequence' | 'reply'>, parts: readonly Uint8Array[]): void;
     reply(request: ServiceMailboxRecord, payload: ServiceApplicationPayloadInput, terminalResult?: number, failureCode?: number): void;
     pumpOne(nowMs?: number, observe?: RawServicePumpObserver): Promise<RawServicePumpResult>;
-    setReadableHandler(handler: () => void): void;
+    setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void;
     /** Returns whether a receive budget ended before no-data; idle ticks only maintain peers. */
-    pumpBatch(receiveReady?: boolean): Promise<boolean>;
+    pumpBatch(receiveReady?: boolean, routeReady?: boolean): Promise<boolean>;
     private receiveOne;
-    private pullMonitorEvents;
     private reportProtocolError;
     private replyGenericProtocolError;
     private processReceived;
+    expireOperations(nowMs: number, turnDeadlineMs: number): number;
+    get pendingOperationCount(): number;
     tickLiveness(nowMs?: number): Promise<ServiceLivenessTick>;
-    drainMonitorEvents(nowMs?: number): Promise<number>;
+    /**
+     * The socket's one route observer (Core ROUTER §10.1). It replaces the
+     * observation with Core's selected-route snapshot, ends the admission of
+     * every RID whose observed route disappeared or was replaced, and starts the
+     * handshake of every newly selected route. Returns the number of changes.
+     */
+    observeSelectedRoutes(): Promise<number>;
     close(): void;
     private requestToTarget;
     /**
@@ -139,18 +140,9 @@ export declare class RawServiceMeshRuntime {
     private applicationFrame;
     private applicationPayload;
     private admitPeer;
-    private currentConnectionCandidate;
-    private createConnectionCandidate;
-    private createUnresolvedConnectionCandidate;
-    private promoteUnresolvedConnectionCandidate;
-    private removeConnectionCandidate;
-    private isDiscoveredLifecycleReplacement;
-    private expectedPeerRoutingId;
-    private acceptsExpectedMonitorEndpoint;
     private retireNotRequiredExpectedPeer;
     private selectBilateralConnection;
     private removePeer;
-    private observeMonitorEvent;
     private requireStarted;
     private send;
 }