@zlink-systems/framework 0.10.0

package/src/runtime/host/location-runtime-owner.ts

@@ -0,0 +1,313 @@
+import type { RoutingId } from '../../contracts';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import type { ZLinkActorTransferStore } from '../../contracts/Locations/ActorTransfer';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkChannelRuntimeManager } from '../channels';
+import {
+  ZLinkInMemoryProviderLocationStore,
+  ZLinkLocationLifecycle,
+  ZLinkLocationRuntime,
+  ZLinkLocationStoreRepository,
+  ZLinkLocationSpotRouteResolver,
+  ZLinkOwnerLeaseTracker,
+  ZLinkStoreLocationResolvers,
+  type ZLinkLocationEventSink,
+  type ZLinkLocationRuntimeStores,
+  type ZLinkDomainLocationStore
+} from '../locations';
+import type { ZLinkSpotNodeRuntimeManager } from '../spots';
+import type { ZLinkSpotRouteResolver } from '../spots/spot-routing-internal';
+
+export interface ZLinkLocationRuntimeOwnerOptions {
+  readonly registration: ZLinkFrameworkRegistration;
+  readonly runtimeEventPublisher: ZLinkRuntimeEventPublisher;
+  readonly fallbackNodeRid: RoutingId;
+  readonly metrics: import('../diagnostics').ZLinkRuntimeMetrics;
+  readonly rewriteAuthorityPayloadForOwner?: import('../locations').ZLinkLocationRuntimeOptions['rewriteAuthorityPayloadForOwner'];
+}
+
+export interface ZLinkLocationRuntimeStopSnapshot {
+  readonly runtime?: ZLinkLocationRuntime;
+  readonly lifecycle?: ZLinkLocationLifecycle;
+}
+
+export class ZLinkLocationRuntimeOwner {
+  private stores?: ZLinkLocationRuntimeStores;
+  private runtime?: ZLinkLocationRuntime;
+  private lifecycle?: ZLinkLocationLifecycle;
+  private events?: ZLinkLocationEventSink;
+  private leaseTrackerState?: {
+    readonly stores: ZLinkLocationRuntimeStores;
+    readonly tracker: ZLinkOwnerLeaseTracker;
+  };
+  private spotRouteInvalidator?: (spotId: RoutingId) => void;
+
+  constructor(private readonly options: ZLinkLocationRuntimeOwnerOptions) {}
+
+  get currentStores(): ZLinkLocationRuntimeStores | undefined {
+    return this.stores;
+  }
+
+  get currentRuntime(): ZLinkLocationRuntime | undefined {
+    return this.runtime;
+  }
+
+  get currentLifecycle(): ZLinkLocationLifecycle | undefined {
+    return this.lifecycle;
+  }
+
+  get currentEvents(): ZLinkLocationEventSink | undefined {
+    return this.events;
+  }
+
+  get currentLeaseTracker(): ZLinkOwnerLeaseTracker | undefined {
+    return this.leaseTrackerState?.tracker;
+  }
+
+  setSpotRouteInvalidator(invalidator?: (spotId: RoutingId) => void): void {
+    this.spotRouteInvalidator = invalidator;
+  }
+
+  actorTransferStore(): ZLinkActorTransferStore | undefined {
+    const store = this.stores?.locationStore ?? this.createAndRememberStores()?.locationStore;
+    return isActorTransferStore(store) ? store : undefined;
+  }
+
+  locationStore(): ZLinkDomainLocationStore | undefined {
+    return this.stores?.locationStore ?? this.createAndRememberStores()?.locationStore;
+  }
+
+  ensureRuntime(primaryMeshName: string | undefined): ZLinkLocationRuntime | undefined {
+    if (this.runtime !== undefined) {
+      return this.runtime;
+    }
+    const stores = this.stores ?? this.createRuntimeStores();
+    if (stores === undefined) {
+      return undefined;
+    }
+    this.stores = stores;
+    const runtime = new ZLinkLocationRuntime({
+      stores,
+      options: this.options.registration.locations.options,
+      events: this.ensureEvents(),
+      leaseTracker: this.leaseTracker(stores),
+      metrics: this.options.metrics,
+      meshNames: [...this.options.registration.spotNodes.keys()],
+      leaseScopes: [
+        ...[...this.options.registration.spotNodes.keys()]
+          .map(name => ({ kind: 'mesh' as const, name })),
+        ...[...this.options.registration.channels.keys()]
+          .map(name => ({ kind: 'channel' as const, name }))
+      ],
+      rewriteAuthorityPayloadForOwner: this.options.rewriteAuthorityPayloadForOwner
+    });
+    this.runtime = runtime;
+    this.lifecycle = new ZLinkLocationLifecycle(
+      runtime,
+      stores.actorStore,
+      primaryMeshName ?? '',
+      stores.authorityStore,
+      stores.spotStore,
+      spotId => this.spotRouteInvalidator?.(spotId)
+    );
+    return runtime;
+  }
+
+  createRefResolver(spotMeshNames: readonly string[]): ZLinkStoreLocationResolvers | undefined {
+    this.ensureRuntime(spotMeshNames.length === 1 ? spotMeshNames[0] : undefined);
+    const stores = this.stores;
+    if (stores === undefined) {
+      return undefined;
+    }
+    return new ZLinkStoreLocationResolvers({
+      stores: { ...stores, authorityStore: stores.locationStore },
+      leaseTracker: this.leaseTracker(stores),
+      events: this.events,
+      spotMeshNames,
+      routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+    });
+  }
+
+  createSpotRouteResolver(
+    spotMeshNames: readonly string[],
+    spotRouterChannelIdByMesh: (meshName: string) => string,
+    resolveLocalSpot?: (spotId: RoutingId) => import('../spots/spot-routing-internal').ZLinkSpotRouteTarget | undefined
+  ): ZLinkSpotRouteResolver | undefined {
+    const stores = this.stores;
+    if (stores === undefined || spotMeshNames.length === 0) {
+      return undefined;
+    }
+    return new ZLinkLocationSpotRouteResolver(
+      new ZLinkStoreLocationResolvers({
+        stores: { ...stores, authorityStore: stores.locationStore },
+        leaseTracker: this.leaseTracker(stores),
+        events: this.events,
+        routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+      }),
+      spotMeshNames,
+      spotRouterChannelIdByMesh,
+      resolveLocalSpot
+    );
+  }
+
+  createActorLocationResolver(spotMeshNames: readonly string[]): ZLinkStoreLocationResolvers | undefined {
+    const stores = this.stores;
+    if (stores === undefined) {
+      return undefined;
+    }
+    return new ZLinkStoreLocationResolvers({
+      stores: { ...stores, authorityStore: stores.locationStore },
+      leaseTracker: this.leaseTracker(stores),
+      events: this.events,
+      spotMeshNames,
+      routeCacheMaxAgeMs: this.options.registration.locations.options.routeCacheMaxAgeMs
+    });
+  }
+
+  ownerNodeRid(spotNodeRuntime?: ZLinkSpotNodeRuntimeManager): RoutingId {
+    const primaryMeshNode = spotNodeRuntime?.primaryMeshNode;
+    const spotNodeRid = primaryMeshNode === undefined
+      ? undefined
+      : String(primaryMeshNode.status().routingId);
+    if (spotNodeRid !== undefined) {
+      return spotNodeRid;
+    }
+    for (const channel of this.options.registration.channels.values()) {
+      const routingId = channel.routingId ?? channel.server?.routingId;
+      if (routingId !== undefined) {
+        return routingId;
+      }
+    }
+    for (const routeChannel of this.options.registration.routeChannelOptions.values()) {
+      if (routeChannel.routingId !== undefined) {
+        return routeChannel.routingId;
+      }
+    }
+    for (const spotNode of this.options.registration.spotNodes.values()) {
+      const routingId = spotNode.routingId ?? spotNode.router?.routingId ?? spotNode.pubSub?.routingId;
+      if (routingId !== undefined) {
+        return routingId;
+      }
+    }
+    return this.options.fallbackNodeRid;
+  }
+
+  async startForRuntime(
+    primaryMeshName: string | undefined,
+    spotNodeRuntime: ZLinkSpotNodeRuntimeManager,
+    channelRuntime: ZLinkChannelRuntimeManager
+  ): Promise<ZLinkLocationRuntime | undefined> {
+    const runtime = this.ensureRuntime(primaryMeshName);
+    if (runtime === undefined) {
+      return undefined;
+    }
+    await runtime.start(this.ownerNodeRid(spotNodeRuntime));
+    const stores = this.currentStores;
+    if (stores === undefined) {
+      return runtime;
+    }
+    spotNodeRuntime.configureLocationAutoConnect(
+      runtime,
+      stores,
+      this.options.registration.locations.options,
+      this.currentEvents
+    );
+    await spotNodeRuntime.startLocationAutoConnect();
+    channelRuntime.configureLocationAutoConnect(
+      runtime,
+      stores,
+      this.options.registration.locations.options,
+      this.currentEvents
+    );
+    await channelRuntime.startLocationAutoConnect();
+    return runtime;
+  }
+
+  clearForStop(): ZLinkLocationRuntimeStopSnapshot {
+    const snapshot = {
+      runtime: this.runtime,
+      lifecycle: this.lifecycle
+    };
+    this.stores = undefined;
+    this.runtime = undefined;
+    this.lifecycle = undefined;
+    this.events = undefined;
+    this.leaseTrackerState = undefined;
+    return snapshot;
+  }
+
+  private createRuntimeStores(): ZLinkLocationRuntimeStores | undefined {
+    const locations = this.options.registration.locations;
+    if (locations.useInMemoryStores) {
+      const provider = new ZLinkInMemoryProviderLocationStore();
+      const store = new ZLinkLocationStoreRepository(provider);
+      return {
+        locationStore: store,
+        authorityStore: store,
+        clientServerStore: store,
+        fanoutStore: store,
+        peerStore: store,
+        spotStore: store,
+        actorStore: store,
+        routeStore: store,
+        ownerLeaseStore: store
+      };
+    }
+    const provider = locations.storeInstance;
+    if (provider !== undefined) {
+      const store = new ZLinkLocationStoreRepository(provider);
+      return {
+        locationStore: store,
+        authorityStore: store,
+        clientServerStore: store,
+        fanoutStore: store,
+        peerStore: store,
+        spotStore: store,
+        actorStore: store,
+        routeStore: store,
+        ownerLeaseStore: store
+      };
+    }
+    return undefined;
+  }
+
+  private createAndRememberStores(): ZLinkLocationRuntimeStores | undefined {
+    if (this.stores !== undefined) return this.stores;
+    this.stores = this.createRuntimeStores();
+    return this.stores;
+  }
+
+  private leaseTracker(stores: ZLinkLocationRuntimeStores): ZLinkOwnerLeaseTracker {
+    if (this.leaseTrackerState?.stores === stores) {
+      return this.leaseTrackerState.tracker;
+    }
+    const tracker = new ZLinkOwnerLeaseTracker({
+      store: stores.ownerLeaseStore,
+      options: this.options.registration.locations.options
+    });
+    this.leaseTrackerState = { stores, tracker };
+    return tracker;
+  }
+
+  private ensureEvents(): ZLinkLocationEventSink | undefined {
+    return this.events;
+  }
+}
+
+function isActorTransferStore(value: unknown): value is ZLinkActorTransferStore {
+  const store = value as Partial<Record<
+    | 'prepareActorTransfer'
+    | 'commitActorTransfer'
+    | 'activateActorTransfer'
+    | 'abortActorTransfer'
+    | 'takeOverActorTransfer'
+    | 'resolveActorTransfer',
+    unknown
+  >>;
+  return typeof store.prepareActorTransfer === 'function'
+    && typeof store.commitActorTransfer === 'function'
+    && typeof store.activateActorTransfer === 'function'
+    && typeof store.abortActorTransfer === 'function'
+    && typeof store.takeOverActorTransfer === 'function'
+    && typeof store.resolveActorTransfer === 'function';
+}

package/src/runtime/host/mesh-router-resolver.ts

@@ -0,0 +1,114 @@
+import type { RoutingId } from '../../contracts';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import { normalizeRoutingId as normalizeRuntimeRoutingId, routingIdsEqual } from '../routing-id';
+
+export class MeshRouterResolver {
+  constructor(private readonly registration: ZLinkFrameworkRegistration) {}
+
+  canUseRouterChannel(routerChannelId: string): boolean {
+    return this.registration.routeChannels.has(routerChannelId)
+      || this.registration.spotNodes.get(routerChannelId)?.router !== undefined;
+  }
+
+  classifyManualNodeTarget(meshName: string, targetNodeRid: RoutingId): boolean | undefined {
+    const router = this.registration.spotNodes.get(meshName)?.router;
+    if (router === undefined) return undefined;
+    const manualConnections = router.manualConnections ?? [];
+    const manualPeers = router.manualPeerConnections ?? [];
+    if (manualConnections.length === 0 && manualPeers.length === 0) return undefined;
+    if (manualPeers.some((peer) => routingIdsEqual(peer.peerRid, targetNodeRid))) return true;
+    return manualConnections.length === 0 ? false : undefined;
+  }
+
+  defaultRouterChannelId(): string | undefined {
+    const candidates = [
+      ...this.registration.routeChannels,
+      ...[...this.registration.spotNodes.entries()]
+        .filter(([, spotNode]) => spotNode.router !== undefined)
+        .map(([spotNodeName]) => spotNodeName)
+    ];
+    return candidates.length === 1 ? candidates[0] : undefined;
+  }
+
+  defaultSpotRouterChannelId(): string | undefined {
+    const candidates = [...this.registration.spotNodes.entries()]
+      .filter(([, spotNode]) => spotNode.router !== undefined)
+      .map(([spotNodeName]) => spotNodeName);
+    return candidates.length === 1 ? candidates[0] : undefined;
+  }
+
+  remoteBoundSessionTargetForSource(sourceNodeRid: RoutingId): ZLinkRemoteBoundSessionTarget | undefined {
+    const routerChannelId = this.defaultSpotRouterChannelId()
+      ?? this.defaultRouterChannelId();
+    if (routerChannelId === undefined) {
+      return undefined;
+    }
+    const targetNodeRid = normalizeRuntimeRoutingId(sourceNodeRid);
+    return {
+      routerChannelId,
+      targetNodeRid,
+      spotId: targetNodeRid
+    };
+  }
+
+  primaryMeshName(): string | undefined {
+    const names = [...this.registration.spotNodes.entries()]
+      .filter(([, node]) =>
+        node.entrySpotType !== undefined
+        || (node.spotFactories?.length ?? 0) > 0
+        || (node.actorFactories instanceof Map
+          ? node.actorFactories.size > 0
+          : Object.keys(node.actorFactories ?? {}).length > 0))
+      .map(([name]) => name);
+    if (names.length === 1) return names[0];
+    if (names.length > 1) return undefined;
+    const allMeshNames = [...this.registration.spotNodes.keys()];
+    return allMeshNames.length === 1 ? allMeshNames[0] : undefined;
+  }
+
+  actorMeshName(actorType: string): string | undefined {
+    const matches = [...this.registration.spotNodes.entries()]
+      .filter(([, node]) => node.actorFactories instanceof Map
+        ? node.actorFactories.has(actorType)
+        : node.actorFactories !== undefined && Object.hasOwn(node.actorFactories, actorType))
+      .map(([name]) => name);
+    return matches.length === 1 ? matches[0] : undefined;
+  }
+
+  spotLocationMeshNames(): readonly string[] {
+    return [...new Set([
+      ...this.registration.spotNodes.keys(),
+      ...this.registration.routeChannels.keys()
+    ])];
+  }
+
+  spotRouterChannelIdByMesh(): (meshName: string) => string {
+    const routeChannels = [...this.registration.routeChannelOptions.values()];
+    const mapped = new Map<string, string>();
+    for (const [spotMeshName, spotNode] of this.registration.spotNodes.entries()) {
+      const conventionalRouteChannelId = `${spotMeshName}.route`;
+      if (
+        this.registration.routeChannels.has(conventionalRouteChannelId)
+        || this.registration.routeChannelOptions.has(conventionalRouteChannelId)
+      ) {
+        mapped.set(spotMeshName, conventionalRouteChannelId);
+        continue;
+      }
+      const spotNodeRid = spotNode.router?.routingId ?? spotNode.routingId;
+      if (spotNodeRid === undefined) {
+        continue;
+      }
+      const candidates = routeChannels
+        .filter((routeChannel) =>
+          routeChannel.routingId !== undefined &&
+          routingIdsEqual(routeChannel.routingId, spotNodeRid)
+        )
+        .map((routeChannel) => routeChannel.routerChannelId);
+      if (candidates.length === 1) {
+        mapped.set(spotMeshName, candidates[0]);
+      }
+    }
+    return (meshName) => mapped.get(meshName) ?? meshName;
+  }
+}

package/src/runtime/host/relocation-direct-transfer.ts

@@ -0,0 +1,273 @@
+import {
+  RELOCATION_PAYLOAD_CHUNK_COUNT_MAX,
+  RELOCATION_STATE_CHUNK_DATA_MAX_BYTES
+} from '../foundation/service-stateful-wire-codec';
+import { crc32c } from '../foundation/service-relocation-runtime';
+
+/**
+ * Conservative chunk size for paths without a negotiated target receive cap.
+ * Spec 28 §4.2: when no admission reply announced the target's effective
+ * receive chunk limit, the source uses the 32 KiB value that is safe on any
+ * deployment.
+ */
+export const RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES = 32 * 1024;
+
+/**
+ * Phase 1 conservative in-flight budget floor. Until Core exposes the
+ * per-pipe applied HWM observation API, the effective budget is
+ * min(configured, this constant) — spec 28 §5.3 (구현 노트: Phase 1 근사).
+ */
+export const RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Effective chunk size limit for one Actor Join's relocation state chunks:
+ * min(configured, target's advertised cap, conservative floor). 0 from the
+ * target means "not advertised" and does not participate in the min (spec
+ * 15 §4.2).
+ */
+export function effectiveActorJoinChunkLimitBytes(
+  configuredChunkLimitBytes: number,
+  advertisedReceiveChunkLimitBytes: number | undefined
+): number {
+  const candidates = [configuredChunkLimitBytes, RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES];
+  if (advertisedReceiveChunkLimitBytes !== undefined && advertisedReceiveChunkLimitBytes > 0) {
+    candidates.push(advertisedReceiveChunkLimitBytes);
+  }
+  return Math.min(...candidates);
+}
+
+export interface ZLinkRelocationChunkPlan {
+  readonly chunkBytes: number;
+  readonly chunkCount: number;
+  readonly totalLength: number;
+  readonly checksumCrc32c: number;
+}
+
+/**
+ * Splits one relocation payload into ordered chunks that satisfy the shared
+ * wire bounds (chunk data <= 64 MiB, chunk count <= 4096). The configured
+ * limit is honoured unless the count bound forces larger chunks.
+ */
+export function planRelocationChunks(
+  payload: Uint8Array,
+  configuredChunkLimitBytes: number
+): ZLinkRelocationChunkPlan {
+  if (!Number.isInteger(configuredChunkLimitBytes) || configuredChunkLimitBytes <= 0) {
+    throw new RangeError('relocationPayloadChunkLimitBytes must be a positive integer.');
+  }
+  const totalLength = payload.byteLength;
+  let chunkBytes = Math.min(
+    configuredChunkLimitBytes,
+    RELOCATION_CONSERVATIVE_CHUNK_LIMIT_BYTES
+  );
+  if (Math.ceil(totalLength / chunkBytes) > RELOCATION_PAYLOAD_CHUNK_COUNT_MAX) {
+    chunkBytes = Math.ceil(totalLength / RELOCATION_PAYLOAD_CHUNK_COUNT_MAX);
+  }
+  if (chunkBytes > RELOCATION_STATE_CHUNK_DATA_MAX_BYTES) {
+    throw new RangeError('Relocation payload exceeds the direct transfer size bound.');
+  }
+  const chunkCount = Math.max(1, Math.ceil(totalLength / chunkBytes));
+  return {
+    chunkBytes,
+    chunkCount,
+    totalLength,
+    checksumCrc32c: crc32c(payload)
+  };
+}
+
+export function relocationChunkAt(
+  payload: Uint8Array,
+  plan: ZLinkRelocationChunkPlan,
+  ordinal: number
+): Buffer {
+  if (!Number.isInteger(ordinal) || ordinal < 0 || ordinal >= plan.chunkCount) {
+    throw new RangeError('Relocation chunk ordinal is out of range.');
+  }
+  const source = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return source.subarray(
+    ordinal * plan.chunkBytes,
+    Math.min(source.byteLength, (ordinal + 1) * plan.chunkBytes)
+  );
+}
+
+export type ZLinkRelocationChunkAcceptance = 'accepted' | 'duplicate' | 'completed';
+
+/**
+ * Target-side assembly buffer for one exact relocation identity. Chunks are
+ * copied out of their transport lease immediately; once every chunk arrived
+ * the payload checksum is verified exactly once. A checksum mismatch is a
+ * non-retryable explicit failure (spec 28 §4.3) and partial payloads are
+ * never exposed.
+ */
+export class ZLinkRelocationPayloadAssembly {
+  private readonly buffer: Buffer;
+  private nextOrdinal = 0;
+  private receivedBytes = 0;
+  private outcome?: { readonly payload: Buffer } | { readonly error: Error };
+  private readonly waiters: Array<{
+    resolve: (payload: Buffer) => void;
+    reject: (error: Error) => void;
+  }> = [];
+
+  constructor(
+    readonly totalLength: number,
+    readonly chunkCount: number,
+    readonly checksumCrc32c: number
+  ) {
+    if (!Number.isSafeInteger(totalLength) || totalLength < 0) {
+      throw new RangeError('Relocation payload total length is invalid.');
+    }
+    if (!Number.isInteger(chunkCount) || chunkCount < 0
+      || chunkCount > RELOCATION_PAYLOAD_CHUNK_COUNT_MAX
+      || (totalLength > 0 && chunkCount === 0)) {
+      throw new RangeError('Relocation payload chunk count is invalid.');
+    }
+    this.buffer = Buffer.alloc(totalLength);
+    if (chunkCount === 0) this.finish();
+  }
+
+  get completed(): boolean {
+    return this.outcome !== undefined && 'payload' in this.outcome;
+  }
+
+  /** Copies one in-order chunk into the assembly buffer. */
+  accept(ordinal: number, data: Uint8Array): ZLinkRelocationChunkAcceptance {
+    if (this.outcome !== undefined) {
+      if ('error' in this.outcome) throw this.outcome.error;
+      return ordinal < this.chunkCount ? 'duplicate' : this.conflict(
+        `Relocation chunk ordinal ${ordinal} arrived after assembly completed.`
+      );
+    }
+    if (ordinal < this.nextOrdinal) return 'duplicate';
+    if (ordinal !== this.nextOrdinal || ordinal >= this.chunkCount) {
+      return this.conflict(
+        `Relocation chunk ordinal ${ordinal} does not continue the ordered assembly.`
+      );
+    }
+    if (this.receivedBytes + data.byteLength > this.totalLength) {
+      return this.conflict('Relocation chunks exceed the declared payload length.');
+    }
+    if (ordinal === this.chunkCount - 1
+      && this.receivedBytes + data.byteLength !== this.totalLength) {
+      return this.conflict('Relocation chunks do not cover the declared payload length.');
+    }
+    this.buffer.set(data, this.receivedBytes);
+    this.receivedBytes += data.byteLength;
+    this.nextOrdinal += 1;
+    if (this.nextOrdinal === this.chunkCount) {
+      this.finish();
+      return 'completed';
+    }
+    return 'accepted';
+  }
+
+  /** Resolves with the verified payload or rejects with the explicit failure. */
+  payload(): Promise<Buffer> {
+    if (this.outcome !== undefined) {
+      return 'payload' in this.outcome
+        ? Promise.resolve(this.outcome.payload)
+        : Promise.reject(this.outcome.error);
+    }
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+
+  /** Ends the assembly with an explicit failure (identity conflict, abort). */
+  fail(message: string): Error {
+    if (this.outcome !== undefined) {
+      return 'error' in this.outcome ? this.outcome.error : new Error(message);
+    }
+    const error = new Error(message);
+    this.outcome = { error };
+    for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+    return error;
+  }
+
+  private finish(): void {
+    if (crc32c(this.buffer) !== this.checksumCrc32c) {
+      // Spec 28 §9: an assembled-checksum mismatch on an ordered reliable
+      // connection signals an implementation defect or memory corruption.
+      // It is an explicit, non-retryable failure and the partial payload is
+      // never used for Restore.
+      throw this.fail('Relocation payload checksum mismatch after chunk assembly.');
+    }
+    this.outcome = { payload: this.buffer };
+    for (const waiter of this.waiters.splice(0)) waiter.resolve(this.buffer);
+  }
+
+  private conflict(message: string): never {
+    throw this.fail(message);
+  }
+}
+
+/**
+ * Byte budget for relocation payload bytes concurrently in flight on one
+ * scope (per-peer connection or whole node). A zero limit disables the
+ * budget. Acquisition larger than the whole budget is still admitted when
+ * nothing else is in flight, so no payload size is unable to start.
+ */
+export class ZLinkRelocationInFlightBudget {
+  private inFlight = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(readonly limitBytes: number) {
+    if (!Number.isSafeInteger(limitBytes) || limitBytes < 0) {
+      throw new RangeError('Relocation in-flight budget must be a non-negative integer.');
+    }
+  }
+
+  get inFlightBytes(): number {
+    return this.inFlight;
+  }
+
+  /** Waits for room, charges the bytes, and returns the exactly-once release. */
+  async acquire(bytes: number, signal?: AbortSignal): Promise<() => void> {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) {
+      throw new RangeError('Relocation budget charge must be a non-negative integer.');
+    }
+    while (this.limitBytes !== 0
+      && this.inFlight > 0
+      && this.inFlight + bytes > this.limitBytes) {
+      await this.waitForRelease(signal);
+    }
+    this.inFlight += bytes;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.inFlight -= bytes;
+      for (const waiter of this.waiters.splice(0)) waiter();
+    };
+  }
+
+  /** Pre-seal admission wait: resolves while the budget has any headroom. */
+  async waitForHeadroom(signal?: AbortSignal): Promise<void> {
+    while (this.limitBytes !== 0 && this.inFlight >= this.limitBytes) {
+      await this.waitForRelease(signal);
+    }
+  }
+
+  private waitForRelease(signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+      const waiter = () => {
+        signal?.removeEventListener('abort', aborted);
+        resolve();
+      };
+      const aborted = () => {
+        const index = this.waiters.indexOf(waiter);
+        if (index >= 0) this.waiters.splice(index, 1);
+        reject(signal?.reason as Error);
+      };
+      signal?.addEventListener('abort', aborted, { once: true });
+      this.waiters.push(waiter);
+    });
+  }
+}
+
+/** Effective Phase 1 budget: min(configured, conservative floor); 0 = off. */
+export function effectiveRelocationBudgetBytes(configuredBytes: number): number {
+  if (configuredBytes === 0) return 0;
+  return Math.min(configuredBytes, RELOCATION_PHASE1_CONSERVATIVE_BUDGET_BYTES);
+}