@zlink-systems/framework 0.30.1 → 0.30.2

package/src/runtime/locations/relocation-blob.ts

@@ -1,3 +1,9 @@
+import {
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind
+} from '../../contracts/Errors/ZLinkFrameworkException';
+import { isIndeterminateLocationStoreFailure } from './location-store-failure';
+import type { ZLinkRuntimeMetrics } from '../diagnostics/runtime-metrics';
 import { randomUUID } from 'node:crypto';
 import { awaitWithAbort, macrotaskBoundary } from '../abort';
 import type {
@@ -19,6 +25,22 @@ export async function putNewRelocationBlob(
   readonly reference: ZLinkBlobReference;
   readonly expiresAt: Date;
   readonly storeNow: Date;
+}> {
+  if (store instanceof ZLinkProviderRelocationRepository) {
+    return store.putNew(payload, retentionMs, signal);
+  }
+  return putNewRelocationBlobCore(store, payload, retentionMs, signal);
+}
+
+async function putNewRelocationBlobCore(
+  store: ZLinkRelocationStore,
+  payload: Uint8Array,
+  retentionMs: number,
+  signal?: AbortSignal
+): Promise<{
+  readonly reference: ZLinkBlobReference;
+  readonly expiresAt: Date;
+  readonly storeNow: Date;
 }> {
   let reference = relocationBlobReference(randomUUID());
   for (; ; await macrotaskBoundary()) {
@@ -26,7 +48,8 @@ export async function putNewRelocationBlob(
     let result: ZLinkBlobPutResult;
     try {
       result = await awaitWithAbort(store.put(reference, payload, retentionMs, signal), signal);
-    } catch {
+    } catch (error) {
+      if (!isRelocationProviderFailure(error)) throw error;
       signal?.throwIfAborted();
       const read = await awaitWithAbort(store.read(reference, signal), signal);
       if (read.kind === 'found' && Buffer.compare(read.bytes, payload) === 0) {
@@ -45,3 +68,54 @@ export async function putNewRelocationBlob(
     reference = relocationBlobReference(randomUUID());
   }
 }
+
+/** Observes provider requests before callers interpret or decode blob contents. */
+export class ZLinkProviderRelocationRepository implements ZLinkRelocationStore {
+  constructor(
+    private readonly provider: ZLinkRelocationStore,
+    private readonly metrics: ZLinkRuntimeMetrics
+  ) {}
+
+  putNew(payload: Uint8Array, retentionMs: number, signal?: AbortSignal) {
+    return this.observe(
+      'relocation_put',
+      () => putNewRelocationBlobCore(this.provider, payload, retentionMs, signal),
+      signal
+    );
+  }
+  put(...args: Parameters<ZLinkRelocationStore['put']>) {
+    return this.observe('relocation_put', () => this.provider.put(...args), args[3]);
+  }
+  read(...args: Parameters<ZLinkRelocationStore['read']>) {
+    return this.observe('relocation_get', () => this.provider.read(...args), args[1]);
+  }
+  renew(...args: Parameters<ZLinkRelocationStore['renew']>) {
+    return this.observe('relocation_put', () => this.provider.renew(...args), args[2]);
+  }
+  delete(...args: Parameters<ZLinkRelocationStore['delete']>) {
+    return this.observe('relocation_delete', () => this.provider.delete(...args), args[1]);
+  }
+  private async observe<T>(
+    operation: 'relocation_put' | 'relocation_get' | 'relocation_delete',
+    request: () => Promise<T>,
+    signal?: AbortSignal
+  ): Promise<T> {
+    try {
+      return await request();
+    } catch (error) {
+      if (isRelocationProviderFailure(error, signal)) {
+        this.metrics.recordLocationStoreError(operation);
+      }
+      throw error;
+    }
+  }
+}
+
+function isRelocationProviderFailure(error: unknown, signal?: AbortSignal): boolean {
+  return (
+    isIndeterminateLocationStoreFailure(error, signal) &&
+    !(
+      error instanceof ZLinkFrameworkException && error.kind !== ZLinkFrameworkErrorKind.Unavailable
+    )
+  );
+}

package/src/runtime/locations/request-source-resolver.ts

@@ -0,0 +1,138 @@
+import type { RoutingId } from '../../contracts/Common';
+import type { ZLinkMeshNodeDescriptor } from '../../contracts/Locations/Rows';
+import type { ZLinkLocationOwnerToken } from './internal-location-contracts';
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
+import { awaitWithAbort, throwIfAborted } from '../abort';
+
+/** Source request owner values the first accepting owner records (Location runtime §9.3). */
+export interface ZLinkRequestSourceFence {
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+  readonly nodeRid: RoutingId;
+  readonly nodeGeneration: bigint;
+}
+
+export interface ZLinkRequestSourceResolverOptions {
+  readonly listLiveMeshNodes: (
+    meshName: string,
+    signal?: AbortSignal
+  ) => Promise<readonly ZLinkMeshNodeDescriptor[]>;
+  readonly remainingOwnerTokenLeaseMs: (
+    owner: ZLinkLocationOwnerToken,
+    signal?: AbortSignal
+  ) => Promise<number>;
+  readonly monotonicNowMs?: () => number;
+}
+
+interface PolledSource {
+  readonly fence: ZLinkRequestSourceFence;
+  readonly leaseDeadlineMs: number;
+}
+
+/**
+ * Chooses the descriptor that supplies the source request owner values (Session·Actor binding
+ * §4): the admitted sender's descriptor with the exact RID and node lifecycle generation whose
+ * owner lease passes the Location runtime §4.1 check. Auto-connect polling keeps the live
+ * descriptors here with the local lease deadline computed from the same lease read. A sender
+ * missing from them is read from the Store once and kept with them.
+ */
+export class ZLinkRequestSourceResolver {
+  private readonly polled = new Map<string, Map<string, PolledSource>>();
+  private readonly monotonicNowMs: () => number;
+
+  constructor(private readonly options: ZLinkRequestSourceResolverOptions) {
+    this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+  }
+
+  /** Replaces the polled descriptors of one mesh with a live descriptor listing. */
+  async observeLiveDescriptors(
+    meshName: string,
+    descriptors: readonly ZLinkMeshNodeDescriptor[],
+    signal?: AbortSignal
+  ): Promise<void> {
+    const sources = new Map<string, PolledSource>();
+    for (const descriptor of descriptors) {
+      const source = await this.polledSource(descriptor, signal);
+      if (source !== undefined) sources.set(encodeRoutingIdStorageHex(descriptor.rid), source);
+    }
+    this.polled.set(meshName, sources);
+  }
+
+  /**
+   * Returns the recorded values, undefined when the sender has no live descriptor, or a promise
+   * while the Store is read once for a sender the polled descriptors do not contain.
+   */
+  accept(
+    meshName: string,
+    nodeRid: RoutingId,
+    nodeGeneration: bigint,
+    nodeRidStorageHex: string,
+    signal?: AbortSignal
+  ): ZLinkRequestSourceFence | undefined | Promise<ZLinkRequestSourceFence | undefined> {
+    throwIfAborted(signal);
+    const known = this.polled.get(meshName)?.get(nodeRidStorageHex);
+    if (known !== undefined && known.fence.nodeGeneration === nodeGeneration) {
+      return this.monotonicNowMs() < known.leaseDeadlineMs ? known.fence : undefined;
+    }
+    return this.readOnce(meshName, nodeRid, nodeGeneration, nodeRidStorageHex, signal);
+  }
+
+  private async readOnce(
+    meshName: string,
+    nodeRid: RoutingId,
+    nodeGeneration: bigint,
+    nodeRidStorageHex: string,
+    signal?: AbortSignal
+  ): Promise<ZLinkRequestSourceFence | undefined> {
+    // The Store boundary already classifies provider failures as Unavailable. Preserve their
+    // cause for the ingress error reporter, and let programming errors propagate unchanged.
+    const descriptors = await awaitWithAbort(
+      this.options.listLiveMeshNodes(meshName, signal),
+      signal
+    );
+    const descriptor = descriptors.find(
+      (value) => routingIdsEqual(value.rid, nodeRid) && value.lifecycleGeneration === nodeGeneration
+    );
+    const source =
+      descriptor === undefined ? undefined : await this.polledSource(descriptor, signal);
+    throwIfAborted(signal);
+    if (source === undefined) return undefined;
+    let sources = this.polled.get(meshName);
+    if (sources === undefined) {
+      sources = new Map();
+      this.polled.set(meshName, sources);
+    }
+    sources.set(nodeRidStorageHex, source);
+    return source.fence;
+  }
+
+  private async polledSource(
+    descriptor: ZLinkMeshNodeDescriptor,
+    signal?: AbortSignal
+  ): Promise<PolledSource | undefined> {
+    if (
+      descriptor.ownerId.length === 0 ||
+      descriptor.leaseGeneration <= 0n ||
+      descriptor.lifecycleGeneration <= 0n
+    ) {
+      return undefined;
+    }
+    const remainingMs = await awaitWithAbort(
+      this.options.remainingOwnerTokenLeaseMs(
+        { ownerId: descriptor.ownerId, leaseGeneration: descriptor.leaseGeneration },
+        signal
+      ),
+      signal
+    );
+    if (remainingMs <= 0) return undefined;
+    return {
+      fence: {
+        ownerId: descriptor.ownerId,
+        leaseGeneration: descriptor.leaseGeneration,
+        nodeRid: descriptor.rid,
+        nodeGeneration: descriptor.lifecycleGeneration
+      },
+      leaseDeadlineMs: this.monotonicNowMs() + remainingMs
+    };
+  }
+}

package/src/runtime/locations/resolvers.ts

@@ -17,7 +17,7 @@ import {
   createInternalFrameworkException,
   internalFrameworkErrorKind
 } from '../framework-errors-internal';
-import { routingIdsEqual } from '../routing-id';
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
 import {
   type SpotHandle,
   type ZLinkActorSpotHandleResolver,
@@ -282,7 +282,7 @@ export class ZLinkStoreLocationResolvers
         descriptor.objectRole === ZLinkObjectRole.Server &&
         descriptor.placementWeight > 0 &&
         !routingIdsEqual(descriptor.rid, excludedNodeRid) &&
-        !excludedCandidateRids.has(String(descriptor.rid)) &&
+        !excludedCandidateRids.has(encodeRoutingIdStorageHex(descriptor.rid)) &&
         capacity.active + capacity.reserved < capacity.limit &&
         descriptor.objectCapabilities.some(
           (candidate) => candidate.objectKind === 'actor' && candidate.stableType === actorType

package/src/runtime/locations/runtime.ts

@@ -1,3 +1,5 @@
+import { ZLinkDescriptorPublicationUnconfirmedError } from './descriptor-publication';
+import { isIndeterminateLocationStoreFailure } from './location-store-failure';
 import { listAllMeshNodeDescriptors } from './location-store-pages';
 import { MILLISECONDS_PER_SECOND } from '../diagnostics/runtime-metrics';
 import { ZLINK_PROVIDER_MAX_PAGE_SIZE } from '../../contracts/Locations/Stores';
@@ -148,7 +150,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   private readonly liveRows: ZLinkLiveRowFilter;
   private readonly leaseTracker: ZLinkOwnerLeaseTracker;
   private readonly ownershipLostHandlers = new Set<(event: ZLinkOwnershipLostEvent) => void>();
-  private readonly ownerLeaseRenewedHandlers = new Set<(renewal: ZLinkOwnerLeaseRenewed) => void>();
+  private readonly ownerLeaseRenewedHandlers = new Set<
+    (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  >();
   private readonly ownerLeaseRenewalFailedHandlers = new Set<() => void>();
   private heartbeatTimer: unknown;
   private heartbeatRenewal?: Promise<unknown>;
@@ -216,9 +220,22 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     return this.ownerToken;
   }
 
+  /** Location runtime §5: a startup Store request ends within the renew timeout. */
+  async writeDescriptor<T>(
+    action: (signal?: AbortSignal) => Promise<T>,
+    signal?: AbortSignal
+  ): Promise<T> {
+    try {
+      return await withTimeout(action, this.options.ownerLeaseRenewTimeoutMs, signal);
+    } catch (error) {
+      if (!isIndeterminateLocationStoreFailure(error, signal)) throw error;
+      throw new ZLinkDescriptorPublicationUnconfirmedError(error);
+    }
+  }
+
   closeOwnerLeaseAdmission(error: unknown): void {
     this.ownerLeaseDeadlineMs = undefined;
-    this.recordFailure(errorMessage(error), 'owner_lease_recovery');
+    this.recordFailure(errorMessage(error));
   }
 
   async reclaimOwnerAuthorities(signal?: AbortSignal): Promise<void> {
@@ -308,11 +325,15 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     this.ownershipLostHandlers.delete(handler);
   }
 
-  addOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void {
+  addOwnerLeaseRenewedHandler(
+    handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  ): void {
     this.ownerLeaseRenewedHandlers.add(handler);
   }
 
-  removeOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void {
+  removeOwnerLeaseRenewedHandler(
+    handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  ): void {
     this.ownerLeaseRenewedHandlers.delete(handler);
   }
 
@@ -414,7 +435,6 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       return await this.claimFreshOwnerLease(signal, shutdownSignal);
     }
 
-    const wasOwnerLeaseUsable = this.ownerLeaseUsable;
     try {
       const renewStartedAtMs = this.monotonicNowMs();
       this.leaseOperationStartedAtMs = renewStartedAtMs;
@@ -444,6 +464,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         // another heartbeat interval.
         return await this.claimFreshOwnerLease(signal, shutdownSignal);
       }
+      const wasOwnerLeaseUsable = this.ownerLeaseUsable;
       this.ownerLeaseHealthy = true;
       this.ownerLeaseRenewedAt = result.storeNow;
       this.setOwnerLeaseDeadline(
@@ -453,14 +474,14 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         result.storeNow
       );
       this.lastError = undefined;
-      if (!wasOwnerLeaseUsable) {
-        for (const handler of this.ownerLeaseRenewedHandlers) handler(result);
+      for (const handler of this.ownerLeaseRenewedHandlers) {
+        handler(result, wasOwnerLeaseUsable);
       }
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
       this.recordOwnerLeaseRenewFailure();
-      this.recordFailure(errorMessage(error), 'lease_renew');
+      this.recordFailure(errorMessage(error));
       for (const handler of this.ownerLeaseRenewalFailedHandlers) handler();
       return false;
     }
@@ -484,13 +505,13 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       if (signal?.aborted === true) throw error;
       if (error instanceof ZLinkOwnerLeaseClaimError) throw error;
       this.recordOwnerLeaseRenewFailure();
-      this.recordFailure(errorMessage(error), 'owner_lease_claim');
+      this.recordFailure(errorMessage(error));
       return false;
     }
     const claimCompletedAtMs = this.monotonicNowMs();
     if (claim.kind !== 'claimed') {
       const error = new ZLinkOwnerLeaseClaimError(claim.kind);
-      this.recordFailure(error.message, 'owner_lease_claim');
+      this.recordFailure(error.message);
       throw error;
     }
     try {
@@ -510,16 +531,19 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       );
       this.lastError = undefined;
       for (const handler of this.ownerLeaseRenewedHandlers) {
-        handler({
-          kind: 'renewed',
-          leaseExpiresAt: claim.leaseExpiresAt,
-          storeNow: claim.storeNow
-        });
+        handler(
+          {
+            kind: 'renewed',
+            leaseExpiresAt: claim.leaseExpiresAt,
+            storeNow: claim.storeNow
+          },
+          false
+        );
       }
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
-      this.recordFailure(errorMessage(error), 'owner_lease_claim');
+      this.recordFailure(errorMessage(error));
       return false;
     }
   }
@@ -563,7 +587,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
             throw new ZLinkOwnerCleanupError(completionError);
           }
           if (!isAbortError(completionError)) {
-            this.recordFailure(errorMessage(completionError), 'owner_lease_claim');
+            this.recordFailure(errorMessage(completionError));
           }
         }
       }
@@ -607,9 +631,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         cleanupSignal
       );
     } catch (confirmationError) {
-      this.recordFailure(errorMessage(confirmationError), 'owner_lease_claim_confirmation');
+      this.recordFailure(errorMessage(confirmationError));
       if (cancelled) throw new ZLinkOwnerCleanupError(confirmationError);
-      throw confirmationError;
+      throw originalError instanceof ZLinkOwnerLeaseClaimError ? originalError : confirmationError;
     }
     if (confirmed.kind !== 'found' || confirmed.token.ownerId !== this.ownerId) {
       throw originalError;
@@ -625,7 +649,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
           cleanupSignal
         );
       } catch (releaseError) {
-        this.recordFailure(errorMessage(releaseError), 'owner_lease_release');
+        this.recordFailure(errorMessage(releaseError));
         throw new ZLinkOwnerCleanupError(releaseError);
       }
       throw originalError;
@@ -693,7 +717,10 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       updatedAt: new Date()
     };
     let result = await this.guardWrite(() =>
-      this.stores.locationStore.updateMeshNode(stamped, intent, signal)
+      this.writeDescriptor(
+        (writeSignal) => this.stores.locationStore.updateMeshNode(stamped, intent, writeSignal),
+        signal
+      )
     );
     if (
       intent === ZLinkLocationWriteIntent.Renew &&
@@ -705,7 +732,15 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       // NewClaim as a bounded fallback. If another owner has recreated the
       // row, NewClaim remains rejected and the caller keeps the conflict.
       result = await this.guardWrite(() =>
-        this.stores.locationStore.updateMeshNode(stamped, ZLinkLocationWriteIntent.NewClaim, signal)
+        this.writeDescriptor(
+          (writeSignal) =>
+            this.stores.locationStore.updateMeshNode(
+              stamped,
+              ZLinkLocationWriteIntent.NewClaim,
+              writeSignal
+            ),
+          signal
+        )
       );
     }
     this.notifyIfStale(
@@ -912,7 +947,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   }
 
   reportDiscoveryFailure(error: unknown): void {
-    this.recordFailure(errorMessage(error), 'read');
+    this.recordFailure(errorMessage(error));
   }
 
   async listPeerLocations(
@@ -945,6 +980,14 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     return live.map((row) => ({ ...row, endpoint: normalizeEndpoint(row.endpoint) }));
   }
 
+  /** Remaining exact owner lease from the same tracker that filters live descriptors. */
+  remainingOwnerTokenLeaseMs(
+    owner: ZLinkLocationOwnerToken,
+    signal?: AbortSignal
+  ): Promise<number> {
+    return this.leaseTracker.remainingOwnerTokenLeaseMs(owner, signal);
+  }
+
   async listMeshNodeDescriptors(
     meshName: string,
     page?: ZLinkPageRequest,
@@ -1269,7 +1312,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         this.monotonicNowMs() >= this.ownerLeaseDeadlineMs
       ) {
         this.ownerLeaseHealthy = false;
-        this.recordFailure('Owner lease expired before renewal completed.', 'lease_expired');
+        this.recordFailure('Owner lease expired before renewal completed.');
         for (const handler of this.ownerLeaseRenewalFailedHandlers) handler();
       }
       const renewal = this.renewOwnerLeaseOnce()
@@ -1294,7 +1337,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     try {
       return await write();
     } catch (error) {
-      this.recordFailure(errorMessage(error), 'compare_exchange');
+      this.recordFailure(errorMessage(error));
       throw error;
     }
   }
@@ -1305,7 +1348,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     try {
       return await write();
     } catch (error) {
-      this.recordFailure(errorMessage(error), 'compare_exchange');
+      this.recordFailure(errorMessage(error));
       throw error;
     }
   }
@@ -1315,12 +1358,6 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     kind: ZLinkLocationKind,
     key: string
   ): void {
-    if (
-      result.status === ZLinkLocationWriteStatus.IgnoredStale ||
-      result.status === ZLinkLocationWriteStatus.RejectedConflict
-    ) {
-      this.metrics?.recordLocationStoreError('compare_exchange');
-    }
     if (result.status !== ZLinkLocationWriteStatus.IgnoredStale) {
       return;
     }
@@ -1334,12 +1371,6 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     kind: ZLinkLocationKind,
     key: string
   ): void {
-    if (
-      status === ZLinkLocationWriteStatus.IgnoredStale ||
-      status === ZLinkLocationWriteStatus.RejectedConflict
-    ) {
-      this.metrics?.recordLocationStoreError('compare_exchange');
-    }
     if (status !== ZLinkLocationWriteStatus.IgnoredStale) {
       return;
     }
@@ -1348,8 +1379,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     }
   }
 
-  private recordFailure(message: string, operation = 'read'): void {
-    this.metrics?.recordLocationStoreError(operation);
+  private recordFailure(message: string): void {
     this.ownerLeaseHealthy = false;
     this.lastError = message;
   }

package/src/runtime/messaging/payload-codec.ts

@@ -17,10 +17,7 @@ import {
   materializeZLinkMessageValue,
   readZLinkMessageDeclaredType
 } from '../../contracts/Common/ZLinkMessage';
-import {
-  adoptEncodedPayload,
-  borrowEncodedPayload
-} from '../../contracts/Common/encoded-payload-storage';
+import { borrowEncodedPayload } from '../../contracts/Common/encoded-payload-storage';
 import { ZLinkConfigurationException } from '../configuration';
 import { parseFrameworkJsonV1, stringifyFrameworkJsonV1 } from './framework-json-v1';
 import type { ZLinkJsonSchema } from '../../contracts/Handlers/JsonContract';
@@ -434,13 +431,13 @@ function toRuntimeMessage(payload: ZLinkEncodedPayload): Message {
     : RuntimeMessage.fromOwned(owned);
 }
 
-function encodedPayloadFromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
-  if (!Buffer.isBuffer(bytes)) {
-    return ZLinkEncodedPayload.from(bytes);
-  }
-  const payload = ZLinkEncodedPayload.from(Buffer.alloc(0));
-  adoptEncodedPayload(payload, bytes);
-  return payload;
+/**
+ * Wraps received bytes for a serializer without copying them. Binding receive
+ * Buffers keep their storage after the message closes and nothing writes to
+ * them, so the payload may adopt them; the public from() and data() still copy.
+ */
+export function encodedPayloadFromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
+  return ZLinkEncodedPayload.fromOwned(bytes);
 }
 
 function rememberContentType(message: Message, contentType: string): Message {

package/src/runtime/messaging/request-result.ts

@@ -3,56 +3,60 @@ import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
 const completedAdmission = Promise.resolve();
 const ignoreAdmissionFailure = (): void => {};
 
-export function createZLinkRequest<TReply>(
-  start: (onAdmitted: () => void) => Promise<TReply>,
-  deliverReply?: (reply: Promise<TReply>) => Promise<TReply>
-): ZLinkRequest<TReply> {
-  let admitted: Promise<void> | undefined;
-  let resolveAdmission: (() => void) | undefined;
-  let rejectAdmission: ((error: unknown) => void) | undefined;
-  const confirmAdmission = (): void => {
-    admitted ??= completedAdmission;
-    resolveAdmission?.();
-  };
-  const failAdmission = (error: unknown): void => {
-    if (admitted === undefined) {
-      admitted = Promise.reject(error);
+class RequestAdmission {
+  private admitted: Promise<void> | undefined;
+  private resolveAdmission: (() => void) | undefined;
+  private rejectAdmission: ((error: unknown) => void) | undefined;
+  confirm(): void {
+    this.admitted ??= completedAdmission;
+    this.resolveAdmission?.();
+  }
+  fail(error: unknown): void {
+    if (this.admitted === undefined) {
+      this.admitted = Promise.reject(error);
       // Existing callers may observe only the reply Promise. Observing the
       // rejection here leaves the public admission Promise rejected.
-      void admitted.catch(ignoreAdmissionFailure);
+      void this.admitted.catch(ignoreAdmissionFailure);
     } else {
-      rejectAdmission?.(error);
+      this.rejectAdmission?.(error);
     }
-  };
-  const observeAdmission = (): Promise<void> => {
-    if (admitted === undefined) {
-      admitted = new Promise<void>((resolve, reject) => {
-        resolveAdmission = resolve;
-        rejectAdmission = reject;
+  }
+  observe(): Promise<void> {
+    if (this.admitted === undefined) {
+      this.admitted = new Promise<void>((resolve, reject) => {
+        this.resolveAdmission = resolve;
+        this.rejectAdmission = reject;
       });
-      void admitted.catch(ignoreAdmissionFailure);
+      void this.admitted.catch(ignoreAdmissionFailure);
     }
-    return admitted;
-  };
+    return this.admitted;
+  }
+}
+
+export function createZLinkRequest<TReply>(
+  start: (onAdmitted: () => void) => Promise<TReply>,
+  deliverReply?: (reply: Promise<TReply>) => Promise<TReply>
+): ZLinkRequest<TReply> {
+  const admission = new RequestAdmission();
   let pending: Promise<TReply>;
   try {
-    pending = start(confirmAdmission);
+    pending = start(() => admission.confirm());
   } catch (error) {
     pending = Promise.reject(error);
   }
   const observed = pending.then(
     (value) => {
       // A successful reply proves admission even without an observation callback.
-      confirmAdmission();
+      admission.confirm();
       return value;
     },
     (error: unknown) => {
-      failAdmission(error);
+      admission.fail(error);
       throw error;
     }
   );
   const reply = deliverReply?.(observed) ?? observed;
   return Object.defineProperty(reply, 'admitted', {
-    get: observeAdmission
+    get: () => admission.observe()
   }) as ZLinkRequest<TReply>;
 }