@tinycloud/sdk-services 3.1.0 → 3.2.0-beta.3

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   BaseService: () => BaseService,
+  CLEAR_PENDING_WARNING: () => CLEAR_PENDING_WARNING,
   DECRYPT_ACTION: () => DECRYPT_ACTION,
   DECRYPT_FACT_TYPE: () => DECRYPT_FACT_TYPE,
   DECRYPT_RESULT_TYPE: () => DECRYPT_RESULT_TYPE,
@@ -47,11 +48,13 @@ __export(src_exports, {
   KVListResultSchema: () => KVListResultSchema,
   KVResponseHeadersSchema: () => KVResponseHeadersSchema,
   KVService: () => KVService,
+  MAX_SECRET_SCOPE_LENGTH: () => MAX_SECRET_SCOPE_LENGTH,
   NETWORK_NAME_PATTERN: () => NETWORK_NAME_PATTERN,
   NetworkIdError: () => NetworkIdError,
   PrefixedKVService: () => PrefixedKVService,
   RetryPolicySchema: () => RetryPolicySchema,
   SECRET_NAME_RE: () => SECRET_NAME_RE,
+  SECRET_SCOPE_RE: () => SECRET_SCOPE_RE,
   SQLAction: () => SQLAction,
   SQLMigrations: () => SQLMigrations,
   SQLService: () => SQLService,
@@ -65,6 +68,7 @@ __export(src_exports, {
   ServiceResponseEventSchema: () => ServiceResponseEventSchema,
   ServiceRetryEventSchema: () => ServiceRetryEventSchema,
   ServiceSessionSchema: () => ServiceSessionSchema,
+  TC832_RESERVED_SCOPES: () => TC832_RESERVED_SCOPES,
   TelemetryEvents: () => TelemetryEvents,
   TelemetrySpanEventSchema: () => TelemetrySpanEventSchema,
   TinyCloudDebugLogger: () => TinyCloudDebugLogger,
@@ -72,6 +76,7 @@ __export(src_exports, {
   VaultHeaders: () => VaultHeaders,
   VaultPublicSpaceKVActions: () => VaultPublicSpaceKVActions,
   abortedError: () => abortedError,
+  appSecretScope: () => appSecretScope,
   authExpiredError: () => authExpiredError,
   authRequiredError: () => authRequiredError,
   authUnauthorizedError: () => authUnauthorizedError,
@@ -84,6 +89,7 @@ __export(src_exports, {
   buildDecryptInvocation: () => buildDecryptInvocation,
   buildNetworkId: () => buildNetworkId,
   canonicalHashHex: () => canonicalHashHex,
+  canonicalReplicationIdentity: () => canonicalReplicationIdentity,
   canonicalSignedResponse: () => canonicalSignedResponse,
   canonicalizeEncryptionJson: () => canonicalize,
   canonicalizeSecretScope: () => canonicalizeSecretScope,
@@ -110,6 +116,7 @@ __export(src_exports, {
   installTinyCloudDebugGlobals: () => installTinyCloudDebugGlobals,
   isNetworkId: () => isNetworkId,
   isStorageFullError: () => isStorageFullError,
+  kvPrefixCovers: () => kvPrefixCovers,
   networkDiscoveryKey: () => networkDiscoveryKey,
   networkError: () => networkError,
   notFoundError: () => notFoundError,
@@ -123,6 +130,8 @@ __export(src_exports, {
   parseSecretCatalogKey: () => parseSecretCatalogKey,
   parseStorageQuotaBytes: () => parseStorageQuotaBytes,
   permissionDeniedError: () => permissionDeniedError,
+  replicationIdentityKey: () => replicationIdentityKey,
+  requiresSecretsOptIn: () => requiresSecretsOptIn,
   resolveSecretListPrefix: () => resolveSecretListPrefix,
   resolveSecretPath: () => resolveSecretPath,
   serviceError: () => serviceError,
@@ -210,7 +219,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 };
@@ -236,9 +250,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;
 }
@@ -275,6 +314,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");
@@ -899,6 +944,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
@@ -1650,6 +1701,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) {
@@ -1895,14 +1947,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;
@@ -2156,6 +2222,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) {
@@ -2406,6 +2473,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"));
       }
@@ -2419,64 +2487,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));
@@ -2485,6 +2527,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",
@@ -2497,6 +2589,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"));
       }
@@ -2511,63 +2604,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));
@@ -2576,11 +2621,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"));
       }
@@ -2611,155 +2709,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"));
       }
@@ -2776,49 +2896,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 {
@@ -2826,6 +2941,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.
    */
@@ -2994,61 +3159,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));
@@ -3057,6 +3183,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.
    */
@@ -3085,7 +3259,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(
@@ -3151,7 +3325,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()
@@ -3224,6 +3398,64 @@ 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/scope.ts
+function kvPrefixCovers(prefix, key) {
+  if (prefix === "") return true;
+  if (prefix.endsWith("/")) return key.startsWith(prefix);
+  return key === prefix || key.startsWith(`${prefix}/`);
+}
+function requiresSecretsOptIn(space, prefix) {
+  if (space === "secrets" || space.endsWith(":secrets")) return true;
+  return prefix.split("/", 1)[0] === "vault";
+}
+
 // src/responseErrors.ts
 function parseServiceErrorBody(errorText) {
   try {
@@ -3400,7 +3632,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);
@@ -3440,7 +3672,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);
@@ -3466,7 +3698,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);
@@ -3491,7 +3723,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);
@@ -3516,7 +3748,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") {
@@ -3892,7 +4124,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);
@@ -3918,7 +4150,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);
@@ -3951,7 +4183,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);
@@ -3983,7 +4215,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);
@@ -4008,7 +4240,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);
@@ -4033,7 +4265,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);
@@ -4058,7 +4290,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);
@@ -4093,7 +4325,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) {
@@ -5442,6 +5674,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;
@@ -5455,13 +5693,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 {
@@ -5741,11 +5999,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 };
@@ -5772,7 +6037,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 });
@@ -5817,7 +6083,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" };
     }
@@ -5886,7 +6152,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 });
@@ -5913,6 +6180,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",
@@ -6012,7 +6287,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 });
@@ -6021,7 +6297,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 });
@@ -6131,6 +6408,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) {
@@ -6724,6 +7002,35 @@ var SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
 var SECRET_PREFIX = "secrets/";
 var SCOPED_SECRET_PREFIX = "secrets/scoped/";
 var RESERVED_SECRET_SCOPES = /* @__PURE__ */ new Set(["default", "global"]);
+var SECRET_SCOPE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var MAX_SECRET_SCOPE_LENGTH = 64;
+var TC832_RESERVED_SCOPES = Object.freeze([
+  "default",
+  "global",
+  "scoped"
+]);
+function appSecretScope(appId) {
+  if (appId.trim() === "") {
+    throw new Error("App id must be non-empty to derive a secret scope.");
+  }
+  const scope = appId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (scope === "") {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} must contain at least one letter or number.`
+    );
+  }
+  if (scope.length > MAX_SECRET_SCOPE_LENGTH) {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} yields a secret scope longer than ${MAX_SECRET_SCOPE_LENGTH} characters.`
+    );
+  }
+  if (TC832_RESERVED_SCOPES.includes(scope)) {
+    throw new Error(
+      `App id ${JSON.stringify(appId)} yields the reserved secret scope ${JSON.stringify(scope)}.`
+    );
+  }
+  return scope;
+}
 function canonicalizeSecretScope(scope) {
   if (scope === void 0) {
     return void 0;
@@ -6826,7 +7133,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;
     }
@@ -6836,11 +7145,12 @@ var SecretsService = class {
     const secretPath = resolveSecretPathResult(name, options);
     if ("ok" in secretPath) return secretPath;
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    return this.vault.put(secretPath.vaultKey, {
+    const payload = {
       value,
       createdAt: now,
       updatedAt: now
-    });
+    };
+    return options?.ifAbsent === true ? this.vault.put(secretPath.vaultKey, payload, { ifNoneMatch: "*" }) : this.vault.put(secretPath.vaultKey, payload);
   }
   async delete(name, options) {
     const secretPath = resolveSecretPathResult(name, options);
@@ -6859,7 +7169,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;
@@ -6878,6 +7189,7 @@ var SecretsService = class {
         prefix: "secrets/",
         removePrefix: true,
         limit: 1e3,
+        source: "network",
         ...cursor === void 0 ? {} : { cursor }
       });
       if (!result.ok) {
@@ -7870,6 +8182,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseService,
+  CLEAR_PENDING_WARNING,
   DECRYPT_ACTION,
   DECRYPT_FACT_TYPE,
   DECRYPT_RESULT_TYPE,
@@ -7896,11 +8209,13 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   KVListResultSchema,
   KVResponseHeadersSchema,
   KVService,
+  MAX_SECRET_SCOPE_LENGTH,
   NETWORK_NAME_PATTERN,
   NetworkIdError,
   PrefixedKVService,
   RetryPolicySchema,
   SECRET_NAME_RE,
+  SECRET_SCOPE_RE,
   SQLAction,
   SQLMigrations,
   SQLService,
@@ -7914,6 +8229,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   ServiceResponseEventSchema,
   ServiceRetryEventSchema,
   ServiceSessionSchema,
+  TC832_RESERVED_SCOPES,
   TelemetryEvents,
   TelemetrySpanEventSchema,
   TinyCloudDebugLogger,
@@ -7921,6 +8237,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   VaultHeaders,
   VaultPublicSpaceKVActions,
   abortedError,
+  appSecretScope,
   authExpiredError,
   authRequiredError,
   authUnauthorizedError,
@@ -7933,6 +8250,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   buildDecryptInvocation,
   buildNetworkId,
   canonicalHashHex,
+  canonicalReplicationIdentity,
   canonicalSignedResponse,
   canonicalizeEncryptionJson,
   canonicalizeSecretScope,
@@ -7959,6 +8277,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   installTinyCloudDebugGlobals,
   isNetworkId,
   isStorageFullError,
+  kvPrefixCovers,
   networkDiscoveryKey,
   networkError,
   notFoundError,
@@ -7972,6 +8291,8 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   parseSecretCatalogKey,
   parseStorageQuotaBytes,
   permissionDeniedError,
+  replicationIdentityKey,
+  requiresSecretsOptIn,
   resolveSecretListPrefix,
   resolveSecretPath,
   serviceError,