@zlink-systems/framework 0.21.0 → 0.22.0

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

@@ -1,6 +1,4 @@
-import type {
-  ApplicationJobRecordLease
-} from '../application-jobs/application-ingress-record-owner';
+import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
 
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 
@@ -59,12 +57,15 @@ interface DomainState {
 export class ServiceMailbox {
   private readonly application: DomainState;
   private readonly infrastructure: DomainState;
-  private readonly relocationSeals = new Map<string, {
-    readonly serial: bigint;
-    readonly captured: ServiceMailboxRecord[];
-    readonly held: ServiceMailboxRecord[];
-    heldBytes: number;
-  }>();
+  private readonly relocationSeals = new Map<
+    string,
+    {
+      readonly serial: bigint;
+      readonly captured: ServiceMailboxRecord[];
+      readonly held: ServiceMailboxRecord[];
+      heldBytes: number;
+    }
+  >();
   private readonly relocatedOwners = new Set<string>();
   private nextClaimSerial = 1n;
   private nextRelocationSerial = 1n;
@@ -154,10 +155,7 @@ export class ServiceMailbox {
     }
   }
 
-  release(
-    claim: ServiceMailboxClaim,
-    remaining: readonly ServiceMailboxRecord[] = []
-  ): boolean {
+  release(claim: ServiceMailboxClaim, remaining: readonly ServiceMailboxRecord[] = []): boolean {
     const target = this.domain(claim.domain);
     const queue = target.owners.get(claim.owner);
     if (queue === undefined || !queue.claimed || queue.claimSerial !== claim.serial) return false;
@@ -217,7 +215,9 @@ export class ServiceMailbox {
     return true;
   }
 
-  commitRelocation(seal: ServiceMailboxRelocationSeal): readonly ServiceMailboxRecord[] | undefined {
+  commitRelocation(
+    seal: ServiceMailboxRelocationSeal
+  ): readonly ServiceMailboxRecord[] | undefined {
     const current = this.relocationSeals.get(seal.owner);
     if (current === undefined || current.serial !== seal.serial) return undefined;
     this.relocationSeals.delete(seal.owner);

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

@@ -5,8 +5,7 @@ const detachedStateLaneResource = new AsyncResource('zlink:service-maintenance-r
 
 export type ServiceMaintenanceKind = 'retire' | 'shutdown';
 export type ServiceMaintenanceState =
-  | 'serving' | 'preparing' | 'retiring' | 'draining'
-  | 'completed' | 'blocked' | 'forceStopped';
+  'serving' | 'preparing' | 'retiring' | 'draining' | 'completed' | 'blocked' | 'forceStopped';
 
 export interface ServiceRelocationUnit {
   readonly id: string;
@@ -104,7 +103,10 @@ export class ServiceMaintenanceRuntime {
     abortSignal?: AbortSignal
   ): Promise<ServiceMaintenanceSnapshot> {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error('Maintenance deadline exceeded.')), deadlineMs);
+    const timer = setTimeout(
+      () => controller.abort(new Error('Maintenance deadline exceeded.')),
+      deadlineMs
+    );
     const abort = () => controller.abort(abortSignal?.reason);
     if (abortSignal?.aborted === true) {
       abort();
@@ -113,7 +115,7 @@ export class ServiceMaintenanceRuntime {
     }
     try {
       this.transition('preparing');
-      if (!await this.options.preflight(kind, controller.signal)) {
+      if (!(await this.options.preflight(kind, controller.signal))) {
         return await this.transitionAsync('blocked');
       }
       if (kind === 'retire') {
@@ -141,10 +143,7 @@ export class ServiceMaintenanceRuntime {
     }
   }
 
-  private async runUnits(
-    signal: AbortSignal,
-    stopStartingSignal?: AbortSignal
-  ): Promise<void> {
+  private async runUnits(signal: AbortSignal, stopStartingSignal?: AbortSignal): Promise<void> {
     const pending = new Set<Promise<void>>();
     for (;;) {
       const queued = await this.lane.run(() => this.units.length > 0);
@@ -155,7 +154,7 @@ export class ServiceMaintenanceRuntime {
         stopStartingSignal.throwIfAborted();
       }
       let admitted = false;
-      for (let index = 0;;) {
+      for (let index = 0; ;) {
         if (stopStartingSignal?.aborted === true) break;
         const unit = await this.lane.run(() => this.units.at(index));
         if (unit === undefined) break;
@@ -173,14 +172,16 @@ export class ServiceMaintenanceRuntime {
         if (!claim.claimed || claim.publication === undefined) continue;
         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);
-        }));
+        running = startOutsideStateLane(() =>
+          unit.relocate(signal).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);
       }
@@ -197,7 +198,9 @@ export class ServiceMaintenanceRuntime {
     this.publish();
   }
 
-  private async transitionAsync(state: ServiceMaintenanceState): Promise<ServiceMaintenanceSnapshot> {
+  private async transitionAsync(
+    state: ServiceMaintenanceState
+  ): Promise<ServiceMaintenanceSnapshot> {
     const publication = await this.lane.run(() => {
       this.state = state;
       return this.publishCore();
@@ -236,7 +239,5 @@ export function classifyRelocationRecovery(
   inventoryMatches: boolean
 ): 'resume' | 'orphan' | 'relocationDataLost' {
   if (!publishedReference) return payloadPresent ? 'orphan' : 'resume';
-  return payloadPresent && checksumMatches && inventoryMatches
-    ? 'resume'
-    : 'relocationDataLost';
+  return payloadPresent && checksumMatches && inventoryMatches ? 'resume' : 'relocationDataLost';
 }

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

@@ -1,9 +1,7 @@
 const MAX_METADATA_BYTES = 1024;
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 
-export function encodeServiceMetadataFrame(
-  entries: ReadonlyMap<string, string>
-): Buffer {
+export function encodeServiceMetadataFrame(entries: ReadonlyMap<string, string>): Buffer {
   if (entries.size > 0xff) {
     throw new RangeError('Application metadata contains more than 255 entries.');
   }
@@ -61,12 +59,7 @@ export function validateServiceMetadataFrame(frame: Uint8Array): Buffer {
   return Buffer.from(bytes);
 }
 
-function textBytes(
-  value: string,
-  minimum: number,
-  maximum: number,
-  name: string
-): Buffer {
+function textBytes(value: string, minimum: number, maximum: number, name: string): Buffer {
   const bytes = Buffer.from(value, 'utf8');
   if (bytes.byteLength < minimum || bytes.byteLength > maximum || bytes.includes(0)) {
     throw new RangeError(`${name} must contain ${minimum}..${maximum} UTF-8 bytes without NUL.`);

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

@@ -8,11 +8,11 @@ import type {
   ZLinkLocationOwnerToken,
   ZLinkMeshNodeDescriptorKey
 } from '../locations/internal-location-contracts';
-import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
-import {
-  inventoryDigest,
-  type ServiceRelocationEnvelope
-} from './service-relocation-runtime';
+import type {
+  ZLinkAuthorityStore,
+  ZLinkObjectCreationStore
+} from '../locations/internal-store-contracts';
+import { inventoryDigest, type ServiceRelocationEnvelope } from './service-relocation-runtime';
 
 export interface ServiceRelocationAggregateParticipantPlan {
   readonly key: ZLinkAuthorityKey;
@@ -39,7 +39,8 @@ export interface ServicePreparedRelocationAggregate {
 type AggregateStore = Pick<
   ZLinkObjectCreationStore,
   'prepareAggregate' | 'commitAggregate' | 'abortAggregate'
-> & Pick<ZLinkAuthorityStore, 'readAuthority'>;
+> &
+  Pick<ZLinkAuthorityStore, 'readAuthority'>;
 
 const MAX_PREPARE_CONFLICT_ATTEMPTS = 8;
 
@@ -76,7 +77,7 @@ export class ServiceRelocationAggregateCommitter {
       // A heartbeat can change one of those versions while every authority
       // row remains the exact Store-confirmed value in this plan. Retry only
       // that coordination loss; a changed authority row leaves immediately.
-      if (!await this.authorityStoreVersionsUnchanged(plan, signal)) break;
+      if (!(await this.authorityStoreVersionsUnchanged(plan, signal))) break;
       signal?.throwIfAborted();
       result = await this.store.prepareAggregate(request, signal);
     }
@@ -84,8 +85,8 @@ export class ServiceRelocationAggregateCommitter {
       throw new Error(`Location Store rejected relocation aggregate prepare: ${result.kind}.`);
     }
     if (
-      result.fence.aggregateId.value !== aggregateId.value
-      || result.fence.aggregateGeneration !== plan.envelope.aggregateGeneration
+      result.fence.aggregateId.value !== aggregateId.value ||
+      result.fence.aggregateGeneration !== plan.envelope.aggregateGeneration
     ) {
       throw new Error('Location Store returned a different relocation aggregate fence.');
     }
@@ -99,8 +100,8 @@ export class ServiceRelocationAggregateCommitter {
     for (const participant of plan.participants) {
       const current = await this.store.readAuthority(participant.key, signal);
       if (
-        current.kind !== 'snapshot'
-        || current.storeVersion.value !== participant.expected.storeVersion.value
+        current.kind !== 'snapshot' ||
+        current.storeVersion.value !== participant.expected.storeVersion.value
       ) {
         return false;
       }
@@ -125,10 +126,7 @@ export class ServiceRelocationAggregateCommitter {
     return await this.readCommittedParticipants(prepared.plan, signal);
   }
 
-  async abort(
-    prepared: ServicePreparedRelocationAggregate,
-    signal?: AbortSignal
-  ): Promise<void> {
+  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}.`);
@@ -150,25 +148,27 @@ export class ServiceRelocationAggregateCommitter {
     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))
+        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.');
+        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
+          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
+        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.');
       }
@@ -181,21 +181,22 @@ export class ServiceRelocationAggregateCommitter {
 function validateAndEncodeParticipants(
   plan: ServiceRelocationAggregatePlan
 ): readonly ZLinkAggregateParticipant[] {
-  const envelopeByKey = new Map(plan.envelope.participants.map(value => [value.key, value]));
+  const envelopeByKey = new Map(plan.envelope.participants.map((value) => [value.key, value]));
   const ordered = [...plan.participants].sort((left, right) =>
-    left.key.value.localeCompare(right.key.value));
+    left.key.value.localeCompare(right.key.value)
+  );
   if (
-    ordered.length !== plan.envelope.participants.length
-    || new Set(ordered.map(({ key }) => key.value)).size !== ordered.length
+    ordered.length !== plan.envelope.participants.length ||
+    new Set(ordered.map(({ key }) => key.value)).size !== ordered.length
   ) {
     throw new TypeError('Relocation aggregate plan must cover every participant exactly once.');
   }
-  return ordered.map(participant => {
+  return ordered.map((participant) => {
     const envelope = envelopeByKey.get(participant.key.value);
     if (
-      envelope === undefined
-      || envelope.objectGeneration !== participant.expected.objectGeneration
-      || envelope.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration
+      envelope === undefined ||
+      envelope.objectGeneration !== participant.expected.objectGeneration ||
+      envelope.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration
     ) {
       throw new TypeError('Relocation aggregate participant fence differs from its envelope.');
     }
@@ -210,8 +211,10 @@ function validateAndEncodeParticipants(
 }
 
 function aggregateIdentity(value: string): ZLinkAggregateId {
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)
-    || /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(value)) {
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value) ||
+    /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(value)
+  ) {
     throw new TypeError('Relocation aggregate id must be a lowercase non-zero 128-bit identity.');
   }
   return { value } as ZLinkAggregateId;

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

@@ -6,10 +6,7 @@ export interface ServiceRelocationStaging {
 }
 
 export interface ServiceRelocationRestoreOwner<TStaging extends ServiceRelocationStaging> {
-  prepare(
-    envelope: ServiceRelocationEnvelope,
-    signal?: AbortSignal
-  ): Promise<TStaging>;
+  prepare(envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<TStaging>;
   publish(
     staging: TStaging,
     authority: ZLinkAuthoritySnapshot,

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

@@ -1,4 +1,7 @@
-import type { ZLinkAuthorityKey, ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type {
+  ZLinkAuthorityKey,
+  ZLinkAuthoritySnapshot
+} from '../locations/internal-location-contracts';
 import type {
   ServiceRelocationRestoreOwner,
   ServiceRelocationStaging
@@ -80,7 +83,7 @@ export class ServiceRelocationObjectCaptureOwner {
     memberships: readonly ServiceRelocationMembership[],
     signal?: AbortSignal
   ): Promise<ServiceCapturedObjectRelocation> {
-    if (spot.objectKind !== 'user_spot' || actors.some(actor => actor.objectKind !== 'actor')) {
+    if (spot.objectKind !== 'user_spot' || actors.some((actor) => actor.objectKind !== 'actor')) {
       throw new TypeError('User Spot relocation requires one Spot and only Actor participants.');
     }
     if (actors.length !== memberships.length) {
@@ -105,13 +108,7 @@ export class ServiceRelocationObjectCaptureOwner {
     if (actor.objectKind !== 'actor' || membership.actorKey !== actor.authorityKey) {
       throw new TypeError('Standalone Actor relocation has an invalid membership identity.');
     }
-    return await this.capture(
-      aggregateId,
-      aggregateGeneration,
-      [actor],
-      [membership],
-      signal
-    );
+    return await this.capture(aggregateId, aggregateGeneration, [actor], [membership], signal);
   }
 
   async captureInstanceSpotAggregate(
@@ -122,8 +119,10 @@ export class ServiceRelocationObjectCaptureOwner {
     memberships: readonly ServiceRelocationMembership[],
     signal?: AbortSignal
   ): Promise<ServiceCapturedObjectRelocation> {
-    if (spot.objectKind !== 'instance_spot'
-      || actors.some(actor => actor.objectKind !== 'actor')) {
+    if (
+      spot.objectKind !== 'instance_spot' ||
+      actors.some((actor) => actor.objectKind !== 'actor')
+    ) {
       throw new TypeError(
         'Instance Spot relocation requires one Spot and only Actor participants.'
       );
@@ -170,20 +169,23 @@ export class ServiceRelocationObjectCaptureOwner {
           authorityOwnerGeneration: unit.authorityOwnerGeneration,
           applicationState: Buffer.from(await unit.captureApplicationState(signal)),
           boundSessionState: Buffer.from(work.boundSessionState),
-          queuedMessages: work.queuedMessages.map(message => ({
+          queuedMessages: work.queuedMessages.map((message) => ({
             sequence: message.sequence,
             payload: Buffer.from(message.payload)
           })),
-          timers: work.timers.map(timer => ({ ...timer }))
+          timers: work.timers.map((timer) => ({ ...timer }))
         }),
         signal
       );
-      return new ServiceCapturedObjectRelocation({
-        aggregateId,
-        aggregateGeneration,
-        participants,
-        memberships
-      }, units);
+      return new ServiceCapturedObjectRelocation(
+        {
+          aggregateId,
+          aggregateGeneration,
+          participants,
+          memberships
+        },
+        units
+      );
     } catch (error) {
       for (const { unit } of captured.reverse()) await unit.abortSeal();
       throw error;
@@ -195,13 +197,8 @@ export interface ServiceRelocationHiddenObject {
   readonly authorityKey: string;
 }
 
-export interface ServiceRelocationTargetObjectPort<
-  THidden extends ServiceRelocationHiddenObject
-> {
-  createHidden(
-    participant: ServiceRelocationParticipant,
-    signal?: AbortSignal
-  ): Promise<THidden>;
+export interface ServiceRelocationTargetObjectPort<THidden extends ServiceRelocationHiddenObject> {
+  createHidden(participant: ServiceRelocationParticipant, signal?: AbortSignal): Promise<THidden>;
   restoreApplicationState(
     hidden: THidden,
     payload: Uint8Array,
@@ -212,26 +209,14 @@ export interface ServiceRelocationTargetObjectPort<
     memberships: readonly ServiceRelocationMembership[],
     signal?: AbortSignal
   ): Promise<void>;
-  publish(
-    hidden: THidden,
-    authority: ZLinkAuthoritySnapshot,
-    signal?: AbortSignal
-  ): Promise<void>;
-  restoreBoundSession(
-    hidden: THidden,
-    payload: Uint8Array,
-    signal?: AbortSignal
-  ): Promise<void>;
+  publish(hidden: THidden, authority: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<void>;
+  restoreBoundSession(hidden: THidden, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
   replayQueuedMessage(
     hidden: THidden,
     message: ServiceRelocationQueuedMessage,
     signal?: AbortSignal
   ): Promise<void>;
-  restoreTimer(
-    hidden: THidden,
-    timer: ServiceRelocationTimer,
-    signal?: AbortSignal
-  ): Promise<void>;
+  restoreTimer(hidden: THidden, timer: ServiceRelocationTimer, signal?: AbortSignal): Promise<void>;
   normalize(
     hidden: THidden,
     authority: ZLinkAuthoritySnapshot,
@@ -285,16 +270,18 @@ export class ServiceRelocationObjectRestoreOwner<
       await mapConcurrentOrdered(
         participants,
         this.maxConcurrentCallbacks,
-        participant => this.target.restoreApplicationState(
-          hidden.get(participant.key)!,
-          participant.applicationState,
-          signal
-        ),
+        (participant) =>
+          this.target.restoreApplicationState(
+            hidden.get(participant.key)!,
+            participant.applicationState,
+            signal
+          ),
         signal
       );
       await this.target.restoreMemberships(hidden, envelope.memberships, signal);
-      const spot = envelope.participants.find(({ objectKind }) =>
-        objectKind === 'user_spot' || objectKind === 'instance_spot');
+      const spot = envelope.participants.find(
+        ({ objectKind }) => objectKind === 'user_spot' || objectKind === 'instance_spot'
+      );
       const primary = spot ?? envelope.participants[0]!;
       return {
         id: `${envelope.aggregateId}:${envelope.aggregateGeneration}`,
@@ -324,11 +311,7 @@ export class ServiceRelocationObjectRestoreOwner<
   ): Promise<void> {
     for (const participant of staging.envelope.participants) {
       const hidden = staging.hidden.get(participant.key)!;
-      await this.target.restoreBoundSession(
-        hidden,
-        participant.boundSessionState,
-        signal
-      );
+      await this.target.restoreBoundSession(hidden, participant.boundSessionState, signal);
       for (const message of participant.queuedMessages) {
         await this.target.replayQueuedMessage(hidden, message, signal);
       }
@@ -379,8 +362,9 @@ export class ServiceRelocationObjectRestoreOwner<
 }
 
 function validateRelocationShape(envelope: ServiceRelocationEnvelope): void {
-  const spots = envelope.participants.filter(({ objectKind }) =>
-    objectKind === 'user_spot' || objectKind === 'instance_spot');
+  const spots = envelope.participants.filter(
+    ({ objectKind }) => objectKind === 'user_spot' || objectKind === 'instance_spot'
+  );
   const actors = envelope.participants.filter(({ objectKind }) => objectKind === 'actor');
   if (spots.length === 0 && (actors.length !== 1 || envelope.participants.length !== 1)) {
     throw new TypeError('Standalone relocation must contain exactly one Actor.');
@@ -420,9 +404,7 @@ async function mapConcurrentOrdered<TInput, TResult>(
       }
     }
   };
-  await Promise.all(
-    Array.from({ length: Math.min(concurrency, values.length) }, () => worker())
-  );
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => worker()));
   if (failure !== undefined) throw failure;
   return results;
 }