@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/host/user-spot-creation-coordinator.ts

@@ -1,10 +1,29 @@
+import { createHash } from 'node:crypto';
+import {
+  type RoutingId,
+  type SpotRef,
+  type ZLinkSpotCreateResult,
+  ZLinkFrameworkException,
+  ZLinkSpotCreateState
+} from '../../contracts';
+
+import {
+  decodeServiceClosingSpotAuthority,
+  decodeServiceReadySpotAuthority,
+  encodeServiceUserSpotAuthorityPayload
+} from '../foundation/service-authority-payload-codec';
+import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+import type {
+  ServiceDirectSpotRouteFence,
+  ServiceUserSpotCloseRecord,
+  ServiceUserSpotCreateRecord
+} from '../foundation/service-stateful-wire-codec';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
   wireReplyFailureException
 } from '../framework-errors-internal';
-import { createHash } from 'node:crypto';
-import type { RoutingId, SpotRef, ZLinkSpotCreateResult } from '../../contracts';
+import { encodeAuthorityKey } from '../locations/authority-key-codec';
 import type {
   ZLinkAuthoritySnapshot,
   ZLinkLocationOwnerToken,
@@ -14,19 +33,9 @@ import type {
   ZLinkAuthorityStore,
   ZLinkObjectCreationStore
 } from '../locations/internal-store-contracts';
-import { ZLinkFrameworkException, ZLinkSpotCreateState } from '../../contracts';
-import {
-  decodeServiceReadySpotAuthority,
-  encodeServiceUserSpotAuthorityPayload
-} from '../foundation/service-authority-payload-codec';
-import { encodeAuthorityKey } from '../locations/authority-key-codec';
 import type { ZLinkLocalSpotCreateResult } from '../spots/spot-manager-internal-contracts';
-import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
-import type {
-  ServiceUserSpotCloseRecord,
-  ServiceUserSpotCreateRecord,
-  ServiceDirectSpotRouteFence
-} from '../foundation/service-stateful-wire-codec';
+const DEFAULT_USER_SPOT_CLEANUP_TIMEOUT_MS = 1_000;
+const DEFAULT_USER_SPOT_POLL_INTERVAL_MS = 10;
 
 export interface ZLinkUserSpotCreationCoordinatorOptions {
   readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
@@ -108,9 +117,10 @@ export class ZLinkUserSpotCreationCoordinator {
     ) => Promise<ZLinkLocalSpotCreateResult>,
     discard?: (signal?: AbortSignal) => Promise<void>
   ): Promise<ZLinkUserSpotCreationResult> {
-    const deadline = createDeadline(request.timeoutMs, request.signal);
-    const deadlineMs = performance.now() + request.timeoutMs;
     const deadlineUnixMs = Date.now() + request.timeoutMs;
+    const remainingMs = Math.max(0, deadlineUnixMs - Date.now());
+    const deadline = createDeadline(remainingMs, request.signal);
+    const deadlineMs = performance.now() + remainingMs;
     const signal = deadline.signal;
     signal.throwIfAborted();
     const sha256 = createHash('sha256').update(request.requestPayload).digest();
@@ -186,7 +196,8 @@ export class ZLinkUserSpotCreationCoordinator {
               }
             }
           },
-          signal
+          signal,
+          BigInt(deadlineUnixMs)
         );
       } catch (error) {
         deadline.close();
@@ -332,55 +343,34 @@ export class ZLinkUserSpotCreationCoordinator {
 
   async close(
     spot: SpotRef,
-    closeOwner: (current: SpotRef, snapshot: ZLinkAuthoritySnapshot) => Promise<boolean>,
-    signal?: AbortSignal,
-    ownerPresent?: (current: SpotRef) => boolean,
-    ownerCanClose?: (current: SpotRef) => boolean
+    closeOwner: (
+      current: SpotRef,
+      beginAuthority: (onCommitted: () => void) => Promise<{ release(): Promise<void> }>
+    ) => Promise<boolean>,
+    signal?: AbortSignal
   ): Promise<boolean> {
     const resolved = await this.resolveCloseTarget(spot, signal);
     if (resolved === undefined) return false;
     const { spot: currentRef, snapshot: current } = resolved;
     const key = encodeAuthorityKey('user_spot', String(spot.spotId));
-    if (ownerPresent?.(currentRef) === false) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
-        `User Spot '${String(spot.spotId)}' is missing from its authority owner.`,
-        true
-      );
-    }
-    if (ownerCanClose?.(currentRef) === false) return false;
-    const closing = await this.beginClosing(key, current, String(spot.spotId), signal);
-    let closed: boolean;
-    try {
-      closed = await closeOwner(currentRef, closing);
-    } catch (error) {
-      await this.restoreReady(key, closing, String(spot.spotId), signal);
-      throw error;
-    }
-    if (!closed) {
-      await this.restoreReady(key, closing, String(spot.spotId), signal);
-      return false;
-    }
-    const deleted = await this.options.store.compareExchangeAuthority(
-      key,
-      closing.storeVersion,
-      { kind: 'delete' },
-      signal
+    return await closeOwner(currentRef, async (onCommitted) =>
+      this.commitCloseAuthority(key, current, String(spot.spotId), onCommitted)
     );
-    if (deleted.kind === 'deleted') {
-      this.forgetReadyRoute(currentRef.spotId, current);
-      return true;
-    }
-    if (deleted.kind === 'conflict') {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
-        `User Spot '${String(spot.spotId)}' authority changed while closing.`,
-        true
-      );
-    }
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
-      `User Spot '${String(spot.spotId)}' generation cannot be closed.`
+  }
+
+  /** Commits Closing for the owner's own incarnation when its context requests Close. */
+  async beginOwnerClose(
+    spot: SpotRef,
+    onCommitted: () => void
+  ): Promise<{ release(): Promise<void> } | undefined> {
+    const resolved = await this.resolveCloseTarget(spot);
+    if (resolved === undefined) return undefined;
+    const spotId = String(spot.spotId);
+    return await this.commitCloseAuthority(
+      encodeAuthorityKey('user_spot', spotId),
+      resolved.snapshot,
+      spotId,
+      onCommitted
     );
   }
 
@@ -391,29 +381,14 @@ export class ZLinkUserSpotCreationCoordinator {
     const key = encodeAuthorityKey('user_spot', String(spot.spotId));
     const current = await this.options.store.readAuthority(key, signal);
     if (current.kind === 'missing') return undefined;
-    if (current.objectGeneration !== spot.objectGeneration) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
-        `User Spot '${String(spot.spotId)}' generation is stale.`
-      );
-    }
-    const currentRef = spotRef(current, {
-      meshName: current.allocation.descriptor.meshName,
-      spotId: spot.spotId,
-      stableType: current.allocation.stableType,
-      requestPayload: Buffer.alloc(0),
-      timeoutMs: 1
-    });
-    if (
-      String(current.allocation.descriptor.rid) !== String(spot.nodeRid) ||
-      current.allocation.descriptor.meshName !== spot.meshName
-    ) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
-        `User Spot '${String(spot.spotId)}' owner route is stale.`
-      );
-    }
-    return { spot: currentRef, snapshot: current };
+    return {
+      spot: requireCloseTarget(current, String(spot.spotId), {
+        objectGeneration: spot.objectGeneration,
+        nodeRid: String(spot.nodeRid),
+        meshName: spot.meshName
+      }),
+      snapshot: current
+    };
   }
 
   async handleRemoteCreate(
@@ -565,7 +540,8 @@ export class ZLinkUserSpotCreationCoordinator {
               }
             }
           },
-          signal
+          signal,
+          record.deadlineUnixMs
         );
         await discard?.(signal);
         return {
@@ -600,7 +576,8 @@ export class ZLinkUserSpotCreationCoordinator {
               ownerNodeGeneration: current.allocation.descriptorLifecycleGeneration
             })
           },
-          signal
+          signal,
+          record.deadlineUnixMs
         );
       } catch (error) {
         throw createInternalFrameworkException(
@@ -631,7 +608,9 @@ export class ZLinkUserSpotCreationCoordinator {
       };
     } catch (error) {
       local?.publication?.abort();
-      const cleanupDeadline = createDeadline(this.options.cleanupTimeoutMs ?? 1_000);
+      const cleanupDeadline = createDeadline(
+        this.options.cleanupTimeoutMs ?? DEFAULT_USER_SPOT_CLEANUP_TIMEOUT_MS
+      );
       const cleanupSignal = cleanupDeadline.signal;
       const cleanup = await Promise.allSettled([
         waitForAbort(
@@ -672,65 +651,71 @@ export class ZLinkUserSpotCreationCoordinator {
 
   async handleRemoteClose(
     record: ServiceUserSpotCloseRecord,
-    closeOwner: (spot: SpotRef, signal?: AbortSignal) => Promise<boolean>,
-    signal?: AbortSignal
+    closeOwner: (
+      spot: SpotRef,
+      beginAuthority: (onCommitted: () => void) => Promise<{ release(): Promise<void> }>,
+      signal?: AbortSignal
+    ) => Promise<boolean>,
+    signal?: AbortSignal,
+    canResume?: (spot: SpotRef) => boolean
   ): Promise<boolean> {
     const key = encodeAuthorityKey('user_spot', record.target.spotId);
     const current = await this.options.store.readAuthority(key, signal);
     if (current.kind === 'missing') return false;
-    if (current.objectGeneration !== record.target.objectGeneration) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
-        `User Spot '${record.target.spotId}' generation is stale.`
-      );
-    }
-    if (
-      current.authorityOwnerGeneration !== record.target.authorityOwnerGeneration ||
-      current.storeVersion.value !== record.target.expectedStoreVersion ||
-      String(current.allocation.descriptor.rid) !== record.target.targetNodeRid ||
-      current.allocation.descriptorLifecycleGeneration !== record.target.targetNodeGeneration ||
-      current.allocation.objectKind !== 'user_spot' ||
-      current.allocation.state !== 'active'
-    ) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
-        `User Spot '${record.target.spotId}' close authority is moving.`,
-        true
-      );
-    }
-    const spot: SpotRef = {
+    const candidate: SpotRef = {
       spotId: record.target.spotId as RoutingId,
       objectGeneration: current.objectGeneration,
       meshName: current.allocation.descriptor.meshName,
       nodeRid: current.allocation.descriptor.rid
     };
-    const closing = await this.beginClosing(key, current, record.target.spotId, signal);
-    let closed: boolean;
-    try {
-      closed = await closeOwner(spot, signal);
-    } catch (error) {
-      await this.restoreReady(key, closing, record.target.spotId, signal);
-      throw error;
-    }
-    if (!closed) {
-      await this.restoreReady(key, closing, record.target.spotId, signal);
-      return false;
-    }
-    const deleted = await this.options.store.compareExchangeAuthority(
-      key,
-      closing.storeVersion,
-      { kind: 'delete' },
+    // A Closing committed by this owner is resumed, so its store version has
+    // advanced past the one the source observed.
+    const resuming =
+      canResume?.(candidate) === true &&
+      decodeServiceClosingSpotAuthority(current.payload)?.kind === 'user_spot';
+    const spot = requireCloseTarget(current, record.target.spotId, {
+      objectGeneration: record.target.objectGeneration,
+      nodeRid: record.target.targetNodeRid,
+      nodeGeneration: record.target.targetNodeGeneration,
+      authorityOwnerGeneration: record.target.authorityOwnerGeneration,
+      storeVersion: resuming ? undefined : record.target.expectedStoreVersion
+    });
+    return await closeOwner(
+      spot,
+      async (onCommitted) =>
+        this.commitCloseAuthority(key, current, record.target.spotId, onCommitted),
       signal
     );
-    if (deleted.kind === 'deleted') {
-      this.forgetReadyRoute(record.target.spotId as RoutingId, current);
-      return true;
-    }
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.SpotMoving,
-      `User Spot '${record.target.spotId}' authority changed while closing.`,
-      true
-    );
+  }
+
+  private async commitCloseAuthority(
+    key: ReturnType<typeof encodeAuthorityKey>,
+    current: ZLinkAuthoritySnapshot,
+    spotId: string,
+    onCommitted: () => void
+  ): Promise<{ release(): Promise<void> }> {
+    const closing = await this.beginClosing(key, current, spotId);
+    const authority = {
+      release: async () => {
+        this.forgetReadyRoute(spotId as RoutingId, current);
+        const deleted = await this.options.store.compareExchangeAuthority(
+          key,
+          closing.storeVersion,
+          {
+            kind: 'delete'
+          }
+        );
+        if (deleted.kind !== 'deleted') {
+          throw createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.SpotMoving,
+            `User Spot '${spotId}' authority changed while closing.`,
+            true
+          );
+        }
+      }
+    };
+    onCommitted();
+    return authority;
   }
 
   forgetReadyRoute(spotId: RoutingId, snapshot: ZLinkAuthoritySnapshot): void {
@@ -743,8 +728,7 @@ export class ZLinkUserSpotCreationCoordinator {
   private async beginClosing(
     key: ReturnType<typeof encodeAuthorityKey>,
     current: ZLinkAuthoritySnapshot,
-    spotId: string,
-    signal?: AbortSignal
+    spotId: string
   ): Promise<ZLinkAuthoritySnapshot> {
     const ready = decodeServiceReadySpotAuthority(current.payload);
     if (
@@ -766,7 +750,7 @@ export class ZLinkUserSpotCreationCoordinator {
         payload: userSpotAuthorityPayload(current, spotId, 'closing'),
         generationTransition: 'preserve'
       },
-      signal
+      undefined
     );
     if (closing.kind === 'stored') {
       const { kind: _kind, ...snapshot } = closing;
@@ -779,31 +763,6 @@ export class ZLinkUserSpotCreationCoordinator {
     );
   }
 
-  private async restoreReady(
-    key: ReturnType<typeof encodeAuthorityKey>,
-    closing: ZLinkAuthoritySnapshot,
-    spotId: string,
-    signal?: AbortSignal
-  ): Promise<void> {
-    const restored = await this.options.store.compareExchangeAuthority(
-      key,
-      closing.storeVersion,
-      {
-        kind: 'put',
-        payload: userSpotAuthorityPayload(closing, spotId, 'ready'),
-        generationTransition: 'preserve'
-      },
-      signal
-    );
-    if (restored.kind !== 'stored') {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
-        'User Spot Ready authority could not be restored after close was declined.',
-        true
-      );
-    }
-  }
-
   private async awaitReady(
     request: ZLinkUserSpotCreationRequest,
     signal: AbortSignal
@@ -815,7 +774,7 @@ export class ZLinkUserSpotCreationCoordinator {
       if (current.kind === 'snapshot' && current.allocation.state === 'active') {
         return spotRef(current, request);
       }
-      await wait(this.options.pollIntervalMs ?? 10, signal);
+      await wait(this.options.pollIntervalMs ?? DEFAULT_USER_SPOT_POLL_INTERVAL_MS, signal);
     }
   }
 
@@ -926,6 +885,66 @@ function readySpotRoute(
   };
 }
 
+/** The Close fence a caller observed; omitted parts are not part of that caller's fence. */
+interface ZLinkUserSpotCloseFence {
+  readonly objectGeneration: bigint;
+  readonly nodeRid: string;
+  readonly meshName?: string;
+  readonly nodeGeneration?: bigint;
+  readonly authorityOwnerGeneration?: bigint;
+  readonly storeVersion?: string;
+}
+
+/**
+ * The single classifier of a Close target (§7, §9): another ObjectGeneration is
+ * SpotGenerationStale; any owner fence difference or an authority that is not
+ * in a Framework-owned Ready or Closing state is SpotMoving.
+ */
+function requireCloseTarget(
+  current: ZLinkAuthoritySnapshot,
+  spotId: string,
+  fence: ZLinkUserSpotCloseFence
+): SpotRef {
+  if (current.objectGeneration !== fence.objectGeneration) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
+      `User Spot '${spotId}' generation is stale.`
+    );
+  }
+  // A committed Closing stays the close target: its owner resumes that Close.
+  const decoded =
+    decodeServiceReadySpotAuthority(current.payload) ??
+    decodeServiceClosingSpotAuthority(current.payload);
+  const allocation = current.allocation;
+  if (
+    decoded?.kind !== 'user_spot' ||
+    decoded.spotId !== spotId ||
+    decoded.ownerId !== current.ownerId ||
+    decoded.ownerLeaseGeneration !== current.ownerLeaseGeneration ||
+    allocation.objectKind !== 'user_spot' ||
+    allocation.state !== 'active' ||
+    String(allocation.descriptor.rid) !== fence.nodeRid ||
+    (fence.meshName !== undefined && allocation.descriptor.meshName !== fence.meshName) ||
+    (fence.nodeGeneration !== undefined &&
+      allocation.descriptorLifecycleGeneration !== fence.nodeGeneration) ||
+    (fence.authorityOwnerGeneration !== undefined &&
+      current.authorityOwnerGeneration !== fence.authorityOwnerGeneration) ||
+    (fence.storeVersion !== undefined && current.storeVersion.value !== fence.storeVersion)
+  ) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.SpotMoving,
+      `User Spot '${spotId}' owner fence changed or the Spot is moving.`,
+      true
+    );
+  }
+  return {
+    spotId: spotId as RoutingId,
+    objectGeneration: current.objectGeneration,
+    meshName: allocation.descriptor.meshName,
+    nodeRid: allocation.descriptor.rid
+  };
+}
+
 function spotRef(
   snapshot: ZLinkAuthoritySnapshot,
   request: ZLinkUserSpotCreationRequest,

package/src/runtime/locations/aggregate-inventory-store.ts

@@ -1,12 +1,15 @@
 import { createHash, timingSafeEqual } from 'node:crypto';
 import type { ZLinkLocationStore, ZLinkStoreKey, ZLinkStoreReadResult } from '../../contracts';
+import { SHA256_DIGEST_BYTES } from '../foundation/actor-join-recovery-codec';
+import { PROVIDER_STORAGE_NAMESPACE_PREFIX, storeKey } from './in-memory-provider-location-store';
 import type {
   ZLinkAggregateFence,
   ZLinkAggregatePrepareRequest
 } from './internal-location-contracts';
-import { storeKey } from './in-memory-provider-location-store';
 
-const PREFIX = 'zlink:v11:aggregate-inventory:';
+const INVENTORY_PAGE_KIND = 'aggregate-inventory-page-v1';
+const INVENTORY_ROOT_KIND = 'aggregate-inventory-root-v1';
+const PREFIX = `${PROVIDER_STORAGE_NAMESPACE_PREFIX}aggregate-inventory:`;
 const MAX_PAGE_ENTRIES = 1_024;
 const MAX_PAGE_BYTES = 1_024 * 1_024;
 const MAX_TREE_LEVELS = 32;
@@ -30,7 +33,7 @@ interface InventoryReference {
 }
 
 interface InventoryPage {
-  readonly kind: 'aggregate-inventory-page-v1';
+  readonly kind: typeof INVENTORY_PAGE_KIND;
   readonly level: number;
   readonly index: number;
   readonly startIndex: number;
@@ -40,7 +43,7 @@ interface InventoryPage {
 }
 
 interface InventoryRoot {
-  readonly kind: 'aggregate-inventory-root-v1';
+  readonly kind: typeof INVENTORY_ROOT_KIND;
   readonly totalCount: number;
   readonly digest: string;
   readonly declaredDigest: string;
@@ -209,8 +212,8 @@ function buildTree(request: ZLinkAggregatePrepareRequest): InventoryTree {
   if (request.participants.length < 1) {
     throw new RangeError('Aggregate inventory requires at least one participant.');
   }
-  if (request.inventoryDigest.byteLength !== 32) {
-    throw new TypeError('Aggregate inventory digest must contain 32 bytes.');
+  if (request.inventoryDigest.byteLength !== SHA256_DIGEST_BYTES) {
+    throw new TypeError(`Aggregate inventory digest must contain ${SHA256_DIGEST_BYTES} bytes.`);
   }
   const entries = request.participants.map((participant, index): InventoryEntry => ({
     index,
@@ -240,7 +243,7 @@ function buildTree(request: ZLinkAggregatePrepareRequest): InventoryTree {
   ) {
     level++;
     if (level >= MAX_TREE_LEVELS) {
-      throw new RangeError('Aggregate inventory tree exceeds 32 levels.');
+      throw new RangeError(`Aggregate inventory tree exceeds ${MAX_TREE_LEVELS} levels.`);
     }
     references = packIndexPages(level, references, pages);
   }
@@ -269,7 +272,7 @@ function packLeafPages(
     let bytes: Uint8Array;
     do {
       page = {
-        kind: 'aggregate-inventory-page-v1',
+        kind: INVENTORY_PAGE_KIND,
         level: 0,
         index: references.length,
         startIndex: offset,
@@ -304,7 +307,7 @@ function packIndexPages(
     do {
       const selected = children.slice(offset, offset + count);
       page = {
-        kind: 'aggregate-inventory-page-v1',
+        kind: INVENTORY_PAGE_KIND,
         level,
         index: references.length,
         startIndex: selected[0]!.startIndex,
@@ -339,7 +342,7 @@ function rootCandidate(
     if (page.level <= topLevel) pageCountsByLevel[page.level]!++;
   }
   return {
-    kind: 'aggregate-inventory-root-v1',
+    kind: INVENTORY_ROOT_KIND,
     totalCount,
     digest,
     declaredDigest,
@@ -456,7 +459,7 @@ function decodeRoot(bytes: Uint8Array): InventoryRoot {
     value === null ||
     typeof value !== 'object' ||
     !('kind' in value) ||
-    value.kind !== 'aggregate-inventory-root-v1'
+    value.kind !== INVENTORY_ROOT_KIND
   ) {
     throw new Error('Invalid inventory root.');
   }
@@ -469,7 +472,7 @@ function decodePage(bytes: Uint8Array): InventoryPage {
     value === null ||
     typeof value !== 'object' ||
     !('kind' in value) ||
-    value.kind !== 'aggregate-inventory-page-v1' ||
+    value.kind !== INVENTORY_PAGE_KIND ||
     !('entries' in value) ||
     !Array.isArray(value.entries) ||
     !('children' in value) ||
@@ -524,7 +527,7 @@ function isSha256(value: unknown): value is string {
 function sameHash(expected: string, actual: Uint8Array): boolean {
   return (
     isSha256(expected) &&
-    actual.byteLength === 32 &&
+    actual.byteLength === SHA256_DIGEST_BYTES &&
     timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(actual))
   );
 }

package/src/runtime/locations/authority-key-codec.ts

@@ -1,3 +1,4 @@
+import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
 import type {
   ZLinkAuthorityKey,
   ZLinkPlacementObjectKind
@@ -8,8 +9,10 @@ export function encodeAuthorityKey(
   globalId: string
 ): ZLinkAuthorityKey {
   const bytes = Buffer.from(globalId);
-  if (bytes.byteLength < 1 || bytes.byteLength > 255) {
-    throw new RangeError('Authority identity must contain 1..255 UTF-8 bytes.');
+  if (bytes.byteLength < 1 || bytes.byteLength > ZLINK_MAX_IDENTITY_TEXT_BYTES) {
+    throw new RangeError(
+      `Authority identity must contain 1..${ZLINK_MAX_IDENTITY_TEXT_BYTES} UTF-8 bytes.`
+    );
   }
   const discriminator = kind === 'actor' ? 'a' : 's';
   return {
@@ -27,7 +30,8 @@ export function decodeAuthorityKey(key: ZLinkAuthorityKey): {
   const match = /^zla1:([as]):([1-9][0-9]{0,2}):(.*)$/.exec(key.value);
   if (match === null) throw new TypeError('Authority key is not canonical.');
   const declaredLength = Number(match[2]);
-  if (declaredLength > 255) throw new TypeError('Authority key identity exceeds the byte limit.');
+  if (declaredLength > ZLINK_MAX_IDENTITY_TEXT_BYTES)
+    throw new TypeError('Authority key identity exceeds the byte limit.');
   const encoded = match[3]!;
   const bytes: number[] = [];
   for (let index = 0; index < encoded.length;) {