@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/abort.ts

@@ -38,15 +38,15 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
   }
 }
 
+export function macrotaskBoundary(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
 export function awaitWithAbort<T>(
   operation: Promise<T>,
   signal: AbortSignal | undefined,
   abortOperation?: () => void
 ): Promise<T> {
-  if (signal?.aborted === true) {
-    abortOperation?.();
-    throw createAbortError();
-  }
   if (signal === undefined) {
     return operation;
   }
@@ -63,7 +63,6 @@ export function awaitWithAbort<T>(
       abortOperation?.();
       reject(createAbortError());
     };
-    signal.addEventListener('abort', abort, { once: true });
     operation.then(
       (value) => {
         if (settle()) resolve(value);
@@ -72,5 +71,7 @@ export function awaitWithAbort<T>(
         if (settle()) reject(error);
       }
     );
+    if (signal.aborted) abort();
+    else signal.addEventListener('abort', abort, { once: true });
   });
 }

package/src/runtime/activation-admission.ts

@@ -0,0 +1,72 @@
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from './framework-errors-internal';
+
+/** Current activation admission count and limit of one MeshNode. */
+export interface ZLinkActivationConcurrency {
+  readonly active: number;
+  readonly limit: number;
+}
+
+interface ZLinkActivationRecord {
+  readonly limit: number;
+  active: number;
+}
+
+/**
+ * MeshNode §5.1 "Pending activation": the single per-MeshNode record of activation admissions.
+ *
+ * Actor creation, User Spot creation, Instance Spot cold activation and a relocation target's
+ * Restore each hold one admission from the moment the target MeshNode receives the operation
+ * until Ready or its target commit, or until it ends by rejection, failure or cleanup. Entry Spot
+ * and Actor Join never acquire one. The limit is enforced here, and the status current value and
+ * the placement `IsAvailable` headroom both read this record.
+ */
+export class ZLinkActivationAdmission {
+  private readonly records = new Map<string, ZLinkActivationRecord>();
+
+  constructor(private readonly limitOf: (meshName: string) => number) {}
+
+  current(meshName: string): ZLinkActivationConcurrency {
+    const record = this.records.get(meshName);
+    return { active: record?.active ?? 0, limit: record?.limit ?? this.limitOf(meshName) };
+  }
+
+  hasHeadroom(meshName: string): boolean {
+    const { active, limit } = this.current(meshName);
+    return active < limit;
+  }
+
+  /**
+   * Holds one admission for `meshName`. A MeshNode without headroom does not accept a new
+   * admission (MeshNode §5.1): the operation fails as Unavailable at once. The returned release
+   * is idempotent.
+   */
+  async acquire(meshName: string, signal?: AbortSignal): Promise<() => void> {
+    signal?.throwIfAborted();
+    const record = this.record(meshName);
+    if (record.active >= record.limit) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted,
+        `MeshNode '${meshName}' has no activation admission headroom.`
+      );
+    }
+    record.active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      record.active -= 1;
+    };
+  }
+
+  private record(meshName: string): ZLinkActivationRecord {
+    let record = this.records.get(meshName);
+    if (record === undefined) {
+      record = { limit: this.limitOf(meshName), active: 0 };
+      this.records.set(meshName, record);
+    }
+    return record;
+  }
+}

package/src/runtime/actors/actor-authority-payload-codec.ts

@@ -1,13 +1,29 @@
-import type { RoutingId } from '../../contracts';
-import { ZLinkSpotKind, zlinkSpotKindFromWire, zlinkSpotKindToWire } from '../../contracts';
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
+import {
+  type RoutingId,
+  ZLinkSpotKind,
+  zlinkSpotKindFromWire,
+  zlinkSpotKindToWire
+} from '../../contracts';
+
+import { ZLINK_MAX_ROUTING_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { AUTHORITY_ENVELOPE_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 import { crc32c } from '../foundation/service-relocation-runtime';
+import { SERVICE_WIRE_TEXT8_MAX_BYTES } from '../foundation/service-wire-binary-primitives';
 import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
 
 const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_VERSION = 1;
 const AUTHORITY_FLAGS = 0;
 const ACTOR_RELOCATION_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x50]);
-const MAXIMUM_BYTES = 1024 * 1024;
+const AUTHORITY_MINIMUM_BYTES = 15;
+const ACTOR_RELOCATION_MINIMUM_BYTES = 32;
+const ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE = 5;
+const ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE = 6;
+const ACTOR_RELOCATION_FIRST_PHASE = 1;
+const ACTOR_RELOCATION_STEADY_PHASE = 4;
+const ENTRY_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.Entry);
+const USER_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.User);
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 
 export type ZLinkActorAuthorityState = 'creating' | 'ready';
@@ -47,8 +63,10 @@ export function encodeCanonicalAuthorityPayload(value: ZLinkCanonicalAuthorityPa
     body
   );
   const encoded = concat(envelope, u32be(crc32c(envelope)));
-  if (encoded.byteLength > MAXIMUM_BYTES) {
-    throw new RangeError('Actor authority payload exceeds 1 MiB.');
+  if (encoded.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new RangeError(
+      `Actor authority payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return encoded;
 }
@@ -59,7 +77,10 @@ export function decodeCanonicalAuthorityPayload(
 ): ZLinkCanonicalAuthorityPayload | undefined {
   try {
     const reader = new BigEndianReader(payload);
-    if (reader.bytes.byteLength < 15 || reader.bytes.byteLength > MAXIMUM_BYTES) {
+    if (
+      reader.bytes.byteLength < AUTHORITY_MINIMUM_BYTES ||
+      reader.bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES
+    ) {
       return undefined;
     }
     reader.expect(AUTHORITY_MAGIC);
@@ -81,7 +102,7 @@ export function decodeCanonicalAuthorityPayload(
 /** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.Encode. */
 export function encodeActorAuthorityPayload(value: ZLinkActorAuthorityPayload): Buffer {
   const spotKind = zlinkSpotKindToWire(value.currentSpotKind);
-  if (spotKind !== 1 && spotKind !== 2) {
+  if (spotKind !== ENTRY_SPOT_WIRE_KIND && spotKind !== USER_SPOT_WIRE_KIND) {
     throw new RangeError('Actor currentSpotKind must be Entry or User.');
   }
   const actor = concat(
@@ -173,7 +194,7 @@ export function actorRelocationAuthorityApplicationPayload(
   const current = decodeActorRelocationEnvelope(payload);
   return current === undefined
     ? Buffer.from(payload)
-    : current.phase === 4
+    : current.phase === ACTOR_RELOCATION_STEADY_PHASE
       ? Buffer.from(current.applicationPayload)
       : undefined;
 }
@@ -196,8 +217,10 @@ export function replaceActorRelocationAuthorityApplicationPayload(
     applicationPayload
   );
   const encoded = concat(withoutChecksum, u32le(crc32c(withoutChecksum)));
-  if (encoded.byteLength > MAXIMUM_BYTES) {
-    throw new RangeError('Actor relocation authority payload exceeds 1 MiB.');
+  if (encoded.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new RangeError(
+      `Actor relocation authority payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return encoded;
 }
@@ -205,7 +228,11 @@ export function replaceActorRelocationAuthorityApplicationPayload(
 function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnvelope | undefined {
   try {
     const bytes = Buffer.from(payload);
-    if (bytes.byteLength < 32 || bytes.byteLength > MAXIMUM_BYTES) return undefined;
+    if (
+      bytes.byteLength < ACTOR_RELOCATION_MINIMUM_BYTES ||
+      bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES
+    )
+      return undefined;
     const checksumOffset = bytes.byteLength - 4;
     if (bytes.readUInt32LE(checksumOffset) !== crc32c(bytes.subarray(0, checksumOffset))) {
       return undefined;
@@ -213,10 +240,15 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
     const reader = new LittleEndianReader(bytes.subarray(0, checksumOffset));
     reader.expect(ACTOR_RELOCATION_MAGIC);
     const version = reader.u16();
-    if (version !== 5 && version !== 6) return undefined;
+    if (
+      version !== ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE &&
+      version !== ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE
+    )
+      return undefined;
     if (reader.take(16).every((byte) => byte === 0)) return undefined;
     const phase = reader.u8();
-    if (phase < 1 || phase > 4) return undefined;
+    if (phase < ACTOR_RELOCATION_FIRST_PHASE || phase > ACTOR_RELOCATION_STEADY_PHASE)
+      return undefined;
     const isBound = reader.bool();
     if (isBound) {
       reader.bytes8();
@@ -230,7 +262,7 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
       const ownerLeaseGeneration = reader.u64();
       const sessionOwnerNodeGeneration = reader.u64();
       reader.u64();
-      if (version === 6) {
+      if (version === ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE) {
         reader.text16();
         reader.u64();
       }
@@ -247,7 +279,7 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
     }
     const prefix = Buffer.from(reader.bytes.subarray(0, reader.offset));
     const applicationLength = reader.i32();
-    if (applicationLength < 1 || applicationLength > MAXIMUM_BYTES) return undefined;
+    if (applicationLength < 1 || applicationLength > AUTHORITY_ENVELOPE_MAX_BYTES) return undefined;
     const applicationPayload = Buffer.from(reader.take(applicationLength));
     if (!reader.done) return undefined;
     return { prefix, phase, applicationPayload };
@@ -258,22 +290,28 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
 
 function text8(value: string, name: string): Buffer {
   const bytes = Buffer.from(value, 'utf8');
-  if (bytes.byteLength < 1 || bytes.byteLength > 0xff || bytes.includes(0)) {
-    throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+  if (
+    bytes.byteLength < 1 ||
+    bytes.byteLength > SERVICE_WIRE_TEXT8_MAX_BYTES ||
+    bytes.includes(0)
+  ) {
+    throw new RangeError(
+      `${name} must contain 1..${SERVICE_WIRE_TEXT8_MAX_BYTES} UTF-8 bytes without NUL.`
+    );
   }
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
 function rid(value: RoutingId, name: string): Buffer {
   const bytes = Buffer.from(encodeRoutingIdStorageHex(value), 'hex');
-  if (bytes.byteLength < 1 || bytes.byteLength > 0xff) {
-    throw new RangeError(`${name} must contain 1..255 bytes.`);
+  if (bytes.byteLength < 1 || bytes.byteLength > ZLINK_MAX_ROUTING_ID_BYTES) {
+    throw new RangeError(`${name} must contain 1..${ZLINK_MAX_ROUTING_ID_BYTES} bytes.`);
   }
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
 function nonzeroU64be(value: bigint, name: string): Buffer {
-  if (value === 0n || value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value === 0n || value < 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be a non-zero u64.`);
   }
   const result = Buffer.alloc(8);