@zlink-systems/framework 0.17.0 → 0.18.1

package/dist/runtime/host/user-spot-creation-coordinator.d.ts

@@ -65,5 +65,5 @@ export declare class ZLinkUserSpotCreationCoordinator {
     private awaitReady;
     private remoteCreate;
 }
-export declare function encodeLocationCreationContent(payload: Uint8Array, checksum?: number): string;
-export declare function decodeLocationCreationContent(reference: string, expectedSha256?: Uint8Array, expectedEncodedSize?: bigint): Buffer;
+export declare function encodeLocationCreationContent(payload: Uint8Array): string;
+export declare function decodeLocationCreationContent(reference: string, expectedSha256: Uint8Array, expectedEncodedSize: bigint): Buffer;

package/dist/runtime/host/user-spot-creation-coordinator.js

@@ -25,9 +25,8 @@ class ZLinkUserSpotCreationCoordinator {
         const deadlineUnixMs = Date.now() + request.timeoutMs;
         const signal = deadline.signal;
         signal.throwIfAborted();
-        const checksum = crc32c(request.requestPayload);
         const sha256 = (0, node_crypto_1.createHash)('sha256').update(request.requestPayload).digest();
-        const contentReference = encodeLocationCreationContent(request.requestPayload, checksum);
+        const contentReference = encodeLocationCreationContent(request.requestPayload);
         const excludedNodeRids = new Set();
         let target;
         let authorityTarget;
@@ -334,12 +333,7 @@ class ZLinkUserSpotCreationCoordinator {
             || pending.reservationId !== record.reservation.reservationId) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Remote User Spot Pending creation projection is missing.');
         }
-        const requestPayload = decodeLocationCreationContent(pending.requestContentReference);
-        if (BigInt(requestPayload.byteLength) !== pending.requestEncodedSize
-            || !(0, node_crypto_1.createHash)('sha256').update(requestPayload).digest()
-                .equals(Buffer.from(pending.requestSha256))) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Remote User Spot Pending creation content failed integrity validation.');
-        }
+        const requestPayload = decodeLocationCreationContent(pending.requestContentReference, pending.requestSha256, pending.requestEncodedSize);
         let local;
         try {
             local = await materialize(requestPayload, current, signal ?? new AbortController().signal);
@@ -647,24 +641,27 @@ function localCreationRecord(request, snapshot, targetNodeRid, targetNodeGenerat
         deadlineUnixMs: BigInt(deadlineUnixMs)
     };
 }
-function encodeLocationCreationContent(payload, checksum = crc32c(payload)) {
-    return `inline-v1:${checksum.toString(16).padStart(8, '0')}:${Buffer.from(payload).toString('base64url')}`;
+// 21-location-runtime.md#2.4: requestContentReference is `inline-v1:{base64url}`
+// over `A-Z a-z 0-9 - _` with no `=` padding, and no other form is recognized.
+// The same atomic record's requestEncodedSize and requestSha256 decide the
+// content's integrity, so the reference carries no checksum segment of its own.
+function encodeLocationCreationContent(payload) {
+    return `inline-v1:${Buffer.from(payload).toString('base64url')}`;
 }
+// Decodes the reference and verifies it against the same record's
+// requestEncodedSize and requestSha256. A reference outside the specified form,
+// a length mismatch or a digest mismatch all throw, and the caller must record
+// the creation as failed without running the factory.
 function decodeLocationCreationContent(reference, expectedSha256, expectedEncodedSize) {
-    const match = /^inline-v1:([0-9a-f]{8}):([A-Za-z0-9_-]+)$/.exec(reference);
-    if (match === null) {
-        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'User Spot creation content reference is invalid.');
-    }
-    const payload = Buffer.from(match[2], 'base64url');
-    if (crc32c(payload) !== Number.parseInt(match[1], 16)) {
-        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'User Spot creation content checksum does not match.');
+    const match = /^inline-v1:([A-Za-z0-9_-]*)$/.exec(reference);
+    if (match === null || match[1].length % 4 === 1) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Creation content reference is not in the inline-v1 form.');
     }
-    if (expectedEncodedSize !== undefined
-        && BigInt(payload.byteLength) !== expectedEncodedSize) {
+    const payload = Buffer.from(match[1], 'base64url');
+    if (BigInt(payload.byteLength) !== expectedEncodedSize) {
         throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Creation content encoded size does not match its Pending reservation.');
     }
-    if (expectedSha256 !== undefined
-        && !(0, node_crypto_1.createHash)('sha256').update(payload).digest().equals(Buffer.from(expectedSha256))) {
+    if (!(0, node_crypto_1.createHash)('sha256').update(payload).digest().equals(Buffer.from(expectedSha256))) {
         throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Creation content SHA-256 does not match its Pending reservation.');
     }
     return payload;
@@ -695,16 +692,6 @@ function userSpotAuthorityPayload(snapshot, spotId, state) {
         ownerNodeGeneration: snapshot.allocation.descriptorLifecycleGeneration
     });
 }
-function crc32c(payload) {
-    let crc = 0xffff_ffff;
-    for (const value of payload) {
-        crc ^= value;
-        for (let bit = 0; bit < 8; bit++) {
-            crc = (crc >>> 1) ^ (0x82f6_3b78 & -(crc & 1));
-        }
-    }
-    return (~crc) >>> 0;
-}
 function remoteUserSpotFailure(terminalResult, failureCode, message) {
     //  Route every User Spot create terminal through the shared ownership-aware
     //  translator (spec 32-framework-error-model:81-118, 99-108) rather than an

package/dist/runtime/streams/stream-session-runtime.d.ts

@@ -131,6 +131,7 @@ export declare class ZLinkStreamSessionNodeRuntime {
     private stopped;
     private readonly receiveAbortController;
     private receiveLoop;
+    private monitorLoop;
     private readonly receiveWake;
     private receiveWorkSinceYield;
     constructor(options: ZLinkStreamSessionNodeRuntimeOptions & ZLinkStreamLivenessOptions);
@@ -140,11 +141,12 @@ export declare class ZLinkStreamSessionNodeRuntime {
     findSession(routingId: unknown): ZLinkStreamSessionRuntime | undefined;
     dispose(): Promise<void>;
     drainCloseSessions(): Promise<void>;
+    private runMonitorLoop;
+    private monitorIdleDelay;
     private runReceiveLoop;
     private acceptPacket;
     private takePacket;
     private recyclePacket;
-    private drainMonitorEvents;
     private handleMalformedPacket;
     private isReceiveStopped;
     private onMonitorEvent;

package/dist/runtime/streams/stream-session-runtime.js

@@ -25,6 +25,9 @@ const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
+const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
+const ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS = 20;
+const ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS = 7;
 const systemLivenessClock = {
     now: () => performance.now(),
     setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
@@ -654,6 +657,7 @@ class ZLinkStreamSessionNodeRuntime {
     stopped = false;
     receiveAbortController = new AbortController();
     receiveLoop;
+    monitorLoop;
     receiveWake = new ZLinkStreamReceiveWake();
     receiveWorkSinceYield = 0;
     constructor(options) {
@@ -663,7 +667,8 @@ class ZLinkStreamSessionNodeRuntime {
         if (this.stopped || this.receiveLoop !== undefined) {
             return;
         }
-        this.options.monitor?.onEvent(event => this.onMonitorEvent(event));
+        const monitor = this.options.monitor;
+        monitor?.onEvent(event => this.onMonitorEvent(event));
         const running = this.runReceiveLoop(this.receiveAbortController.signal)
             .catch((error) => {
             if (!this.stopped) {
@@ -671,6 +676,14 @@ class ZLinkStreamSessionNodeRuntime {
             }
         });
         this.receiveLoop = running;
+        if (monitor !== undefined) {
+            this.monitorLoop = this.runMonitorLoop(monitor, this.receiveAbortController.signal)
+                .catch((error) => {
+                if (!this.stopped) {
+                    this.options.onError?.(error);
+                }
+            });
+        }
     }
     markConnected(routingId, localAddr, remoteAddr) {
         const session = this.getOrCreateSession(routingId);
@@ -689,6 +702,7 @@ class ZLinkStreamSessionNodeRuntime {
         this.wakeReceiveLoop();
         try {
             await this.receiveLoop;
+            await this.monitorLoop;
             const sessions = [...this.sessions.values()];
             this.sessions.clear();
             for (const packet of this.availablePackets.splice(0))
@@ -710,9 +724,47 @@ class ZLinkStreamSessionNodeRuntime {
     async drainCloseSessions() {
         await Promise.allSettled([...this.sessions.values()].map((session) => session.drainClose()));
     }
+    // Spec server 04-session §2/§7: a session exists once the handshake succeeds,
+    // and connect/disconnect callbacks are its base surface. A stream node learns
+    // of both from the socket monitor, which is a source of its own with no
+    // event-loop readiness callback. Draining it from the receive loop would tie
+    // a connection event to inbound traffic, so a session that never sends - a
+    // push-only console - would stay unknown to the node until it happened to
+    // write something. The .NET runtime already drains the monitor in its own
+    // loop (ZLinkStreamNodeRuntime.RunMonitorLoopAsync); this is the same rule.
+    async runMonitorLoop(monitor, signal) {
+        let misses = 0;
+        while (!this.isReceiveStopped(signal)) {
+            if (monitor.drain() > 0) {
+                misses = 0;
+                // Yield so a burst of monitor events cannot starve the event loop.
+                await this.monitorIdleDelay(0, signal);
+                continue;
+            }
+            misses = Math.min(misses + 1, ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS);
+            await this.monitorIdleDelay(monitorIdleDelayMs(misses), signal);
+        }
+    }
+    monitorIdleDelay(delayMs, signal) {
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            }, delayMs);
+            // The bound socket already holds the event loop open for this node. The
+            // idle poll must not become a second reason for a process to stay alive.
+            timer.unref();
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
     async runReceiveLoop(signal) {
         while (!this.isReceiveStopped(signal)) {
-            this.drainMonitorEvents();
             let permit;
             let packet;
             let packetTransferred = false;
@@ -839,9 +891,6 @@ class ZLinkStreamSessionNodeRuntime {
         if (!this.stopped)
             this.availablePackets.push(packet);
     }
-    drainMonitorEvents() {
-        this.options.monitor?.drain();
-    }
     handleMalformedPacket(routingId, session, error) {
         this.options.onError?.(error);
         try {
@@ -1112,6 +1161,10 @@ class ZLinkStreamSessionNodeRuntime {
     }
 }
 exports.ZLinkStreamSessionNodeRuntime = ZLinkStreamSessionNodeRuntime;
+function monitorIdleDelayMs(misses) {
+    const scaled = ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS * 2 ** (misses - 1);
+    return Math.min(scaled, ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS);
+}
 function streamMonitorEndpointKey(localAddr, remoteAddr) {
     return `${localAddr ?? ''}\n${remoteAddr ?? ''}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.17.0",
-    "@zlink-systems/zlink": "1.2.0"
+    "@zlink-systems/stream-wire": "0.18.1",
+    "@zlink-systems/zlink": "1.2.1"
   }
 }

package/src/runtime/host/user-spot-creation-coordinator.ts

@@ -104,9 +104,8 @@ export class ZLinkUserSpotCreationCoordinator {
     const deadlineUnixMs = Date.now() + request.timeoutMs;
     const signal = deadline.signal;
     signal.throwIfAborted();
-    const checksum = crc32c(request.requestPayload);
     const sha256 = createHash('sha256').update(request.requestPayload).digest();
-    const contentReference = encodeLocationCreationContent(request.requestPayload, checksum);
+    const contentReference = encodeLocationCreationContent(request.requestPayload);
     const excludedNodeRids = new Set<string>();
     let target: Awaited<ReturnType<ZLinkUserSpotCreationCoordinatorOptions['target']>>;
     let authorityTarget;
@@ -542,18 +541,10 @@ export class ZLinkUserSpotCreationCoordinator {
       );
     }
     const requestPayload = decodeLocationCreationContent(
-      pending.requestContentReference
+      pending.requestContentReference,
+      pending.requestSha256,
+      pending.requestEncodedSize
     );
-    if (
-      BigInt(requestPayload.byteLength) !== pending.requestEncodedSize
-      || !createHash('sha256').update(requestPayload).digest()
-        .equals(Buffer.from(pending.requestSha256))
-    ) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestFailed,
-        'Remote User Spot Pending creation content failed integrity validation.'
-      );
-    }
     let local: ZLinkLocalSpotCreateResult | undefined;
     try {
       local = await materialize(
@@ -1002,45 +993,38 @@ function localCreationRecord(
   };
 }
 
-export function encodeLocationCreationContent(
-  payload: Uint8Array,
-  checksum = crc32c(payload)
-): string {
-  return `inline-v1:${checksum.toString(16).padStart(8, '0')}:${Buffer.from(payload).toString('base64url')}`;
+// 21-location-runtime.md#2.4: requestContentReference is `inline-v1:{base64url}`
+// over `A-Z a-z 0-9 - _` with no `=` padding, and no other form is recognized.
+// The same atomic record's requestEncodedSize and requestSha256 decide the
+// content's integrity, so the reference carries no checksum segment of its own.
+export function encodeLocationCreationContent(payload: Uint8Array): string {
+  return `inline-v1:${Buffer.from(payload).toString('base64url')}`;
 }
 
+// Decodes the reference and verifies it against the same record's
+// requestEncodedSize and requestSha256. A reference outside the specified form,
+// a length mismatch or a digest mismatch all throw, and the caller must record
+// the creation as failed without running the factory.
 export function decodeLocationCreationContent(
   reference: string,
-  expectedSha256?: Uint8Array,
-  expectedEncodedSize?: bigint
+  expectedSha256: Uint8Array,
+  expectedEncodedSize: bigint
 ): Buffer {
-  const match = /^inline-v1:([0-9a-f]{8}):([A-Za-z0-9_-]+)$/.exec(reference);
-  if (match === null) {
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.RequestFailed,
-      'User Spot creation content reference is invalid.'
-    );
-  }
-  const payload = Buffer.from(match[2]!, 'base64url');
-  if (crc32c(payload) !== Number.parseInt(match[1]!, 16)) {
+  const match = /^inline-v1:([A-Za-z0-9_-]*)$/.exec(reference);
+  if (match === null || match[1]!.length % 4 === 1) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestFailed,
-      'User Spot creation content checksum does not match.'
+      'Creation content reference is not in the inline-v1 form.'
     );
   }
-  if (
-    expectedEncodedSize !== undefined
-    && BigInt(payload.byteLength) !== expectedEncodedSize
-  ) {
+  const payload = Buffer.from(match[1]!, 'base64url');
+  if (BigInt(payload.byteLength) !== expectedEncodedSize) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestFailed,
       'Creation content encoded size does not match its Pending reservation.'
     );
   }
-  if (
-    expectedSha256 !== undefined
-    && !createHash('sha256').update(payload).digest().equals(Buffer.from(expectedSha256))
-  ) {
+  if (!createHash('sha256').update(payload).digest().equals(Buffer.from(expectedSha256))) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestFailed,
       'Creation content SHA-256 does not match its Pending reservation.'
@@ -1088,17 +1072,6 @@ function userSpotAuthorityPayload(
   });
 }
 
-function crc32c(payload: Uint8Array): number {
-  let crc = 0xffff_ffff;
-  for (const value of payload) {
-    crc ^= value;
-    for (let bit = 0; bit < 8; bit++) {
-      crc = (crc >>> 1) ^ (0x82f6_3b78 & -(crc & 1));
-    }
-  }
-  return (~crc) >>> 0;
-}
-
 function remoteUserSpotFailure(
   terminalResult: number,
   failureCode: number,

package/src/runtime/streams/stream-session-runtime.ts

@@ -69,6 +69,9 @@ const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
+const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
+const ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS = 20;
+const ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS = 7;
 
 interface ZLinkStreamLivenessClock {
   now(): number;
@@ -884,6 +887,7 @@ export class ZLinkStreamSessionNodeRuntime {
   private stopped = false;
   private readonly receiveAbortController = new AbortController();
   private receiveLoop: Promise<void> | undefined;
+  private monitorLoop: Promise<void> | undefined;
   private readonly receiveWake = new ZLinkStreamReceiveWake();
   private receiveWorkSinceYield = 0;
   constructor(
@@ -894,7 +898,8 @@ export class ZLinkStreamSessionNodeRuntime {
     if (this.stopped || this.receiveLoop !== undefined) {
       return;
     }
-    this.options.monitor?.onEvent(event => this.onMonitorEvent(event));
+    const monitor = this.options.monitor;
+    monitor?.onEvent(event => this.onMonitorEvent(event));
     const running = this.runReceiveLoop(this.receiveAbortController.signal)
       .catch((error) => {
         if (!this.stopped) {
@@ -902,6 +907,14 @@ export class ZLinkStreamSessionNodeRuntime {
         }
       });
     this.receiveLoop = running;
+    if (monitor !== undefined) {
+      this.monitorLoop = this.runMonitorLoop(monitor, this.receiveAbortController.signal)
+        .catch((error) => {
+          if (!this.stopped) {
+            this.options.onError?.(error);
+          }
+        });
+    }
   }
 
   markConnected(routingId: unknown, localAddr?: string, remoteAddr?: string): void {
@@ -924,6 +937,7 @@ export class ZLinkStreamSessionNodeRuntime {
     this.wakeReceiveLoop();
     try {
       await this.receiveLoop;
+      await this.monitorLoop;
       const sessions = [...this.sessions.values()];
       this.sessions.clear();
       for (const packet of this.availablePackets.splice(0)) packet.close();
@@ -945,9 +959,51 @@ export class ZLinkStreamSessionNodeRuntime {
     await Promise.allSettled([...this.sessions.values()].map((session) => session.drainClose()));
   }
 
+  // Spec server 04-session §2/§7: a session exists once the handshake succeeds,
+  // and connect/disconnect callbacks are its base surface. A stream node learns
+  // of both from the socket monitor, which is a source of its own with no
+  // event-loop readiness callback. Draining it from the receive loop would tie
+  // a connection event to inbound traffic, so a session that never sends - a
+  // push-only console - would stay unknown to the node until it happened to
+  // write something. The .NET runtime already drains the monitor in its own
+  // loop (ZLinkStreamNodeRuntime.RunMonitorLoopAsync); this is the same rule.
+  private async runMonitorLoop(
+    monitor: ZLinkBackendSocketMonitor,
+    signal: AbortSignal
+  ): Promise<void> {
+    let misses = 0;
+    while (!this.isReceiveStopped(signal)) {
+      if (monitor.drain() > 0) {
+        misses = 0;
+        // Yield so a burst of monitor events cannot starve the event loop.
+        await this.monitorIdleDelay(0, signal);
+        continue;
+      }
+      misses = Math.min(misses + 1, ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS);
+      await this.monitorIdleDelay(monitorIdleDelayMs(misses), signal);
+    }
+  }
+
+  private monitorIdleDelay(delayMs: number, signal: AbortSignal): Promise<void> {
+    if (signal.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      const onAbort = (): void => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+      }, delayMs);
+      // The bound socket already holds the event loop open for this node. The
+      // idle poll must not become a second reason for a process to stay alive.
+      timer.unref();
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
   private async runReceiveLoop(signal: AbortSignal): Promise<void> {
     while (!this.isReceiveStopped(signal)) {
-      this.drainMonitorEvents();
       let permit: ApplicationJobPermitPort | undefined;
       let packet: ZLinkBackendStreamPacket | undefined;
       let packetTransferred = false;
@@ -1078,10 +1134,6 @@ export class ZLinkStreamSessionNodeRuntime {
     if (!this.stopped) this.availablePackets.push(packet);
   }
 
-  private drainMonitorEvents(): void {
-    this.options.monitor?.drain();
-  }
-
   private handleMalformedPacket(
     routingId: unknown,
     session: ZLinkStreamSessionRuntime,
@@ -1387,6 +1439,11 @@ export class ZLinkStreamSessionNodeRuntime {
   }
 }
 
+function monitorIdleDelayMs(misses: number): number {
+  const scaled = ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS * 2 ** (misses - 1);
+  return Math.min(scaled, ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS);
+}
+
 function streamMonitorEndpointKey(localAddr: string | undefined, remoteAddr: string | undefined): string {
   return `${localAddr ?? ''}\n${remoteAddr ?? ''}`;
 }