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

package/dist/kv/replication/index.js

@@ -0,0 +1,1342 @@
+// src/kv/replication/constants.ts
+var CLEAR_PENDING_WARNING = "Clearing pending writes surrenders read-your-writes protection for the cleared keys. If a write whose record was cleared had an unknown outcome or never finished, it may commit now or later; this device can serve an older value until the next sync after that commit, as it would for a write from another device.";
+
+// src/kv/replication/identity.ts
+var SPACE_ID = /^(tinycloud:pkh:eip155:\d+:)([^:]+)(:.+)$/;
+var PRINCIPAL_DID = /^(did:pkh:eip155:\d+:)([^:]+)$/;
+function canonicalReplicationIdentity(raw) {
+  if (!raw || typeof raw.host !== "string" || typeof raw.space !== "string" || typeof raw.principal !== "string") {
+    throw new TypeError(
+      "Replication identity host, space, and principal must be strings"
+    );
+  }
+  const authority = /^https?:\/\/([^/?#]*)/i.exec(raw.host)?.[1];
+  let url;
+  try {
+    url = new URL(raw.host);
+  } catch {
+    throw new TypeError(
+      "Replication identity host must be an absolute HTTP(S) URL"
+    );
+  }
+  if (!authority || authority.includes("@") || raw.host.includes("?") || raw.host.includes("#") || url.username || url.password) {
+    throw new TypeError(
+      "Replication identity host must be HTTP(S) without credentials, query, or fragment"
+    );
+  }
+  const space = SPACE_ID.exec(raw.space);
+  const principal = PRINCIPAL_DID.exec(raw.principal);
+  if (!space || !principal) {
+    throw new TypeError(
+      "Replication identity requires a full TinyCloud space id and a pkh principal DID"
+    );
+  }
+  return {
+    host: `${url.origin}${url.pathname.replace(/\/+$/, "")}`,
+    space: `${space[1]}${space[2].toLowerCase()}${space[3]}`,
+    principal: `${principal[1]}${principal[2].toLowerCase()}`
+  };
+}
+function replicationIdentityKey(id) {
+  const canonical = canonicalReplicationIdentity(id);
+  return `tc-replication/v1
+${canonical.host}
+${canonical.space}
+${canonical.principal}`;
+}
+
+// src/kv/replication/scope.ts
+function kvPrefixCovers(prefix, key) {
+  if (prefix === "") return true;
+  if (prefix.endsWith("/")) return key.startsWith(prefix);
+  return key === prefix || key.startsWith(`${prefix}/`);
+}
+function listRangeCovers(path, key) {
+  return key === path || key.startsWith(path.endsWith("/") ? path : `${path}/`);
+}
+function requiresSecretsOptIn(space, prefix) {
+  if (space === "secrets" || space.endsWith(":secrets")) return true;
+  return prefix.split("/", 1)[0] === "vault";
+}
+
+// src/errors.ts
+import { CAPABILITY_REGISTRY } from "@tinycloud/bootstrap";
+
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  ABORTED: "ABORTED",
+  INVALID_INPUT: "INVALID_INPUT",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  // KV-specific errors
+  KV_NOT_FOUND: "KV_NOT_FOUND",
+  KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
+  KV_CONFLICT: "KV_CONFLICT",
+  KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 3,
+  backoff: "exponential",
+  baseDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+};
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function serviceError(code, message, service, options) {
+  return {
+    code,
+    message,
+    service,
+    cause: options?.cause,
+    meta: options?.meta
+  };
+}
+
+// src/errors.ts
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function isRequestTimeoutError(error) {
+  return error instanceof RequestTimeoutError || error instanceof Error && error.name === "TimeoutError" && typeof error.timeoutMs === "number";
+}
+function timeoutError(service, timeoutMs, cause) {
+  if (timeoutMs === void 0) {
+    return {
+      code: ErrorCodes.TIMEOUT,
+      message: "Request timed out.",
+      service,
+      ...cause === void 0 ? {} : { cause }
+    };
+  }
+  return {
+    code: ErrorCodes.TIMEOUT,
+    message: `Request timed out after ${timeoutMs}ms.`,
+    service,
+    ...cause === void 0 ? {} : { cause },
+    meta: { timeoutMs }
+  };
+}
+function abortedError(service) {
+  return {
+    code: ErrorCodes.ABORTED,
+    message: "Request was aborted.",
+    service
+  };
+}
+var grantableActions = new Set(
+  CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
+);
+var capabilityServices = new Set(
+  CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
+);
+function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+  if (error instanceof Error) {
+    if (isRequestTimeoutError(error)) {
+      return timeoutError(service, error.timeoutMs, error);
+    }
+    if (error.name === "AbortError") {
+      return abortedError(service);
+    }
+    if (error.name === "TimeoutError" || error.message.toLowerCase().includes("timeout")) {
+      return timeoutError(service);
+    }
+    return {
+      code: defaultCode,
+      message: error.message,
+      service,
+      cause: error
+    };
+  }
+  return {
+    code: defaultCode,
+    message: String(error),
+    service
+  };
+}
+
+// src/kv/replication/outcome.ts
+var DEFINITIVE_FAILURES = /* @__PURE__ */ new Set([
+  ErrorCodes.AUTH_REQUIRED,
+  ErrorCodes.INVALID_INPUT,
+  ErrorCodes.AUTH_UNAUTHORIZED,
+  ErrorCodes.KV_PRECONDITION_FAILED,
+  ErrorCodes.STORAGE_QUOTA_EXCEEDED,
+  ErrorCodes.STORAGE_LIMIT_REACHED
+]);
+function classifyWriteOutcome(op, result, options = {}) {
+  if (result.ok) return "committed";
+  const { code, meta } = result.error;
+  if (op === "delete" && code === ErrorCodes.KV_NOT_FOUND) {
+    return options.conditional === true ? "failed" : "committed";
+  }
+  if (meta?.requestMayHaveDispatched === false) return "failed";
+  if (DEFINITIVE_FAILURES.has(code)) return "failed";
+  if (meta?.outcome === "batch-unconfirmed") return "ambiguous";
+  const status = typeof meta?.status === "number" ? meta.status : void 0;
+  if (status !== void 0 && status >= 400 && status < 500) return "failed";
+  return "ambiguous";
+}
+
+// src/kv/replication/pendingWrites.ts
+function emptyPendingState(identity) {
+  return { v: 2, identity: { ...identity }, committedEpoch: 0, seq: 0, records: [] };
+}
+function begin(s, opId, keys, at) {
+  const records = keys.map(({ key, op }) => ({ opId, seq: ++s.seq, key, op, state: "in_flight", epoch: null, at, settledAt: null }));
+  s.records.push(...records);
+  return records;
+}
+function settle(s, opId, outcome, at, code) {
+  if (outcome === "failed") {
+    s.records = s.records.filter((r) => r.opId !== opId);
+    return;
+  }
+  const own = s.records.filter((r) => r.opId === opId && r.state === "in_flight");
+  if (outcome === "committed" && own.length > 0) {
+    const epoch = ++s.committedEpoch;
+    for (const r of own) {
+      r.state = "committed";
+      r.epoch = epoch;
+      r.settledAt = at;
+    }
+    return;
+  }
+  for (const r of own) {
+    r.state = "ambiguous";
+    r.settledAt = at;
+    if (code) r.code = code;
+  }
+}
+function afterSync(s, prefix, syncStartEpoch) {
+  const before = s.records.length;
+  s.records = s.records.filter((r) => !(r.state === "committed" && r.epoch !== null && r.epoch <= syncStartEpoch && kvPrefixCovers(prefix, r.key)));
+  return before - s.records.length;
+}
+function clearPrefix(s, prefix) {
+  const before = s.records.length;
+  s.records = s.records.filter((r) => !kvPrefixCovers(prefix, r.key));
+  return before - s.records.length;
+}
+function clearPending(s, now) {
+  const before = s.records.length;
+  s.records = s.records.filter((r) => r.state === "committed" || r.state === "in_flight" && now - Date.parse(r.at) <= 10 * 6e4);
+  return before - s.records.length;
+}
+function pinnedKeys(s, prefix, now, cap = 100) {
+  return s.records.filter((r) => kvPrefixCovers(prefix, r.key) && (r.state === "in_flight" || r.state === "ambiguous")).sort((a, b) => a.seq - b.seq).slice(0, cap).map((r) => ({ key: r.key, state: r.state, op: r.op, since: r.at, ...r.code ? { code: r.code } : {}, likelyOrphaned: r.state === "in_flight" && now - Date.parse(r.at) > 10 * 6e4 }));
+}
+
+// src/kv/replication/localResponse.ts
+function parseLocalValue(bytes, contentType, raw, binary) {
+  if (binary) return bytes;
+  const text = new TextDecoder().decode(bytes);
+  if (raw) return text;
+  if (contentType?.includes("application/json")) return JSON.parse(text);
+  if (contentType?.startsWith("text/")) return text;
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function localGet(result, key, options) {
+  if (result.status === "present") {
+    if (options.maxResponseBytes !== void 0 && result.value.byteLength > options.maxResponseBytes) {
+      return err(serviceError(ErrorCodes.KV_RESPONSE_TOO_LARGE, `KV value at key ${JSON.stringify(key)} exceeds the requested response limit`, "kv", { meta: { status: 413 } }));
+    }
+    const contentType = Object.entries(result.metadata).find(([name]) => name.toLowerCase() === "content-type")?.[1];
+    const headers = new Headers({ etag: result.etag, "content-length": String(result.value.byteLength), "cache-control": "private, no-cache", ...result.metadata, "x-tinycloud-source": "replica" });
+    return ok({
+      data: parseLocalValue(result.value, contentType, options.raw, options.binary),
+      headers: {
+        etag: result.etag,
+        contentType,
+        contentLength: result.value.byteLength,
+        get: (name) => headers.get(name)
+      }
+    });
+  }
+  if (result.status === "absent" || result.status === "deleted") return err(serviceError(ErrorCodes.KV_NOT_FOUND, `Key not found: ${key}`, "kv"));
+  return err(serviceError(ErrorCodes.NETWORK_ERROR, "Local value is not available", "kv"));
+}
+
+// src/kv/replication/listLocal.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+function utf8Compare(a, b) {
+  const x = encoder.encode(a), y = encoder.encode(b);
+  for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return x.length - y.length;
+}
+function encodeTcr1(space, path, last) {
+  const bytes = encoder.encode(JSON.stringify({ v: 1, space, path, last }));
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32768) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+  }
+  const payload = btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return `tcr1.${payload}`;
+}
+function decodeTcr1(cursor) {
+  try {
+    const encoded = cursor.slice(5).replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(encoded + "=".repeat((4 - encoded.length % 4) % 4));
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    const x = JSON.parse(decoder.decode(bytes));
+    return x?.v === 1 && typeof x.space === "string" && typeof x.path === "string" && typeof x.last === "string" ? x : null;
+  } catch {
+    return null;
+  }
+}
+function cursorRestart() {
+  return err(serviceError(ErrorCodes.INVALID_INPUT, "Local list cursor cannot be served; restart without the cursor", "kv", { meta: { replication: "cursor_restart" } }));
+}
+function localList(handle, space, path, limit, cursor, validateMeta) {
+  const after = cursor ? decodeTcr1(cursor)?.last : void 0;
+  const exact = !path.endsWith("/") && (after === void 0 || utf8Compare(path, after) > 0) ? awaitExact(handle, path, after, validateMeta) : Promise.resolve(false);
+  return exact.then(async (hasExact) => {
+    const child = path.endsWith("/") ? path : `${path}/`;
+    const want = limit === void 0 ? void 0 : limit + 1 - (hasExact ? 1 : 0);
+    const children = await handle.list({ prefix: child, after, limit: want });
+    validateMeta(children.meta);
+    let keys = (hasExact ? [path] : []).concat(children.keys);
+    const truncated = limit !== void 0 && keys.length > limit;
+    if (truncated) keys = keys.slice(0, limit);
+    return { keys, truncated, ...truncated ? { nextCursor: encodeTcr1(space, path, keys[keys.length - 1]) } : {} };
+  });
+}
+async function awaitExact(handle, path, after, validateMeta) {
+  if (after !== void 0 && utf8Compare(path, after) <= 0) return false;
+  const result = await handle.list({ prefix: path, limit: 1 });
+  validateMeta(result.meta);
+  return result.keys[0] === path;
+}
+function listPathCovered(prefixes, path) {
+  const descendant = path.endsWith("/") ? path : `${path}/`;
+  const covering = prefixes.filter((prefix) => kvPrefixCovers(prefix, path) && kvPrefixCovers(prefix, descendant));
+  return covering.length === 1 ? covering[0] : void 0;
+}
+
+// src/kv/replication/events.ts
+function emitEvent(emit, scheduler, event) {
+  try {
+    emit({ ...event, at: new Date(scheduler.now()).toISOString() });
+  } catch {
+  }
+}
+
+// src/kv/replication/controller.ts
+var CLOSE_TIMEOUT_MS = 3e3;
+var STATUS_REFRESH_TIMEOUT_MS = CLOSE_TIMEOUT_MS;
+var nowDate = (now) => new Date(now).toISOString();
+var errorCode = (e) => typeof e === "object" && e !== null && "code" in e && typeof e.code === "string" ? e.code : "REPLICA_UNAVAILABLE";
+function raceSignal(job, signal) {
+  if (signal.aborted) return Promise.reject(signal.reason ?? Object.assign(new Error("KV request was aborted"), { code: ErrorCodes.ABORTED }));
+  let remove = () => {
+  };
+  const aborted = new Promise((_, reject) => {
+    const onAbort = () => reject(signal.reason ?? Object.assign(new Error("KV request was aborted"), { code: ErrorCodes.ABORTED }));
+    signal.addEventListener("abort", onAbort, { once: true });
+    remove = () => signal.removeEventListener("abort", onAbort);
+  });
+  return Promise.race([job, aborted]).finally(remove);
+}
+function createKVReplication(deps) {
+  const { options, mode, storage, identity, session, authority, pending, scheduler } = deps;
+  const replicas = /* @__PURE__ */ new Map();
+  const statusInspections = /* @__PURE__ */ new Set();
+  let isClosed = false;
+  let purgeStarted = false;
+  let purgeInProgress = false;
+  let previous = deps.previous;
+  let pinnedStateReported = false;
+  const inProcessProof = /* @__PURE__ */ new Set();
+  const emit = (event) => emitEvent(deps.emit, scheduler, event);
+  const configuredPrefix = (path) => options.prefixes.find((prefix) => kvPrefixCovers(prefix, path));
+  function recordRevocation(prefix, error) {
+    if (errorCode(error) !== "GRANT_REVOKED") return;
+    const state = replicas.get(prefix) ?? {};
+    state.authorityRevoked = true;
+    state.reason = "grant_revoked";
+    state.lastError = "GRANT_REVOKED";
+    replicas.set(prefix, state);
+  }
+  async function open(prefix) {
+    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;
+    if (state?.opening) return state.opening;
+    state ?? (state = {});
+    replicas.set(prefix, state);
+    if (state.unsupported) throw Object.assign(new Error("Replication runtime is unsupported"), { code: "RUNTIME_UNSUPPORTED" });
+    if (state.retryAt !== void 0 && scheduler.now() < state.retryAt) throw Object.assign(new Error("Replica open is backing off"), { code: state.lastError ?? "REPLICA_UNAVAILABLE" });
+    if (requiresSecretsOptIn(session.space, prefix) && !options.allowSecrets) {
+      const firstRefusal = state.lastError !== "SECRETS_OPT_IN_REQUIRED";
+      state.reason = "replica_unavailable";
+      state.lastError = "SECRETS_OPT_IN_REQUIRED";
+      if (firstRefusal) emit({ type: "replication.state", space: session.space, replica: prefix, state: "unavailable", code: "SECRETS_OPT_IN_REQUIRED" });
+      throw Object.assign(new Error("Replication requires allowSecrets for this space or prefix"), { code: "SECRETS_OPT_IN_REQUIRED" });
+    }
+    state.opening = (async () => {
+      if (previous) {
+        await previous;
+        previous = void 0;
+      }
+      const sessionGrant = authority.sessionGrant(prefix);
+      const delegated = "refused" in sessionGrant ? void 0 : sessionGrant;
+      const plan = authority.sessionOnly ? void 0 : authority.plan(prefix);
+      let refusalCode;
+      if ("refused" in sessionGrant) refusalCode = sessionGrant.refused;
+      if (plan && "refused" in plan) refusalCode ?? (refusalCode = plan.refused);
+      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 handle = await storage.open(spec);
+      state.handle = handle;
+      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) {
+        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;
+          }
+        }
+        if (installed?.unconstrained) {
+          state.strategy ?? (state.strategy = "installed");
+          state.reason = void 0;
+        }
+      }
+      if (!installed?.unconstrained) {
+        state.reason = "grant_missing";
+        state.lastError = refusalCode ?? "SESSION_LACKS_SYNC";
+        emit({ type: "replication.state", space: session.space, replica: prefix, state: "grant_missing", code: state.lastError });
+      } else emit({ type: "replication.state", space: session.space, replica: prefix, state: "grant_installed", strategy: state.strategy });
+      if (isClosed || purgeStarted) {
+        await handle.close();
+        throw Object.assign(new Error("Replication controller is closed"), { code: "REPLICA_CLOSED" });
+      }
+      if (mode === "background" && state.reason !== "grant_missing") {
+        void syncPrefix(prefix, "start").catch(() => void 0);
+        schedule(prefix);
+      }
+      return handle;
+    })();
+    try {
+      return await state.opening;
+    } catch (error) {
+      const code = errorCode(error);
+      recordRevocation(prefix, error);
+      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") 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;
+    } finally {
+      state.opening = void 0;
+    }
+  }
+  function schedule(prefix) {
+    const state = replicas.get(prefix);
+    if (!state || mode !== "background" || isClosed || purgeStarted) return;
+    state.timer = scheduler.setTimeout(() => {
+      state.timer = void 0;
+      void syncPrefix(prefix, "interval").catch(() => void 0).finally(() => schedule(prefix));
+    }, options.syncIntervalMs);
+  }
+  async function syncPrefix(prefix, trigger, signal, context) {
+    const handle = await open(prefix);
+    const state = replicas.get(prefix);
+    if (state.sync) return state.sync;
+    const abort = new AbortController();
+    const syncContext = context ?? {};
+    state.syncContext = syncContext;
+    state.abort = abort;
+    const abortFromCaller = () => {
+      syncContext.abortCause ?? (syncContext.abortCause = "caller");
+      abort.abort(signal?.reason);
+    };
+    signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const started = scheduler.now();
+    let job;
+    job = (async () => {
+      try {
+        const syncStartEpoch = (await pending.read()).committedEpoch;
+        const result = await handle.sync({ signal: abort.signal, syncStartEpoch });
+        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 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;
+        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 });
+        throw error;
+      } finally {
+        signal?.removeEventListener("abort", abortFromCaller);
+        state.abort = void 0;
+      }
+    })();
+    state.sync = job;
+    try {
+      return await job;
+    } finally {
+      if (state.sync === job) {
+        state.sync = void 0;
+        state.syncContext = void 0;
+      }
+    }
+  }
+  async function drainForegroundSync(prefix, sync2) {
+    let cancel = () => {
+    };
+    const settled = sync2.then(
+      (result) => ({ settled: true, result }),
+      (error) => ({ settled: true, error })
+    );
+    const timeout = new Promise((resolve) => {
+      cancel = scheduler.setTimeout(() => resolve({ settled: false }), CLOSE_TIMEOUT_MS);
+    });
+    try {
+      const drained = await Promise.race([settled, timeout]);
+      if (!drained.settled) emit({ type: "replication.sync", space: session.space, replica: prefix, trigger: "stale_read", outcome: "aborted", code: "DRAIN_TIMEOUT", durationMs: CLOSE_TIMEOUT_MS, lagMs: null });
+      return drained;
+    } finally {
+      cancel();
+    }
+  }
+  function validateReadMeta(meta) {
+    if (meta.coverage !== "complete") throw Object.assign(new Error("Replica coverage changed before the local read"), { code: "COVERAGE_INCOMPLETE" });
+    if (meta.authority !== "valid") {
+      const code = meta.authority === "expired" ? "GRANT_EXPIRED" : meta.authority === "revoked" ? "GRANT_REVOKED" : "GRANT_NOT_YET_VALID";
+      throw Object.assign(new Error("Replica authority changed before the local read"), { code });
+    }
+  }
+  function reasonForReadMetaCode(code) {
+    if (code === "COVERAGE_INCOMPLETE") return "coverage_incomplete";
+    if (code === "GRANT_EXPIRED") return "grant_expired";
+    if (code === "GRANT_REVOKED") return "grant_revoked";
+    if (code === "GRANT_NOT_YET_VALID") return "grant_not_yet_valid";
+    return "replica_error";
+  }
+  async function statusAfterDrain(handle, signal) {
+    let cancel = () => {
+    };
+    const timeout = new Promise((_resolve, reject) => {
+      cancel = scheduler.setTimeout(
+        () => reject(Object.assign(new Error("Replica status refresh timed out"), { code: "STATUS_TIMEOUT" })),
+        STATUS_REFRESH_TIMEOUT_MS
+      );
+    });
+    try {
+      return await raceSignal(Promise.race([handle.status(), timeout]), signal);
+    } finally {
+      cancel();
+    }
+  }
+  function staleSyncOutcome(outcome, timedOut, currentStatus) {
+    if ("error" in outcome) {
+      const code = errorCode(outcome.error);
+      if (code === "NETWORK_ERROR" || timedOut && (code === "ABORTED" || code === "TIMEOUT")) return { status: currentStatus, syncedBeforeRead: false, syncError: code === "NETWORK_ERROR" ? code : "TIMEOUT" };
+      return { status: currentStatus, syncedBeforeRead: false, syncError: code, failure: "error" };
+    }
+    if (outcome.result.status === "busy") return { status: currentStatus, syncedBeforeRead: false, failure: "busy" };
+    return { status: currentStatus, syncedBeforeRead: true };
+  }
+  async function freshness(prefix, handle, signal) {
+    let currentStatus = await handle.status();
+    const syncedAt = currentStatus.lastSyncAt === null ? null : Date.parse(currentStatus.lastSyncAt);
+    const stale = syncedAt === null || !Number.isFinite(syncedAt) || scheduler.now() - syncedAt > options.maxStalenessMs;
+    let snapshot;
+    try {
+      snapshot = await pending.read();
+    } catch (error) {
+      return { status: currentStatus, syncedBeforeRead: false, syncError: errorCode(error), failure: "error" };
+    }
+    const behind = currentStatus.syncedThroughEpoch < snapshot.committedEpoch;
+    const unproven = !pending.durable && !inProcessProof.has(prefix);
+    if ((stale || behind || unproven) && !signal.aborted) {
+      const syncController = mode === "foreground" ? new AbortController() : void 0;
+      const syncState = replicas.get(prefix);
+      const ownsSync = !syncState?.sync;
+      const syncContext = syncState?.syncContext ?? {};
+      const abortFromCaller = () => {
+        if (ownsSync) syncContext.abortCause ?? (syncContext.abortCause = "caller");
+        syncController?.abort(signal.reason);
+      };
+      if (syncController) signal.addEventListener("abort", abortFromCaller, { once: true });
+      let cancelTimeout = () => {
+      };
+      const timeout = new Promise((resolve) => {
+        cancelTimeout = scheduler.setTimeout(() => resolve({ timeout: true }), options.staleSyncTimeoutMs);
+      });
+      let cancelAbort = () => {
+      };
+      const callerAbort = new Promise((resolve) => {
+        if (signal.aborted) resolve({ callerAborted: true });
+        else {
+          const listener = () => resolve({ callerAborted: true });
+          signal.addEventListener("abort", listener, { once: true });
+          cancelAbort = () => signal.removeEventListener("abort", listener);
+        }
+      });
+      const sync2 = syncPrefix(prefix, "stale_read", syncController?.signal, syncContext);
+      const outcome = await Promise.race([
+        sync2.then((result) => ({ result }), (error) => ({ error })),
+        timeout,
+        callerAbort
+      ]);
+      cancelTimeout();
+      cancelAbort();
+      signal.removeEventListener("abort", abortFromCaller);
+      if ("callerAborted" in outcome) {
+        if (syncController && ownsSync) {
+          syncContext.abortCause ?? (syncContext.abortCause = "caller");
+          syncController.abort(signal.reason);
+          await drainForegroundSync(prefix, sync2);
+        }
+        return { status: currentStatus, syncedBeforeRead: false, syncError: cancellationCode(signal) };
+      }
+      if ("timeout" in outcome) {
+        if (ownsSync) {
+          syncContext.abortCause ?? (syncContext.abortCause = "timeout");
+          syncController?.abort(Object.assign(new Error("Stale-read sync timed out"), { code: "TIMEOUT" }));
+        }
+        const drained = syncController ? await drainForegroundSync(prefix, sync2) : void 0;
+        if (signal.aborted) return { status: currentStatus, syncedBeforeRead: false, syncError: cancellationCode(signal) };
+        if (drained && !drained.settled) return { status: currentStatus, syncedBeforeRead: false, syncError: "DRAIN_TIMEOUT", failure: "error" };
+        try {
+          currentStatus = await statusAfterDrain(handle, signal);
+        } catch (error) {
+          if (signal.aborted) return { status: currentStatus, syncedBeforeRead: false, syncError: cancellationCode(signal), failure: "error" };
+          return { status: currentStatus, syncedBeforeRead: false, syncError: errorCode(error), failure: "error" };
+        }
+        const timeoutAbort = syncContext.abortCause === "timeout";
+        return staleSyncOutcome(
+          drained?.settled ? "result" in drained ? { result: drained.result } : { error: drained.error } : { error: Object.assign(new Error("Stale-read sync timed out"), { code: "TIMEOUT" }) },
+          timeoutAbort || !syncController,
+          currentStatus
+        );
+      }
+      if ("error" in outcome) return staleSyncOutcome({ error: outcome.error }, false, currentStatus);
+      if (outcome.result.status === "busy") return { status: currentStatus, syncedBeforeRead: false, failure: "busy" };
+      currentStatus = await handle.status();
+      return { status: currentStatus, syncedBeforeRead: true };
+    }
+    return { status: currentStatus, syncedBeforeRead: false };
+  }
+  function readEvent(op, path, prefix, source, reason, outcome, started, extra = {}) {
+    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 verifyGet(r, local, reason, started, extra) {
+    const prefix = configuredPrefix(r.path) ?? null;
+    const localFound = local.ok;
+    const localNotFound = !local.ok && local.error.code === ErrorCodes.KV_NOT_FOUND;
+    const outcome = localFound ? "found" : localNotFound ? "not_found" : "error";
+    try {
+      const network = await raceSignal(r.network(), r.signal);
+      if (r.signal.aborted) {
+        readEvent("get", r.path, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
+        return abortedResult(r.signal);
+      }
+      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;
+      }
+      const networkFound = network.ok;
+      const networkNotFound = !network.ok && network.error.code === ErrorCodes.KV_NOT_FOUND;
+      const localEtag = local.ok ? local.data.headers.etag ?? null : null;
+      const networkEtag = network.ok ? network.data.headers.etag ?? null : null;
+      const matches = localFound && networkFound ? localEtag === networkEtag : localNotFound && networkNotFound;
+      const verify = matches ? "match" : "diverged";
+      if (!matches) {
+        emit({
+          type: "replication.divergence",
+          op: "get",
+          space: r.space,
+          key: r.path,
+          replica: prefix ?? "",
+          kind: localFound && networkFound ? "value" : localNotFound ? "missing_local" : "extra_local",
+          localEtag,
+          networkEtag,
+          stalenessMs: typeof extra.stalenessMs === "number" ? extra.stalenessMs : null
+        });
+      }
+      readEvent("get", r.path, prefix, "replica", reason, outcome, started, { ...extra, verify });
+      return local;
+    } catch (error) {
+      if (r.signal.aborted) {
+        readEvent("get", r.path, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
+        return abortedResult(r.signal);
+      }
+      readEvent("get", r.path, prefix, "replica", reason, outcome, started, { ...extra, code: errorCode(error), verify: "error" });
+      return local;
+    }
+  }
+  async function verifyList(r, local, started, extra) {
+    const prefix = listPathCovered(options.prefixes, r.listPath) ?? null;
+    try {
+      const network = await raceSignal(r.network(), r.signal);
+      if (r.signal.aborted) {
+        readEvent("list", r.listPath, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
+        return abortedResult(r.signal);
+      }
+      if (!network.ok) {
+        readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, { ...extra, code: network.error.code, verify: "error" });
+        return ok(local);
+      }
+      const localSet = new Set(local.keys);
+      const networkSet = new Set(network.data.keys);
+      const localOnly = local.keys.filter((key) => !networkSet.has(key));
+      const networkOnly = network.data.keys.filter((key) => !localSet.has(key));
+      const sameKeys = localOnly.length === 0 && networkOnly.length === 0;
+      const sameOrder = sameKeys && local.keys.every((key, index) => key === network.data.keys[index]);
+      const verify = sameOrder ? "match" : "diverged";
+      if (!sameKeys || !sameOrder) {
+        emit({
+          type: "replication.divergence",
+          op: "list",
+          space: r.space,
+          key: r.listPath,
+          replica: prefix ?? "",
+          kind: sameKeys ? "order" : "keys",
+          ...!sameKeys ? { localOnly, networkOnly } : {},
+          stalenessMs: typeof extra.stalenessMs === "number" ? extra.stalenessMs : null
+        });
+      }
+      readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, { ...extra, verify });
+      return ok(local);
+    } catch (error) {
+      if (r.signal.aborted) {
+        readEvent("list", r.listPath, prefix, "none", "aborted", "error", started, { ...extra, verify: "aborted" });
+        return abortedResult(r.signal);
+      }
+      readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, { ...extra, code: errorCode(error), verify: "error" });
+      return ok(local);
+    }
+  }
+  async function reportExistingPins() {
+    if (pinnedStateReported) return;
+    pinnedStateReported = true;
+    try {
+      const records = await pending.read();
+      const pins = pinnedKeys(records, "", scheduler.now());
+      if (pins.length > 0) emit({ type: "replication.state", space: session.space, state: "pinned", count: pins.length, keys: pins.map((pin) => pin.key) });
+    } catch {
+      emit({ type: "replication.state", space: session.space, state: "pending_store_error", code: "STORAGE_ERROR" });
+    }
+  }
+  async function get(r) {
+    const started = scheduler.now();
+    const prefix = configuredPrefix(r.path);
+    if (r.options?.source === "network") {
+      let outcome = "error";
+      try {
+        const value = await r.network();
+        outcome = value.ok ? "found" : value.error.code === ErrorCodes.KV_NOT_FOUND ? "not_found" : "error";
+        return value;
+      } finally {
+        observeNetworkRequested({ op: "get", space: r.space, path: r.path, reason: "NETWORK_REQUESTED", outcome, latencyMs: scheduler.now() - started });
+      }
+    }
+    if (!prefix) {
+      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;
+    }
+    try {
+      await raceSignal(reportExistingPins(), r.signal);
+    } catch {
+      if (r.signal.aborted) return abortedResult(r.signal);
+    }
+    let handle;
+    try {
+      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 (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;
+    }
+    let fresh;
+    try {
+      fresh = await freshness(prefix, handle, r.signal);
+    } catch (error) {
+      recordRevocation(prefix, error);
+      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;
+    }
+    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;
+    }
+    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 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;
+    }
+    try {
+      const local = await raceSignal(handle.get(r.path), r.signal);
+      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;
+      }
+      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;
+      }
+      const result = localGet(local, r.path, r.options ?? {});
+      const reason = local.status === "present" ? "hit" : local.status;
+      const syncedAt = fresh.status.lastSyncAt === null ? null : Date.parse(fresh.status.lastSyncAt);
+      const event = {
+        syncedBeforeRead: fresh.syncedBeforeRead,
+        coverage: local.meta.coverage,
+        authority: local.meta.authority,
+        stalenessMs: syncedAt === null ? null : scheduler.now() - syncedAt,
+        ...fresh.syncError ? { syncError: fresh.syncError } : {}
+      };
+      if (options.verify) return await verifyGet(r, result, reason, started, event);
+      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) {
+      recordRevocation(prefix, error);
+      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;
+    }
+  }
+  async function list(r) {
+    const started = scheduler.now();
+    if (r.options?.source === "network") {
+      let outcome = "error";
+      try {
+        const result = await r.network();
+        outcome = result.ok ? "found" : "error";
+        return result;
+      } finally {
+        observeNetworkRequested({ op: "list", space: r.space, path: r.listPath, reason: "NETWORK_REQUESTED", outcome, latencyMs: scheduler.now() - started });
+      }
+    }
+    const cursor = r.options?.cursor;
+    const decoded = cursor?.startsWith("tcr1.") ? decodeTcr1(cursor) : null;
+    if (cursor && cursor.startsWith("tcr1.") && !decoded) {
+      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;
+    }
+    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();
+    };
+    if (cursor && decoded && (decoded.space !== r.space || decoded.path !== r.listPath)) return restart();
+    if (!prefix || !r.listPath || r.options?.raw) {
+      if (cursor && decoded) return restart();
+      const result = await r.network();
+      readEvent("list", r.listPath, prefix ?? null, "network", prefix ? "unsupported_option" : "not_covered", result.ok ? "found" : "error", started);
+      return result;
+    }
+    let handle;
+    try {
+      handle = await raceSignal(open(prefix), r.signal);
+    } 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", errorCode(error) === "RUNTIME_UNSUPPORTED" ? "runtime_unsupported" : "replica_unavailable", result.ok ? "found" : "error", started, { code: errorCode(error) });
+      return result;
+    }
+    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;
+    }
+    let fresh;
+    try {
+      fresh = await freshness(prefix, handle, r.signal);
+    } catch (error) {
+      recordRevocation(prefix, 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_error", result.ok ? "found" : "error", started, { code: errorCode(error) });
+      return result;
+    }
+    if (r.signal.aborted) return abortedResult(r.signal);
+    let state;
+    try {
+      state = await raceSignal(pending.read(), r.signal);
+    } 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 pendingRange = state.records.find((record) => listRangeCovers(r.listPath, record.key) && (!decoded || utf8Compare(record.key, decoded.last) > 0));
+    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 (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;
+    }
+    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 event = {
+        count: page.keys.length,
+        syncedBeforeRead: fresh.syncedBeforeRead,
+        stalenessMs: fresh.status.lastSyncAt === null ? null : scheduler.now() - Date.parse(fresh.status.lastSyncAt),
+        ...fresh.syncError ? { syncError: fresh.syncError } : {}
+      };
+      if (options.verify && !cursor) return await verifyList(r, page, started, event);
+      readEvent("list", r.listPath, prefix, "replica", "hit", "found", started, event);
+      return ok(page);
+    } catch (error) {
+      if (r.signal.aborted) return abortedResult(r.signal);
+      const code = errorCode(error);
+      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;
+    }
+  }
+  async function write(r) {
+    const covered = r.entries.flatMap((entry) => {
+      const prefix = configuredPrefix(entry.path);
+      return prefix ? [{ key: entry.path, op: r.op === "delete" ? "delete" : "put" }] : [];
+    });
+    if (covered.length === 0) return r.network();
+    await reportExistingPins();
+    const opId = globalThis.crypto?.randomUUID?.() ?? `${scheduler.now()}-${Math.random()}`;
+    try {
+      await pending.update((s) => begin(s, opId, covered, nowDate(scheduler.now())));
+    } catch (error) {
+      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();
+    let result;
+    try {
+      result = await r.network();
+    } catch (error) {
+      const wrapped = wrapError("kv", error);
+      result = err({
+        ...wrapped,
+        meta: { ...wrapped.meta, requestMayHaveDispatched: true }
+      });
+    }
+    const outcome = classifyWriteOutcome(r.op, result, { conditional: r.conditional === true });
+    let settleError;
+    try {
+      await pending.update((s) => settle(s, opId, outcome, nowDate(scheduler.now()), result.ok ? void 0 : result.error.code));
+    } catch (error) {
+      settleError = error;
+    }
+    emit({ type: "replication.write", space: r.space, op: r.op, keys: covered.map((x) => x.key), outcome, ...!result.ok ? { code: result.error.code } : {}, latencyMs: scheduler.now() - started });
+    const state = await pending.read().catch(() => void 0);
+    const pins = state ? pinnedKeys(state, "", scheduler.now()) : [];
+    if (outcome === "ambiguous") emit({ type: "replication.state", space: r.space, state: "pinned", count: pins.length, keys: pins.map((p) => p.key) });
+    if (settleError) emit({ type: "replication.state", space: r.space, state: "pending_store_error", code: "STORAGE_ERROR" });
+    return result;
+  }
+  function observeNetworkRequested(r) {
+    emit({ type: "replication.read", op: r.op, space: r.space, key: r.path, replica: null, source: "network", reason: "NETWORK_REQUESTED", outcome: r.outcome, latencyMs: r.latencyMs, stalenessMs: null, coverage: null, authority: null });
+  }
+  async function inspectPersistedStatus(prefix) {
+    if (!storage.inspectStatus || isClosed || purgeInProgress) return { missing: false };
+    const sessionGrant = authority.sessionGrant(prefix);
+    const device = "refused" in sessionGrant ? void 0 : sessionGrant.device;
+    const spec = { identity, space: session.space, prefix, allowSecrets: options.allowSecrets, ...device ? { device } : {}, ...deps.fetch ? { fetch: deps.fetch } : {} };
+    const abort = new AbortController();
+    const job = Promise.resolve().then(() => storage.inspectStatus(spec, { signal: abort.signal }));
+    const settled = job.then(() => void 0, () => void 0);
+    const inspection = { abort, settled };
+    statusInspections.add(inspection);
+    void settled.then(() => statusInspections.delete(inspection));
+    let cancel = () => {
+    };
+    const timeout = new Promise((resolve) => {
+      cancel = scheduler.setTimeout(() => {
+        abort.abort(Object.assign(new Error("Replica status inspection timed out"), { code: "STATUS_TIMEOUT" }));
+        resolve({ timedOut: true });
+      }, STATUS_REFRESH_TIMEOUT_MS);
+    });
+    try {
+      const result = await Promise.race([job.then((local) => ({ local })), timeout]);
+      if ("timedOut" in result) return { missing: false, errorCode: "STATUS_TIMEOUT" };
+      return { missing: result.local === void 0, ...result.local ? { local: result.local } : {} };
+    } catch (error) {
+      return { missing: false, errorCode: errorCode(error) };
+    } finally {
+      cancel();
+    }
+  }
+  function cancelStatusInspections() {
+    const active = [...statusInspections];
+    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);
+  }
+  async function status() {
+    const persistedSnapshot = pending.readExisting ? await pending.readExisting() : await pending.read();
+    const snapshot = persistedSnapshot ?? emptyPendingState(identity);
+    const entries = await Promise.all(options.prefixes.map(async (prefix) => {
+      const records = snapshot.records.filter((r) => kvPrefixCovers(prefix, r.key));
+      const opened = replicas.get(prefix);
+      let local;
+      if (opened?.handle) {
+        try {
+          local = await opened.handle.status();
+        } catch {
+        }
+      }
+      let inspected = { missing: false };
+      if (!local && !opened?.opening && !opened?.authorityRevoked) inspected = await inspectPersistedStatus(prefix);
+      local ?? (local = inspected.local);
+      if (inspected.missing && !opened?.reason && !opened?.authorityRevoked && !opened?.opening && !isClosed) return void 0;
+      const revoked = opened?.authorityRevoked === true || local?.authority.state === "revoked";
+      const state = isClosed ? "closed" : revoked ? "revoked" : opened?.reason === "grant_missing" ? "grant_missing" : local?.coverage === "complete" && local.authority.state === "valid" ? "ready" : opened?.reason || inspected.errorCode ? "unavailable" : "idle";
+      return {
+        prefix,
+        state,
+        ...opened?.reason ? { reason: opened.reason } : inspected.errorCode ? { reason: "replica_unavailable" } : {},
+        ...inspected.errorCode ? { errorCode: inspected.errorCode } : {},
+        ...local ?? {},
+        ...revoked ? { authority: { state: "revoked", expiresAt: local?.authority.expiresAt ?? null } } : {},
+        pending: {
+          inFlight: records.filter((r) => r.state === "in_flight").length,
+          committed: records.filter((r) => r.state === "committed").length,
+          ambiguous: records.filter((r) => r.state === "ambiguous").length
+        },
+        pinned: pinnedKeys(snapshot, prefix, scheduler.now()),
+        lagMs: local?.lastSyncAt ? scheduler.now() - Date.parse(local.lastSyncAt) : null
+      };
+    }));
+    return entries.filter((entry) => entry !== void 0);
+  }
+  async function sync(o) {
+    const prefixes = o?.prefix ? options.prefixes.filter((p) => p === o.prefix) : options.prefixes;
+    await Promise.all(prefixes.map((prefix) => syncPrefix(prefix, "manual", o?.signal).then(() => void 0)));
+  }
+  async function clearPending2() {
+    const count = await pending.update((s) => clearPending(s, scheduler.now()));
+    emit({ type: "replication.state", space: session.space, state: "pending_cleared", count });
+    return count;
+  }
+  function purge(o) {
+    var _a;
+    purgeStarted = true;
+    purgeInProgress = true;
+    const hasStatusInspections = statusInspections.size > 0;
+    const statusDrain = cancelStatusInspections();
+    for (const state of replicas.values()) {
+      state.timer?.();
+      state.timer = void 0;
+      state.syncContext && ((_a = state.syncContext).abortCause ?? (_a.abortCause = "purge"));
+      state.abort?.abort();
+      state.mintAbort?.abort();
+    }
+    return Promise.resolve().then(async () => {
+      const report = { purged: [], failed: [] };
+      const timeoutMs = o?.timeoutMs ?? 5e3;
+      const withTimeout = async (job) => {
+        let cancel = () => {
+        };
+        const timeout = new Promise((_, reject) => {
+          cancel = scheduler.setTimeout(() => reject(Object.assign(new Error("Replication cleanup timed out"), { code: "TIMEOUT" })), timeoutMs);
+        });
+        try {
+          return await Promise.race([job, timeout]);
+        } finally {
+          cancel();
+        }
+      };
+      const drain = Promise.all([
+        ...[...replicas.values()].flatMap((state) => [
+          state.opening?.catch(() => void 0),
+          state.sync?.catch(() => void 0),
+          state.handle?.close().catch(() => void 0)
+        ]),
+        ...hasStatusInspections ? [statusDrain] : []
+      ]);
+      let drainCode;
+      try {
+        await withTimeout(drain);
+      } catch (error) {
+        drainCode = errorCode(error);
+      }
+      const jobs = options.prefixes.map(async (prefix) => {
+        try {
+          if (drainCode) throw Object.assign(new Error("Replica cleanup did not settle before purge"), { code: drainCode });
+          const grant = authority.sessionGrant(prefix);
+          const sessionDeviceDid = replicas.get(prefix)?.handle?.deviceDid ?? ("refused" in grant ? void 0 : grant.device.did);
+          await withTimeout(storage.purge({ identity, space: session.space, prefix, ...sessionDeviceDid ? { sessionDeviceDid } : {} }));
+          await pending.update((s) => clearPrefix(s, prefix));
+          replicas.delete(prefix);
+          inProcessProof.delete(prefix);
+          report.purged.push(prefix);
+          emit({ type: "replication.state", space: session.space, replica: prefix, state: "purged" });
+        } catch (error) {
+          const code = errorCode(error);
+          report.failed.push({ prefix, code });
+          emit({ type: "replication.state", space: session.space, replica: prefix, state: "purge_failed", code });
+        }
+      });
+      await Promise.all(jobs);
+      return report;
+    }).finally(() => {
+      purgeInProgress = false;
+    });
+  }
+  async function close() {
+    var _a;
+    if (isClosed) return;
+    isClosed = true;
+    const hasStatusInspections = statusInspections.size > 0;
+    const statusDrain = cancelStatusInspections();
+    for (const [prefix, state] of replicas) {
+      state.timer?.();
+      state.timer = void 0;
+      state.mintAbort?.abort();
+      state.syncContext && ((_a = state.syncContext).abortCause ?? (_a.abortCause = "close"));
+      state.abort?.abort();
+      emit({ type: "replication.state", space: session.space, replica: prefix, state: "closed" });
+    }
+    const drain = Promise.all([
+      ...[...replicas.values()].map(async (state) => {
+        await state.opening?.catch(() => void 0);
+        await state.sync?.catch(() => void 0);
+        await state.handle?.close().catch(() => void 0);
+      }),
+      ...hasStatusInspections ? [statusDrain] : []
+    ]);
+    let cancel = () => {
+    };
+    let drained = false;
+    void drain.then(
+      () => {
+        drained = true;
+        cancel();
+      },
+      () => {
+        drained = true;
+        cancel();
+      }
+    );
+    const timeout = new Promise((resolve) => {
+      queueMicrotask(() => {
+        if (!drained) cancel = scheduler.setTimeout(resolve, CLOSE_TIMEOUT_MS);
+      });
+    });
+    try {
+      await Promise.race([drain, timeout]);
+    } finally {
+      cancel();
+    }
+  }
+  return { get, list, write, observeNetworkRequested, 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;
+}
+function abortedResult(signal) {
+  const code = cancellationCode(signal);
+  return err(serviceError(code, code === ErrorCodes.TIMEOUT ? "KV request timed out" : "KV request was aborted", "kv"));
+}
+
+// src/kv/replication/memoryPendingStore.ts
+function createMemoryPendingStore(identity) {
+  const canonical = canonicalReplicationIdentity(identity);
+  const key = replicationIdentityKey(canonical);
+  let state = emptyPendingState(canonical);
+  let tail = Promise.resolve();
+  return {
+    identity: canonical,
+    durable: false,
+    async read() {
+      return structuredClone(state);
+    },
+    async update(mutate) {
+      let resolve;
+      let reject;
+      const result = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      const operation = tail.then(() => {
+        try {
+          if (replicationIdentityKey(state.identity) !== key) throw Object.assign(new Error("Pending-store identity mismatch"), { code: "STORAGE_ERROR" });
+          const next = structuredClone(state);
+          const value = mutate(next);
+          state = next;
+          resolve(value);
+        } catch (error) {
+          reject(error);
+        }
+      });
+      tail = operation.then(() => void 0, () => void 0);
+      return result;
+    }
+  };
+}
+export {
+  CLEAR_PENDING_WARNING,
+  canonicalReplicationIdentity,
+  createKVReplication,
+  createMemoryPendingStore,
+  kvPrefixCovers,
+  replicationIdentityKey,
+  requiresSecretsOptIn
+};
+//# sourceMappingURL=index.js.map