@zlink-systems/framework 0.20.0 → 0.22.0

package/src/runtime/host/relocation-direct-transfer.ts

@@ -56,10 +56,7 @@ export function planRelocationChunks(
     throw new RangeError('relocationPayloadChunkLimitBytes must be a positive integer.');
   }
   const totalLength = payload.byteLength;
-  let chunkBytes = Math.min(
-    configuredChunkLimitBytes,
-    RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES
-  );
+  let chunkBytes = Math.min(configuredChunkLimitBytes, RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES);
   if (Math.ceil(totalLength / chunkBytes) > RELOCATION_PAYLOAD_CHUNK_COUNT_MAX) {
     chunkBytes = Math.ceil(totalLength / RELOCATION_PAYLOAD_CHUNK_COUNT_MAX);
   }
@@ -117,9 +114,12 @@ export class ZLinkRelocationPayloadAssembly {
     if (!Number.isSafeInteger(totalLength) || totalLength < 0) {
       throw new RangeError('Relocation payload total length is invalid.');
     }
-    if (!Number.isInteger(chunkCount) || chunkCount < 0
-      || chunkCount > RELOCATION_PAYLOAD_CHUNK_COUNT_MAX
-      || (totalLength > 0 && chunkCount === 0)) {
+    if (
+      !Number.isInteger(chunkCount) ||
+      chunkCount < 0 ||
+      chunkCount > RELOCATION_PAYLOAD_CHUNK_COUNT_MAX ||
+      (totalLength > 0 && chunkCount === 0)
+    ) {
       throw new RangeError('Relocation payload chunk count is invalid.');
     }
     this.buffer = Buffer.alloc(totalLength);
@@ -134,9 +134,9 @@ export class ZLinkRelocationPayloadAssembly {
   accept(ordinal: number, data: Uint8Array): ZLinkRelocationChunkAcceptance {
     if (this.outcome !== undefined) {
       if ('error' in this.outcome) throw this.outcome.error;
-      return ordinal < this.chunkCount ? 'duplicate' : this.conflict(
-        `Relocation chunk ordinal ${ordinal} arrived after assembly completed.`
-      );
+      return ordinal < this.chunkCount
+        ? 'duplicate'
+        : this.conflict(`Relocation chunk ordinal ${ordinal} arrived after assembly completed.`);
     }
     if (ordinal < this.nextOrdinal) return 'duplicate';
     if (ordinal !== this.nextOrdinal || ordinal >= this.chunkCount) {
@@ -147,8 +147,10 @@ export class ZLinkRelocationPayloadAssembly {
     if (this.receivedBytes + data.byteLength > this.totalLength) {
       return this.conflict('Relocation chunks exceed the declared payload length.');
     }
-    if (ordinal === this.chunkCount - 1
-      && this.receivedBytes + data.byteLength !== this.totalLength) {
+    if (
+      ordinal === this.chunkCount - 1 &&
+      this.receivedBytes + data.byteLength !== this.totalLength
+    ) {
       return this.conflict('Relocation chunks do not cover the declared payload length.');
     }
     this.buffer.set(data, this.receivedBytes);
@@ -226,9 +228,7 @@ export class ZLinkRelocationInFlightBudget {
     if (!Number.isSafeInteger(bytes) || bytes < 0) {
       throw new RangeError('Relocation budget charge must be a non-negative integer.');
     }
-    while (this.limitBytes !== 0
-      && this.inFlight > 0
-      && this.inFlight + bytes > this.limitBytes) {
+    while (this.limitBytes !== 0 && this.inFlight > 0 && this.inFlight + bytes > this.limitBytes) {
       await this.waitForRelease(signal);
     }
     this.inFlight += bytes;

package/src/runtime/host/relocation-integrity-fault-gate.ts

@@ -1,6 +1,7 @@
 /** Internal E2E-only fault seam for direct relocation transfer integrity cases. */
-export const ZLINK_INTERNAL_RELOCATION_INTEGRITY_FAULT_GATE =
-  Symbol.for('zlink.internal.relocation-integrity-fault-gate');
+export const ZLINK_INTERNAL_RELOCATION_INTEGRITY_FAULT_GATE = Symbol.for(
+  'zlink.internal.relocation-integrity-fault-gate'
+);
 
 export interface ZLinkInternalRelocationIntegrityFaultGate {
   consumeChecksumMismatch(): boolean;

package/src/runtime/host/remote-actor-join-receiver.ts

@@ -15,11 +15,7 @@ import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
 } from '../framework-errors-internal';
-import {
-  normalizeRoutingId,
-  routingIdWireHex,
-  routingIdsEqual
-} from '../routing-id';
+import { normalizeRoutingId, routingIdWireHex, routingIdsEqual } from '../routing-id';
 
 export interface ZLinkCanonicalActorJoinAuthorityFence {
   readonly actorId: string;
@@ -81,14 +77,25 @@ export class ZLinkRemoteActorJoinReceiver {
       generation: BigInt(join.actorGeneration)
     };
     state.setNativeActorRef(actorRef as unknown as ZLinkBackendActorRef);
-    const refreshedTarget = mergeRemoteBoundSessionTarget({
-      routerChannelId: join.boundSessionRouterChannelId ?? join.routerChannelId ?? routeContext.channelName ?? '',
-      targetNodeRid: join.boundSessionTargetNodeRid ?? normalizeRoutingId(routeContext.sourceNodeRid),
-      spotId: join.boundSessionSpotId ?? join.sourceSpotId ?? normalizeRoutingId(routeContext.sourceNodeRid)
-    }, preferredRemoteBoundSessionTarget(
-      state.remoteBoundSessionTarget,
-      state.boundSessionTransferTarget
-    ));
+    const refreshedTarget = mergeRemoteBoundSessionTarget(
+      {
+        routerChannelId:
+          join.boundSessionRouterChannelId ??
+          join.routerChannelId ??
+          routeContext.channelName ??
+          '',
+        targetNodeRid:
+          join.boundSessionTargetNodeRid ?? normalizeRoutingId(routeContext.sourceNodeRid),
+        spotId:
+          join.boundSessionSpotId ??
+          join.sourceSpotId ??
+          normalizeRoutingId(routeContext.sourceNodeRid)
+      },
+      preferredRemoteBoundSessionTarget(
+        state.remoteBoundSessionTarget,
+        state.boundSessionTransferTarget
+      )
+    );
     state.setRemoteBoundSessionTarget(refreshedTarget);
     const request = RuntimeMessage.from(Buffer.from(join.request, 'base64'));
     try {
@@ -182,13 +189,13 @@ export class ZLinkRemoteActorJoinReceiver {
 
     const fence = decodeJoinAuthorityFence(join);
     if (
-      authority.allocation.state !== 'active'
-      || authority.allocation.objectKind !== 'actor'
-      || authority.objectGeneration !== fence.objectGeneration
-      || !routingIdsEqual(authority.allocation.descriptor.rid, join.actorNodeRid)
-      || authority.allocation.descriptorLifecycleGeneration !== fence.nodeGeneration
-      || authority.authorityOwnerGeneration !== fence.authorityOwnerGeneration
-      || authority.ownerLeaseGeneration !== fence.ownerLeaseGeneration
+      authority.allocation.state !== 'active' ||
+      authority.allocation.objectKind !== 'actor' ||
+      authority.objectGeneration !== fence.objectGeneration ||
+      !routingIdsEqual(authority.allocation.descriptor.rid, join.actorNodeRid) ||
+      authority.allocation.descriptorLifecycleGeneration !== fence.nodeGeneration ||
+      authority.authorityOwnerGeneration !== fence.authorityOwnerGeneration ||
+      authority.ownerLeaseGeneration !== fence.ownerLeaseGeneration
     ) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.RequestProtocolError,
@@ -199,14 +206,16 @@ export class ZLinkRemoteActorJoinReceiver {
   }
 }
 
-type JoinAuthorityFence = ZLinkCanonicalActorJoinAuthorityFence | {
-  readonly actorId: string;
-  readonly actorNodeRid: RoutingId;
-  readonly actorGeneration: string;
-  readonly actorNodeGeneration: string;
-  readonly expectedAuthorityOwnerGeneration: string;
-  readonly expectedOwnerLeaseGeneration: string;
-};
+type JoinAuthorityFence =
+  | ZLinkCanonicalActorJoinAuthorityFence
+  | {
+      readonly actorId: string;
+      readonly actorNodeRid: RoutingId;
+      readonly actorGeneration: string;
+      readonly actorNodeGeneration: string;
+      readonly expectedAuthorityOwnerGeneration: string;
+      readonly expectedOwnerLeaseGeneration: string;
+    };
 
 function hasAuthorityFence(
   join: ReturnType<typeof decodeRemoteActorJoinPayload>
@@ -220,10 +229,10 @@ function hasAuthorityFence(
     join.expectedAuthorityOwnerGeneration,
     join.expectedOwnerLeaseGeneration
   ];
-  if (fields.every(value => value === undefined)) {
+  if (fields.every((value) => value === undefined)) {
     return false;
   }
-  if (fields.some(value => value === undefined)) {
+  if (fields.some((value) => value === undefined)) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestProtocolError,
       `Actor '${join.actorId}' Join carries an incomplete Authority fence.`
@@ -257,10 +266,10 @@ function decodeJoinAuthorityFence(join: JoinAuthorityFence): {
   // object/owner generations are bounded counters; the MeshNode lifecycle is
   // an opaque full-range token, for which only zero denotes absence.
   if (
-    objectGeneration <= 0n
-    || nodeGeneration === 0n
-    || authorityOwnerGeneration <= 0n
-    || ownerLeaseGeneration <= 0n
+    objectGeneration <= 0n ||
+    nodeGeneration === 0n ||
+    authorityOwnerGeneration <= 0n ||
+    ownerLeaseGeneration <= 0n
   ) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestProtocolError,

package/src/runtime/host/remote-actor-packet-target-store.ts

@@ -1,14 +1,6 @@
-import type {
-  ActorRef,
-  RoutingId,
-  SpotId,
-  ZLinkSessionActor
-} from '../../contracts';
+import type { ActorRef, RoutingId, SpotId, ZLinkSessionActor } from '../../contracts';
 import { ZLinkSpotKind } from '../../contracts';
-import type {
-  DefaultZLinkActorManager,
-  ZLinkRemoteActorPacketTarget
-} from '../actors';
+import type { DefaultZLinkActorManager, ZLinkRemoteActorPacketTarget } from '../actors';
 import type { ZLinkStreamActorLookupPort } from '../streams/stream-binding-runtime-ports';
 import { decodeRemoteActorPacketTarget } from '../actors/actor-packet-relay-wire';
 import { normalizeRoutingId as normalizeRuntimeRoutingId } from '../routing-id';
@@ -29,15 +21,25 @@ interface ZLinkSessionActorPacketTargetCacheEntry {
 }
 
 export class ZLinkRemoteActorPacketTargetStore {
-  private readonly sessionActorPacketTargets =
-    new WeakMap<ZLinkSessionActor, ZLinkSessionActorPacketTargetCacheEntry>();
-  private readonly sessionActorPacketTargetsByActor = new Map<string, ZLinkRemoteActorPacketTarget>();
-  private readonly sessionActorPacketTargetsByActorId =
-    new Map<string, ZLinkSessionActorPacketTargetCacheEntry>();
-  private readonly sessionActorPacketTargetOwners = new Map<string, {
-    readonly actors: Set<ZLinkSessionActor>;
-    readonly keys: Set<string>;
-  }>();
+  private readonly sessionActorPacketTargets = new WeakMap<
+    ZLinkSessionActor,
+    ZLinkSessionActorPacketTargetCacheEntry
+  >();
+  private readonly sessionActorPacketTargetsByActor = new Map<
+    string,
+    ZLinkRemoteActorPacketTarget
+  >();
+  private readonly sessionActorPacketTargetsByActorId = new Map<
+    string,
+    ZLinkSessionActorPacketTargetCacheEntry
+  >();
+  private readonly sessionActorPacketTargetOwners = new Map<
+    string,
+    {
+      readonly actors: Set<ZLinkSessionActor>;
+      readonly keys: Set<string>;
+    }
+  >();
 
   constructor(private readonly options: ZLinkRemoteActorPacketTargetStoreOptions) {}
 
@@ -61,17 +63,14 @@ export class ZLinkRemoteActorPacketTargetStore {
     return decodeRemoteActorPacketTarget(value);
   }
 
-  clear(
-    actorId: string,
-    expectedTenureKey?: string,
-    expectedActor?: ZLinkSessionActor
-  ): void {
+  clear(actorId: string, expectedTenureKey?: string, expectedActor?: ZLinkSessionActor): void {
     if (
-      expectedTenureKey !== undefined
-      && (expectedActor === undefined
-        || expectedActor.actorId !== actorId
-        || this.tenureKeyForActor(expectedActor) !== expectedTenureKey)
-    ) return;
+      expectedTenureKey !== undefined &&
+      (expectedActor === undefined ||
+        expectedActor.actorId !== actorId ||
+        this.tenureKeyForActor(expectedActor) !== expectedTenureKey)
+    )
+      return;
     const state = this.options.actorManager()?.getState(actorId);
     if (typeof state?.setRemoteActorPacketTarget === 'function') {
       state.setRemoteActorPacketTarget(undefined);
@@ -93,18 +92,23 @@ export class ZLinkRemoteActorPacketTargetStore {
     const routeKey = sessionActorPacketTargetTenureKey(actor);
     const actorEntry = this.sessionActorPacketTargets.get(actor);
     const actorIdEntry = this.sessionActorPacketTargetsByActorId.get(actor.actorId);
-    return (actorEntry?.routeKey === routeKey ? actorEntry.target : undefined)
-      ?? this.sessionActorPacketTargetsByActor.get(routeKey)
-      ?? (actorIdEntry?.routeKey === routeKey ? actorIdEntry.target : undefined)
-      ?? this.targetForActorRef(actor.ref);
+    return (
+      (actorEntry?.routeKey === routeKey ? actorEntry.target : undefined) ??
+      this.sessionActorPacketTargetsByActor.get(routeKey) ??
+      (actorIdEntry?.routeKey === routeKey ? actorIdEntry.target : undefined) ??
+      this.targetForActorRef(actor.ref)
+    );
   }
 
-  targetForState(actorId: string, routerChannelIdHint?: string): ZLinkRemoteActorPacketTarget | undefined {
+  targetForState(
+    actorId: string,
+    routerChannelIdHint?: string
+  ): ZLinkRemoteActorPacketTarget | undefined {
     const state = this.options.actorManager()?.getState(actorId);
     if (
       state?.remoteActorPacketTarget !== undefined &&
-      (state.spotId === undefined
-        || routingIdsEqual(state.remoteActorPacketTarget.spotId, state.spotId))
+      (state.spotId === undefined ||
+        routingIdsEqual(state.remoteActorPacketTarget.spotId, state.spotId))
     ) {
       return state.remoteActorPacketTarget;
     }
@@ -122,11 +126,12 @@ export class ZLinkRemoteActorPacketTargetStore {
       return undefined;
     }
     const actorRef = state?.nativeActorRef as ActorRef | undefined;
-    const targetNodeRid = actorRef?.nodeRid as RoutingId | undefined
-      ?? this.options.primaryNodeRid();
-    const routerChannelId = routerChannelIdHint
-      ?? this.options.meshRouters.defaultSpotRouterChannelId()
-      ?? this.options.meshRouters.defaultRouterChannelId();
+    const targetNodeRid =
+      (actorRef?.nodeRid as RoutingId | undefined) ?? this.options.primaryNodeRid();
+    const routerChannelId =
+      routerChannelIdHint ??
+      this.options.meshRouters.defaultSpotRouterChannelId() ??
+      this.options.meshRouters.defaultRouterChannelId();
     const localNodeRid = this.options.primaryNodeRid();
     if (
       spotId === undefined &&
@@ -144,9 +149,7 @@ export class ZLinkRemoteActorPacketTargetStore {
       targetNodeRid: normalizeRuntimeRoutingId(targetNodeRid),
       spotId: validateSpotId(spotId),
       spotKind: ZLinkSpotKind.User,
-      ...(state?.spotGeneration === undefined
-        ? {}
-        : { targetSpotGeneration: state.spotGeneration })
+      ...(state?.spotGeneration === undefined ? {} : { targetSpotGeneration: state.spotGeneration })
     };
   }
 
@@ -157,10 +160,11 @@ export class ZLinkRemoteActorPacketTargetStore {
       return undefined;
     }
     const meshName = actorRef.meshName;
-    const routerChannelId = meshName.trim().length === 0
-      ? this.options.meshRouters.defaultSpotRouterChannelId()
-        ?? this.options.meshRouters.defaultRouterChannelId()
-      : this.options.spotRouterChannelIdForMesh(meshName);
+    const routerChannelId =
+      meshName.trim().length === 0
+        ? (this.options.meshRouters.defaultSpotRouterChannelId() ??
+          this.options.meshRouters.defaultRouterChannelId())
+        : this.options.spotRouterChannelIdForMesh(meshName);
     if (routerChannelId === undefined) {
       return undefined;
     }
@@ -185,10 +189,8 @@ export class ZLinkRemoteActorPacketTargetStore {
     target: ZLinkRemoteActorPacketTarget,
     expectedTenureKey?: string
   ): void {
-    if (
-      expectedTenureKey !== undefined
-      && this.tenureKeyForActor(actor) !== expectedTenureKey
-    ) return;
+    if (expectedTenureKey !== undefined && this.tenureKeyForActor(actor) !== expectedTenureKey)
+      return;
     const state = this.options.actorManager()?.getState(actor.actorId);
     if (typeof state?.setRemoteActorPacketTarget === 'function') {
       state.setRemoteActorPacketTarget(target);