@tinycloud/cli 1.2.0-beta.2 → 1.2.0-beta.3

package/dist/legacy-entry.js

@@ -131,6 +131,114 @@ var init_storage = __esm({
   }
 });
 
+// src/lib/replication-registry.ts
+function stopForSignal(signal) {
+  void closeReplication().finally(() => {
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  });
+}
+function installSignalHandlers() {
+  if (state.installedSignalHandlers) return;
+  state.installedSignalHandlers = true;
+  state.sigintHandler = () => stopForSignal("SIGINT");
+  state.sigtermHandler = () => stopForSignal("SIGTERM");
+  process.once("SIGINT", state.sigintHandler);
+  process.once("SIGTERM", state.sigtermHandler);
+}
+function removeSignalHandlers() {
+  if (!state.installedSignalHandlers) return;
+  state.installedSignalHandlers = false;
+  if (state.sigintHandler) process.removeListener("SIGINT", state.sigintHandler);
+  if (state.sigtermHandler) process.removeListener("SIGTERM", state.sigtermHandler);
+  state.sigintHandler = void 0;
+  state.sigtermHandler = void 0;
+}
+function registerReplication(profile, control) {
+  state.controls.set(profile, control);
+  state.allControls.add(control);
+  state.generation += 1;
+  installSignalHandlers();
+}
+function replicationForProfile(profile) {
+  return state.controls.get(profile);
+}
+function registeredReplications() {
+  return state.controls;
+}
+function closeReplication(schedule = scheduleTimeout) {
+  if (state.closing) return state.closing;
+  removeSignalHandlers();
+  let resolveClosing;
+  let rejectClosing;
+  const closing = new Promise((resolve5, reject) => {
+    resolveClosing = resolve5;
+    rejectClosing = reject;
+  });
+  state.closing = closing;
+  void (async () => {
+    let timeout;
+    const deadline = new Promise((resolve5) => {
+      timeout = schedule(() => resolve5(true), CLOSE_TIMEOUT_MS);
+    });
+    let timedOut = false;
+    const abandonQueuedControls = () => {
+      for (const control of state.allControls) {
+        void Promise.resolve().then(() => control.close()).catch(() => void 0);
+      }
+      state.controls.clear();
+      state.allControls.clear();
+    };
+    try {
+      while (!timedOut) {
+        while (state.allControls.size > 0) {
+          const generation = state.generation;
+          const pending = [...state.allControls];
+          state.controls.clear();
+          state.allControls.clear();
+          const drained = Promise.allSettled(pending.map((control) => Promise.resolve().then(() => control.close()))).then(() => false);
+          timedOut ||= await Promise.race([drained, deadline]);
+          if (timedOut) {
+            abandonQueuedControls();
+            break;
+          }
+          if (state.generation === generation && state.allControls.size === 0) break;
+        }
+        if (timedOut) break;
+        const turn = new Promise((resolve5) => setImmediate(() => resolve5(false)));
+        timedOut ||= await Promise.race([turn, deadline]);
+        if (timedOut) abandonQueuedControls();
+        else if (state.allControls.size === 0) break;
+      }
+      state.closing = void 0;
+      if (state.allControls.size === 0) removeSignalHandlers();
+      resolveClosing(timedOut);
+    } catch (error) {
+      state.closing = void 0;
+      if (state.allControls.size === 0) removeSignalHandlers();
+      rejectClosing(error);
+    } finally {
+      clearTimeout(timeout);
+    }
+  })();
+  return closing;
+}
+var registryKey, globalState, state, CLOSE_TIMEOUT_MS, scheduleTimeout;
+var init_replication_registry = __esm({
+  "src/lib/replication-registry.ts"() {
+    "use strict";
+    registryKey = /* @__PURE__ */ Symbol.for("@tinycloud/cli/replication-registry");
+    globalState = globalThis;
+    state = globalState[registryKey] ??= {
+      controls: /* @__PURE__ */ new Map(),
+      allControls: /* @__PURE__ */ new Set(),
+      installedSignalHandlers: false,
+      generation: 0
+    };
+    CLOSE_TIMEOUT_MS = 3e3;
+    scheduleTimeout = (callback, delayMs) => setTimeout(callback, delayMs);
+  }
+});
+
 // src/output/theme.ts
 import chalk from "chalk";
 var TC_PALETTE, theme;
@@ -546,7 +654,8 @@ function handleError(error) {
     ...Object.keys(meta).length ? { meta } : {},
     warnings: mergeWarnings(drainWarnings(), operationWarnings(cliError.metadata?.warnings))
   });
-  process.exit(cliError.exitCode);
+  if (registeredReplications().size === 0) return process.exit(cliError.exitCode);
+  return closeReplication().then(() => process.exit(cliError.exitCode));
 }
 function safeCliRecovery(value, context) {
   if (typeof value !== "object" || value === null || Array.isArray(value) || !("action" in value)) return void 0;
@@ -656,6 +765,7 @@ var activeProfileName, CLIError, SETUP_KEYS;
 var init_errors = __esm({
   "src/output/errors.ts"() {
     "use strict";
+    init_replication_registry();
     init_constants();
     init_formatter();
     init_storage2();
@@ -1214,11 +1324,11 @@ var init_md = __esm({
         if (len % 4)
           throw new Error("_sha2: outputLen should be aligned to 32bit");
         const outLen = len / 4;
-        const state = this.get();
-        if (outLen > state.length)
+        const state2 = this.get();
+        if (outLen > state2.length)
           throw new Error("_sha2: outputLen bigger than state");
         for (let i = 0; i < outLen; i++)
-          oview.setUint32(4 * i, state[i], isLE2);
+          oview.setUint32(4 * i, state2[i], isLE2);
       }
       digest() {
         const { buffer, outputLen } = this;
@@ -6401,6 +6511,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");
@@ -8322,7 +8438,7 @@ function encOk(data) {
 function encErr(error) {
   return { ok: false, error };
 }
-var import_decrypt_transport_response_error, ErrorCodes, defaultRetryPolicy, TelemetryEvents, REDACTED, SAFE_NUMBER_FIELDS, SAFE_BOOLEAN_FIELDS, DEBUG_FLAG, MAX_EVENTS, TinyCloudDebugLogger, tinyCloudDebugLogger, ServiceErrorSchema, GenericResultSchema, KVResponseHeadersSchema, GenericKVResponseSchema, KVListResponseSchema, KVListResultSchema, ServiceRequestEventSchema, ServiceResponseEventSchema, ServiceErrorEventSchema, ServiceRetryEventSchema, TelemetrySpanEventSchema, RetryPolicySchema, ServiceSessionSchema, URN_PREFIX, NETWORK_NAME_RE, PKH_EIP155_DID_RE, NetworkIdError, RequestTimeoutError, grantableActions, capabilityServices, MAX_CAUSE_DEPTH2, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, MAX_TIMER_DELAY_MS, BaseService, PrefixedKVService, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, KVAction, MAX_KV_BATCH_READ_ITEMS, pathByteEncoder, REVOKED_BODY, KVService, SQLMigrations, DatabaseHandle, SQLAction, DDL_TOKENS, MIGRATIONS_TABLE, MIGRATIONS_SCHEMA, MIGRATIONS_META_NAMESPACE, MIGRATIONS_META_ID, SQLService, DuckDbDatabaseHandle, DuckDbAction, DuckDbService, AsyncQueue, HOOK_STREAM_RETRY_BASE_DELAY_MS, HOOK_STREAM_RETRY_MAX_DELAY_MS, HOOK_STREAM_HEALTHY_MS, HooksService, SUPERSEDED, STREAM_ERROR_NAMES, STREAM_ERROR_CODES, VaultVersionConfig, CURRENT_VAULT_VERSION, VaultHeaders, DB_NAME, DB_VERSION, STORE_NAME, WRAP_KEY_ID, DataVaultService, SECRET_NAME_RE, SECRET_PREFIX, SCOPED_SECRET_PREFIX, RESERVED_SECRET_SCOPES, TC832_RESERVED_SCOPES, HEX, DEFAULT_ENCRYPTION_ALG, ENVELOPE_VERSION, DEFAULT_KEY_VERSION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, EncryptionService;
+var import_decrypt_transport_response_error, ErrorCodes, defaultRetryPolicy, TelemetryEvents, REDACTED, SAFE_NUMBER_FIELDS, SAFE_BOOLEAN_FIELDS, SAFE_REPLICATION_FIELDS, DEBUG_FLAG, MAX_EVENTS, TinyCloudDebugLogger, tinyCloudDebugLogger, ServiceErrorSchema, GenericResultSchema, KVResponseHeadersSchema, GenericKVResponseSchema, KVListResponseSchema, KVListResultSchema, ServiceRequestEventSchema, ServiceResponseEventSchema, ServiceErrorEventSchema, ServiceRetryEventSchema, TelemetrySpanEventSchema, RetryPolicySchema, ServiceSessionSchema, URN_PREFIX, NETWORK_NAME_RE, PKH_EIP155_DID_RE, NetworkIdError, RequestTimeoutError, grantableActions, capabilityServices, MAX_CAUSE_DEPTH2, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, MAX_TIMER_DELAY_MS, BaseService, PrefixedKVService, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, KVAction, MAX_KV_BATCH_READ_ITEMS, pathByteEncoder, REVOKED_BODY, KVService, SQLMigrations, DatabaseHandle, SQLAction, DDL_TOKENS, MIGRATIONS_TABLE, MIGRATIONS_SCHEMA, MIGRATIONS_META_NAMESPACE, MIGRATIONS_META_ID, SQLService, DuckDbDatabaseHandle, DuckDbAction, DuckDbService, AsyncQueue, HOOK_STREAM_RETRY_BASE_DELAY_MS, HOOK_STREAM_RETRY_MAX_DELAY_MS, HOOK_STREAM_HEALTHY_MS, HooksService, SUPERSEDED, STREAM_ERROR_NAMES, STREAM_ERROR_CODES, VaultVersionConfig, CURRENT_VAULT_VERSION, VaultHeaders, DB_NAME, DB_VERSION, STORE_NAME, WRAP_KEY_ID, DataVaultService, SECRET_NAME_RE, SECRET_PREFIX, SCOPED_SECRET_PREFIX, RESERVED_SECRET_SCOPES, TC832_RESERVED_SCOPES, HEX, DEFAULT_ENCRYPTION_ALG, ENVELOPE_VERSION, DEFAULT_KEY_VERSION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, EncryptionService;
 var init_dist2 = __esm({
   "../sdk-services/dist/index.js"() {
     "use strict";
@@ -8392,7 +8508,12 @@ var init_dist2 = __esm({
       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"
     };
     REDACTED = "[REDACTED]";
     SAFE_NUMBER_FIELDS = /* @__PURE__ */ new Set([
@@ -8401,9 +8522,34 @@ var init_dist2 = __esm({
       "endedAt",
       "startedAt",
       "status",
-      "timestamp"
+      "timestamp",
+      "latencyMs",
+      "stalenessMs",
+      "count",
+      "changes",
+      "deleted",
+      "fetched",
+      "pages",
+      "lagMs",
+      "pendingCleared"
     ]);
     SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted"]);
+    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"]
+    };
     DEBUG_FLAG = "TinyCloud_debug";
     MAX_EVENTS = 1e3;
     TinyCloudDebugLogger = class {
@@ -8854,6 +9000,7 @@ var init_dist2 = __esm({
         const parents = [
           this.abortController.signal,
           this.context?.abortSignal,
+          this.context?.operationAbortSignal,
           signal
         ].filter((parent) => parent !== void 0);
         for (const parent of parents) {
@@ -9068,14 +9215,28 @@ var init_dist2 = __esm({
        */
       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;
@@ -9329,6 +9490,7 @@ var init_dist2 = __esm({
         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) {
@@ -9579,6 +9741,7 @@ var init_dist2 = __esm({
        */
       async get(key, options) {
         return this.withTelemetry("get", key, async () => {
+          if (this.readThroughReady !== null) await this.readThroughReady;
           if (!this.requireAuth()) {
             return err(authRequiredError("kv"));
           }
@@ -9592,64 +9755,38 @@ var init_dist2 = __esm({
           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 ? validatedCapabilityOf2({
-                  service: "kv",
-                  code: ErrorCodes.AUTH_UNAUTHORIZED,
-                  meta: {
-                    status: response.status,
-                    resource: `${this.context.session.spaceId}/kv/${path}`,
-                    requiredAction: KVAction.GET
-                  }
-                }) : void 0;
-                return this.authorizationFailure(
-                  `Failed to get key ${JSON.stringify(key)}`,
-                  response,
-                  errorText2,
-                  [path],
-                  KVAction.GET,
-                  structuredCapability ? { permissionHint, ...structuredCapability } : {}
-                );
-              }
-              if (response.status === 404) {
-                return await this.classifyNotFound(response, key);
-              }
-              const errorText = await response.text();
-              if (response.status === 413) {
-                return err(serviceError(
-                  ErrorCodes.KV_RESPONSE_TOO_LARGE,
-                  `KV value at key ${JSON.stringify(key)} exceeds the requested response limit`,
-                  "kv",
-                  { meta: { status: response.status, statusText: response.statusText } }
-                ));
+            const network = () => this.getFromNetwork(key, path, options, request.signal);
+            if (options?.source === "network") {
+              const observer = this.readThrough;
+              if (observer === null) return await network();
+              let outcome = "error";
+              const startedAt = Date.now();
+              try {
+                const result = await network();
+                outcome = result.ok ? "found" : result.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error";
+                return result;
+              } finally {
+                try {
+                  observer.observeNetworkRequested({
+                    op: "get",
+                    space: this.context.session.spaceId,
+                    path,
+                    reason: "NETWORK_REQUESTED",
+                    outcome,
+                    latencyMs: Date.now() - startedAt
+                  });
+                } catch {
+                }
               }
-              return err(
-                serviceError(
-                  ErrorCodes.NETWORK_ERROR,
-                  `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
-                  "kv",
-                  { meta: { status: response.status, statusText: response.statusText } }
-                )
-              );
             }
-            const data = await this.parseResponse(
-              response,
-              options?.raw,
-              options?.binary
-            );
-            return ok({
-              data,
-              headers: this.createResponseHeaders(response.headers)
+            if (this.readThrough === null) return await network();
+            return await this.readThrough.get({
+              space: this.context.session.spaceId,
+              key,
+              path,
+              options,
+              signal: request.signal,
+              network
             });
           } catch (error) {
             return err(wrapError2("kv", error));
@@ -9658,6 +9795,56 @@ var init_dist2 = __esm({
           }
         });
       }
+      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 ? validatedCapabilityOf2({
+              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",
@@ -9670,6 +9857,7 @@ var init_dist2 = __esm({
        */
       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"));
           }
@@ -9684,63 +9872,15 @@ var init_dist2 = __esm({
           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(wrapError2("kv", error));
@@ -9749,11 +9889,64 @@ var init_dist2 = __esm({
           }
         });
       }
+      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"));
           }
@@ -9784,155 +9977,177 @@ var init_dist2 = __esm({
             }
             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 = wrapError2("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 = wrapError2("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 = wrapError2("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"));
           }
@@ -9949,49 +10164,44 @@ var init_dist2 = __esm({
           }
           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(wrapError2("kv", error));
           } finally {
@@ -9999,6 +10209,56 @@ var init_dist2 = __esm({
           }
         });
       }
+      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.
        */
@@ -10167,61 +10427,22 @@ var init_dist2 = __esm({
        */
       async delete(key, options) {
         return this.withTelemetry("delete", key, async () => {
+          if (this.readThroughReady !== null) await this.readThroughReady;
           if (!this.requireAuth()) {
             return err(authRequiredError("kv"));
           }
           const path = this.getFullPath(key, options?.prefix);
           const request = this.createRequestSignal(options?.signal, options?.timeout);
           try {
-            const response = await this.invokeOperation(
-              path,
-              KVAction.DELETE,
-              void 0,
-              request.signal,
-              options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
-            );
-            if (!response.ok) {
-              if (response.status === 401 || response.status === 403) {
-                return this.authorizationFailure(
-                  `Failed to delete key ${JSON.stringify(key)}`,
-                  response,
-                  await this.readAuthorizationText(response),
-                  [path],
-                  KVAction.DELETE
-                );
-              }
-              if (response.status === 404) {
-                return await this.classifyNotFound(response, key);
-              }
-              const errorText = await response.text();
-              if (response.status === 412) {
-                return err(serviceError(
-                  ErrorCodes.KV_PRECONDITION_FAILED,
-                  `KV precondition failed for key ${JSON.stringify(key)}`,
-                  "kv",
-                  { meta: { status: response.status, statusText: response.statusText } }
-                ));
-              }
-              if (response.status === 503 && options?.ifMatch !== void 0) {
-                return err(serviceError(
-                  ErrorCodes.KV_CONFLICT,
-                  `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
-                  "kv",
-                  { meta: { status: response.status, statusText: response.statusText } }
-                ));
-              }
-              return err(
-                serviceError(
-                  ErrorCodes.NETWORK_ERROR,
-                  `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
-                  "kv",
-                  { meta: { status: response.status, statusText: response.statusText } }
-                )
-              );
-            }
-            return ok({
-              data: void 0,
-              headers: this.createResponseHeaders(response.headers)
+            const network = () => this.deleteFromNetwork(key, path, options, request.signal);
+            if (this.readThrough === null) return await network();
+            return await this.readThrough.write({
+              op: "delete",
+              space: this.context.session.spaceId,
+              entries: [{ path }],
+              signal: request.signal,
+              conditional: options?.ifMatch !== void 0,
+              network
             });
           } catch (error) {
             return err(wrapError2("kv", error));
@@ -10230,6 +10451,54 @@ var init_dist2 = __esm({
           }
         });
       }
+      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.
        */
@@ -10525,7 +10794,7 @@ var init_dist2 = __esm({
               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);
@@ -10565,7 +10834,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "execute", dbName, requestedActions2);
+              return await this.handleErrorResponse(response, "execute", dbName, requestedActions2);
             }
             const data = await response.json();
             return ok(data);
@@ -10591,7 +10860,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "batch", dbName, requestedActions2);
+              return await this.handleErrorResponse(response, "batch", dbName, requestedActions2);
             }
             const data = await response.json();
             return ok(data);
@@ -10616,7 +10885,7 @@ var init_dist2 = __esm({
               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);
@@ -10641,7 +10910,7 @@ var init_dist2 = __esm({
               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") {
@@ -10928,7 +11197,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "query");
+              return await this.handleErrorResponse(response, "query");
             }
             const data = await response.json();
             return ok(data);
@@ -10954,7 +11223,7 @@ var init_dist2 = __esm({
               { 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);
@@ -10987,7 +11256,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "execute");
+              return await this.handleErrorResponse(response, "execute");
             }
             const data = await response.json();
             return ok(data);
@@ -11019,7 +11288,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "batch");
+              return await this.handleErrorResponse(response, "batch");
             }
             const data = await response.json();
             return ok(data);
@@ -11044,7 +11313,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "executeStatement");
+              return await this.handleErrorResponse(response, "executeStatement");
             }
             const data = await response.json();
             return ok(data);
@@ -11069,7 +11338,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "describe");
+              return await this.handleErrorResponse(response, "describe");
             }
             const data = await response.json();
             return ok(data);
@@ -11094,7 +11363,7 @@ var init_dist2 = __esm({
               request.signal
             );
             if (!response.ok) {
-              return this.handleErrorResponse(response, "export");
+              return await this.handleErrorResponse(response, "export");
             }
             const blob = await response.blob();
             return ok(blob);
@@ -11129,7 +11398,7 @@ var init_dist2 = __esm({
               signal: request.signal
             });
             if (!response.ok) {
-              return this.handleErrorResponse(response, "import");
+              return await this.handleErrorResponse(response, "import");
             }
             return ok(void 0);
           } catch (error) {
@@ -12139,7 +12408,8 @@ var init_dist2 = __esm({
         }
         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 });
@@ -12184,7 +12454,7 @@ var init_dist2 = __esm({
         }
         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" };
         }
@@ -12253,7 +12523,8 @@ var init_dist2 = __esm({
         }
         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 });
@@ -12387,7 +12658,8 @@ var init_dist2 = __esm({
           }
           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 });
@@ -12396,7 +12668,8 @@ var init_dist2 = __esm({
             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 });
@@ -12506,6 +12779,7 @@ var init_dist2 = __esm({
               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) {
@@ -14264,7 +14538,8 @@ async function loadManifestPermissions(source, profile, options = {}) {
         service,
         space: String(manifest.space ?? "applications"),
         path: resolvedPath,
-        actions
+        actions,
+        ...Array.isArray(entry.caveats) ? { caveats: entry.caveats } : {}
       };
     });
     permissions.push(...await secretPermissionsFromAppManifest(manifest, profile, options.ownerDid));
@@ -14511,13 +14786,127 @@ var init_delegation_expiry = __esm({
   }
 });
 
+// src/lib/replication-log.ts
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync, writeFileSync } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+function appendReplicationEvent(root, event) {
+  mkdirSync(root, { recursive: true, mode: DIR_MODE });
+  chmodSync(root, DIR_MODE);
+  const path = join4(root, "events.jsonl");
+  let size = 0;
+  try {
+    size = statSync(path).size;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const line = `${JSON.stringify(event)}
+`;
+  if (size + Buffer.byteLength(line) > MAX_LOG_BYTES) {
+    const rotated = join4(root, "events.jsonl.1");
+    try {
+      renameSync(path, rotated);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    writeFileSync(path, line, { mode: LOG_MODE });
+  } else {
+    appendFileSync(path, line, { mode: LOG_MODE });
+  }
+  chmodSync(path, LOG_MODE);
+}
+function replicationLogPath(profileRoot) {
+  return join4(profileRoot, "replication", "events.jsonl");
+}
+function createReplicationEventSink(profileRoot, options) {
+  const pinnedNotices = /* @__PURE__ */ new Set();
+  const missingGrantWarnings = /* @__PURE__ */ new Set();
+  return (event) => {
+    appendProfileReplicationEvent(profileRoot, event);
+    if (event.type === "replication.state" && event.state === "grant_missing") {
+      const prefix = event.replica ?? event.space ?? "configured prefix";
+      const key = `${event.space ?? ""}\0${event.replica ?? ""}`;
+      if (!missingGrantWarnings.has(key)) {
+        missingGrantWarnings.add(key);
+        process.stderr.write(`[replication] Warning: no usable kv/get+sync grant for ${prefix}; reads use the network (${event.code ?? "grant_missing"}).
+`);
+      }
+    }
+    if (options.debug) {
+      if (event.type === "replication.read") {
+        const detail = event.source === "replica" ? "replica hit" : `${event.source} ${event.reason}`;
+        const syncStatus = event.syncedBeforeRead === void 0 ? "" : ` syncedBeforeRead:${event.syncedBeforeRead}`;
+        const syncError = event.syncError === void 0 ? "" : ` syncError:${event.syncError}`;
+        process.stderr.write(`[replication] ${event.op} ${event.key} \u2190 ${detail} ${event.latencyMs}ms${syncStatus}${syncError}${event.stalenessMs === null ? "" : ` (synced ${Math.round(event.stalenessMs / 1e3)}s ago)`}
+`);
+      } else if (event.type === "replication.write") {
+        process.stderr.write(`[replication] ${event.op} ${event.keys.join(",")} ${event.outcome}${event.code ? ` ${event.code}` : ""}
+`);
+      } else if (event.type === "replication.sync") {
+        const pending = event.pendingCleared === void 0 ? "" : ` pendingCleared:${event.pendingCleared}`;
+        process.stderr.write(`[replication] sync ${event.replica} ${event.outcome}${event.code ? ` ${event.code}` : ""}${pending}
+`);
+      }
+    }
+    if (event.type === "replication.read" && (event.pendingState === "in_flight" || event.pendingState === "ambiguous") && !options.quiet && !pinnedNotices.has(event.key)) {
+      pinnedNotices.add(event.key);
+      process.stderr.write(`[replication] ${event.key} reads from the network: an earlier write's outcome is unknown (${event.pendingState}${event.code ? `, ${event.code}` : ""}). Review: tc replica report
+`);
+    }
+  };
+}
+function appendProfileReplicationEvent(profileRoot, event) {
+  appendReplicationEvent(dirname2(replicationLogPath(profileRoot)), event);
+}
+var MAX_LOG_BYTES, LOG_MODE, DIR_MODE;
+var init_replication_log = __esm({
+  "src/lib/replication-log.ts"() {
+    "use strict";
+    MAX_LOG_BYTES = 5 * 1024 * 1024;
+    LOG_MODE = 384;
+    DIR_MODE = 448;
+  }
+});
+
+// src/lib/replication-config.ts
+import { join as join5 } from "path";
+import { profilePath, withProfileLock as withProfileLock2 } from "@tinycloud/operations/state";
+import { sqliteReplicaStorage } from "@tinycloud/node-sdk";
+function createCliReplicationConfig(profile, settings, output2, enabled) {
+  if (!enabled || !settings || settings.prefixes.length === 0) return void 0;
+  const root = profilePath(profile);
+  return {
+    enabled: true,
+    prefixes: settings.prefixes,
+    allowSecrets: settings.allowSecrets === true,
+    mode: "foreground",
+    verify: process.env.TC_REPLICATION_VERIFY === "1",
+    maxStalenessMs: Number(process.env.TC_REPLICATION_MAX_STALENESS_MS ?? 6e4),
+    staleSyncTimeoutMs: Number(process.env.TC_REPLICATION_SYNC_TIMEOUT_MS ?? 1e4),
+    storage: sqliteReplicaStorage({
+      dir: join5(root, "replication"),
+      guard: (section) => withProfileLock2(profile, section, { requireProfile: true, timeoutMs: 35e3 })
+    }),
+    onEvent: createReplicationEventSink(root, output2)
+  };
+}
+var init_replication_config = __esm({
+  "src/lib/replication-config.ts"() {
+    "use strict";
+    init_replication_log();
+  }
+});
+
 // src/lib/sdk.ts
 var sdk_exports = {};
 __export(sdk_exports, {
   bootstrapDelegatedSession: () => bootstrapDelegatedSession,
+  closeReplication: () => closeReplication,
   createSDKInstance: () => createSDKInstance,
   ensureAuthenticated: () => ensureAuthenticated,
   jwkHasPrivateParameter: () => jwkHasPrivateParameter,
+  registerReplication: () => registerReplication,
+  registeredReplications: () => registeredReplications,
+  replicationForProfile: () => replicationForProfile,
   restoreProfileSessionNode: () => restoreProfileSessionNode,
   selectSignerJwk: () => selectSignerJwk,
   storedSessionVerifiesLocally: () => storedSessionVerifiesLocally
@@ -14632,10 +15021,21 @@ async function createSDKInstance(ctx, options) {
     );
   }
   if (profile?.authMethod === "local" && effectivePrivateKey) {
+    const replication2 = createCliReplicationConfig(
+      ctx.profile,
+      profile?.replication,
+      { debug: ctx.replicationDebug, quiet: ctx.quiet },
+      ctx.replication
+    );
+    if (ctx.replication && !replication2) {
+      process.stderr.write("[replication] Enabled, but this profile has no configured prefixes; reads use the network.\n");
+    }
     const node2 = new TinyCloudNode({
       host: ctx.host,
-      privateKey: effectivePrivateKey
+      privateKey: effectivePrivateKey,
+      ...replication2 ? { replication: replication2 } : {}
     });
+    if (node2.replication) registerReplication(ctx.profile, node2.replication);
     const restoredOwnSession = Boolean(session && session.delegationHeader && session.delegationCid && session.spaceId);
     if (restoredOwnSession) {
       await restoreProfileSession(node2, ctx.profile, profile, persistedSessionData(ctx.profile, profile, session, key));
@@ -14651,10 +15051,21 @@ async function createSDKInstance(ctx, options) {
     }
     return node2;
   }
+  const replication = createCliReplicationConfig(
+    ctx.profile,
+    profile?.replication,
+    { debug: ctx.replicationDebug, quiet: ctx.quiet },
+    ctx.replication
+  );
+  if (ctx.replication && !replication) {
+    process.stderr.write("[replication] Enabled, but this profile has no configured prefixes; reads use the network.\n");
+  }
   const node = new TinyCloudNode({
     host: ctx.host,
-    privateKey: options?.privateKey
+    privateKey: options?.privateKey,
+    ...replication ? { replication } : {}
   });
+  if (node.replication) registerReplication(ctx.profile, node.replication);
   if (options?.privateKey) {
     await node.signIn();
   } else if (session && session.delegationHeader && session.delegationCid && session.spaceId) {
@@ -14796,6 +15207,9 @@ var init_sdk = __esm({
     init_session_expired();
     init_warnings();
     init_delegation_expiry();
+    init_replication_config();
+    init_replication_registry();
+    init_replication_registry();
     BOOTSTRAP_PROFILE_FIELDS = ["sessionDid", "spaceId"];
   }
 });
@@ -14936,14 +15350,14 @@ var init_host = __esm({
 
 // src/config/profiles.ts
 import { chmod as chmod2, lstat, readdir as readdir2, rm as rm2, rmdir } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join6 } from "path";
 import {
-  profilePath,
+  profilePath as profilePath2,
   readSession,
   recordProfileDeletion,
   refuseWriteToDeletedProfile as refuseWriteToDeletedProfile2,
   removeSession,
-  withProfileLock as withProfileLock2,
+  withProfileLock as withProfileLock3,
   writeSession
 } from "@tinycloud/operations/state";
 var ProfileManager;
@@ -14961,7 +15375,7 @@ var init_profiles = __esm({
        * it around a whole read-modify-write, not just each write.
        */
       static async withLock(name, action, options) {
-        return withProfileLock2(name, action, options);
+        return withProfileLock3(name, action, options);
       }
       /**
        * Read-modify-write of profile.json under the profile lock, so concurrent
@@ -14987,7 +15401,7 @@ var init_profiles = __esm({
       /** Owner-only profile directory (0700), created or tightened before any write into it. */
       static async ensureProfileDir(name) {
         await _ProfileManager.ensureConfigDir();
-        const profileDir = join4(PROFILES_DIR, name);
+        const profileDir = join6(PROFILES_DIR, name);
         await ensureDir(profileDir);
         await chmod2(profileDir, PRIVATE_DIR_MODE);
         return profileDir;
@@ -15016,8 +15430,8 @@ var init_profiles = __esm({
        * Throws CLIError if the profile doesn't exist.
        */
       static async getProfile(name) {
-        const profilePath4 = join4(PROFILES_DIR, name, "profile.json");
-        const profile = await readJson(profilePath4);
+        const profilePath5 = join6(PROFILES_DIR, name, "profile.json");
+        const profile = await readJson(profilePath5);
         if (!profile) {
           throw new CLIError(
             "PROFILE_NOT_FOUND",
@@ -15032,18 +15446,18 @@ var init_profiles = __esm({
        */
       static async setProfile(name, data) {
         await _ProfileManager.withLock(name, async () => {
-          await writeJson(join4(await _ProfileManager.ensureProfileDir(name), "profile.json"), data);
+          await writeJson(join6(await _ProfileManager.ensureProfileDir(name), "profile.json"), data);
         });
       }
       /** Removes profile.json under the profile lock (rollback of a profile a failed login created). */
       static async removeProfileConfig(name) {
-        await _ProfileManager.withLock(name, () => rm2(join4(PROFILES_DIR, name, "profile.json"), { force: true }));
+        await _ProfileManager.withLock(name, () => rm2(join6(PROFILES_DIR, name, "profile.json"), { force: true }));
       }
       /**
        * Returns true if a profile directory exists.
        */
       static async profileExists(name) {
-        return fileExists(join4(PROFILES_DIR, name, "profile.json"));
+        return fileExists(join6(PROFILES_DIR, name, "profile.json"));
       }
       /**
        * Returns an array of profile directory names.
@@ -15067,7 +15481,7 @@ var init_profiles = __esm({
       static async deleteProfile(name) {
         let profileDir;
         try {
-          profileDir = profilePath(name);
+          profileDir = profilePath2(name);
         } catch {
           throw new CLIError(
             "INVALID_PROFILE_NAME",
@@ -15092,11 +15506,11 @@ var init_profiles = __esm({
           return;
         }
         await _ProfileManager.withLock(name, async () => {
-          for (const file of ["session.json", "key.json"]) await rm2(join4(profileDir, file), { force: true });
+          for (const file of ["session.json", "key.json"]) await rm2(join6(profileDir, file), { force: true });
           for (const entry of await readdir2(profileDir)) {
-            if (entry !== ".lock" && entry !== "profile.json") await rm2(join4(profileDir, entry), { recursive: true, force: true });
+            if (entry !== ".lock" && entry !== "profile.json") await rm2(join6(profileDir, entry), { recursive: true, force: true });
           }
-          await rm2(join4(profileDir, "profile.json"), { force: true });
+          await rm2(join6(profileDir, "profile.json"), { force: true });
           await recordProfileDeletion(name);
         });
         await rmdir(profileDir).catch((error) => {
@@ -15108,7 +15522,7 @@ var init_profiles = __esm({
        * Returns the parsed JWK for a profile, or null if no key exists.
        */
       static async getKey(name) {
-        return readJson(join4(PROFILES_DIR, name, "key.json"));
+        return readJson(join6(PROFILES_DIR, name, "key.json"));
       }
       /**
        * Saves a JWK key under the profile lock (0600, in an owner-only profile
@@ -15118,12 +15532,12 @@ var init_profiles = __esm({
       static async setKey(name, jwk) {
         await _ProfileManager.withLock(name, async () => {
           await refuseWriteToDeletedProfile2(name);
-          await writeJson(join4(await _ProfileManager.ensureProfileDir(name), "key.json"), jwk);
+          await writeJson(join6(await _ProfileManager.ensureProfileDir(name), "key.json"), jwk);
         });
       }
       /** Removes key.json under the profile lock (rollback of a key a failed login created). */
       static async removeKey(name) {
-        await _ProfileManager.withLock(name, () => rm2(join4(PROFILES_DIR, name, "key.json"), { force: true }));
+        await _ProfileManager.withLock(name, () => rm2(join6(PROFILES_DIR, name, "key.json"), { force: true }));
       }
       // ── Session management ──────────────────────────────────────────────
       /**
@@ -15150,7 +15564,7 @@ var init_profiles = __esm({
        * created or tightened to 0700.
        */
       static async getCacheDir(name) {
-        const cacheDir = join4(await _ProfileManager.ensureProfileDir(name), "cache");
+        const cacheDir = join6(await _ProfileManager.ensureProfileDir(name), "cache");
         await ensureDir(cacheDir);
         await chmod2(cacheDir, PRIVATE_DIR_MODE);
         return cacheDir;
@@ -15173,11 +15587,20 @@ var init_profiles = __esm({
         const config = await _ProfileManager.getConfig();
         const profile = options.profile ?? process.env.TC_PROFILE ?? config.defaultProfile ?? DEFAULT_PROFILE;
         let profileHost;
+        let profileConfig;
         try {
-          const profileConfig = await _ProfileManager.getProfile(profile);
+          profileConfig = await _ProfileManager.getProfile(profile);
           profileHost = profileConfig.host;
         } catch {
         }
+        const envReplication = process.env.TC_REPLICATION?.toLowerCase();
+        const envEnabled = envReplication === "1" || envReplication === "true" || envReplication === "on";
+        const explicitEnvOff = envReplication === "0" || envReplication === "false" || envReplication === "off";
+        if (envReplication !== void 0 && !envEnabled && !explicitEnvOff) {
+          throw new CLIError("INVALID_ARGUMENT", "TC_REPLICATION must be one of 1, true, on, 0, false or off.", ExitCode.USAGE_ERROR);
+        }
+        const explicitOff = options.noReplication === true || options.replication === false;
+        const replication = options.replication === true ? true : explicitOff ? false : envEnabled;
         const explicitHost = options.host ?? process.env.TC_HOST;
         let host = explicitHost ?? profileHost ?? DEFAULT_HOST;
         let localDiscovery;
@@ -15197,6 +15620,8 @@ var init_profiles = __esm({
           verbose: options.verbose ?? false,
           noCache: options.noCache ?? false,
           quiet: options.quiet ?? false,
+          replication,
+          replicationDebug: options.replicationDebug === true || process.env.TC_REPLICATION_DEBUG === "1",
           ...localDiscovery === void 0 ? {} : { localDiscovery }
         };
       }
@@ -15223,7 +15648,7 @@ function registerAccountCommand(program) {
       assertOk(status);
       outputJson(status.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   const apps = account.command("apps").description("Manage account application registry");
@@ -15254,7 +15679,7 @@ function registerAccountCommand(program) {
         ) + "\n"
       );
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   const spaces = account.command("spaces").description("Manage account space registry");
@@ -15285,7 +15710,7 @@ function registerAccountCommand(program) {
         ) + "\n"
       );
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   spaces.command("info <space-id>").description("Show a registered account space").action(async (spaceId, _options, cmd) => {
@@ -15295,7 +15720,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson(formatSpace(result.data));
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   spaces.command("register <space-id>").description("Register a space in account/spaces").requiredOption("--name <name>", "Display name for the space").requiredOption("--owner <did>", "Owner DID for the space").option("--type <type>", "Space type: owned, delegated, or discovered", "discovered").option("--permission <permission...>", "Permission strings for the space").action(async (spaceId, options, cmd) => {
@@ -15312,7 +15737,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ space: formatSpace(result.data), registered: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   spaces.command("sync").description("Register currently accessible spaces into account/spaces").action(async (_options, cmd) => {
@@ -15322,7 +15747,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ spaces: result.data.map(formatSpace), count: result.data.length, synced: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   spaces.command("remove <space-id>").alias("delete").description("Remove a space registry entry").action(async (spaceId, _options, cmd) => {
@@ -15332,7 +15757,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ spaceId, removed: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   apps.command("info <app-id>").description("Show a registered account application").action(async (appId, _options, cmd) => {
@@ -15342,7 +15767,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson(result.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   apps.command("register <manifest>").description("Register an app manifest in account/applications").action(async (manifestSource, _options, cmd) => {
@@ -15353,7 +15778,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ application: result.data, registered: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   apps.command("remove <app-id>").alias("delete").description("Remove an application registry entry").action(async (appId, _options, cmd) => {
@@ -15363,7 +15788,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ appId, removed: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   const delegations = account.command("delegations").description("View and revoke account delegations");
@@ -15399,7 +15824,7 @@ function registerAccountCommand(program) {
         ) + "\n"
       );
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   delegations.command("revoke <cid>").description("Revoke an active delegation granted by this account").requiredOption("--space <space>", "Space name or ID containing the delegation").action(async (cid, options, cmd) => {
@@ -15409,7 +15834,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ cid, space: options.space, revoked: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   const index = account.command("index").description("Manage the materialized account SQLite index");
@@ -15420,7 +15845,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson({ ...result.data, ensured: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   index.command("status").description("Show account SQLite index sync status").action(async (_options, cmd) => {
@@ -15430,7 +15855,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson(result.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   index.command("rebuild").description("Rebuild account SQLite index from canonical account data").action(async (_options, cmd) => {
@@ -15440,7 +15865,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson(result.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   index.command("query <sql>").description("Query the materialized account SQLite index").option("--params <json>", "Bind parameters as a JSON array for ? placeholders").action(async (sql, options, cmd) => {
@@ -15451,7 +15876,7 @@ function registerAccountCommand(program) {
       assertOk(result);
       outputJson(result.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   const billing = account.command("billing").description("Open account billing");
@@ -15463,7 +15888,7 @@ function registerAccountCommand(program) {
         }
         outputJson({ url: ACCOUNT_BILLING_URL, opened: Boolean(options.open) });
       } catch (error) {
-        handleError(error);
+        return handleError(error);
       }
     });
   }
@@ -15529,15 +15954,15 @@ import { get as httpGet } from "http";
 import { get as httpsGet } from "https";
 import { spawn } from "child_process";
 import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 import { createInterface as createInterface2 } from "readline";
 import { grantAuthRequest, principalDidEquals, signedCompactUcanExpiry as signedCompactUcanExpiry3 } from "@tinycloud/node-sdk";
 import { invokeOperation } from "@tinycloud/operations";
 
 // src/lib/profile-replicas.ts
-import { lstat as lstat2, readdir as readdir4, realpath } from "fs/promises";
-import { join as join6, sep } from "path";
-import { ProfileDeletedError as ProfileDeletedError2, profilePath as profilePath2, withProfileLock as withProfileLock3 } from "@tinycloud/operations/state";
+import { lstat as lstat2, readdir as readdir4, realpath, rm as rm4 } from "fs/promises";
+import { join as join8, relative, sep } from "path";
+import { ProfileDeletedError as ProfileDeletedError2, profilePath as profilePath3, withProfileLock as withProfileLock4 } from "@tinycloud/operations/state";
 
 // ../../node_modules/@noble/hashes/esm/blake3.js
 init_md();
@@ -15772,8 +16197,8 @@ var BLAKE3 = class _BLAKE3 extends BLAKE2 {
   }
   _cloneInto(to) {
     to = super._cloneInto(to);
-    const { IV, flags, state, chunkPos, posOut, chunkOut, stack, chunksDone } = this;
-    to.state.set(state.slice());
+    const { IV, flags, state: state2, chunkPos, posOut, chunkOut, stack, chunksDone } = this;
+    to.state.set(state2.slice());
     to.stack = stack.map((i) => Uint32Array.from(i));
     to.IV.set(IV);
     to.flags = flags;
@@ -17435,6 +17860,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];
@@ -17464,11 +17894,11 @@ function effectiveAuthority(input) {
   const notBefore = maxIso(input.window?.notBefore ?? null, input.grant?.notBefore ?? null);
   const expiresAt = minIso(input.window?.expiresAt ?? null, input.grant?.expiresAt ?? null);
   const retainUntil = input.policy === "retainAfterExpiry" ? input.window?.retainUntil ?? null : null;
-  let state = "valid";
-  if (input.revoked !== null) state = "revoked";
-  else if (notBefore !== null && input.now < Date.parse(notBefore)) state = "not-yet-valid";
-  else if (expiresAt !== null && input.now >= Date.parse(expiresAt)) state = "expired";
-  return { state, notBefore, expiresAt, retainUntil, retentionRevoked: (input.retentionRevoked ?? null) !== null };
+  let state2 = "valid";
+  if (input.revoked !== null) state2 = "revoked";
+  else if (notBefore !== null && input.now < Date.parse(notBefore)) state2 = "not-yet-valid";
+  else if (expiresAt !== null && input.now >= Date.parse(expiresAt)) state2 = "expired";
+  return { state: state2, notBefore, expiresAt, retainUntil, retentionRevoked: (input.retentionRevoked ?? null) !== null };
 }
 function assertReadable(authority, now) {
   switch (authority.state) {
@@ -17533,29 +17963,29 @@ var Replica = class {
     this.#onCommit = options.onCommit;
   }
   async #state() {
-    const state = await this.#store.open();
-    if (state === null) throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, "The replica has not been created.");
-    return state;
+    const state2 = await this.#store.open();
+    if (state2 === null) throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, "The replica has not been created.");
+    return state2;
   }
   /** Throws unless local reads are allowed now; returns the meta every read reports. */
-  #readMeta(state) {
+  #readMeta(state2) {
     const now = this.#now();
     const authority = assertReadable(
       effectiveAuthority({
-        window: state.authority,
-        grant: state.grant,
-        revoked: state.revoked,
-        retentionRevoked: state.retentionRevoked,
-        policy: state.config.localReadPolicy,
+        window: state2.authority,
+        grant: state2.grant,
+        revoked: state2.revoked,
+        retentionRevoked: state2.retentionRevoked,
+        policy: state2.config.localReadPolicy,
         now
       }),
       now
     );
     return {
       consistency: "observed",
-      source: { host: state.config.host, nodeDid: state.nodeDid, space: state.config.space, prefix: state.config.prefix },
-      asOf: state.lastSyncAt,
-      coverage: state.coverage,
+      source: { host: state2.config.host, nodeDid: state2.nodeDid, space: state2.config.space, prefix: state2.config.prefix },
+      asOf: state2.lastSyncAt,
+      coverage: state2.coverage,
       authority
     };
   }
@@ -17568,13 +17998,13 @@ var Replica = class {
     return this.#readMeta(await this.#state());
   }
   async get(key, options = {}) {
-    const state = await this.#state();
-    this.#readMeta(state);
-    if (!kvPrefixCovers(state.config.prefix, key)) return { status: "not_covered", key, meta: await this.#confirmedMeta() };
+    const state2 = await this.#state();
+    this.#readMeta(state2);
+    if (!kvPrefixCovers(state2.config.prefix, key)) return { status: "not_covered", key, meta: await this.#confirmedMeta() };
     for (let attempt = 0; ; attempt += 1) {
       const entry = await this.#store.get(key);
       if (entry === void 0) {
-        const status = state.coverage === "complete" ? "absent" : "coverage_incomplete";
+        const status = state2.coverage === "complete" ? "absent" : "coverage_incomplete";
         return { status, key, meta: await this.#confirmedMeta() };
       }
       if (entry.deleted) return { status: "deleted", key, meta: await this.#confirmedMeta() };
@@ -17597,9 +18027,9 @@ var Replica = class {
   }
   /** Live keys under `prefix` (a plain string prefix within the replica's scope). */
   async list(options = {}) {
-    const state = await this.#state();
-    this.#readMeta(state);
-    const scope = state.config.prefix;
+    const state2 = await this.#state();
+    this.#readMeta(state2);
+    const scope = state2.config.prefix;
     const prefix = options.prefix ?? "";
     if (prefix !== "" && !scope.startsWith(prefix) && !kvPrefixCovers(scope, prefix)) {
       throw new ReplicaError(
@@ -17706,9 +18136,9 @@ var Replica = class {
     return { notBefore: authority.notBefore, expiresAt: authority.expiresAt };
   }
   async #syncUnder(attempt, limit) {
-    const state = await this.#state();
-    const { config } = state;
-    this.#syncWindow(attempt.promote === null ? state.authority : null, attempt.grant);
+    const state2 = await this.#state();
+    const { config } = state2;
+    this.#syncWindow(attempt.promote === null ? state2.authority : null, attempt.grant);
     const report = {
       pages: 0,
       changes: 0,
@@ -17717,14 +18147,14 @@ var Replica = class {
       contentMissing: 0,
       repaired: 0,
       resets: 0,
-      coverage: state.coverage,
+      coverage: state2.coverage,
       cursorAdvanced: false,
       promotedGrant: false,
       blobsCollected: 0
     };
-    let cursor = state.cursor;
-    let pinned = state.nodeDid;
-    let coverage = state.coverage;
+    let cursor = state2.cursor;
+    let pinned = state2.nodeDid;
+    let coverage = state2.coverage;
     const retentionGrantCid = config.retentionGrantCid;
     for (; ; ) {
       let page;
@@ -17885,17 +18315,17 @@ var Replica = class {
       }
       await this.#store.renewLease(attempt.lease, this.#leaseTtlMs);
       if (changes.length === 0) continue;
-      const state = await this.#state();
+      const state2 = await this.#state();
       await this.#store.applyPage(attempt.lease, {
         changes,
         blobs,
         cursor,
-        source: { nodeDid: nodeDid ?? "", space: state.config.space, prefix: state.config.prefix },
+        source: { nodeDid: nodeDid ?? "", space: state2.config.space, prefix: state2.config.prefix },
         authority: null,
         coverage,
         at: new Date(this.#now()).toISOString(),
         retentionGrantCid,
-        window: this.#syncWindow(state.authority, attempt.grant),
+        window: this.#syncWindow(state2.authority, attempt.grant),
         complete: false,
         promoteGrant: null
       });
@@ -18062,7 +18492,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;
   }
@@ -18084,8 +18514,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}.`,
@@ -18238,7 +18669,7 @@ function kvSyncTransport(kv) {
 import { randomBytes as randomBytes2 } from "crypto";
 import { constants as fsConstants } from "fs";
 import { chmod as chmod3, link, mkdir as mkdir2, open as open2, readFile as readFile4, readdir as readdir3, rm as rm3, rmdir as rmdir2, stat as stat2, unlink } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join7 } from "path";
 var ReplicaErrorCode2 = {
   /** Another process holds the sync lease. */
   BUSY: "REPLICA_BUSY",
@@ -18325,11 +18756,11 @@ function effectiveAuthority2(input) {
   const notBefore = maxIso2(input.window?.notBefore ?? null, input.grant?.notBefore ?? null);
   const expiresAt = minIso2(input.window?.expiresAt ?? null, input.grant?.expiresAt ?? null);
   const retainUntil = input.policy === "retainAfterExpiry" ? input.window?.retainUntil ?? null : null;
-  let state = "valid";
-  if (input.revoked !== null) state = "revoked";
-  else if (notBefore !== null && input.now < Date.parse(notBefore)) state = "not-yet-valid";
-  else if (expiresAt !== null && input.now >= Date.parse(expiresAt)) state = "expired";
-  return { state, notBefore, expiresAt, retainUntil, retentionRevoked: (input.retentionRevoked ?? null) !== null };
+  let state2 = "valid";
+  if (input.revoked !== null) state2 = "revoked";
+  else if (notBefore !== null && input.now < Date.parse(notBefore)) state2 = "not-yet-valid";
+  else if (expiresAt !== null && input.now >= Date.parse(expiresAt)) state2 = "expired";
+  return { state: state2, notBefore, expiresAt, retainUntil, retentionRevoked: (input.retentionRevoked ?? null) !== null };
 }
 function wrap(native) {
   const statements = /* @__PURE__ */ new Map();
@@ -18348,8 +18779,20 @@ function wrap(native) {
     get: (sql, ...params) => prepared(sql).get(...params) ?? void 0,
     all: (sql, ...params) => prepared(sql).all(...params),
     close: () => {
-      statements.clear();
-      native.close();
+      let failure;
+      try {
+        for (const statement of statements.values()) {
+          try {
+            statement.finalize?.();
+          } catch (error) {
+            failure ??= error;
+          }
+        }
+      } finally {
+        statements.clear();
+        native.close();
+      }
+      if (failure !== void 0) throw failure;
     }
   };
 }
@@ -18363,7 +18806,7 @@ async function loadSqlite() {
   if (runtime.Bun !== void 0) {
     const module2 = await load(["bun", "sqlite"].join(":"));
     const Database = module2.Database;
-    return (path) => wrap(new Database(path, { create: true }));
+    return (path, options) => wrap(new Database(path, { create: !options?.readonly, ...options?.readonly ? { readonly: true } : {} }));
   }
   const version = runtime.process?.versions?.node ?? "0.0.0";
   if (!nodeSqliteSupported(version)) {
@@ -18388,7 +18831,7 @@ async function loadSqlite() {
     process2.emitWarning = emitWarning;
   }
   const DatabaseSync = module.DatabaseSync;
-  return (path) => wrap(new DatabaseSync(path));
+  return (path, options) => wrap(options?.readonly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path));
 }
 var SCHEMA_VERSION = 1;
 var DURABILITY = "sqlite-wal-synchronous-full+fsynced-blobs";
@@ -18506,12 +18949,60 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
     this.#faults = options[FAULTS] ?? {};
     this.#guard = options.guard ?? ((section) => section());
   }
+  /**
+   * Read-only status snapshot; does not create a replica, migrate, recover
+   * revocation cleanup, or enter the mutation guard. An existing database is
+   * opened normally in read-only WAL mode so committed WAL state is visible.
+   */
+  static async inspect(dir, options = {}) {
+    const checkAbort = () => {
+      if (options.signal?.aborted) throw options.signal.reason ?? new ReplicaError2(ReplicaErrorCode2.CLOSED, "Replica status inspection was cancelled.");
+    };
+    checkAbort();
+    const dbPath = join7(dir, "replica.db");
+    let ino;
+    try {
+      ino = (await stat2(dbPath)).ino;
+    } catch (error) {
+      if (errnoOf(error) === "ENOENT") return null;
+      throw storageError(error, "Inspecting the replica");
+    }
+    checkAbort();
+    const opener = await loadSqlite();
+    checkAbort();
+    let db;
+    try {
+      db = opener(dbPath, { readonly: true });
+      db.exec("PRAGMA busy_timeout = 0");
+      checkAbort();
+      const store = new _SqliteReplicaStore(dir, db, ino, { create: false, ...options.now ? { now: options.now } : {} });
+      for (let attempt = 0; attempt < 2; attempt++) {
+        const before = db.get("PRAGMA data_version").data_version;
+        const state2 = await store.open();
+        checkAbort();
+        if (state2 === null) return null;
+        const status = await store.status();
+        await new Promise((resolve5) => setImmediate(resolve5));
+        checkAbort();
+        const after = db.get("PRAGMA data_version").data_version;
+        if (before === after) return { state: state2, status };
+      }
+      throw new ReplicaError2(ReplicaErrorCode2.BUSY, "The replica changed during status inspection.");
+    } catch (error) {
+      if (/SQLITE_BUSY|database is locked/i.test(error instanceof Error ? error.message : String(error))) {
+        throw new ReplicaError2(ReplicaErrorCode2.BUSY, "The replica is busy during status inspection.", void 0, { cause: error });
+      }
+      throw storageError(error, "Inspecting the replica");
+    } finally {
+      db?.close();
+    }
+  }
   /**
    * Open the replica store in `dir`. With `create: false` a missing replica is
    * REPLICA_NOT_FOUND and nothing is written to disk.
    */
   static async open(dir, options) {
-    const dbPath = join5(dir, "replica.db");
+    const dbPath = join7(dir, "replica.db");
     if (!options.create) {
       const exists = await stat2(dbPath).then(
         () => true,
@@ -18523,8 +19014,8 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
     let store;
     try {
       if (options.create) {
-        await mkdir2(join5(dir, "blobs", ".tmp"), { recursive: true, mode: 448 });
-        await Promise.all([chmod3(dir, 448), chmod3(join5(dir, "blobs"), 448), chmod3(join5(dir, "blobs", ".tmp"), 448)]);
+        await mkdir2(join7(dir, "blobs", ".tmp"), { recursive: true, mode: 448 });
+        await Promise.all([chmod3(dir, 448), chmod3(join7(dir, "blobs"), 448), chmod3(join7(dir, "blobs", ".tmp"), 448)]);
         const handle = await open2(dbPath, fsConstants.O_CREAT | fsConstants.O_RDWR, 384);
         await handle.close();
         await chmod3(dbPath, 384);
@@ -18565,7 +19056,7 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
   }
   /** Refuse to touch the filesystem for a replica that was deleted (or replaced) under us. */
   async #assertPresent() {
-    const ino = await stat2(join5(this.dir, "replica.db")).then(
+    const ino = await stat2(join7(this.dir, "replica.db")).then(
       (stats) => stats.ino,
       () => void 0
     );
@@ -18797,7 +19288,7 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
     return held;
   }
   #blobPath(hash) {
-    return join5(this.dir, "blobs", hash.slice(0, 2), hash);
+    return join7(this.dir, "blobs", hash.slice(0, 2), hash);
   }
   /**
    * Make every blob durable before any row references it: write to a fresh
@@ -18814,11 +19305,11 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
         () => false
       );
       if (exists) continue;
-      const shard = join5(this.dir, "blobs", hash.slice(0, 2));
+      const shard = join7(this.dir, "blobs", hash.slice(0, 2));
       await mkdir2(shard, { mode: 448 }).catch((error) => {
         if (errnoOf(error) !== "EEXIST") throw error;
       });
-      const temp = join5(this.dir, "blobs", ".tmp", `${hash}.${randomBytes2(6).toString("hex")}`);
+      const temp = join7(this.dir, "blobs", ".tmp", `${hash}.${randomBytes2(6).toString("hex")}`);
       const handle = await open2(temp, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 384);
       try {
         await handle.writeFile(bytes);
@@ -18834,7 +19325,7 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
         await unlink(temp);
       }
       dirs.add(shard);
-      dirs.add(join5(this.dir, "blobs"));
+      dirs.add(join7(this.dir, "blobs"));
     }
     for (const dir of dirs) {
       const handle = await open2(dir, fsConstants.O_RDONLY);
@@ -18942,12 +19433,12 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
   /** Unlink every blob not in `keep`, and every temp file. Only a missing directory counts as empty. */
   async #unlinkBlobs(keep) {
     let removed = 0;
-    const root = join5(this.dir, "blobs");
+    const root = join7(this.dir, "blobs");
     for (const shard of await entriesOf(root)) {
-      const shardPath = join5(root, shard);
+      const shardPath = join7(root, shard);
       if (shard === ".tmp") {
         for (const name of await entriesOf(shardPath)) {
-          await rm3(join5(shardPath, name), { force: true });
+          await rm3(join7(shardPath, name), { force: true });
           removed += 1;
         }
         continue;
@@ -18958,7 +19449,7 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
           kept += 1;
           continue;
         }
-        await rm3(join5(shardPath, name), { force: true });
+        await rm3(join7(shardPath, name), { force: true });
         removed += 1;
       }
       if (kept === 0) await rmdir2(shardPath).catch(() => void 0);
@@ -18967,9 +19458,9 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
   }
   /** Whether any content file (a blob or a temp file) is on disk. */
   async #holdsContentFiles() {
-    const root = join5(this.dir, "blobs");
+    const root = join7(this.dir, "blobs");
     for (const shard of await entriesOf(root)) {
-      if ((await entriesOf(join5(root, shard))).length > 0) return true;
+      if ((await entriesOf(join7(root, shard))).length > 0) return true;
     }
     return false;
   }
@@ -19150,8 +19641,8 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
     }
   }
   async status(now = this.#now()) {
-    const state = await this.open();
-    if (state === null) throw new ReplicaError2(ReplicaErrorCode2.NOT_FOUND, "The replica has not been created.");
+    const state2 = await this.open();
+    if (state2 === null) throw new ReplicaError2(ReplicaErrorCode2.NOT_FOUND, "The replica has not been created.");
     const row = this.#row();
     const counts = this.#db.get(
       `SELECT
@@ -19162,41 +19653,41 @@ var SqliteReplicaStore = class _SqliteReplicaStore {
        FROM entry`
     );
     const { retentionRevoked: _retentionRevoked, ...authority } = effectiveAuthority2({
-      window: state.authority,
-      grant: state.grant,
-      revoked: state.revoked,
-      retentionRevoked: state.retentionRevoked,
-      policy: state.config.localReadPolicy,
+      window: state2.authority,
+      grant: state2.grant,
+      revoked: state2.revoked,
+      retentionRevoked: state2.retentionRevoked,
+      policy: state2.config.localReadPolicy,
       now
     });
     return {
-      name: state.config.name,
-      replicaId: state.config.replicaId,
-      source: { host: state.config.host, nodeDid: state.nodeDid, space: state.config.space, prefix: state.config.prefix },
+      name: state2.config.name,
+      replicaId: state2.config.replicaId,
+      source: { host: state2.config.host, nodeDid: state2.nodeDid, space: state2.config.space, prefix: state2.config.prefix },
       device: {
-        did: state.config.deviceDid,
-        delegationCid: state.grant?.cid ?? null,
-        pendingDelegationCid: state.pendingGrant?.cid ?? null,
-        pendingDelegationError: state.pendingGrantError
+        did: state2.config.deviceDid,
+        delegationCid: state2.grant?.cid ?? null,
+        pendingDelegationCid: state2.pendingGrant?.cid ?? null,
+        pendingDelegationError: state2.pendingGrantError
       },
       authority: {
         ...authority,
-        localReadPolicy: state.config.localReadPolicy,
-        retentionGrantCid: state.config.retentionGrantCid,
-        revokedDetail: state.revoked,
-        retentionRevokedDetail: state.retentionRevoked
+        localReadPolicy: state2.config.localReadPolicy,
+        retentionGrantCid: state2.config.retentionGrantCid,
+        revokedDetail: state2.revoked,
+        retentionRevokedDetail: state2.retentionRevoked
       },
       consistency: "observed",
-      coverage: state.coverage,
-      lastSyncAt: state.lastSyncAt,
-      lastCompleteAt: state.lastCompleteAt,
+      coverage: state2.coverage,
+      lastSyncAt: state2.lastSyncAt,
+      lastCompleteAt: state2.lastCompleteAt,
       counts: { keys: Number(counts.keys), contentMissing: Number(counts.missing), tombstones: Number(counts.tombstones) },
       bytes: Number(counts.bytes),
       durability: DURABILITY,
       syncing: row.lease_holder !== null && row.lease_expires_at !== null && row.lease_expires_at > now,
       purgePending: row.purge_pending === 1,
-      lastError: state.lastError,
-      lastReset: state.lastReset
+      lastError: state2.lastError,
+      lastReset: state2.lastReset
     };
   }
   async close() {
@@ -19229,14 +19720,14 @@ async function safeReplicaRoot(profile, root) {
   if (!rootStats.isDirectory()) {
     throw refuseUnsafeReplicaPath(profile, `the replicas path "${root}" is not a real directory`);
   }
-  const [profileRealPath, rootRealPath] = await Promise.all([realpath(profilePath2(profile)), realpath(root)]);
+  const [profileRealPath, rootRealPath] = await Promise.all([realpath(profilePath3(profile)), realpath(root)]);
   if (!rootRealPath.startsWith(profileRealPath + sep)) {
     throw refuseUnsafeReplicaPath(profile, `the replicas directory "${root}" resolves outside the selected profile`);
   }
   return rootRealPath;
 }
 async function safeReplicaEntry(profile, root, entry) {
-  const entryPath = join6(root, entry.name);
+  const entryPath = join8(root, entry.name);
   const rootRealPath = await safeReplicaRoot(profile, root);
   if (rootRealPath === null) {
     throw refuseUnsafeReplicaPath(profile, `the replicas directory "${root}" disappeared`);
@@ -19254,9 +19745,9 @@ async function safeReplicaEntry(profile, root, entry) {
   }
   return entryPath;
 }
-async function removeProfileReplicas(profile) {
-  return withProfileLock3(profile, async () => {
-    const root = join6(profilePath2(profile), "replicas");
+async function removeProfileReplicas(profile, heldLeases) {
+  return withProfileLock4(profile, async () => {
+    const root = join8(profilePath3(profile), "replicas");
     if (await safeReplicaRoot(profile, root) === null) return [];
     const replicas = (await readdir4(root, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
     if (replicas.length === 0) return [];
@@ -19270,7 +19761,7 @@ async function removeProfileReplicas(profile) {
           create: false,
           guard: async (action) => {
             try {
-              return await withProfileLock3(profile, action, { requireProfile: true });
+              return await withProfileLock4(profile, action, { requireProfile: true });
             } catch (error) {
               if (error instanceof ProfileDeletedError2) {
                 throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, `Profile "${profile}" was deleted; its replicas are gone and nothing was written.`);
@@ -19283,7 +19774,7 @@ async function removeProfileReplicas(profile) {
         if (await store.open() === null) {
           throw new CLIError("REPLICA_PURGE_FAILED", `Replica "${entry.name}" has no initialized store; logout cleared the session but removed no replicas.`, ExitCode.ERROR);
         }
-        const lease = await store.acquireSyncLease(SYNC_LEASE_MS);
+        const lease = heldLeases?.get(entryPath) ?? await store.acquireSyncLease(SYNC_LEASE_MS);
         if (lease === null) {
           throw new CLIError("REPLICA_BUSY", `Cannot log out: replica "${entry.name}" is syncing. The session was cleared and no replicas were removed.`, ExitCode.ERROR);
         }
@@ -19295,7 +19786,7 @@ async function removeProfileReplicas(profile) {
           await replica.store.destroy(replica.lease);
           removed.push(replica.name);
         } catch (error) {
-          const replicaStillExists = await lstat2(join6(root, replica.name)).then(
+          const replicaStillExists = await lstat2(join8(root, replica.name)).then(
             () => true,
             (statError) => statError.code !== "ENOENT"
           );
@@ -19318,8 +19809,248 @@ async function removeProfileReplicas(profile) {
         ExitCode.ERROR
       );
     } finally {
+      await Promise.all(opened.map(async ({ name, store, lease }) => {
+        if (lease !== null && heldLeases?.has(join8(root, name)) !== true) await store.releaseLease(lease).catch(() => void 0);
+        await store.close().catch(() => void 0);
+      }));
+    }
+  });
+}
+async function removeProfileReplication(profile, heldLeases) {
+  return withProfileLock4(profile, async () => {
+    const root = join8(profilePath3(profile), "replication");
+    const rootReal = await safeReplicaRoot(profile, root);
+    if (rootReal === null) return [];
+    const profileReal = await realpath(profilePath3(profile));
+    const partitions = await readdir4(root, { withFileTypes: true });
+    const opened = [];
+    const removed = [];
+    let deleting = false;
+    try {
+      for (const partition of partitions) {
+        const partitionPath = join8(root, partition.name);
+        const partitionStats = await lstat2(partitionPath);
+        if (partition.isSymbolicLink() || partitionStats.isSymbolicLink()) {
+          throw refuseUnsafeReplicaPath(profile, `replication entry "${partition.name}" is a symlink`);
+        }
+        if (partitionStats.isDirectory()) {
+          const partitionReal = await realpath(partitionPath);
+          if (!partitionReal.startsWith(rootReal + sep) || !partitionReal.startsWith(profileReal + sep)) {
+            throw refuseUnsafeReplicaPath(profile, `replication entry "${partition.name}" resolves outside the selected profile`);
+          }
+          const replicasRoot2 = join8(partitionPath, "replicas");
+          const replicasStats = await lstat2(replicasRoot2).catch((error) => {
+            if (error.code === "ENOENT") return null;
+            throw error;
+          });
+          if (!replicasStats) continue;
+          if (replicasStats.isSymbolicLink() || !replicasStats.isDirectory()) {
+            throw refuseUnsafeReplicaPath(profile, `replication replicas path "${replicasRoot2}" is not a real directory`);
+          }
+          const replicas = await readdir4(replicasRoot2, { withFileTypes: true });
+          for (const replica of replicas) {
+            const replicaPath = join8(replicasRoot2, replica.name);
+            const replicaStats = await lstat2(replicaPath);
+            if (replica.isSymbolicLink() || replicaStats.isSymbolicLink() || !replicaStats.isDirectory()) {
+              throw refuseUnsafeReplicaPath(profile, `replication replica "${replica.name}" is not a real directory`);
+            }
+            const replicaReal = await realpath(replicaPath);
+            if (!replicaReal.startsWith(rootReal + sep)) {
+              throw refuseUnsafeReplicaPath(profile, `replication replica "${replica.name}" resolves outside the replication root`);
+            }
+            const database = await lstat2(join8(replicaPath, "replica.db")).catch((error) => {
+              if (error.code === "ENOENT") return null;
+              throw error;
+            });
+            if (!database) continue;
+            if (database.isSymbolicLink() || !database.isFile()) {
+              throw refuseUnsafeReplicaPath(profile, `replication database "${replica.name}" is not a regular file`);
+            }
+          }
+        } else if (!partitionStats.isFile()) {
+          throw refuseUnsafeReplicaPath(profile, `replication path "${partition.name}" is not a regular file or directory`);
+        }
+      }
+      const hasReplicaDatabase = await Promise.all(partitions.filter((entry) => entry.isDirectory()).map(async (partition) => {
+        return Promise.all((await readdir4(join8(root, partition.name, "replicas"), { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map((entry) => lstat2(join8(root, partition.name, "replicas", entry.name, "replica.db")).then(() => true, () => false)));
+      })).then((values) => values.some((partition) => partition.some(Boolean)));
+      if (hasReplicaDatabase) await loadSqlite();
+      for (const partition of partitions.filter((entry) => entry.isDirectory())) {
+        const replicasRoot2 = join8(root, partition.name, "replicas");
+        for (const entry of await readdir4(replicasRoot2, { withFileTypes: true }).catch(() => [])) {
+          if (!entry.isDirectory()) continue;
+          const database = await lstat2(join8(replicasRoot2, entry.name, "replica.db")).catch((error) => {
+            if (error.code === "ENOENT") return null;
+            throw error;
+          });
+          if (!database) continue;
+          const name = `replication/${partition.name}/${entry.name}`;
+          const store = await SqliteReplicaStore.open(join8(replicasRoot2, entry.name), { create: false, guard: async (action) => withProfileLock4(profile, action, { requireProfile: true }) });
+          if (await store.open() === null) {
+            await store.close();
+            throw new CLIError("REPLICA_PURGE_FAILED", `Logout cleared the session, but flag replica "${name}" has no initialized store.`, ExitCode.ERROR);
+          }
+          const lease = heldLeases?.get(join8(replicasRoot2, entry.name)) ?? await store.acquireSyncLease(SYNC_LEASE_MS);
+          if (lease === null) {
+            await store.close();
+            throw new CLIError("REPLICA_BUSY", `Cannot log out: flag replica "${name}" is syncing. The session was cleared and no replicas were removed.`, ExitCode.ERROR);
+          }
+          opened.push({ name, path: join8(replicasRoot2, entry.name), store, lease });
+        }
+      }
+      deleting = true;
+      for (const item of opened) {
+        await item.store.destroy(item.lease);
+        removed.push(item.name);
+      }
+      await rm4(root, { recursive: true });
+      return removed;
+    } catch (error) {
+      if (deleting) {
+        const remaining = opened.filter(({ name }) => !removed.includes(name)).map(({ name }) => name);
+        throw new CLIError(
+          "REPLICA_PURGE_FAILED",
+          `Logout cleared the session, but replication cleanup failed. Removed: ${removed.join(", ") || "none"}. Not removed: ${remaining.join(", ") || "none"}. ${error instanceof Error ? error.message : String(error)}`,
+          ExitCode.ERROR,
+          { replicasRemoved: removed, replicasRemaining: remaining }
+        );
+      }
+      if (error instanceof CLIError) throw error;
+      throw new CLIError("REPLICA_PURGE_FAILED", `Logout cleared the session, but replication cleanup failed; no flag replicas were removed. ${error instanceof Error ? error.message : String(error)}`, ExitCode.ERROR);
+    } finally {
+      await Promise.all(opened.map(async ({ path, store, lease }) => {
+        if (heldLeases?.has(path) !== true) await store.releaseLease(lease).catch(() => void 0);
+        await store.close().catch(() => void 0);
+      }));
+    }
+  });
+}
+async function acquireLogoutLeases(profile) {
+  return withProfileLock4(profile, async () => {
+    let sqliteLoaded = false;
+    const opened = [];
+    try {
+      const legacyRoot = join8(profilePath3(profile), "replicas");
+      if (await safeReplicaRoot(profile, legacyRoot) !== null) {
+        const entries = (await readdir4(legacyRoot, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+          const path = await safeReplicaEntry(profile, legacyRoot, entry);
+          if (!sqliteLoaded) {
+            await loadSqlite();
+            sqliteLoaded = true;
+          }
+          const store = await SqliteReplicaStore.open(path, { create: false, guard: async (action) => withProfileLock4(profile, action, { requireProfile: true }) });
+          if (await store.open() === null) {
+            await store.close();
+            throw new CLIError("REPLICA_PURGE_FAILED", `Replica "${entry.name}" has no initialized store; logout cleared the session but removed no replicas.`, ExitCode.ERROR);
+          }
+          const lease = await store.acquireSyncLease(SYNC_LEASE_MS);
+          if (lease === null) {
+            await store.close();
+            throw new CLIError("REPLICA_BUSY", `Cannot log out: replica "${entry.name}" is syncing. The session was cleared and no replicas were removed.`, ExitCode.ERROR);
+          }
+          opened.push({ path, store, lease });
+        }
+      }
+      const replicationRoot = join8(profilePath3(profile), "replication");
+      const replicationReal = await safeReplicaRoot(profile, replicationRoot);
+      if (replicationReal !== null) {
+        const partitions = await readdir4(replicationRoot, { withFileTypes: true });
+        for (const partition of partitions) {
+          const partitionPath = join8(replicationRoot, partition.name);
+          const partitionStats = await lstat2(partitionPath);
+          if (partition.isSymbolicLink() || partitionStats.isSymbolicLink()) {
+            throw refuseUnsafeReplicaPath(profile, `replication entry "${partition.name}" is a symlink`);
+          }
+          if (!partitionStats.isDirectory()) {
+            if (!partitionStats.isFile()) throw refuseUnsafeReplicaPath(profile, `replication path "${partition.name}" is not a regular file or directory`);
+            continue;
+          }
+          const partitionReal = await realpath(partitionPath);
+          if (!partitionReal.startsWith(replicationReal + sep)) {
+            throw refuseUnsafeReplicaPath(profile, `replication entry "${partition.name}" resolves outside the replication root`);
+          }
+          const replicasRoot2 = join8(partitionPath, "replicas");
+          const replicasStats = await lstat2(replicasRoot2).catch((error) => {
+            if (error.code === "ENOENT") return null;
+            throw error;
+          });
+          if (!replicasStats) continue;
+          if (replicasStats.isSymbolicLink() || !replicasStats.isDirectory()) {
+            throw refuseUnsafeReplicaPath(profile, `replication replicas path "${replicasRoot2}" is not a real directory`);
+          }
+          for (const replica of await readdir4(replicasRoot2, { withFileTypes: true })) {
+            const path = join8(replicasRoot2, replica.name);
+            const stats = await lstat2(path);
+            if (!replica.isDirectory() || replica.isSymbolicLink() || stats.isSymbolicLink() || !stats.isDirectory()) {
+              throw refuseUnsafeReplicaPath(profile, `replication replica "${replica.name}" is not a real directory`);
+            }
+            const database = await lstat2(join8(path, "replica.db")).catch((error) => {
+              if (error.code === "ENOENT") return null;
+              throw error;
+            });
+            if (!database) continue;
+            if (database.isSymbolicLink() || !database.isFile()) {
+              throw refuseUnsafeReplicaPath(profile, `replication database "${replica.name}" is not a regular file`);
+            }
+            const replicaReal = await realpath(path);
+            if (!replicaReal.startsWith(replicationReal + sep)) {
+              throw refuseUnsafeReplicaPath(profile, `replication replica "${replica.name}" resolves outside the replication root`);
+            }
+            if (!sqliteLoaded) {
+              await loadSqlite();
+              sqliteLoaded = true;
+            }
+            const store = await SqliteReplicaStore.open(path, { create: false, guard: async (action) => withProfileLock4(profile, action, { requireProfile: true }) });
+            if (await store.open() === null) {
+              await store.close();
+              throw new CLIError("REPLICA_PURGE_FAILED", `Logout cleared the session, but flag replica "replication/${partition.name}/${replica.name}" has no initialized store.`, ExitCode.ERROR);
+            }
+            const lease = await store.acquireSyncLease(SYNC_LEASE_MS);
+            if (lease === null) {
+              await store.close();
+              throw new CLIError("REPLICA_BUSY", `Cannot log out: flag replica "replication/${partition.name}/${replica.name}" is syncing. The session was cleared and no replicas were removed.`, ExitCode.ERROR);
+            }
+            opened.push({ path, store, lease });
+          }
+        }
+      }
+      return opened;
+    } catch (error) {
       await Promise.all(opened.map(async ({ store, lease }) => {
-        if (lease !== null) await store.releaseLease(lease).catch(() => void 0);
+        await store.releaseLease(lease).catch(() => void 0);
+        await store.close().catch(() => void 0);
+      }));
+      throw error;
+    }
+  });
+}
+async function removeProfileReplicasAndReplication(profile) {
+  return withProfileLock4(profile, async () => {
+    const acquired = await acquireLogoutLeases(profile);
+    const heldLeases = new Map(acquired.map(({ path, lease }) => [path, lease]));
+    let legacyRemoved = [];
+    try {
+      legacyRemoved = await removeProfileReplicas(profile, heldLeases);
+      const replication = await removeProfileReplication(profile, heldLeases);
+      return [...legacyRemoved, ...replication];
+    } catch (error) {
+      const partialRemoved = error instanceof CLIError && Array.isArray(error.metadata?.replicasRemoved) ? error.metadata.replicasRemoved.filter((name) => typeof name === "string") : [];
+      const removed = [.../* @__PURE__ */ new Set([...legacyRemoved, ...partialRemoved])];
+      const removedSet = new Set(removed);
+      const remaining = acquired.map(({ path }) => {
+        const name = relative(profilePath3(profile), path).split(sep).join("/");
+        return name.startsWith("replication/") ? name.replace("/replicas/", "/") : name.split("/").at(-1);
+      }).filter((name) => !removedSet.has(name));
+      throw new CLIError(
+        error instanceof CLIError ? error.code : "REPLICA_PURGE_FAILED",
+        `Logout cleared the session, but replica cleanup failed. Removed: ${removed.join(", ") || "none"}. Not removed: ${remaining.join(", ") || "none"}.`,
+        error instanceof CLIError ? error.exitCode : ExitCode.ERROR,
+        { replicasRemoved: removed, replicasRemaining: remaining }
+      );
+    } finally {
+      await Promise.all(acquired.map(async ({ store, lease }) => {
+        await store.releaseLease(lease).catch(() => void 0);
         await store.close().catch(() => void 0);
       }));
     }
@@ -19648,6 +20379,7 @@ import {
 } from "crypto";
 
 // src/auth/local-key.ts
+init_replication_config();
 import { TCWSessionManager, importKey, initPanicHook } from "@tinycloud/node-sdk-wasm";
 import { PrivateKeySigner } from "@tinycloud/node-sdk";
 import { randomBytes as randomBytes3 } from "crypto";
@@ -19693,10 +20425,18 @@ async function generateLocalIdentity(chainId = 1) {
 }
 async function localKeySignIn(options) {
   const { TinyCloudNode: TinyCloudNode3 } = await import("@tinycloud/node-sdk");
+  const profile = options.profile ?? "default";
+  const replication = createCliReplicationConfig(
+    profile,
+    options.replication,
+    { debug: false, quiet: true },
+    options.replication !== void 0
+  );
   const node = new TinyCloudNode3({
     privateKey: options.privateKey,
     host: options.host,
-    autoCreateSpace: true
+    autoCreateSpace: true,
+    ...replication ? { replication } : {}
   });
   await node.signIn();
   const address = await new PrivateKeySigner(options.privateKey).getAddress();
@@ -19826,6 +20566,15 @@ function sessionExpiresAt(session) {
 function ownerSpaceId(space, ownerDid) {
   return space.startsWith("tinycloud:") ? space : `tinycloud:${ownerDid.slice("did:".length)}:${space}`;
 }
+function sameLoginSpace(left, right, ownerDid) {
+  const normalizedLeft = normalizePkhIdentifier(ownerDid === void 0 ? left : ownerSpaceId(left, ownerDid));
+  const normalizedRight = normalizePkhIdentifier(ownerDid === void 0 ? right : ownerSpaceId(right, ownerDid));
+  if (normalizedLeft === normalizedRight) return true;
+  if (ownerDid !== void 0) return false;
+  if (left.startsWith("tinycloud:") && !right.startsWith("tinycloud:")) return left.split(":").at(-1) === right;
+  if (right.startsWith("tinycloud:") && !left.startsWith("tinycloud:")) return right.split(":").at(-1) === left;
+  return false;
+}
 function permissionTuples(permissions, ownerDid) {
   return new Set(permissions.flatMap((permission) => actionTuples(permission, ownerDid)));
 }
@@ -20091,11 +20840,11 @@ function assertSessionReplaceable(profileName2, snapshot, ownerDid, scope, newEx
     ExitCode.USAGE_ERROR
   );
 }
-async function restore(profileName2, state) {
+async function restore(profileName2, state2) {
   const writes = [
-    () => state.key === null ? ProfileManager.removeKey(profileName2) : ProfileManager.setKey(profileName2, state.key),
-    () => state.session === null ? ProfileManager.clearSession(profileName2) : ProfileManager.setSession(profileName2, state.session),
-    () => state.profile === null ? ProfileManager.removeProfileConfig(profileName2) : ProfileManager.setProfile(profileName2, state.profile)
+    () => state2.key === null ? ProfileManager.removeKey(profileName2) : ProfileManager.setKey(profileName2, state2.key),
+    () => state2.session === null ? ProfileManager.clearSession(profileName2) : ProfileManager.setSession(profileName2, state2.session),
+    () => state2.profile === null ? ProfileManager.removeProfileConfig(profileName2) : ProfileManager.setProfile(profileName2, state2.profile)
   ];
   const failures = [];
   for (const write of writes) {
@@ -21017,6 +21766,79 @@ init_session_expired();
 init_delegation_expiry();
 init_space();
 init_permissions();
+
+// src/auth/replication-login.ts
+import { grantPathsForSelector, isCapabilitySubset } from "@tinycloud/sdk-core";
+init_errors();
+init_constants();
+function unconstrained(caveats) {
+  return (caveats ?? []).every((caveat) => Object.keys(caveat).length === 0);
+}
+function addReplicationLoginEntries(request, primarySpace, options) {
+  const result = [...request];
+  for (const prefix of options.prefixes) {
+    if (requiresSecretsOptIn(primarySpace, prefix) && options.allowSecrets !== true) {
+      throw new CLIError("SECRETS_OPT_IN_REQUIRED", `Replication prefix ${JSON.stringify(prefix)} in ${primarySpace} requires --replication-allow-secrets.`, ExitCode.USAGE_ERROR);
+    }
+    const requested = {
+      service: "tinycloud.kv",
+      space: primarySpace,
+      path: prefix,
+      actions: ["tinycloud.kv/get"]
+    };
+    const required = grantPathsForSelector(prefix).map((path) => ({ ...requested, path }));
+    const matching = request.filter(
+      (entry) => sameLoginSpace(entry.space ?? "", primarySpace, options.ownerDid)
+    );
+    const authority = matching.map((entry) => {
+      const { caveats: _caveats, ...grant } = entry;
+      return { ...grant, space: primarySpace };
+    });
+    if (!isCapabilitySubset(required, authority).subset) {
+      const caveatedAtRequestedPath = matching.filter((entry) => !unconstrained(entry.caveats)).map((entry) => {
+        const { caveats: _caveats, ...grant } = entry;
+        return { ...grant, space: primarySpace };
+      });
+      if (isCapabilitySubset([requested], caveatedAtRequestedPath).subset) {
+        throw new CLIError("REPLICATION_PREFIX_CAVEATED", `Replication prefix ${JSON.stringify(prefix)} is covered only by caveated get authority.`, ExitCode.USAGE_ERROR);
+      }
+      throw new CLIError("REPLICATION_PREFIX_OUTSIDE_SCOPE", `Replication prefix ${JSON.stringify(prefix)} has no covering get in the login request.`, ExitCode.USAGE_ERROR);
+    }
+    const unrestricted = matching.filter((entry) => unconstrained(entry.caveats)).map((entry) => {
+      const { caveats: _caveats, ...grant } = entry;
+      return { ...grant, space: primarySpace };
+    });
+    if (!isCapabilitySubset(required, unrestricted).subset) {
+      throw new CLIError("REPLICATION_PREFIX_CAVEATED", `Replication prefix ${JSON.stringify(prefix)} is covered only by caveated get authority.`, ExitCode.USAGE_ERROR);
+    }
+    const service = "tinycloud.kv";
+    const actions = [`${service}/get`, `${service}/sync`];
+    for (const path of grantPathsForSelector(prefix)) {
+      const existing = result.find((entry) => entry.service === service && entry.space === primarySpace && entry.path === path && actions.every((action) => entry.actions.includes(action)) && unconstrained(entry.caveats));
+      if (!existing) result.push({ service, space: primarySpace, path, actions });
+    }
+  }
+  return result;
+}
+function buildReplicationLoginRequest(request, options) {
+  if (options.prefixes.length === 0) return request;
+  if (request === void 0) {
+    const space = options.ownerDid === void 0 ? "default" : ownerSpaceId("default", options.ownerDid);
+    const defaults = options.ownerDid === void 0 ? [
+      { service: "tinycloud.kv", space, path: "", actions: ["tinycloud.kv/put", "tinycloud.kv/get", "tinycloud.kv/del", "tinycloud.kv/list", "tinycloud.kv/metadata"] },
+      { service: "tinycloud.sql", space, path: "", actions: ["tinycloud.sql/read", "tinycloud.sql/write", "tinycloud.sql/admin"] },
+      { service: "tinycloud.capabilities", space, path: "", actions: ["tinycloud.capabilities/read"] }
+    ] : ownerLoginPermissions(options.ownerDid);
+    return addReplicationLoginEntries(defaults, space, options);
+  }
+  const primary = request.find((entry) => entry.service === "tinycloud.kv" && entry.space !== void 0)?.space ?? request.find((entry) => entry.space !== void 0)?.space;
+  if (!primary) {
+    throw new CLIError("INVALID_LOGIN_SCOPE", "Replication login needs a primary space in the requested manifest.", ExitCode.USAGE_ERROR);
+  }
+  return addReplicationLoginEntries(request, primary, options);
+}
+
+// src/commands/auth.ts
 function resolveOpenKeyHost(profile) {
   return process.env.TC_OPENKEY_HOST ?? profile.openkeyHost ?? DEFAULT_OPENKEY_HOST;
 }
@@ -21049,7 +21871,7 @@ async function promptAuthMethod() {
 function registerAuthCommand(program, options) {
   const auth = program.command("auth").description("Authentication management");
   registerAuthGrantsCommand(auth, { openKeyAcquisition: options?.openKeyAcquisition });
-  auth.command("login").description("Authenticate with TinyCloud").option("--device", "Approve on another device (e.g. a phone) through OpenKey device authorization; requires a KV-scoped --manifest (SQL and secret decrypt need browser or --paste login)").option("--paste", "Use manual paste mode instead of browser callback").option("--no-popup", "Print the OpenKey URL without opening a browser").option("--method <method>", "Authentication method: local or openkey").option("--manifest <fileOrBase64>", `Request only this manifest's permissions (one space, plus raw encryption network entries such as a secrets decrypt grant); ${SHARE_PUBLISHING_MANIFEST_REF} covers \`tc share publish\``).option("--expiry <duration>", "OpenKey session lifetime, e.g. 1h or 7d (device login: at most 30d, default 30d)").option("--owner <did>", "Sign in as this owner (did:pkh:eip155:CHAIN:ADDRESS): OpenKey preselects that key, e.g. one that is not the account's primary key, and an approval by any other identity is refused. With --manifest, also names the secrets owner for a manifest's `secrets` on a profile with no recorded owner").option("--replace-session", "Scoped or device login: replace this profile's live session even though the new scope would narrow, change or shorten it (prefer a new profile)").action(async (options2, cmd) => {
+  auth.command("login").description("Authenticate with TinyCloud").option("--device", "Approve on another device (e.g. a phone) through OpenKey device authorization; requires a KV-scoped --manifest (SQL and secret decrypt need browser or --paste login)").option("--paste", "Use manual paste mode instead of browser callback").option("--no-popup", "Print the OpenKey URL without opening a browser").option("--method <method>", "Authentication method: local or openkey").option("--manifest <fileOrBase64>", `Request only this manifest's permissions (one space, plus raw encryption network entries such as a secrets decrypt grant); ${SHARE_PUBLISHING_MANIFEST_REF} covers \`tc share publish\``).option("--expiry <duration>", "OpenKey session lifetime, e.g. 1h or 7d (device login: at most 30d, default 30d)").option("--owner <did>", "Sign in as this owner (did:pkh:eip155:CHAIN:ADDRESS): OpenKey preselects that key, e.g. one that is not the account's primary key, and an approval by any other identity is refused. With --manifest, also names the secrets owner for a manifest's `secrets` on a profile with no recorded owner").option("--replace-session", "Scoped or device login: replace this profile's live session even though the new scope would narrow, change or shorten it (prefer a new profile)").option("--replication-prefix <prefix>", "Add replication get+sync authority for this prefix (repeatable)", (prefix, values = []) => [...values, prefix]).option("--replication-allow-secrets", "Allow replication of secret material (network-wide decrypt warning)").action(async (options2, cmd) => {
     try {
       if (options2.device && options2.paste) {
         throw new CLIError("INVALID_ARGUMENT", "--device and --paste are mutually exclusive.", ExitCode.USAGE_ERROR);
@@ -21069,19 +21891,31 @@ function registerAuthCommand(program, options) {
       const ctx = await ProfileManager.resolveContext(globalOpts, { storedSession: "unused" });
       const owner = options2.owner === void 0 ? void 0 : canonicalOwnerDid(options2.owner);
       const permissions = options2.manifest ? await loadManifestPermissions(options2.manifest, ctx.profile, { allowLogicalSpaces: true, ownerDid: owner, device: options2.device === true }) : void 0;
+      const profileConfig = await ProfileManager.getProfile(ctx.profile).catch((error) => {
+        if (error instanceof CLIError && error.code === "PROFILE_NOT_FOUND") return void 0;
+        throw error;
+      });
+      const replicationOptions = {
+        prefixes: options2.replicationPrefix ?? profileConfig?.replication?.prefixes ?? [],
+        ...options2.replicationAllowSecrets === true || profileConfig?.replication?.allowSecrets === true ? { allowSecrets: true } : {},
+        ...owner === void 0 ? {} : { ownerDid: owner }
+      };
+      const loginPermissions = permissions === void 0 ? void 0 : buildReplicationLoginRequest(permissions, replicationOptions);
       const persistHost = globalOpts.host !== void 0;
       if (options2.device) {
         const { profile, result } = await loginWithDeviceAuthorization({
           profileName: ctx.profile,
           nodeOrigin: ctx.host,
           shareOrigin: DEFAULT_SHARE_ORIGIN,
-          permissions,
+          permissions: loginPermissions,
           ...options2.expiry === void 0 ? {} : { expiry: parseRequestedExpiry(parseExpiryOption(options2.expiry)) },
           reason: "Allow this TinyCloud CLI profile to use the permissions in the requested manifest.",
           expectedOwner: owner,
           replaceSession: options2.replaceSession === true,
           persistHost
         });
+        await persistReplicationLogin(ctx.profile, replicationOptions);
+        if (replicationOptions.allowSecrets) writeReplicationSecretsWarning();
         reportDeclined(result.declined);
         outputJson({
           authenticated: true,
@@ -21120,20 +21954,26 @@ function registerAuthCommand(program, options) {
         );
       }
       if (method === "local") {
-        await handleLocalAuth(ctx.profile, ctx.host);
+        buildReplicationLoginRequest(void 0, replicationOptions);
+        await handleLocalAuth(ctx.profile, ctx.host, { replication: replicationOptions });
+        await persistReplicationLogin(ctx.profile, replicationOptions);
+        if (replicationOptions.allowSecrets) writeReplicationSecretsWarning();
       } else {
         await handleOpenKeyAuth(ctx.profile, ctx.host, {
           paste: options2.paste,
           noPopup: options2.popup === false,
-          permissions,
+          permissions: loginPermissions,
+          replication: replicationOptions,
           expiry: parseExpiryOption(options2.expiry),
           expectedOwner: owner,
           replaceSession: options2.replaceSession === true,
           persistHost
         });
+        await persistReplicationLogin(ctx.profile, replicationOptions);
+        if (replicationOptions.allowSecrets) writeReplicationSecretsWarning();
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("logout").description("Clear the local session and remove local replicas. Logout is local; delegations and grants on the node stay valid until they expire. Use `tc delegation revoke <cid>` to end access now.").option("--keep-replicas", "Keep this profile's local replicas").action(async (options2, cmd) => {
@@ -21142,7 +21982,7 @@ function registerAuthCommand(program, options) {
       const ctx = await ProfileManager.resolveContext(globalOpts, { storedSession: "unused" });
       await ProfileManager.getProfile(ctx.profile);
       await ProfileManager.clearSession(ctx.profile);
-      const replicasRemoved = options2.keepReplicas ? [] : await removeProfileReplicas(ctx.profile);
+      const replicasRemoved = options2.keepReplicas ? [] : await removeProfileReplicasAndReplication(ctx.profile);
       outputJson({
         profile: ctx.profile,
         authenticated: false,
@@ -21151,7 +21991,7 @@ function registerAuthCommand(program, options) {
         warning: "Logout is local; delegations and grants on the node stay valid until they expire. Use `tc delegation revoke <cid>` to end access now."
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("rotate").description("Rotate the active profile session key").option("--paste", "Use manual paste mode instead of browser callback").option("--no-popup", "Print the OpenKey URL without opening a browser").action(async (options2, cmd) => {
@@ -21163,7 +22003,7 @@ function registerAuthCommand(program, options) {
         noPopup: options2.popup === false
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("status").description("Show current authentication state").action(async (_options, cmd) => {
@@ -21214,7 +22054,7 @@ function registerAuthCommand(program, options) {
         process.stdout.write(formatField("Has Key", hasKey !== null) + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("request").description("Create a TinyCloud permission request artifact").option(
@@ -21367,7 +22207,7 @@ function registerAuthCommand(program, options) {
         expiry
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("import [source]").description("Import a TinyCloud delegation or permission request artifact").option("--stdin", "Read the JSON artifact from stdin").option("--paste", "Read the JSON artifact from stdin").action(async (source, options2, cmd) => {
@@ -21508,7 +22348,7 @@ function registerAuthCommand(program, options) {
         expiry: importExpiry.toISOString()
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("grant [request]").description("Grant a TinyCloud permission request artifact to its requester").option("--stdin", "Read the JSON request artifact from stdin").option("--paste", "Read the JSON request artifact from stdin").option("--yes", "Skip local-key TTY confirmation", false).action(async (source, options2, cmd) => {
@@ -21549,7 +22389,7 @@ function registerAuthCommand(program, options) {
       });
       outputJson(grant);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("retry [requestId]").description("Check whether a stored permission request is now satisfied").option("--last", "Use the latest stored permission request for this profile").option("--exec", "Run the captured command when the request is covered").action(async (requestId, options2, cmd) => {
@@ -21592,7 +22432,7 @@ function registerAuthCommand(program, options) {
         command: isPermissionRequestArtifact(artifact) ? artifact.command ?? null : null
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("caps").description("Show granted capabilities for the active session").option("--diff <spec>", "Show missing capabilities for a spec").option("--history", "Show recent permission grants").action(async (options2, cmd) => {
@@ -21650,7 +22490,7 @@ function registerAuthCommand(program, options) {
         ) + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   auth.command("whoami").description("Show identity information").action(async (_options, cmd) => {
@@ -21691,13 +22531,13 @@ function registerAuthCommand(program, options) {
         process.stdout.write(formatField("Authenticated", authenticated) + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
 async function emitPermissionRequestArtifact(artifact, emitOption) {
   if (typeof emitOption === "string" && emitOption.length > 0) {
-    await mkdir3(dirname2(emitOption), { recursive: true });
+    await mkdir3(dirname3(emitOption), { recursive: true });
     await writeFile2(emitOption, JSON.stringify(artifact, null, 2) + "\n", "utf8");
     outputJson({
       emitted: true,
@@ -22178,8 +23018,13 @@ async function rotateAuthKey(profileName2, host, options = {}) {
   const { jwk, did } = await withSpinner("Generating session key...", async () => {
     return generateKey();
   });
+  let permissions;
   await ProfileManager.withLock(profileName2, async () => {
     const current = await ProfileManager.getProfile(profileName2);
+    if (current.replication?.prefixes.length) {
+      const previousSession = await ProfileManager.getSession(profileName2);
+      if (Array.isArray(previousSession?.permissions)) permissions = previousSession.permissions;
+    }
     await ProfileManager.setKey(profileName2, jwk);
     await ProfileManager.clearSession(profileName2);
     await ProfileManager.setProfile(profileName2, {
@@ -22194,7 +23039,8 @@ async function rotateAuthKey(profileName2, host, options = {}) {
   });
   const result = await refreshOpenKeySession(profileName2, host, {
     paste: options.paste,
-    noPopup: options.noPopup
+    noPopup: options.noPopup,
+    permissions
   });
   outputRotationResult(result.profile, profileName2, oldDid, "openkey");
 }
@@ -22241,7 +23087,7 @@ async function handleLocalAuth(profileName2, host, options = {}) {
   let address;
   let did;
   let sessionDid = profile?.sessionDid;
-  if ((profile?.authMethod === "local" || posture === "local-owner-key") && profile.privateKey) {
+  if (profile && (profile.authMethod === "local" || posture === "local-owner-key") && profile.privateKey) {
     privateKey = profile.privateKey;
     address = profile.address ?? await deriveAddress(privateKey);
     did = profile.did.startsWith("did:pkh:") ? profile.did : addressToDID(address, profile.chainId ?? DEFAULT_CHAIN_ID);
@@ -22275,7 +23121,12 @@ async function handleLocalAuth(profileName2, host, options = {}) {
     sessionDid ??= keyToDID(hasKey);
   }
   const sessionResult = await withSpinner("Signing in...", async () => {
-    return localKeySignIn({ privateKey, host });
+    const replication = options.replication ?? profile?.replication;
+    return localKeySignIn({
+      privateKey,
+      host,
+      ...replication?.prefixes.length ? { profile: profileName2, replication } : {}
+    });
   });
   const session = {
     authMethod: "local",
@@ -22353,6 +23204,22 @@ ${declined.map((permission) => `  ${compactPermission(permission)}`).join("\n")}
 `);
   }
 }
+async function persistReplicationLogin(profileName2, settings) {
+  await ProfileManager.updateProfile(profileName2, (profile) => {
+    const { replication: _previous, ...rest } = profile;
+    return settings.prefixes.length === 0 ? rest : {
+      ...rest,
+      replication: {
+        prefixes: [...settings.prefixes],
+        ...settings.allowSecrets === true ? { allowSecrets: true } : {}
+      }
+    };
+  });
+}
+function writeReplicationSecretsWarning() {
+  process.stderr.write(`${theme.warn("Warning:")} replication copies encrypted secret material to this device. The allow-secrets option does not grant decrypt.
+`);
+}
 async function refreshOpenKeySession(profileName2, host, options = {}) {
   const snapshot = await readProfileSnapshot(profileName2);
   const profile = snapshot.profile ?? await ProfileManager.getProfile(profileName2);
@@ -22364,14 +23231,22 @@ async function refreshOpenKeySession(profileName2, host, options = {}) {
       ExitCode.AUTH_REQUIRED
     );
   }
-  if (options.permissions !== void 0) validateLoginPermissions(options.permissions);
-  const permissions = options.permissions === void 0 ? void 0 : scopedLoginPermissions(options.permissions);
-  if (permissions !== void 0) {
-    assertNotLocalOwner(profileName2, profile, "Scoped browser login");
-  }
   const expiry = options.expiry === void 0 ? void 0 : parseRequestedExpiry(options.expiry);
   const openKeyExpiry = expiry === void 0 ? void 0 : openKeyExpiryParam(expiry);
   const expectedOwner = expectedOwnerFor(profileName2, profile, options.expectedOwner);
+  const replication = options.replication ?? profile.replication ?? { prefixes: [] };
+  const previousSession = options.replication === void 0 && profile.replication?.prefixes.length ? await ProfileManager.getSession(profileName2) : null;
+  const rememberedPermissions = Array.isArray(previousSession?.permissions) ? previousSession.permissions : void 0;
+  const baseRequest = options.permissions ?? rememberedPermissions;
+  const requested = buildReplicationLoginRequest(baseRequest, {
+    ...replication,
+    ...expectedOwner === void 0 ? {} : { ownerDid: expectedOwner }
+  });
+  if (requested !== void 0) validateLoginPermissions(requested);
+  const permissions = requested === void 0 ? void 0 : scopedLoginPermissions(requested);
+  if (permissions !== void 0) {
+    assertNotLocalOwner(profileName2, profile, "Scoped browser login");
+  }
   if (permissions !== void 0 && options.replaceSession !== true) {
     const estimatedExpiry = expiry === void 0 ? void 0 : new Date(Date.now() + expiry.durationMs).toISOString();
     assertSessionReplaceable(profileName2, snapshot, expectedOwner, permissions, estimatedExpiry);
@@ -22500,6 +23375,9 @@ _tc() {
     '(-v --verbose)'{-v,--verbose}'[Enable verbose output]' \\
     '--no-cache[Disable caching]' \\
     '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]' \\
+    '--replication[Enable read-through replication]' \\
+    '--no-replication[Disable replication]' \\
+    '--replication-debug[Write replication diagnostics to stderr]' \\
     '1:command:->cmd' \\
     '*::arg:->args'
 
@@ -22559,6 +23437,9 @@ complete -c tc -l host -s H -d "TinyCloud node URL"
 complete -c tc -l verbose -s v -d "Enable verbose output"
 complete -c tc -l no-cache -d "Disable caching"
 complete -c tc -l quiet -s q -d "Suppress non-essential output"
+complete -c tc -l replication -d "Enable read-through replication"
+complete -c tc -l no-replication -d "Disable replication"
+complete -c tc -l replication-debug -d "Write replication diagnostics to stderr"
 `;
 }
 
@@ -22593,7 +23474,7 @@ function registerContextCommand(program) {
         access: "not-tested"
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -22642,7 +23523,7 @@ function registerDelegationCommand(program, configuration = {}) {
         expiry: expiry.toISOString()
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   delegation.command("list").description("List delegations").option("--granted", "Show only delegations I've granted").option("--received", "Show only delegations I've received").action(async (options, cmd) => {
@@ -22674,7 +23555,7 @@ function registerDelegationCommand(program, configuration = {}) {
         count: delegations.length
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   delegation.command("info <cid>").description("Get delegation details").action(async (cid, _options, cmd) => {
@@ -22688,7 +23569,7 @@ function registerDelegationCommand(program, configuration = {}) {
       }
       outputJson(result.data);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   delegation.command("revoke <cid>").description("Revoke a delegation").option("--yes", "Skip local-key TTY confirmation", false).action(async (cid, options, cmd) => {
@@ -22706,7 +23587,7 @@ function registerDelegationCommand(program, configuration = {}) {
         openKeyAcquisition: configuration.openKeyAcquisition
       }));
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -22818,7 +23699,7 @@ function registerDoctorCommand(program) {
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -22862,7 +23743,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   duckdb.command("execute <sql>").description("Run INSERT/UPDATE/DELETE/DDL statement").option("--db <name>", "Database name", "default").option("--params <json>", "Bind parameters as JSON array").action(async (sqlStr, options, cmd) => {
@@ -22880,7 +23761,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
       }
       outputJson({ changes: result.data.changes });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   duckdb.command("describe").description("Show database schema (tables, columns, views)").option("--db <name>", "Database name", "default").action(async (options, cmd) => {
@@ -22925,7 +23806,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   duckdb.command("export").description("Export database as binary file").option("--db <name>", "Database name", "default").option("-o, --output <file>", "Output file path", "export.duckdb").action(async (options, cmd) => {
@@ -22950,7 +23831,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
         sizeHuman: formatBytes(blob.size)
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   duckdb.command("import <file>").description("Import a DuckDB database file").option("--db <name>", "Database name", "default").action(async (file, options, cmd) => {
@@ -22974,7 +23855,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
         imported: true
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23013,7 +23894,7 @@ function registerEnableCommand(program) {
       };
       output(value, () => result.declined.length === 0 ? `Share enabled for profile ${context.profile}.` : `Share enabled for profile ${context.profile} with ${result.declined.length} capability group(s) declined; publishing may fail.`);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23085,7 +23966,7 @@ function registerInitCommand(program) {
         authenticated: true
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23098,8 +23979,8 @@ init_storage();
 init_errors();
 init_constants();
 import { randomUUID as randomUUID2 } from "crypto";
-import { lstat as lstat3, open as open3, rename as rename2, rm as rm4 } from "fs/promises";
-import { basename as basename2, dirname as dirname3, join as join7 } from "path";
+import { lstat as lstat3, open as open3, rename as rename2, rm as rm5 } from "fs/promises";
+import { basename as basename2, dirname as dirname4, join as join9 } from "path";
 async function validatePrivateOutput(path, label = "output") {
   try {
     const destination = await lstat3(path);
@@ -23110,7 +23991,7 @@ async function validatePrivateOutput(path, label = "output") {
     if (error?.code !== "ENOENT") throw error;
   }
   try {
-    const parent = await lstat3(dirname3(path));
+    const parent = await lstat3(dirname4(path));
     if (!parent.isDirectory()) {
       throw new CLIError("INVALID_ARGUMENT", `${label} "${path}" requires an existing directory parent.`, ExitCode.USAGE_ERROR);
     }
@@ -23121,8 +24002,8 @@ async function validatePrivateOutput(path, label = "output") {
 }
 async function writePrivateOutput(path, value, label = "output") {
   await validatePrivateOutput(path, label);
-  const parentPath = dirname3(path);
-  const temp = join7(parentPath, `.${basename2(path)}.${randomUUID2()}.tmp`);
+  const parentPath = dirname4(path);
+  const temp = join9(parentPath, `.${basename2(path)}.${randomUUID2()}.tmp`);
   let created = false;
   try {
     const handle = await open3(temp, "wx", PRIVATE_FILE_MODE);
@@ -23135,7 +24016,7 @@ async function writePrivateOutput(path, value, label = "output") {
     }
     await rename2(temp, path);
   } catch (error) {
-    if (created) await rm4(temp, { force: true }).catch(() => void 0);
+    if (created) await rm5(temp, { force: true }).catch(() => void 0);
     const code3 = error instanceof Error && "code" in error && typeof error.code === "string" ? ` (${error.code})` : "";
     throw new CLIError("ERROR", `Could not write ${label.toLowerCase()} "${path}"${code3}.`, ExitCode.ERROR);
   }
@@ -23228,7 +24109,7 @@ function registerKvCommand(program) {
         process.stdout.write(content + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   kv.command("put <key> [value]").description("Set a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, value, options, cmd) => {
@@ -23263,7 +24144,7 @@ function registerKvCommand(program) {
       }
       outputJson({ key, written: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   kv.command("delete <key>").description("Delete a key").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
@@ -23279,7 +24160,7 @@ function registerKvCommand(program) {
       }
       outputJson({ key, deleted: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   kv.command("list").description("List keys").option("--prefix <prefix>", "Filter by key prefix").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (options, cmd) => {
@@ -23315,7 +24196,7 @@ function registerKvCommand(program) {
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   kv.command("head <key>").description("Get metadata for a key (no body)").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
@@ -23341,7 +24222,7 @@ function registerKvCommand(program) {
         metadata: result.data.headers ?? {}
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23453,7 +24334,7 @@ ${theme.heading("Permissions")}
         process.stdout.write(formatTable(["service", "path", "actions"], rows) + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23512,7 +24393,7 @@ function registerNodeCommand(program) {
       if (error instanceof TypeError && error.message.includes("fetch")) {
         outputJson({ healthy: false, host: (await ProfileManager.resolveContext(cmd.optsWithGlobals(), { storedSession: "unused" })).host, error: "Connection refused" });
       } else {
-        handleError(error);
+        return handleError(error);
       }
     }
   });
@@ -23527,7 +24408,7 @@ function registerNodeCommand(program) {
       const data = await response.json();
       outputJson({ ...data, host: ctx.host });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   node.command("status").description("Combined health and version info").action(async (_options, cmd) => {
@@ -23552,7 +24433,7 @@ function registerNodeCommand(program) {
         ...versionData
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23612,7 +24493,7 @@ function registerProfileCommand(program) {
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   profile.command("create <name>").description("Create a new profile").option("--host <url>", "TinyCloud node URL").option(
@@ -23646,7 +24527,7 @@ function registerProfileCommand(program) {
       });
       outputJson({ profile: name, did, host, posture, operatorType, created: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   profile.command("show [name]").description("Show profile details").action(async (name, _options, cmd) => {
@@ -23685,7 +24566,7 @@ function registerProfileCommand(program) {
         process.stdout.write(formatField("Created", p.createdAt) + "\n");
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   profile.command("switch <name>").description("Set default profile").action(async (name, _options, cmd) => {
@@ -23697,7 +24578,7 @@ function registerProfileCommand(program) {
       await ProfileManager.setConfig({ ...config, defaultProfile: name });
       outputJson({ defaultProfile: name, switched: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   profile.command("set-default-space [name]").description("Set (or clear) the default space used when --space is omitted").option("--profile <name>", "Profile to modify (defaults to the active profile)").option("--unset", "Clear the default space so commands fall back to the primary space").addHelpText("after", `
@@ -23736,7 +24617,7 @@ Examples:
       await ProfileManager.updateProfile(profileName2, (p) => ({ ...p, defaultSpace }));
       outputJson({ profile: profileName2, defaultSpace: defaultSpace ?? null, updated: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   profile.command("delete <name>").description("Delete a profile").action(async (name, _options, cmd) => {
@@ -23755,7 +24636,7 @@ Examples:
       await ProfileManager.deleteProfile(name);
       outputJson({ profile: name, deleted: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -23779,16 +24660,105 @@ function parseOperatorType(raw) {
 }
 
 // src/commands/replica.ts
+init_sdk();
+init_replication_registry();
 import { randomBytes as randomBytes5 } from "crypto";
 import { constants as fsConstants2 } from "fs";
-import { open as open4, readdir as readdir5, rename as rename3, stat as stat3, unlink as unlink2 } from "fs/promises";
-import { basename as basename3, dirname as dirname4, join as join8, resolve as resolve2 } from "path";
+import { open as open4, readdir as readdir5, rename as rename3, stat as stat3, unlink as unlink2, readFile as readFile9, lstat as lstat4 } from "fs/promises";
+import { basename as basename3, dirname as dirname5, join as join10, resolve as resolve2 } from "path";
+
+// src/lib/replication-report.ts
+var CLEAR_PENDING_WARNING = "Clearing pending writes stops pinning keys whose last write had an unknown outcome or never finished. If such a write did commit, or commits later, this device can serve the older value for that key until the next sync after the commit, as it would for a write from another device.";
+function percentile(values, fraction) {
+  if (values.length === 0) return null;
+  values.sort((left, right) => left - right);
+  return values[Math.ceil(fraction * values.length) - 1] ?? values[values.length - 1];
+}
+function createReplicationReport(since, events, replicas, partitions, warning) {
+  const reads = events.filter((event) => event.type === "replication.read");
+  const replicaReads = reads.filter((event) => event.source === "replica");
+  const sourceLatency = /* @__PURE__ */ new Map();
+  const readsBySourceReason = {};
+  for (const event of reads) {
+    const key = `${event.source}:${event.reason}`;
+    readsBySourceReason[key] = (readsBySourceReason[key] ?? 0) + 1;
+    const values = sourceLatency.get(event.source) ?? [];
+    values.push(event.latencyMs);
+    sourceLatency.set(event.source, values);
+  }
+  const latencyMs = Object.fromEntries([...sourceLatency].map(([source, values]) => [source, {
+    p50: percentile([...values], 0.5),
+    p95: percentile([...values], 0.95)
+  }]));
+  const staleness = reads.flatMap((event) => event.stalenessMs === null ? [] : [event.stalenessMs]);
+  const syncs = {};
+  const writes = {};
+  const divergences = events.filter((event) => event.type === "replication.divergence").slice(-20);
+  for (const event of events) {
+    if (event.type === "replication.sync") {
+      const key = `${event.class ?? "none"}:${event.code ?? event.outcome}`;
+      syncs[key] = (syncs[key] ?? 0) + 1;
+    } else if (event.type === "replication.write") {
+      writes[event.outcome] = (writes[event.outcome] ?? 0) + 1;
+    }
+  }
+  return {
+    since,
+    totals: {
+      reads: reads.length,
+      replicaReads: replicaReads.length,
+      hitRatio: reads.length === 0 ? 0 : replicaReads.length / reads.length,
+      writes: events.filter((event) => event.type === "replication.write").length,
+      divergences: events.filter((event) => event.type === "replication.divergence").length
+    },
+    readsBySourceReason,
+    latencyMs,
+    stalenessMs: { p50: percentile([...staleness], 0.5), p95: percentile([...staleness], 0.95), max: staleness.length ? Math.max(...staleness) : null },
+    syncs,
+    writes,
+    divergences,
+    replicas,
+    partitions,
+    ...warning === void 0 ? {} : { warning }
+  };
+}
+function renderReplicationReport(report) {
+  const lines = [
+    `Replication report (since ${report.since})`,
+    `Reads: ${report.totals.reads}; replica: ${report.totals.replicaReads}; hit ratio: ${(report.totals.hitRatio * 100).toFixed(1)}%`,
+    `Latency ms: ${Object.entries(report.latencyMs).map(([source, value]) => `${source} p50=${value.p50 ?? "\u2014"} p95=${value.p95 ?? "\u2014"}`).join("; ") || "none"}`,
+    `Staleness ms: p50=${report.stalenessMs.p50 ?? "\u2014"} p95=${report.stalenessMs.p95 ?? "\u2014"} max=${report.stalenessMs.max ?? "\u2014"}`,
+    `Syncs: ${Object.entries(report.syncs).map(([key, count]) => `${key}=${count}`).join(", ") || "none"}`,
+    `Writes: ${Object.entries(report.writes).map(([key, count]) => `${key}=${count}`).join(", ") || "none"}`,
+    `Read source/reason: ${Object.entries(report.readsBySourceReason).map(([key, count]) => `${key}=${count}`).join(", ") || "none"}`,
+    `Divergences: ${report.totals.divergences}; showing ${report.divergences.length} of ${report.totals.divergences}`,
+    `Replicas: ${report.replicas.length}`
+  ];
+  for (const divergence of report.divergences) {
+    if (divergence.type === "replication.divergence") {
+      lines.push(`  ${divergence.space} ${divergence.key}: ${divergence.kind} stalenessMs=${divergence.stalenessMs}`);
+    }
+  }
+  for (const replica of report.replicas) {
+    const grant = replica.grant ? ` grant=${replica.grant.cid} parent=${replica.grant.parentCid ?? "\u2014"} expires=${replica.grant.expiresAt ?? "\u2014"}` : " grant=missing";
+    lines.push(`  ${replica.prefix}: ${replica.state}; pending in_flight=${replica.pending.inFlight} committed=${replica.pending.committed} ambiguous=${replica.pending.ambiguous}${grant}`);
+    for (const pinned of replica.pinned) lines.push(`    pinned ${pinned.key} ${pinned.state} ${pinned.op} since=${pinned.since} code=${pinned.code ?? "\u2014"} likelyOrphaned=${pinned.likelyOrphaned}`);
+  }
+  for (const partition of report.partitions) {
+    lines.push(`Partition ${partition.idHash}: host=${partition.host ?? "unknown"} space=${partition.space ?? "unknown"} pinned=${partition.pinned}`);
+  }
+  if (report.partitions.some((partition) => partition.pinned > 100)) lines.push("Warning: a partition holds more than 100 pinned records.");
+  if (report.warning) lines.push(`Warning: ${report.warning}`);
+  return lines.join("\n");
+}
+
+// src/commands/replica.ts
 import {
   ProfileDeletedError as ProfileDeletedError3,
-  profilePath as profilePath3,
+  profilePath as profilePath4,
   readAdditionalDelegations as readAdditionalDelegations2,
   readSession as readSession2,
-  withProfileLock as withProfileLock4
+  withProfileLock as withProfileLock5
 } from "@tinycloud/operations/state";
 init_profiles();
 init_constants();
@@ -23796,6 +24766,8 @@ init_errors();
 init_formatter();
 init_theme();
 var EXIT_BY_CODE = {
+  [ReplicaErrorCode.INVALID_ARGUMENT]: ExitCode.USAGE_ERROR,
+  [ReplicaErrorCode.CLOSED]: ExitCode.ERROR,
   [ReplicaErrorCode.BUSY]: ExitCode.ERROR,
   [ReplicaErrorCode.RUNTIME_UNSUPPORTED]: ExitCode.ERROR,
   [ReplicaErrorCode.STORAGE_ERROR]: ExitCode.ERROR,
@@ -23845,7 +24817,7 @@ async function run(action) {
     await loadSqlite();
     await action();
   } catch (error) {
-    handleError(toCliError(error));
+    return handleError(toCliError(error));
   }
 }
 async function profileName(cmd) {
@@ -23856,13 +24828,13 @@ async function profileName(cmd) {
   return config?.defaultProfile ?? DEFAULT_PROFILE;
 }
 function replicasRoot(profile) {
-  return join8(profilePath3(profile), "replicas");
+  return join10(profilePath4(profile), "replicas");
 }
 async function replicaNames(profile) {
   const names = [];
   for (const name of await readdir5(replicasRoot(profile)).catch(() => [])) {
     if (!NAME.test(name)) continue;
-    const exists = await stat3(join8(replicasRoot(profile), name, "replica.db")).then(
+    const exists = await stat3(join10(replicasRoot(profile), name, "replica.db")).then(
       () => true,
       () => false
     );
@@ -23888,7 +24860,7 @@ async function existingReplicaName(profile, option) {
 function profileGuard(profile) {
   return async (section) => {
     try {
-      return await withProfileLock4(profile, section, { requireProfile: true });
+      return await withProfileLock5(profile, section, { requireProfile: true });
     } catch (error) {
       if (error instanceof ProfileDeletedError3) {
         throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, `Profile "${profile}" was deleted; its replicas are gone and nothing was written.`);
@@ -23898,12 +24870,12 @@ function profileGuard(profile) {
   };
 }
 async function openReplica(profile, name) {
-  return SqliteReplicaStore.open(join8(replicasRoot(profile), name), { create: false, guard: profileGuard(profile) });
+  return SqliteReplicaStore.open(join10(replicasRoot(profile), name), { create: false, guard: profileGuard(profile) });
 }
 async function createReplica(profile, config) {
   const guard = profileGuard(profile);
   return guard(async () => {
-    const store = await SqliteReplicaStore.open(join8(replicasRoot(profile), config.name), { create: true, guard });
+    const store = await SqliteReplicaStore.open(join10(replicasRoot(profile), config.name), { create: true, guard });
     if (await store.open() === null) await store.init(config);
     return store;
   });
@@ -24035,7 +25007,7 @@ function describeStatus(status) {
 }
 async function writeFileAtomic(path, bytes) {
   const target = resolve2(path);
-  const temp = join8(dirname4(target), `.${basename3(target)}.${randomBytes5(6).toString("hex")}.tmp`);
+  const temp = join10(dirname5(target), `.${basename3(target)}.${randomBytes5(6).toString("hex")}.tmp`);
   const handle = await open4(temp, fsConstants2.O_CREAT | fsConstants2.O_EXCL | fsConstants2.O_WRONLY, 384);
   try {
     await handle.writeFile(bytes);
@@ -24061,6 +25033,49 @@ function replicaSecretsWarning(space, prefix, secretsAllowed) {
   if (!secretsAllowed || !requiresSecretsOptIn(space, prefix)) return void 0;
   return `This replica stores the ciphertext of every secret under "${prefix}". A tinycloud.encryption/decrypt grant covers the whole encryption network, not one secret (TC-755), so whoever holds decrypt can open every replicated secret.`;
 }
+async function readReplicationEvents(profile, sinceMs) {
+  const root = join10(profilePath4(profile), "replication");
+  const events = [];
+  for (const name of ["events.jsonl.1", "events.jsonl"]) {
+    const data = await readFile9(join10(root, name), "utf8").catch((error) => {
+      if (error.code === "ENOENT") return "";
+      throw error;
+    });
+    for (const line of data.split("\n")) {
+      if (!line) continue;
+      try {
+        const event = JSON.parse(line);
+        if (Number.isFinite(Date.parse(event.at)) && Date.parse(event.at) >= sinceMs) events.push(event);
+      } catch {
+      }
+    }
+  }
+  return events;
+}
+async function replicationPartitions(profile) {
+  const root = join10(profilePath4(profile), "replication");
+  const entries = await readdir5(root, { withFileTypes: true }).catch((error) => {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  });
+  const partitions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^[a-z2-7]{26}$/.test(entry.name)) continue;
+    const directory = join10(root, entry.name);
+    const info = await lstat4(directory);
+    if (info.isSymbolicLink() || !info.isDirectory()) continue;
+    const identity = await readFile9(join10(directory, "identity.json"), "utf8").then((value) => JSON.parse(value)).catch(() => null);
+    const pending = await readFile9(join10(directory, "pending.json"), "utf8").then((value) => JSON.parse(value)).catch(() => null);
+    const pinned = pending?.records?.filter((record2) => record2.state === "in_flight" || record2.state === "ambiguous").length ?? 0;
+    partitions.push({
+      idHash: entry.name,
+      host: typeof identity?.host === "string" ? identity.host : null,
+      space: typeof identity?.space === "string" ? identity.space : null,
+      pinned
+    });
+  }
+  return partitions.sort((left, right) => left.idHash.localeCompare(right.idHash));
+}
 function registerReplicaCommand(program) {
   const replica = program.command("replica").description("Durable read-only local replicas of a KV prefix (sync online, read offline) [beta]").addHelpText(
     "after",
@@ -24076,6 +25091,53 @@ SECRETS_OPT_IN_REQUIRED; 3 grant missing; 4 key absent, deleted, content missing
 or coverage incomplete; 5 grant expired, revoked or not yet valid; 6 network;
 7 node, protocol or integrity error; 10 storage full.`
   );
+  replica.command("report").description("Report replication reads, syncs, pending writes and local identity partitions").option("--since <duration>", "Include events from the last duration (default: 24h)", "24h").option("--purge", "Purge configured replicas for the current identity").option("--clear-pending", "Clear ambiguous and likely orphaned in-flight writes").action(
+    (options, cmd) => run(async () => {
+      const globals = cmd.optsWithGlobals();
+      const context = await ProfileManager.resolveContext(globals);
+      const node = context.replication ? await ensureAuthenticated(context) : void 0;
+      const profile = await profileName(cmd);
+      let durationMs;
+      try {
+        durationMs = parseDuration(options.since);
+      } catch (error) {
+        throw new CLIError("USAGE_ERROR", error instanceof Error ? error.message : String(error), ExitCode.USAGE_ERROR);
+      }
+      const control = node?.replication ?? replicationForProfile(profile);
+      let cleared;
+      let purged;
+      let warning;
+      if (options.clearPending || options.purge) {
+        if (!control) throw new CLIError("REPLICATION_UNAVAILABLE", "No replication runtime is registered for this profile.", ExitCode.ERROR);
+        warning = CLEAR_PENDING_WARNING;
+        process.stderr.write(`Warning: ${warning}
+`);
+        if (options.clearPending) cleared = await control.clearPending();
+        if (options.purge) purged = await control.purge();
+      }
+      const sinceMs = Date.now() - durationMs;
+      const [events, partitions, replicas] = await Promise.all([
+        readReplicationEvents(profile, sinceMs),
+        replicationPartitions(profile),
+        node?.replication ? node.replication.status() : control ? control.status() : Promise.resolve([])
+      ]);
+      const report = createReplicationReport(options.since, events, replicas, partitions, warning);
+      if (shouldOutputJson()) {
+        outputJson({
+          ...report,
+          ...cleared === void 0 ? {} : { cleared },
+          ...purged === void 0 ? {} : { purged }
+        });
+      } else {
+        process.stdout.write(`${renderReplicationReport(report)}
+`);
+        if (cleared !== void 0) process.stdout.write(`Cleared ${cleared} pending write record(s).
+`);
+        if (purged !== void 0) process.stdout.write(`Purge: ${JSON.stringify(purged)}
+`);
+      }
+    })
+  );
   replica.command("sync").description("Create or update a replica from its source host").option("--replica <name>", "Replica name (default: the profile's only replica, or one named after the prefix)").option("--space <id|name>", "Space to replicate (first sync; default: the space of the sync grant)").option("--prefix <prefix>", "KV prefix to replicate, e.g. notes/ (first sync)").option("--retention-grant <cid>", "CID of a tinycloud.kv/retain grant: keep local reads after the sync grant expires").option("--limit <n>", "Feed page size (1-1000)", (value) => Number.parseInt(value, 10)).option("--allow-secrets", "Opt in to copying ciphertext under a secrets prefix; replica grants do not include decrypt").action(
     (options, cmd) => run(async () => {
       const profile = await profileName(cmd);
@@ -24095,8 +25157,8 @@ or coverage incomplete; 5 grant expired, revoked or not yet valid; 6 network;
       let store;
       if (existing.includes(name)) {
         store = await openReplica(profile, name);
-        const state = await store.open();
-        const differs = syncOptionsDiffer(state.config, {
+        const state2 = await store.open();
+        const differs = syncOptionsDiffer(state2.config, {
           ...options.space === void 0 ? {} : { space: options.space },
           ...options.prefix === void 0 ? {} : { prefix: options.prefix },
           ...globals.host === void 0 ? {} : { host: globals.host }
@@ -24136,24 +25198,24 @@ or coverage incomplete; 5 grant expired, revoked or not yet valid; 6 network;
         });
       }
       try {
-        const state = await store.open();
-        const { space, prefix, host } = state.config;
-        if (requiresSecretsOptIn(space, prefix) && !state.config.allowSecrets && options.allowSecrets !== true) {
+        const state2 = await store.open();
+        const { space, prefix, host } = state2.config;
+        if (requiresSecretsOptIn(space, prefix) && !state2.config.allowSecrets && options.allowSecrets !== true) {
           throw new ReplicaError(ReplicaErrorCode.SECRETS_OPT_IN_REQUIRED, `Replicating ${space}/kv/${prefix} needs --allow-secrets.`);
         }
         let grant;
         try {
-          grant = chooseGrant(grants, state.config.deviceDid, space, prefix);
+          grant = chooseGrant(grants, state2.config.deviceDid, space, prefix);
         } catch (error) {
-          if (!isReplicaError(error, ReplicaErrorCode.GRANT_MISSING) || (state.grant ?? state.pendingGrant) === null) throw error;
+          if (!isReplicaError(error, ReplicaErrorCode.GRANT_MISSING) || (state2.grant ?? state2.pendingGrant) === null) throw error;
         }
         if (grant !== void 0) await store.installGrant(grant);
-        if (options.retentionGrant !== void 0 && options.retentionGrant !== state.config.retentionGrantCid) {
+        if (options.retentionGrant !== void 0 && options.retentionGrant !== state2.config.retentionGrantCid) {
           await store.setRetentionGrant(options.retentionGrant === "" ? null : options.retentionGrant);
         }
         const current = await store.open();
         const transportFor = await grantTransports({ host, space, deviceDid: current.config.deviceDid, jwk });
-        const warning = replicaSecretsWarning(space, prefix, options.allowSecrets === true || state.config.allowSecrets);
+        const warning = replicaSecretsWarning(space, prefix, options.allowSecrets === true || state2.config.allowSecrets);
         if (warning !== void 0) process.stderr.write(`Warning: ${warning}
 `);
         const report = await new Replica({ store, transportFor }).sync(options.limit === void 0 ? {} : { limit: options.limit });
@@ -24283,8 +25345,8 @@ init_theme();
 init_errors();
 init_warnings();
 init_constants();
-import { readFile as readFile9 } from "fs/promises";
-import { join as join9 } from "path";
+import { readFile as readFile10 } from "fs/promises";
+import { join as join11 } from "path";
 import { homedir, hostname, userInfo } from "os";
 import { appSecretScope } from "@tinycloud/sdk-core";
 import { invokeOperation as invokeOperation2 } from "@tinycloud/operations";
@@ -24813,7 +25875,7 @@ function resolveSecretListPrefix(options = {}) {
 }
 function resolveProfilesDir() {
   const home = process.env.TC_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? homedir();
-  return join9(home, ".tinycloud", "profiles");
+  return join11(home, ".tinycloud", "profiles");
 }
 async function ensureSecretsNode(ctx, options, openKeyAcquisition, selectedProfile) {
   const auth = authOptions(options);
@@ -25176,7 +26238,7 @@ function permissionsFromDelegation2(delegation) {
 }
 async function loadDelegationCandidates(source) {
   try {
-    const raw = JSON.parse(await readFile9(source, "utf8"));
+    const raw = JSON.parse(await readFile10(source, "utf8"));
     return normalizeDelegationCandidates(raw, source);
   } catch (error) {
     if (error?.code !== "ENOENT") {
@@ -25195,8 +26257,8 @@ async function loadDelegationCandidates(source) {
     }
   }
   try {
-    const importedPath = join9(resolveProfilesDir(), source, "additional-delegations.json");
-    const raw = JSON.parse(await readFile9(importedPath, "utf8"));
+    const importedPath = join11(resolveProfilesDir(), source, "additional-delegations.json");
+    const raw = JSON.parse(await readFile10(importedPath, "utf8"));
     return normalizeDelegationCandidates(raw, source);
   } catch (error) {
     if (error?.code === "ENOENT") {
@@ -25521,7 +26583,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
           scopeOptions,
           space: spaceUri,
           label: `Checking secret ${name}...`,
-          operation: () => secrets2.get(name, scopeOptions)
+          operation: () => secrets2.get(name, { ...scopeOptions, source: "network" })
         });
         if (result.ok) {
           secret = {
@@ -25590,7 +26652,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
         scopeOptions,
         space: spaceUri,
         label: "Listing secrets...",
-        operation: () => secrets2.list(scopeOptions)
+        operation: () => secrets2.list({ ...scopeOptions, source: "network" })
       });
       if (!result.ok) {
         throw cliErrorFromService(result.error);
@@ -25703,7 +26765,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
         throw new CLIError("USAGE_ERROR", "Provide only one of: value argument, --file, or --stdin", ExitCode.USAGE_ERROR);
       }
       if (options.file) {
-        secretValue = await readFile9(options.file, "utf-8");
+        secretValue = await readFile10(options.file, "utf-8");
       } else if (options.stdin) {
         secretValue = (await readStdin3()).toString("utf-8");
       } else {
@@ -32735,12 +33797,12 @@ async function notifyShare(input) {
     if (input.signal?.aborted) throw new ShareNotifyError("share delivery was cancelled");
     attempts += 1;
     try {
-      const state = await input.adapter.deliver({ shareId: input.shareId, recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
+      const state2 = await input.adapter.deliver({ shareId: input.shareId, recipient, idempotencyKey, ...input.record === void 0 ? {} : { record: input.record }, ...input.signal === void 0 ? {} : { signal: input.signal } });
       return {
         protocol: "tinycloud-share",
         version: 1,
         shareId: input.shareId,
-        state: state === "delivered" && input.record?.deliveredRecipients?.includes(recipient) ? "already-delivered" : state,
+        state: state2 === "delivered" && input.record?.deliveredRecipients?.includes(recipient) ? "already-delivered" : state2,
         idempotencyKey,
         attempts
       };
@@ -34211,9 +35273,9 @@ function receiveJson(result, path) {
 
 // src/share/io.ts
 import { constants } from "fs";
-import { lstat as lstat4, mkdir as mkdir4, mkdtemp, open as open7, readFile as readFile10, realpath as realpath2, stat as stat4, link as link2, rename as rename4, rm as rm5, unlink as unlink3 } from "fs/promises";
+import { lstat as lstat5, mkdir as mkdir4, mkdtemp, open as open7, readFile as readFile11, realpath as realpath2, stat as stat4, link as link2, rename as rename4, rm as rm6, unlink as unlink3 } from "fs/promises";
 import { randomBytes as randomBytes6 } from "crypto";
-import { basename as basename4, join as join10, resolve as resolve3, sep as sep2 } from "path";
+import { basename as basename4, join as join12, resolve as resolve3, sep as sep2 } from "path";
 init_errors();
 var MAX_SHARE_STDIN_BYTES = 100 * 1024 * 1024;
 var MAX_SHARE_URL_BYTES = 64 * 1024;
@@ -34258,7 +35320,7 @@ async function readShareInput(input, name, limit = MAX_SHARE_STDIN_BYTES) {
   const path = resolve3(input);
   const info = await stat4(path);
   if (!info.isFile() || info.size > limit) throw new Error("MAX_BYTES_EXCEEDED");
-  const bytes = new Uint8Array(await readFile10(path));
+  const bytes = new Uint8Array(await readFile11(path));
   if (bytes.byteLength > limit) throw new Error("MAX_BYTES_EXCEEDED");
   return { bytes, filename };
 }
@@ -34267,9 +35329,9 @@ async function assertDirectory(path) {
   const segments = absolute.split(sep2).filter(Boolean);
   let current = absolute.startsWith(sep2) ? sep2 : "";
   for (const segment of segments) {
-    current = current === sep2 ? join10(current, segment) : join10(current, segment);
+    current = current === sep2 ? join12(current, segment) : join12(current, segment);
     try {
-      const info = await lstat4(current);
+      const info = await lstat5(current);
       if (info.isSymbolicLink()) {
         const canonical = await realpath2(current);
         if (current !== "/tmp" && current !== "/var") throw new Error("OUTPUT_EXISTS");
@@ -34278,7 +35340,7 @@ async function assertDirectory(path) {
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
       await mkdir4(current, { mode: 448 });
-      const created = await lstat4(current);
+      const created = await lstat5(current);
       if (created.isSymbolicLink() || !created.isDirectory()) throw new Error("OUTPUT_EXISTS");
     }
   }
@@ -34289,23 +35351,23 @@ async function writeShareOutput(directory, filename, bytes, force) {
   const safeName = safeFilename(filename);
   const directoryHandle = await open7(outputDirectory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0));
   const stableDirectory = await realpath2(outputDirectory);
-  const outputPath = join10(stableDirectory, safeName);
+  const outputPath = join12(stableDirectory, safeName);
   const directoryIdentity = await directoryHandle.stat();
   const assertStableDirectory = async () => {
     const current = await stat4(stableDirectory);
     if (current.dev !== directoryIdentity.dev || current.ino !== directoryIdentity.ino) throw new Error("OUTPUT_EXISTS");
   };
   await assertStableDirectory();
-  const stagingDirectory = await mkdtemp(join10(stableDirectory, ".tinycloud-share-stage-"));
-  const stagingInfo = await lstat4(stagingDirectory);
+  const stagingDirectory = await mkdtemp(join12(stableDirectory, ".tinycloud-share-stage-"));
+  const stagingInfo = await lstat5(stagingDirectory);
   if (!stagingInfo.isDirectory() || (stagingInfo.mode & 511) !== 448) throw new Error("OUTPUT_EXISTS");
-  const stagingPath = join10(stagingDirectory, `.tinycloud-share-${randomBytes6(16).toString("hex")}.tmp`);
+  const stagingPath = join12(stagingDirectory, `.tinycloud-share-${randomBytes6(16).toString("hex")}.tmp`);
   let temporaryPath;
   let handle;
   try {
     await assertStableDirectory();
     try {
-      const existing = await lstat4(outputPath);
+      const existing = await lstat5(outputPath);
       if (existing.isSymbolicLink()) throw new Error("UNSAFE_FILENAME");
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
@@ -34333,10 +35395,10 @@ async function writeShareOutput(directory, filename, bytes, force) {
       if (temporaryPath !== void 0) await unlink3(temporaryPath);
     } catch {
     }
-    await rm5(stagingDirectory, { recursive: true, force: true });
+    await rm6(stagingDirectory, { recursive: true, force: true });
     await directoryHandle.close();
   }
-  return join10(outputDirectory, safeName);
+  return join12(outputDirectory, safeName);
 }
 
 // src/share/errors.ts
@@ -34619,7 +35681,7 @@ function registerShareCommand(program) {
       if (json) writeJson2({ ...redactPublishedShare(result), expiryClamped: result.metadata.expiryClamped === true, ...notification === void 0 ? {} : { notification } });
       else publishHuman(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("inspect [url]").description("Verify a share link and print safe metadata").option("--stdin", "Read the complete URL from stdin").option("--json", "Print versioned redacted JSON").option("--viewer-origin <origin>", "Require this canonical Share origin", SHARE_ORIGIN).action(async (url, options, command) => {
@@ -34629,7 +35691,7 @@ function registerShareCommand(program) {
       if (json) writeJson2(result);
       else inspectHuman(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("receive [url]").description("Verify and receive a share link").option("--stdin", "Read the complete URL from stdin").option("--output <directory>", "Create the file in this directory").option("--stdout", "Write verified plaintext bytes to stdout").option("--force", "Allow replacing an existing non-symlink output").option("--max-bytes <bytes>", "Bound received content bytes").option("--json", "Print versioned redacted JSON").option("--viewer-origin <origin>", "Require this canonical Share origin", SHARE_ORIGIN).action(async (url, options, command) => {
@@ -34677,7 +35739,7 @@ function registerShareCommand(program) {
       if (json) receiveJson(result, output2);
       else receiveHuman(output2);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("list").description("List encrypted sender history without complete bearer URLs").option("--json", "Print versioned redacted JSON").action(async (options, command) => {
@@ -34688,7 +35750,7 @@ function registerShareCommand(program) {
       if (json) writeJson2({ protocol: "tinycloud-share", version: 1, shares: result });
       else process.stdout.write(result.map((item) => `${item.shareId}	${item.target}	${item.expiresAt}`).join("\n") + (result.length ? "\n" : ""));
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("show <id>").description("Show one redacted sender-history record").option("--reveal-link", "Explicitly include the complete link").option("--json", "Print versioned redacted JSON").action(async (id, options, command) => {
@@ -34700,7 +35762,7 @@ function registerShareCommand(program) {
       if (json) writeJson2({ protocol: "tinycloud-share", version: 1, share: result });
       else writeJson2(result);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
   share.command("notify <id>").description("Retry idempotent delivery within 5 minutes of publication; after that publish a new share").requiredOption("--to <address>", "Recipient email").option("--json", "Print versioned JSON").action(async (id, options, command) => {
@@ -34727,7 +35789,7 @@ function registerShareCommand(program) {
       if (result.reason === "delivery-window-expired") process.stderr.write(NOTIFY_WINDOW_MESSAGE);
       if (result.state === "partial-failure") process.exitCode = 9;
     } catch (error) {
-      handleError(shareCliError(error, "notify"));
+      return handleError(shareCliError(error, "notify"));
     }
   });
   share.command("revoke <id>").description("Revoke addressed shares; report bearer retention honestly").option("--ancestor", "Revoke the owner delegation ancestry").option("--json", "Print versioned JSON").action(async (id, options, command) => {
@@ -34744,7 +35806,7 @@ function registerShareCommand(program) {
       else process.stdout.write(`${result.state}
 `);
     } catch (error) {
-      handleError(shareCliError(error));
+      return handleError(shareCliError(error));
     }
   });
 }
@@ -34759,7 +35821,7 @@ init_host();
 init_theme();
 import { randomBytes as randomBytes7 } from "crypto";
 import { mkdir as mkdir5, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5 } from "path";
+import { dirname as dirname6 } from "path";
 function didWithoutFragment2(did) {
   const fragment = did.indexOf("#");
   return fragment === -1 ? did : did.slice(0, fragment);
@@ -34790,7 +35852,7 @@ function registerSpaceCommand(program) {
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   space.command("create <name>").alias("host").description("Create (host) one of your owned spaces by name").action(async (name, _options, cmd) => {
@@ -34801,7 +35863,7 @@ function registerSpaceCommand(program) {
       const spaceId = await node.hostOwnedSpace(name);
       outputJson({ spaceId, name, hosted: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   space.command("host-request <name>").description("Emit a request asking the space owner to host it (delegate-only)").option("--emit [file]", "Write the request artifact to file (or stdout when no path)").addHelpText("after", `
@@ -34848,7 +35910,7 @@ it directly with \`tc space host <name>\` (no request needed).
       };
       await emitHostRequestArtifact(artifact, options.emit);
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   space.command("info [space-id]").description("Get space info").action(async (spaceId, _options, cmd) => {
@@ -34868,7 +35930,7 @@ it directly with \`tc space host <name>\` (no request needed).
         host: ctx.host
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   space.command("switch <name>").description("Switch active space").action(async (name, _options, cmd) => {
@@ -34878,13 +35940,13 @@ it directly with \`tc space host <name>\` (no request needed).
       await ProfileManager.updateProfile(ctx.profile, (profile) => ({ ...profile, spaceName: name }));
       outputJson({ profile: ctx.profile, spaceName: name, switched: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
 async function emitHostRequestArtifact(artifact, emitOption) {
   if (typeof emitOption === "string" && emitOption.length > 0) {
-    await mkdir5(dirname5(emitOption), { recursive: true });
+    await mkdir5(dirname6(emitOption), { recursive: true });
     await writeFile4(emitOption, JSON.stringify(artifact, null, 2) + "\n", "utf8");
     outputJson({
       emitted: true,
@@ -34991,7 +36053,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
         }
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   sql.command("execute <sql>").description("Run a write or schema statement").option("--db <name>", "SQLite database name within the current space", "default").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("--params <json>", "Bind parameters as a JSON array for ? placeholders").addHelpText("after", `
@@ -35024,7 +36086,7 @@ Output:
         lastInsertRowId: result.data.lastInsertRowId
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   sql.command("export").description("Export a SQLite database as a binary .db file").option("--db <name>", "SQLite database name within the current space", "default").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("-o, --output <file>", "Output file path", "export.db").addHelpText("after", `
@@ -35059,7 +36121,7 @@ Output:
         sizeHuman: formatBytes(blob.size)
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   sql.command("copy").description("Copy rows between SQL databases (optionally across spaces)").requiredOption("--from-db <name>", "Source database name").requiredOption("--to-db <name>", "Destination database name").option("--from-space <name|uri>", "Source space (defaults to primary)").option("--to-space <name|uri>", "Destination space (defaults to primary)").option("--table <name...>", "Restrict copy to specific tables (repeat or comma-separated)").option("--dry-run", "Print the plan without writing", false).addHelpText("after", `
@@ -35162,7 +36224,7 @@ Notes:
         tables: plan.map((p) => ({ table: p.table, rowsRead: p.rows, rowsWritten: p.copied }))
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -35218,7 +36280,7 @@ function registerStatusCommand(program) {
       }
       process.stdout.write(formatStatus(summary));
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
@@ -35519,10 +36581,10 @@ function formatSession(session) {
   return `${theme.success("present")}${formatExpiresAt(session.expiresAt)}`;
 }
 function formatDelegation2(delegation) {
-  const state = delegation.expired === true ? theme.warn("expired") : theme.success("active");
+  const state2 = delegation.expired === true ? theme.warn("expired") : theme.success("active");
   return [
     delegation.cid,
-    state,
+    state2,
     formatExpiresAt(delegation.expiresAt).trim(),
     plural(delegation.permissions.length, "permission")
   ].filter(Boolean).join("  ");
@@ -35599,13 +36661,13 @@ function registerUpgradeCommand(program) {
 `);
       }
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
 
 // src/commands/vault.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 init_profiles();
 init_formatter();
 init_errors();
@@ -35648,7 +36710,7 @@ function registerVaultCommand(program) {
       await withSpinner("Unlocking vault...", () => unlockVault(node, privateKey));
       outputJson({ unlocked: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vault.command("put <key> [value]").description("Encrypt and store a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (key, value, options, cmd) => {
@@ -35667,7 +36729,7 @@ function registerVaultCommand(program) {
         throw new CLIError("USAGE_ERROR", "Provide only one of: value argument, --file, or --stdin", ExitCode.USAGE_ERROR);
       }
       if (options.file) {
-        putValue = new Uint8Array(await readFile11(options.file));
+        putValue = new Uint8Array(await readFile12(options.file));
       } else if (options.stdin) {
         putValue = new Uint8Array(await readStdin4());
       } else {
@@ -35679,7 +36741,7 @@ function registerVaultCommand(program) {
       }
       outputJson({ key, written: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vault.command("get <key>").description("Decrypt and retrieve a value").option("--raw", "Output raw value (no JSON wrapping)").option("-o, --output <file>", "Write value to file").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (key, options, cmd) => {
@@ -35689,7 +36751,7 @@ function registerVaultCommand(program) {
       const privateKey = resolvePrivateKey(options);
       const node = await ensureAuthenticated(ctx, { privateKey });
       await withSpinner("Unlocking vault...", () => unlockVault(node, privateKey));
-      const result = await withSpinner(`Getting ${key}...`, () => node.vault.get(key));
+      const result = await withSpinner(`Getting ${key}...`, () => node.vault.get(key, { source: "network" }));
       if (!result.ok) {
         if (result.error.code === "NOT_FOUND") {
           throw new CLIError("NOT_FOUND", `Key "${key}" not found`, ExitCode.NOT_FOUND);
@@ -35713,7 +36775,7 @@ function registerVaultCommand(program) {
         data: data instanceof Uint8Array ? Buffer.from(data).toString("base64") : data
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vault.command("delete <key>").description("Delete an encrypted key").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (key, options, cmd) => {
@@ -35729,7 +36791,7 @@ function registerVaultCommand(program) {
       }
       outputJson({ key, deleted: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vault.command("list").description("List vault keys").option("--prefix <prefix>", "Filter by key prefix").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (options, cmd) => {
@@ -35739,7 +36801,7 @@ function registerVaultCommand(program) {
       const privateKey = resolvePrivateKey(options);
       const node = await ensureAuthenticated(ctx, { privateKey });
       await withSpinner("Unlocking vault...", () => unlockVault(node, privateKey));
-      const listOptions = options.prefix ? { prefix: options.prefix } : void 0;
+      const listOptions = options.prefix ? { prefix: options.prefix, source: "network" } : { source: "network" };
       const result = await withSpinner("Listing vault keys...", () => node.vault.list(listOptions));
       if (!result.ok) {
         throw cliErrorFromService(result.error);
@@ -35752,7 +36814,7 @@ function registerVaultCommand(program) {
         prefix: options.prefix ?? null
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vault.command("head <key>").description("Get metadata for a vault key").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (key, options, cmd) => {
@@ -35776,13 +36838,13 @@ function registerVaultCommand(program) {
         metadata: result.data.headers ?? result.data
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }
 
 // src/commands/vars.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 init_profiles();
 init_formatter();
 init_errors();
@@ -35827,7 +36889,7 @@ function registerVarsCommand(program) {
         count: keyList.length
       });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vars.command("get <name>").description("Get a variable value").option("--raw", "Output raw value (no JSON wrapping)").option("-o, --output <file>", "Write value to file").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (name, options, cmd) => {
@@ -35869,7 +36931,7 @@ function registerVarsCommand(program) {
       }
       outputJson({ name, value });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vars.command("put <name> [value]").description("Set a variable").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (name, value, options, cmd) => {
@@ -35887,7 +36949,7 @@ function registerVarsCommand(program) {
         throw new CLIError("USAGE_ERROR", "Provide only one of: value argument, --file, or --stdin", ExitCode.USAGE_ERROR);
       }
       if (options.file) {
-        varValue = await readFile12(options.file, "utf-8");
+        varValue = await readFile13(options.file, "utf-8");
       } else if (options.stdin) {
         varValue = (await readStdin5()).toString("utf-8");
       } else {
@@ -35904,7 +36966,7 @@ function registerVarsCommand(program) {
       }
       outputJson({ name, written: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
   vars.command("delete <name>").description("Delete a variable").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (name, options, cmd) => {
@@ -35920,7 +36982,7 @@ function registerVarsCommand(program) {
       }
       outputJson({ name, deleted: true });
     } catch (error) {
-      handleError(error);
+      return handleError(error);
     }
   });
 }