@enbox/dwn-clients 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/dwn-clients",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
@@ -43,12 +43,12 @@
     "access": "public"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.14"
   },
   "dependencies": {
     "@enbox/common": "0.1.1",
     "@enbox/crypto": "0.1.1",
-    "@enbox/dwn-sdk-js": "0.3.9",
+    "@enbox/dwn-sdk-js": "0.4.1",
     "ms": "2.1.3"
   },
   "devDependencies": {
@@ -57,7 +57,7 @@
     "@types/sinon": "17.0.3",
     "@typescript-eslint/eslint-plugin": "8.32.1",
     "@typescript-eslint/parser": "8.32.1",
-    "bun-types": "1.3.10",
+    "bun-types": "1.3.14",
     "eslint": "9.7.0",
     "sinon": "18.0.0",
     "typescript": "5.9.3"

package/src/dwn-rpc-error.ts

@@ -0,0 +1,52 @@
+import { JsonRpcErrorCodes } from './json-rpc.js';
+
+/**
+ * Error surfaced by DWN JSON-RPC transports when the server returns a typed
+ * JSON-RPC error envelope.
+ */
+export class DwnRpcError extends Error {
+  public readonly code: JsonRpcErrorCodes;
+  public readonly data?: unknown;
+  public readonly terminal: boolean;
+
+  constructor(code: JsonRpcErrorCodes, message: string, data?: unknown) {
+    super(`(${code}) - ${message}`);
+    this.name = 'DwnRpcError';
+    this.code = code;
+    this.data = data;
+    this.terminal = isTerminalJsonRpcErrorCode(code, message, data);
+  }
+}
+
+/**
+ * JSON-RPC errors that represent deterministic request rejection before DWN
+ * replicated admission can run. Internal/server/transport/rate-limit errors
+ * remain retryable.
+ */
+export function isTerminalJsonRpcErrorCode(code: JsonRpcErrorCodes, message = '', data?: unknown): boolean {
+  if (isQuotaExceededError(message, data)) {
+    return false;
+  }
+
+  switch (code) {
+    case JsonRpcErrorCodes.InvalidRequest:
+    case JsonRpcErrorCodes.InvalidParams:
+    case JsonRpcErrorCodes.BadRequest:
+    case JsonRpcErrorCodes.Unauthorized:
+    case JsonRpcErrorCodes.Forbidden:
+    case JsonRpcErrorCodes.Conflict:
+      return true;
+    default:
+      return false;
+  }
+}
+
+function isQuotaExceededError(message: string, data: unknown): boolean {
+  const code = typeof data === 'object' && data !== null && 'code' in data
+    ? (data as { code?: unknown }).code
+    : undefined;
+  return code === 'TenantMessageQuotaExceeded' ||
+    code === 'TenantStorageQuotaExceeded' ||
+    message.includes('TenantMessageQuotaExceeded') ||
+    message.includes('TenantStorageQuotaExceeded');
+}

package/src/dwn-rpc-types.ts

@@ -1,4 +1,11 @@
-import type { GenericMessage, ProgressToken, RecordsReadReply, SubscriptionMessage, UnionMessageReply } from '@enbox/dwn-sdk-js';
+import type {
+  GenericMessage,
+  ProgressToken,
+  RecordsReadReply,
+  ReplicationApplyResult,
+  SubscriptionMessage,
+  UnionMessageReply,
+} from '@enbox/dwn-sdk-js';
 
 export interface SerializableDwnMessage {
   toJSON(): string;
@@ -74,6 +81,15 @@ export interface DwnRpc {
    * @returns A promise that resolves to the response from the DWN server.
    */
   sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse>
+
+  /**
+   * Applies a replicated message through the DWN server's replication entry point.
+   *
+   * This differs from `sendDwnRequest()` in duplicate replay handling: the server
+   * calls `Dwn.applyReplicatedMessage()`, which repairs missing replication index
+   * entries when the message store already contains the exact message.
+   */
+  applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult>
 }
 
 
@@ -110,6 +126,13 @@ export type DwnRpcRequest = {
    */
   signal?: AbortSignal;
 
+  /**
+   * Optional HTTP per-attempt timeout in milliseconds. When supplied, this
+   * replaces the transport default timeout; use this for legitimate large
+   * uploads that need more than the default budget.
+   */
+  timeoutMs?: number;
+
   /**
    * Subscription options — only set for subscribe requests.
    * Groups the handler, resubscribe factory, and any future subscription
@@ -129,6 +152,34 @@ export type DwnRpcRequest = {
   };
 };
 
+/**
+ * Represents a JSON RPC request to apply a replicated DWN message through the
+ * server-side replication entry point.
+ */
+export type DwnReplicationApplyRequest = {
+  /** Optional data to be sent with the request. */
+  data?: any;
+
+  /** The URL of the DWN server to which the request is sent. */
+  dwnUrl: string;
+
+  /** The replicated message to apply. */
+  message: GenericMessage | SerializableDwnMessage;
+
+  /** The DID of the target tenant to which the message is addressed. */
+  targetDid: string;
+
+  /** Optional caller-provided abort signal. Honoured by the HTTP transport. */
+  signal?: AbortSignal;
+
+  /**
+   * Optional HTTP per-attempt timeout in milliseconds. When omitted, HTTP
+   * replicated apply uses a larger default for data-bearing RecordsWrite
+   * messages so large sync uploads are not aborted by the normal short budget.
+   */
+  timeoutMs?: number;
+};
+
 /**
  * Represents the JSON RPC response from a DWN server to a request, combining the results of various
  * DWN operations.

package/src/http-dwn-rpc-client.ts

@@ -1,10 +1,13 @@
 import type { JsonRpcResponse } from './json-rpc.js';
-import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './dwn-rpc-types.js';
+import type { ReplicationApplyResult } from '@enbox/dwn-sdk-js';
+import type { DwnReplicationApplyRequest, DwnRpc, DwnRpcRequest, DwnRpcResponse } from './dwn-rpc-types.js';
 import type { DwnServerInfoCache, ServerInfo } from './server-info-types.js';
 
 import { CryptoUtils } from '@enbox/crypto';
-import { DataStream } from '@enbox/dwn-sdk-js';
+import { DwnRpcError } from './dwn-rpc-error.js';
 import { DwnServerInfoCacheMemory } from './dwn-server-info-cache-memory.js';
+import { normalizeReadableStream } from './readable-stream.js';
+import { parseReplicationApplyResult } from './replication-apply-result.js';
 import { RateLimitError } from './rate-limit-error.js';
 import { sleep } from '@enbox/common';
 import { createJsonRpcRequest, JsonRpcErrorCodes, parseJson } from './json-rpc.js';
@@ -25,6 +28,9 @@ const DEFAULT_MAX_DELAY_MS = 10_000;
 /** Per-request timeout in milliseconds (prevents hung connections / SSRF). */
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 
+/** Larger per-attempt timeout for data-bearing replicated apply uploads. */
+const DEFAULT_LARGE_REPLICATED_APPLY_TIMEOUT_MS = 300_000;
+
 /** HTTP status codes that are considered retryable. */
 const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
 
@@ -93,6 +99,48 @@ function parseRetryAfterMs(response: Response): number | undefined {
   return undefined;
 }
 
+function createAttemptInit(init: RequestInit | undefined, requestTimeoutMs: number): RequestInit {
+  const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
+  if (init?.signal === undefined || init.signal === null) {
+    return { ...init, signal: timeoutSignal };
+  }
+
+  return { ...init, signal: AbortSignal.any([init.signal, timeoutSignal]) };
+}
+
+function shouldReturnResponse(response: Response, attempt: number, maxRetriesForRequest: number): boolean {
+  return !RETRYABLE_STATUS_CODES.has(response.status) || attempt === maxRetriesForRequest;
+}
+
+function shouldRethrowFetchError(error: unknown, attempt: number, maxRetriesForRequest: number): boolean {
+  return !isRetryable(error) || attempt === maxRetriesForRequest;
+}
+
+function getRetryDelayMs(attempt: number, baseDelayMs: number, maxDelayMs: number, lastResponse?: Response): number {
+  const retryAfterMs = lastResponse !== undefined ? parseRetryAfterMs(lastResponse) : undefined;
+  const backoffMs = computeBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+
+  return retryAfterMs === undefined ? backoffMs : Math.max(retryAfterMs, backoffMs);
+}
+
+/**
+ * Mutates the request options and headers with an octet-stream body.
+ * Returns whether the body is replayable for transport-level retries.
+ */
+function attachDataRequestBody(fetchOpts: RequestInit, requestHeaders: Record<string, string>, requestBody: BodyInit): boolean {
+  requestHeaders['content-type'] = 'application/octet-stream';
+  fetchOpts.body = requestBody;
+
+  if (requestBody instanceof ReadableStream) {
+    // Required by the Fetch standard for streaming request bodies. The stream is one-shot,
+    // so transport-level retries must not replay the same body after a failed attempt.
+    (fetchOpts as RequestInit & { duplex: 'half' }).duplex = 'half';
+    return false;
+  }
+
+  return true;
+}
+
 /**
  * HTTP client that can be used to communicate with Dwn Servers.
  *
@@ -113,11 +161,6 @@ export class HttpDwnRpcClient implements DwnRpc {
     };
   }
 
-  /** Detects whether the current runtime is Bun (vs a browser). */
-  static isBunRuntime(): boolean {
-    return typeof (globalThis as Record<string, unknown>).Bun !== 'undefined';
-  }
-
   get transportProtocols(): string[] { return ['http:', 'https:']; }
 
   async sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse> {
@@ -141,29 +184,15 @@ export class HttpDwnRpcClient implements DwnRpc {
       ...(request.signal ? { signal: request.signal } : {}),
     };
 
-    if (request.data) {
-      requestHeaders['content-type'] = 'application/octet-stream';
-      let requestBody = request.data;
-
-      if (requestBody instanceof ReadableStream) {
-        // Bun's fetch currently fails on some ReadableStream uploads in the sync push path.
-        // Buffer to a Blob in Bun to avoid the broken path. In browsers, keep the stream
-        // and set `duplex: 'half'` which the Fetch spec requires for streaming request bodies.
-        // See: https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests
-        if (HttpDwnRpcClient.isBunRuntime()) {
-          const bodyBytes = await DataStream.toBytes(requestBody as ReadableStream<Uint8Array>);
-          requestBody = new Blob([bodyBytes as BlobPart], { type: 'application/octet-stream' });
-        } else {
-          // Browsers require `duplex: 'half'` when the fetch body is a ReadableStream.
-          // TypeScript's built-in RequestInit does not include `duplex` yet.
-          (fetchOpts as Record<string, unknown>).duplex = 'half';
-        }
-      }
-
-      fetchOpts.body = requestBody;
+    let isRequestBodyReplayable = true;
+    if (request.data !== undefined) {
+      isRequestBodyReplayable = attachDataRequestBody(fetchOpts, requestHeaders, request.data as BodyInit);
     }
 
-    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts);
+    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts, {
+      requestTimeoutMs     : request.timeoutMs,
+      retryableRequestBody : isRequestBodyReplayable,
+    });
 
     // After retries are exhausted, a 429 means we're still rate-limited.
     // Per-IP 429s return plain JSON (not a JSON-RPC envelope), so we must
@@ -205,29 +234,74 @@ export class HttpDwnRpcClient implements DwnRpc {
         const retryAfter = dwnRpcResponse.error.data?.retryAfterSec ?? 1;
         throw new RateLimitError(retryAfter);
       }
-      throw new Error(`(${code}) - ${message}`);
+      throw new DwnRpcError(code, message, dwnRpcResponse.error.data);
     }
 
-    // Materialise the response body before attaching to the reply.
-    // Bun has a bug where ReadableStream from fetch resp.body crashes in
-    // DataStream.toBytes() (reader.releaseLock() is undefined) when the
-    // stream is later consumed by the local DWN node (e.g. during sync).
-    // Buffering via arrayBuffer() avoids the broken getReader() path.
-    // TODO: https://github.com/enboxorg/enbox/issues/90 — remove once Bun ships fix
     const { reply } = dwnRpcResponse.result;
     if (hasDataStream) {
-      const bodyBytes = new Uint8Array(await resp.arrayBuffer());
-      const dataStream = DataStream.fromBytes(bodyBytes);
+      const dataStream = resp.body;
+      if (dataStream === null) {
+        throw new Error(`missing data stream in json rpc response. dwn url: ${request.dwnUrl}`);
+      }
       if (reply.record) {
-        reply.record.data = dataStream;
+        reply.record.data = normalizeReadableStream(dataStream);
       } else if (reply.entry) {
-        reply.entry.data = dataStream;
+        reply.entry.data = normalizeReadableStream(dataStream);
       }
     }
 
     return reply as DwnRpcResponse;
   }
 
+  async applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult> {
+    const requestId = CryptoUtils.randomUuid();
+    const jsonRpcRequest = createJsonRpcRequest(requestId, 'dwn.applyReplicatedMessage', {
+      target  : request.targetDid,
+      message : request.message
+    });
+
+    const requestHeaders: Record<string, string> = {
+      'dwn-request': JSON.stringify(jsonRpcRequest)
+    };
+
+    const fetchOpts: RequestInit = {
+      method  : 'POST',
+      headers : requestHeaders,
+      ...(request.signal ? { signal: request.signal } : {}),
+    };
+
+    let isRequestBodyReplayable = true;
+    if (request.data !== undefined) {
+      isRequestBodyReplayable = attachDataRequestBody(fetchOpts, requestHeaders, request.data as BodyInit);
+    }
+
+    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts, {
+      requestTimeoutMs     : request.timeoutMs ?? defaultReplicationApplyTimeoutMs(request.message),
+      retryableRequestBody : isRequestBodyReplayable,
+    });
+    if (resp.status === 429) {
+      const retryAfter = Number.parseInt(resp.headers.get('retry-after') ?? '1', 10);
+      throw new RateLimitError(retryAfter);
+    }
+
+    const responseBody = await resp.text();
+    const jsonRpcResponse = parseJson(responseBody) as JsonRpcResponse;
+    if (jsonRpcResponse == null) {
+      throw new Error(`failed to parse json rpc response. dwn url: ${request.dwnUrl}, status: ${resp.status}`);
+    }
+
+    if (jsonRpcResponse.error) {
+      const { code, message } = jsonRpcResponse.error;
+      if (code === JsonRpcErrorCodes.TooManyRequests) {
+        const retryAfter = jsonRpcResponse.error.data?.retryAfterSec ?? 1;
+        throw new RateLimitError(retryAfter);
+      }
+      throw new DwnRpcError(code, message, jsonRpcResponse.error.data);
+    }
+
+    return parseReplicationApplyResult(jsonRpcResponse.result.result);
+  }
+
   async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
     const serverInfo = await this.serverInfoCache.get(dwnUrl);
     if (serverInfo) {
@@ -279,46 +353,39 @@ export class HttpDwnRpcClient implements DwnRpc {
    * retryable HTTP status codes with exponential backoff and jitter.
    * Honours the `Retry-After` response header when present.
    */
-  private async fetchWithRetry(url: string, init?: RequestInit): Promise<Response> {
+  private async fetchWithRetry(
+    url: string,
+    init?: RequestInit,
+    options: { requestTimeoutMs?: number; retryableRequestBody?: boolean } = {},
+  ): Promise<Response> {
     const { maxRetries, baseDelayMs, maxDelayMs } = this._retryOptions;
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const maxRetriesForRequest = options.retryableRequestBody === false ? 0 : maxRetries;
 
     let lastError: unknown;
     let lastResponse: Response | undefined;
 
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= maxRetriesForRequest; attempt++) {
       try {
         // Apply a per-attempt timeout to prevent hung connections / SSRF.
         // If the caller already supplied a signal, combine it with the timeout
         // via AbortSignal.any(); otherwise create a fresh timeout signal.
-        const timeoutSignal = AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
-        const attemptInit: RequestInit = {
-          ...init,
-          signal: init?.signal
-            ? AbortSignal.any([init.signal, timeoutSignal])
-            : timeoutSignal,
-        };
-
-        const response = await fetch(url, attemptInit);
-
-        if (!RETRYABLE_STATUS_CODES.has(response.status) || attempt === maxRetries) {
+        const response = await fetch(url, createAttemptInit(init, requestTimeoutMs));
+        if (shouldReturnResponse(response, attempt, maxRetriesForRequest)) {
           return response;
         }
 
         // Retryable status — back off and try again.
         lastResponse = response;
       } catch (error: unknown) {
-        if (!isRetryable(error) || attempt === maxRetries) {
+        if (shouldRethrowFetchError(error, attempt, maxRetriesForRequest)) {
           throw error;
         }
         lastError = error;
       }
 
       // Compute the delay, preferring Retry-After when available.
-      const retryAfterMs = lastResponse ? parseRetryAfterMs(lastResponse) : undefined;
-      const backoffMs = computeBackoffDelay(attempt, baseDelayMs, maxDelayMs);
-      const delayMs = retryAfterMs === undefined ? backoffMs : Math.max(retryAfterMs, backoffMs);
-
-      await sleep(delayMs);
+      await sleep(getRetryDelayMs(attempt, baseDelayMs, maxDelayMs, lastResponse));
     }
 
     // Should not reach here, but satisfy the compiler.
@@ -328,3 +395,10 @@ export class HttpDwnRpcClient implements DwnRpc {
     throw lastError;
   }
 }
+
+function defaultReplicationApplyTimeoutMs(message: DwnReplicationApplyRequest['message']): number | undefined {
+  const dataSize = (message as { descriptor?: { dataSize?: unknown } }).descriptor?.dataSize;
+  return typeof dataSize === 'number' && dataSize > 1_048_576
+    ? DEFAULT_LARGE_REPLICATED_APPLY_TIMEOUT_MS
+    : undefined;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './dwn-registrar.js';
+export * from './dwn-rpc-error.js';
 export * from './dwn-rpc-types.js';
 export * from './dwn-server-info-cache-memory.js';
 export * from './http-dwn-rpc-client.js';
@@ -6,9 +7,11 @@ export * from './json-rpc.js';
 export * from './json-rpc-socket.js';
 export * from './provider-directory-types.js';
 export * from './rate-limit-error.js';
+export * from './readable-stream.js';
 export * from './registration-types.js';
 export * from './rpc-client.js';
 export * from './server-info-types.js';
+export * from './ws-payload-size.js';
 // `./utils.js` removed: `concatenateUrl` (its only export) lives in
 // `@enbox/common` now — import from there if you need it.
 export * from './web-socket-clients.js';

package/src/json-rpc-socket.ts

@@ -177,12 +177,17 @@ export class JsonRpcSocket {
   public async request(request: JsonRpcRequest): Promise<JsonRpcResponse> {
     return new Promise((resolve, reject) => {
       request.id ??= CryptoUtils.randomUuid();
+      const timeout = setTimeout(() => {
+        this.messageHandlers.delete(request.id!);
+        reject(new Error('request timed out'));
+      }, this.responseTimeout);
 
       const handleResponse = (event: { data: any }):void => {
         const jsonRpsResponse = parseJson(toText(event.data)) as JsonRpcResponse;
         if (jsonRpsResponse.id === request.id) {
           // if the incoming response id matches the request id, we will remove the listener and resolve the response
           this.messageHandlers.delete(request.id);
+          clearTimeout(timeout);
           return resolve(jsonRpsResponse);
         }
       };
@@ -190,12 +195,6 @@ export class JsonRpcSocket {
       // add the listener to the map of message handlers
       this.messageHandlers.set(request.id!, handleResponse);
       this.send(request);
-
-      // reject this promise if we don't receive any response back within the timeout period
-      setTimeout(() => {
-        this.messageHandlers.delete(request.id!);
-        reject(new Error('request timed out'));
-      }, this.responseTimeout);
     });
   }
 

package/src/readable-stream.ts

@@ -0,0 +1,59 @@
+type ReadableStreamReader = {
+  cancel?: (reason?: unknown) => Promise<void>;
+  read(): Promise<{ done: boolean; value?: Uint8Array }>;
+  releaseLock?: () => void;
+};
+
+/**
+ * Wraps runtime-provided streams in a standard `ReadableStream` so downstream
+ * consumers see consistent reader behavior across Bun and browsers.
+ */
+export function normalizeReadableStream(readableStream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  const reader = readableStream.getReader() as ReadableStreamReader;
+  let readerReleased = false;
+
+  const releaseReader = (): void => {
+    if (readerReleased) {
+      return;
+    }
+
+    reader.releaseLock?.();
+    readerReleased = true;
+  };
+
+  const cancelReader = async (reason?: unknown): Promise<void> => {
+    try {
+      await reader.cancel?.(reason);
+    } finally {
+      releaseReader();
+    }
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller): Promise<void> {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          releaseReader();
+          controller.close();
+          return;
+        }
+
+        controller.enqueue(value!);
+      } catch (error: unknown) {
+        try {
+          await reader.cancel?.(error);
+        } catch {
+          // Preserve the original read error.
+        } finally {
+          releaseReader();
+        }
+        throw error;
+      }
+    },
+
+    async cancel(reason): Promise<void> {
+      await cancelReader(reason);
+    },
+  });
+}

package/src/replication-apply-result.ts

@@ -0,0 +1,124 @@
+import type { DependencyRef, ProgressToken, ReplicationApplyResult } from '@enbox/dwn-sdk-js';
+
+import { DwnRpcError } from './dwn-rpc-error.js';
+import { JsonRpcErrorCodes } from './json-rpc.js';
+
+const deferredReasons = new Set(['tenant-inactive', 'resolver-unavailable', 'storage']);
+
+export function parseReplicationApplyResult(value: unknown): ReplicationApplyResult {
+  if (!isObject(value) || typeof value.kind !== 'string') {
+    throw malformedReplicationApplyResult('result must be an object with a string kind');
+  }
+
+  switch (value.kind) {
+    case 'Applied':
+      return parseAppliedResult(value);
+    case 'Duplicate':
+    case 'Superseded':
+      return { kind: value.kind };
+    case 'Incomplete':
+      if (!Array.isArray(value.missing) || !value.missing.every(isDependencyRef)) {
+        throw malformedReplicationApplyResult('Incomplete result must include missing dependency refs');
+      }
+      return { kind: 'Incomplete', missing: value.missing };
+    case 'Invalid':
+      if (typeof value.reason !== 'string') {
+        throw malformedReplicationApplyResult('Invalid result must include a string reason');
+      }
+      return { kind: 'Invalid', reason: value.reason };
+    case 'Deferred':
+      if (typeof value.reason !== 'string' || !deferredReasons.has(value.reason)) {
+        throw malformedReplicationApplyResult('Deferred result must include a valid reason');
+      }
+      return { kind: 'Deferred', reason: value.reason as Extract<ReplicationApplyResult, { kind: 'Deferred' }>['reason'] };
+    default:
+      throw malformedReplicationApplyResult(`unknown result kind ${value.kind}`);
+  }
+}
+
+function parseAppliedResult(value: Record<string, unknown>): Extract<ReplicationApplyResult, { kind: 'Applied' }> {
+  const result: Extract<ReplicationApplyResult, { kind: 'Applied' }> = { kind: 'Applied' };
+
+  if (value.ancestryOnly !== undefined) {
+    if (value.ancestryOnly !== true) {
+      throw malformedReplicationApplyResult('Applied result ancestryOnly must be true when present');
+    }
+    result.ancestryOnly = true;
+  }
+
+  if (value.position !== undefined) {
+    if (!isProgressToken(value.position)) {
+      throw malformedReplicationApplyResult('Applied result position must be a valid ProgressToken when present');
+    }
+    result.position = value.position;
+  }
+
+  return result;
+}
+
+function malformedReplicationApplyResult(detail: string): DwnRpcError {
+  return new DwnRpcError(
+    JsonRpcErrorCodes.InternalError,
+    `malformed dwn.applyReplicatedMessage result: ${detail}`,
+  );
+}
+
+function isDependencyRef(value: unknown): value is DependencyRef {
+  if (!isObject(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  if (!isOptionalString(value.messageCid) || !isOptionalBoolean(value.terminal)) {
+    return false;
+  }
+
+  switch (value.type) {
+    case 'Protocol':
+      return typeof value.protocol === 'string';
+    case 'InitialWrite':
+      return typeof value.recordId === 'string' && isOptionalString(value.protocol);
+    case 'Parent':
+      return typeof value.recordId === 'string' && typeof value.protocol === 'string';
+    case 'Ancestor':
+      return typeof value.recordId === 'string' && isOptionalString(value.protocol);
+    case 'Role':
+      return typeof value.protocol === 'string' &&
+        typeof value.protocolPath === 'string' &&
+        typeof value.recipient === 'string' &&
+        isOptionalString(value.contextPrefix);
+    case 'Grant':
+      return typeof value.permissionGrantId === 'string';
+    case 'KeyDelivery':
+      return typeof value.protocol === 'string' && typeof value.contextId === 'string';
+    case 'CrossProtocolRef':
+      return typeof value.protocol === 'string' && typeof value.recordId === 'string';
+    case 'RecordData':
+      return typeof value.recordId === 'string' &&
+        typeof value.dataCid === 'string' &&
+        isOptionalString(value.protocol);
+    default:
+      return false;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isProgressToken(value: unknown): value is ProgressToken {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  return typeof value.streamId === 'string' && value.streamId !== '' &&
+    typeof value.epoch === 'string' && value.epoch !== '' &&
+    typeof value.position === 'string' && value.position !== '' &&
+    (value.messageCid === undefined || (typeof value.messageCid === 'string' && value.messageCid !== ''));
+}
+
+function isOptionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === 'string';
+}
+
+function isOptionalBoolean(value: unknown): value is boolean | undefined {
+  return value === undefined || typeof value === 'boolean';
+}