@zlink-systems/framework 0.30.0 → 0.30.1

package/src/contracts/Handlers/JsonContract.ts

@@ -1,216 +1,8 @@
-const MAX_CONTRACT_SCHEMA_DEPTH = 64;
-
-/** Describes the fields accepted by the default framework-json-v1 serializer. */
-export type ZLinkJsonSchema =
-  | { readonly type: 'boolean' }
-  | { readonly type: 'string' }
-  | { readonly type: 'number' }
-  | { readonly type: 'int32' }
-  | { readonly type: 'uint32' }
-  | { readonly type: 'int64' }
-  | { readonly type: 'uint64' }
-  | { readonly type: 'bytes' }
-  | { readonly type: 'enum'; readonly names: readonly string[] }
-  | { readonly type: 'nullable'; readonly value: ZLinkJsonSchema }
-  | { readonly type: 'array'; readonly items: ZLinkJsonSchema }
-  | { readonly type: 'record'; readonly values: ZLinkJsonSchema }
-  | {
-      readonly type: 'object';
-      readonly properties: Readonly<Record<string, ZLinkJsonSchema>>;
-      readonly required: readonly string[];
-      /** Unknown properties are ignored during decoding unless this is false. */
-      readonly additionalProperties?: boolean;
-    };
-
-/**
- * Describes the request and optional reply fields carried under one packet
- * name by the default JSON serializer.
- */
-export interface ZLinkPacketJsonContract {
-  readonly payload: ZLinkJsonSchema;
-  readonly reply?: ZLinkJsonSchema;
-}
-
-const ZLINK_PACKET_JSON_CONTRACTS = Symbol.for('@zlink-systems/framework:packet-json-contracts');
-
-export function defineZLinkPacketJsonContract(
-  packetName: string,
-  contract: ZLinkPacketJsonContract
-): ZLinkPacketJsonContract {
-  if (packetName.trim().length === 0) {
-    throw new TypeError('ZLink packet name must not be empty.');
-  }
-  const runtimeContract: unknown = contract;
-  if (typeof runtimeContract !== 'object' || runtimeContract === null) {
-    throw new TypeError('ZLink packet JSON contract must be an object.');
-  }
-  const normalizedContract = runtimeContract as ZLinkPacketJsonContract;
-  const normalized = Object.freeze({
-    payload: normalizeJsonSchema(normalizedContract.payload, new Set(), 0),
-    ...(normalizedContract.reply === undefined
-      ? {}
-      : { reply: normalizeJsonSchema(normalizedContract.reply, new Set(), 0) })
-  });
-  const contracts = packetJsonContracts();
-  const current = contracts.get(packetName);
-  if (current !== undefined && canonicalContract(current) !== canonicalContract(normalized)) {
-    throw new TypeError(
-      `ZLink packet '${packetName}' has conflicting JSON contracts in one process.`
-    );
-  }
-  if (current !== undefined) return current;
-  contracts.set(packetName, normalized);
-  return normalized;
-}
-
-export function readZLinkPacketJsonContract(
-  packetName: string
-): ZLinkPacketJsonContract | undefined {
-  return packetJsonContracts().get(packetName);
-}
-
-function normalizeJsonSchema(
-  schema: ZLinkJsonSchema,
-  parents: Set<object>,
-  depth: number
-): ZLinkJsonSchema {
-  // Keep the runtime boundary defensive for JavaScript callers even though
-  // the TypeScript signature describes the accepted shape.
-  const runtimeSchema: unknown = schema;
-  if (
-    typeof runtimeSchema !== 'object' ||
-    runtimeSchema === null ||
-    depth > MAX_CONTRACT_SCHEMA_DEPTH
-  ) {
-    throw new TypeError(
-      `ZLink packet JSON schema must be an acyclic object with at most ${MAX_CONTRACT_SCHEMA_DEPTH} levels.`
-    );
-  }
-  const normalizedSchema = runtimeSchema as ZLinkJsonSchema;
-  if (parents.has(normalizedSchema))
-    throw new TypeError('ZLink packet JSON schema must not contain a cycle.');
-  const nextParents = new Set(parents).add(normalizedSchema);
-  switch (normalizedSchema.type) {
-    case 'boolean':
-    case 'string':
-    case 'number':
-    case 'int32':
-    case 'uint32':
-    case 'int64':
-    case 'uint64':
-    case 'bytes':
-      return Object.freeze({ type: normalizedSchema.type });
-    case 'enum': {
-      if (
-        !Array.isArray(normalizedSchema.names) ||
-        normalizedSchema.names.length === 0 ||
-        normalizedSchema.names.some((name) => typeof name !== 'string' || name.length === 0)
-      ) {
-        throw new TypeError('ZLink packet enum schema requires non-empty string names.');
-      }
-      if (new Set(normalizedSchema.names).size !== normalizedSchema.names.length) {
-        throw new TypeError('ZLink packet enum schema names must be unique.');
-      }
-      return Object.freeze({ type: 'enum', names: Object.freeze([...normalizedSchema.names]) });
-    }
-    case 'nullable':
-      return Object.freeze({
-        type: 'nullable',
-        value: normalizeJsonSchema(normalizedSchema.value, nextParents, depth + 1)
-      });
-    case 'array':
-      return Object.freeze({
-        type: 'array',
-        items: normalizeJsonSchema(normalizedSchema.items, nextParents, depth + 1)
-      });
-    case 'record':
-      return Object.freeze({
-        type: 'record',
-        values: normalizeJsonSchema(normalizedSchema.values, nextParents, depth + 1)
-      });
-    case 'object': {
-      const runtimeProperties: unknown = normalizedSchema.properties;
-      if (
-        typeof runtimeProperties !== 'object' ||
-        runtimeProperties === null ||
-        Array.isArray(runtimeProperties)
-      ) {
-        throw new TypeError('ZLink packet object schema properties must be an object.');
-      }
-      if (
-        !Array.isArray(normalizedSchema.required) ||
-        normalizedSchema.required.some((name) => typeof name !== 'string' || name.length === 0)
-      ) {
-        throw new TypeError('ZLink packet object schema required must contain property names.');
-      }
-      if (
-        normalizedSchema.additionalProperties !== undefined &&
-        typeof normalizedSchema.additionalProperties !== 'boolean'
-      ) {
-        throw new TypeError('ZLink packet object schema additionalProperties must be boolean.');
-      }
-      const properties: Record<string, ZLinkJsonSchema> = {};
-      for (const [name, property] of Object.entries(
-        runtimeProperties as Record<string, ZLinkJsonSchema>
-      )) {
-        if (isPrototypeKey(name)) {
-          throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
-        }
-        properties[name] = normalizeJsonSchema(property, nextParents, depth + 1);
-      }
-      if (new Set(normalizedSchema.required).size !== normalizedSchema.required.length) {
-        throw new TypeError('ZLink packet JSON required properties must be unique.');
-      }
-      for (const name of normalizedSchema.required) {
-        if (isPrototypeKey(name)) {
-          throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
-        }
-        if (!Object.prototype.hasOwnProperty.call(properties, name)) {
-          throw new TypeError(
-            `ZLink packet JSON required property '${name}' has no property schema.`
-          );
-        }
-      }
-      return Object.freeze({
-        type: 'object',
-        properties: Object.freeze(properties),
-        required: Object.freeze([...normalizedSchema.required]),
-        ...(normalizedSchema.additionalProperties === undefined
-          ? {}
-          : { additionalProperties: normalizedSchema.additionalProperties })
-      });
-    }
-  }
-  throw new TypeError(
-    `ZLink packet JSON schema type '${String((normalizedSchema as { type?: unknown }).type)}' is not supported.`
-  );
-}
-
-function packetJsonContracts(): Map<string, ZLinkPacketJsonContract> {
-  const root = globalThis as typeof globalThis & Record<symbol, unknown>;
-  let contracts = root[ZLINK_PACKET_JSON_CONTRACTS] as
-    Map<string, ZLinkPacketJsonContract> | undefined;
-  if (contracts === undefined) {
-    contracts = new Map();
-    Object.defineProperty(root, ZLINK_PACKET_JSON_CONTRACTS, {
-      configurable: false,
-      enumerable: false,
-      value: contracts,
-      writable: false
-    });
-  }
-  return contracts;
-}
-
-function canonicalContract(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalContract).join(',')}]`;
-  if (typeof value !== 'object' || value === null) return JSON.stringify(value);
-  return `{${Object.entries(value as Record<string, unknown>)
-    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-    .map(([key, item]) => `${JSON.stringify(key)}:${canonicalContract(item)}`)
-    .join(',')}}`;
-}
-
-function isPrototypeKey(name: string): boolean {
-  return name === '__proto__' || name === 'prototype' || name === 'constructor';
-}
+export {
+  defineZLinkPacketJsonContract,
+  readZLinkPacketJsonContract
+} from '@zlink-systems/stream-wire/internal/json';
+export type {
+  ZLinkJsonSchema,
+  ZLinkPacketJsonContract
+} from '@zlink-systems/stream-wire/internal/json';

package/src/contracts/Spots/Contracts.ts

@@ -2,6 +2,7 @@ import type { ZLinkActor } from '../Actors';
 import type { ZLinkChannelRequestCall, ZLinkPublishCall, ZLinkSendCall } from '../Channels';
 import type { RoutingId, SpotId, Type, ZLinkMessageMetadata } from '../Common';
 import type { ZLinkSpotTimerHandler } from '../Handlers';
+import type { ZLinkRequest } from '../Handlers/Attributes';
 import type { ZLinkTimer, ZLinkTimerOptions } from '../Timers';
 import type {
   ZLinkEntrySpot,
@@ -106,7 +107,7 @@ export interface ZLinkSpotRequestCall {
   instanceSpot(instanceSpotType: string): this;
   inMesh(meshName: string): this;
   timeout(timeoutMs: number): this;
-  submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply>;
   yield<TReply>(signal?: AbortSignal): Promise<TReply>;
 }
 

package/src/nest-integration.ts

@@ -77,6 +77,7 @@ export {
   type ZLinkHandlerFilterScopeRunner
 } from './runtime/channels/handler-filter-scope';
 export {
+  registerHandlerInstanceScopeFactory as registerIntegrationHandlerInstanceScopeFactory,
   disposeOwnedInstance as disposeIntegrationHandler,
   disposeOwnedInstances as disposeIntegrationHandlers
 } from './runtime/handlers/handler-instance-scope';

package/src/runtime/actors/actor-client.ts

@@ -1,4 +1,6 @@
 import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
+import { createZLinkRequest } from '../messaging/request-result';
+import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
 import {
   type ActorRef,
   type RoutingId,
@@ -89,7 +91,8 @@ export interface ZLinkActorClientOptions {
     parts: readonly Message[],
     returnResponse: boolean,
     actor: ActorRef,
-    deadlineUnixMs?: number
+    deadlineUnixMs?: number,
+    onAdmitted?: () => void
   ) => Promise<unknown> | undefined;
   readonly sendErrorReporter?: (error: unknown) => void;
   readonly routeTransport?: ZLinkActorRoutedJoinTransport;
@@ -118,8 +121,17 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   requestToActor(actorId: string, request: unknown): ZLinkActorRequestCall {
     requireActorId(actorId);
     return new DefaultZLinkActorRequestCall(
-      (packetName, timeoutMs, metadata, signal) =>
-        this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'async'),
+      (packetName, timeoutMs, metadata, signal, onAdmitted) =>
+        this.request(
+          actorId,
+          packetName,
+          request,
+          timeoutMs,
+          metadata,
+          signal,
+          'async',
+          onAdmitted
+        ),
       (packetName, timeoutMs, metadata, signal) =>
         this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'yield'),
       actorId,
@@ -211,7 +223,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     timeoutMs: number | undefined,
     metadata: ReadonlyMap<string, string>,
     signal?: AbortSignal,
-    waitPolicy: 'async' | 'yield' = 'async'
+    waitPolicy: 'async' | 'yield' = 'async',
+    onAdmitted?: () => void
   ): Promise<TReply> {
     throwIfAborted(signal);
     const sourceSpotId = currentZLinkActorExecution()?.spotId ?? currentZLinkSpotSerialSourceId();
@@ -267,7 +280,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         parts,
         true,
         routedActor,
-        deadlineUnixMs
+        deadlineUnixMs,
+        onAdmitted
       );
       if (handoff !== undefined) {
         const submissions = [handoff];
@@ -278,7 +292,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
             parts,
             true,
             routedActor,
-            deadlineUnixMs
+            deadlineUnixMs,
+            onAdmitted
           );
           if (duplicate !== undefined) submissions.push(duplicate);
         }
@@ -297,7 +312,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         remainingActorRequestTimeout(actorId, deadlineMs),
         signal,
         route,
-        messageFollow
+        messageFollow,
+        onAdmitted
       );
     } catch (error) {
       if (isStaleActorError(error)) {
@@ -423,7 +439,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     route?: ZLinkResolvedActorRoute,
-    messageFollowContext?: ZLinkActorMessageFollowContext
+    messageFollowContext?: ZLinkActorMessageFollowContext,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     const node = this.requireNode(meshName);
     if (
@@ -459,7 +476,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         this.options.routeTransport,
         remoteActorRouteTarget(route),
         relay,
-        { timeoutMs, signal },
+        { timeoutMs, signal, onAdmitted },
         `Remote Actor request is not available for '${actor.actorId}'.`,
         (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}')
       );
@@ -481,7 +498,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       () =>
         node.requestToActor(actor, toMessageLikeParts(parts), {
           flags: ZLINK_BACKEND_SEND_NONE,
-          timeoutMs
+          timeoutMs,
+          onAdmitted
         }),
       signal
     );
@@ -700,7 +718,8 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
       packetName: string | undefined,
       timeoutMs: number | undefined,
       metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      signal?: AbortSignal,
+      onAdmitted?: () => void
     ) => Promise<TReply>,
     private readonly yieldSubmitter: <TReply>(
       packetName: string | undefined,
@@ -728,8 +747,9 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
     return this;
   }
 
-  submit<TReply>(signal?: AbortSignal): Promise<TReply> {
-    return this.execute<TReply>('async', signal);
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply> {
+    this.rejectSelfActorRequest();
+    return createZLinkRequest((onAdmitted) => this.execute<TReply>('async', signal, onAdmitted));
   }
 
   yield<TReply>(signal?: AbortSignal): Promise<TReply> {
@@ -739,9 +759,12 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
     return turn.yieldPromise(pending);
   }
 
-  private execute<TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal): Promise<TReply> {
+  private execute<TReply>(
+    waitPolicy: 'async' | 'yield',
+    signal?: AbortSignal,
+    onAdmitted?: () => void
+  ): Promise<TReply> {
     ensureSingleSubmit(this.executed);
-    this.rejectSelfActorRequest();
     this.executed = true;
     throwIfAborted(signal);
     const submitter = waitPolicy === 'async' ? this.asyncSubmitter : this.yieldSubmitter;
@@ -749,7 +772,8 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
       this.packet ?? resolveFrameworkPacketName(this.request, undefined, 'Actor'),
       this.timeoutMs ?? this.defaultRequestTimeoutMs,
       this.selectedMetadata,
-      signal
+      signal,
+      onAdmitted
     );
   }
 

package/src/runtime/actors/actor-handoff.ts

@@ -776,7 +776,8 @@ export class ZLinkActorHandoffCoordinator {
     fallbackActorRef?: ActorRef,
     deadlineUnixMs?: number,
     messageFollowOrigin?: ZLinkMessageFollowOrigin,
-    provisionalReplay?: ZLinkActorHandoffDispatch
+    provisionalReplay?: ZLinkActorHandoffDispatch,
+    onAdmitted?: () => void
   ): Promise<unknown> | undefined {
     const incomingContext = actorMessageFollowContext(fallbackActorRef);
     const originalDeadlineUnixMs =
@@ -871,6 +872,7 @@ export class ZLinkActorHandoffCoordinator {
         });
       });
       releaseApplicationJobPermitForDurableHandoff();
+      onAdmitted?.();
       if (handoff.prefixRelease !== undefined) {
         try {
           this.admitPendingPrefix(actorId, handoff, handoff.prefixRelease);
@@ -916,7 +918,7 @@ export class ZLinkActorHandoffCoordinator {
               incomingContext,
               messageFollowOrigin
             );
-            return this.enqueueMessageFollow(followRoute, actorId, packet);
+            return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
           }
           this.options.onMarker?.('message_follow_rejected', actorId);
           return Promise.reject(actorLocationStale(actorId));
@@ -973,7 +975,7 @@ export class ZLinkActorHandoffCoordinator {
       context,
       messageFollowOrigin
     );
-    return this.enqueueMessageFollow(followRoute, actorId, packet);
+    return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
   }
 
   snapshot(actorId: string): readonly ZLinkActorHandoffPacket[] {
@@ -1440,7 +1442,8 @@ export class ZLinkActorHandoffCoordinator {
   private enqueueMessageFollow(
     entry: MessageFollowRoute,
     actorId: string,
-    packet: ZLinkActorHandoffPacket
+    packet: ZLinkActorHandoffPacket,
+    onAdmitted?: () => void
   ): Promise<unknown> {
     const context = packet.messageFollowContext;
     const duplicate = entry.operations.get(context.operationId);
@@ -1453,6 +1456,7 @@ export class ZLinkActorHandoffCoordinator {
         this.options.onMarker?.('message_follow_rejected', actorId);
         return Promise.reject(actorLocationStale(actorId));
       }
+      onAdmitted?.();
       return duplicate.result;
     }
     const bytes = packetBytes(packet);
@@ -1474,6 +1478,7 @@ export class ZLinkActorHandoffCoordinator {
       replyRouteId: context.replyRouteId,
       result
     });
+    onAdmitted?.();
     entry.tail = entry.tail.then(async () => {
       try {
         resolve(await this.relayMessageFollow(actorId, entry, packet));

package/src/runtime/actors/actor-join-relocation.ts

@@ -30,6 +30,7 @@ export interface ZLinkActorJoinRelocation {
     };
     /** Target's advertised relocation state chunk cap from the accepted admission reply. */
     readonly advertisedReceiveChunkLimitBytes?: number;
+    readonly deadlineAtMs?: number;
     readonly signal?: AbortSignal;
   }): Promise<{
     readonly actorRef: ZLinkBackendActorRef;

package/src/runtime/actors/actor-local-native-join.ts

@@ -199,33 +199,24 @@ export class ZLinkLocalNativeActorJoin {
       );
     }
     const membershipEpoch = location.membershipEpoch + 1n;
+    const currentActor = toFrameworkActorRef(actorRef, meshName);
+    const authorityOwnerGeneration = state.locationGeneration ?? actorRef.generation;
     const commit = async (spot?: ZLinkSpot): Promise<void> => {
       throwIfAborted(signal);
-      if (target.spotKind === ZLinkSpotKind.Entry) {
-        await this.options.locationLifecycle?.notifyActorLeftSpot(
-          actorType,
-          actor.context.actorId,
-          storeSpotId,
-          spotGeneration,
-          membershipEpoch,
-          node.status().lifecycleGeneration
-        );
-      } else {
-        await this.options.locationLifecycle?.notifyActorJoinedSpot(
-          actorType,
-          actor.context.actorId,
-          meshName,
-          storeSpotId,
-          spotGeneration,
-          membershipEpoch,
-          node.status().lifecycleGeneration
-        );
-      }
+      await this.options.locationLifecycle?.commitActorMembership(
+        actorType,
+        currentActor,
+        authorityOwnerGeneration,
+        storeSpotId,
+        spotGeneration,
+        target.spotKind === ZLinkSpotKind.Entry ? ZLinkSpotKind.Entry : ZLinkSpotKind.User,
+        node.status().lifecycleGeneration
+      );
       const committedActor = node.restoreActorAuthority!(
         actor.context.actorId,
         actorType,
         actorRef.generation,
-        state.locationGeneration ?? actorRef.generation,
+        authorityOwnerGeneration,
         target.spotKind === ZLinkSpotKind.Entry ? undefined : String(target.spotId),
         spotGeneration,
         membershipEpoch
@@ -297,6 +288,7 @@ export class ZLinkLocalNativeActorJoin {
     completionOperationId: ZLinkActorJoinOperationId | undefined,
     entrySpot: boolean
   ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
+    const deadlineAtMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
     const actorType = state.actorType;
     if (actorType === undefined) {
       throw createInternalFrameworkException(
@@ -443,6 +435,7 @@ export class ZLinkLocalNativeActorJoin {
         target,
         relocationId,
         completionOperationId,
+        deadlineAtMs,
         ...(control.canonicalHandoffId === undefined || canonicalAdmission === undefined
           ? {}
           : {
@@ -456,11 +449,9 @@ export class ZLinkLocalNativeActorJoin {
                 },
                 requestContentType: canonicalAdmission.request.contentType,
                 request: Buffer.from(canonicalAdmission.request.payload),
-                ...(completionOperationId === undefined
+                ...(completionOperationId === undefined || control.replyContentType === undefined
                   ? {}
-                  : {
-                      replyContentType: control.replyContentType ?? ZlinkStreamContentType.Raw
-                    }),
+                  : { replyContentType: control.replyContentType }),
                 reply:
                   completionOperationId === undefined
                     ? Buffer.alloc(0)
@@ -469,7 +460,7 @@ export class ZLinkLocalNativeActorJoin {
                 expectedOwnerLeaseGeneration: actorAuthorityFence!.ownerLeaseGeneration,
                 targetNodeGeneration: target.targetNodeGeneration!,
                 targetSpotGeneration: control.location.spotGeneration,
-                targetAuthorityOwnerGeneration: actorAuthorityFence!.authorityOwnerGeneration + 1n,
+                targetAuthorityOwnerGeneration: actorAuthorityFence!.authorityOwnerGeneration,
                 targetSpotAuthorityOwnerGeneration: target.authorityOwnerGeneration ?? 1n
               }
             }),

package/src/runtime/actors/actor-remote-wire.ts

@@ -21,9 +21,26 @@ export interface ZLinkRemoteActorSourceLeaveTerminal {
   readonly succeeded: boolean;
 }
 
+const JSON_OBJECT_START = '{'.charCodeAt(0);
+const JSON_SPACE = ' '.charCodeAt(0);
+const JSON_TAB = '\t'.charCodeAt(0);
+const JSON_LINE_FEED = '\n'.charCodeAt(0);
+const JSON_CARRIAGE_RETURN = '\r'.charCodeAt(0);
+
 export function decodeRemoteActorSourceLeaveTerminal(
   payload: Buffer
 ): ZLinkRemoteActorSourceLeaveTerminal | undefined {
+  // A SourceLeave terminal is a JSON object. Binary channel frames and JSON
+  // primitives cannot be terminals, so do not materialize or parse them.
+  let offset = 0;
+  while (
+    payload[offset] === JSON_SPACE ||
+    payload[offset] === JSON_TAB ||
+    payload[offset] === JSON_LINE_FEED ||
+    payload[offset] === JSON_CARRIAGE_RETURN
+  )
+    offset++;
+  if (payload[offset] !== JSON_OBJECT_START) return undefined;
   let decoded: unknown;
   try {
     decoded = JSON.parse(payload.toString());

package/src/runtime/actors/actor-routed-join-transport.ts

@@ -19,13 +19,13 @@ export interface ZLinkActorRoutedJoinTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   submitInfrastructure?(
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -34,7 +34,11 @@ export interface ZLinkActorRoutedJoinTransport {
   requestRawToSpot?(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
@@ -43,6 +47,7 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestFromSpotToSpot?<TReply = unknown>(
@@ -53,12 +58,17 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestRawFromSpotToSpot?(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
 }

package/src/runtime/actors/actor-routed-json-request.ts

@@ -7,7 +7,11 @@ export async function tryRequestRoutedJson(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  }
 ): Promise<boolean> {
   const request = transport.requestRawToSpot;
   if (request === undefined) return false;
@@ -24,7 +28,11 @@ export async function requestRoutedJsonReply<T>(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal },
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  },
   unavailableMessage: string,
   decode: (replyParts: readonly Message[]) => T
 ): Promise<T> {