@tinycloud/replica 0.1.0-beta.3 → 0.1.1-beta.0

package/dist/replica.worker.js

@@ -6852,7 +6852,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 };
@@ -6876,9 +6881,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;
 }
@@ -6915,6 +6945,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");
@@ -7412,6 +7448,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
@@ -8086,6 +8128,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) {
@@ -8325,14 +8368,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;
@@ -8586,6 +8643,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) {
@@ -8836,6 +8894,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"));
       }
@@ -8849,64 +8908,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 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));
@@ -8915,6 +8948,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",
@@ -8927,6 +9010,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"));
       }
@@ -8941,63 +9025,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));
@@ -9006,11 +9042,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"));
       }
@@ -9041,155 +9130,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(
-          session2,
-          paths.map((path) => ({
-            spaceId: session2.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: session2.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 session2 = 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(
+        session2,
+        paths.map((path) => ({
+          spaceId: session2.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"));
       }
@@ -9206,49 +9317,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 {
@@ -9256,6 +9362,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.
    */
@@ -9424,61 +9580,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 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));
@@ -9487,6 +9604,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.
    */
@@ -9515,7 +9680,7 @@ var KVService = class extends BaseService {
             );
           }
           if (response.status === 404) {
-            return this.classifyNotFound(response, key);
+            return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           return err(
@@ -9581,7 +9746,7 @@ var KVService = class extends BaseService {
           signal: request.signal
         });
         if (!response.ok) {
-          return this.createSignedReadUrlError(response, key, path);
+          return await this.createSignedReadUrlError(response, key, path);
         }
         const signedUrl = this.normalizeSignedReadUrlResponse(
           await response.json()
@@ -9816,7 +9981,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);
@@ -9856,7 +10021,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);
@@ -9882,7 +10047,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);
@@ -9907,7 +10072,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);
@@ -9932,7 +10097,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") {
@@ -10301,7 +10466,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);
@@ -10327,7 +10492,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);
@@ -10360,7 +10525,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);
@@ -10392,7 +10557,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);
@@ -10417,7 +10582,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);
@@ -10442,7 +10607,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);
@@ -10467,7 +10632,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);
@@ -10502,7 +10667,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) {
@@ -11804,6 +11969,12 @@ function defaultVaultMessage(input) {
       return input.message ?? `Public key not found for ${input.did}`;
     case "STORAGE_ERROR":
       return input.message ?? input.cause.message;
+    case "ALREADY_EXISTS":
+      return input.message ?? `A value already exists at ${input.key}`;
+    case "AUTH_UNAUTHORIZED":
+      return input.message;
+    case "PERMISSION_DENIED":
+      return input.message;
     case "STORAGE_QUOTA_EXCEEDED":
     case "STORAGE_LIMIT_REACHED":
       return input.message;
@@ -11817,13 +11988,33 @@ function vaultError(input) {
   };
   return { ok: false, error };
 }
+function typedKvCause(error) {
+  return Object.assign(new Error(error.message), {
+    name: "ServiceError",
+    code: error.code,
+    service: error.service,
+    ...error.meta !== void 0 ? { meta: error.meta } : {},
+    ...error.cause !== void 0 ? { cause: error.cause } : {}
+  });
+}
 function kvWriteError(context, error) {
   if (error.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error.code === ErrorCodes.STORAGE_LIMIT_REACHED) {
     return vaultError({ code: error.code, message: error.message, meta: error.meta });
   }
+  const message = `${context}: ${error.message}`;
+  if (error.code === ErrorCodes.AUTH_UNAUTHORIZED) {
+    const code = authorizationVerdictOf(error) === "unauthenticated" ? "AUTH_UNAUTHORIZED" : "PERMISSION_DENIED";
+    return vaultError({
+      code,
+      message,
+      ...error.meta !== void 0 ? { meta: error.meta } : {},
+      cause: typedKvCause(error)
+    });
+  }
   return vaultError({
     code: "STORAGE_ERROR",
-    cause: new Error(`${context}: ${error.message}`)
+    cause: new Error(message, { cause: typedKvCause(error) }),
+    ...error.meta !== void 0 ? { meta: error.meta } : {}
   });
 }
 var DataVaultService = class extends BaseService {
@@ -12103,11 +12294,18 @@ var DataVaultService = class extends BaseService {
           cause: new Error(envelopeResult.error.message)
         });
       }
-      const valuePutResult = await this.tc.kv.put(
-        `vault/${key}`,
-        JSON.stringify(envelopeResult.data)
-      );
+      const valuePath = `vault/${key}`;
+      const valueBody = JSON.stringify(envelopeResult.data);
+      const valuePutResult = options?.ifNoneMatch !== void 0 ? await this.tc.kv.put(valuePath, valueBody, { ifNoneMatch: options.ifNoneMatch }) : await this.tc.kv.put(valuePath, valueBody);
       if (!valuePutResult.ok) {
+        if (options?.ifNoneMatch !== void 0 && valuePutResult.error.code === ErrorCodes.KV_PRECONDITION_FAILED) {
+          return vaultError({
+            code: "ALREADY_EXISTS",
+            key,
+            ...valuePutResult.error.meta !== void 0 ? { meta: valuePutResult.error.meta } : {},
+            cause: typedKvCause(valuePutResult.error)
+          });
+        }
         return kvWriteError("Failed to store encrypted value", valuePutResult.error);
       }
       return { ok: true, data: void 0 };
@@ -12134,7 +12332,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 });
@@ -12179,7 +12378,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" };
     }
@@ -12248,7 +12447,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 });
@@ -12275,6 +12475,14 @@ var DataVaultService = class extends BaseService {
       if (this.usesNetworkEncryption) {
         return this.putNetworkEncrypted(key, value, options);
       }
+      if (options?.ifNoneMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "ifNoneMatch is only supported by network-encrypted vaults"
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -12374,7 +12582,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 });
@@ -12383,7 +12592,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 });
@@ -12493,6 +12703,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) {
@@ -13064,6 +13275,11 @@ var DataVaultService = class extends BaseService {
   }
 };
 DataVaultService.serviceName = "vault";
+var TC832_RESERVED_SCOPES = Object.freeze([
+  "default",
+  "global",
+  "scoped"
+]);
 function canonicalize(value) {
   if (value === void 0) {
     return "";
@@ -14383,6 +14599,11 @@ function kvPrefixCovers(prefix, key) {
   if (prefix.endsWith("/")) return key.startsWith(prefix);
   return key === prefix || key.startsWith(`${prefix}/`);
 }
+function authorityPathCovers(grantPath, requestedPath) {
+  if (grantPath === "" || grantPath === "/") return true;
+  if (grantPath.endsWith("/")) return requestedPath.startsWith(grantPath);
+  return requestedPath === grantPath;
+}
 function requiresSecretsOptIn(space, prefix) {
   if (space === "secrets" || space.endsWith(":secrets")) return true;
   const firstSegment = prefix.split("/", 1)[0];
@@ -16496,7 +16717,7 @@ function kvPathIn(resource, space) {
 function grantCovers(grant, space, prefix, ability) {
   for (const [resource, abilities] of Object.entries(grant.att)) {
     const path = kvPathIn(resource, space);
-    if (path === void 0 || !kvPrefixCovers(path, prefix)) continue;
+    if (path === void 0 || !authorityPathCovers(path, prefix)) continue;
     if (ability in abilities) return true;
     if (ability !== "tinycloud.kv/sync" && ability !== "tinycloud.kv/retain" && "tinycloud.kv/*" in abilities) return true;
   }
@@ -16509,8 +16730,9 @@ function assertGrantInstallable(grant, input) {
       `The grant was issued to ${grant.audience}, not this device (${input.deviceDid}).`
     );
   }
+  const requiredPaths = input.prefix.endsWith("/") ? [input.prefix] : [input.prefix, `${input.prefix}/`];
   for (const ability of ["tinycloud.kv/sync", "tinycloud.kv/get"]) {
-    if (!grantCovers(grant, input.space, input.prefix, ability)) {
+    if (!requiredPaths.every((path) => grantCovers(grant, input.space, path, ability))) {
       throw new ReplicaError(
         ReplicaErrorCode.GRANT_NOT_COVERING,
         `The grant does not carry ${ability} on ${input.space}/kv/${input.prefix}.`,