@tinycloud/sdk-services 3.2.6-beta.4 → 3.3.0-beta.25

package/dist/kv/replication/index.cjs

@@ -111,6 +111,14 @@ var ErrorCodes = {
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
   PERMISSION_DENIED: "PERMISSION_DENIED",
+  // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
+  // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
+  NODE_BUSY: "NODE_BUSY",
+  /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
@@ -146,11 +154,12 @@ var ErrorCodes = {
   DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
 };
 var defaultRetryPolicy = {
-  maxAttempts: 3,
+  maxAttempts: 4,
   backoff: "exponential",
-  baseDelayMs: 1e3,
-  maxDelayMs: 1e4,
-  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+  baseDelayMs: 250,
+  maxDelayMs: 4e3,
+  retryableErrors: [ErrorCodes.NODE_BUSY, ErrorCodes.REQUEST_TIMEOUT],
+  maxTotalMs: 12e3
 };
 function ok(data) {
   return { ok: true, data };
@@ -404,6 +413,35 @@ function emitEvent(emit, scheduler, event) {
   }
 }
 
+// src/kv/replication/grantPolicyConstants.ts
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+var DEFAULT_GRANT_TTL_MS = DAY_MS;
+var MAX_GRANT_TTL_MS = 7 * DAY_MS;
+var CONSENT_WINDOW_MS = 7 * DAY_MS;
+var RENEW_BELOW_FRACTION = 0.25;
+
+// src/kv/replication/grantPolicy.ts
+var EXPIRED = Number.NEGATIVE_INFINITY;
+var consentDeadlineMs = (anchor) => Number.isFinite(anchor.at) ? anchor.at + CONSENT_WINDOW_MS : EXPIRED;
+var clampConsentAnchor = (anchor, now) => {
+  if (anchor === null || !Number.isFinite(anchor.at) || !Number.isFinite(now)) return null;
+  return anchor.at > now ? { at: now, source: anchor.source } : anchor;
+};
+var mintRemainingMs = ({ now, grantTtlMs, consentDeadline }) => {
+  if (!Number.isFinite(now) || !Number.isFinite(grantTtlMs) || !Number.isFinite(consentDeadline)) return 0;
+  return Math.min(Math.min(grantTtlMs, MAX_GRANT_TTL_MS), consentDeadline - now);
+};
+var needsSilentRenewal = ({ now, installedAt, effectiveExpiresAt, consentDeadline }) => {
+  if (!Number.isFinite(now) || !Number.isFinite(installedAt) || !Number.isFinite(effectiveExpiresAt) || !Number.isFinite(consentDeadline)) {
+    return false;
+  }
+  if (!(now < consentDeadline)) return false;
+  const remaining = effectiveExpiresAt - now;
+  const lifetime = effectiveExpiresAt - installedAt;
+  return remaining < lifetime * RENEW_BELOW_FRACTION;
+};
+
 // src/kv/replication/controller.ts
 var CLOSE_TIMEOUT_MS = 3e3;
 var STATUS_REFRESH_TIMEOUT_MS = CLOSE_TIMEOUT_MS;
@@ -431,6 +469,128 @@ function createKVReplication(deps) {
   let previous = deps.previous;
   let pinnedStateReported = false;
   const inProcessProof = /* @__PURE__ */ new Set();
+  let anchorUnavailable = false;
+  let consentAnchor = null;
+  try {
+    consentAnchor = clampConsentAnchor(authority.consentAnchor?.() ?? null, scheduler.now());
+    if (consentAnchor?.source === "first_install") consentAnchor = null;
+  } catch {
+    anchorUnavailable = true;
+  }
+  const grantPolicy = { grantTtlMs: options.grantTtlMs ?? DEFAULT_GRANT_TTL_MS, consentAnchor };
+  const quota = options.maxBytes === void 0 && options.minFreeBytes === void 0 ? void 0 : { maxBytes: options.maxBytes, minFreeBytes: options.minFreeBytes };
+  const policyDeadline = consentAnchor === null ? null : consentDeadlineMs(consentAnchor);
+  let scheduledConsentDeadline = null;
+  let cancelConsentTimer;
+  function durableDeadline() {
+    if (storage.kind !== "indexeddb" || !deps.stamp) return null;
+    try {
+      const deadline = storage.lifecycle?.consentDeadline(deps.stamp);
+      return typeof deadline === "number" && Number.isFinite(deadline) ? deadline : null;
+    } catch {
+      return null;
+    }
+  }
+  function mintDeadline() {
+    if (policyDeadline === null) return null;
+    if (storage.kind !== "indexeddb") return policyDeadline;
+    const durable = durableDeadline();
+    return durable === null ? null : Math.min(policyDeadline, durable);
+  }
+  function scheduleConsentDeadline() {
+    const deadline = durableDeadline();
+    if (deadline === null || consentDenyStarted || isClosed) return;
+    const now = scheduler.now();
+    if (!Number.isFinite(now)) return;
+    if (scheduledConsentDeadline === deadline && cancelConsentTimer) return;
+    scheduledConsentDeadline = deadline;
+    cancelConsentTimer?.();
+    cancelConsentTimer = scheduler.setTimeout(() => {
+      cancelConsentTimer = void 0;
+      checkDelivery();
+    }, Math.max(0, deadline - now));
+  }
+  const reportedDeadline = /* @__PURE__ */ new Set();
+  let consentDenyStarted = false;
+  function checkDelivery() {
+    const gate = storage.lifecycle;
+    if (!gate) return storage.kind === "indexeddb" || anchorUnavailable || deps.stamp !== void 0 ? { status: "gated", gate: "gate_unavailable" } : { status: "allow" };
+    if (!deps.stamp) return { status: "gated", gate: "not_established" };
+    if (consentDenyStarted) return { status: "gated", gate: "stamp_stale" };
+    try {
+      const decision = gate.checkDelivery(deps.stamp);
+      if (decision.status === "consent_expired") startConsentDenial();
+      if (decision.status !== "allow") return decision;
+      if (storage.kind === "indexeddb") {
+        const deadline = durableDeadline();
+        if (deadline === null) return { status: "gated", gate: "gate_unavailable" };
+        const now = scheduler.now();
+        if (!Number.isFinite(now)) return { status: "gated", gate: "gate_unavailable" };
+        if (now >= deadline) {
+          startConsentDenial();
+          return { status: "consent_expired", code: "CONSENT_EXPIRED" };
+        }
+      }
+      return anchorUnavailable ? { status: "gated", gate: "gate_unavailable" } : decision;
+    } catch {
+      return { status: "gated", gate: "gate_unavailable" };
+    }
+  }
+  function markConsentExpired() {
+    if (consentDenyStarted || isClosed || purgeStarted) return false;
+    cancelConsentTimer?.();
+    cancelConsentTimer = void 0;
+    consentDenyStarted = true;
+    for (const state of replicas.values()) {
+      state.renewalTimer?.();
+      state.renewalTimer = void 0;
+      state.mintAbort?.abort();
+      const id = state.handle?.replicaId;
+      if (id && !reportedDeadline.has(id)) {
+        reportedDeadline.add(id);
+        emit({ type: "replication.grant", replicaId: id, action: "consent_deadline_reached", code: "CONSENT_EXPIRED" });
+      }
+    }
+    return true;
+  }
+  function observeConsentExpired(stamp) {
+    if (!deps.stamp || stamp.incarnation !== deps.stamp.incarnation || stamp.lifecycleEpoch !== deps.stamp.lifecycleEpoch) return;
+    if (markConsentExpired()) emit({ type: "replication.lifecycle", action: "denied", reason: "consent_expired" });
+  }
+  function startConsentDenial() {
+    const gate = storage.lifecycle;
+    if (!gate || !markConsentExpired()) return;
+    void gate.deny({ reason: "consent_expired", principal: identity.principal }).then(
+      (outcome) => emit({ type: "replication.lifecycle", action: outcome.status === "denied" ? "denied" : outcome.status === "stale" ? "deny_stale" : outcome.status === "deleted" ? "database_deleted" : outcome.status === "marker" ? "marker_set" : "unguarded", reason: "consent_expired" }),
+      () => emit({ type: "replication.lifecycle", action: "deny_failed", reason: "consent_expired" })
+    );
+  }
+  function deliveryError(decision) {
+    return Object.assign(new Error(decision.status === "consent_expired" ? "Replica consent expired" : "Replica session is gated"), {
+      code: decision.status === "consent_expired" ? decision.code : "REPLICA_GATED",
+      ...decision.status === "gated" ? { gate: decision.gate } : {}
+    });
+  }
+  function deliveryReason(code) {
+    return code === "CONSENT_EXPIRED" || code === "GRANT_EXPIRED" ? "grant_expired" : code === "REPLICA_GATED" ? "replica_gated" : "replica_error";
+  }
+  function reportGrantExpiry(prefix) {
+    const state = replicas.get(prefix);
+    if (!state) return;
+    state.reason = "grant_expired";
+    state.lastError = "GRANT_EXPIRED";
+    const replicaId = state.handle?.replicaId;
+    if (!replicaId || state.reportedExpired) return;
+    state.reportedExpired = true;
+    emit({ type: "replication.grant", replicaId, action: "expired", code: "GRANT_EXPIRED" });
+  }
+  function reportGrantCap(state, handle, grant) {
+    if (!grant?.unconstrained || !handle.replicaId || typeof grant.effectiveExpiresAt !== "number" || !Number.isFinite(grant.effectiveExpiresAt) || !(grant.expiresAt === null || grant.effectiveExpiresAt < grant.expiresAt)) return;
+    const capKey = `${grant.cid}:${grant.effectiveExpiresAt}`;
+    if (state.reportedCappedCid === capKey) return;
+    state.reportedCappedCid = capKey;
+    emit({ type: "replication.grant", replicaId: handle.replicaId, action: "capped", effectiveExpiresAt: nowDate(grant.effectiveExpiresAt) });
+  }
   const configuredPrefix = (path) => options.prefixes.find((prefix) => kvPrefixCovers(prefix, path));
   function recordRevocation(prefix, error) {
     if (errorCode(error) !== "GRANT_REVOKED") return;
@@ -454,7 +614,26 @@ function createKVReplication(deps) {
     markRootUnsupported(prefix);
     return Object.assign(new Error("This node doesn't support whole-space sync yet."), { code: "REPLICATION_ROOT_UNSUPPORTED" });
   }
+  function canReuseInstalled(grant, sessionOnly) {
+    if (!grant?.unconstrained) return false;
+    if (!deps.stamp) return true;
+    if (!sessionOnly && consentAnchor === null) return false;
+    const now = scheduler.now();
+    const deadline = storage.kind === "indexeddb" ? durableDeadline() : policyDeadline ?? grant.consentDeadline;
+    return grant.state === "active" && typeof grant.installedAt === "number" && Number.isFinite(grant.installedAt) && typeof grant.effectiveExpiresAt === "number" && Number.isFinite(grant.effectiveExpiresAt) && typeof grant.consentDeadline === "number" && Number.isFinite(grant.consentDeadline) && typeof deadline === "number" && Number.isFinite(deadline) && Number.isFinite(now) && now >= grant.installedAt && (grant.expiresAt === null || typeof grant.expiresAt === "number" && Number.isFinite(grant.expiresAt) && now < grant.expiresAt) && now < Math.min(grant.effectiveExpiresAt, grant.consentDeadline, deadline);
+  }
+  function sessionRefusal(prefix) {
+    try {
+      if (authority.sessionOnly !== true) return void 0;
+      const grant = authority.sessionGrant(prefix);
+      return "refused" in grant ? grant.refused : void 0;
+    } catch {
+      return "NOT_COVERED";
+    }
+  }
   async function open(prefix) {
+    const delivery = checkDelivery();
+    if (delivery.status !== "allow") throw deliveryError(delivery);
     if (isClosed || purgeStarted) throw Object.assign(new Error("Replication controller is closed"), { code: "REPLICA_CLOSED" });
     let state = replicas.get(prefix);
     if (state?.handle) return state.handle;
@@ -475,46 +654,99 @@ function createKVReplication(deps) {
         await previous;
         previous = void 0;
       }
+      const delivery2 = checkDelivery();
+      if (delivery2.status !== "allow") throw deliveryError(delivery2);
+      const sessionOnly = authority.sessionOnly === true;
       const sessionGrant = authority.sessionGrant(prefix);
       const delegated = "refused" in sessionGrant ? void 0 : sessionGrant;
-      const plan = authority.sessionOnly ? void 0 : authority.plan(prefix);
+      const plan = sessionOnly ? void 0 : authority.plan(prefix);
       let refusalCode;
       if ("refused" in sessionGrant) refusalCode = sessionGrant.refused;
       if (plan && "refused" in plan) refusalCode ?? (refusalCode = plan.refused);
+      if (deps.stamp && consentAnchor === null && !sessionOnly) refusalCode = "REPLICA_GATED";
       let device;
       if (delegated) {
         device = delegated.device;
         state.strategy = "session";
       }
-      const spec = { identity, space: session.space, prefix, allowSecrets: options.allowSecrets, ...device ? { device } : {}, ...deps.fetch ? { fetch: deps.fetch } : {} };
+      const spec = {
+        identity,
+        space: session.space,
+        prefix,
+        allowSecrets: options.allowSecrets,
+        grantPolicy,
+        ...quota ? { quota } : {},
+        ...deps.stamp ? { stamp: deps.stamp } : {},
+        ...device ? { device } : {},
+        ...deps.fetch ? { fetch: deps.fetch } : {},
+        onPeerCommit: (info) => {
+          if (isClosed || purgeStarted || state.handle === void 0) return;
+          emit({
+            type: "replication.sync",
+            space: session.space,
+            replica: prefix,
+            trigger: "peer",
+            origin: "peer",
+            outcome: "ok",
+            durationMs: 0,
+            lagMs: null,
+            ...info.changes === void 0 ? {} : { changes: info.changes },
+            ...info.coverage === void 0 ? {} : { coverage: info.coverage }
+          });
+        }
+      };
       if (prefix === "/" && deps.nodeFeatures !== void 0 && !deps.nodeFeatures.includes("kv-sync-root")) {
         throw unsupportedRoot(prefix);
       }
       const handle = await storage.open(spec);
       state.handle = handle;
+      const afterOpen = checkDelivery();
+      if (afterOpen.status !== "allow") throw deliveryError(afterOpen);
       emit({ type: "replication.state", space: session.space, replica: prefix, state: "opened" });
-      const runtimePlan = !authority.sessionOnly && plan && !("refused" in plan) ? plan : void 0;
-      let installed = runtimePlan ? await handle.grant() : void 0;
-      if (delegated) installed = await handle.installGrant(delegated.ucan);
-      else if (runtimePlan) {
+      const runtimePlan = !sessionOnly && plan && !("refused" in plan) ? plan : void 0;
+      let installed = runtimePlan || delegated ? await handle.grant() : void 0;
+      if (installed && !canReuseInstalled(installed, sessionOnly)) {
+        if (installed.unconstrained) refusalCode = consentAnchor === null && !sessionOnly ? "REPLICA_GATED" : "GRANT_EXPIRED";
+        installed = void 0;
+      }
+      let mintedExpiryMs;
+      if (delegated && consentAnchor !== null) {
+        const beforeInstall = checkDelivery();
+        if (beforeInstall.status !== "allow") throw deliveryError(beforeInstall);
+        installed = await handle.installGrant(delegated.ucan);
+      } else if (runtimePlan) {
         if (!installed || !installed.unconstrained || installed.parentCid !== runtimePlan.parentCid || installed.expiresAt !== null && runtimePlan.expiresAt > installed.expiresAt + 3e5) {
-          try {
-            const mintAbort = new AbortController();
-            state.mintAbort = mintAbort;
-            const minted = await authority.mint(handle.deviceDid, prefix, mintAbort.signal);
-            installed = await handle.installGrant(minted.ucan);
-            state.strategy = "minted";
-          } catch (error) {
-            if (!installed?.unconstrained) throw error;
-          } finally {
-            state.mintAbort = void 0;
+          const deadline = mintDeadline();
+          const expiryMs = mintRemainingMs({ now: scheduler.now(), grantTtlMs: grantPolicy.grantTtlMs, consentDeadline: deadline ?? Number.NaN });
+          if (expiryMs > 0) {
+            try {
+              const mintAbort = new AbortController();
+              state.mintAbort = mintAbort;
+              const minted = await authority.mint(handle.deviceDid, prefix, mintAbort.signal, { expiryMs });
+              const beforeInstall = checkDelivery();
+              if (beforeInstall.status !== "allow") throw deliveryError(beforeInstall);
+              installed = await handle.installGrant(minted.ucan);
+              state.strategy = "minted";
+              mintedExpiryMs = expiryMs;
+            } catch (error) {
+              if (errorCode(error) === "CONSENT_EXPIRED" || errorCode(error) === "REPLICA_GATED" || !installed?.unconstrained) throw error;
+            } finally {
+              state.mintAbort = void 0;
+            }
           }
         }
         if (installed?.unconstrained) {
           state.strategy ?? (state.strategy = "installed");
           state.reason = void 0;
         }
+      } else if ((delegated || sessionOnly) && installed?.unconstrained) {
+        state.strategy = "installed";
       }
+      const beforeGrantEvent = checkDelivery();
+      if (beforeGrantEvent.status !== "allow") throw deliveryError(beforeGrantEvent);
+      reportGrantCap(state, handle, installed);
+      if (mintedExpiryMs !== void 0) state.reportedExpired = false;
+      if (mintedExpiryMs !== void 0 && handle.replicaId) emit({ type: "replication.grant", replicaId: handle.replicaId, action: "minted", expiryMs: mintedExpiryMs });
       if (!installed?.unconstrained) {
         state.reason = "grant_missing";
         state.lastError = refusalCode ?? "SESSION_LACKS_SYNC";
@@ -524,6 +756,7 @@ function createKVReplication(deps) {
         await handle.close();
         throw Object.assign(new Error("Replication controller is closed"), { code: "REPLICA_CLOSED" });
       }
+      if (installed?.unconstrained) await maybeRenew(prefix, handle, installed, runtimePlan);
       if (mode === "background" && state.reason !== "grant_missing") {
         void syncPrefix(prefix, "start").catch(() => void 0);
         schedule(prefix);
@@ -534,12 +767,14 @@ function createKVReplication(deps) {
       return await state.opening;
     } catch (error) {
       const code = errorCode(error);
+      if (code === "CONSENT_EXPIRED") startConsentDenial();
       recordRevocation(prefix, error);
-      if (code !== "GRANT_REVOKED") state.reason = "replica_unavailable";
+      if (code === "REPLICA_GATED" || code === "CONSENT_EXPIRED") state.reason = deliveryReason(code);
+      else if (code !== "GRANT_REVOKED") state.reason = "replica_unavailable";
       state.lastError = code;
       state.failures = (state.failures ?? 0) + 1;
       if (code === "RUNTIME_UNSUPPORTED") state.unsupported = true;
-      else if (code !== "REPLICA_CLOSED" && code !== "REPLICATION_ROOT_UNSUPPORTED") state.retryAt = scheduler.now() + Math.min(3e5, 5e3 * 2 ** Math.min(state.failures - 1, 6));
+      else if (code !== "REPLICA_CLOSED" && code !== "REPLICATION_ROOT_UNSUPPORTED" && code !== "REPLICA_GATED" && code !== "CONSENT_EXPIRED") state.retryAt = scheduler.now() + Math.min(3e5, 5e3 * 2 ** Math.min(state.failures - 1, 6));
       state.handle?.close().catch(() => void 0);
       state.handle = void 0;
       throw error;
@@ -547,6 +782,96 @@ function createKVReplication(deps) {
       state.opening = void 0;
     }
   }
+  function scheduleRenewal(prefix, handle, grant, plan) {
+    const state = replicas.get(prefix);
+    state?.renewalTimer?.();
+    if (state) state.renewalTimer = void 0;
+    if (!state || isClosed || purgeStarted || plan.path !== "session" || !authority.canRenew) return;
+    const { installedAt, effectiveExpiresAt } = grant;
+    const deadline = mintDeadline();
+    if (typeof installedAt !== "number" || !Number.isFinite(installedAt) || typeof effectiveExpiresAt !== "number" || !Number.isFinite(effectiveExpiresAt) || !(effectiveExpiresAt > installedAt) || deadline === null) return;
+    const threshold = installedAt + (effectiveExpiresAt - installedAt) * (1 - RENEW_BELOW_FRACTION);
+    const now = scheduler.now();
+    if (!Number.isFinite(now) || !(threshold < deadline) || now > threshold) return;
+    state.renewalTimer = scheduler.setTimeout(() => {
+      state.renewalTimer = void 0;
+      void maybeRenew(prefix, handle).catch(() => void 0);
+    }, Math.max(0, Math.floor(threshold) + 1 - now));
+  }
+  async function maybeRenew(prefix, handle, knownGrant, knownPlan) {
+    const state = replicas.get(prefix);
+    if (!state || state.handle !== handle || isClosed || purgeStarted || !authority.canRenew) return;
+    if (state.renewing) return state.renewing;
+    const decision = checkDelivery();
+    if (decision.status !== "allow") return;
+    const grant = knownGrant ?? await handle.grant();
+    if (!grant?.unconstrained) return;
+    const { installedAt, effectiveExpiresAt } = grant;
+    const deadline = mintDeadline();
+    if (typeof installedAt !== "number" || !Number.isFinite(installedAt) || typeof effectiveExpiresAt !== "number" || !Number.isFinite(effectiveExpiresAt) || deadline === null) return;
+    const now = scheduler.now();
+    if (!needsSilentRenewal({ now, installedAt, effectiveExpiresAt, consentDeadline: deadline })) {
+      if (knownPlan) scheduleRenewal(prefix, handle, grant, knownPlan);
+      return;
+    }
+    let plan = knownPlan;
+    try {
+      if (!plan) {
+        const selected = authority.plan(prefix);
+        if ("refused" in selected) {
+          if (handle.replicaId) emit({ type: "replication.grant", replicaId: handle.replicaId, action: "renewal_refused", code: selected.refused });
+          return;
+        }
+        plan = selected;
+      }
+    } catch {
+      if (handle.replicaId) emit({ type: "replication.grant", replicaId: handle.replicaId, action: "renewal_deferred" });
+      return;
+    }
+    if (plan?.path !== "session") {
+      if (handle.replicaId && state.reportedRenewalUnqualifiedCid !== grant.cid) {
+        state.reportedRenewalUnqualifiedCid = grant.cid;
+        emit({ type: "replication.grant", replicaId: handle.replicaId, action: "renewal_deferred" });
+      }
+      return;
+    }
+    const expiryMs = mintRemainingMs({ now, grantTtlMs: grantPolicy.grantTtlMs, consentDeadline: deadline });
+    if (!(expiryMs > 0)) return;
+    state.renewalTimer?.();
+    state.renewalTimer = void 0;
+    const mintAbort = new AbortController();
+    state.mintAbort = mintAbort;
+    const job = Promise.resolve().then(async () => {
+      const minted = await authority.mint(handle.deviceDid, prefix, mintAbort.signal, { expiryMs, renewalOnly: true });
+      const beforeInstall = checkDelivery();
+      if (beforeInstall.status !== "allow") throw deliveryError(beforeInstall);
+      const installed = await handle.installGrant(minted.ucan);
+      const beforeEvent = checkDelivery();
+      if (beforeEvent.status !== "allow") throw deliveryError(beforeEvent);
+      reportGrantCap(state, handle, installed);
+      state.reportedExpired = false;
+      if (state.reason === "grant_expired") state.reason = void 0;
+      if (state.lastError === "GRANT_EXPIRED") state.lastError = void 0;
+      if (handle.replicaId) emit({ type: "replication.grant", replicaId: handle.replicaId, action: "renewed", expiryMs });
+      if (typeof installed.effectiveExpiresAt === "number" && installed.effectiveExpiresAt > effectiveExpiresAt) {
+        scheduleRenewal(prefix, handle, installed, plan);
+      }
+    });
+    state.renewing = job;
+    try {
+      await job;
+    } catch (error) {
+      const code = errorCode(error);
+      if (code === "CONSENT_EXPIRED" || code === "REPLICA_GATED") throw error;
+      if (!isClosed && handle.replicaId) {
+        const refused = typeof error === "object" && error !== null && "refused" in error && typeof error.refused === "string" ? error.refused : null;
+        emit({ type: "replication.grant", replicaId: handle.replicaId, action: refused ? "renewal_refused" : "renewal_deferred", code: refused ?? code });
+      }
+    } finally {
+      state.renewing = void 0;
+      if (state.mintAbort === mintAbort) state.mintAbort = void 0;
+    }
+  }
   function schedule(prefix) {
     const state = replicas.get(prefix);
     if (!state || mode !== "background" || isClosed || purgeStarted) return;
@@ -559,6 +884,8 @@ function createKVReplication(deps) {
     if (prefix === "/" && deps.nodeFeatures !== void 0 && !deps.nodeFeatures.includes("kv-sync-root")) {
       throw unsupportedRoot(prefix);
     }
+    const initialRefusal = sessionRefusal(prefix);
+    if (initialRefusal) throw Object.assign(new Error("Current session does not cover replica sync"), { code: initialRefusal });
     const handle = await open(prefix);
     const state = replicas.get(prefix);
     if (state.sync) return state.sync;
@@ -576,22 +903,36 @@ function createKVReplication(deps) {
     job = (async () => {
       try {
         const syncStartEpoch = (await pending.read()).committedEpoch;
+        const beforeSync = checkDelivery();
+        if (beforeSync.status !== "allow") throw deliveryError(beforeSync);
+        await maybeRenew(prefix, handle);
+        const afterRenewal = checkDelivery();
+        if (afterRenewal.status !== "allow") throw deliveryError(afterRenewal);
+        const refusal = sessionRefusal(prefix);
+        if (refusal) throw Object.assign(new Error("Current session does not cover replica sync"), { code: refusal });
         const result = await handle.sync({ signal: abort.signal, syncStartEpoch });
+        const afterSyncDelivery = checkDelivery();
+        if (afterSyncDelivery.status !== "allow") throw deliveryError(afterSyncDelivery);
         if (result.status === "busy") {
           emit({ type: "replication.sync", space: session.space, replica: prefix, trigger, outcome: "busy", durationMs: scheduler.now() - started, lagMs: null });
           return result;
         }
         inProcessProof.add(prefix);
         const snapshot = await pending.read();
+        const beforePending = checkDelivery();
+        if (beforePending.status !== "allow") throw deliveryError(beforePending);
         const clearedCandidates = snapshot.records.some((r) => r.state === "committed" && r.epoch !== null && r.epoch <= syncStartEpoch && kvPrefixCovers(prefix, r.key));
         const cleared = clearedCandidates ? await pending.update((s) => afterSync(s, prefix, syncStartEpoch)) : 0;
+        const beforeResult = checkDelivery();
+        if (beforeResult.status !== "allow") throw deliveryError(beforeResult);
         emit({ type: "replication.sync", space: session.space, replica: prefix, trigger, outcome: "ok", durationMs: scheduler.now() - started, lagMs: null, pendingCleared: cleared, pages: result.pages, changes: result.changes, deleted: result.deleted, fetched: result.fetched, contentMissing: result.contentMissing, coverage: result.coverage });
         return result;
       } catch (error) {
         const code = errorCode(error);
         state.lastError = code;
         recordRevocation(prefix, error);
-        emit({ type: "replication.sync", space: session.space, replica: prefix, trigger, outcome: abort.signal.aborted ? "aborted" : "error", class: code === "NETWORK_ERROR" || code === "TIMEOUT" ? "offline" : "node", code, durationMs: scheduler.now() - started, lagMs: null });
+        if (code === "CONSENT_EXPIRED") startConsentDenial();
+        emit({ type: "replication.sync", space: session.space, replica: prefix, trigger, outcome: abort.signal.aborted ? "aborted" : "error", class: code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" ? "lifecycle" : code === "NETWORK_ERROR" || code === "TIMEOUT" ? "offline" : "node", code, durationMs: scheduler.now() - started, lagMs: null });
         throw error;
       } finally {
         signal?.removeEventListener("abort", abortFromCaller);
@@ -747,8 +1088,19 @@ function createKVReplication(deps) {
     return { status: currentStatus, syncedBeforeRead: false };
   }
   function readEvent(op, path, prefix, source, reason, outcome, started, extra = {}) {
+    if (prefix !== null && reason === "grant_expired" && extra.code !== "CONSENT_EXPIRED") reportGrantExpiry(prefix);
     emit({ type: "replication.read", op, space: session.space, key: path, replica: prefix, source, reason, outcome, latencyMs: scheduler.now() - started, stalenessMs: null, coverage: null, authority: null, ...extra });
   }
+  async function networkRead(network, op, path, prefix, reason, started, extra = {}) {
+    let outcome = "error";
+    try {
+      const result = await network();
+      outcome = result.ok ? "found" : op === "get" && (reason === "pending_write" || reason === "not_covered") && result.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error";
+      return result;
+    } finally {
+      readEvent(op, path, prefix, "network", reason, outcome, started, extra);
+    }
+  }
   async function verifyGet(r, local, reason, started, extra) {
     const prefix = configuredPrefix(r.path) ?? null;
     const localFound = local.ok;
@@ -760,6 +1112,16 @@ function createKVReplication(deps) {
         readEvent("get", r.path, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
         return abortedResult(r.signal);
       }
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") {
+        readEvent("get", r.path, prefix, "network", delivery.status === "consent_expired" ? "grant_expired" : "replica_gated", network.ok ? "found" : "error", started, { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" });
+        return network;
+      }
+      const refusal = prefix === null ? void 0 : sessionRefusal(prefix);
+      if (refusal) {
+        readEvent("get", r.path, prefix, "network", "grant_missing", network.ok ? "found" : "error", started, { code: refusal });
+        return network;
+      }
       if (!network.ok && network.error.code !== ErrorCodes.KV_NOT_FOUND) {
         readEvent("get", r.path, prefix, "replica", reason, outcome, started, { ...extra, code: network.error.code, verify: "error" });
         return local;
@@ -790,6 +1152,16 @@ function createKVReplication(deps) {
         readEvent("get", r.path, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
         return abortedResult(r.signal);
       }
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") {
+        readEvent("get", r.path, prefix, "network", delivery.status === "consent_expired" ? "grant_expired" : "replica_gated", "error", started, { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" });
+        return err(wrapError("kv", error));
+      }
+      const refusal = prefix === null ? void 0 : sessionRefusal(prefix);
+      if (refusal) {
+        readEvent("get", r.path, prefix, "network", "grant_missing", "error", started, { code: refusal });
+        return err(wrapError("kv", error));
+      }
       readEvent("get", r.path, prefix, "replica", reason, outcome, started, { ...extra, code: errorCode(error), verify: "error" });
       return local;
     }
@@ -802,6 +1174,16 @@ function createKVReplication(deps) {
         readEvent("list", r.listPath, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
         return abortedResult(r.signal);
       }
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") {
+        readEvent("list", r.listPath, prefix, "network", delivery.status === "consent_expired" ? "grant_expired" : "replica_gated", network.ok ? "found" : "error", started, { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" });
+        return network;
+      }
+      const refusal = prefix === null ? void 0 : sessionRefusal(prefix);
+      if (refusal) {
+        readEvent("list", r.listPath, prefix, "network", "grant_missing", network.ok ? "found" : "error", started, { code: refusal });
+        return network;
+      }
       if (!network.ok) {
         readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, { ...extra, code: network.error.code, verify: "error" });
         return ok(local);
@@ -832,6 +1214,16 @@ function createKVReplication(deps) {
         readEvent("list", r.listPath, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
         return abortedResult(r.signal);
       }
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") {
+        readEvent("list", r.listPath, prefix, "network", delivery.status === "consent_expired" ? "grant_expired" : "replica_gated", "error", started, { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" });
+        return err(wrapError("kv", error));
+      }
+      const refusal = prefix === null ? void 0 : sessionRefusal(prefix);
+      if (refusal) {
+        readEvent("list", r.listPath, prefix, "network", "grant_missing", "error", started, { code: refusal });
+        return err(wrapError("kv", error));
+      }
       readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, { ...extra, code: errorCode(error), verify: "error" });
       return ok(local);
     }
@@ -860,11 +1252,26 @@ function createKVReplication(deps) {
         observeNetworkRequested({ op: "get", space: r.space, path: r.path, reason: "NETWORK_REQUESTED", outcome, latencyMs: scheduler.now() - started });
       }
     }
-    if (prefix === void 0) {
-      const value = await r.network();
-      readEvent("get", r.path, null, "network", "not_covered", value.ok ? "found" : value.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error", started);
-      return value;
+    let networkRejected = false;
+    const fallback = async (replica, reason, extra = {}) => {
+      try {
+        return await networkRead(r.network, "get", r.path, replica, reason, started, extra);
+      } catch (error) {
+        networkRejected = true;
+        throw error;
+      }
+    };
+    if (prefix === void 0) return networkRead(r.network, "get", r.path, null, "not_covered", started);
+    const delivery = checkDelivery();
+    if (delivery.status !== "allow") {
+      return fallback(
+        prefix,
+        delivery.status === "consent_expired" ? "grant_expired" : "replica_gated",
+        { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" }
+      );
     }
+    const refusal = sessionRefusal(prefix);
+    if (refusal) return fallback(prefix, "grant_missing", { code: refusal });
     try {
       await raceSignal(reportExistingPins(), r.signal);
     } catch {
@@ -875,86 +1282,63 @@ function createKVReplication(deps) {
       handle = await raceSignal(open(prefix), r.signal);
     } catch (error) {
       if (r.signal.aborted) return abortedResult(r.signal);
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", errorCode(error) === "RUNTIME_UNSUPPORTED" ? "runtime_unsupported" : "replica_unavailable", value.ok ? "found" : "error", started, { code: errorCode(error) });
-      return value;
+      if (errorCode(error) === "CONSENT_EXPIRED") startConsentDenial();
+      const code = errorCode(error);
+      return fallback(prefix, code === "RUNTIME_UNSUPPORTED" ? "runtime_unsupported" : code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_unavailable", { code });
     }
     if (replicas.get(prefix)?.reason === "grant_missing") {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "grant_missing", value.ok ? "found" : "error", started, { code: replicas.get(prefix)?.lastError });
-      return value;
+      const code = replicas.get(prefix)?.lastError;
+      return fallback(prefix, code === "GRANT_EXPIRED" ? "grant_expired" : code === "REPLICA_GATED" ? "replica_gated" : "grant_missing", { code });
     }
     let fresh;
     try {
       fresh = await freshness(prefix, handle, r.signal);
     } catch (error) {
       recordRevocation(prefix, error);
+      if (errorCode(error) === "CONSENT_EXPIRED") startConsentDenial();
       if (r.signal.aborted) return abortedResult(r.signal);
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "replica_error", value.ok ? "found" : "error", started, { code: errorCode(error) });
-      return value;
+      const code = errorCode(error);
+      return fallback(prefix, code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_error", { code });
     }
     if (r.signal.aborted) return abortedResult(r.signal);
     if (fresh.failure) {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", fresh.failure === "busy" ? "stale" : "stale", value.ok ? "found" : "error", started, { code: fresh.failure === "busy" ? "REPLICA_BUSY" : fresh.syncError, syncedBeforeRead: fresh.syncedBeforeRead });
-      return value;
+      const code = fresh.failure === "busy" ? "REPLICA_BUSY" : fresh.syncError;
+      return fallback(
+        prefix,
+        code === "GRANT_REVOKED" ? "grant_revoked" : code === "REPLICA_GATED" || code === "CONSENT_EXPIRED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "stale",
+        { code, syncedBeforeRead: fresh.syncedBeforeRead }
+      );
     }
     let pendingState;
     try {
       pendingState = await raceSignal(pending.read(), r.signal);
     } catch (error) {
       if (r.signal.aborted) return abortedResult(r.signal);
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "replica_unavailable", value.ok ? "found" : "error", started, { code: errorCode(error) });
-      return value;
+      const code = errorCode(error);
+      return fallback(prefix, code === "REPLICA_GATED" || code === "CONSENT_EXPIRED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_unavailable", { code });
     }
     const record = pendingState.records.find((x) => x.key === r.path);
-    if (record) {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "pending_write", value.ok ? "found" : value.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error", started, { pendingState: record.state, syncedBeforeRead: fresh.syncedBeforeRead });
-      return value;
-    }
-    if (!pending.durable && !inProcessProof.has(prefix)) {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "REPLICA_UNPROVEN_SINCE_START", value.ok ? "found" : "error", started);
-      return value;
-    }
-    if (fresh.status.syncedThroughEpoch < pendingState.committedEpoch) {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "REPLICA_BEHIND_OWN_WRITES", value.ok ? "found" : "error", started);
-      return value;
-    }
-    if (fresh.status.authority.state !== "valid") {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", fresh.status.authority.state === "expired" ? "grant_expired" : fresh.status.authority.state === "revoked" ? "grant_revoked" : "grant_not_yet_valid", value.ok ? "found" : "error", started);
-      return value;
-    }
-    if (fresh.status.coverage !== "complete") {
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "coverage_incomplete", value.ok ? "found" : "error", started);
-      return value;
-    }
+    if (record) return fallback(prefix, "pending_write", { pendingState: record.state, syncedBeforeRead: fresh.syncedBeforeRead });
+    if (!pending.durable && !inProcessProof.has(prefix)) return fallback(prefix, "REPLICA_UNPROVEN_SINCE_START");
+    if (fresh.status.syncedThroughEpoch < pendingState.committedEpoch) return fallback(prefix, "REPLICA_BEHIND_OWN_WRITES");
+    if (fresh.status.authority.state !== "valid") return fallback(prefix, fresh.status.authority.state === "expired" ? "grant_expired" : fresh.status.authority.state === "revoked" ? "grant_revoked" : "grant_not_yet_valid");
+    if (fresh.status.coverage !== "complete") return fallback(prefix, "coverage_incomplete");
     try {
       const local = await raceSignal(handle.get(r.path), r.signal);
+      const delivery2 = checkDelivery();
+      if (delivery2.status !== "allow") throw deliveryError(delivery2);
+      const refusal2 = sessionRefusal(prefix);
+      if (refusal2) return await fallback(prefix, "grant_missing", { code: refusal2 });
       try {
         validateReadMeta(local.meta);
       } catch (error) {
         const code = errorCode(error);
         recordRevocation(prefix, error);
-        const value = await r.network();
-        readEvent("get", r.path, prefix, "network", reasonForReadMetaCode(code), value.ok ? "found" : "error", started, { code });
-        return value;
-      }
-      if (local.status === "coverage_incomplete" || local.status === "not_covered" || local.status === "content_missing") {
-        const value = await r.network();
-        readEvent("get", r.path, prefix, "network", local.status === "content_missing" ? "content_missing" : local.status === "coverage_incomplete" ? "coverage_incomplete" : "not_covered", value.ok ? "found" : "error", started);
-        return value;
+        return await fallback(prefix, reasonForReadMetaCode(code), { code });
       }
+      if (local.status === "coverage_incomplete" || local.status === "not_covered" || local.status === "content_missing") return await fallback(prefix, local.status === "content_missing" ? "content_missing" : local.status === "coverage_incomplete" ? "coverage_incomplete" : "not_covered");
       if (local.status === "present" && r.options?.maxResponseBytes !== void 0 && local.value.byteLength > r.options.maxResponseBytes) {
-        const value = await r.network();
-        readEvent("get", r.path, prefix, "network", "unsupported_option", value.ok ? "found" : "error", started);
-        return value;
+        return await fallback(prefix, "unsupported_option");
       }
       const result = localGet(local, r.path, r.options ?? {});
       const reason = local.status === "present" ? "hit" : local.status;
@@ -970,11 +1354,11 @@ function createKVReplication(deps) {
       readEvent("get", r.path, prefix, "replica", reason, result.ok ? "found" : result.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error", started, event);
       return result;
     } catch (error) {
+      if (networkRejected) throw error;
       recordRevocation(prefix, error);
+      if (errorCode(error) === "CONSENT_EXPIRED") startConsentDenial();
       if (r.signal.aborted) return abortedResult(r.signal);
-      const value = await r.network();
-      readEvent("get", r.path, prefix, "network", "replica_error", value.ok ? "found" : "error", started, { code: errorCode(error) });
-      return value;
+      return fallback(prefix, deliveryReason(errorCode(error)), { code: errorCode(error) });
     }
   }
   async function list(r) {
@@ -995,17 +1379,46 @@ function createKVReplication(deps) {
       readEvent("list", r.listPath, null, "none", "cursor_restart", "error", started);
       return cursorRestart();
     }
-    if (cursor && !cursor.startsWith("tcr1.")) {
-      const result = await r.network();
-      readEvent("list", r.listPath, null, "network", "network_cursor", result.ok ? "found" : "error", started);
-      return result;
+    if (cursor && !cursor.startsWith("tcr1.")) return networkRead(r.network, "list", r.listPath, null, "network_cursor", started);
+    const prefix = listPathCovered(options.prefixes, r.listPath);
+    let networkRejected = false;
+    const fallback = async (replica, reason, extra = {}) => {
+      try {
+        return await networkRead(r.network, "list", r.listPath, replica, reason, started, extra);
+      } catch (error) {
+        networkRejected = true;
+        throw error;
+      }
+    };
+    if (prefix !== void 0 && !r.options?.raw) {
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") {
+        if (decoded) {
+          readEvent("list", r.listPath, prefix, "none", "cursor_restart", "error", started);
+          return cursorRestart();
+        }
+        return fallback(
+          prefix,
+          delivery.status === "consent_expired" ? "grant_expired" : "replica_gated",
+          { code: delivery.status === "consent_expired" ? delivery.code : "REPLICA_GATED" }
+        );
+      }
+    }
+    if (prefix !== void 0 && !r.options?.raw) {
+      const refusal = sessionRefusal(prefix);
+      if (refusal) {
+        if (decoded) {
+          readEvent("list", r.listPath, prefix, "none", "cursor_restart", "error", started);
+          return cursorRestart();
+        }
+        return fallback(prefix, "grant_missing", { code: refusal });
+      }
     }
     try {
       await raceSignal(reportExistingPins(), r.signal);
     } catch {
       if (r.signal.aborted) return abortedResult(r.signal);
     }
-    const prefix = listPathCovered(options.prefixes, r.listPath);
     const restart = () => {
       readEvent("list", r.listPath, prefix ?? null, "none", "cursor_restart", "error", started);
       return cursorRestart();
@@ -1013,36 +1426,33 @@ function createKVReplication(deps) {
     if (cursor && decoded && (decoded.space !== r.space || decoded.path !== r.listPath)) return restart();
     if (prefix === void 0 || r.options?.raw) {
       if (cursor && decoded) return restart();
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix ?? null, "network", prefix !== void 0 ? "unsupported_option" : "not_covered", result.ok ? "found" : "error", started);
-      return result;
+      return networkRead(r.network, "list", r.listPath, prefix ?? null, prefix !== void 0 ? "unsupported_option" : "not_covered", started);
     }
     let handle;
     try {
       handle = await raceSignal(open(prefix), r.signal);
     } catch (error) {
       if (r.signal.aborted) return abortedResult(r.signal);
+      if (errorCode(error) === "CONSENT_EXPIRED") startConsentDenial();
       if (cursor && decoded) return restart();
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", errorCode(error) === "RUNTIME_UNSUPPORTED" ? "runtime_unsupported" : "replica_unavailable", result.ok ? "found" : "error", started, { code: errorCode(error) });
-      return result;
+      const code = errorCode(error);
+      return fallback(prefix, code === "RUNTIME_UNSUPPORTED" ? "runtime_unsupported" : code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_unavailable", { code });
     }
     if (replicas.get(prefix)?.reason === "grant_missing") {
       if (cursor && decoded) return restart();
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "grant_missing", result.ok ? "found" : "error", started);
-      return result;
+      const code = replicas.get(prefix)?.lastError;
+      return fallback(prefix, code === "GRANT_EXPIRED" ? "grant_expired" : code === "REPLICA_GATED" ? "replica_gated" : "grant_missing", { code });
     }
     let fresh;
     try {
       fresh = await freshness(prefix, handle, r.signal);
     } catch (error) {
       recordRevocation(prefix, error);
+      if (errorCode(error) === "CONSENT_EXPIRED") startConsentDenial();
       if (r.signal.aborted) return abortedResult(r.signal);
       if (cursor && decoded) return restart();
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "replica_error", result.ok ? "found" : "error", started, { code: errorCode(error) });
-      return result;
+      const code = errorCode(error);
+      return fallback(prefix, code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_error", { code });
     }
     if (r.signal.aborted) return abortedResult(r.signal);
     let state;
@@ -1051,41 +1461,35 @@ function createKVReplication(deps) {
     } catch (error) {
       if (r.signal.aborted) return abortedResult(r.signal);
       if (cursor && decoded) return restart();
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "replica_unavailable", result.ok ? "found" : "error", started, { code: errorCode(error) });
-      return result;
+      const code = errorCode(error);
+      return fallback(prefix, code === "REPLICA_GATED" || code === "CONSENT_EXPIRED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "replica_unavailable", { code });
     }
-    const pendingRange = state.records.find((record) => listRangeCovers(r.listPath, record.key) && (!decoded || utf8Compare(record.key, decoded.last) > 0));
+    const pendingRange = state.records.find((record) => listRangeCovers(r.listPath, record.key));
     const behind = fresh.status.syncedThroughEpoch < state.committedEpoch;
     if (cursor && decoded && (fresh.failure || pendingRange || behind || fresh.status.coverage !== "complete" || fresh.status.authority.state !== "valid" || !pending.durable && !inProcessProof.has(prefix))) return restart();
-    if (behind) {
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "REPLICA_BEHIND_OWN_WRITES", result.ok ? "found" : "error", started);
-      return result;
-    }
+    if (behind) return fallback(prefix, "REPLICA_BEHIND_OWN_WRITES");
     if (fresh.failure) {
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "stale", result.ok ? "found" : "error", started, { code: fresh.failure === "busy" ? "REPLICA_BUSY" : fresh.syncError });
-      return result;
-    }
-    if (pendingRange) {
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "pending_write", result.ok ? "found" : "error", started, { pendingState: pendingRange.state });
-      return result;
-    }
-    if (!pending.durable && !inProcessProof.has(prefix)) {
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", "REPLICA_UNPROVEN_SINCE_START", result.ok ? "found" : "error", started);
-      return result;
-    }
-    if (fresh.status.coverage !== "complete" || fresh.status.authority.state !== "valid") {
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", fresh.status.coverage !== "complete" ? "coverage_incomplete" : fresh.status.authority.state === "expired" ? "grant_expired" : fresh.status.authority.state === "revoked" ? "grant_revoked" : "grant_not_yet_valid", result.ok ? "found" : "error", started);
-      return result;
+      const code = fresh.failure === "busy" ? "REPLICA_BUSY" : fresh.syncError;
+      return fallback(prefix, code === "GRANT_REVOKED" ? "grant_revoked" : code === "REPLICA_GATED" || code === "CONSENT_EXPIRED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : "stale", { code });
     }
+    if (pendingRange) return fallback(prefix, "pending_write", { pendingState: pendingRange.state });
+    if (!pending.durable && !inProcessProof.has(prefix)) return fallback(prefix, "REPLICA_UNPROVEN_SINCE_START");
+    if (fresh.status.coverage !== "complete" || fresh.status.authority.state !== "valid") return fallback(prefix, fresh.status.coverage !== "complete" ? "coverage_incomplete" : fresh.status.authority.state === "expired" ? "grant_expired" : fresh.status.authority.state === "revoked" ? "grant_revoked" : "grant_not_yet_valid");
     try {
       const signalHandle = { list: (o) => raceSignal(handle.list(o), r.signal) };
       const page = await raceSignal(localList(signalHandle, r.space, r.listPath, r.options?.limit, cursor, validateReadMeta), r.signal);
+      const latest = await raceSignal(pending.read(), r.signal);
+      const laterPending = latest.records.find((record) => listRangeCovers(r.listPath, record.key));
+      if (cursor && decoded && (laterPending || fresh.status.syncedThroughEpoch < latest.committedEpoch)) return restart();
+      if (fresh.status.syncedThroughEpoch < latest.committedEpoch) return await fallback(prefix, "REPLICA_BEHIND_OWN_WRITES");
+      if (laterPending) return await fallback(prefix, "pending_write", { pendingState: laterPending.state });
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") throw deliveryError(delivery);
+      const refusal = sessionRefusal(prefix);
+      if (refusal) {
+        if (decoded) return restart();
+        return await fallback(prefix, "grant_missing", { code: refusal });
+      }
       const event = {
         count: page.keys.length,
         syncedBeforeRead: fresh.syncedBeforeRead,
@@ -1096,14 +1500,14 @@ function createKVReplication(deps) {
       readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, event);
       return ok(page);
     } catch (error) {
+      if (networkRejected) throw error;
       if (r.signal.aborted) return abortedResult(r.signal);
       const code = errorCode(error);
+      if (code === "CONSENT_EXPIRED") startConsentDenial();
       recordRevocation(prefix, error);
       if (cursor && decoded) return restart();
-      const reason = reasonForReadMetaCode(code);
-      const result = await r.network();
-      readEvent("list", r.listPath, prefix, "network", reason, result.ok ? "found" : "error", started, { code });
-      return result;
+      const reason = code === "CONSENT_EXPIRED" || code === "REPLICA_GATED" || code === "GRANT_EXPIRED" ? deliveryReason(code) : reasonForReadMetaCode(code);
+      return fallback(prefix, reason, { code });
     }
   }
   async function write(r) {
@@ -1112,11 +1516,14 @@ function createKVReplication(deps) {
       return prefix !== void 0 ? [{ key: entry.path, op: r.op === "delete" ? "delete" : "put" }] : [];
     });
     if (covered.length === 0) return r.network();
+    if (checkDelivery().status !== "allow") return r.network();
     await reportExistingPins();
+    if (checkDelivery().status !== "allow") return r.network();
     const opId = globalThis.crypto?.randomUUID?.() ?? `${scheduler.now()}-${Math.random()}`;
     try {
       await pending.update((s) => begin(s, opId, covered, nowDate(scheduler.now())));
     } catch (error) {
+      if (errorCode(error) === "REPLICA_GATED" || errorCode(error) === "CONSENT_EXPIRED" || checkDelivery().status !== "allow") return r.network();
       return err(serviceError(ErrorCodes.KV_WRITE_FAILED, "Unable to persist pending KV write; request was not dispatched", "kv", { cause: error instanceof Error ? error : void 0, meta: { replication: "pending_store_unavailable", requestDispatched: false } }));
     }
     const started = scheduler.now();
@@ -1181,8 +1588,32 @@ function createKVReplication(deps) {
     for (const inspection of active) inspection.abort.abort(Object.assign(new Error("Replica status inspection cancelled"), { code: "ABORTED" }));
     return Promise.all(active.map((inspection) => inspection.settled)).then(() => void 0);
   }
+  function gatedStatus(decision) {
+    return options.prefixes.map((prefix) => ({
+      prefix,
+      state: "gated",
+      reason: "replica_gated",
+      gate: decision.status === "gated" ? decision.gate : "stamp_stale",
+      errorCode: decision.status === "consent_expired" ? decision.code : "REPLICA_GATED",
+      pending: { inFlight: 0, committed: 0, ambiguous: 0 },
+      pinned: [],
+      lagMs: null,
+      redacted: true
+    }));
+  }
   async function status() {
-    const persistedSnapshot = pending.readExisting ? await pending.readExisting() : await pending.read();
+    const beforeStatus = checkDelivery();
+    if (beforeStatus.status !== "allow") return gatedStatus(beforeStatus);
+    let persistedSnapshot;
+    try {
+      persistedSnapshot = pending.readExisting ? await pending.readExisting() : await pending.read();
+    } catch (error) {
+      const delivery = checkDelivery();
+      if (delivery.status !== "allow") return gatedStatus(delivery);
+      throw error;
+    }
+    const afterPending = checkDelivery();
+    if (afterPending.status !== "allow") return gatedStatus(afterPending);
     const snapshot = persistedSnapshot ?? emptyPendingState(identity);
     const entries = await Promise.all(options.prefixes.map(async (prefix) => {
       if (prefix === "/" && deps.nodeFeatures !== void 0 && !deps.nodeFeatures.includes("kv-sync-root")) {
@@ -1204,7 +1635,7 @@ function createKVReplication(deps) {
       const full = local && !("redacted" in local) ? local : void 0;
       const revoked = opened?.authorityRevoked === true || full?.authority.state === "revoked";
       const rootUnsupported = opened?.lastError === "REPLICATION_ROOT_UNSUPPORTED";
-      const state = isClosed ? "closed" : revoked ? "revoked" : rootUnsupported ? "unavailable" : opened?.reason === "grant_missing" ? "grant_missing" : full?.coverage === "complete" && full.authority.state === "valid" ? "ready" : opened?.reason || inspected.errorCode ? "unavailable" : "idle";
+      const state = isClosed ? "closed" : revoked ? "revoked" : rootUnsupported || opened?.reason === "grant_expired" ? "unavailable" : opened?.reason === "grant_missing" ? "grant_missing" : full?.coverage === "complete" && full.authority.state === "valid" ? "ready" : opened?.reason || inspected.errorCode ? "unavailable" : "idle";
       return {
         prefix,
         state,
@@ -1221,6 +1652,8 @@ function createKVReplication(deps) {
         lagMs: full?.lastSyncAt ? scheduler.now() - Date.parse(full.lastSyncAt) : null
       };
     }));
+    const beforeReturn = checkDelivery();
+    if (beforeReturn.status !== "allow") return gatedStatus(beforeReturn);
     return entries.filter((entry) => entry !== void 0);
   }
   async function sync(o) {
@@ -1236,11 +1669,15 @@ function createKVReplication(deps) {
     var _a;
     purgeStarted = true;
     purgeInProgress = true;
+    cancelConsentTimer?.();
+    cancelConsentTimer = void 0;
     const hasStatusInspections = statusInspections.size > 0;
     const statusDrain = cancelStatusInspections();
     for (const state of replicas.values()) {
       state.timer?.();
       state.timer = void 0;
+      state.renewalTimer?.();
+      state.renewalTimer = void 0;
       state.syncContext && ((_a = state.syncContext).abortCause ?? (_a.abortCause = "purge"));
       state.abort?.abort();
       state.mintAbort?.abort();
@@ -1264,6 +1701,7 @@ function createKVReplication(deps) {
         ...[...replicas.values()].flatMap((state) => [
           state.opening?.catch(() => void 0),
           state.sync?.catch(() => void 0),
+          state.renewing?.catch(() => void 0),
           state.handle?.close().catch(() => void 0)
         ]),
         ...hasStatusInspections ? [statusDrain] : []
@@ -1301,11 +1739,15 @@ function createKVReplication(deps) {
     var _a;
     if (isClosed) return;
     isClosed = true;
+    cancelConsentTimer?.();
+    cancelConsentTimer = void 0;
     const hasStatusInspections = statusInspections.size > 0;
     const statusDrain = cancelStatusInspections();
     for (const [prefix, state] of replicas) {
       state.timer?.();
       state.timer = void 0;
+      state.renewalTimer?.();
+      state.renewalTimer = void 0;
       state.mintAbort?.abort();
       state.syncContext && ((_a = state.syncContext).abortCause ?? (_a.abortCause = "close"));
       state.abort?.abort();
@@ -1314,6 +1756,7 @@ function createKVReplication(deps) {
     const drain = Promise.all([
       ...[...replicas.values()].map(async (state) => {
         await state.opening?.catch(() => void 0);
+        await state.renewing?.catch(() => void 0);
         await state.sync?.catch(() => void 0);
         await state.handle?.close().catch(() => void 0);
       }),
@@ -1343,7 +1786,8 @@ function createKVReplication(deps) {
       cancel();
     }
   }
-  return { get, list, write, observeNetworkRequested, status, sync, purge, clearPending: clearPending2, close };
+  scheduleConsentDeadline();
+  return { get, list, write, observeNetworkRequested, observeConsentExpired, status, sync, purge, clearPending: clearPending2, close };
 }
 function cancellationCode(signal) {
   return wrapError("kv", signal.reason).code === ErrorCodes.TIMEOUT || typeof signal.reason === "object" && signal.reason !== null && "code" in signal.reason && signal.reason.code === ErrorCodes.TIMEOUT ? ErrorCodes.TIMEOUT : ErrorCodes.ABORTED;