@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,242 @@
+import { AsyncResource } from 'node:async_hooks';
+import { ZLinkStateLane } from '../execution/state-lane';
+
+const detachedStateLaneResource = new AsyncResource('zlink:service-maintenance-runtime');
+
+export type ServiceMaintenanceKind = 'retire' | 'shutdown';
+export type ServiceMaintenanceState =
+  | 'serving' | 'preparing' | 'retiring' | 'draining'
+  | 'completed' | 'blocked' | 'forceStopped';
+
+export interface ServiceRelocationUnit {
+  readonly id: string;
+  readonly ready: () => boolean;
+  readonly relocate: (signal: AbortSignal) => Promise<void>;
+}
+
+export interface ServiceMaintenanceSnapshot {
+  readonly kind?: ServiceMaintenanceKind;
+  readonly state: ServiceMaintenanceState;
+  readonly queued: number;
+  readonly activeOutbound: number;
+  readonly terminalError?: unknown;
+}
+
+export interface ServiceMaintenanceOptions {
+  readonly preflight: (kind: ServiceMaintenanceKind, signal: AbortSignal) => Promise<boolean>;
+  readonly publishState: (state: 'retiring' | 'draining') => void;
+  readonly forceStop: () => Promise<void> | void;
+}
+
+/** Owns first-intent-wins maintenance admission and terminal observation. */
+export class ServiceMaintenanceRuntime {
+  private readonly lane = new ZLinkStateLane();
+  private readonly units: ServiceRelocationUnit[] = [];
+  private readonly observers = new Set<(snapshot: ServiceMaintenanceSnapshot) => void>();
+  private activeOutbound = 0;
+  private state: ServiceMaintenanceState = 'serving';
+  private kind?: ServiceMaintenanceKind;
+  private terminalError?: unknown;
+  private operation?: Promise<ServiceMaintenanceSnapshot>;
+
+  constructor(private readonly options: ServiceMaintenanceOptions) {}
+
+  enqueue(unit: ServiceRelocationUnit): void {
+    if (this.state !== 'serving' && this.state !== 'preparing' && this.state !== 'retiring') {
+      throw new Error('Maintenance admission is sealed.');
+    }
+    if (unit.id.length === 0) {
+      throw new TypeError('Relocation unit identity must be valid.');
+    }
+    this.units.push(unit);
+    this.publish();
+  }
+
+  observe(observer: (snapshot: ServiceMaintenanceSnapshot) => void): () => void {
+    this.observers.add(observer);
+    observer(this.snapshot());
+    return () => this.observers.delete(observer);
+  }
+
+  start(
+    kind: ServiceMaintenanceKind,
+    deadlineMs: number,
+    stopStartingSignal?: AbortSignal,
+    abortSignal?: AbortSignal
+  ): Promise<ServiceMaintenanceSnapshot> {
+    if (this.operation !== undefined) return this.operation;
+    if (!Number.isFinite(deadlineMs) || deadlineMs < 0) {
+      throw new RangeError('Maintenance deadline must be non-negative and finite.');
+    }
+    this.kind = kind;
+    let resolve!: (snapshot: ServiceMaintenanceSnapshot) => void;
+    let reject!: (error: unknown) => void;
+    const operation = new Promise<ServiceMaintenanceSnapshot>((complete, fail) => {
+      resolve = complete;
+      reject = fail;
+    });
+    // Install first: publishing the synchronous preparing transition can
+    // re-enter start(), which must observe this first intent rather than
+    // create a second maintenance operation.
+    this.operation = operation;
+    void this.run(kind, deadlineMs, stopStartingSignal, abortSignal).then(resolve, reject);
+    return operation;
+  }
+
+  snapshot(): ServiceMaintenanceSnapshot {
+    return this.snapshotCore();
+  }
+
+  private snapshotCore(): ServiceMaintenanceSnapshot {
+    return {
+      ...(this.kind === undefined ? {} : { kind: this.kind }),
+      state: this.state,
+      queued: this.units.length,
+      activeOutbound: this.activeOutbound,
+      ...(this.terminalError === undefined ? {} : { terminalError: this.terminalError })
+    };
+  }
+
+  private async run(
+    kind: ServiceMaintenanceKind,
+    deadlineMs: number,
+    stopStartingSignal?: AbortSignal,
+    abortSignal?: AbortSignal
+  ): Promise<ServiceMaintenanceSnapshot> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('Maintenance deadline exceeded.')), deadlineMs);
+    const abort = () => controller.abort(abortSignal?.reason);
+    if (abortSignal?.aborted === true) {
+      abort();
+    } else {
+      abortSignal?.addEventListener('abort', abort, { once: true });
+    }
+    try {
+      this.transition('preparing');
+      if (!await this.options.preflight(kind, controller.signal)) {
+        return await this.transitionAsync('blocked');
+      }
+      if (kind === 'retire') {
+        this.options.publishState('retiring');
+        await this.transitionAsync('retiring');
+        await this.runUnits(controller.signal, stopStartingSignal);
+      }
+      this.options.publishState('draining');
+      await this.transitionAsync('draining');
+      return await this.transitionAsync('completed');
+    } catch (error) {
+      const blocked = await this.lane.run(() => {
+        this.terminalError = error;
+        return this.state === 'preparing';
+      });
+      if (blocked) {
+        return await this.transitionAsync('blocked');
+      } else {
+        await this.options.forceStop();
+        return await this.transitionAsync('forceStopped');
+      }
+    } finally {
+      clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', abort);
+    }
+  }
+
+  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);
+      if (!queued && pending.size === 0) return;
+      signal.throwIfAborted();
+      if (stopStartingSignal?.aborted === true) {
+        await Promise.allSettled(pending);
+        stopStartingSignal.throwIfAborted();
+      }
+      let admitted = false;
+      for (let index = 0;;) {
+        if (stopStartingSignal?.aborted === true) break;
+        const unit = await this.lane.run(() => this.units.at(index));
+        if (unit === undefined) break;
+        if (!unit.ready()) {
+          index++;
+          continue;
+        }
+        const claim = await this.lane.run(() => {
+          const current = this.units.indexOf(unit);
+          if (current < 0) return { claimed: false };
+          this.units.splice(current, 1);
+          this.activeOutbound++;
+          return { claimed: true, publication: this.publishCore() };
+        });
+        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);
+        }));
+        pending.add(running);
+        this.notify(claim.publication);
+      }
+      if (pending.size === 0) {
+        if (!admitted) throw new Error('No relocation unit is ready to start.');
+      } else {
+        await Promise.race(pending);
+      }
+    }
+  }
+
+  private transition(state: ServiceMaintenanceState): void {
+    this.state = state;
+    this.publish();
+  }
+
+  private async transitionAsync(state: ServiceMaintenanceState): Promise<ServiceMaintenanceSnapshot> {
+    const publication = await this.lane.run(() => {
+      this.state = state;
+      return this.publishCore();
+    });
+    this.notify(publication);
+    return publication.snapshot;
+  }
+
+  private publish(): void {
+    this.notify(this.publishCore());
+  }
+
+  private publishCore(): {
+    readonly snapshot: ServiceMaintenanceSnapshot;
+    readonly observers: readonly ((snapshot: ServiceMaintenanceSnapshot) => void)[];
+  } {
+    return { snapshot: this.snapshotCore(), observers: [...this.observers] };
+  }
+
+  private notify(publication: {
+    readonly snapshot: ServiceMaintenanceSnapshot;
+    readonly observers: readonly ((snapshot: ServiceMaintenanceSnapshot) => void)[];
+  }): void {
+    for (const observer of publication.observers) observer(publication.snapshot);
+  }
+}
+
+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

@@ -0,0 +1,75 @@
+const MAX_METADATA_BYTES = 1024;
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
+
+export function encodeServiceMetadataFrame(
+  entries: ReadonlyMap<string, string>
+): Buffer {
+  if (entries.size > 0xff) {
+    throw new RangeError('Application metadata contains more than 255 entries.');
+  }
+  const encoded: Buffer[] = [Buffer.of(1, entries.size)];
+  for (const [key, value] of entries) {
+    const keyBytes = textBytes(key, 1, 0xff, 'metadata key');
+    const valueBytes = textBytes(value, 0, 0xffff, 'metadata value');
+    const valueLength = Buffer.allocUnsafe(2);
+    valueLength.writeUInt16BE(valueBytes.byteLength);
+    encoded.push(Buffer.of(keyBytes.byteLength), keyBytes, valueLength, valueBytes);
+  }
+  return validateServiceMetadataFrame(Buffer.concat(encoded));
+}
+
+export function validateServiceMetadataFrame(frame: Uint8Array): Buffer {
+  if (frame.byteLength > MAX_METADATA_BYTES) {
+    throw new RangeError('Application metadata frame exceeds 1024 bytes.');
+  }
+  const bytes = Buffer.from(frame);
+  let offset = 0;
+  const take = (length: number): Buffer => {
+    if (length < 0 || offset + length > bytes.byteLength) {
+      throw new TypeError('Application metadata frame is truncated.');
+    }
+    const value = bytes.subarray(offset, offset + length);
+    offset += length;
+    return value;
+  };
+  if (take(1)[0] !== 1) {
+    throw new TypeError('Application metadata frame version is invalid.');
+  }
+  const count = take(1)[0]!;
+  const keys = new Set<string>();
+  for (let index = 0; index < count; index += 1) {
+    const key = take(take(1)[0]!);
+    if (key.byteLength === 0 || key.includes(0)) {
+      throw new TypeError('Application metadata key is invalid.');
+    }
+    FATAL_UTF8.decode(key);
+    const keyIdentity = key.toString('hex');
+    if (keys.has(keyIdentity)) {
+      throw new TypeError('Application metadata keys must be unique.');
+    }
+    keys.add(keyIdentity);
+    const valueLength = take(2).readUInt16BE();
+    const value = take(valueLength);
+    if (value.includes(0)) {
+      throw new TypeError('Application metadata value is invalid.');
+    }
+    FATAL_UTF8.decode(value);
+  }
+  if (offset !== bytes.byteLength) {
+    throw new TypeError('Application metadata frame has trailing bytes.');
+  }
+  return Buffer.from(bytes);
+}
+
+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.`);
+  }
+  return bytes;
+}

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

@@ -0,0 +1,218 @@
+import type {
+  ZLinkAggregateFence,
+  ZLinkAggregateId,
+  ZLinkAggregateParticipant,
+  ZLinkAuthorityKey,
+  ZLinkAuthoritySnapshot,
+  ZLinkCapacityVector,
+  ZLinkLocationOwnerToken,
+  ZLinkMeshNodeDescriptorKey
+} from '../locations/internal-location-contracts';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
+import {
+  inventoryDigest,
+  type ServiceRelocationEnvelope
+} from './service-relocation-runtime';
+
+export interface ServiceRelocationAggregateParticipantPlan {
+  readonly key: ZLinkAuthorityKey;
+  readonly expected: ZLinkAuthoritySnapshot;
+  readonly ownerTransition: 'preserve' | 'newOwner';
+  readonly authorityPayload: Uint8Array;
+  readonly membershipMutation: Uint8Array;
+}
+
+export interface ServiceRelocationAggregatePlan {
+  readonly envelope: ServiceRelocationEnvelope;
+  readonly participants: readonly ServiceRelocationAggregateParticipantPlan[];
+  readonly targetDescriptor: ZLinkMeshNodeDescriptorKey;
+  readonly targetDescriptorLifecycleGeneration: bigint;
+  readonly capacity: ZLinkCapacityVector;
+  readonly targetOwner: ZLinkLocationOwnerToken;
+}
+
+export interface ServicePreparedRelocationAggregate {
+  readonly fence: ZLinkAggregateFence;
+  readonly plan: ServiceRelocationAggregatePlan;
+}
+
+type AggregateStore = Pick<
+  ZLinkObjectCreationStore,
+  'prepareAggregate' | 'commitAggregate' | 'abortAggregate'
+> & Pick<ZLinkAuthorityStore, 'readAuthority'>;
+
+const MAX_PREPARE_CONFLICT_ATTEMPTS = 8;
+
+/** Commits every owner and membership row through one Location Store fence. */
+export class ServiceRelocationAggregateCommitter {
+  constructor(private readonly store: AggregateStore) {}
+
+  async prepare(
+    plan: ServiceRelocationAggregatePlan,
+    signal?: AbortSignal
+  ): Promise<ServicePreparedRelocationAggregate> {
+    const participants = validateAndEncodeParticipants(plan);
+    const aggregateId = aggregateIdentity(plan.envelope.aggregateId);
+    const request = {
+      aggregateId,
+      aggregateGeneration: plan.envelope.aggregateGeneration,
+      participants,
+      inventoryDigest: Buffer.from(
+        inventoryDigest(plan.envelope.participants, plan.envelope.memberships),
+        'hex'
+      ),
+      targetDescriptor: plan.targetDescriptor,
+      targetDescriptorLifecycleGeneration: plan.targetDescriptorLifecycleGeneration,
+      capacity: plan.capacity,
+      targetOwner: plan.targetOwner
+    };
+    let result = await this.store.prepareAggregate(request, signal);
+    for (
+      let attempt = 1;
+      attempt < MAX_PREPARE_CONFLICT_ATTEMPTS && result.kind === 'conflict';
+      attempt++
+    ) {
+      // The provider CAS also fences auxiliary live-owner and capacity rows.
+      // 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;
+      signal?.throwIfAborted();
+      result = await this.store.prepareAggregate(request, signal);
+    }
+    if (result.kind !== 'prepared' && result.kind !== 'alreadyPrepared') {
+      throw new Error(`Location Store rejected relocation aggregate prepare: ${result.kind}.`);
+    }
+    if (
+      result.fence.aggregateId.value !== aggregateId.value
+      || result.fence.aggregateGeneration !== plan.envelope.aggregateGeneration
+    ) {
+      throw new Error('Location Store returned a different relocation aggregate fence.');
+    }
+    return { fence: result.fence, plan };
+  }
+
+  private async authorityStoreVersionsUnchanged(
+    plan: ServiceRelocationAggregatePlan,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    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
+      ) {
+        return false;
+      }
+    }
+    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(
+  plan: ServiceRelocationAggregatePlan
+): readonly ZLinkAggregateParticipant[] {
+  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));
+  if (
+    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 => {
+    const envelope = envelopeByKey.get(participant.key.value);
+    if (
+      envelope === undefined
+      || envelope.objectGeneration !== participant.expected.objectGeneration
+      || envelope.authorityOwnerGeneration !== participant.expected.authorityOwnerGeneration
+    ) {
+      throw new TypeError('Relocation aggregate participant fence differs from its envelope.');
+    }
+    return {
+      authorityKey: participant.key,
+      expectedStoreVersion: participant.expected.storeVersion,
+      ownerTransition: participant.ownerTransition,
+      authorityPayload: Buffer.from(participant.authorityPayload),
+      membershipMutation: Buffer.from(participant.membershipMutation)
+    };
+  });
+}
+
+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)) {
+    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

@@ -0,0 +1,37 @@
+import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type { ServiceRelocationEnvelope } from './service-relocation-runtime';
+
+export interface ServiceRelocationStaging {
+  readonly id: string;
+}
+
+export interface ServiceRelocationRestoreOwner<TStaging extends ServiceRelocationStaging> {
+  prepare(
+    envelope: ServiceRelocationEnvelope,
+    signal?: AbortSignal
+  ): Promise<TStaging>;
+  publish(
+    staging: TStaging,
+    authority: ZLinkAuthoritySnapshot,
+    signal?: AbortSignal
+  ): Promise<void>;
+  restoreSavedWork(staging: TStaging, signal?: AbortSignal): Promise<void>;
+  normalize(
+    staging: TStaging,
+    authority: ZLinkAuthoritySnapshot,
+    signal?: AbortSignal
+  ): Promise<void>;
+  openAdmission(staging: TStaging, signal?: AbortSignal): Promise<void>;
+  abort(staging: TStaging): Promise<void> | void;
+}
+
+export class ServiceRelocationPostCommitError extends Error {
+  constructor(
+    readonly authority: ZLinkAuthoritySnapshot,
+    readonly staging: ServiceRelocationStaging,
+    readonly cause: unknown
+  ) {
+    super('Relocation owner committed, but target publication failed.');
+    this.name = 'ServiceRelocationPostCommitError';
+  }
+}