@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/execution/index.ts

@@ -1,5 +1,4 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { ZLinkConfigurationException } from '../configuration';
 import { isAbortError } from '../abort';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -53,6 +52,7 @@ export class ZLinkSpotSerialTurn {
   private suspendedResolve: (() => void) | undefined;
   private suspendedPromise: Promise<void> | undefined;
   private suspendSignaled = false;
+  private yieldUsed = false;
   private owner: Promise<unknown> | undefined;
   private frameworkOperationsBlocked = false;
 
@@ -115,26 +115,41 @@ export class ZLinkSpotSerialTurn {
   }
 
   resetSuspension(): void {
+    this.yieldUsed = false;
     this.suspendSignaled = false;
     this.suspendedResolve = undefined;
     this.suspendedPromise = undefined;
   }
 
-  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
-    if (!this.yieldAllowed) {
-      throw new ZLinkConfigurationException(
-        'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  admitYield(): void {
+    const current = spotSerialTurnStorage.getStore();
+    if (
+      current?.turn !== this ||
+      !this.yieldAllowed ||
+      !current.executor.isActiveTurn(this, current.turnId) ||
+      this.yieldUsed
+    ) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'Yield requires the current SpotWide application turn and may be used only once per turn.'
       );
     }
+    this.yieldUsed = true;
+  }
+
+  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
+    this.admitYield();
     return await this.yieldFrameworkPromise(pending);
   }
 
   /** Suspends a turn only for a Framework-owned lifecycle boundary. */
   async yieldFrameworkPromise<T>(pending: Promise<T>): Promise<T> {
     this.signalSuspended();
-    const result = await pending;
-    await this.awaitResumePermit();
-    return result;
+    try {
+      return await pending;
+    } finally {
+      await this.awaitResumePermit();
+    }
   }
 
   async resumeOwnerUntilNextYield(): Promise<void> {
@@ -204,16 +219,18 @@ export function currentZLinkSpotSerialSourceId(): unknown {
 
 export function requireZLinkYieldTurn(capturedTurn?: ZLinkSpotSerialTurn): ZLinkSpotSerialTurn {
   const turn = capturedTurn ?? captureZLinkSpotSerialTurn();
-  if (turn === undefined || !turn.yieldAllowed) {
-    throw new ZLinkConfigurationException(
-      'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  if (turn === undefined) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.InvalidOperation,
+      'Yield requires a current SpotWide application turn.'
     );
   }
+  turn.admitYield();
   return turn;
 }
 
 export interface ZLinkCapturedExecutionTurn {
-  yieldPromise<T>(pending: Promise<T>): Promise<T>;
+  yieldPromise<T>(operation: () => Promise<T>): Promise<T>;
   post(callback: () => void): void;
 }
 
@@ -223,7 +240,16 @@ export function captureZLinkExecutionTurn(): ZLinkCapturedExecutionTurn | undefi
     return undefined;
   }
   return {
-    yieldPromise: <T>(pending: Promise<T>) => current.turn.yieldPromise(pending),
+    yieldPromise: <T>(operation: () => Promise<T>) => {
+      const turn = requireZLinkYieldTurn(current.turn);
+      let pending: Promise<T>;
+      try {
+        pending = operation();
+      } catch (error) {
+        pending = Promise.reject(error);
+      }
+      return turn.yieldFrameworkPromise(pending);
+    },
     post: (callback: () => void) => {
       void current.executor.post(callback);
     }
@@ -241,7 +267,7 @@ export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecut
 
 export interface ZLinkExecutionBarrierSeal {
   readonly generation: bigint;
-  readonly kind: 'close' | 'relocation';
+  readonly kind: 'close' | 'relocation' | 'activation';
 }
 
 export interface ZLinkExecutionBarrierClaim {

package/src/runtime/execution/serial-execution-queue.ts

@@ -1,6 +1,7 @@
 import { macrotaskBoundary } from '../abort';
 import {
   diagnosticWorkName,
+  startOutsideStateLane,
   guardStateLaneCompletion,
   isStructuralGuardEnabled,
   trackDiagnosticCompletion
@@ -9,6 +10,9 @@ import {
 export type ZLinkSerialWorkLane = 'application' | 'lifecycle';
 
 export interface ZLinkSerialWorkOptions {
+  readonly onAdmitted?: () => void;
+  /** Transfers an unstarted durable record out of this FIFO in the owner turn. */
+  readonly onWithdrawable?: (withdraw: () => boolean) => void;
   readonly lane?: ZLinkSerialWorkLane;
   readonly payloadBytes?: number;
   readonly metadataBytes?: number;
@@ -166,12 +170,22 @@ export class ZLinkSerialExecutionQueue {
     return this.admit(operation, { lane: 'lifecycle' }, context, undefined, true);
   }
 
+  get retainsApplicationForLifecycle(): boolean {
+    return this.activeLifecycle?.context !== undefined;
+  }
+
   visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void {
     for (const record of this.application.records) {
       if (record.mailbox === undefined) visitor(record);
     }
   }
 
+  get hasPendingDurableApplication(): boolean {
+    // Every application record accepted behind durable work inherits durable
+    // ownership, so the tail answers this without scanning the FIFO.
+    return this.application.records.at(-1)?.preparation !== undefined;
+  }
+
   get hasPendingWork(): boolean {
     return (
       this.consumer?.running === true ||
@@ -269,6 +283,19 @@ export class ZLinkSerialExecutionQueue {
       release();
       throw error;
     }
+    options.onAdmitted?.();
+    options.onWithdrawable?.(() => {
+      const index = target.records.indexOf(record as SerialWorkRecord<unknown>);
+      if (index < 0) return false;
+      target.records.splice(index, 1);
+      record.preparationController?.abort(
+        new Error('Durable record transferred to another handoff.')
+      );
+      record.preparation?.cancel();
+      resolve(undefined as T);
+      release();
+      return true;
+    });
     this.scheduleDrain();
     return result;
   }
@@ -284,10 +311,12 @@ export class ZLinkSerialExecutionQueue {
     const consumer = this.consumer!;
     if (consumer.scheduled || consumer.running) return;
     consumer.scheduled = true;
-    queueMicrotask(() => {
-      consumer.scheduled = false;
-      void this.drain();
-    });
+    startOutsideStateLane(() =>
+      queueMicrotask(() => {
+        consumer.scheduled = false;
+        void this.drain();
+      })
+    );
   }
 
   /** Notifications carry no payload, admission sequence, result Promise, or host permit. */

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

@@ -12,6 +12,13 @@ export function isStructuralGuardEnabled(): boolean {
   return process.env.ZLINK_NODE_STRUCTURAL_GUARD === '1' || process.env.NODE_ENV === 'test';
 }
 
+/** Detaches lane ownership while preserving the caller's other execution contexts. */
+export function startOutsideStateLane<T>(work: () => T): T {
+  return currentLaneStorage.exit(() =>
+    diagnosticTurnStorage === undefined ? work() : diagnosticTurnStorage.exit(work)
+  );
+}
+
 const currentLaneStorage = new AsyncLocalStorage<ZLinkStateLane>();
 const diagnosticPending = isStructuralGuardEnabled() ? new Map<number, string>() : undefined;
 let nextDiagnosticWork = 0;

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

@@ -131,7 +131,7 @@ export function encodeCanonicalActorJoinRecoverySavedWork(
   const replyContentType =
     operationId === undefined
       ? null
-      : requireText(input.replyContentType, 'Actor Join reply content type');
+      : (nullableText(input.replyContentType ?? null, 'Actor Join reply content type') ?? null);
   const metadata = encodeMetadataJson({
     Request: {
       ActorId: requireText(input.actorId, 'Actor id'),
@@ -288,7 +288,7 @@ export function decodeCanonicalActorJoinRecoverySavedWork(
   const operationLow = integer(metadata.OperationIdLow, 'OperationIdLow');
   const hasOperation = operationHigh !== 0n || operationLow !== 0n;
   const replyContentType = nullableText(metadata.ReplyContentType, 'ReplyContentType');
-  if (hasOperation !== (replyContentType !== undefined)) {
+  if (!hasOperation && replyContentType !== undefined) {
     throw new TypeError('Canonical Actor Join recovery reply identity is invalid.');
   }
   const targetNodeRid = base64(metadata.TargetNodeRid, 'TargetNodeRid');

package/src/runtime/foundation/durable-service-request.ts

@@ -0,0 +1,137 @@
+import { awaitWithAbort } from '../abort';
+import { RequestResult, SubmitResult, isZLinkBackendResultError } from '../backend/runtime-values';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+
+export interface PeerRouteObservation {
+  readonly generation?: bigint;
+  readonly ready: boolean;
+}
+
+export interface DurableServiceRequestPort {
+  readonly requestStopSignal?: AbortSignal;
+  observePeerRoute(target: string): PeerRouteObservation;
+  observePeerRouteChanged(listener: (target: string) => void): () => void;
+  observePeerConnectionIntentRemoved(listener: (target: string) => void): () => void;
+  requestService(
+    target: string,
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]>;
+}
+
+/** Actor model §8.1: a ready edge or a typed transport failure owns replay. */
+export async function requestDurableService(
+  port: DurableServiceRequestPort,
+  target: string,
+  parts: readonly Uint8Array[],
+  deadlineMs: number,
+  operationKind: string,
+  signal?: AbortSignal,
+  onSubmitted?: (signal: AbortSignal) => Promise<void>
+): Promise<readonly Buffer[]> {
+  let wasAdmitted = false;
+  const stop = new AbortController();
+  const exhausted = (cause?: unknown) =>
+    createInternalFrameworkException(
+      wasAdmitted
+        ? ZLinkFrameworkInternalErrorKind.DeadlineExceeded
+        : ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+      `${operationKind} exhausted its end-to-end deadline.`,
+      true,
+      cause
+    );
+  const timer = setTimeout(
+    () => stop.abort(exhausted()),
+    Math.max(0, Math.ceil(deadlineMs - performance.now()))
+  );
+  const unobserveIntent = port.observePeerConnectionIntentRemoved((rid) => {
+    if (rid === target)
+      stop.abort(
+        createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+          `${operationKind} target node lifecycle ended.`,
+          true
+        )
+      );
+  });
+  const cancellation = AbortSignal.any([
+    stop.signal,
+    ...(signal === undefined ? [] : [signal]),
+    ...(port.requestStopSignal === undefined ? [] : [port.requestStopSignal])
+  ]);
+  try {
+    for (;;) {
+      cancellation.throwIfAborted();
+      const remainingMs = Math.ceil(deadlineMs - performance.now());
+      if (remainingMs <= 0) throw exhausted();
+      let changed!: () => void;
+      const transition = new Promise<void>((resolve) => {
+        changed = resolve;
+      });
+      let submittedGeneration: bigint | undefined;
+      const attemptStop = new AbortController();
+      const attemptSignal = AbortSignal.any([cancellation, attemptStop.signal]);
+      const unobserveRoute = port.observePeerRouteChanged((rid) => {
+        if (rid !== target) return;
+        const route = port.observePeerRoute(target);
+        if (
+          submittedGeneration === undefined
+            ? route.ready
+            : route.generation !== undefined && route.generation !== submittedGeneration
+        ) {
+          changed();
+          attemptStop.abort();
+        }
+      });
+      try {
+        const route = port.observePeerRoute(target);
+        if (!route.ready) {
+          await awaitWithAbort(transition, cancellation);
+          continue;
+        }
+        submittedGeneration = route.generation;
+        const reply = port.requestService(target, parts, remainingMs, () => {
+          wasAdmitted = true;
+        });
+        const request =
+          onSubmitted === undefined
+            ? reply
+            : Promise.race([
+                reply,
+                Promise.resolve()
+                  .then(() => onSubmitted(attemptSignal))
+                  .then(() => reply)
+              ]);
+        const result = await awaitWithAbort(
+          Promise.race([request.then((parts) => ({ parts })), transition.then(() => undefined)]),
+          cancellation
+        );
+        if (result !== undefined) return result.parts;
+      } catch (error) {
+        cancellation.throwIfAborted();
+        if (!durableRequestCanReplay(error)) throw error;
+        if (isZLinkBackendResultError(error) && error.operation === 'request') wasAdmitted = true;
+      } finally {
+        attemptStop.abort();
+        unobserveRoute();
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    unobserveIntent();
+  }
+}
+
+export function durableRequestCanReplay(error: unknown): boolean {
+  if (!isZLinkBackendResultError(error)) return false;
+  return error.operation === 'request'
+    ? error.result === RequestResult.NotConnected || error.result === RequestResult.TimedOut
+    : error.result === SubmitResult.NotConnected ||
+        error.result === SubmitResult.NotFound ||
+        error.result === SubmitResult.NotAdmitted ||
+        error.result === SubmitResult.Backpressured;
+}

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

@@ -19,12 +19,16 @@ export type ZLinkOperationIdentityKey = string & {
 export function operationIdentityKey(
   operationId: ZLinkOperationIdentity128
 ): ZLinkOperationIdentityKey {
+  validateOperationIdentity(operationId);
+  return `${operationId.high.toString(16)}:${operationId.low.toString(16)}` as ZLinkOperationIdentityKey;
+}
+
+export function validateOperationIdentity(operationId: ZLinkOperationIdentity128): void {
   requireUnsigned64(operationId.high, 'operationId.high');
   requireUnsigned64(operationId.low, 'operationId.low');
   if (operationId.high === 0n && operationId.low === 0n) {
     throw new RangeError('Operation identity must not be all zero.');
   }
-  return `${operationId.high.toString(16)}:${operationId.low.toString(16)}` as ZLinkOperationIdentityKey;
 }
 
 export function createRandomOperationIdentity(

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

@@ -24,11 +24,22 @@ export interface PendingOperation<T> {
   readonly promise: Promise<T>;
 }
 
+/**
+ * Receives an operation's terminal at the place it is taken from the
+ * registry. One long-lived observer serves every observed operation, so an
+ * observed registration creates no Promise or per-operation callback.
+ */
+export interface OperationObserver<T, Context> {
+  operationCompleted(id: bigint, value: T, context: Context | undefined): void;
+  operationFailed(id: bigint, reason: unknown, context: Context | undefined): void;
+}
+
 interface Entry<T, Context> {
   readonly context: Context | undefined;
-  readonly deadlineMs?: number;
-  readonly resolve: (value: T | PromiseLike<T>) => void;
-  readonly reject: (reason: unknown) => void;
+  deadlineMs?: number;
+  resolve?: (value: T | PromiseLike<T>) => void;
+  reject?: (reason: unknown) => void;
+  observer?: OperationObserver<T, Context>;
 }
 
 const systemClock: OperationClock = {
@@ -40,7 +51,14 @@ export class OperationRegistry<T, Context = unknown> {
   private readonly entries = new Map<bigint, Entry<T, Context>>();
   private nextId = 1n;
   private deadlineCursor?: MapIterator<[bigint, Entry<T, Context>]>;
+  /**
+   * A lower bound of the earliest pending deadline. Completed entries only
+   * leave it early; a full expiry pass replaces it with the exact value.
+   */
+  private earliestDeadlineMs = Number.POSITIVE_INFINITY;
+  private scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
   private closed = false;
+  private pendingCount = 0;
 
   constructor(
     private readonly clock: OperationClock = systemClock,
@@ -63,28 +81,56 @@ export class OperationRegistry<T, Context = unknown> {
       resolve = onResolve;
       reject = onReject;
     });
-    const entry: Entry<T, Context> = {
-      context,
-      deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
-      resolve,
-      reject
-    };
+    const deadlineMs = timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined;
+    const entry: Entry<T, Context> = { context, deadlineMs, resolve, reject };
     this.entries.set(id, entry);
-    if (this.entries.size === 1) this.onPendingChanged?.();
+    this.notePending(deadlineMs);
     return { id, promise };
   }
 
-  complete(id: bigint, value: T): boolean {
+  /** Registers an operation whose terminal goes to `observer` instead of a Promise. */
+  registerObserved(
+    timeoutMs: number,
+    observer: OperationObserver<T, Context>,
+    context?: Context
+  ): bigint {
+    if (this.closed) throw new Error('Operation registry is closed.');
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      throw new RangeError('timeoutMs must be a non-negative finite number.');
+    }
+    const id = this.nextId++;
+    const deadlineMs = this.clock.now() + timeoutMs;
+    this.entries.set(id, { context, deadlineMs, observer });
+    this.notePending(deadlineMs);
+    return id;
+  }
+
+  /** The time the next expiry pass has work, as a lower bound (spec 08 §4.2). */
+  nextDeadlineMs(): number {
+    return this.earliestDeadlineMs;
+  }
+
+  private notePending(deadlineMs: number | undefined): void {
+    this.pendingCount++;
+    const earlier = deadlineMs !== undefined && deadlineMs < this.earliestDeadlineMs;
+    if (earlier) this.earliestDeadlineMs = deadlineMs;
+    if (earlier || this.pendingCount === 1) this.onPendingChanged?.();
+  }
+
+  complete(id: bigint, value: T, terminalContextRetentionMs = 0): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
-    entry.resolve(value);
+    if (entry.observer !== undefined) entry.observer.operationCompleted(id, value, entry.context);
+    else entry.resolve!(value);
+    this.retainTerminal(id, entry, terminalContextRetentionMs);
     return true;
   }
 
   fail(id: bigint, reason: unknown): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
-    entry.reject(reason);
+    if (entry.observer !== undefined) entry.observer.operationFailed(id, reason, entry.context);
+    else entry.reject!(reason);
     return true;
   }
 
@@ -93,7 +139,7 @@ export class OperationRegistry<T, Context = unknown> {
   }
 
   isPending(id: bigint): boolean {
-    return this.entries.has(id);
+    return this.pendingEntry(id) !== undefined;
   }
 
   context(id: bigint): Context | undefined {
@@ -104,35 +150,67 @@ export class OperationRegistry<T, Context = unknown> {
     if (this.closed) return;
     this.closed = true;
     for (const id of this.entries.keys()) this.cancel(id, reason);
+    this.entries.clear();
     this.deadlineCursor = undefined;
   }
 
+  failAll(reason: unknown): void {
+    for (const id of this.entries.keys()) this.fail(id, reason);
+  }
+
   get size(): number {
-    return this.entries.size;
+    return this.pendingCount;
   }
 
   expire(nowMs: number, turnDeadlineMs: number): number {
     let expired = 0;
     while (this.clock.now() < turnDeadlineMs) {
-      this.deadlineCursor ??= this.entries.entries();
+      if (this.deadlineCursor === undefined) {
+        this.deadlineCursor = this.entries.entries();
+        this.scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
+      }
       const current = this.deadlineCursor.next();
       if (current.done === true) {
         this.deadlineCursor = undefined;
+        // Entries registered during the pass are appended and were scanned.
+        this.earliestDeadlineMs = this.scanEarliestDeadlineMs;
         break;
       }
       const [id, entry] = current.value;
-      if (entry.deadlineMs !== undefined && entry.deadlineMs <= nowMs) {
-        if (this.fail(id, new OperationTimeoutError(id))) expired++;
+      if (entry.deadlineMs === undefined) continue;
+      if (entry.deadlineMs <= nowMs) {
+        if (!this.isPending(id)) this.entries.delete(id);
+        else if (this.fail(id, new OperationTimeoutError(id))) expired++;
+      } else if (entry.deadlineMs < this.scanEarliestDeadlineMs) {
+        this.scanEarliestDeadlineMs = entry.deadlineMs;
       }
     }
     return expired;
   }
 
   private take(id: bigint): Entry<T, Context> | undefined {
-    const entry = this.entries.get(id);
+    const entry = this.pendingEntry(id);
     if (entry === undefined) return undefined;
     this.entries.delete(id);
-    if (this.entries.size === 0) this.onPendingChanged?.();
+    this.pendingCount--;
+    if (this.pendingCount === 0) this.onPendingChanged?.();
     return entry;
   }
+
+  private pendingEntry(id: bigint): Entry<T, Context> | undefined {
+    const entry = this.entries.get(id);
+    return entry !== undefined && (entry.resolve !== undefined || entry.observer !== undefined)
+      ? entry
+      : undefined;
+  }
+
+  private retainTerminal(id: bigint, entry: Entry<T, Context>, retentionMs: number): void {
+    if (this.closed || entry.context === undefined || retentionMs === 0) return;
+    entry.resolve = undefined;
+    entry.reject = undefined;
+    entry.observer = undefined;
+    entry.deadlineMs = this.clock.now() + retentionMs;
+    this.entries.set(id, entry);
+    this.earliestDeadlineMs = Math.min(this.earliestDeadlineMs, entry.deadlineMs);
+  }
 }