@zlink-systems/framework 0.28.0 → 0.29.1

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

@@ -52,6 +52,7 @@ export interface ZLinkSerialWorkPreparation {
 type SerialWorkRecord<T> = Omit<ZLinkSerialWorkRecord<T>, 'acceptedSequence'> & {
   acceptedSequence: bigint;
   readonly operationEnvelope: boolean;
+  readonly mailbox?: ZLinkSerialExecutionQueue;
   readonly preparation?: ZLinkSerialWorkPreparation;
   preparationState: 'idle' | 'pending' | 'canceling' | 'ready' | 'failed';
   preparationController?: AbortController;
@@ -70,11 +71,13 @@ export class ZLinkSerialExecutionQueue {
   private readonly application: ZLinkSerialAdmissionLane;
   private readonly lifecycle: ZLinkSerialAdmissionLane;
   private activeLifecycle?: ZLinkSerialWorkRecord<unknown>;
+  private activeRecord?: ZLinkSerialWorkRecord<unknown>;
+  /** The admitted node itself owns ready membership; no second readiness flag. */
+  private ownerMembership?: SerialWorkRecord<unknown>;
   private readonly ownerTimeBudget: number;
   private readonly lifecycleBurstLimit: number;
   private nextAcceptedSequence = 1n;
-  private draining = false;
-  private drainScheduled = false;
+  private readonly consumer?: { running: boolean; scheduled: boolean };
   private lifecycleStreak = 0;
   private lifecycleDebt = false;
   private claimStartedAt?: number;
@@ -83,7 +86,8 @@ export class ZLinkSerialExecutionQueue {
 
   constructor(
     private readonly executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>,
-    options: ZLinkSerialSchedulerOptions = {}
+    options: ZLinkSerialSchedulerOptions = {},
+    private readonly sharedOwner?: ZLinkSerialExecutionQueue
   ) {
     const configured = { ...ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS, ...options };
     validateNonNegative(configured.ownerTimeBudget, 'ownerTimeBudget');
@@ -92,6 +96,7 @@ export class ZLinkSerialExecutionQueue {
     this.lifecycle = createLane();
     this.ownerTimeBudget = configured.ownerTimeBudget;
     this.lifecycleBurstLimit = configured.lifecycleBurstLimit;
+    if (sharedOwner === undefined) this.consumer = { running: false, scheduled: false };
   }
 
   submit<T>(
@@ -162,12 +167,15 @@ export class ZLinkSerialExecutionQueue {
   }
 
   visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void {
-    for (const record of this.application.records) visitor(record);
+    for (const record of this.application.records) {
+      if (record.mailbox === undefined) visitor(record);
+    }
   }
 
   get hasPendingWork(): boolean {
     return (
-      this.draining ||
+      this.consumer?.running === true ||
+      this.activeRecord !== undefined ||
       this.activeLifecycle !== undefined ||
       this.application.records.length > 0 ||
       this.lifecycle.records.length > 0
@@ -219,7 +227,7 @@ export class ZLinkSerialExecutionQueue {
         this.activeLifecycle = undefined;
         if (this.application.records.length > 0 || this.lifecycle.records.length > 0) {
           this.scheduleDrain();
-        } else if (!this.draining) {
+        } else if (this.consumer?.running !== true) {
           this.resolveIdleWaiters();
         }
       }
@@ -266,39 +274,95 @@ export class ZLinkSerialExecutionQueue {
   }
 
   private scheduleDrain(): void {
-    if (this.drainScheduled || this.draining) return;
-    this.drainScheduled = true;
+    if (this.sharedOwner !== undefined) {
+      if (this.activeRecord !== undefined) return;
+      // Ready membership in the existing owner queue is the only notification state.
+      if (this.ownerMembership !== undefined) return;
+      this.enqueueMailboxTurn(() => this.consumeMailbox());
+      return;
+    }
+    const consumer = this.consumer!;
+    if (consumer.scheduled || consumer.running) return;
+    consumer.scheduled = true;
     queueMicrotask(() => {
-      this.drainScheduled = false;
+      consumer.scheduled = false;
       void this.drain();
     });
   }
 
+  /** Notifications carry no payload, admission sequence, result Promise, or host permit. */
+  private enqueueMailboxTurn(operation: () => void): void {
+    const entry: SerialWorkRecord<unknown> = {
+      acceptedSequence: 0n,
+      lane: 'application',
+      mailbox: this,
+      operation,
+      operationEnvelope: false,
+      preparationState: 'ready',
+      resolve: unexpectedMailboxSettlement,
+      reject: unexpectedMailboxSettlement,
+      release: unexpectedMailboxSettlement,
+      fail: unexpectedMailboxSettlement
+    };
+    const owner = this.sharedOwner!;
+    owner.application.records.push(entry);
+    this.ownerMembership = entry;
+    owner.scheduleDrain();
+  }
+
+  /** Called only by the shared scheduler's consumer, never by a producer. */
+  private consumeMailbox(): void {
+    const selection = this.selectNext();
+    if (selection === undefined) {
+      if (!this.hasPendingWork) this.resolveIdleWaiters();
+      return;
+    }
+    const record = selection.record;
+    if (!this.prepareSelected(selection)) return;
+    this.takeSelected(selection);
+    if (record.preparationState === 'failed') {
+      record.preparation?.cancel();
+      record.fail(record.preparationError);
+      this.scheduleDrain();
+      return;
+    }
+    this.activeRecord = record;
+    // The operation can submit Spot turns, including Yield continuations. Its
+    // Actor claim remains held until terminal settlement returns to this gate.
+    let terminal: Promise<unknown>;
+    try {
+      terminal = Promise.resolve(record.operation());
+    } catch (error) {
+      terminal = Promise.reject(error);
+    }
+    void terminal.then(
+      (value) => this.finishMailbox(record, () => record.resolve(value)),
+      (error) => this.finishMailbox(record, () => record.reject(error))
+    );
+  }
+
+  private finishMailbox(record: SerialWorkRecord<unknown>, settle: () => void): void {
+    this.enqueueMailboxTurn(() => {
+      settle();
+      record.release();
+      record.preparation?.cancel();
+      this.activeRecord = undefined;
+      if (this.selectNext() !== undefined) this.scheduleDrain();
+      else if (!this.hasPendingWork) this.resolveIdleWaiters();
+    });
+  }
+
   private async drain(): Promise<void> {
-    if (this.draining) return;
-    this.draining = true;
+    const consumer = this.consumer!;
+    if (consumer.running) return;
+    consumer.running = true;
     let waitingForPreparation = false;
     try {
       for (;;) {
         const selection = this.selectNext();
         if (selection === undefined) break;
         const record = selection.record;
-        if (selection.lane === 'lifecycle') {
-          const applicationHead = this.application.records[0]!;
-          if (
-            this.application.records.length > 0 &&
-            !this.cancelPreparationForRearbitration(applicationHead)
-          ) {
-            waitingForPreparation = true;
-            break;
-          }
-        }
-        if (record.preparationState === 'idle') {
-          this.startPreparation(record);
-          waitingForPreparation = true;
-          break;
-        }
-        if (record.preparationState === 'pending' || record.preparationState === 'canceling') {
+        if (!this.prepareSelected(selection)) {
           waitingForPreparation = true;
           break;
         }
@@ -310,7 +374,9 @@ export class ZLinkSerialExecutionQueue {
         }
         this.claimStartedAt ??= performance.now();
         try {
-          if (record.operationEnvelope) {
+          if (record.mailbox !== undefined) {
+            record.operation();
+          } else if (record.operationEnvelope) {
             try {
               const outcome = record.operation();
               void Promise.resolve(outcome).then(
@@ -330,6 +396,7 @@ export class ZLinkSerialExecutionQueue {
             await this.executeRecord(record);
           }
         } catch (error) {
+          if (record.mailbox !== undefined) throw error;
           record.fail(error);
         } finally {
           record.preparation?.cancel();
@@ -340,7 +407,7 @@ export class ZLinkSerialExecutionQueue {
         }
       }
     } finally {
-      this.draining = false;
+      consumer.running = false;
       this.claimStartedAt = undefined;
       if (!waitingForPreparation && this.selectNext() !== undefined) {
         this.scheduleDrain();
@@ -352,6 +419,21 @@ export class ZLinkSerialExecutionQueue {
     }
   }
 
+  private prepareSelected(selection: {
+    readonly lane: ZLinkSerialWorkLane;
+    readonly record: SerialWorkRecord<unknown>;
+  }): boolean {
+    if (
+      selection.lane === 'lifecycle' &&
+      this.application.records.length > 0 &&
+      !this.cancelPreparationForRearbitration(this.application.records[0]!)
+    )
+      return false;
+    const record = selection.record;
+    if (record.preparationState === 'idle') this.startPreparation(record);
+    return record.preparationState !== 'pending' && record.preparationState !== 'canceling';
+  }
+
   private selectNext():
     | {
         readonly lane: ZLinkSerialWorkLane;
@@ -389,6 +471,8 @@ export class ZLinkSerialExecutionQueue {
     if (record !== selection.record) {
       throw new Error('The selected serial work record changed before owner claim.');
     }
+    if (selection.record.mailbox !== undefined)
+      selection.record.mailbox.ownerMembership = undefined;
     return record;
   }
 
@@ -565,6 +649,10 @@ function createLane(): ZLinkSerialAdmissionLane {
   };
 }
 
+function unexpectedMailboxSettlement(): never {
+  throw new Error('A mailbox notification has no independent terminal result.');
+}
+
 function validatePositive(value: number, field: string): void {
   if (!Number.isSafeInteger(value) || value < 1) {
     throw new RangeError(`${field} must be a positive safe integer.`);

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

@@ -24,7 +24,8 @@ export interface PendingOperation<T> {
   readonly promise: Promise<T>;
 }
 
-interface Entry<T> {
+interface Entry<T, Context> {
+  readonly context: Context | undefined;
   readonly deadlineMs?: number;
   readonly resolve: (value: T | PromiseLike<T>) => void;
   readonly reject: (reason: unknown) => void;
@@ -35,10 +36,10 @@ const systemClock: OperationClock = {
 };
 
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
-export class OperationRegistry<T> {
-  private readonly entries = new Map<bigint, Entry<T>>();
+export class OperationRegistry<T, Context = unknown> {
+  private readonly entries = new Map<bigint, Entry<T, Context>>();
   private nextId = 1n;
-  private deadlineCursor?: MapIterator<[bigint, Entry<T>]>;
+  private deadlineCursor?: MapIterator<[bigint, Entry<T, Context>]>;
   private closed = false;
 
   constructor(
@@ -48,20 +49,22 @@ export class OperationRegistry<T> {
 
   register(
     timeoutMs: number,
-    timeoutOwner: 'registry' | 'sender' = 'registry'
+    timeoutOwner: 'registry' | 'sender' = 'registry',
+    context?: Context
   ): PendingOperation<T> {
     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++;
-    let resolve!: Entry<T>['resolve'];
-    let reject!: Entry<T>['reject'];
+    let resolve!: Entry<T, Context>['resolve'];
+    let reject!: Entry<T, Context>['reject'];
     const promise = new Promise<T>((onResolve, onReject) => {
       resolve = onResolve;
       reject = onReject;
     });
-    const entry: Entry<T> = {
+    const entry: Entry<T, Context> = {
+      context,
       deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
       resolve,
       reject
@@ -93,6 +96,10 @@ export class OperationRegistry<T> {
     return this.entries.has(id);
   }
 
+  context(id: bigint): Context | undefined {
+    return this.entries.get(id)?.context;
+  }
+
   close(reason = 'Operation registry closed.'): void {
     if (this.closed) return;
     this.closed = true;
@@ -121,7 +128,7 @@ export class OperationRegistry<T> {
     return expired;
   }
 
-  private take(id: bigint): Entry<T> | undefined {
+  private take(id: bigint): Entry<T, Context> | undefined {
     const entry = this.entries.get(id);
     if (entry === undefined) return undefined;
     this.entries.delete(id);

package/src/runtime/foundation/service-authority-payload-codec.ts

@@ -62,52 +62,6 @@ export interface ServiceUserSpotAuthorityPayload {
   readonly ownerNodeGeneration: bigint;
 }
 
-/** Replaces only authority-relocation-state and preserves the canonical owner payload. */
-export function replaceServiceAuthorityRelocationState(
-  payload: Uint8Array,
-  relocationState: Uint8Array
-): Buffer {
-  const bytes = Buffer.from(payload);
-  const reader = new AuthorityReader(bytes);
-  reader.expect(AUTHORITY_MAGIC);
-  if (reader.u8() !== AUTHORITY_FORMAT_VERSION || reader.u16() !== AUTHORITY_FLAGS) {
-    throw new TypeError('Authority payload header is invalid.');
-  }
-  const bodyLength = reader.u32();
-  const body = reader.takeReader(bodyLength);
-  const checksumOffset = reader.offset;
-  const checksum = reader.u32();
-  if (!reader.done || crc32c(bytes.subarray(0, checksumOffset)) !== checksum) {
-    throw new TypeError('Authority payload checksum is invalid.');
-  }
-  body.u8();
-  body.u8();
-  body.skip(body.u16());
-  body.text8();
-  body.nonZeroU64();
-  body.text8();
-  body.rid();
-  body.nonZeroU64();
-  const relocationOffset = body.offset;
-  body.bool8();
-  body.skip(body.u32());
-  const relocationEnd = body.offset;
-  const currentBody = bytes.subarray(11, 11 + bodyLength);
-  const nextBody = Buffer.concat([
-    currentBody.subarray(0, relocationOffset),
-    Buffer.from(relocationState),
-    currentBody.subarray(relocationEnd)
-  ]);
-  const envelope = Buffer.concat([
-    AUTHORITY_MAGIC,
-    Buffer.of(AUTHORITY_FORMAT_VERSION),
-    u16(AUTHORITY_FLAGS),
-    u32(nextBody.byteLength),
-    nextBody
-  ]);
-  return Buffer.concat([envelope, u32(crc32c(envelope))]);
-}
-
 export function encodeServiceUserSpotAuthorityPayload(
   value: ServiceUserSpotAuthorityPayload
 ): Buffer {

package/src/runtime/foundation/service-stateful-registry.ts

@@ -621,18 +621,19 @@ function createSpotState(
   }
 }
 
-export class ServiceTerminalOperationRegistry<T> {
-  private readonly operations: OperationRegistry<T>;
+export class ServiceTerminalOperationRegistry<T, Context = unknown> {
+  private readonly operations: OperationRegistry<T, Context>;
 
-  constructor(operations = new OperationRegistry<T>()) {
+  constructor(operations = new OperationRegistry<T, Context>()) {
     this.operations = operations;
   }
 
   register(
     timeoutMs: number,
-    timeoutOwner: 'registry' | 'sender' = 'registry'
+    timeoutOwner: 'registry' | 'sender' = 'registry',
+    context?: Context
   ): PendingOperation<T> {
-    return this.operations.register(timeoutMs, timeoutOwner);
+    return this.operations.register(timeoutMs, timeoutOwner, context);
   }
 
   reply(id: bigint, value: T): boolean {
@@ -651,6 +652,10 @@ export class ServiceTerminalOperationRegistry<T> {
     return this.operations.isPending(id);
   }
 
+  context(id: bigint): Context | undefined {
+    return this.operations.context(id);
+  }
+
   get size(): number {
     return this.operations.size;
   }