@zlink-systems/framework 0.29.1 → 0.30.0

package/src/runtime/host/spot-address-transport.ts

@@ -1,3 +1,4 @@
+import type { ServiceInstanceColdActivationTarget } from '../foundation/service-stateful-wire-codec';
 import { ZLinkFrameworkException, ZLinkSpotKind, type RoutingId } from '../../contracts';
 import {
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
@@ -44,7 +45,11 @@ import type {
   ZLinkSpotAddressTransport,
   ZLinkSpotRoutedTransport
 } from '../spots/spot-outbound';
-import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type {
+  ZLinkSpotRouteResolver,
+  ZLinkSpotRouteTarget,
+  ZLinkInstanceReactivationRoute
+} from '../spots/spot-routing-internal';
 
 export interface ZLinkHostSpotAddressTransportOptions {
   readonly resolver: () => ZLinkSpotRouteResolver | undefined;
@@ -65,13 +70,7 @@ export function hasObjectClientCapability(role: 'none' | 'client' | 'server' | u
 type MissingTarget = {
   readonly meshName: string;
   readonly node: ZLinkBackendMeshNode;
-  readonly target: {
-    readonly targetNodeRid: string;
-    readonly targetNodeGeneration: bigint;
-    readonly targetSpotId: string;
-    readonly stableType: string;
-    readonly descriptorVersion: string;
-  };
+  readonly target: ServiceInstanceColdActivationTarget;
 };
 
 type MissingTargetSelection =
@@ -106,7 +105,10 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     const activationDeadlineUnixMs = BigInt(
       Math.round(Date.now() + this.options.defaultRequestTimeoutMs)
     );
-    const existing = await this.resolveExisting(spotId);
+    const resolution = await this.resolveExisting(spotId, undefined, call);
+    const existing = resolution !== undefined && !('kind' in resolution) ? resolution : undefined;
+    if (resolution !== undefined && 'kind' in resolution)
+      call = this.reactivationCall(resolution, call);
     if (existing !== undefined) {
       this.validateExisting(existing, call);
       try {
@@ -166,7 +168,7 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     if (!call.instanceSpot) {
       return { status: ZLinkSubmitStatus.TargetNotFound };
     }
-    const selected = this.selectMissingTarget(spotId, call);
+    const selected = this.selectMissingTarget(spotId, call, resolution);
     if (selected.kind === 'unsupported') {
       this.traceInstanceAddress(
         ZLinkMessageFlowOutcome.Dropped,
@@ -252,10 +254,13 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     const timeoutMs = call.timeoutMs ?? this.options.defaultRequestTimeoutMs;
     const deadline = createSpotAddressDeadline(timeoutMs, call.signal);
     try {
-      const existing = await this.resolveExisting(spotId, deadline.signal);
+      const resolution = await this.resolveExisting(spotId, deadline.signal, call);
+      const existing = resolution !== undefined && !('kind' in resolution) ? resolution : undefined;
+      if (resolution !== undefined && 'kind' in resolution)
+        call = this.reactivationCall(resolution, call);
       deadline.requireRemaining();
       if (existing === undefined) {
-        return await this.requestToMissingInstance(spotId, request, call, deadline);
+        return await this.requestToMissingInstance(spotId, request, call, deadline, resolution);
       }
       this.validateExisting(existing, call);
       try {
@@ -351,7 +356,8 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     spotId: RoutingId,
     request: unknown,
     call: ZLinkSpotAddressCallOptions,
-    deadline: ZLinkSpotAddressDeadline
+    deadline: ZLinkSpotAddressDeadline,
+    current?: ZLinkSpotRouteTarget | ZLinkInstanceReactivationRoute
   ): Promise<TReply> {
     if (!call.instanceSpot) {
       throw createInternalFrameworkException(
@@ -359,7 +365,7 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
         `Spot '${String(spotId)}' has no Ready authority.`
       );
     }
-    const selected = this.selectMissingTarget(spotId, call);
+    const selected = this.selectMissingTarget(spotId, call, current);
     if (selected.kind === 'capacity') {
       throw missingInstancePlacementCapacity(spotId, call.instanceSpotType);
     }
@@ -507,14 +513,20 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
 
   private async resolveExisting(
     spotId: RoutingId,
-    signal?: AbortSignal
-  ): Promise<import('../spots/spot-routing-internal').ZLinkSpotRouteTarget | undefined> {
+    signal?: AbortSignal,
+    call?: ZLinkSpotAddressCallOptions
+  ): Promise<ZLinkSpotRouteTarget | ZLinkInstanceReactivationRoute | undefined> {
     const resolver = this.options.resolver();
     if (resolver === undefined) {
       throw new Error('Global Spot address resolution requires a Location Store.');
     }
     try {
-      return await awaitWithAbort(resolver.resolve(spotId, signal), signal);
+      return await awaitWithAbort(
+        call?.instanceSpot === true
+          ? resolver.resolve(spotId, signal, true)
+          : resolver.resolve(spotId, signal),
+        signal
+      );
     } catch (error) {
       if (
         error instanceof ZLinkFrameworkException &&
@@ -526,9 +538,18 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     }
   }
 
+  private reactivationCall(
+    route: ZLinkInstanceReactivationRoute,
+    call: ZLinkSpotAddressCallOptions
+  ): ZLinkSpotAddressCallOptions {
+    this.validateExisting(route, call);
+    return { ...call, initialMeshName: route.meshName, instanceSpotType: route.stableType };
+  }
+
   private selectMissingTarget(
     spotId: RoutingId,
-    call: ZLinkSpotAddressCallOptions
+    call: ZLinkSpotAddressCallOptions,
+    current?: ZLinkSpotRouteTarget | ZLinkInstanceReactivationRoute
   ): MissingTargetSelection {
     const configuredMeshes = this.options.meshNames();
     if (
@@ -574,14 +595,15 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     const stableType =
       call.instanceSpotType ?? (distinctTypes.length === 1 ? distinctTypes[0] : undefined);
     if (stableType === undefined) {
-      if (distinctTypes.length === 0) return { kind: 'unsupported' };
+      if (distinctTypes.length === 0)
+        return { kind: current === undefined ? 'unsupported' : 'unavailable' };
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.InvalidOperation,
         'Instance Spot type is required when multiple types are registered.'
       );
     }
     if (canInspectPlacementTypes && !distinctTypes.includes(stableType)) {
-      return { kind: 'unsupported' };
+      return { kind: current === undefined ? 'unsupported' : 'unavailable' };
     }
     let unavailable = false;
     let capacity = false;
@@ -600,6 +622,7 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
           node,
           target: {
             ...placement.target,
+            targetMeshName: meshName,
             targetSpotId: String(spotId),
             stableType
           }
@@ -611,12 +634,12 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     }
     if (unavailable) return { kind: 'unavailable' };
     if (capacity) return { kind: 'capacity' };
-    if (unsupported) return { kind: 'unsupported' };
+    if (unsupported) return { kind: current === undefined ? 'unsupported' : 'unavailable' };
     return { kind: 'unavailable' };
   }
 
   private validateExisting(
-    target: import('../spots/spot-routing-internal').ZLinkSpotRouteTarget,
+    target: Pick<ZLinkSpotRouteTarget, 'spotId' | 'spotKind' | 'stableType'>,
     call: ZLinkSpotAddressCallOptions
   ): void {
     if (!call.instanceSpot) return;

package/src/runtime/host/spot-runtime-options-factory.ts

@@ -102,6 +102,7 @@ export class ZLinkSpotRuntimeOptionsFactory {
           Promise.resolve()
       },
       dispatchEntryActorPacket: (
+        origin,
         actorId,
         parts,
         returnResponse,
@@ -117,6 +118,7 @@ export class ZLinkSpotRuntimeOptionsFactory {
           );
         }
         return runtime.dispatchEntryActorPacket(
+          origin,
           actorId,
           parts,
           returnResponse,

package/src/runtime/host/user-spot-creation-coordinator.ts

@@ -38,6 +38,10 @@ const DEFAULT_USER_SPOT_CLEANUP_TIMEOUT_MS = 1_000;
 const DEFAULT_USER_SPOT_POLL_INTERVAL_MS = 10;
 
 export interface ZLinkUserSpotCreationCoordinatorOptions {
+  readonly relocationPolicy?: (
+    meshName: string,
+    stableType: string
+  ) => import('../locations/internal-location-contracts').ZLinkObjectReserveRequest['actorRelocationPolicy'];
   readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
   readonly target: (
     request: Pick<ZLinkUserSpotCreationRequest, 'meshName' | 'stableType'>,
@@ -169,6 +173,10 @@ export class ZLinkUserSpotCreationCoordinator {
         reserved = await this.options.store.reserve(
           {
             key: { kind: 'user_spot', globalId: String(request.spotId) },
+            actorRelocationPolicy: this.options.relocationPolicy?.(
+              target.meshName,
+              request.stableType
+            ),
             intent: {
               stableType: request.stableType,
               requestContentReference: contentReference,

package/src/runtime/locations/domain-store-contract.ts

@@ -39,7 +39,10 @@ import type {
   ZLinkObjectCreationCompleteResult,
   ZLinkObjectReserveResult
 } from '../../contracts/Locations/Authority';
-import type { ZLinkObjectReserveRequest } from './internal-location-contracts';
+import type {
+  ZLinkObjectReserveRequest,
+  ZLinkEndedOwnerReleaseIntent
+} from './internal-location-contracts';
 
 /**
  * Framework-private domain repository. Provider implementations never
@@ -143,7 +146,8 @@ export interface ZLinkDomainLocationStore {
   releaseEndedReservation?(
     key: ZLinkAuthorityKey,
     expectedStoreVersion: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    request?: ZLinkEndedOwnerReleaseIntent
   ): Promise<boolean>;
   abort(
     request: ZLinkObjectAbortRequest,

package/src/runtime/locations/in-memory-authority-store.ts

@@ -32,6 +32,7 @@ import type {
   ZLinkObjectCommitResult,
   ZLinkObjectCreationCompleteRequest,
   ZLinkObjectCreationCompleteResult,
+  ZLinkEndedOwnerReleaseIntent,
   ZLinkObjectReserveRequest,
   ZLinkObjectReserveResult,
   ZLinkCreationOperationIdentity,
@@ -42,7 +43,13 @@ import type {
 } from './internal-location-contracts';
 import { encodeAuthorityKey } from './authority-key-codec';
 import { creationTerminalPreimage } from './opaque-record-key';
-import { ServiceRelocationAuthorityPayloadCodec } from '../foundation/service-relocation-runtime';
+import {
+  ServiceRelocationAuthorityPayloadCodec,
+  serviceRelocationAuthorityApplicationPayload
+} from '../foundation/service-relocation-runtime';
+import { decodeServiceReadySpotAuthority } from '../foundation/service-authority-payload-codec';
+import { decodeActorAuthorityPayload } from '../actors/actor-authority-payload-codec';
+import { ZLinkSpotKind } from '../../contracts';
 
 const MAX_GENERATION = 0x7fff_ffff_ffff_ffffn;
 
@@ -64,6 +71,7 @@ export interface ZLinkInMemoryAuthorityValidation {
     currentActive: ZLinkCapacityVector
   ): boolean;
   identityClaimed?(authorityKey: string): boolean;
+  hasSpotMembers?(spotId: string, objectGeneration: bigint): boolean;
 }
 
 interface AuthorityRow {
@@ -203,6 +211,26 @@ export class ZLinkInMemoryAuthorityStore {
     if (!this.isOwnerLive(row.snapshot)) {
       return { kind: 'conflict', current: this.read(keyValue) };
     }
+    const actor =
+      row.snapshot.allocation.objectKind === 'actor'
+        ? decodeActorAuthorityPayload(
+            serviceRelocationAuthorityApplicationPayload(mutation.payload)
+          )
+        : undefined;
+    const previousActor =
+      actor === undefined
+        ? undefined
+        : decodeActorAuthorityPayload(
+            serviceRelocationAuthorityApplicationPayload(row.snapshot.payload)
+          );
+    if (
+      actor?.currentSpotKind === ZLinkSpotKind.User &&
+      (previousActor?.currentSpotKind !== ZLinkSpotKind.User ||
+        previousActor.currentSpotId !== actor.currentSpotId ||
+        previousActor.currentSpotGeneration !== actor.currentSpotGeneration) &&
+      !this.acceptsUserSpotMembership(actor.currentSpotId, actor.currentSpotGeneration)
+    )
+      return { kind: 'conflict', current: this.read(keyValue) };
     if (
       mutation.generationTransition === 'reincarnate' &&
       (this.objectGeneration >= MAX_GENERATION || this.ownerGeneration >= MAX_GENERATION)
@@ -283,27 +311,41 @@ export class ZLinkInMemoryAuthorityStore {
   async releaseEndedReservation(
     key: ZLinkAuthorityKey,
     expectedStoreVersion: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    request?: ZLinkEndedOwnerReleaseIntent
   ): Promise<boolean> {
     signal?.throwIfAborted();
-    return this.tryReleaseEndedReservation(key, expectedStoreVersion);
+    return this.tryReleaseEndedReservation(key, expectedStoreVersion, request);
+  }
+
+  acceptsUserSpotMembership(spotId: string, objectGeneration: bigint): boolean {
+    const row = this.rows.get(encodeAuthorityKey('user_spot', spotId).value);
+    return (
+      row !== undefined &&
+      row.snapshot.allocation.objectKind === 'user_spot' &&
+      row.snapshot.allocation.state === 'active' &&
+      row.snapshot.objectGeneration === objectGeneration &&
+      decodeServiceReadySpotAuthority(row.snapshot.payload)?.kind === 'user_spot' &&
+      this.isOwnerLive(row.snapshot)
+    );
   }
 
   private tryReleaseEndedReservation(
     key: ZLinkAuthorityKey,
     expectedStoreVersion: string,
-    request?: ZLinkObjectReserveRequest
+    request?: ZLinkEndedOwnerReleaseIntent
   ): boolean {
     const current = this.rows.get(key.value);
     if (
       current === undefined ||
       current.snapshot.storeVersion.value !== expectedStoreVersion ||
       (current.snapshot.allocation.state === 'active'
-        ? request?.key.kind !== 'actor'
+        ? request === undefined
         : current.creation === undefined)
     )
       return false;
     if (current.snapshot.allocation.state === 'active') {
+      let unavailable = false;
       for (const aggregate of this.aggregates.values()) {
         if (
           aggregate.state === 'prepared' &&
@@ -311,9 +353,9 @@ export class ZLinkInMemoryAuthorityStore {
             (participant) => participant.authorityKey.value === key.value
           )
         )
-          return false;
+          unavailable = true;
       }
-      if (relocationAuthorityCodec.read(current.snapshot.payload) !== undefined) return false;
+      unavailable ||= relocationAuthorityCodec.read(current.snapshot.payload) !== undefined;
       if (
         this.validation.isOwnerLive({
           ownerId: current.snapshot.ownerId,
@@ -321,10 +363,37 @@ export class ZLinkInMemoryAuthorityStore {
         })
       )
         return false;
-      if (request?.actorRelocationPolicy !== 'disabled')
+      const spot =
+        current.snapshot.allocation.objectKind === 'actor'
+          ? undefined
+          : decodeServiceReadySpotAuthority(current.snapshot.payload);
+      if (current.snapshot.allocation.objectKind !== 'actor') {
+        unavailable ||=
+          spot === undefined ||
+          spot.kind !== request?.key.kind ||
+          spot.stableType !== request.intent.stableType ||
+          spot.spotId !== request.key.globalId ||
+          spot.activationRecovery !== undefined;
+        if (spot?.kind === 'user_spot') {
+          unavailable ||=
+            this.validation.hasSpotMembers?.(spot.spotId, current.snapshot.objectGeneration) ===
+            true;
+          for (const row of this.rows.values()) {
+            if (row.snapshot.allocation.objectKind !== 'actor') continue;
+            const actor = decodeActorAuthorityPayload(
+              serviceRelocationAuthorityApplicationPayload(row.snapshot.payload)
+            );
+            unavailable ||=
+              actor?.currentSpotKind === ZLinkSpotKind.User &&
+              actor.currentSpotId === spot.spotId &&
+              actor.currentSpotGeneration === current.snapshot.objectGeneration;
+          }
+        }
+      }
+      if (unavailable || request?.actorRelocationPolicy !== 'disabled')
         throw new ZLinkFrameworkException(
           ZLinkFrameworkErrorKind.Unavailable,
-          'Actor owner lease is unavailable.'
+          'Object owner lease is unavailable.'
         );
     } else if (
       this.validation.isTargetLive(
@@ -532,6 +601,17 @@ export class ZLinkInMemoryAuthorityStore {
     if (!this.creationTerminalAvailable(terminalRecord)) {
       return { kind: 'stale' };
     }
+    const actor =
+      request.completion.kind === 'created'
+        ? decodeActorAuthorityPayload(
+            serviceRelocationAuthorityApplicationPayload(request.completion.readyPayload)
+          )
+        : undefined;
+    if (
+      actor?.currentSpotKind === ZLinkSpotKind.User &&
+      !this.acceptsUserSpotMembership(actor.currentSpotId, actor.currentSpotGeneration)
+    )
+      return { kind: 'stale' };
     const nextVersion = this.tryNextStoreVersion();
     if (nextVersion === undefined) return { kind: 'generationExhausted' };
     const pending = row.snapshot.allocation;
@@ -698,6 +778,30 @@ export class ZLinkInMemoryAuthorityStore {
       ) {
         return { kind: 'stale' };
       }
+      const actor =
+        row.snapshot.allocation.objectKind === 'actor'
+          ? decodeActorAuthorityPayload(
+              serviceRelocationAuthorityApplicationPayload(participant.authorityPayload)
+            )
+          : undefined;
+      if (actor?.currentSpotKind === ZLinkSpotKind.User) {
+        const participantSpot = aggregate.request.participants.find(
+          (candidate) =>
+            candidate.authorityKey.value ===
+            encodeAuthorityKey('user_spot', actor.currentSpotId).value
+        );
+        if (participantSpot === undefined) {
+          if (!this.acceptsUserSpotMembership(actor.currentSpotId, actor.currentSpotGeneration))
+            return { kind: 'stale' };
+        } else {
+          const spot = this.rows.get(participantSpot.authorityKey.value);
+          if (
+            spot?.snapshot.allocation.objectKind !== 'user_spot' ||
+            spot.snapshot.objectGeneration !== actor.currentSpotGeneration
+          )
+            return { kind: 'stale' };
+        }
+      }
       if (participant.ownerTransition === 'newOwner') {
         if (
           !this.validation.isTargetLive(

package/src/runtime/locations/in-memory-location-store.ts

@@ -1,4 +1,5 @@
 import type { RoutingId } from '../../contracts/Common';
+import { ZLinkSpotKind } from '../../contracts';
 import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
 import {
   isValidPublicWeight,
@@ -58,6 +59,7 @@ import {
   type ZLinkObjectCommitResult,
   type ZLinkObjectCreationCompleteRequest,
   type ZLinkObjectCreationCompleteResult,
+  type ZLinkEndedOwnerReleaseIntent,
   type ZLinkObjectReserveRequest,
   type ZLinkObjectReserveResult,
   type ZLinkOwnerLeaseClaimResult,
@@ -143,7 +145,18 @@ export class ZLinkInMemoryLocationStore
                     typeCapacity.limit)))
           );
         },
-        identityClaimed: (authorityKey) => this.entrySpotClaims.has(authorityKey)
+        identityClaimed: (authorityKey) => this.entrySpotClaims.has(authorityKey),
+        hasSpotMembers: (spotId, objectGeneration) => {
+          for (const actor of this.actors.rows.values()) {
+            if (
+              actor.spotKind === ZLinkSpotKind.User &&
+              String(actor.spotId) === spotId &&
+              actor.spotGeneration === objectGeneration
+            )
+              return true;
+          }
+          return false;
+        }
       },
       now
     );
@@ -205,9 +218,10 @@ export class ZLinkInMemoryLocationStore
   async releaseEndedReservation(
     key: ZLinkAuthorityKey,
     expectedStoreVersion: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    request?: ZLinkEndedOwnerReleaseIntent
   ): Promise<boolean> {
-    return this.authority.releaseEndedReservation(key, expectedStoreVersion, signal);
+    return this.authority.releaseEndedReservation(key, expectedStoreVersion, signal, request);
   }
 
   async abort(
@@ -705,6 +719,14 @@ export class ZLinkInMemoryLocationStore
     });
     const updatedAt = this.now();
     const current = this.actors.rows.get(key);
+    if (
+      actor.spotKind === ZLinkSpotKind.User &&
+      (current?.spotKind !== ZLinkSpotKind.User ||
+        String(current.spotId) !== String(actor.spotId) ||
+        current.spotGeneration !== actor.spotGeneration) &&
+      !this.authority.acceptsUserSpotMembership(String(actor.spotId), actor.spotGeneration)
+    )
+      return rejectedConflict();
     if (
       intent === ZLinkLocationWriteIntent.NewClaim &&
       current !== undefined &&

package/src/runtime/locations/internal-location-contracts.ts

@@ -5,6 +5,10 @@ import type { ZLinkRelocationConfiguration } from '../../contracts/Configuration
 export interface ZLinkObjectReserveRequest extends ReserveRequest {
   readonly actorRelocationPolicy?: ZLinkRelocationConfiguration<unknown>['kind'];
 }
+export type ZLinkEndedOwnerReleaseIntent = Pick<
+  ZLinkObjectReserveRequest,
+  'key' | 'actorRelocationPolicy'
+> & { readonly intent: Pick<ZLinkObjectReserveRequest['intent'], 'stableType'> };
 export type * from '../../contracts/Locations/Authority';
 export type {
   ZLinkActorLocation,