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

package/dist/index.js

@@ -60,7 +60,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 };
@@ -86,9 +91,34 @@ var SAFE_NUMBER_FIELDS = /* @__PURE__ */ new Set([
   "endedAt",
   "startedAt",
   "status",
-  "timestamp"
+  "timestamp",
+  "latencyMs",
+  "stalenessMs",
+  "count",
+  "changes",
+  "deleted",
+  "fetched",
+  "pages",
+  "lagMs",
+  "pendingCleared"
 ]);
 var SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted"]);
+var SAFE_REPLICATION_FIELDS = {
+  source: ["replica", "network", "none"],
+  reason: ["hit", "absent", "deleted", "content_missing", "coverage_incomplete", "not_covered", "pending_write", "grant_missing", "grant_expired", "grant_revoked", "grant_not_yet_valid", "stale", "replica_error", "runtime_unsupported", "replica_unavailable", "unsupported_option", "network_cursor", "cursor_restart", "aborted", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED"],
+  op: ["get", "list", "put", "delete", "batchPut"],
+  trigger: ["start", "interval", "stale_read", "manual"],
+  outcome: ["found", "not_found", "error", "committed", "failed", "ambiguous", "ok", "busy", "aborted"],
+  class: ["offline", "authority", "storage", "node"],
+  state: ["opened", "grant_installed", "grant_missing", "runtime_unsupported", "unavailable", "revoked", "recreated", "purged", "purge_failed", "pending_store_error", "pinned", "pending_cleared", "closed", "idle", "ready"],
+  kind: ["value", "missing_local", "extra_local", "keys", "order"],
+  coverage: ["empty", "bootstrapping", "complete"],
+  authority: ["valid", "expired", "revoked", "not-yet-valid"],
+  code: ["NETWORK_ERROR", "TIMEOUT", "ABORTED", "REPLICA_BUSY", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "INTEGRITY_ERROR", "STORAGE_ERROR", "REPLICA_CLOSED", "RUNTIME_UNSUPPORTED", "GRANT_EXPIRED", "GRANT_REVOKED", "GRANT_NOT_YET_VALID", "GRANT_MISSING", "GRANT_INVALID", "SOURCE_CHANGED", "PROTOCOL_ERROR", "SCOPE_VIOLATION", "NODE_ERROR", "CONTENT_MISMATCH", "STORAGE_FULL"],
+  pendingState: ["in_flight", "committed", "ambiguous"],
+  strategy: ["session", "minted", "installed"],
+  verify: ["match", "diverged", "error", "aborted"]
+};
 function finiteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
@@ -125,6 +155,12 @@ function projectDiagnosticData(value) {
       const boolean = read(value, key);
       if (typeof boolean === "boolean") projected[key] = boolean;
     }
+    for (const [key, allowed] of Object.entries(SAFE_REPLICATION_FIELDS)) {
+      const candidate = read(value, key);
+      if (typeof candidate === "string" && allowed.includes(candidate)) {
+        projected[key] = candidate;
+      }
+    }
     const url = read(value, "url");
     if (url !== void 0) projected.url = REDACTED;
     const error = read(value, "error");
@@ -749,6 +785,12 @@ var ServiceContext = class {
   get abortSignal() {
     return this._abortController.signal;
   }
+  get operationAbortSignal() {
+    return this._operationAbortSignal;
+  }
+  setOperationAbortSignal(signal) {
+    this._operationAbortSignal = signal;
+  }
   /**
    * Permanently retire this graph after its owner installs a replacement.
    * Unlike `abort()`, retirement never creates a fresh controller, so captured
@@ -1500,6 +1542,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) {
@@ -1745,14 +1788,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;
@@ -2006,6 +2063,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) {
@@ -2256,6 +2314,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"));
       }
@@ -2269,64 +2328,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));
@@ -2335,6 +2368,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",
@@ -2347,6 +2430,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"));
       }
@@ -2361,63 +2445,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));
@@ -2426,11 +2462,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"));
       }
@@ -2461,155 +2550,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"));
       }
@@ -2626,49 +2737,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 {
@@ -2676,6 +2782,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.
    */
@@ -2698,6 +2854,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;
@@ -2707,7 +2864,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,
@@ -2723,7 +2880,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,
@@ -2803,7 +2960,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)) {
@@ -2835,7 +2992,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 }
     };
   }
@@ -2844,61 +3005,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));
@@ -2907,6 +3029,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.
    */
@@ -3074,6 +3244,65 @@ var KVService = class extends BaseService {
  */
 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";
+}
+
 // src/responseErrors.ts
 function parseServiceErrorBody(errorText) {
   try {
@@ -3250,7 +3479,7 @@ var SQLService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "query", dbName, [action]);
+          return await this.handleErrorResponse(response, "query", dbName, [action]);
         }
         const data = await response.json();
         return ok(data);
@@ -3290,7 +3519,7 @@ var SQLService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "execute", dbName, requestedActions);
+          return await this.handleErrorResponse(response, "execute", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
@@ -3316,7 +3545,7 @@ var SQLService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "batch", dbName, requestedActions);
+          return await this.handleErrorResponse(response, "batch", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
@@ -3341,7 +3570,7 @@ var SQLService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "executeStatement", dbName, [SQLAction.WRITE]);
+          return await this.handleErrorResponse(response, "executeStatement", dbName, [SQLAction.WRITE]);
         }
         const data = await response.json();
         return ok(data);
@@ -3366,7 +3595,7 @@ var SQLService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "export", dbName, [SQLAction.READ]);
+          return await this.handleErrorResponse(response, "export", dbName, [SQLAction.READ]);
         }
         const resp = response;
         if (typeof resp.blob === "function") {
@@ -3742,7 +3971,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "query");
+          return await this.handleErrorResponse(response, "query");
         }
         const data = await response.json();
         return ok(data);
@@ -3768,7 +3997,7 @@ var DuckDbService = class extends BaseService {
           { Accept: "application/vnd.apache.arrow.stream" }
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "queryArrow");
+          return await this.handleErrorResponse(response, "queryArrow");
         }
         const buffer = await response.arrayBuffer();
         return ok(buffer);
@@ -3801,7 +4030,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "execute");
+          return await this.handleErrorResponse(response, "execute");
         }
         const data = await response.json();
         return ok(data);
@@ -3833,7 +4062,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "batch");
+          return await this.handleErrorResponse(response, "batch");
         }
         const data = await response.json();
         return ok(data);
@@ -3858,7 +4087,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "executeStatement");
+          return await this.handleErrorResponse(response, "executeStatement");
         }
         const data = await response.json();
         return ok(data);
@@ -3883,7 +4112,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "describe");
+          return await this.handleErrorResponse(response, "describe");
         }
         const data = await response.json();
         return ok(data);
@@ -3908,7 +4137,7 @@ var DuckDbService = class extends BaseService {
           request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "export");
+          return await this.handleErrorResponse(response, "export");
         }
         const blob = await response.blob();
         return ok(blob);
@@ -3943,7 +4172,7 @@ var DuckDbService = class extends BaseService {
           signal: request.signal
         });
         if (!response.ok) {
-          return this.handleErrorResponse(response, "import");
+          return await this.handleErrorResponse(response, "import");
         }
         return ok(void 0);
       } catch (error) {
@@ -5655,7 +5884,8 @@ var DataVaultService = class extends BaseService {
     }
     try {
       const valueResult = await this.tc.kv.get(`vault/${key}`, {
-        raw: true
+        raw: true,
+        ...options?.source === void 0 ? {} : { source: options.source }
       });
       if (!valueResult.ok) {
         return vaultError({ code: "KEY_NOT_FOUND", key });
@@ -5700,7 +5930,7 @@ var DataVaultService = class extends BaseService {
     }
     let valueResult;
     try {
-      valueResult = await this.tc.kv.get(`vault/${key}`, { raw: true });
+      valueResult = await this.tc.kv.get(`vault/${key}`, { raw: true, source: "network" });
     } catch {
       return { status: "node_unreachable" };
     }
@@ -5769,7 +5999,8 @@ var DataVaultService = class extends BaseService {
     }
     try {
       const valueResult = await this.tc.kv.get(`vault/${key}`, {
-        raw: true
+        raw: true,
+        source: "network"
       });
       if (!valueResult.ok) {
         return vaultError({ code: "KEY_NOT_FOUND", key });
@@ -5903,7 +6134,8 @@ var DataVaultService = class extends BaseService {
       }
       try {
         const keyResult = await this.tc.kv.get(`keys/${key}`, {
-          raw: true
+          raw: true,
+          ...options?.source === void 0 ? {} : { source: options.source }
         });
         if (!keyResult.ok) {
           return vaultError({ code: "KEY_NOT_FOUND", key });
@@ -5912,7 +6144,8 @@ var DataVaultService = class extends BaseService {
         const keyBlobBytes = base64Decode(keyEnvelope.key);
         const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
         const valueResult = await this.tc.kv.get(`vault/${key}`, {
-          raw: true
+          raw: true,
+          ...options?.source === void 0 ? {} : { source: options.source }
         });
         if (!valueResult.ok) {
           return vaultError({ code: "KEY_NOT_FOUND", key });
@@ -6022,6 +6255,7 @@ var DataVaultService = class extends BaseService {
           prefix: listPrefix,
           removePrefix: true,
           ...options?.limit === void 0 ? {} : { limit: options.limit },
+          ...options?.source === void 0 ? {} : { source: options.source },
           ...options?.cursor === void 0 ? {} : { cursor: options.cursor }
         });
         if (!listResult.ok) {
@@ -6746,7 +6980,9 @@ var SecretsService = class {
   async get(name, options) {
     const secretPath = resolveSecretPathResult(name, options);
     if ("ok" in secretPath) return secretPath;
-    const result = await this.vault.get(secretPath.vaultKey);
+    const result = options?.source === void 0 ? await this.vault.get(secretPath.vaultKey) : await this.vault.get(secretPath.vaultKey, {
+      source: options.source
+    });
     if (!result.ok) {
       return result;
     }
@@ -6780,7 +7016,8 @@ var SecretsService = class {
     }
     const result = await this.vault.list({
       prefix,
-      removePrefix: true
+      removePrefix: true,
+      ...options?.source === void 0 ? {} : { source: options.source }
     });
     if (!result.ok) {
       return result;
@@ -6799,6 +7036,7 @@ var SecretsService = class {
         prefix: "secrets/",
         removePrefix: true,
         limit: 1e3,
+        source: "network",
         ...cursor === void 0 ? {} : { cursor }
       });
       if (!result.ok) {
@@ -7790,6 +8028,7 @@ EncryptionService.serviceName = "encryption";
 import { DecryptTransportResponseError as DecryptTransportResponseError3 } from "@tinycloud/sdk-services/internal/decrypt-transport-response-error";
 export {
   BaseService,
+  CLEAR_PENDING_WARNING,
   DECRYPT_ACTION,
   DECRYPT_FACT_TYPE,
   DECRYPT_RESULT_TYPE,
@@ -7857,6 +8096,7 @@ export {
   buildDecryptInvocation,
   buildNetworkId,
   canonicalHashHex,
+  canonicalReplicationIdentity,
   canonicalSignedResponse,
   canonicalize as canonicalizeEncryptionJson,
   canonicalizeSecretScope,
@@ -7883,6 +8123,7 @@ export {
   installTinyCloudDebugGlobals,
   isNetworkId,
   isStorageFullError,
+  kvPrefixCovers,
   networkDiscoveryKey,
   networkError,
   notFoundError,
@@ -7896,6 +8137,8 @@ export {
   parseSecretCatalogKey,
   parseStorageQuotaBytes,
   permissionDeniedError,
+  replicationIdentityKey,
+  requiresSecretsOptIn,
   resolveSecretListPrefix,
   resolveSecretPath,
   serviceError,