@tinycloud/sdk-services 3.2.0-beta.2 → 3.2.0-beta.5

package/dist/kv/index.cjs

@@ -20,10 +20,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/kv/index.ts
 var kv_exports = {};
 __export(kv_exports, {
+  CLEAR_PENDING_WARNING: () => CLEAR_PENDING_WARNING,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS: () => DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   KVAction: () => KVAction,
   KVService: () => KVService,
-  PrefixedKVService: () => PrefixedKVService
+  PrefixedKVService: () => PrefixedKVService,
+  canonicalReplicationIdentity: () => canonicalReplicationIdentity,
+  kvPrefixCovers: () => kvPrefixCovers,
+  replicationIdentityKey: () => replicationIdentityKey,
+  requiresSecretsOptIn: () => requiresSecretsOptIn
 });
 module.exports = __toCommonJS(kv_exports);
 
@@ -89,7 +94,12 @@ var TelemetryEvents = {
   SERVICE_ERROR: "service.error",
   SERVICE_RETRY: "service.retry",
   SESSION_CHANGED: "session.changed",
-  SESSION_EXPIRED: "session.expired"
+  SESSION_EXPIRED: "session.expired",
+  REPLICATION_READ: "replication.read",
+  REPLICATION_WRITE: "replication.write",
+  REPLICATION_SYNC: "replication.sync",
+  REPLICATION_STATE: "replication.state",
+  REPLICATION_DIVERGENCE: "replication.divergence"
 };
 function ok(data) {
   return { ok: true, data };
@@ -617,6 +627,7 @@ var BaseService = class {
     const parents = [
       this.abortController.signal,
       this.context?.abortSignal,
+      this.context?.operationAbortSignal,
       signal
     ].filter((parent) => parent !== void 0);
     for (const parent of parents) {
@@ -862,14 +873,28 @@ var KVService = class extends BaseService {
    */
   constructor(config = {}) {
     super();
+    this.readThrough = null;
+    this.readThroughReady = null;
     this._config = config;
   }
+  /** Delay KV routing until an asynchronously loaded read-through is attached. */
+  setReadThroughReady(ready) {
+    const settled = ready.then(() => void 0, () => void 0);
+    this.readThroughReady = settled;
+    void settled.then(() => {
+      if (this.readThroughReady === settled) this.readThroughReady = null;
+    });
+  }
   /**
    * Get the service configuration.
    */
   get config() {
     return this._config;
   }
+  /** Install or remove the optional replication read-through policy. */
+  setReadThrough(readThrough) {
+    this.readThrough = readThrough;
+  }
   handleQuotaErrorResponse(response, errorText, key) {
     if (response.status !== 402 && response.status !== 413) {
       return void 0;
@@ -1123,6 +1148,7 @@ var KVService = class extends BaseService {
     return aligned;
   }
   async batchRead(keys, action, options) {
+    if (this.readThroughReady !== null) await this.readThroughReady;
     if (!this.requireAuth()) return err(authRequiredError("kv"));
     if (keys.length === 0) return ok({ results: [], count: 0 });
     if (keys.length > MAX_KV_BATCH_READ_ITEMS) {
@@ -1373,6 +1399,7 @@ var KVService = class extends BaseService {
    */
   async get(key, options) {
     return this.withTelemetry("get", key, async () => {
+      if (this.readThroughReady !== null) await this.readThroughReady;
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
@@ -1386,64 +1413,38 @@ var KVService = class extends BaseService {
       const path = this.getFullPath(key, options?.prefix);
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const response = await this.invokeOperation(
-          path,
-          KVAction.GET,
-          void 0,
-          request.signal,
-          options?.maxResponseBytes === void 0 ? void 0 : { "x-tinycloud-max-response-bytes": String(options.maxResponseBytes) }
-        );
-        if (!response.ok) {
-          if (response.status === 401 || response.status === 403) {
-            const errorText2 = await this.readAuthorizationText(response);
-            const permissionHint = parsePermissionHintFromErrorText(errorText2);
-            const structuredCapability = permissionHint?.service === "tinycloud.kv" && permissionHint.space === this.context.session.spaceId && permissionHint.path === path ? validatedCapabilityOf({
-              service: "kv",
-              code: ErrorCodes.AUTH_UNAUTHORIZED,
-              meta: {
-                status: response.status,
-                resource: `${this.context.session.spaceId}/kv/${path}`,
-                requiredAction: KVAction.GET
-              }
-            }) : void 0;
-            return this.authorizationFailure(
-              `Failed to get key ${JSON.stringify(key)}`,
-              response,
-              errorText2,
-              [path],
-              KVAction.GET,
-              structuredCapability ? { permissionHint, ...structuredCapability } : {}
-            );
-          }
-          if (response.status === 404) {
-            return await this.classifyNotFound(response, key);
-          }
-          const errorText = await response.text();
-          if (response.status === 413) {
-            return err(serviceError(
-              ErrorCodes.KV_RESPONSE_TOO_LARGE,
-              `KV value at key ${JSON.stringify(key)} exceeds the requested response limit`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            ));
+        const network = () => this.getFromNetwork(key, path, options, request.signal);
+        if (options?.source === "network") {
+          const observer = this.readThrough;
+          if (observer === null) return await network();
+          let outcome = "error";
+          const startedAt = Date.now();
+          try {
+            const result = await network();
+            outcome = result.ok ? "found" : result.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error";
+            return result;
+          } finally {
+            try {
+              observer.observeNetworkRequested({
+                op: "get",
+                space: this.context.session.spaceId,
+                path,
+                reason: "NETWORK_REQUESTED",
+                outcome,
+                latencyMs: Date.now() - startedAt
+              });
+            } catch {
+            }
           }
-          return err(
-            serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            )
-          );
         }
-        const data = await this.parseResponse(
-          response,
-          options?.raw,
-          options?.binary
-        );
-        return ok({
-          data,
-          headers: this.createResponseHeaders(response.headers)
+        if (this.readThrough === null) return await network();
+        return await this.readThrough.get({
+          space: this.context.session.spaceId,
+          key,
+          path,
+          options,
+          signal: request.signal,
+          network
         });
       } catch (error) {
         return err(wrapError("kv", error));
@@ -1452,6 +1453,56 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async getFromNetwork(key, path, options, signal) {
+    const response = await this.invokeOperation(
+      path,
+      KVAction.GET,
+      void 0,
+      signal,
+      options?.maxResponseBytes === void 0 ? void 0 : { "x-tinycloud-max-response-bytes": String(options.maxResponseBytes) }
+    );
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        const errorText2 = await this.readAuthorizationText(response);
+        const permissionHint = parsePermissionHintFromErrorText(errorText2);
+        const structuredCapability = permissionHint?.service === "tinycloud.kv" && permissionHint.space === this.context.session.spaceId && permissionHint.path === path ? validatedCapabilityOf({
+          service: "kv",
+          code: ErrorCodes.AUTH_UNAUTHORIZED,
+          meta: {
+            status: response.status,
+            resource: `${this.context.session.spaceId}/kv/${path}`,
+            requiredAction: KVAction.GET
+          }
+        }) : void 0;
+        return this.authorizationFailure(
+          `Failed to get key ${JSON.stringify(key)}`,
+          response,
+          errorText2,
+          [path],
+          KVAction.GET,
+          structuredCapability ? { permissionHint, ...structuredCapability } : {}
+        );
+      }
+      if (response.status === 404) return this.classifyNotFound(response, key);
+      const errorText = await response.text();
+      if (response.status === 413) {
+        return err(serviceError(
+          ErrorCodes.KV_RESPONSE_TOO_LARGE,
+          `KV value at key ${JSON.stringify(key)} exceeds the requested response limit`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      return err(serviceError(
+        ErrorCodes.NETWORK_ERROR,
+        `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      ));
+    }
+    const data = await this.parseResponse(response, options?.raw, options?.binary);
+    return ok({ data, headers: this.createResponseHeaders(response.headers) });
+  }
   async batchGet(keys, options) {
     return this.withTelemetry(
       "batchGet",
@@ -1464,6 +1515,7 @@ var KVService = class extends BaseService {
    */
   async put(key, value, options) {
     return this.withTelemetry("put", key, async () => {
+      if (this.readThroughReady !== null) await this.readThroughReady;
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
@@ -1478,63 +1530,15 @@ var KVService = class extends BaseService {
       const body = this.serializePutValue(value, options?.contentType);
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const response = await this.invokeOperation(
-          path,
-          KVAction.PUT,
-          body,
-          request.signal,
-          {
-            ...options?.ifMatch === void 0 ? {} : { "if-match": options.ifMatch },
-            ...options?.ifNoneMatch === void 0 ? {} : { "if-none-match": options.ifNoneMatch }
-          }
-        );
-        if (response.status === 401 || response.status === 403) {
-          return this.authorizationFailure(
-            `Failed to put key ${JSON.stringify(key)}`,
-            response,
-            await this.readAuthorizationText(response),
-            [path],
-            KVAction.PUT
-          );
-        }
-        if (!response.ok) {
-          const errorText = await response.text();
-          if (response.status === 412) {
-            return err(serviceError(
-              ErrorCodes.KV_PRECONDITION_FAILED,
-              `KV precondition failed for key ${JSON.stringify(key)}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            ));
-          }
-          if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
-            return err(serviceError(
-              ErrorCodes.KV_CONFLICT,
-              `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            ));
-          }
-          const quotaError = this.handleQuotaErrorResponse(
-            response,
-            errorText,
-            key
-          );
-          if (quotaError) {
-            return quotaError;
-          }
-          return err(
-            serviceError(
-              ErrorCodes.KV_WRITE_FAILED,
-              `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            )
-          );
-        }
-        return ok({
-          data: void 0,
-          headers: this.createResponseHeaders(response.headers)
+        const network = () => this.putToNetwork(key, path, body, options, request.signal);
+        if (this.readThrough === null) return await network();
+        return await this.readThrough.write({
+          op: "put",
+          space: this.context.session.spaceId,
+          entries: [{ path, body }],
+          signal: request.signal,
+          conditional: options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0,
+          network
         });
       } catch (error) {
         return err(wrapError("kv", error));
@@ -1543,11 +1547,64 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async putToNetwork(key, path, body, options, signal) {
+    const response = await this.invokeOperation(
+      path,
+      KVAction.PUT,
+      body,
+      signal,
+      {
+        ...options?.ifMatch === void 0 ? {} : { "if-match": options.ifMatch },
+        ...options?.ifNoneMatch === void 0 ? {} : { "if-none-match": options.ifNoneMatch }
+      }
+    );
+    if (response.status === 401 || response.status === 403) {
+      return this.authorizationFailure(
+        `Failed to put key ${JSON.stringify(key)}`,
+        response,
+        await this.readAuthorizationText(response),
+        [path],
+        KVAction.PUT
+      );
+    }
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 412) {
+        return err(serviceError(
+          ErrorCodes.KV_PRECONDITION_FAILED,
+          `KV precondition failed for key ${JSON.stringify(key)}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
+        return err(serviceError(
+          ErrorCodes.KV_CONFLICT,
+          `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      const quotaError = this.handleQuotaErrorResponse(response, errorText, key);
+      if (quotaError) return quotaError;
+      return err(serviceError(
+        ErrorCodes.KV_WRITE_FAILED,
+        `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      ));
+    }
+    return ok({
+      data: void 0,
+      headers: this.createResponseHeaders(response.headers)
+    });
+  }
   /**
    * Store multiple values in one TinyCloud KV invocation.
    */
   async batchPut(items, options) {
     return this.withTelemetry("batchPut", String(items.length), async () => {
+      if (this.readThroughReady !== null) await this.readThroughReady;
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
@@ -1578,155 +1635,177 @@ var KVService = class extends BaseService {
         }
         seen.add(path);
       }
-      let requestMayHaveDispatched = false;
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const body = new FormData();
-        for (let index = 0; index < items.length; index++) {
-          body.append(
-            encodeKvBatchPartName(paths[index]),
-            this.serializeBatchPutValue(items[index])
-          );
-        }
-        const headers = this.context.invokeAny(
-          session,
-          paths.map((path) => ({
-            spaceId: session.spaceId,
-            service: "kv",
-            path,
-            action: KVAction.PUT
-          }))
+        const network = () => this.batchPutToNetwork(items, paths, request.signal);
+        if (this.readThrough === null) return await network();
+        const entries = items.map((item, index) => ({
+          path: paths[index],
+          body: this.serializeBatchPutValue(item)
+        }));
+        return await this.readThrough.write({
+          op: "batchPut",
+          space: session.spaceId,
+          entries,
+          signal: request.signal,
+          network: () => this.batchPutToNetwork(items, paths, request.signal, entries)
+        });
+      } catch (error) {
+        const wrapped = wrapError("kv", error);
+        return err({ ...wrapped, meta: { ...wrapped.meta, requestMayHaveDispatched: false } });
+      } finally {
+        request.dispose();
+      }
+    });
+  }
+  async batchPutToNetwork(items, paths, signal, entries) {
+    const session = this.context.session;
+    let requestMayHaveDispatched = false;
+    try {
+      const body = new FormData();
+      for (let index = 0; index < items.length; index++) {
+        body.append(
+          encodeKvBatchPartName(paths[index]),
+          entries?.[index]?.body ?? this.serializeBatchPutValue(items[index])
         );
-        const url = `${this.host}/invoke`;
-        const init = {
-          method: "POST",
-          headers,
-          body,
-          signal: request.signal
-        };
-        const fetchFn = this.context.fetch;
-        requestMayHaveDispatched = true;
-        const response = await fetchFn(url, init);
-        if (!response.ok) {
-          let errorText;
-          try {
-            errorText = await response.text();
-          } catch (textError) {
-            const cause = textError instanceof Error ? textError : new Error(String(textError));
-            return err(
-              serviceError(
-                ErrorCodes.KV_WRITE_FAILED,
-                `Failed to batch put ${items.length} key(s): ${response.status} - <response body could not be read: ${cause.message}>`,
-                "kv",
-                { cause, meta: { status: response.status, statusText: response.statusText } }
-              )
-            );
-          }
-          if (response.status === 401 || response.status === 403) {
-            return this.authorizationFailure(
-              `Failed to batch put ${items.length} key(s)`,
-              response,
-              errorText,
-              paths,
-              KVAction.PUT
-            );
-          }
-          const quotaError = this.handleQuotaErrorResponse(
-            response,
-            errorText,
-            "batch"
-          );
-          if (quotaError) {
-            return quotaError;
-          }
+      }
+      const headers = this.context.invokeAny(
+        session,
+        paths.map((path) => ({
+          spaceId: session.spaceId,
+          service: "kv",
+          path,
+          action: KVAction.PUT
+        }))
+      );
+      const url = `${this.host}/invoke`;
+      const init = {
+        method: "POST",
+        headers,
+        body,
+        signal
+      };
+      const fetchFn = this.context.fetch;
+      requestMayHaveDispatched = true;
+      const response = await fetchFn(url, init);
+      if (!response.ok) {
+        let errorText;
+        try {
+          errorText = await response.text();
+        } catch (textError) {
+          const cause = textError instanceof Error ? textError : new Error(String(textError));
           return err(
             serviceError(
               ErrorCodes.KV_WRITE_FAILED,
-              `Failed to batch put ${items.length} key(s): ${response.status} - ${errorText}`,
+              `Failed to batch put ${items.length} key(s): ${response.status} - <response body could not be read: ${cause.message}>`,
               "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
+              { cause, meta: { status: response.status, statusText: response.statusText } }
             )
           );
         }
-        let rawBody;
-        try {
-          rawBody = await response.json();
-        } catch (jsonError) {
-          const cause = jsonError instanceof Error ? jsonError : new Error(String(jsonError));
-          const timedOut = isRequestTimeoutError(cause);
-          return err(
-            serviceError(
-              timedOut ? ErrorCodes.TIMEOUT : ErrorCodes.NETWORK_ERROR,
-              timedOut ? `KV batchPut response body did not arrive in time: ${cause.message}` : `KV batchPut response was not valid JSON: ${cause.message}`,
-              "kv",
-              {
-                cause,
-                meta: {
-                  ...timedOut ? { timeoutMs: cause.timeoutMs } : {},
-                  requestMayHaveDispatched: true,
-                  responseReceived: true,
-                  status: response.status,
-                  outcome: "batch-unconfirmed"
-                }
-              }
-            )
+        if (response.status === 401 || response.status === 403) {
+          return this.authorizationFailure(
+            `Failed to batch put ${items.length} key(s)`,
+            response,
+            errorText,
+            paths,
+            KVAction.PUT
           );
         }
-        const batchResponse = this.normalizeBatchPutResponse(rawBody);
-        if (!batchResponse) {
-          return err(
-            serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              "KV batchPut response did not include matching written keys and count",
-              "kv",
-              {
-                meta: {
-                  requestMayHaveDispatched: true,
-                  responseReceived: true,
-                  status: response.status,
-                  outcome: "batch-unconfirmed"
-                }
-              }
-            )
-          );
+        const quotaError = this.handleQuotaErrorResponse(
+          response,
+          errorText,
+          "batch"
+        );
+        if (quotaError) {
+          return quotaError;
         }
-        const requestedPaths = new Set(paths);
-        const writtenPaths = new Set(batchResponse.written);
-        const matchesRequest = batchResponse.count === paths.length && batchResponse.written.length === paths.length && writtenPaths.size === paths.length && batchResponse.written.every((key) => requestedPaths.has(key));
-        if (!matchesRequest) {
-          return err(
-            serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              `KV batchPut response did not confirm all ${paths.length} requested key(s) were written`,
-              "kv",
-              {
-                meta: {
-                  requestMayHaveDispatched: true,
-                  responseReceived: true,
-                  status: response.status,
-                  outcome: "batch-unconfirmed"
-                }
+        return err(
+          serviceError(
+            ErrorCodes.KV_WRITE_FAILED,
+            `Failed to batch put ${items.length} key(s): ${response.status} - ${errorText}`,
+            "kv",
+            { meta: { status: response.status, statusText: response.statusText } }
+          )
+        );
+      }
+      let rawBody;
+      try {
+        rawBody = await response.json();
+      } catch (jsonError) {
+        const cause = jsonError instanceof Error ? jsonError : new Error(String(jsonError));
+        const timedOut = isRequestTimeoutError(cause);
+        return err(
+          serviceError(
+            timedOut ? ErrorCodes.TIMEOUT : ErrorCodes.NETWORK_ERROR,
+            timedOut ? `KV batchPut response body did not arrive in time: ${cause.message}` : `KV batchPut response was not valid JSON: ${cause.message}`,
+            "kv",
+            {
+              cause,
+              meta: {
+                ...timedOut ? { timeoutMs: cause.timeoutMs } : {},
+                requestMayHaveDispatched: true,
+                responseReceived: true,
+                status: response.status,
+                outcome: "batch-unconfirmed"
               }
-            )
-          );
-        }
-        return ok(batchResponse);
-      } catch (error) {
-        const wrapped = wrapError("kv", error);
-        return err({
-          ...wrapped,
-          meta: { ...wrapped.meta, requestMayHaveDispatched }
-        });
-      } finally {
-        request.dispose();
+            }
+          )
+        );
       }
-    });
+      const batchResponse = this.normalizeBatchPutResponse(rawBody);
+      if (!batchResponse) {
+        return err(
+          serviceError(
+            ErrorCodes.NETWORK_ERROR,
+            "KV batchPut response did not include matching written keys and count",
+            "kv",
+            {
+              meta: {
+                requestMayHaveDispatched: true,
+                responseReceived: true,
+                status: response.status,
+                outcome: "batch-unconfirmed"
+              }
+            }
+          )
+        );
+      }
+      const requestedPaths = new Set(paths);
+      const writtenPaths = new Set(batchResponse.written);
+      const matchesRequest = batchResponse.count === paths.length && batchResponse.written.length === paths.length && writtenPaths.size === paths.length && batchResponse.written.every((key) => requestedPaths.has(key));
+      if (!matchesRequest) {
+        return err(
+          serviceError(
+            ErrorCodes.NETWORK_ERROR,
+            `KV batchPut response did not confirm all ${paths.length} requested key(s) were written`,
+            "kv",
+            {
+              meta: {
+                requestMayHaveDispatched: true,
+                responseReceived: true,
+                status: response.status,
+                outcome: "batch-unconfirmed"
+              }
+            }
+          )
+        );
+      }
+      return ok(batchResponse);
+    } catch (error) {
+      const wrapped = wrapError("kv", error);
+      return err({
+        ...wrapped,
+        meta: { ...wrapped.meta, requestMayHaveDispatched }
+      });
+    }
   }
   /**
    * List keys with optional prefix filtering.
    */
   async list(options) {
     return this.withTelemetry("list", options?.prefix, async () => {
+      if (this.readThroughReady !== null) await this.readThroughReady;
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
@@ -1743,49 +1822,44 @@ var KVService = class extends BaseService {
       }
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const response = await this.invokeOperation(
-          listPath,
-          KVAction.LIST,
-          void 0,
-          request.signal,
-          options?.limit === void 0 && options?.cursor === void 0 ? void 0 : {
-            ...options?.limit === void 0 ? {} : { "x-tinycloud-limit": String(options.limit) },
-            ...options?.cursor === void 0 ? {} : { "x-tinycloud-cursor": options.cursor }
-          }
-        );
-        if (!response.ok) {
-          if (response.status === 401 || response.status === 403) {
-            return this.authorizationFailure(
-              "Failed to list keys",
-              response,
-              await this.readAuthorizationText(response),
-              [listPath],
-              KVAction.LIST
-            );
+        const network = () => this.listFromNetwork(listPath, options, request.signal);
+        let page;
+        if (options?.source === "network") {
+          const observer = this.readThrough;
+          if (observer === null) {
+            page = await network();
+          } else {
+            let outcome = "error";
+            const startedAt = Date.now();
+            try {
+              page = await network();
+              outcome = page.ok ? "found" : "error";
+            } finally {
+              try {
+                observer.observeNetworkRequested({
+                  op: "list",
+                  space: this.context.session.spaceId,
+                  path: listPath,
+                  reason: "NETWORK_REQUESTED",
+                  outcome,
+                  latencyMs: Date.now() - startedAt
+                });
+              } catch {
+              }
+            }
           }
-          const errorText = await response.text();
-          return err(
-            serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              `Failed to list keys: ${response.status} - ${errorText}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            )
-          );
-        }
-        let keys = await this.parseResponse(response, options?.raw);
-        keys = keys ?? [];
-        if (options?.removePrefix && listPath) {
-          const prefixWithSlash = listPath.endsWith("/") ? listPath : `${listPath}/`;
-          keys = keys.map(
-            (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
-          );
+        } else if (this.readThrough === null) {
+          page = await network();
+        } else {
+          page = await this.readThrough.list({
+            space: this.context.session.spaceId,
+            listPath,
+            options,
+            signal: request.signal,
+            network
+          });
         }
-        return ok({
-          keys,
-          ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" },
-          ...response.headers.get("x-tinycloud-next-cursor") === null ? {} : { nextCursor: response.headers.get("x-tinycloud-next-cursor") ?? void 0 }
-        });
+        return page.ok ? this.finishList(page.data, listPath, options?.removePrefix) : page;
       } catch (error) {
         return err(wrapError("kv", error));
       } finally {
@@ -1793,6 +1867,56 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async listFromNetwork(listPath, options, signal) {
+    const response = await this.invokeOperation(
+      listPath,
+      KVAction.LIST,
+      void 0,
+      signal,
+      options?.limit === void 0 && options?.cursor === void 0 ? void 0 : {
+        ...options?.limit === void 0 ? {} : { "x-tinycloud-limit": String(options.limit) },
+        ...options?.cursor === void 0 ? {} : { "x-tinycloud-cursor": options.cursor }
+      }
+    );
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        return this.authorizationFailure(
+          "Failed to list keys",
+          response,
+          await this.readAuthorizationText(response),
+          [listPath],
+          KVAction.LIST
+        );
+      }
+      const errorText = await response.text();
+      return err(serviceError(
+        ErrorCodes.NETWORK_ERROR,
+        `Failed to list keys: ${response.status} - ${errorText}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      ));
+    }
+    const keys = await this.parseResponse(response, options?.raw) ?? [];
+    return ok({
+      keys,
+      ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" },
+      ...response.headers.get("x-tinycloud-next-cursor") === null ? {} : { nextCursor: response.headers.get("x-tinycloud-next-cursor") ?? void 0 }
+    });
+  }
+  finishList(page, listPath, removePrefix) {
+    let keys = page.keys;
+    if (removePrefix && listPath) {
+      const prefixWithSlash = listPath.endsWith("/") ? listPath : `${listPath}/`;
+      keys = keys.map(
+        (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
+      );
+    }
+    return ok({
+      keys,
+      ...page.truncated === void 0 ? {} : { truncated: page.truncated },
+      ...page.nextCursor === void 0 ? {} : { nextCursor: page.nextCursor }
+    });
+  }
   /**
    * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
    */
@@ -1815,6 +1939,7 @@ var KVService = class extends BaseService {
           "kv"
         ));
       }
+      const requestPrefix = options.prefix === "/" ? "" : options.prefix;
       const headers = {};
       if (options.limit !== void 0) headers["x-tinycloud-limit"] = String(options.limit);
       if (options.cursor !== void 0) headers["x-tinycloud-cursor"] = options.cursor;
@@ -1824,7 +1949,7 @@ var KVService = class extends BaseService {
       const request = this.createRequestSignal(options.signal, options.timeout);
       try {
         const response = await this.invokeOperation(
-          options.prefix,
+          requestPrefix,
           KVAction.SYNC,
           void 0,
           request.signal,
@@ -1840,7 +1965,7 @@ var KVService = class extends BaseService {
         } catch {
           body = void 0;
         }
-        const page = this.normalizeChangesResponse(body);
+        const page = this.normalizeChangesResponse(body, options.prefix);
         if (!page) {
           return err(serviceError(
             ErrorCodes.NETWORK_ERROR,
@@ -1920,7 +2045,7 @@ var KVService = class extends BaseService {
       { meta }
     ));
   }
-  normalizeChangesResponse(data) {
+  normalizeChangesResponse(data, requestedPrefix) {
     if (!isJsonObject(data)) return void 0;
     const { changes, more, cursor, source, authority } = data;
     if (!Array.isArray(changes) || typeof more !== "boolean" || typeof cursor !== "string" || !isJsonObject(source) || typeof source.nodeDid !== "string" || typeof source.space !== "string" || typeof source.prefix !== "string" || !isJsonObject(authority)) {
@@ -1952,7 +2077,11 @@ var KVService = class extends BaseService {
       changes: parsed,
       more,
       cursor,
-      source: { nodeDid: source.nodeDid, space: source.space, prefix: source.prefix },
+      source: {
+        nodeDid: source.nodeDid,
+        space: source.space,
+        prefix: requestedPrefix === "/" && source.prefix === "" ? "/" : source.prefix
+      },
       authority: { notBefore, expiresAt, retainUntil }
     };
   }
@@ -1961,61 +2090,22 @@ var KVService = class extends BaseService {
    */
   async delete(key, options) {
     return this.withTelemetry("delete", key, async () => {
+      if (this.readThroughReady !== null) await this.readThroughReady;
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
       const path = this.getFullPath(key, options?.prefix);
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const response = await this.invokeOperation(
-          path,
-          KVAction.DELETE,
-          void 0,
-          request.signal,
-          options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
-        );
-        if (!response.ok) {
-          if (response.status === 401 || response.status === 403) {
-            return this.authorizationFailure(
-              `Failed to delete key ${JSON.stringify(key)}`,
-              response,
-              await this.readAuthorizationText(response),
-              [path],
-              KVAction.DELETE
-            );
-          }
-          if (response.status === 404) {
-            return await this.classifyNotFound(response, key);
-          }
-          const errorText = await response.text();
-          if (response.status === 412) {
-            return err(serviceError(
-              ErrorCodes.KV_PRECONDITION_FAILED,
-              `KV precondition failed for key ${JSON.stringify(key)}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            ));
-          }
-          if (response.status === 503 && options?.ifMatch !== void 0) {
-            return err(serviceError(
-              ErrorCodes.KV_CONFLICT,
-              `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            ));
-          }
-          return err(
-            serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
-              "kv",
-              { meta: { status: response.status, statusText: response.statusText } }
-            )
-          );
-        }
-        return ok({
-          data: void 0,
-          headers: this.createResponseHeaders(response.headers)
+        const network = () => this.deleteFromNetwork(key, path, options, request.signal);
+        if (this.readThrough === null) return await network();
+        return await this.readThrough.write({
+          op: "delete",
+          space: this.context.session.spaceId,
+          entries: [{ path }],
+          signal: request.signal,
+          conditional: options?.ifMatch !== void 0,
+          network
         });
       } catch (error) {
         return err(wrapError("kv", error));
@@ -2024,6 +2114,54 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async deleteFromNetwork(key, path, options, signal) {
+    const response = await this.invokeOperation(
+      path,
+      KVAction.DELETE,
+      void 0,
+      signal,
+      options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
+    );
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        return this.authorizationFailure(
+          `Failed to delete key ${JSON.stringify(key)}`,
+          response,
+          await this.readAuthorizationText(response),
+          [path],
+          KVAction.DELETE
+        );
+      }
+      if (response.status === 404) return this.classifyNotFound(response, key);
+      const errorText = await response.text();
+      if (response.status === 412) {
+        return err(serviceError(
+          ErrorCodes.KV_PRECONDITION_FAILED,
+          `KV precondition failed for key ${JSON.stringify(key)}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      if (response.status === 503 && options?.ifMatch !== void 0) {
+        return err(serviceError(
+          ErrorCodes.KV_CONFLICT,
+          `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      return err(serviceError(
+        ErrorCodes.NETWORK_ERROR,
+        `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      ));
+    }
+    return ok({
+      data: void 0,
+      headers: this.createResponseHeaders(response.headers)
+    });
+  }
   /**
    * Get metadata for a key without retrieving the value.
    */
@@ -2190,11 +2328,75 @@ var KVService = class extends BaseService {
  * Service identifier for registration.
  */
 KVService.serviceName = "kv";
+
+// src/kv/replication/constants.ts
+var CLEAR_PENDING_WARNING = "Clearing pending writes surrenders read-your-writes protection for the cleared keys. If a write whose record was cleared had an unknown outcome or never finished, it may commit now or later; this device can serve an older value until the next sync after that commit, as it would for a write from another device.";
+
+// src/kv/replication/identity.ts
+var SPACE_ID = /^(tinycloud:pkh:eip155:\d+:)([^:]+)(:.+)$/;
+var PRINCIPAL_DID = /^(did:pkh:eip155:\d+:)([^:]+)$/;
+function canonicalReplicationIdentity(raw) {
+  if (!raw || typeof raw.host !== "string" || typeof raw.space !== "string" || typeof raw.principal !== "string") {
+    throw new TypeError(
+      "Replication identity host, space, and principal must be strings"
+    );
+  }
+  const authority = /^https?:\/\/([^/?#]*)/i.exec(raw.host)?.[1];
+  let url;
+  try {
+    url = new URL(raw.host);
+  } catch {
+    throw new TypeError(
+      "Replication identity host must be an absolute HTTP(S) URL"
+    );
+  }
+  if (!authority || authority.includes("@") || raw.host.includes("?") || raw.host.includes("#") || url.username || url.password) {
+    throw new TypeError(
+      "Replication identity host must be HTTP(S) without credentials, query, or fragment"
+    );
+  }
+  const space = SPACE_ID.exec(raw.space);
+  const principal = PRINCIPAL_DID.exec(raw.principal);
+  if (!space || !principal) {
+    throw new TypeError(
+      "Replication identity requires a full TinyCloud space id and a pkh principal DID"
+    );
+  }
+  return {
+    host: `${url.origin}${url.pathname.replace(/\/+$/, "")}`,
+    space: `${space[1]}${space[2].toLowerCase()}${space[3]}`,
+    principal: `${principal[1]}${principal[2].toLowerCase()}`
+  };
+}
+function replicationIdentityKey(id) {
+  const canonical = canonicalReplicationIdentity(id);
+  return `tc-replication/v1
+${canonical.host}
+${canonical.space}
+${canonical.principal}`;
+}
+
+// src/kv/replication/prefix.ts
+function kvPrefixCovers(prefix, key) {
+  return prefix === "/" || key.startsWith(prefix);
+}
+
+// src/kv/replication/scope.ts
+function requiresSecretsOptIn(space, prefix) {
+  if (prefix === "/") return true;
+  if (space === "secrets" || space.endsWith(":secrets")) return true;
+  return prefix.split("/", 1)[0] === "vault";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CLEAR_PENDING_WARNING,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   KVAction,
   KVService,
-  PrefixedKVService
+  PrefixedKVService,
+  canonicalReplicationIdentity,
+  kvPrefixCovers,
+  replicationIdentityKey,
+  requiresSecretsOptIn
 });
 //# sourceMappingURL=index.cjs.map