@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/foundation/runtime-state-projections.ts

@@ -1,4 +1,12 @@
-import { ZLinkFrameworkRuntimeState } from '../../contracts';
+import { ZLinkFrameworkRuntimeState, ZLinkTopologyState } from '../../contracts';
+
+export function runtimeObservationIsTerminal(state: ZLinkFrameworkRuntimeState): boolean {
+  return state === ZLinkFrameworkRuntimeState.Stopped;
+}
+
+export function topologyObservationIsTerminal(state: ZLinkTopologyState): boolean {
+  return state === ZLinkTopologyState.Stopped || state === ZLinkTopologyState.Failed;
+}
 
 export type MaintenanceAdmissionState =
   'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';

package/src/runtime/foundation/service-authority-payload-codec.ts

@@ -1,5 +1,13 @@
-import { crc32c } from './service-relocation-runtime';
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
+import { ZLinkSpotKind, zlinkSpotKindToWire } from '../../contracts';
 import type { ZLinkLocationOwnerToken } from '../../contracts/Locations';
+import { SHA256_DIGEST_BYTES } from './actor-join-recovery-codec';
+import { crc32c } from './service-relocation-runtime';
+import { SERVICE_WIRE_TEXT8_MAX_BYTES } from './service-wire-binary-primitives';
+const SPOT_AUTHORITY_OBJECT_KIND = 2;
+const USER_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.User);
+const INSTANCE_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.Instance);
+const AUTHORITY_TEXT16_MAX_BYTES = 0xffff;
 
 const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_FORMAT_VERSION = 1;
@@ -189,6 +197,16 @@ export function decodeServiceReadySpotAuthority(
   return decoded?.state === 'ready' && decoded.operationKind === 0 ? decoded : undefined;
 }
 
+export function decodeServiceClosingSpotAuthority(
+  payload: Uint8Array
+): ServiceReadySpotAuthority | undefined {
+  const decoded = decodeSpotAuthority(payload);
+  return decoded?.operationKind === 3 &&
+    (decoded.kind === 'user_spot' || decoded.state === 'closing')
+    ? decoded
+    : undefined;
+}
+
 export function decodeServiceInstanceAuthorityPayload(
   payload: Uint8Array
 ): ServiceDecodedInstanceAuthority | undefined {
@@ -301,7 +319,7 @@ function decodeSpotAuthority(payload: Uint8Array):
     const operationKind = body.u8();
     const objectKind = body.u8();
     const object = body.takeReader(body.u16());
-    if (objectKind !== 2) return undefined;
+    if (objectKind !== SPOT_AUTHORITY_OBJECT_KIND) return undefined;
     const spotKind = object.u8();
     const spot = object.takeReader(object.u16());
     if (!object.done) return undefined;
@@ -310,12 +328,12 @@ function decodeSpotAuthority(payload: Uint8Array):
     let state: number;
     let stableType: string;
     let spotId: string;
-    if (spotKind === 2) {
+    if (spotKind === USER_SPOT_WIRE_KIND) {
       kind = 'user_spot';
       spotId = spot.rid();
       stableType = spot.text8();
       state = spot.u8();
-    } else if (spotKind === 3) {
+    } else if (spotKind === INSTANCE_SPOT_WIRE_KIND) {
       kind = 'instance_spot';
       state = spot.u8();
       const instance = spot.takeReader(spot.u16());
@@ -407,23 +425,33 @@ function rid(value: string, name: string): Buffer {
 
 function text16(value: string, name: string): Buffer {
   const bytes = Buffer.from(value);
-  if (bytes.byteLength < 1 || bytes.byteLength > 0xffff || bytes.includes(0)) {
-    throw new RangeError(`${name} must contain 1..65535 UTF-8 bytes without NUL.`);
+  if (bytes.byteLength < 1 || bytes.byteLength > AUTHORITY_TEXT16_MAX_BYTES || bytes.includes(0)) {
+    throw new RangeError(
+      `${name} must contain 1..${AUTHORITY_TEXT16_MAX_BYTES} UTF-8 bytes without NUL.`
+    );
   }
   return concat(u16(bytes.byteLength), bytes);
 }
 
 function sha256(value: Uint8Array): Buffer {
-  if (value.byteLength !== 32) {
-    throw new RangeError('activationRecovery.sha256 must contain exactly 32 bytes.');
+  if (value.byteLength !== SHA256_DIGEST_BYTES) {
+    throw new RangeError(
+      `activationRecovery.sha256 must contain exactly ${SHA256_DIGEST_BYTES} bytes.`
+    );
   }
-  return concat(Buffer.of(32), value);
+  return concat(Buffer.of(SHA256_DIGEST_BYTES), value);
 }
 
 function sized8(value: string, name: string): Buffer {
   const bytes = Buffer.from(value);
-  if (bytes.byteLength < 1 || bytes.byteLength > 255 || 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);
 }
@@ -448,7 +476,7 @@ function boundedU32(value: number, name: string): Buffer {
 }
 
 function u64(value: bigint, name: string): Buffer {
-  if (value <= 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value <= 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be a non-zero u64.`);
   }
   const result = Buffer.alloc(8);
@@ -457,7 +485,7 @@ function u64(value: bigint, name: string): Buffer {
 }
 
 function ordinalU64(value: bigint, name: string): Buffer {
-  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value < 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be a u64.`);
   }
   const result = Buffer.alloc(8);

package/src/runtime/foundation/service-discovery-registry.ts

@@ -1,3 +1,8 @@
+import {
+  isValidPublicWeight,
+  ZLINK_MAX_PUBLIC_WEIGHT
+} from '../../contracts/Configuration/RegistrationBuilderPolicy';
+import { SmoothWeightedSelection } from './service-weighted-selection';
 export interface ClientServerDescriptor {
   readonly channelName: string;
   readonly serverRoutingId: string;
@@ -31,6 +36,20 @@ export interface SelectedClientServer {
 
 /** Dedicated discovery state; fanout publishers never reuse RouteMesh peer rows. */
 export class ServiceDiscoveryRegistry {
+  private readonly clientServerChanged = new Set<(error?: Error) => void>();
+
+  onClientServerChanged(listener: (error?: Error) => void): () => void {
+    this.clientServerChanged.add(listener);
+    return () => {
+      this.clientServerChanged.delete(listener);
+    };
+  }
+
+  dispose(error: Error): void {
+    for (const listener of this.clientServerChanged) listener(error);
+    this.clientServerChanged.clear();
+  }
+
   private readonly clientServers = new Map<string, Current<ClientServerDescriptor>>();
   private readonly fanoutPublishers = new Map<string, Current<FanoutPublisherDescriptor>>();
   private readonly clientServerSelections = new Map<
@@ -101,6 +120,14 @@ export class ServiceDiscoveryRegistry {
     return selection.select();
   }
 
+  hasReadyClientServer(channelName: string): boolean {
+    return [...this.clientServers.values()].some(
+      ({ descriptor }) =>
+        descriptor.channelName === channelName &&
+        (descriptor.state === 'serving' || descriptor.state === 'retiring')
+    );
+  }
+
   clientServerDescriptors(channelName: string): readonly ClientServerDescriptor[] {
     return [...this.clientServers.values()]
       .map((value) => value.descriptor)
@@ -161,6 +188,7 @@ export class ServiceDiscoveryRegistry {
     if (this.clientServerSelections.has(channelName)) {
       this.clientServerSelections.get(channelName)!.rebuild();
     }
+    for (const listener of this.clientServerChanged) listener();
   }
 
   private clientServerCandidates(channelName: string) {
@@ -239,8 +267,10 @@ function validateClientServer(descriptor: ClientServerDescriptor): void {
   requireText(descriptor.securityIdentity, 'securityIdentity');
   requireText(descriptor.advertisedEndpoint, 'advertisedEndpoint');
   validateRevision(descriptor.lifecycleGeneration, descriptor.descriptorRevision);
-  if (!Number.isInteger(descriptor.weight) || descriptor.weight < 0 || descriptor.weight > 10_000) {
-    throw new RangeError('ClientServer weight must be an integer in 0..10000.');
+  if (!isValidPublicWeight(descriptor.weight)) {
+    throw new RangeError(
+      `ClientServer weight must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`
+    );
   }
   if (
     !Number.isSafeInteger(descriptor.effectiveMaxMessageBytes) ||
@@ -268,4 +298,3 @@ function requireText(value: string, field: string): void {
     throw new TypeError(`${field} must be non-empty text without NUL.`);
   }
 }
-import { SmoothWeightedSelection } from './service-weighted-selection';

package/src/runtime/foundation/service-instance-activation-recovery-codec.ts

@@ -1,3 +1,5 @@
+import { SERVICE_WIRE_TEXT8_MAX_BYTES } from './service-wire-binary-primitives';
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import { crc32c } from './service-relocation-runtime';
 import { validateApplicationPayloadFrame } from './service-wire-m6a-codec';
 import type { ServiceInstanceActivationTarget } from './service-stateful-wire-codec';
@@ -199,8 +201,14 @@ function requireOperation(value: ServiceInstanceActivationRecoveryEnvelope): voi
 
 function textBytes(value: string, name: string): Buffer {
   const bytes = Buffer.from(value, 'utf8');
-  if (bytes.byteLength < 1 || bytes.byteLength > 255 || 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 bytes;
 }
@@ -216,13 +224,13 @@ function writeText8(target: Buffer, offset: number, value: Uint8Array): number {
 }
 
 function validatePositiveU64(value: bigint, name: string): void {
-  if (value <= 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value <= 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} is out of range.`);
   }
 }
 
 function validateU64(value: bigint, name: string): void {
-  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value < 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} is out of range.`);
   }
 }

package/src/runtime/foundation/service-liveness-registry.ts

@@ -1,3 +1,4 @@
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
 export interface ServiceProbe {
   readonly nodeRoutingId: string;
   readonly connectionId: string;
@@ -139,7 +140,7 @@ export class ServiceLivenessRegistry {
 
   private allocateProbeId(): bigint {
     const result = this.nextProbeId++;
-    if (this.nextProbeId > 0xffff_ffff_ffff_ffffn) this.nextProbeId = 1n;
+    if (this.nextProbeId > UINT64_MAX) this.nextProbeId = 1n;
     return result;
   }
 }

package/src/runtime/foundation/service-maintenance-runtime.ts

@@ -145,12 +145,27 @@ export class ServiceMaintenanceRuntime {
 
   private async runUnits(signal: AbortSignal, stopStartingSignal?: AbortSignal): Promise<void> {
     const pending = new Set<Promise<void>>();
+    // A unit failure is recorded before its promise leaves `pending`, so no
+    // failure is lost. Every started unit runs to its own terminal before the
+    // first failure is reported: the host result follows the settled
+    // authority of each unit (spec 30 §13).
+    const failures: unknown[] = [];
+    const reportFailure = async (): Promise<void> => {
+      if (failures.length === 0) return;
+      await Promise.allSettled(pending);
+      throw failures[0];
+    };
     for (;;) {
+      await reportFailure();
       const queued = await this.lane.run(() => this.units.length > 0);
-      if (!queued && pending.size === 0) return;
+      if (!queued && pending.size === 0) {
+        await reportFailure();
+        return;
+      }
       signal.throwIfAborted();
       if (stopStartingSignal?.aborted === true) {
         await Promise.allSettled(pending);
+        await reportFailure();
         stopStartingSignal.throwIfAborted();
       }
       let admitted = false;
@@ -173,19 +188,25 @@ export class ServiceMaintenanceRuntime {
         admitted = true;
         let running!: Promise<void>;
         running = startOutsideStateLane(() =>
-          unit.relocate(signal).finally(async () => {
-            const publication = await this.lane.run(() => {
-              this.activeOutbound--;
-              pending.delete(running);
-              return this.publishCore();
-            });
-            this.notify(publication);
-          })
+          unit
+            .relocate(signal)
+            .catch((error: unknown) => {
+              failures.push(error);
+            })
+            .finally(async () => {
+              const publication = await this.lane.run(() => {
+                this.activeOutbound--;
+                pending.delete(running);
+                return this.publishCore();
+              });
+              this.notify(publication);
+            })
         );
         pending.add(running);
         this.notify(claim.publication);
       }
       if (pending.size === 0) {
+        await reportFailure();
         if (!admitted) throw new Error('No relocation unit is ready to start.');
       } else {
         await Promise.race(pending);
@@ -231,13 +252,3 @@ export class ServiceMaintenanceRuntime {
 function startOutsideStateLane<T>(work: () => T): T {
   return detachedStateLaneResource.runInAsyncScope(work);
 }
-
-export function classifyRelocationRecovery(
-  publishedReference: boolean,
-  payloadPresent: boolean,
-  checksumMatches: boolean,
-  inventoryMatches: boolean
-): 'resume' | 'orphan' | 'relocationDataLost' {
-  if (!publishedReference) return payloadPresent ? 'orphan' : 'resume';
-  return payloadPresent && checksumMatches && inventoryMatches ? 'resume' : 'relocationDataLost';
-}

package/src/runtime/foundation/service-metadata-codec.ts

@@ -1,4 +1,4 @@
-const MAX_METADATA_BYTES = 1024;
+import { ZLINK_STREAM_MAX_METADATA_BYTES as MAX_METADATA_BYTES } from '@zlink-systems/stream-wire';
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 
 export function encodeServiceMetadataFrame(entries: ReadonlyMap<string, string>): Buffer {
@@ -18,7 +18,7 @@ export function encodeServiceMetadataFrame(entries: ReadonlyMap<string, string>)
 
 export function validateServiceMetadataFrame(frame: Uint8Array): Buffer {
   if (frame.byteLength > MAX_METADATA_BYTES) {
-    throw new RangeError('Application metadata frame exceeds 1024 bytes.');
+    throw new RangeError(`Application metadata frame exceeds ${MAX_METADATA_BYTES} bytes.`);
   }
   const bytes = Buffer.from(frame);
   let offset = 0;

package/src/runtime/foundation/service-relocation-aggregate-committer.ts

@@ -36,15 +36,13 @@ export interface ServicePreparedRelocationAggregate {
   readonly plan: ServiceRelocationAggregatePlan;
 }
 
-type AggregateStore = Pick<
-  ZLinkObjectCreationStore,
-  'prepareAggregate' | 'commitAggregate' | 'abortAggregate'
-> &
+type AggregateStore = Pick<ZLinkObjectCreationStore, 'prepareAggregate' | 'abortAggregate'> &
   Pick<ZLinkAuthorityStore, 'readAuthority'>;
 
 const MAX_PREPARE_CONFLICT_ATTEMPTS = 8;
 
-/** Commits every owner and membership row through one Location Store fence. */
+/** Prepares and aborts relocation through one Location Store fence. */
+
 export class ServiceRelocationAggregateCommitter {
   constructor(private readonly store: AggregateStore) {}
 
@@ -109,73 +107,12 @@ export class ServiceRelocationAggregateCommitter {
     return true;
   }
 
-  async commit(
-    prepared: ServicePreparedRelocationAggregate,
-    signal?: AbortSignal
-  ): Promise<ReadonlyMap<string, ZLinkAuthoritySnapshot>> {
-    try {
-      await this.commitFence(prepared.fence, signal);
-    } catch (firstError) {
-      // A lost commit response is reconciled by repeating the exact durable fence.
-      try {
-        await this.commitFence(prepared.fence, signal);
-      } catch {
-        throw firstError;
-      }
-    }
-    return await this.readCommittedParticipants(prepared.plan, signal);
-  }
-
   async abort(prepared: ServicePreparedRelocationAggregate, signal?: AbortSignal): Promise<void> {
     const result = await this.store.abortAggregate(prepared.fence, signal);
     if (result.kind !== 'aborted' && result.kind !== 'alreadyAborted') {
       throw new Error(`Location Store rejected relocation aggregate abort: ${result.kind}.`);
     }
   }
-
-  private async commitFence(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<void> {
-    const result = await this.store.commitAggregate(fence, signal);
-    if (result.kind !== 'committed' && result.kind !== 'alreadyCommitted') {
-      throw new Error(`Location Store rejected relocation aggregate commit: ${result.kind}.`);
-    }
-  }
-
-  private async readCommittedParticipants(
-    plan: ServiceRelocationAggregatePlan,
-    signal?: AbortSignal
-  ): Promise<ReadonlyMap<string, ZLinkAuthoritySnapshot>> {
-    const committed = new Map<string, ZLinkAuthoritySnapshot>();
-    for (const participant of plan.participants) {
-      const current = await this.store.readAuthority(participant.key, signal);
-      if (
-        current.kind !== 'snapshot' ||
-        current.objectGeneration !== participant.expected.objectGeneration ||
-        current.storeVersion.value === participant.expected.storeVersion.value ||
-        !Buffer.from(current.payload).equals(Buffer.from(participant.authorityPayload))
-      ) {
-        throw new Error(
-          'Committed relocation aggregate does not match its exact participant plan.'
-        );
-      }
-      if (participant.ownerTransition === 'newOwner') {
-        if (
-          current.ownerId !== plan.targetOwner.ownerId ||
-          current.ownerLeaseGeneration !== plan.targetOwner.leaseGeneration ||
-          current.authorityOwnerGeneration <= participant.expected.authorityOwnerGeneration
-        ) {
-          throw new Error('Committed relocation participant has a different owner fence.');
-        }
-      } else if (
-        current.ownerId !== participant.expected.ownerId ||
-        current.ownerLeaseGeneration !== participant.expected.ownerLeaseGeneration ||
-        current.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration
-      ) {
-        throw new Error('Preserved relocation participant changed its owner fence.');
-      }
-      committed.set(participant.key.value, current);
-    }
-    return committed;
-  }
 }
 
 function validateAndEncodeParticipants(

package/src/runtime/foundation/service-relocation-coordinator.ts

@@ -32,3 +32,16 @@ export class ServiceRelocationPostCommitError extends Error {
     this.name = 'ServiceRelocationPostCommitError';
   }
 }
+
+/**
+ * A relocation whose settled authority leaves the host in `Error` with
+ * `Blocked/RelocationFailed` (spec 30 §13): the source owner lease ended
+ * before its Preserve fence succeeded, or units settled on both the source
+ * and the target.
+ */
+export class ServiceRelocationAuthorityError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ServiceRelocationAuthorityError';
+  }
+}

package/src/runtime/foundation/service-relocation-object-owner.ts

@@ -13,6 +13,7 @@ import type {
   ServiceRelocationQueuedMessage,
   ServiceRelocationTimer
 } from './service-relocation-runtime';
+const DEFAULT_RELOCATION_CALLBACK_CONCURRENCY = 8;
 
 export interface ServiceRelocationSealedWork {
   readonly boundSessionState: Uint8Array;
@@ -30,10 +31,12 @@ export interface ServiceRelocationCaptureUnit {
   captureApplicationState(signal?: AbortSignal): Promise<Uint8Array>;
   commitSeal(): Promise<void> | void;
   abortSeal(): Promise<void> | void;
+  /** Expired-owner terminal: pending requests fail once and dispatch stays closed. */
+  discardSeal?(reason: unknown): Promise<void> | void;
 }
 
 export class ServiceCapturedObjectRelocation {
-  private terminal: 'open' | 'committed' | 'aborted' = 'open';
+  private terminal: 'open' | 'committed' | 'aborted' | 'discarded' = 'open';
 
   constructor(
     readonly envelope: ServiceRelocationEnvelope,
@@ -42,8 +45,8 @@ export class ServiceCapturedObjectRelocation {
 
   async commitSource(): Promise<void> {
     if (this.terminal === 'committed') return;
-    if (this.terminal === 'aborted') {
-      throw new Error('Relocation source capture was already aborted.');
+    if (this.terminal !== 'open') {
+      throw new Error(`Relocation source capture was already ${this.terminal}.`);
     }
     for (const unit of this.units) await unit.commitSeal();
     this.terminal = 'committed';
@@ -51,8 +54,8 @@ export class ServiceCapturedObjectRelocation {
 
   async abortSource(): Promise<void> {
     if (this.terminal === 'aborted') return;
-    if (this.terminal === 'committed') {
-      throw new Error('Committed relocation source capture cannot be aborted.');
+    if (this.terminal !== 'open') {
+      throw new Error(`A ${this.terminal} relocation source capture cannot be aborted.`);
     }
     const failures: unknown[] = [];
     for (const unit of [...this.units].reverse()) {
@@ -67,11 +70,24 @@ export class ServiceCapturedObjectRelocation {
       throw new AggregateError(failures, 'Relocation source rollback was incomplete.');
     }
   }
+
+  /**
+   * The source owner lease ended before the authority settled (spec 28 §4.4):
+   * the source neither resumes nor commits. Retained work is dropped and
+   * every pending request without a terminal fails once with `reason`.
+   */
+  async discardSource(reason: unknown): Promise<void> {
+    if (this.terminal !== 'open') return;
+    this.terminal = 'discarded';
+    for (const unit of this.units) await unit.discardSeal?.(reason);
+  }
 }
 
 /** Captures the two valid relocation units: User Spot aggregate or one Actor. */
 export class ServiceRelocationObjectCaptureOwner {
-  constructor(private readonly maxConcurrentCallbacks = 8) {
+  constructor(
+    private readonly maxConcurrentCallbacks: number = DEFAULT_RELOCATION_CALLBACK_CONCURRENCY
+  ) {
     requireCallbackConcurrency(maxConcurrentCallbacks);
   }
 
@@ -241,7 +257,7 @@ export class ServiceRelocationObjectRestoreOwner<
   constructor(
     private readonly target: ServiceRelocationTargetObjectPort<THidden>,
     private readonly authorityKey: (value: string) => ZLinkAuthorityKey,
-    private readonly maxConcurrentCallbacks = 8
+    private readonly maxConcurrentCallbacks: number = DEFAULT_RELOCATION_CALLBACK_CONCURRENCY
   ) {
     requireCallbackConcurrency(maxConcurrentCallbacks);
   }