@zlink-systems/framework 0.26.0 → 0.27.0

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;
@@ -311,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;
@@ -320,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());
@@ -417,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);
 }
@@ -458,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);
@@ -467,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

@@ -252,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-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;
@@ -84,7 +85,9 @@ export class ServiceCapturedObjectRelocation {
 
 /** 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);
   }
 
@@ -254,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);
   }

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

@@ -1,15 +1,25 @@
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import { createHash } from 'node:crypto';
+import { AUTHORITY_ENVELOPE_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
+import { decodeAuthorityKey } from '../locations/authority-key-codec';
 import type {
-  ZLinkPlacementObjectKind,
-  ZLinkAuthorityKey
+  ZLinkAuthorityKey,
+  ZLinkPlacementObjectKind
 } from '../locations/internal-location-contracts';
-import { decodeAuthorityKey } from '../locations/authority-key-codec';
+import { enumWireRelocationPhase } from '../protocol/service_wire_codec.generated';
 import {
   decodeRelocationEnvelopeV1 as decodeGeneratedRelocationEnvelopeV1,
   encodeRelocationEnvelopeV1 as encodeGeneratedRelocationEnvelopeV1,
   type RelocationEnvelopeV1 as GeneratedRelocationEnvelopeV1,
   type RelocationObjectIdentity as GeneratedRelocationObjectIdentity
 } from '../protocol/service_wire_pilot_codec.generated';
+import { SHA256_DIGEST_BYTES } from './actor-join-recovery-codec';
+const MAX_RELOCATION_GENERATION = 0x7fff_ffff_ffff_ffffn;
+
+const RELOCATION_PREPARING_PHASE = enumWireRelocationPhase('preparing');
+const RELOCATION_ACTIVATING_PHASE = enumWireRelocationPhase('activating');
+const RELOCATION_COMPLETED_PHASE = enumWireRelocationPhase('completed');
+const RELOCATION_LAST_PHASE = enumWireRelocationPhase('aborted');
 
 export interface ServiceRelocationParticipant {
   /** Wire-local participant ordinal; identity is projected from Location Store. */
@@ -280,7 +290,7 @@ export function projectServiceRelocationAuthorityTargetReady(
     coordinatorNodeRid: target.nodeRid,
     coordinatorNodeGeneration: target.nodeGeneration,
     coordinatorExpectedStoreVersion: target.coordinatorExpectedStoreVersion,
-    phase: 5,
+    phase: RELOCATION_ACTIVATING_PHASE,
     sourceCleanupState: 0
   });
   return replaceCanonicalRelocationSlot(layout, slot);
@@ -323,7 +333,7 @@ function decodeCanonicalAuthorityPublication(
 function decodeCanonicalAuthorityLayout(payload: Uint8Array): CanonicalAuthorityLayout | undefined {
   try {
     const bytes = Buffer.from(payload);
-    if (bytes.byteLength < 20 || bytes.byteLength > 1024 * 1024) return undefined;
+    if (bytes.byteLength < 20 || bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) return undefined;
     const reader = new CanonicalReader(bytes);
     reader.expect(Buffer.from('ZLAU'));
     if (reader.u8() !== 1) return undefined;
@@ -395,21 +405,21 @@ export function decodeCanonicalRelocationSlot(
     if (
       !reader.done ||
       aggregateGeneration > 0x7fff_ffff_ffff_fffen ||
-      (aggregateGeneration === 0n && phase !== 1) ||
+      (aggregateGeneration === 0n && phase !== RELOCATION_PREPARING_PHASE) ||
       (rootAggregateGeneration !== undefined && aggregateGeneration !== rootAggregateGeneration) ||
-      targetAttemptGeneration > 0x7fff_ffff_ffff_ffffn ||
+      targetAttemptGeneration > MAX_RELOCATION_GENERATION ||
       sourceNodeGeneration === 0n ||
-      sourceNodeGeneration > 0x7fff_ffff_ffff_ffffn ||
+      sourceNodeGeneration > MAX_RELOCATION_GENERATION ||
       sourceOwnerLeaseGeneration === 0n ||
-      sourceOwnerLeaseGeneration > 0x7fff_ffff_ffff_ffffn ||
-      targetNodeGeneration > 0x7fff_ffff_ffff_ffffn ||
-      targetOwnerLeaseGeneration > 0x7fff_ffff_ffff_ffffn ||
+      sourceOwnerLeaseGeneration > MAX_RELOCATION_GENERATION ||
+      targetNodeGeneration > MAX_RELOCATION_GENERATION ||
+      targetOwnerLeaseGeneration > MAX_RELOCATION_GENERATION ||
       coordinatorLeaseGeneration === 0n ||
-      coordinatorLeaseGeneration > 0x7fff_ffff_ffff_ffffn ||
+      coordinatorLeaseGeneration > MAX_RELOCATION_GENERATION ||
       coordinatorNodeGeneration === 0n ||
-      coordinatorNodeGeneration > 0x7fff_ffff_ffff_ffffn ||
-      phase < 1 ||
-      phase > 9 ||
+      coordinatorNodeGeneration > MAX_RELOCATION_GENERATION ||
+      phase < RELOCATION_PREPARING_PHASE ||
+      phase > RELOCATION_LAST_PHASE ||
       applicationVersion < 0n ||
       sourceCleanupState > 2
     )
@@ -452,10 +462,10 @@ export function encodeCanonicalRelocationSlot(value: CanonicalRelocationSlot): B
   if (aggregateGeneration > 0x7fff_ffff_ffff_fffen) {
     throw new TypeError('Aggregate generation exceeds the issued range.');
   }
-  if (aggregateGeneration === 0n && value.phase !== 1) {
+  if (aggregateGeneration === 0n && value.phase !== RELOCATION_PREPARING_PHASE) {
     throw new TypeError('Zero aggregate generation is only valid while preparing.');
   }
-  if (targetAttemptGeneration > 0x7fff_ffff_ffff_ffffn) {
+  if (targetAttemptGeneration > MAX_RELOCATION_GENERATION) {
     throw new TypeError('Target attempt generation exceeds the ordinal range.');
   }
   const sourceNodeGeneration = canonicalNonZeroOrdinal(
@@ -482,7 +492,11 @@ export function encodeCanonicalRelocationSlot(value: CanonicalRelocationSlot): B
     value.coordinatorNodeGeneration,
     'coordinator node generation'
   );
-  if (!Number.isInteger(value.phase) || value.phase < 1 || value.phase > 9) {
+  if (
+    !Number.isInteger(value.phase) ||
+    value.phase < RELOCATION_PREPARING_PHASE ||
+    value.phase > RELOCATION_LAST_PHASE
+  ) {
     throw new TypeError('Canonical relocation phase is invalid.');
   }
   if (
@@ -553,7 +567,7 @@ function encodeCanonicalRelocationPublicationSlot(
     coordinatorNodeRid: publication.coordinatorNodeRid ?? nodeRid,
     coordinatorNodeGeneration: publication.coordinatorNodeGeneration ?? layout.nodeGeneration,
     coordinatorExpectedStoreVersion: publication.coordinatorExpectedStoreVersion ?? '',
-    phase: publication.canonicalPhase ?? 8,
+    phase: publication.canonicalPhase ?? RELOCATION_COMPLETED_PHASE,
     applicationVersion,
     sourceCleanupState: publication.canonicalSourceCleanupState ?? 0
   });
@@ -579,8 +593,10 @@ function replaceCanonicalRelocationSlot(
     body
   ]);
   const result = Buffer.concat([envelope, canonicalU32(crc32c(envelope))]);
-  if (result.byteLength > 1024 * 1024) {
-    throw new TypeError('Canonical authority payload exceeds 1 MiB.');
+  if (result.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new TypeError(
+      `Canonical authority payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return result;
 }
@@ -1022,8 +1038,8 @@ function encodeAuthorityEnvelope(
     'target owner lease generation'
   );
   if (
-    aggregateGeneration > 0x7fff_ffff_ffff_ffffn ||
-    targetOwnerLeaseGeneration > 0x7fff_ffff_ffff_ffffn
+    aggregateGeneration > MAX_RELOCATION_GENERATION ||
+    targetOwnerLeaseGeneration > MAX_RELOCATION_GENERATION
   ) {
     throw new TypeError('Relocation publication generations must fit signed 64-bit storage.');
   }
@@ -1040,8 +1056,10 @@ function encodeAuthorityEnvelope(
     i64le(targetOwnerLeaseGeneration),
     bytes32le(base)
   ]);
-  if (payload.byteLength > 1024 * 1024) {
-    throw new TypeError('Location authority relocation payload exceeds 1 MiB.');
+  if (payload.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new TypeError(
+      `Location authority relocation payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return payload;
 }
@@ -1067,8 +1085,8 @@ function decodeAuthorityEnvelope(
     if (
       !reader.done ||
       aggregateGeneration === 0n ||
-      aggregateGeneration > 0x7fff_ffff_ffff_ffffn ||
-      inventoryDigestBytes.byteLength !== 32 ||
+      aggregateGeneration > MAX_RELOCATION_GENERATION ||
+      inventoryDigestBytes.byteLength !== SHA256_DIGEST_BYTES ||
       targetOwnerLeaseGeneration <= 0n
     ) {
       return undefined;
@@ -1181,8 +1199,10 @@ function text16le(value: string): Buffer {
 
 function bytes32le(value: Uint8Array): Buffer {
   const bytes = Buffer.from(value);
-  if (bytes.byteLength > 1024 * 1024) {
-    throw new TypeError('Relocation byte field exceeds 1 MiB.');
+  if (bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new TypeError(
+      `Relocation byte field exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   const length = Buffer.alloc(4);
   length.writeInt32LE(bytes.byteLength);
@@ -1350,7 +1370,7 @@ function canonicalU32(value: number): Buffer {
 }
 
 function canonicalU64(value: bigint): Buffer {
-  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value < 0n || value > UINT64_MAX) {
     throw new TypeError('Canonical authority u64 is invalid.');
   }
   const result = Buffer.alloc(8);
@@ -1360,7 +1380,7 @@ function canonicalU64(value: bigint): Buffer {
 
 function canonicalOrdinal(value: bigint, name: string): bigint {
   const ordinal = nonNegativeBigInt(value, name);
-  if (ordinal > 0x7fff_ffff_ffff_ffffn) {
+  if (ordinal > MAX_RELOCATION_GENERATION) {
     throw new TypeError(`${name} exceeds the ordinal range.`);
   }
   return ordinal;
@@ -1373,7 +1393,7 @@ function canonicalNonZeroOrdinal(value: bigint, name: string): bigint {
 }
 
 function canonicalI64(value: bigint): Buffer {
-  if (value < 0n || value > 0x7fff_ffff_ffff_ffffn) {
+  if (value < 0n || value > MAX_RELOCATION_GENERATION) {
     throw new TypeError('Canonical authority i64 is invalid.');
   }
   const result = Buffer.alloc(8);
@@ -1387,8 +1407,10 @@ class DotnetBinaryReader {
 
   constructor(payload: Uint8Array) {
     this.bytes = Buffer.from(payload);
-    if (this.bytes.byteLength > 1024 * 1024) {
-      throw new TypeError('Location authority relocation payload exceeds 1 MiB.');
+    if (this.bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+      throw new TypeError(
+        `Location authority relocation payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+      );
     }
   }
 
@@ -1426,7 +1448,7 @@ class DotnetBinaryReader {
 
   bytes32(): Buffer {
     const length = this.take(4).readInt32LE(0);
-    if (length < 0 || length > 1024 * 1024) {
+    if (length < 0 || length > AUTHORITY_ENVELOPE_MAX_BYTES) {
       throw new TypeError('Location authority relocation byte field is invalid.');
     }
     return Buffer.from(this.take(length));