@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/execution/state-lane.ts

@@ -1,7 +1,23 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+const UNKNOWN_DIAGNOSTIC_CALLER = '<unknown caller>';
 
 type ZLinkStateLaneWork<T> = () => Promise<T> | T;
 
+interface ZLinkStateLaneTurn {
+  readonly lane: ZLinkStateLane;
+  active: boolean;
+}
+
+export function isStructuralGuardEnabled(): boolean {
+  return process.env.ZLINK_NODE_STRUCTURAL_GUARD === '1' || process.env.NODE_ENV === 'test';
+}
+
+const currentLaneStorage = new AsyncLocalStorage<ZLinkStateLane>();
+const diagnosticPending = isStructuralGuardEnabled() ? new Map<number, string>() : undefined;
+let nextDiagnosticWork = 0;
+const diagnosticTurnStorage =
+  diagnosticPending === undefined ? undefined : new AsyncLocalStorage<ZLinkStateLaneTurn>();
+
 /**
  * Single-owner execution lane for a component's mutable state.
  *
@@ -10,15 +26,13 @@ type ZLinkStateLaneWork<T> = () => Promise<T> | T;
  * Actor serial executors, which also own lifecycle and relocation concerns.
  */
 export class ZLinkStateLane {
-  private static readonly currentLaneStorage = new AsyncLocalStorage<ZLinkStateLane>();
-
   private readonly mailbox: Array<() => Promise<void>> = [];
   private draining = false;
   private drainPromise: Promise<void> | undefined;
   private closed = false;
 
   static get current(): ZLinkStateLane | undefined {
-    return ZLinkStateLane.currentLaneStorage.getStore();
+    return currentLaneStorage.getStore();
   }
 
   get isOnLane(): boolean {
@@ -100,7 +114,7 @@ export class ZLinkStateLane {
           return;
         }
         try {
-          await ZLinkStateLane.currentLaneStorage.run(this, work);
+          await currentLaneStorage.run(this, work);
         } catch {
           // Posted callbacks own their errors. One failure must not strand later work.
         }
@@ -114,3 +128,127 @@ export class ZLinkStateLane {
     }
   }
 }
+
+// Install the structural check only in diagnostic processes. The release run()
+// method and its returned Promise are left untouched.
+if (isStructuralGuardEnabled()) {
+  Object.defineProperty(ZLinkStateLane, 'current', {
+    configurable: true,
+    get: () => {
+      const turn = diagnosticTurnStorage?.getStore();
+      return turn?.active === true ? turn.lane : undefined;
+    }
+  });
+
+  const run = ZLinkStateLane.prototype.run;
+  ZLinkStateLane.prototype.run = function <T>(
+    this: ZLinkStateLane,
+    work: ZLinkStateLaneWork<T>
+  ): Promise<T> {
+    const completion = run.call(this, () => runDiagnosticTurn(this, work)) as Promise<T>;
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(completion, `state lane ${diagnosticWorkName(work)}`),
+      'another state lane completion',
+      this
+    );
+  };
+
+  const tryPost = ZLinkStateLane.prototype.tryPost;
+  ZLinkStateLane.prototype.tryPost = function (
+    this: ZLinkStateLane,
+    work: ZLinkStateLaneWork<void>
+  ): boolean {
+    const release = registerDiagnosticWork(`state lane post ${diagnosticWorkName(work)}`);
+    const accepted = tryPost.call(this, () => {
+      try {
+        const result = runDiagnosticTurn(this, work);
+        if (result instanceof Promise) return result.finally(release);
+        release();
+        return result;
+      } catch (error) {
+        release();
+        throw error;
+      }
+    });
+    if (!accepted) release();
+    return accepted;
+  };
+}
+
+function runDiagnosticTurn<T>(lane: ZLinkStateLane, work: ZLinkStateLaneWork<T>): Promise<T> | T {
+  const turn: ZLinkStateLaneTurn = { lane, active: true };
+  return diagnosticTurnStorage!.run(turn, () => {
+    try {
+      const result = work();
+      if (result instanceof Promise) {
+        return result.finally(() => {
+          turn.active = false;
+        });
+      }
+      turn.active = false;
+      return result;
+    } catch (error) {
+      turn.active = false;
+      throw error;
+    }
+  });
+}
+
+/** Applied only by debug-installed wrappers; release completions keep their original identity. */
+export function guardStateLaneCompletion<T>(
+  completion: Promise<T>,
+  label: string,
+  owner?: ZLinkStateLane
+): Promise<T> {
+  return new Proxy(completion, {
+    get(target, property) {
+      if (property === 'then') {
+        return (onFulfilled: (value: T) => unknown, onRejected: (error: unknown) => unknown) => {
+          const current = ZLinkStateLane.current;
+          if (current !== undefined && current !== owner) {
+            throw new Error(`A state lane turn cannot wait for ${label}.`);
+          }
+          return target.then(onFulfilled, onRejected);
+        };
+      }
+      if (property === 'catch') {
+        return (onRejected: (error: unknown) => unknown) =>
+          guardStateLaneCompletion(target.catch(onRejected), label, owner);
+      }
+      if (property === 'finally') {
+        return (onFinally: () => void) =>
+          guardStateLaneCompletion(target.finally(onFinally), label, owner);
+      }
+      const value = Reflect.get(target, property, target) as unknown;
+      return typeof value === 'function' ? value.bind(target) : value;
+    }
+  });
+}
+
+export function trackDiagnosticCompletion<T>(completion: Promise<T>, name: string): Promise<T> {
+  const release = registerDiagnosticWork(name);
+  void completion.then(release, release);
+  return completion;
+}
+
+export function debugPendingWorkNames(): string[] {
+  return [...(diagnosticPending?.values() ?? [])];
+}
+
+export function diagnosticWorkName(work: { readonly name: string }): string {
+  return work.name.length > 0 ? work.name : '<anonymous>';
+}
+
+function registerDiagnosticWork(name: string): () => void {
+  if (diagnosticPending === undefined) return () => undefined;
+  const id = ++nextDiagnosticWork;
+  const frames = new Error().stack?.split('\n').slice(2) ?? [];
+  const caller =
+    frames
+      .find((frame) => !frame.includes('state-lane.') && !frame.includes('serial-execution-queue.'))
+      ?.trim() ?? UNKNOWN_DIAGNOSTIC_CALLER;
+  diagnosticPending.set(id, `${name} ${caller}`);
+  return () => {
+    diagnosticPending.delete(id);
+  };
+}

package/src/runtime/foundation/actor-join-recovery-codec.ts

@@ -1,11 +1,15 @@
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import { createHash } from 'node:crypto';
 import type { RoutingId, ZLinkActorJoinOperationId } from '../../contracts';
-import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
 import {
   decodeZljrRecordV1 as decodeGeneratedZljrRecordV1,
   encodeZljrRecordV1 as encodeGeneratedZljrRecordV1
 } from '../protocol/service_wire_pilot_codec.generated';
+import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
 import { decodeServiceWireFrozenRecord } from './service-stateful-wire-codec';
+const ACTOR_ID_DIGEST_MAX_BYTES = 0xffff;
+
+export const SHA256_DIGEST_BYTES = 32;
 
 const RECOVERY_PACKET_NAME = '__zlink.actor.routed_join.recovery';
 const RECOVERY_CONTENT_TYPE = 'application/x-zlink-actor-routed-join-recovery-v1';
@@ -13,8 +17,8 @@ const MAXIMUM_METADATA_BYTES = 256 * 1024;
 const FRAMEWORK_METADATA_UPPER_BOUND_BYTES = 64 * 1024;
 const ACCEPTED_JOURNAL_UPPER_BOUND_BYTES = 16 * 1024 * 1024;
 const SNAPSHOT_APPLICATION_STATE_RESERVATION_BYTES = 64 * 1024 * 1024;
-const RECREATE_RELOCATION_CONTENT_TYPE = 'application/vnd.zlink.actor-relocation.recreate';
-const SNAPSHOT_RELOCATION_CONTENT_TYPE = 'application/vnd.zlink.actor-relocation.snapshot';
+export const RECREATE_RELOCATION_CONTENT_TYPE = 'application/vnd.zlink.actor-relocation.recreate';
+export const SNAPSHOT_RELOCATION_CONTENT_TYPE = 'application/vnd.zlink.actor-relocation.snapshot';
 
 export interface CanonicalActorJoinRecoveryRequest {
   readonly actorId: string;
@@ -87,7 +91,8 @@ export function canonicalActorJoinHandoffId(input: {
   readonly correlation: bigint;
 }): string {
   const actor = textBytes(input.actorId, 'actorId');
-  if (actor.byteLength > 0xffff) throw new RangeError('Actor id exceeds u16 bytes.');
+  if (actor.byteLength > ACTOR_ID_DIGEST_MAX_BYTES)
+    throw new RangeError('Actor id exceeds u16 bytes.');
   const digest = createHash('sha256')
     .update(
       Buffer.concat([
@@ -139,7 +144,7 @@ export function encodeCanonicalActorJoinRecoverySavedWork(
       RelocationChecksumCrc32c: 0,
       RelocationAggregateId: canonicalUuid(input.relocationId),
       RelocationAggregateGeneration: 1n,
-      RelocationInventoryDigest: Buffer.alloc(32).toString('base64'),
+      RelocationInventoryDigest: Buffer.alloc(SHA256_DIGEST_BYTES).toString('base64'),
       RequestContentType: requireText(input.requestContentType, 'Actor Join request content type'),
       Request: '',
       HandoffFrames: [],
@@ -423,7 +428,7 @@ function requireText(value: string | undefined, name: string): string {
 }
 
 function nonZeroU64(value: bigint, name: string): bigint {
-  if (value < 1n || value > 0xffff_ffff_ffff_ffffn) throw new RangeError(`${name} is invalid.`);
+  if (value < 1n || value > UINT64_MAX) throw new RangeError(`${name} is invalid.`);
   return value;
 }
 
@@ -435,7 +440,7 @@ function u16(value: number): Buffer {
 }
 
 function u64(value: bigint): Buffer {
-  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) throw new RangeError('u64');
+  if (value < 0n || value > UINT64_MAX) throw new RangeError('u64');
   const result = Buffer.alloc(8);
   result.writeBigUInt64BE(value);
   return result;
@@ -461,7 +466,7 @@ function integer(value: unknown, name: string): bigint {
   if (typeof value !== 'string' || !/^\d+$/u.test(value))
     throw new TypeError(`${name} is invalid.`);
   const parsed = BigInt(value);
-  if (parsed > 0xffff_ffff_ffff_ffffn) throw new TypeError(`${name} exceeds u64.`);
+  if (parsed > UINT64_MAX) throw new TypeError(`${name} exceeds u64.`);
   return parsed;
 }
 

package/src/runtime/foundation/event-loop-resources.ts

@@ -1,5 +1,3 @@
-import { runZLinkExecutionArea } from '../execution';
-
 export interface CloseableResource {
   close(): void | Promise<void>;
 }
@@ -23,7 +21,7 @@ export class EventLoopResourceStack {
   }
 }
 
-async function closeResources(resources: readonly CloseableResource[]): Promise<void> {
+export async function closeResources(resources: readonly CloseableResource[]): Promise<void> {
   const failures: unknown[] = [];
   for (const resource of resources) {
     try {
@@ -32,126 +30,11 @@ async function closeResources(resources: readonly CloseableResource[]): Promise<
       failures.push(error);
     }
   }
-  if (failures.length > 0) {
-    throw new AggregateError(failures, 'Event-loop resource cleanup failed.');
-  }
+  finishResourceCleanup(failures);
 }
 
-export type EventLoopTask = () => void | Promise<void>;
-
-/** Keeps infrastructure progress independent from awaiting application handlers. */
-export class EventLoopWorkQueues {
-  private readonly infrastructure: Array<EventLoopTask | undefined> = [];
-  private infrastructureHead = 0;
-  private infrastructureCount = 0;
-  private readonly application: Array<EventLoopTask | undefined> = [];
-  private applicationHead = 0;
-  private applicationCount = 0;
-  private infrastructureScheduled = false;
-  private applicationScheduled = false;
-  private accepting = true;
-
-  submitInfrastructure(task: EventLoopTask): boolean {
-    if (!this.accepting) return false;
-    this.infrastructure.push(task);
-    this.infrastructureCount += 1;
-    this.scheduleInfrastructure();
-    return true;
-  }
-
-  submitApplication(task: EventLoopTask): boolean {
-    if (!this.accepting) return false;
-    this.application.push(task);
-    this.applicationCount += 1;
-    this.scheduleApplication();
-    return true;
-  }
-
-  stopAdmission(): void {
-    this.accepting = false;
-  }
-
-  private scheduleInfrastructure(): void {
-    if (this.infrastructureScheduled) return;
-    this.infrastructureScheduled = true;
-    queueMicrotask(() => this.drainInfrastructure());
-  }
-
-  private drainInfrastructure(): void {
-    this.infrastructureScheduled = false;
-    const task = this.takeInfrastructure();
-    if (task === undefined) return;
-    try {
-      const result = runZLinkExecutionArea('infrastructure', task);
-      if (result instanceof Promise) void result.catch(() => undefined);
-    } finally {
-      if (this.infrastructureCount > 0) this.scheduleInfrastructure();
-    }
-  }
-
-  private scheduleApplication(): void {
-    if (this.applicationScheduled) return;
-    this.applicationScheduled = true;
-    queueMicrotask(() => void this.drainApplication());
-  }
-
-  private async drainApplication(): Promise<void> {
-    try {
-      const task = this.takeApplication();
-      if (task !== undefined) {
-        await 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();
-    }
-  }
-
-  private takeInfrastructure(): EventLoopTask | undefined {
-    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;
-  }
-
-  private takeApplication(): EventLoopTask | undefined {
-    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;
-  }
-
-  private compactInfrastructure(): void {
-    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;
-    }
-  }
-
-  private compactApplication(): void {
-    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;
-    }
+export function finishResourceCleanup(failures: readonly unknown[]): void {
+  if (failures.length > 0) {
+    throw new AggregateError(failures, 'Event-loop resource cleanup failed.');
   }
 }

package/src/runtime/foundation/listener-records.ts

@@ -0,0 +1,21 @@
+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 class ZLinkListenerRecords {
+  private readonly endpoints = new Map<string, string>();
+
+  record(kind: ZLinkListenerKind, name: string, endpoint: string): void {
+    this.endpoints.set(`${kind}:${name}`, endpoint);
+  }
+
+  clear(): void {
+    this.endpoints.clear();
+  }
+
+  endpoint(kind: ZLinkListenerKind, name: string): string | undefined {
+    return this.endpoints.get(`${kind}:${name}`);
+  }
+}

package/src/runtime/foundation/operation-identity.ts

@@ -1,4 +1,8 @@
+import { UINT64_BYTES, UINT64_MAX } from '@zlink-systems/stream-wire';
 import { randomBytes } from 'node:crypto';
+export const OPERATION_IDENTITY_BYTES = 16;
+
+export const ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE = 2n;
 
 export interface ZLinkOperationIdentity128 {
   readonly high: bigint;
@@ -27,13 +31,15 @@ export function createRandomOperationIdentity(
   source: (size: number) => Buffer = randomBytes
 ): ZLinkOperationIdentity128 {
   for (;;) {
-    const bytes = source(16);
-    if (bytes.length !== 16) {
-      throw new RangeError('Operation identity entropy source must return exactly 16 bytes.');
+    const bytes = source(OPERATION_IDENTITY_BYTES);
+    if (bytes.length !== OPERATION_IDENTITY_BYTES) {
+      throw new RangeError(
+        `Operation identity entropy source must return exactly ${OPERATION_IDENTITY_BYTES} bytes.`
+      );
     }
     const operationId = {
       high: bytes.readBigUInt64BE(0),
-      low: bytes.readBigUInt64BE(8)
+      low: bytes.readBigUInt64BE(UINT64_BYTES)
     };
     if (operationId.high !== 0n || operationId.low !== 0n) {
       return operationId;
@@ -42,7 +48,7 @@ export function createRandomOperationIdentity(
 }
 
 function requireUnsigned64(value: bigint, name: string): void {
-  if (typeof value !== 'bigint' || value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (typeof value !== 'bigint' || value < 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be an unsigned 64-bit integer.`);
   }
 }

package/src/runtime/foundation/operation-registry.ts

@@ -1,6 +1,5 @@
 export interface OperationClock {
-  setTimeout(callback: () => void, delayMs: number): unknown;
-  clearTimeout(handle: unknown): void;
+  now(): number;
 }
 
 export class OperationTimeoutError extends Error {
@@ -26,32 +25,26 @@ export interface PendingOperation<T> {
 }
 
 interface Entry<T> {
-  readonly generation: bigint;
+  readonly deadlineMs?: number;
   readonly resolve: (value: T | PromiseLike<T>) => void;
   readonly reject: (reason: unknown) => void;
-  timer?: unknown;
 }
 
 const systemClock: OperationClock = {
-  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 as NodeJS.Timeout);
-  }
+  now: () => performance.now()
 };
 
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
 export class OperationRegistry<T> {
   private readonly entries = new Map<bigint, Entry<T>>();
   private nextId = 1n;
-  private generation = 1n;
+  private deadlineCursor?: MapIterator<[bigint, Entry<T>]>;
   private closed = false;
 
-  constructor(private readonly clock: OperationClock = systemClock) {}
+  constructor(
+    private readonly clock: OperationClock = systemClock,
+    private readonly onPendingChanged?: () => void
+  ) {}
 
   register(
     timeoutMs: number,
@@ -62,23 +55,19 @@ export class OperationRegistry<T> {
       throw new RangeError('timeoutMs must be a non-negative finite number.');
     }
     const id = this.nextId++;
-    const generation = this.generation;
     let resolve!: Entry<T>['resolve'];
     let reject!: Entry<T>['reject'];
     const promise = new Promise<T>((onResolve, onReject) => {
       resolve = onResolve;
       reject = onReject;
     });
-    const entry: Entry<T> = { generation, resolve, reject };
+    const entry: Entry<T> = {
+      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 };
   }
 
@@ -90,10 +79,6 @@ export class OperationRegistry<T> {
   }
 
   fail(id: bigint, reason: unknown): boolean {
-    return this.failCore(id, reason);
-  }
-
-  private failCore(id: bigint, reason: unknown): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
     entry.reject(reason);
@@ -101,7 +86,7 @@ export class OperationRegistry<T> {
   }
 
   cancel(id: bigint, message?: string): boolean {
-    return this.failCore(id, new OperationCancelledError(id, message));
+    return this.fail(id, new OperationCancelledError(id, message));
   }
 
   isPending(id: bigint): boolean {
@@ -111,38 +96,36 @@ export class OperationRegistry<T> {
   close(reason = 'Operation registry closed.'): void {
     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(): number {
     return this.entries.size;
   }
 
-  private rejectIfCurrent(id: bigint, generation: bigint, reason: unknown): void {
-    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: number, turnDeadlineMs: number): number {
+    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;
   }
 
   private take(id: bigint): Entry<T> | undefined {
     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;
   }
-
-  private clearTimer(entry: Entry<T>): void {
-    if (entry.timer === undefined) return;
-    this.clock.clearTimeout(entry.timer);
-    entry.timer = undefined;
-  }
 }