@zlink-systems/framework 0.30.0 → 0.30.2

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/Locations/Rows.ts

@@ -25,6 +25,8 @@ export interface ZLinkObjectCapability {
   readonly policy: ZLinkObjectMaintenancePolicyKind;
   readonly hasSnapshotAdapter: boolean;
   readonly limit: number;
+  /** True only for an Actor capability whose node registered an Entry Spot type accepting it. */
+  readonly entryAccepted: boolean;
 }
 
 export interface ZLinkPopulationCapacity {

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,
@@ -15,12 +16,20 @@ export interface ZLinkActorHandlerRegistry {
 }
 
 export interface ZLinkSpotHandlerRegistry extends ZLinkActorHandlerRegistry {
+  /** Declares a timer handler constructor for relocation without registering an endpoint. */
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkSpot>>(
+    handlerType: Type<THandler>
+  ): this;
   addPacket<THandler>(handlerType: Type<THandler>): this;
   addSubscribe<THandler>(handlerType: Type<THandler>, channelName: string, topic: string): this;
 }
 
 export interface ZLinkInstanceSpotHandlerRegistry {
   addPacket<THandler>(handlerType: Type<THandler>): this;
+  /** Declares a timer handler constructor for relocation without registering an endpoint. */
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkInstanceSpot>>(
+    handlerType: Type<THandler>
+  ): this;
 }
 
 export interface ZLinkWorkerCall<T> {
@@ -106,7 +115,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/contracts/Spots/ZLinkSpot.ts

@@ -61,8 +61,8 @@ export interface ZLinkSpot<
 > extends ZLinkUserSpotActorLifecycle<TActor> {
   readonly context: ZLinkSpotContext<TActor>;
   configure?(): void;
-  onCreate?(request: ZLinkMessage): Promise<ZLinkSpotCreateResponse>;
-  onInitialize?(): Promise<void>;
+  onCreate?(request: ZLinkMessage, signal?: AbortSignal): Promise<ZLinkSpotCreateResponse>;
+  onInitialize?(signal?: AbortSignal): Promise<void>;
   onClosing?(context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal): Promise<void>;
   onRelocationReadyCompleted?(completion: ZLinkSpotRelocationReadyCompletion): Promise<void>;
 }
@@ -70,7 +70,7 @@ export interface ZLinkSpot<
 export interface ZLinkInstanceSpot {
   readonly context: ZLinkInstanceSpotContext;
   configure?(): void;
-  onInitialize?(): Promise<void>;
+  onInitialize?(signal?: AbortSignal): Promise<void>;
   onClosing?(context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal): Promise<void>;
 }
 

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/abort.ts

@@ -38,6 +38,18 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
   }
 }
 
+/**
+ * Whether a handler or dispatch result is a thenable the caller must wait
+ * for. Synchronous results, including null and undefined, are not.
+ */
+export function isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {
+  return (
+    value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
 export function macrotaskBoundary(): Promise<void> {
   return new Promise((resolve) => setImmediate(resolve));
 }

package/src/runtime/actors/actor-authority-publication.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import { createHash } from 'node:crypto';
 import type { ActorRef } from '../../contracts';
 import { ZLinkSpotKind } from '../../contracts';
@@ -278,7 +279,7 @@ function requireActorAuthority(
     snapshot.allocation.objectKind !== 'actor' ||
     snapshot.allocation.stableType !== expected.actorType ||
     snapshot.allocation.descriptor.meshName !== expected.meshName ||
-    String(snapshot.allocation.descriptor.rid) !== String(expected.actor.nodeRid) ||
+    !routingIdsEqual(snapshot.allocation.descriptor.rid, expected.actor.nodeRid) ||
     snapshot.allocation.descriptorLifecycleGeneration !== expected.ownerNodeGeneration ||
     snapshot.ownerId !== expected.owner.ownerId ||
     snapshot.ownerLeaseGeneration !== expected.owner.leaseGeneration ||
@@ -286,7 +287,7 @@ function requireActorAuthority(
     actual.actorType !== expected.actorType ||
     actual.actor.actorId !== expected.actor.actorId ||
     actual.actor.objectGeneration !== expected.actor.objectGeneration ||
-    String(actual.actor.nodeRid) !== String(expected.actor.nodeRid)
+    !routingIdsEqual(actual.actor.nodeRid, expected.actor.nodeRid)
   ) {
     throw new Error(
       `Actor '${expected.actor.actorId}' authority fence does not match its ActorRef.`