@tinycloud/replica 0.2.4-beta.2 → 0.3.0-beta.4

package/dist/replica.worker.js

@@ -6806,6 +6806,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`: 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",
@@ -7620,6 +7628,40 @@ var ServiceContext = class {
     return combined.signal;
   }
 };
+function parseServiceErrorBody(errorText) {
+  try {
+    return JSON.parse(errorText);
+  } catch {
+    return {};
+  }
+}
+function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
+  if (parsed.message) {
+    return compactMessage(parsed.message);
+  }
+  if (looksLikeHtml(errorText)) {
+    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
+      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
+    }
+    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
+  }
+  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
+}
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+function looksLikeHtml(text) {
+  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
 var URN_PREFIX = "urn:tinycloud:encryption:";
 var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
@@ -7732,6 +7774,30 @@ function authRequiredError(service) {
     service
   };
 }
+function nodeRetryError(service, message, response, errorText) {
+  const body = errorText.trim();
+  const [, token, stage] = /^([a-z_]+)(?::\s*([a-z_]+):)?/.exec(body) ?? [];
+  let code;
+  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable")) {
+    code = ErrorCodes.NODE_BUSY;
+  } else if (response.status === 503 && token === "request_timeout") {
+    code = ErrorCodes.REQUEST_TIMEOUT;
+  } else if (response.status === 500 && token === "outcome_unknown") {
+    code = ErrorCodes.OUTCOME_UNKNOWN;
+  } else {
+    return void 0;
+  }
+  const retryable = code !== ErrorCodes.OUTCOME_UNKNOWN;
+  const retryAfter = response.headers.get("retry-after")?.trim();
+  return serviceError(code, message, service, {
+    meta: {
+      ...responseErrorMeta(response.status, response.statusText, errorText),
+      retryable,
+      ...token === "sql_busy" && stage ? { stage } : {},
+      ...retryable && retryAfter && /^\d{1,9}$/.test(retryAfter) ? { retryAfterMs: Number(retryAfter) * 1e3 } : {}
+    }
+  });
+}
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Request timed out after ${timeoutMs}ms.`);
@@ -9035,9 +9101,12 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
+      const message = `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -9119,19 +9188,14 @@ var KVService = class extends BaseService {
           { 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 message = `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       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}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -9431,9 +9495,12 @@ var KVService = class extends BaseService {
         );
       }
       const errorText = await response.text();
+      const message = `Failed to list keys: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to list keys: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -9684,17 +9751,12 @@ var KVService = class extends BaseService {
           { 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 } }
-        ));
-      }
+      const message = `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -9735,10 +9797,13 @@ var KVService = class extends BaseService {
             return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          const message = `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+          const retryError = nodeRetryError("kv", message, response, errorText);
+          if (retryError) return err(retryError);
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+              message,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -9867,40 +9932,6 @@ var KVService = class extends BaseService {
   }
 };
 KVService.serviceName = "kv";
-function parseServiceErrorBody(errorText) {
-  try {
-    return JSON.parse(errorText);
-  } catch {
-    return {};
-  }
-}
-function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
-  if (parsed.message) {
-    return compactMessage(parsed.message);
-  }
-  if (looksLikeHtml(errorText)) {
-    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
-      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
-    }
-    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
-  }
-  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
-}
-function responseErrorMeta(status, statusText, errorText) {
-  const meta = { status, statusText };
-  const snippet = compactMessage(errorText);
-  if (snippet) {
-    meta.responseSnippet = snippet.slice(0, 300);
-  }
-  return meta;
-}
-function looksLikeHtml(text) {
-  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
-}
-function compactMessage(message) {
-  const compact = message.replace(/\s+/g, " ").trim();
-  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
-}
 var SQLMigrations = class {
   constructor(service, dbName) {
     this.service = service;
@@ -10308,6 +10339,8 @@ var SQLService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("sql", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("sql", `SQL ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -10770,6 +10803,8 @@ var DuckDbService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("duckdb", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("duckdb", `DuckDB ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -14647,7 +14682,13 @@ var ReplicaErrorCode = {
   /** A stored blob no longer hashes to its name. */
   INTEGRITY_ERROR: "INTEGRITY_ERROR",
   /** The replica handle was closed; in-flight calls settle with this code. */
-  CLOSED: "REPLICA_CLOSED"
+  CLOSED: "REPLICA_CLOSED",
+  /** The lifecycle gate refused the operation (shared contract `REPLICA_GATED`); `detail.gate` says why. */
+  GATED: "REPLICA_GATED",
+  /** Quota admission refused a page (`maxBytes` or the free-space floor); nothing committed. */
+  STORAGE_BUDGET: "STORAGE_BUDGET",
+  /** The consent deadline passed: the grant is not served until the user consents again. */
+  CONSENT_EXPIRED: "CONSENT_EXPIRED"
 };
 var REPLICA_ERROR = /* @__PURE__ */ Symbol.for("tinycloud.replica.error");
 var ReplicaError = class extends Error {
@@ -14900,6 +14941,11 @@ var Replica = class {
    * active grant serves: a revoked pending grant is discarded, any other
    * refusal is recorded on it. A revocation of the grant serving the replica,
    * learned anywhere in the sync, purges the replica before this returns.
+   *
+   * `signal` cancels between commits: an aborted sync commits nothing past
+   * its last complete page. `finish` runs once every feed page, repair batch
+   * and the GC have committed, still under the sync lease — a sync that fails
+   * or aborts earlier never reaches it.
    */
   async sync(options = {}) {
     const transportFor = this.#transportFor;
@@ -14923,7 +14969,12 @@ var Replica = class {
           signal: options.signal
         };
         try {
-          return await this.#syncUnder(attempt, options.limit ?? DEFAULT_PAGE_LIMIT);
+          const report = await this.#syncUnder(attempt, options.limit ?? DEFAULT_PAGE_LIMIT);
+          if (options.finish !== void 0) {
+            options.signal?.throwIfAborted();
+            await options.finish(lease);
+          }
+          return report;
         } catch (error) {
           const canFallBack = pending && attempt.promote !== null && index < candidates.length - 1;
           if (canFallBack && isReplicaError(error, ReplicaErrorCode.GRANT_REVOKED)) {
@@ -15020,6 +15071,7 @@ var Replica = class {
       const verified = await this.#verify(page, attempt);
       coverage = page.more ? coverage === "complete" ? "complete" : "bootstrapping" : "complete";
       const at = new Date(this.#now()).toISOString();
+      attempt.signal?.throwIfAborted();
       await this.#store.applyPage(attempt.lease, {
         changes: verified.changes,
         blobs: verified.blobs,
@@ -15150,6 +15202,7 @@ var Replica = class {
       await this.#store.renewLease(attempt.lease, this.#leaseTtlMs);
       if (changes.length === 0) continue;
       const state = await this.#state();
+      attempt.signal?.throwIfAborted();
       await this.#store.applyPage(attempt.lease, {
         changes,
         blobs,
@@ -17052,9 +17105,9 @@ function requestAsPromise(request) {
 }
 function transactionDone(tx) {
   const { promise, resolve, reject } = Promise.withResolvers();
-  tx.oncomplete = () => resolve();
-  tx.onabort = () => reject(tx.error ?? new DOMException("Transaction aborted", "AbortError"));
-  tx.onerror = () => reject(tx.error ?? new DOMException("Transaction failed", "UnknownError"));
+  tx.addEventListener("complete", () => resolve(), { once: true });
+  tx.addEventListener("abort", () => reject(tx.error ?? new DOMException("Transaction aborted", "AbortError")), { once: true });
+  tx.addEventListener("error", () => reject(tx.error ?? new DOMException("Transaction failed", "UnknownError")), { once: true });
   return promise;
 }
 function openDatabase(name, upgrade) {
@@ -17106,6 +17159,32 @@ function idbError(error, action) {
   return new ReplicaError(ReplicaErrorCode.STORAGE_ERROR, `${action}: ${message}`, void 0, { cause: error });
 }
 
+// ../sdk-services/dist/kv/replication/grantPolicy.js
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+var MAX_GRANT_TTL_MS = 7 * DAY_MS;
+var CONSENT_WINDOW_MS = 7 * DAY_MS;
+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 effectiveGrantExpiry = ({
+  signedExpiresAt,
+  installedAt,
+  grantTtlMs,
+  consentDeadline
+}) => {
+  const signedValid = signedExpiresAt === null || Number.isFinite(signedExpiresAt);
+  if (!signedValid || !Number.isFinite(installedAt) || !Number.isFinite(grantTtlMs) || !Number.isFinite(consentDeadline)) {
+    return EXPIRED;
+  }
+  const ttl = Math.min(grantTtlMs, MAX_GRANT_TTL_MS);
+  const localBound = Math.min(installedAt + ttl, consentDeadline);
+  return signedExpiresAt === null ? localBound : Math.min(signedExpiresAt, localBound);
+};
+
 // src/browser/store.ts
 var DURABILITY = "indexeddb-strict";
 var STORE_META = "meta";
@@ -17113,6 +17192,21 @@ var STORE_ENTRIES = "entries";
 var STORE_BLOBS = "blobs";
 var ALL_STORES = [STORE_META, STORE_ENTRIES, STORE_BLOBS];
 var DEVICE_DATABASE = "tinycloud-replica-device";
+function rc1Layout(replicaId) {
+  return {
+    partitionId: replicaId,
+    readScope: [],
+    writeScope: [],
+    metaKey: "state",
+    outOfLineKeys: false,
+    entryKey: (key) => key,
+    blobKey: (hash) => hash,
+    blobHashOf: (key) => typeof key === "string" ? key : void 0,
+    range: null,
+    tag: {},
+    blobSizeIndex: null
+  };
+}
 function replicaDatabaseName(replicaId) {
   return `tinycloud-replica/${replicaId}`;
 }
@@ -17122,6 +17216,39 @@ function createStores(db) {
   entries.createIndex("byHash", "hash", { unique: false });
   db.createObjectStore(STORE_BLOBS, { keyPath: "hash" });
 }
+function clearReplicaRows(tx, layout) {
+  for (const name of [STORE_ENTRIES, STORE_BLOBS]) {
+    const store = tx.objectStore(name);
+    if (layout.range === null) store.clear();
+    else store.delete(layout.range);
+  }
+}
+async function blobSizes(tx, layout) {
+  const sizes = /* @__PURE__ */ new Map();
+  if (layout.blobSizeIndex === null) return sizes;
+  const { promise, resolve, reject } = Promise.withResolvers();
+  const request = tx.objectStore(STORE_BLOBS).index(layout.blobSizeIndex).openKeyCursor(layout.range);
+  request.onsuccess = () => {
+    const cursor = request.result;
+    if (cursor === null) {
+      resolve();
+      return;
+    }
+    const hash = layout.blobHashOf(cursor.primaryKey);
+    const key = cursor.key;
+    const size = Array.isArray(key) ? key[key.length - 1] : void 0;
+    if (hash !== void 0 && typeof size === "number") sizes.set(hash, size);
+    cursor.continue();
+  };
+  request.onerror = () => reject(request.error);
+  await promise;
+  return sizes;
+}
+function sumSizes(sizes) {
+  let total = 0;
+  for (const size of sizes.values()) total += size;
+  return total;
+}
 async function deviceIdentity(getKey) {
   let db;
   try {
@@ -17165,7 +17292,10 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
   #db;
   #holder;
   #now;
-  #replicaId;
+  #layout;
+  #hooks;
+  /** False when the connection is shared (the origin database): close() leaves it open. */
+  #ownsDb;
   #closed = false;
   /**
    * The generation this connection opened under, read from `meta` at open.
@@ -17174,11 +17304,13 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
    * with RESET_REQUIRED, checked durably inside the transaction itself.
    */
   #generation = 0;
-  constructor(db, holder, now, replicaId) {
+  constructor(db, options) {
     this.#db = db;
-    this.#holder = holder;
-    this.#now = now;
-    this.#replicaId = replicaId;
+    this.#holder = options.holder;
+    this.#now = options.now;
+    this.#layout = options.layout;
+    this.#hooks = options.hooks;
+    this.#ownsDb = options.ownsDb;
   }
   static async open(replicaId, options) {
     let db;
@@ -17188,16 +17320,43 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
       if (isReplicaError(error)) throw error;
       throw idbError(error, "Opening the replica");
     }
-    const store = new _IndexedDbReplicaStore(db, options.holder, options.now ?? Date.now, replicaId);
+    const store = new _IndexedDbReplicaStore(db, {
+      holder: options.holder,
+      now: options.now ?? Date.now,
+      layout: rc1Layout(replicaId),
+      hooks: {},
+      ownsDb: true
+    });
+    await store.#start({ finishPurge: true });
+    return store;
+  }
+  /**
+   * One replica inside an already-open shared database (the origin
+   * database of `@tinycloud/replica/kv-storage`). `ownsDb` hands the
+   * connection to the store, which then closes it on `close()`. With
+   * `inspect` the store never writes: a torn revocation purge is left for
+   * the next writable open.
+   */
+  static async openIn(db, options) {
+    const store = new _IndexedDbReplicaStore(db, {
+      holder: options.holder,
+      now: options.now ?? Date.now,
+      layout: options.layout,
+      hooks: options.hooks ?? {},
+      ownsDb: options.ownsDb === true
+    });
+    await store.#start({ finishPurge: options.inspect !== true });
+    return store;
+  }
+  async #start(options) {
     try {
-      const state = await store.#rawMeta();
-      store.#generation = state?.generation ?? 0;
-      await store.finishPurgeIfPending();
+      const state = await this.#transact("readonly", [], "Opening the replica", async (_tx, row) => row, { skipFence: true });
+      this.#generation = state?.generation ?? 0;
+      if (options.finishPurge) await this.finishPurgeIfPending();
     } catch (error) {
-      db.close();
-      throw idbError(error, "Opening the replica");
+      if (this.#ownsDb) this.#db.close();
+      throw error;
     }
-    return store;
   }
   /**
    * The fence: the durable `meta` row must match the generation this store
@@ -17212,64 +17371,119 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     }
   }
   /**
-   * A read transaction. `meta` is always in scope and its row is checked
-   * against this store's generation inside the transaction before `body`
-   * (which receives the already-read meta row) runs.
+   * Reads the durable CID timestamp and identity anchor inside the caller's
+   * guarded transaction. Never uses the current time as a substitute for a
+   * missing/corrupt install timestamp: reopening cannot renew a grant.
    */
-  async #readTx(stores, body) {
-    if (this.#closed) throw new ReplicaError(ReplicaErrorCode.STORAGE_ERROR, "The replica store is closed.");
-    const all = stores.includes(STORE_META) ? [...stores] : [STORE_META, ...stores];
-    let tx;
-    try {
-      tx = this.#db.transaction(all, "readonly");
-    } catch (error) {
-      throw idbError(error, "Reading the replica");
+  async #policyView(tx, state) {
+    const binding = this.#hooks.grantPolicy;
+    if (binding === void 0) return void 0;
+    const device = tx.objectStore("device");
+    const stored = await requestAsPromise(device.get(binding.firstInstallKey));
+    const now = this.#now();
+    const anchor = clampConsentAnchor(binding.policy.consentAnchor, now) ?? (stored === void 0 ? null : clampConsentAnchor({ at: stored.at, source: "first_install" }, now));
+    const consentDeadline = anchor === null ? Number.NEGATIVE_INFINITY : consentDeadlineMs(anchor);
+    const grants = {};
+    for (const record of [state.grant, state.pendingGrant]) {
+      if (record === null || grants[record.cid] !== void 0) continue;
+      const installed = await requestAsPromise(device.get(binding.installedAtKey(record.cid)));
+      const installedAt = installed?.at;
+      grants[record.cid] = {
+        installedAt,
+        effectiveExpiresAt: effectiveGrantExpiry({
+          signedExpiresAt: record.expiresAt === null ? null : record.expiresAt * 1e3,
+          installedAt: installedAt ?? Number.NEGATIVE_INFINITY,
+          grantTtlMs: binding.policy.grantTtlMs,
+          consentDeadline
+        })
+      };
+    }
+    return { anchor, consentDeadline, grants };
+  }
+  #cappedGrant(record, view) {
+    if (record === null || view === void 0) return record;
+    const expiry = view.grants[record.cid]?.effectiveExpiresAt;
+    return { ...record, expiresAt: expiry !== void 0 && Number.isFinite(expiry) ? expiry / 1e3 : 0 };
+  }
+  async #assertServing(tx, state) {
+    const view = await this.#policyView(tx, state);
+    if (view === void 0) return;
+    const now = this.#now();
+    if (!Number.isFinite(view.consentDeadline) || !Number.isFinite(now) || now >= view.consentDeadline) {
+      throw new ReplicaError(ReplicaErrorCode.CONSENT_EXPIRED, "The replica consent window ended; local reads are blocked.");
     }
-    const state = await this.#meta(tx);
-    this.#assertLive(state);
-    return body(tx, state);
+    const grant = this.#cappedGrant(state.grant, view);
+    if (grant !== null && (!Number.isFinite(view.grants[grant.cid]?.effectiveExpiresAt) || now >= view.grants[grant.cid].effectiveExpiresAt)) {
+      throw new ReplicaError(ReplicaErrorCode.GRANT_EXPIRED, "The effective grant expired; local reads are blocked.");
+    }
+    assertReadable(effectiveAuthority({
+      window: state.authority,
+      grant,
+      revoked: state.revoked,
+      retentionRevoked: state.retentionRevoked,
+      policy: "whileGrantValid",
+      now
+    }), now);
   }
   /**
-   * A write transaction with `strict` durability — `meta` first, the
-   * generation fence inside the transaction, then `body` (which receives
-   * the already-read meta row). `body` may only await IDB requests issued
-   * on `tx`; the returned promise settles after the writes, and
-   * `transactionDone` settles after the commit. `skipFence` is for `init`:
-   * it checks the marker and generation itself because a purge marker
-   * belonging to this store's generation is the reinitialize-in-place case.
+   * One transaction over `stores` plus `meta`. With a gate (`hooks.run`) the
+   * gate opens it — adding its control stores and asserting the handle's
+   * access before anything else; otherwise this store opens it over the
+   * layout's scope. Inside, the state row is read and, unless `skipFence`,
+   * fenced against this store's generation before `body` runs. `body` may
+   * only await IDB requests issued on `tx`. Write transactions use `strict`
+   * durability and settle after the commit; any failure aborts them.
+   * `skipFence` is for `init` and the open-time reads, which handle the
+   * tombstone and generation themselves.
    */
-  async #writeTx(stores, action, body, options = {}) {
+  async #transact(mode, stores, action, body, options = {}) {
     if (this.#closed) throw new ReplicaError(ReplicaErrorCode.STORAGE_ERROR, "The replica store is closed.");
-    const all = stores.includes(STORE_META) ? [...stores] : [STORE_META, ...stores];
-    let tx;
-    try {
-      tx = this.#db.transaction(all, "readwrite", { durability: "strict" });
-    } catch (error) {
-      throw idbError(error, action);
+    const mapped = (error) => typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error : idbError(error, action);
+    const data = [.../* @__PURE__ */ new Set([STORE_META, ...stores])];
+    const execute = async (tx2) => {
+      const done = mode === "readwrite" ? transactionDone(tx2) : void 0;
+      try {
+        const state = await requestAsPromise(tx2.objectStore(STORE_META).get(this.#layout.metaKey));
+        if (options.skipFence !== true) this.#assertLive(state);
+        if (options.serving === true) await this.#assertServing(tx2, this.#requireMeta(state));
+        const result = await body(tx2, state);
+        await done;
+        return result;
+      } catch (error) {
+        if (done !== void 0) {
+          try {
+            tx2.abort();
+          } catch {
+          }
+          await done.catch(() => void 0);
+        }
+        throw mapped(error);
+      }
+    };
+    const run = this.#hooks.run;
+    if (run !== void 0) {
+      try {
+        return await run(data, mode, execute);
+      } catch (error) {
+        throw mapped(error);
+      }
     }
-    const done = transactionDone(tx);
+    let tx;
     try {
-      const state = await this.#meta(tx);
-      if (options.skipFence !== true) this.#assertLive(state);
-      const result = await body(tx, state);
-      await done;
-      return result;
+      const scope = [.../* @__PURE__ */ new Set([...data, ...mode === "readonly" ? this.#layout.readScope : this.#layout.writeScope])];
+      tx = mode === "readonly" ? this.#db.transaction(scope, mode) : this.#db.transaction(scope, mode, { durability: "strict" });
     } catch (error) {
-      try {
-        tx.abort();
-      } catch {
-      }
-      await done.catch(() => void 0);
       throw idbError(error, action);
     }
+    return execute(tx);
   }
-  /** The raw `meta` row — used at open time, before the generation is set. */
-  async #rawMeta() {
-    const tx = this.#db.transaction(STORE_META, "readonly");
-    return requestAsPromise(tx.objectStore(STORE_META).get("state"));
+  /** A fenced read transaction; serving reads assert grant policy before entries or bytes. */
+  #readTx(stores, body, options = {}) {
+    return this.#transact("readonly", options.serving && this.#hooks.grantPolicy ? [...stores, "device"] : stores, "Reading the replica", body, options);
   }
-  async #meta(tx) {
-    return requestAsPromise(tx.objectStore(STORE_META).get("state"));
+  /** A fenced write transaction (`skipFence` for `init`); `body` receives the already-read state row. */
+  #writeTx(stores, action, body, options = {}) {
+    return this.#transact("readwrite", stores, action, body, options);
   }
   #requireMeta(state) {
     if (state === void 0) throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, "The replica has not been created.");
@@ -17279,17 +17493,13 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     return state;
   }
   #putMeta(tx, state) {
-    return tx.objectStore(STORE_META).put(state, "state");
+    return tx.objectStore(STORE_META).put(state, this.#layout.metaKey);
   }
   async open() {
-    if (this.#closed) throw new ReplicaError(ReplicaErrorCode.STORAGE_ERROR, "The replica store is closed.");
-    let tx;
-    try {
-      tx = this.#db.transaction([STORE_META], "readonly");
-    } catch (error) {
-      throw idbError(error, "Reading the replica");
-    }
-    const state = await this.#meta(tx);
+    const { state, view } = await this.#transact("readonly", this.#hooks.grantPolicy ? ["device"] : [], "Reading the replica", async (tx, row) => ({
+      state: row,
+      view: row !== void 0 && row.purged === false ? await this.#policyView(tx, row) : void 0
+    }), { skipFence: true });
     if (state !== void 0 && state.generation !== this.#generation) {
       throw new ReplicaError(ReplicaErrorCode.RESET_REQUIRED, "The replica was purged or reopened; open it again to continue.");
     }
@@ -17297,8 +17507,9 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     assertFolderPrefix2(state.config.prefix);
     return {
       config: state.config,
-      grant: state.grant,
-      pendingGrant: state.pendingGrant,
+      grant: this.#cappedGrant(state.grant, view),
+      pendingGrant: this.#cappedGrant(state.pendingGrant, view),
+      ...view === void 0 ? {} : { grantPolicyView: view },
       nodeDid: state.nodeDid,
       authority: state.authority,
       revoked: state.revoked,
@@ -17329,6 +17540,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
               );
             }
             const next = existing.generation + 1;
+            await this.#hooks.indexPartition?.(tx);
             this.#putMeta(tx, this.#freshMeta(c, next));
             return next;
           }
@@ -17343,6 +17555,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
           if (same) return existing.generation;
           throw new ReplicaError(ReplicaErrorCode.CONFIG_MISMATCH, `Replica ${c.name} already exists.`);
         }
+        await this.#hooks.indexPartition?.(tx);
         this.#putMeta(tx, this.#freshMeta(c, 0));
         return 0;
       },
@@ -17394,8 +17607,23 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     });
   }
   async installGrant(g) {
-    await this.#writeTx([STORE_META], "Installing the grant", async (tx, meta) => {
+    await this.#writeTx(this.#hooks.grantPolicy ? [STORE_META, "device"] : [STORE_META], "Installing the grant", async (tx, meta) => {
       const state = this.#requireMeta(meta);
+      const binding = this.#hooks.grantPolicy;
+      if (binding !== void 0) {
+        const device = tx.objectStore("device");
+        const timestampKey = binding.installedAtKey(g.cid);
+        const existing = await requestAsPromise(device.get(timestampKey));
+        const now = this.#now();
+        if (existing === void 0) {
+          if (state.grant?.cid === g.cid || state.pendingGrant?.cid === g.cid) {
+            throw new ReplicaError(ReplicaErrorCode.GRANT_EXPIRED, "The original install time for this grant is missing.");
+          }
+          device.put({ at: now }, timestampKey);
+        }
+        const anchor = await requestAsPromise(device.get(binding.firstInstallKey));
+        if (anchor === void 0) device.put({ at: now }, binding.firstInstallKey);
+      }
       if (state.grant?.cid === g.cid || state.pendingGrant?.cid === g.cid) return;
       state.pendingGrant = g;
       state.pendingGrantError = null;
@@ -17481,7 +17709,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
   async #hashesWithEntries(tx, wanted) {
     const found = /* @__PURE__ */ new Set();
     const { promise, resolve, reject } = Promise.withResolvers();
-    const request = tx.objectStore(STORE_ENTRIES).index("byHash").openCursor();
+    const request = tx.objectStore(STORE_ENTRIES).index("byHash").openCursor(this.#layout.range);
     request.onsuccess = () => {
       const cursor = request.result;
       if (cursor === null) {
@@ -17501,6 +17729,9 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     return this.#readTx([STORE_ENTRIES], (tx) => this.#hashesWithEntries(tx, wanted));
   }
   async applyPage(t, p) {
+    const layout = this.#layout;
+    const freeBytes = await this.#hooks.freeBytes?.() ?? null;
+    const signedPromotion = this.#hooks.grantPolicy && p.promoteGrant !== null ? parseUcanGrant(p.promoteGrant.bytes) : p.promoteGrant;
     await this.#writeTx(ALL_STORES, "Committing a sync page", async (tx, meta) => {
       const state = this.#requireMeta(meta);
       this.#checkFence(state, t);
@@ -17529,12 +17760,12 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
           sizes.set(change.hash, bytes.length);
           continue;
         }
-        const previous = await requestAsPromise(entries.get(change.key));
+        const previous = await requestAsPromise(entries.get(layout.entryKey(change.key)));
         if (previous !== void 0 && !previous.deleted && previous.content && previous.hash === change.hash && previous.size !== null) {
           sizes.set(change.hash, previous.size);
           continue;
         }
-        const held = await requestAsPromise(blobs.get(change.hash));
+        const held = await requestAsPromise(blobs.get(layout.blobKey(change.hash)));
         if (held !== void 0) sizes.set(change.hash, held.size);
       }
       for (const change of p.changes) {
@@ -17543,15 +17774,21 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
           throw new ReplicaError(ReplicaErrorCode.STORAGE_ERROR, `No stored content backs ${JSON.stringify(change.key)}.`);
         }
       }
+      let blobBytes = 0;
+      if (this.#hooks.admitPage !== void 0 || this.#hooks.accountCommit !== void 0) {
+        for (const [hash, bytes] of p.blobs) {
+          if (await requestAsPromise(blobs.count(layout.blobKey(hash))) === 0) blobBytes += bytes.length;
+        }
+      }
+      await this.#hooks.admitPage?.(tx, { partitionId: layout.partitionId, blobBytes, entries: p.changes.length, freeBytes });
       for (const [hash, bytes] of p.blobs) {
-        blobs.put({ hash, bytes, size: bytes.length });
+        const record = { ...layout.tag, hash, bytes, size: bytes.length };
+        if (layout.outOfLineKeys) blobs.put(record, layout.blobKey(hash));
+        else blobs.put(record);
       }
       for (const change of p.changes) {
-        if (change.deleted) {
-          entries.put({ key: change.key, deleted: true });
-          continue;
-        }
-        entries.put({
+        const record = change.deleted ? { ...layout.tag, key: change.key, deleted: true } : {
+          ...layout.tag,
           key: change.key,
           deleted: false,
           etag: change.etag,
@@ -17559,8 +17796,11 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
           metadata: change.metadata,
           content: change.content,
           size: change.content ? sizes.get(change.hash) ?? null : null
-        });
+        };
+        if (layout.outOfLineKeys) entries.put(record, layout.entryKey(change.key));
+        else entries.put(record);
       }
+      await this.#hooks.accountCommit?.(tx, { partitionId: layout.partitionId, deltaBytes: blobBytes });
       state.cursor = p.cursor;
       state.coverage = p.coverage;
       state.serial += 1;
@@ -17575,9 +17815,9 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
         state.lastCompleteAt = p.at;
         state.lastError = null;
       }
-      if (p.promoteGrant !== null) {
-        state.grant = p.promoteGrant;
-        if (state.pendingGrant?.cid === p.promoteGrant.cid) {
+      if (signedPromotion !== null) {
+        state.grant = state.pendingGrant?.cid === signedPromotion.cid ? state.pendingGrant : state.grant?.cid === signedPromotion.cid ? state.grant : signedPromotion;
+        if (state.pendingGrant?.cid === signedPromotion.cid) {
           state.pendingGrant = null;
           state.pendingGrantError = null;
         }
@@ -17594,27 +17834,40 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     return state?.serial ?? 0;
   }
   async collectGarbage(t) {
+    const layout = this.#layout;
     return this.#writeTx(ALL_STORES, "Collecting unused content", async (tx, meta) => {
       const state = this.#requireMeta(meta);
       this.#checkFence(state, t);
       const keep = await this.#hashesWithEntries(tx, null);
-      const hashes = await requestAsPromise(tx.objectStore(STORE_BLOBS).getAllKeys());
+      const sizes = layout.blobSizeIndex === null ? new Map(
+        (await requestAsPromise(tx.objectStore(STORE_BLOBS).getAllKeys(layout.range))).flatMap((key) => {
+          const hash = layout.blobHashOf(key);
+          return hash === void 0 ? [] : [[hash, 0]];
+        })
+      ) : await blobSizes(tx, layout);
       let removed = 0;
-      for (const hash of hashes) {
-        if (typeof hash === "string" && !keep.has(hash)) {
-          tx.objectStore(STORE_BLOBS).delete(hash);
-          removed += 1;
-        }
-      }
+      let bytes = 0;
+      for (const [hash, size] of sizes) {
+        if (keep.has(hash)) continue;
+        tx.objectStore(STORE_BLOBS).delete(layout.blobKey(hash));
+        removed += 1;
+        bytes += size;
+      }
+      if (removed > 0) await this.#hooks.accountErase?.(tx, { partitionId: layout.partitionId, bytes });
       return removed;
     });
   }
+  /** Clear this replica's entries and blobs inside `tx`, accounting the erased bytes. */
+  async #clearRows(tx) {
+    const bytes = this.#hooks.accountErase === void 0 ? 0 : sumSizes(await blobSizes(tx, this.#layout));
+    clearReplicaRows(tx, this.#layout);
+    await this.#hooks.accountErase?.(tx, { partitionId: this.#layout.partitionId, bytes });
+  }
   async reset(t, reason, options) {
     const generation = await this.#writeTx(ALL_STORES, "Resetting the replica", async (tx, meta) => {
       const state = this.#requireMeta(meta);
       this.#checkFence(state, t);
-      tx.objectStore(STORE_ENTRIES).clear();
-      tx.objectStore(STORE_BLOBS).clear();
+      await this.#clearRows(tx);
       state.cursor = null;
       if (options?.keepSource !== true) state.nodeDid = null;
       state.coverage = "empty";
@@ -17650,7 +17903,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
       }
       if (state.purged === true) return;
       this.#checkFence(state, t, { allowRevoked: true });
-      this.#eraseContents(tx, state);
+      await this.#eraseContents(tx, state);
       const tombstone = {
         purged: true,
         generation: state.generation + 1,
@@ -17671,9 +17924,8 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
    * the lease and the epoch bump kills the writer identity, so an in-flight
    * commit, GC or reset aborts before touching a row.
    */
-  #eraseContents(tx, state) {
-    tx.objectStore(STORE_ENTRIES).clear();
-    tx.objectStore(STORE_BLOBS).clear();
+  async #eraseContents(tx, state) {
+    await this.#clearRows(tx);
     state.cursor = null;
     state.coverage = "empty";
     state.lastSyncAt = null;
@@ -17688,12 +17940,11 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
   async markRevoked(detail) {
     await this.#writeTx(ALL_STORES, "Recording the revocation", async (tx, meta) => {
       if (meta === void 0) {
-        tx.objectStore(STORE_ENTRIES).clear();
-        tx.objectStore(STORE_BLOBS).clear();
+        await this.#clearRows(tx);
         return;
       }
       const state = this.#requireMeta(meta);
-      this.#eraseContents(tx, state);
+      await this.#eraseContents(tx, state);
       state.revoked = detail;
       state.lastError = { at: new Date(this.#now()).toISOString(), code: ReplicaErrorCode.GRANT_REVOKED, message: detail };
       state.purgePending = true;
@@ -17767,8 +18018,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
         }
         if (state === void 0 || state.purged === true) return;
         if (state.purgePending !== true) return;
-        tx.objectStore(STORE_ENTRIES).clear();
-        tx.objectStore(STORE_BLOBS).clear();
+        await this.#clearRows(tx);
         state.purgePending = false;
         this.#putMeta(tx, state);
       },
@@ -17783,12 +18033,33 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
       this.#putMeta(tx, state);
     });
   }
+  /**
+   * Finish a sync under its live lease: persist the epoch the caller
+   * captured before the sync began (`syncedThroughEpoch`) together with the
+   * completion marker, in one transaction. Call it only after the feed's
+   * last page, repairs and GC have all committed — a sync that fails
+   * earlier never reaches it, so its fence stays where it was.
+   */
+  async completeSync(t, syncStartEpoch) {
+    await this.#writeTx([STORE_META], "Finishing the sync", async (tx, meta) => {
+      const state = this.#requireMeta(meta);
+      this.#checkFence(state, t);
+      state.syncedThroughEpoch = syncStartEpoch;
+      state.syncCompletedAt = new Date(this.#now()).toISOString();
+      this.#putMeta(tx, state);
+    });
+  }
+  /** The epoch persisted by the last completed sync (0 before the first). */
+  async syncFence() {
+    const state = await this.#readTx([], async (_tx, meta) => this.#requireMeta(meta));
+    return { syncedThroughEpoch: state.syncedThroughEpoch ?? 0, syncCompletedAt: state.syncCompletedAt ?? null };
+  }
   async get(key) {
     try {
       return await this.#readTx([STORE_ENTRIES], async (tx) => {
-        const record = await requestAsPromise(tx.objectStore(STORE_ENTRIES).get(key));
+        const record = await requestAsPromise(tx.objectStore(STORE_ENTRIES).get(this.#layout.entryKey(key)));
         return record === void 0 ? void 0 : entryOf(record);
-      });
+      }, { serving: true });
     } catch (error) {
       throw idbError(error, "Reading the replica");
     }
@@ -17797,7 +18068,8 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     try {
       const records = await this.#readTx(
         [STORE_ENTRIES],
-        (tx) => requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll())
+        (tx) => requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll(this.#layout.range)),
+        { serving: true }
       );
       let rows = records.filter((record) => !record.deleted);
       if (o.prefix !== void 0 && o.prefix !== "") rows = rows.filter((record) => record.key.startsWith(o.prefix));
@@ -17813,7 +18085,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     try {
       const records = await this.#readTx(
         [STORE_ENTRIES],
-        (tx) => requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll())
+        (tx) => requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll(this.#layout.range))
       );
       return records.filter((record) => !record.deleted && !record.content).sort((a, b) => compareKeyBytes2(a.key, b.key)).slice(0, limit).map(entryOf);
     } catch (error) {
@@ -17824,9 +18096,9 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     try {
       return await this.#readTx([STORE_BLOBS], async (tx) => {
         if (!isHash(hash)) return void 0;
-        const record = await requestAsPromise(tx.objectStore(STORE_BLOBS).get(hash));
+        const record = await requestAsPromise(tx.objectStore(STORE_BLOBS).get(this.#layout.blobKey(hash)));
         return record?.bytes;
-      });
+      }, { serving: true });
     } catch (error) {
       throw idbError(error, "Reading replica content");
     }
@@ -17834,11 +18106,12 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
   async status(now = this.#now()) {
     let state;
     let records;
+    let view;
     try {
-      ({ state, records } = await this.#readTx([STORE_ENTRIES], async (tx, meta) => {
+      ({ state, records, view } = await this.#readTx(this.#hooks.grantPolicy ? [STORE_ENTRIES, "device"] : [STORE_ENTRIES], async (tx, meta) => {
         const s = this.#requireMeta(meta);
-        const rs = await requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll());
-        return { state: s, records: rs };
+        const rs = await requestAsPromise(tx.objectStore(STORE_ENTRIES).getAll(this.#layout.range));
+        return { state: s, records: rs, view: await this.#policyView(tx, s) };
       }));
     } catch (error) {
       throw idbError(error, "Reading the replica");
@@ -17858,7 +18131,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
     }
     const { retentionRevoked: _retentionRevoked, ...authority } = effectiveAuthority({
       window: state.authority,
-      grant: state.grant,
+      grant: this.#cappedGrant(state.grant, view),
       revoked: state.revoked,
       retentionRevoked: state.retentionRevoked,
       policy: state.config.localReadPolicy,
@@ -17896,7 +18169,7 @@ var IndexedDbReplicaStore = class _IndexedDbReplicaStore {
   }
   async close() {
     this.#closed = true;
-    this.#db.close();
+    if (this.#ownsDb) this.#db.close();
   }
 };