@korajs/server 1.0.0-beta.13 → 1.0.0-beta.14

package/dist/index.js

@@ -17,7 +17,72 @@ import {
   judgeSequenceHolders,
   reportLegacyPair,
   validateIngestedOperation
-} from "./chunk-IRRXJ7YN.js";
+} from "./chunk-UKWG5T6J.js";
+
+// src/diagnostics/json-string-values.ts
+import { KoraError } from "@korajs/core";
+var InvalidDiagnosticOptionsError = class extends KoraError {
+  constructor(option, value) {
+    super(
+      `findJsonStringValues: ${option} must be a ${option === "pageSize" ? "positive" : "non-negative"} integer, got ${String(value)}.`,
+      "INVALID_DIAGNOSTIC_OPTIONS",
+      { option, value }
+    );
+    this.name = "InvalidDiagnosticOptionsError";
+  }
+};
+async function findJsonStringValues(store, options = {}) {
+  const schema = store.getSchema();
+  if (!schema) return [];
+  const sampleSize = options.sampleSize ?? 10;
+  const pageSize = options.pageSize ?? 1e3;
+  if (!Number.isInteger(pageSize) || pageSize < 1) {
+    throw new InvalidDiagnosticOptionsError("pageSize", pageSize);
+  }
+  if (!Number.isInteger(sampleSize) || sampleSize < 0) {
+    throw new InvalidDiagnosticOptionsError("sampleSize", sampleSize);
+  }
+  const reports = [];
+  for (const [collection, definition] of Object.entries(schema.collections)) {
+    const fields = Object.entries(definition.fields).filter(([, descriptor]) => descriptor.kind === "json" || descriptor.kind === "object").map(([name]) => name);
+    if (fields.length === 0) continue;
+    const found = /* @__PURE__ */ new Map();
+    for (let offset = 0; ; offset += pageSize) {
+      const rows = await store.queryCollection(collection, {
+        orderBy: "id",
+        limit: pageSize,
+        offset
+      });
+      for (const row of rows) {
+        for (const field of fields) {
+          if (!isEncodedJson(row[field])) continue;
+          let report = found.get(field);
+          if (!report) {
+            report = { collection, field, count: 0, sampleIds: [] };
+            found.set(field, report);
+          }
+          report.count += 1;
+          if (report.sampleIds.length < sampleSize) report.sampleIds.push(String(row.id));
+        }
+      }
+      if (rows.length < pageSize) break;
+    }
+    reports.push(...found.values());
+  }
+  return reports;
+}
+function isEncodedJson(value) {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  const first = trimmed[0];
+  if (first !== "{" && first !== "[" && first !== '"') return false;
+  try {
+    JSON.parse(trimmed);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/logging/structured-logger.ts
 function defaultJsonSerializer(entry) {
@@ -85,7 +150,7 @@ function isRetriableRejection(code) {
 import { HybridLogicalClock as HybridLogicalClock2, assertOperationTransformCoverage } from "@korajs/core";
 
 // src/scopes/server-scope-filter.ts
-import { KoraError as KoraError2 } from "@korajs/core";
+import { KoraError as KoraError3 } from "@korajs/core";
 import {
   buildScopeSnapshot,
   matchesScopePredicate,
@@ -93,8 +158,8 @@ import {
 } from "@korajs/sync/internal";
 
 // src/scopes/scope-predicate-errors.ts
-import { KoraError } from "@korajs/core";
-var InvalidScopePredicateError = class extends KoraError {
+import { KoraError as KoraError2 } from "@korajs/core";
+var InvalidScopePredicateError = class extends KoraError2 {
   constructor(collection, field) {
     super(
       `Sync scope predicate for "${collection}.${field}" is undefined or null. A missing value would match every record without "${field}", so the grant is refused.`,
@@ -112,7 +177,7 @@ var InvalidScopePredicateError = class extends KoraError {
   collection;
   field;
 };
-var ScopePredicateLimitError = class extends KoraError {
+var ScopePredicateLimitError = class extends KoraError2 {
   constructor(message, context) {
     super(message, "SCOPE_PREDICATE_LIMIT", context);
     this.name = "ScopePredicateLimitError";
@@ -151,14 +216,18 @@ function normalizeScopeMap(scopes, maxValues = DEFAULT_MAX_SCOPE_PREDICATE_VALUE
             collection,
             field
           });
-        const unique = [...new Map(values.map((value) => [stableValueKey(value), value])).values()];
+        const unique = [...new Map(values.map((value) => [stableValueKey(value), value])).entries()];
         if (unique.length > maxValues)
           throw new ScopePredicateLimitError(
             `Scope predicate for ${collection}.${field} exceeds the ${maxValues}-value limit`,
             { collection, field, maxValues }
           );
         predicate[field] = {
-          $in: unique.sort((a, b) => stableValueKey(a).localeCompare(stableValueKey(b)))
+          // Frozen: matchers may cache a set of a large list (F17), which is only
+          // sound for a list that cannot change.
+          $in: Object.freeze(
+            unique.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, value]) => value)
+          )
         };
       } else predicate[field] = expected;
     }
@@ -229,7 +298,7 @@ function missingScopeFields(op, scopes) {
   const snapshot = buildScopeSnapshot(op);
   return Object.keys(collectionScope).filter((field) => !(field in snapshot));
 }
-var UplinkAuthorizationError = class extends KoraError2 {
+var UplinkAuthorizationError = class extends KoraError3 {
   constructor(rejectionCode, message, context) {
     super(message, rejectionCode, context);
     this.rejectionCode = rejectionCode;
@@ -506,7 +575,7 @@ import {
 import { mergeRichtext } from "@korajs/merge";
 
 // src/store/server-identity.ts
-import { KoraError as KoraError3, generateUUIDv7 } from "@korajs/core";
+import { KoraError as KoraError4, generateUUIDv7 } from "@korajs/core";
 var SERVER_NODE_PREFIX = "kora:server:";
 var RESERVED_NODE_PREFIX = "kora:";
 var SERVER_DEPLOYMENT_ID_KEY = "server_deployment_id";
@@ -519,7 +588,7 @@ var SERVER_REVOKED_AUTHORITY_KEY = "server_revoked_authoritative_node_ids";
 var SERVER_LEGACY_SCAN_KEY = "server_legacy_authority_scan_v1";
 var INSTANCE_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
 var SERVER_DERIVED_DOMAIN = "kora/server-derived/v1";
-var ServerIdentityError = class extends KoraError3 {
+var ServerIdentityError = class extends KoraError4 {
   constructor(message, context) {
     super(message, "INVALID_SERVER_IDENTITY", context);
     this.name = "ServerIdentityError";
@@ -1501,6 +1570,16 @@ var MemoryServerStore = class {
     }
     return owner === userId;
   }
+  async claimUnownedNode(nodeId, userId) {
+    this.assertOpen();
+    if (userId === RELEASED_NODE_OWNER) return false;
+    const owner = this.nodeOwners.get(nodeId);
+    if (owner === void 0 || owner === RELEASED_NODE_OWNER) {
+      this.nodeOwners.set(nodeId, userId);
+      return true;
+    }
+    return owner === userId;
+  }
   async getNodeClaimOwner(nodeId) {
     this.assertOpen();
     return this.nodeOwners.get(nodeId) ?? null;
@@ -1558,7 +1637,7 @@ var MemoryServerStore = class {
   }
   async exportBackup() {
     this.assertOpen();
-    const { buildServerBackup } = await import("./server-backup-WBIYHWYQ.js");
+    const { buildServerBackup } = await import("./server-backup-KITNPMZJ.js");
     return buildServerBackup(
       this.nodeId,
       this.operations,
@@ -1568,7 +1647,7 @@ var MemoryServerStore = class {
   }
   async importBackup(data, merge) {
     this.assertOpen();
-    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-WBIYHWYQ.js");
+    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-KITNPMZJ.js");
     const { operations: operations2, versionVector, keyRecords } = parseServerBackup(data);
     await restoreBackupKeyRecords(this, keyRecords, merge === true);
     if (merge) {
@@ -1721,7 +1800,7 @@ function keyRecordKey(owner, keyring) {
 // src/store/postgres-server-store.ts
 import {
   HybridLogicalClock as HybridLogicalClock4,
-  KoraError as KoraError4,
+  KoraError as KoraError5,
   assertOperationTransformCoverage as assertOperationTransformCoverage2,
   quoteIdent as quoteIdent2
 } from "@korajs/core";
@@ -2360,14 +2439,14 @@ var PostgresServerStore = class {
    * log has no transform path to `version` (RT-103): those operations would fold as
    * absent, silently erasing them from their records.
    */
-  async assertTransformCoverage(version, transforms) {
+  async assertTransformCoverage(version2, transforms) {
     if (transforms.length === 0) return;
     const rows = await this.db.execute(
       sql`SELECT DISTINCT schema_version AS v FROM operations`
     );
     assertOperationTransformCoverage2(
       rows.map((row) => Number(row.v)),
-      version,
+      version2,
       transforms,
       "Postgres server store"
     );
@@ -3054,7 +3133,7 @@ var PostgresServerStore = class {
   async exportBackup() {
     this.assertOpen();
     await this.ready;
-    const { buildServerBackup } = await import("./server-backup-WBIYHWYQ.js");
+    const { buildServerBackup } = await import("./server-backup-KITNPMZJ.js");
     const rows = await this.db.select().from(pgOperations).orderBy(asc(pgOperations.deliverySeq));
     const operations2 = rows.map((row) => this.deserializeOperation(row));
     return buildServerBackup(
@@ -3067,7 +3146,7 @@ var PostgresServerStore = class {
   async importBackup(data, merge) {
     this.assertOpen();
     await this.ready;
-    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-WBIYHWYQ.js");
+    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-KITNPMZJ.js");
     const { operations: operations2, versionVector, keyRecords } = parseServerBackup(data);
     await restoreBackupKeyRecords(this, keyRecords, merge === true);
     if (merge) {
@@ -3215,6 +3294,21 @@ var PostgresServerStore = class {
     );
     return rows[0]?.user_id === userId;
   }
+  async claimUnownedNode(nodeId, userId) {
+    this.assertOpen();
+    await this.ready;
+    if (userId === RELEASED_NODE_OWNER) return false;
+    await this.db.execute(
+      sql`INSERT INTO node_claims (node_id, user_id, claimed_at)
+				VALUES (${nodeId}, ${userId}, ${Date.now()})
+				ON CONFLICT (node_id) DO UPDATE SET user_id = EXCLUDED.user_id, claimed_at = EXCLUDED.claimed_at
+				WHERE node_claims.user_id = ${RELEASED_NODE_OWNER}`
+    );
+    const rows = await this.db.execute(
+      sql`SELECT user_id FROM node_claims WHERE node_id = ${nodeId} LIMIT 1`
+    );
+    return rows[0]?.user_id === userId;
+  }
   async getNodeClaimOwner(nodeId) {
     this.assertOpen();
     await this.ready;
@@ -4199,7 +4293,7 @@ async function createPostgresServerStore(options) {
   }
   return store;
 }
-var ServerStoreUnavailableError = class extends KoraError4 {
+var ServerStoreUnavailableError = class extends KoraError5 {
   constructor(connectionString, cause) {
     const reason = cause instanceof Error ? cause.message : String(cause);
     super(
@@ -4256,7 +4350,9 @@ var POSTGRES_DRIVER_SPECIFIERS = [
 ];
 
 // src/store/sqlite-server-store.ts
+import { mkdirSync } from "fs";
 import { createRequire } from "module";
+import { dirname } from "path";
 import { assertOperationTransformCoverage as assertOperationTransformCoverage3, quoteIdent as quoteIdent3 } from "@korajs/core";
 import { planSqliteConstraintRelaxation } from "@korajs/core/internal";
 import { and as and2, asc as asc2, between as between2, count as count2, eq as eq2, gt as gt2, sql as sql2 } from "drizzle-orm";
@@ -4597,14 +4693,14 @@ var SqliteServerStore = class {
    * log has no transform path to `version` (RT-103): those operations would fold as
    * absent, silently erasing them from their records.
    */
-  assertTransformCoverage(version, transforms) {
+  assertTransformCoverage(version2, transforms) {
     if (transforms.length === 0) return;
     const rows = this.db.all(
       sql2`SELECT DISTINCT schema_version AS v FROM operations`
     );
     assertOperationTransformCoverage3(
       rows.map((row) => Number(row.v)),
-      version,
+      version2,
       transforms,
       "SQLite server store"
     );
@@ -5092,6 +5188,20 @@ var SqliteServerStore = class {
     );
     return rows[0]?.user_id === userId;
   }
+  async claimUnownedNode(nodeId, userId) {
+    this.assertOpen();
+    if (userId === RELEASED_NODE_OWNER) return false;
+    this.db.run(
+      sql2`INSERT INTO node_claims (node_id, user_id, claimed_at)
+				VALUES (${nodeId}, ${userId}, ${Date.now()})
+				ON CONFLICT (node_id) DO UPDATE SET user_id = excluded.user_id, claimed_at = excluded.claimed_at
+				WHERE node_claims.user_id = ${RELEASED_NODE_OWNER}`
+    );
+    const rows = this.db.all(
+      sql2`SELECT user_id FROM node_claims WHERE node_id = ${nodeId} LIMIT 1`
+    );
+    return rows[0]?.user_id === userId;
+  }
   async getNodeClaimOwner(nodeId) {
     this.assertOpen();
     const rows = this.db.all(
@@ -5181,7 +5291,7 @@ var SqliteServerStore = class {
   }
   async exportBackup() {
     this.assertOpen();
-    const { buildServerBackup } = await import("./server-backup-WBIYHWYQ.js");
+    const { buildServerBackup } = await import("./server-backup-KITNPMZJ.js");
     const rows = this.db.select().from(operations).orderBy(asc2(operations.deliverySeq)).all();
     const deserialized = rows.map((row) => this.deserializeOperation(row));
     const vv = this.getVersionVector();
@@ -5189,7 +5299,7 @@ var SqliteServerStore = class {
   }
   async importBackup(data, merge) {
     this.assertOpen();
-    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-WBIYHWYQ.js");
+    const { mergeBackupOperations, parseServerBackup, restoreBackupKeyRecords } = await import("./server-backup-KITNPMZJ.js");
     const { operations: ops, versionVector, keyRecords } = parseServerBackup(data);
     await restoreBackupKeyRecords(this, keyRecords, merge === true);
     if (merge) {
@@ -6094,6 +6204,7 @@ function createSqliteServerStore(options) {
   const Database = esmRequire("better-sqlite3");
   const { drizzle } = esmRequire("drizzle-orm/better-sqlite3");
   const filename = options.filename ?? ":memory:";
+  ensureDatabaseDirectory(filename);
   const sqlite = new Database(filename);
   sqlite.pragma("journal_mode = WAL");
   const db = drizzle(sqlite);
@@ -6103,6 +6214,10 @@ function createSqliteServerStore(options) {
     ...options.instanceId !== void 0 ? { instanceId: options.instanceId } : {}
   });
 }
+function ensureDatabaseDirectory(filename) {
+  if (filename === "" || filename === ":memory:" || filename.startsWith("file:")) return;
+  mkdirSync(dirname(filename), { recursive: true });
+}
 
 // src/transport/http-server-transport.ts
 import { SyncError } from "@korajs/core";
@@ -6475,8 +6590,11 @@ function chooseWinner(members, constraint) {
   }
   return sorted[0];
 }
+function groupKeys(constraint) {
+  return [.../* @__PURE__ */ new Set([...constraint.fields, ...Object.keys(constraint.where ?? {})])];
+}
 function groupWhere(constraint, row) {
-  const where = constraint.type === "capacity" ? { ...constraint.where } : {};
+  const where = { ...constraint.where ?? {} };
   for (const field of constraint.fields) {
     const value = row[field];
     if (value === null || value === void 0) return null;
@@ -6485,6 +6603,7 @@ function groupWhere(constraint, row) {
   return where;
 }
 async function undoConstrainedWrite(store, schema, collection, constraintIndex, constraint, loser, winner) {
+  const keys = groupKeys(constraint);
   const ops = await store.getRecordOperations?.(collection, loser.row.id) ?? [];
   const state = await store.getRecordFoldState?.(collection, loser.row.id);
   const newest = stampTimestamp(state?.u ?? null) ?? loser.key;
@@ -6495,12 +6614,14 @@ async function undoConstrainedWrite(store, schema, collection, constraintIndex,
     ops.filter((stored) => {
       if (HybridLogicalClock5.compare(stored.timestamp, loser.key) !== 0) return false;
       const op = operationSchemaView2(stored, schema.version, transforms);
-      return op !== null && op.data !== null && constraint.fields.some((field) => op.data !== null && field in op.data);
+      return op !== null && op.data !== null && keys.some((field) => op.data !== null && field in op.data);
     }).map((op) => op.id)
   );
   const without = foldRecord2(ops, schema, { exclude: losing, transforms }).state;
   const previous = without && isFoldStateLive2(without) ? materialize2(without) : null;
-  const collides = previous !== null && constraint.fields.every((field) => sameValue(previous[field], winner.row[field]));
+  const collides = previous !== null && constraint.fields.every((field) => sameValue(previous[field], winner.row[field])) && Object.entries(constraint.where ?? {}).every(
+    ([field, value]) => sameValue(previous[field], value)
+  );
   if (previous === null || collides) {
     return {
       parent,
@@ -6515,10 +6636,17 @@ async function undoConstrainedWrite(store, schema, collection, constraintIndex,
   }
   const data = {};
   const previousData = {};
-  for (const field of constraint.fields) {
+  for (const field of keys) {
+    if (sameValue(previous[field], loser.row[field])) continue;
     data[field] = previous[field] ?? null;
     previousData[field] = loser.row[field] ?? null;
   }
+  if (Object.keys(data).length === 0) {
+    for (const field of constraint.fields) {
+      data[field] = previous[field] ?? null;
+      previousData[field] = loser.row[field] ?? null;
+    }
+  }
   return {
     parent,
     rule,
@@ -6537,7 +6665,7 @@ async function uniqueAndCapacityCorrections(store, schema, op) {
   const definition = schema.collections[op.collection];
   if (!definition || op.type === "delete") return [];
   const crossRecord = definition.constraints.filter(
-    (constraint) => (constraint.type === "unique" || constraint.type === "capacity") && (op.type === "insert" || constraint.fields.some((field) => op.data !== null && field in op.data))
+    (constraint) => (constraint.type === "unique" || constraint.type === "capacity") && (op.type === "insert" || groupKeys(constraint).some((field) => op.data !== null && field in op.data))
   );
   if (crossRecord.length === 0 || !store.getRecordFieldVersions) return [];
   const row = await store.findRecord(op.collection, op.recordId);
@@ -6563,7 +6691,7 @@ async function uniqueAndCapacityCorrections(store, schema, op) {
       members.push({
         row: candidate,
         versions,
-        key: constrainedVersion(versions, constraint.fields)
+        key: constrainedVersion(versions, groupKeys(constraint))
       });
     }
     if (members.length < 2) continue;
@@ -7126,6 +7254,148 @@ var NoAuthProvider = class {
   }
 };
 
+// src/awareness/presence-records.ts
+var CACHE_TTL_MS = 1e3;
+var MAX_TRACKED_RECORDS = 1e4;
+var MAX_CONCURRENT_READS = 16;
+var PresenceRecords = class {
+  constructor(store, now = Date.now) {
+    this.store = store;
+    this.now = now;
+  }
+  store;
+  now;
+  clock = 0;
+  /** The clock value of each tracked record's last touch, oldest first. */
+  lastTouch = /* @__PURE__ */ new Map();
+  /** Touches forgotten to bound memory count as having happened at this clock. */
+  forgottenTouchesAt = 0;
+  inFlight = /* @__PURE__ */ new Map();
+  cache = /* @__PURE__ */ new Map();
+  running = 0;
+  waiting = [];
+  /**
+   * Record that writes to these records committed: reads that began before are no
+   * longer current. Null means any record may have changed.
+   *
+   * @param keys - Record keys from {@link presenceRecordKey}, or null for every record
+   */
+  touch(keys) {
+    this.clock += 1;
+    if (keys === null) {
+      this.forgottenTouchesAt = this.clock;
+      this.lastTouch.clear();
+      this.cache.clear();
+      return;
+    }
+    for (const key of keys) {
+      this.lastTouch.delete(key);
+      this.lastTouch.set(key, this.clock);
+      this.cache.delete(key);
+    }
+    this.forget(this.lastTouch, (value) => {
+      this.forgottenTouchesAt = Math.max(this.forgottenTouchesAt, value);
+    });
+  }
+  /**
+   * True when a write touched the record after a read that began at `asOf`.
+   *
+   * @param key - Record key from {@link presenceRecordKey}
+   * @param asOf - The read's {@link PresenceRecordRead.asOf}
+   */
+  touchedSince(key, asOf) {
+    return (this.lastTouch.get(key) ?? this.forgottenTouchesAt) > asOf;
+  }
+  /**
+   * A current read of the record that is still fresh enough to reuse, without a store
+   * read; undefined when the record must be read.
+   *
+   * @param collection - The record's collection
+   * @param recordId - The record's id
+   */
+  peek(collection, recordId) {
+    const key = presenceRecordKey(collection, recordId);
+    const cached = this.cache.get(key);
+    if (!cached) return void 0;
+    if (this.now() - cached.atMs >= CACHE_TTL_MS || this.touchedSince(key, cached.startedAt)) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    return { stored: cached.stored, asOf: cached.startedAt };
+  }
+  /**
+   * Read the record from the store, joining a read of it already running when no
+   * write touched the record since that read began. Rejects when the store read fails.
+   *
+   * @param collection - The record's collection
+   * @param recordId - The record's id
+   */
+  async read(collection, recordId) {
+    const key = presenceRecordKey(collection, recordId);
+    let entry = this.inFlight.get(key);
+    if (!entry || this.touchedSince(key, entry.startedAt)) {
+      const startedAt = this.clock;
+      const created = {
+        startedAt,
+        promise: this.readStore(collection, recordId)
+      };
+      entry = created;
+      this.inFlight.set(key, created);
+      void created.promise.then(
+        (stored2) => {
+          if (this.inFlight.get(key) === created) this.inFlight.delete(key);
+          if (this.touchedSince(key, startedAt)) return;
+          this.cache.delete(key);
+          this.cache.set(key, { stored: stored2, startedAt, atMs: this.now() });
+          this.forget(this.cache, () => {
+          });
+        },
+        () => {
+          if (this.inFlight.get(key) === created) this.inFlight.delete(key);
+        }
+      );
+    }
+    const stored = await entry.promise;
+    return { stored, asOf: entry.startedAt };
+  }
+  /** Forget every read and touch (the server stopped). */
+  clear() {
+    this.touch(null);
+    this.inFlight.clear();
+  }
+  async readStore(collection, recordId) {
+    if (this.running < MAX_CONCURRENT_READS) {
+      this.running += 1;
+    } else {
+      await new Promise((resolve2) => this.waiting.push(resolve2));
+    }
+    try {
+      const rows = await this.store.queryCollection(collection, {
+        where: { id: recordId },
+        includeDeleted: true,
+        limit: 1
+      });
+      return rows[0] ?? null;
+    } finally {
+      const next = this.waiting.shift();
+      if (next) next();
+      else this.running -= 1;
+    }
+  }
+  forget(map, onForget) {
+    while (map.size > MAX_TRACKED_RECORDS) {
+      const oldest = map.keys().next();
+      if (oldest.done) return;
+      const value = map.get(oldest.value);
+      map.delete(oldest.value);
+      if (value !== void 0) onForget(value);
+    }
+  }
+};
+function presenceRecordKey(collection, recordId) {
+  return `${collection}\0${recordId}`;
+}
+
 // src/encryption/key-record-service.ts
 import { generateUUIDv7 as generateUUIDv72 } from "@korajs/core";
 import {
@@ -7663,14 +7933,14 @@ function asRecord2(value) {
 
 // src/scopes/resolve-session-scopes.ts
 import {
-  KoraError as KoraError5,
+  KoraError as KoraError6,
   SCOPE_CLAIMS_KEY,
   getCollectionScopeBindings,
   getScopeClaims,
   hasSchemaSyncRules,
   isCollectionSyncScoped
 } from "@korajs/core";
-var ScopeRequiredError = class extends KoraError5 {
+var ScopeRequiredError = class extends KoraError6 {
   constructor(denied) {
     super(
       `Sync scope required: ${denied.map((d) => `"${d.collection}" needs ${d.missingKeys.map((k) => `"${k}"`).join(", ")}`).join("; ")}. The server could not derive these values from the verified token.`,
@@ -7831,11 +8101,11 @@ function isSameStoredOperation(upload, stored) {
   const b = contentKey(stored, storedVersion);
   return a !== null && a === b;
 }
-function contentKey(op, version) {
+function contentKey(op, version2) {
   let body;
   try {
     body = canonicalizeOperationBody(
-      version === 1 ? canonicalizeLegacyOperation2({ ...op, hashVersion: void 0 }) : op
+      version2 === 1 ? canonicalizeLegacyOperation2({ ...op, hashVersion: void 0 }) : op
     );
   } catch {
     return null;
@@ -7851,7 +8121,7 @@ function contentKey(op, version) {
     atomicOps,
     sealed: op.encrypted !== void 0
   };
-  if (version === 2) {
+  if (version2 === 2) {
     key.previousData = body.previousData;
     key.sequenceNumber = op.sequenceNumber;
     key.causalDeps = [...op.causalDeps].sort();
@@ -8071,24 +8341,24 @@ function revocationMatches(principal, filter) {
   return true;
 }
 var warnedUnscopedProviders = /* @__PURE__ */ new WeakSet();
-function warnIfMultiTenantWithoutScopes(auth, resolvedScopes, schema) {
-  if (!auth || auth instanceof NoAuthProvider) {
-    return;
-  }
-  if (resolvedScopes) {
-    return;
-  }
-  if (!schema || Object.keys(schema.collections).length === 0) {
-    return;
-  }
+function warnIfMultiTenantWithoutScopes(auth) {
   if (warnedUnscopedProviders.has(auth)) {
     return;
   }
   warnedUnscopedProviders.add(auth);
   console.warn(
-    "[kora] An authenticated session resolved to no sync scopes, so every user will sync every other user's data. Return per-user sync scopes from your auth provider (for example KoraAuthProvider's resolveScopes) to isolate tenants. Note: declaring sync rules in your schema is not enough on its own \u2014 the per-user values come from the auth provider. (This warning is expected for single-tenant apps where all authenticated users are meant to share the same data.)"
+    "[kora] An authenticated session resolved to no sync scopes: its grant restricts no collection, so every user will sync every other user's data. Return per-user sync scopes from your auth provider (for example KoraAuthProvider's resolveScopes or scopeValues) and declare schema sync rules that bind them, to isolate tenants. If all signed-in users are meant to share the same data, set unscopedSharing: 'allow' in the sync server options to silence this; 'refuse' turns it into a handshake refusal."
   );
 }
+function sharesEveryUsersData(auth, principal, downlink, schema) {
+  if (downlink === null) return false;
+  if (!auth || auth instanceof NoAuthProvider) return false;
+  if (!principal || principal.anonymous === true) return false;
+  if (!schema || Object.keys(schema.collections).length === 0) return false;
+  if (downlink === void 0) return true;
+  const collections = Object.values(downlink);
+  return collections.length > 0 && collections.every((predicate) => Object.keys(predicate).length === 0);
+}
 function stableStringify(value) {
   if (Array.isArray(value)) {
     return `[${value.map((item) => stableStringify(item)).join(",")}]`;
@@ -8100,10 +8370,16 @@ function stableStringify(value) {
   }
   return JSON.stringify(value);
 }
-function sameScopeMap(a, b) {
-  const normalize = (value) => value && typeof value === "object" ? normalizeScopeMap(value) : value;
+function sameNormalizedScopeMap(a, b) {
+  if (a === b) return true;
+  return stableStringify(a ?? null) === stableStringify(b ?? null);
+}
+function sameScopeMap(a, b, maxValues) {
+  const normalize = (value) => value && typeof value === "object" ? normalizeScopeMap(value, maxValues) : value;
   return stableStringify(normalize(a) ?? null) === stableStringify(normalize(b) ?? null);
 }
+var MAX_PRESENCE_LOOKUPS_PER_MINUTE = 1200;
+var MAX_PRESENCE_REREADS = 2;
 var DEFAULT_MAX_BLOB_CHUNK_BYTES = 1024 * 1024;
 var DEFAULT_MAX_BLOB_BYTES_PER_SESSION = 256 * 1024 * 1024;
 var ClientSession = class _ClientSession {
@@ -8127,6 +8403,8 @@ var ClientSession = class _ClientSession {
   /** A provisional anonymous claim awaiting the device's confirmation (RT-21). */
   pendingNodeClaim = null;
   allowLegacyAnonymousClaims;
+  deviceNodeHandover;
+  unscopedSharing;
   anonymousClaimTtlMs;
   isNodeLive;
   /** The credential presented at handshake, kept to re-validate the session (RT-18). */
@@ -8199,7 +8477,6 @@ var ClientSession = class _ClientSession {
    * `collection\u0000id`; null marks a record known to be absent. Only set while a
    * chunk is filtered.
    */
-  recordLookupCache = null;
   deliveryHighWaterBytes;
   handshakeTimeoutMs;
   handshakeTimer = null;
@@ -8250,6 +8527,15 @@ var ClientSession = class _ClientSession {
   maxOperationBytes;
   maxOpsPerMinute;
   maxOpsPerBatch;
+  maxScopePredicateValues;
+  /** {@link getScopePartitionKey}, cached for the scope map it was computed from. */
+  scopePartitionKeyCache = null;
+  /** Store reads for presence cursors (F16), per minute. */
+  presenceLookupLimiter = new SessionRateLimiter(MAX_PRESENCE_LOOKUPS_PER_MINUTE);
+  /** Reads the records presence cursors name (shared by the server's sessions). */
+  presenceRecords;
+  /** A {@link refreshScopes} request arrived during the handshake: re-check once streaming. */
+  scopeRefreshPending = false;
   rateLimiter;
   /** Separate budget for blob chunk requests (RT-24). */
   blobRateLimiter;
@@ -8302,6 +8588,7 @@ var ClientSession = class _ClientSession {
     this.operationTransforms = options.operationTransforms ?? [];
     this.onRelay = options.onRelay ?? null;
     this.onAwarenessUpdate = options.onAwarenessUpdate ?? null;
+    this.presenceRecords = options.presenceRecords ?? new PresenceRecords(options.store);
     this.onYjsDocUpdate = options.onYjsDocUpdate ?? null;
     this.onBlobChunkRequest = options.onBlobChunkRequest ?? null;
     this.onBlobChunkResponse = options.onBlobChunkResponse ?? null;
@@ -8328,10 +8615,13 @@ var ClientSession = class _ClientSession {
       options.blobRequestWindowMs ?? 6e4
     );
     this.maxOpsPerBatch = options.maxOpsPerBatch ?? DEFAULT_MAX_OPS_PER_BATCH;
+    this.maxScopePredicateValues = options.maxScopePredicateValues ?? DEFAULT_MAX_SCOPE_PREDICATE_VALUES;
     this.validateOperation = options.validateOperation ?? null;
     this.koraContext = options.koraContext ?? null;
     this.blobAccess = options.blobAccess ?? null;
     this.allowLegacyAnonymousClaims = options.allowLegacyAnonymousClaims ?? true;
+    this.deviceNodeHandover = options.deviceNodeHandover ?? true;
+    this.unscopedSharing = options.unscopedSharing ?? "warn";
     this.anonymousClaimTtlMs = options.anonymousClaimTtlMs ?? DEFAULT_ANONYMOUS_CLAIM_TTL_MS;
     this.isNodeLive = options.isNodeLive ?? null;
     this.deliveryHighWaterBytes = options.deliveryHighWaterBytes ?? DEFAULT_DELIVERY_HIGH_WATER_BYTES;
@@ -8731,6 +9021,44 @@ var ClientSession = class _ClientSession {
     this.terminate(expired ? "AUTH_EXPIRED" : "AUTH_REVOKED");
     return "terminated";
   }
+  /**
+   * Re-resolve this session's grant on request (`KoraSyncServer.refreshScopes`), for
+   * the user named. A streaming session whose principal is that user re-authenticates
+   * now and ends with a retriable `SCOPE_CHANGED` when its grant changed (or
+   * `AUTH_REVOKED` when the credential is no longer accepted). A session still in its
+   * handshake may have resolved its grant from membership read before the change, so
+   * it re-checks as soon as it reaches streaming; a session whose principal is not
+   * known yet does the same (the re-check is a no-op for a grant that did not change).
+   *
+   * @param userId - The user whose grant changed
+   * @returns The revalidation outcome, `'deferred'` when the check waits for the
+   *   handshake, or `'skipped'` for another user's (or a closed) session
+   */
+  async refreshScopes(userId) {
+    if (this.state === "closed") return "skipped";
+    const principal = this.principal;
+    if (principal && principal.userId !== userId) return "skipped";
+    if (!principal || this.state !== "streaming" && this.state !== "syncing") {
+      this.scopeRefreshPending = true;
+      return "deferred";
+    }
+    return this.revalidateCredential();
+  }
+  /** Run a re-check deferred by {@link refreshScopes} once the session streams. */
+  runDeferredScopeRefresh() {
+    if (!this.scopeRefreshPending) return;
+    this.scopeRefreshPending = false;
+    void this.revalidateCredential().then((outcome) => {
+      if (outcome !== "error") return;
+      this.logger?.log({
+        timestamp: Date.now(),
+        level: "warn",
+        event: "session.revalidation_failed",
+        sessionId: this.sessionId,
+        details: { reason: "deferred scope refresh" }
+      });
+    });
+  }
   /**
    * True when `context` (a fresh authentication of this session's principal)
    * resolves to download or upload scopes other than the ones this session holds.
@@ -8740,7 +9068,7 @@ var ClientSession = class _ClientSession {
     if (this.state !== "streaming" && this.state !== "syncing") return false;
     const resolution = this.computeSessionScopes(context, this.handshakeScope);
     if (!resolution.ok) return true;
-    return !sameScopeMap(resolution.downlink, this.authContext?.downlinkScopes) || !sameScopeMap(resolution.uplink, this.authContext?.uplinkScopes);
+    return !sameNormalizedScopeMap(resolution.downlink, this.authContext?.downlinkScopes) || !sameNormalizedScopeMap(resolution.uplink, this.authContext?.uplinkScopes);
   }
   /**
    * End this session because an admin released its node id (RT-5). Retriable: a
@@ -8883,18 +9211,35 @@ var ClientSession = class _ClientSession {
     const scopes = this.authContext?.downlinkScopes ?? this.authContext?.scopes;
     return recordMatchesScopes(collection, { ...storedRecord ?? {}, id: recordId }, scopes);
   }
-  /**
-   * A stable key for this session's download scope. Presence (awareness) is only
-   * relayed between sessions that share exactly the same key, so it never crosses a
-   * tenant boundary. Unscoped sessions share the key `"*"`.
-   */
   /** This session's download scope, or undefined when it is unscoped. */
   getDownlinkScopes() {
     return this.authContext?.downlinkScopes ?? this.authContext?.scopes;
   }
+  /**
+   * A stable key for this session's download scope: sessions with the same key see
+   * exactly the same data. Unscoped sessions share the key `"*"`. Cached per scope
+   * map, since a large `$in` grant makes the key costly and the relays read it often.
+   */
   getScopePartitionKey() {
     const scopes = this.authContext?.downlinkScopes ?? this.authContext?.scopes;
-    return scopes ? stableStringify(normalizeScopeMap(scopes)) : "*";
+    if (!scopes) return "*";
+    if (this.scopePartitionKeyCache?.scopes !== scopes) {
+      this.scopePartitionKeyCache = {
+        scopes,
+        key: stableStringify(normalizeScopeMap(scopes, this.maxScopePredicateValues))
+      };
+    }
+    return this.scopePartitionKeyCache.key;
+  }
+  /**
+   * Partition for presence without a cursor (a "who is online" state that names no
+   * record): only sessions with the same key see each other's. Signed-in sessions
+   * use their download scope key; every anonymous session is its own partition,
+   * because sessions holding the same anonymous grant are unrelated people.
+   */
+  getPresencePartitionKey() {
+    const key = this.getScopePartitionKey();
+    return this.principal?.anonymous === true ? `anonymous:${this.sessionId}|${key}` : key;
   }
   /**
    * Get the transport for this session.
@@ -8959,7 +9304,7 @@ var ClientSession = class _ClientSession {
       case "heartbeat":
         break;
       case "awareness-update":
-        this.handleAwarenessUpdate(message);
+        await this.handleAwarenessUpdate(message);
         break;
       case "yjs-doc-update":
         await this.handleYjsDocUpdate(message);
@@ -9135,10 +9480,15 @@ var ClientSession = class _ClientSession {
     if (!store.getNodeClaimOwner || !store.replaceNodeClaim) return { ok: false };
     const current = await store.getNodeClaimOwner(nodeId);
     if (current === null) {
-      if (!this.allowLegacyAnonymousClaims || !store.releaseNodeClaim) return { ok: false };
+      if (!this.allowLegacyAnonymousClaims) return { ok: false };
       if (this.isNodeLive?.(nodeId, this.sessionId) === true) return { ok: false };
-      if (!await store.releaseNodeClaim(nodeId)) return { ok: false };
-      if (!await store.claimNode(nodeId, owner)) return { ok: false };
+      if (store.claimUnownedNode) {
+        if (!await store.claimUnownedNode(nodeId, owner)) return { ok: false };
+      } else {
+        if (!store.releaseNodeClaim) return { ok: false };
+        if (!await store.releaseNodeClaim(nodeId)) return { ok: false };
+        if (!await store.claimNode(nodeId, owner)) return { ok: false };
+      }
       this.warnLegacyAnonymousClaim(nodeId);
       return issued;
     }
@@ -9160,6 +9510,68 @@ var ClientSession = class _ClientSession {
     if (legacy) this.warnLegacyAnonymousClaim(nodeId);
     return issued;
   }
+  /**
+   * Automatic device handover after an upgrade from beta.12 (F1). A node with
+   * history but no owner (written before node claims existed) or released by an
+   * admin is claimed for the signed-in user when the node id IS the device id the
+   * auth provider verified for this credential (`metadata.deviceId`; the built-in
+   * provider takes it from the token's `dev` claim, which names a device registered
+   * to that user). `@korajs/auth` clients use that device id as their node id and
+   * cannot change it, so without this they stay refused until an operator binds the
+   * node. The claim is one atomic store step; a node another principal owns is never
+   * taken, and another user presenting the node id is still refused.
+   *
+   * The claim decides ownership from now on only. History written under the node on
+   * beta.12 may include operations another user forged (beta.12 did not verify node
+   * ids); the operation log integrity scan is the tool for auditing it.
+   */
+  async handOverDeviceNode(nodeId, context) {
+    if (!this.deviceNodeHandover || context.anonymous === true) return false;
+    if (!this.store.claimUnownedNode) return false;
+    const deviceId = context.metadata?.deviceId;
+    if (typeof deviceId !== "string" || deviceId.length === 0 || deviceId !== nodeId) return false;
+    const previousOwner = await this.store.getNodeClaimOwner?.(nodeId) ?? null;
+    if (previousOwner !== null && previousOwner !== RELEASED_NODE_OWNER) return false;
+    if (!await this.store.claimUnownedNode(nodeId, context.userId)) return false;
+    this.logger?.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "node_claim.handover",
+      sessionId: this.sessionId,
+      nodeId,
+      details: {
+        userId: context.userId,
+        previousOwner: previousOwner === null ? "none (pre-claims history)" : "released",
+        message: "A signed-in device took over its own node id, which had history but no owner (a database upgraded from beta.12, or a node an administrator released). The node id equals the device id the auth provider verified for this user."
+      }
+    });
+    return true;
+  }
+  /**
+   * The download grant the server itself gives this session, before the client's
+   * handshake scope narrows it (F4). A client may narrow its own view, but that does
+   * not isolate tenants: another client of the same user set can ask for everything.
+   * `null` when the grant cannot be resolved here (the handshake already refused or
+   * accepted it on the full path); then nothing is judged.
+   */
+  grantWithoutHandshakeNarrowing(downlinkAuthScopes, authenticated) {
+    try {
+      return resolveSessionScopes(this.store.getSchema(), {
+        handshakeScope: void 0,
+        authScopes: downlinkAuthScopes,
+        authenticated,
+        onUnresolved: "deny"
+      });
+    } catch {
+      return null;
+    }
+  }
+  /** Who holds a refused node id, as `NODE_ID_CLAIMED` reports it (F9). */
+  async nodeOwnershipOf(nodeId) {
+    if (!this.store.getNodeClaimOwner) return void 0;
+    const owner = await this.store.getNodeClaimOwner(nodeId);
+    return owner === null || owner === RELEASED_NODE_OWNER ? "unowned" : "other-principal";
+  }
   /** The deprecation warning for an anonymous device adopted under a legacy claim (RT-21, RT-91). */
   warnLegacyAnonymousClaim(nodeId) {
     this.logger?.log({
@@ -9169,7 +9581,7 @@ var ClientSession = class _ClientSession {
       sessionId: this.sessionId,
       nodeId,
       details: {
-        message: "An anonymous device re-claimed a node id under a legacy claim (no confirmed node token, or history from before node claims). Upgrade the client; allowLegacyAnonymousClaims will default to false in the next release."
+        message: "An anonymous device re-claimed a node id under a legacy claim (no confirmed node token, or history from before node claims). Upgrade the client; allowLegacyAnonymousClaims will default to false in a later release, announced in its release notes."
       }
     });
   }
@@ -9313,14 +9725,19 @@ var ClientSession = class _ClientSession {
         } else {
           this.nodeOwnerKey = context.userId;
           claimed = await this.store.claimNode(msg.nodeId, context.userId);
+          if (!claimed) claimed = await this.handOverDeviceNode(msg.nodeId, context);
         }
         if (!claimed) {
           this.issuedNodeToken = null;
-          this.sendError(
-            "NODE_ID_CLAIMED",
-            `Node id "${msg.nodeId}" belongs to another principal, or has operation history with no recorded owner (an administrator can release it with KoraSyncServer.releaseNodeClaim). Use a fresh node id per signed-in user.`,
-            false
-          );
+          const nodeOwnership = context.anonymous === true ? void 0 : await this.nodeOwnershipOf(msg.nodeId);
+          this.sendToClient({
+            type: "error",
+            messageId: generateUUIDv73(),
+            code: "NODE_ID_CLAIMED",
+            message: `Node id "${msg.nodeId}" belongs to another principal, or has operation history with no recorded owner (an administrator can release it with KoraSyncServer.releaseNodeClaim). Use a fresh node id per signed-in user.`,
+            retriable: false,
+            ...nodeOwnership ? { nodeOwnership } : {}
+          });
           this.close("node id claimed by another user");
           return;
         }
@@ -9386,11 +9803,23 @@ var ClientSession = class _ClientSession {
       } = this.authContext;
       this.authContext = rest;
     }
-    warnIfMultiTenantWithoutScopes(
+    if (this.unscopedSharing !== "allow" && this.auth && sharesEveryUsersData(
       this.auth,
-      authenticated ? downlinkAuthScopes : resolvedDownlinkScopes,
+      this.principal,
+      this.grantWithoutHandshakeNarrowing(downlinkAuthScopes, authenticated),
       this.store.getSchema()
-    );
+    )) {
+      if (this.unscopedSharing === "refuse") {
+        this.sendError(
+          "UNSCOPED_SHARING_REFUSED",
+          "This server refuses signed-in sessions whose grant restricts no collection (unscopedSharing: 'refuse'). Return per-user sync scopes from the auth provider.",
+          false
+        );
+        this.close("unscoped sharing refused");
+        return;
+      }
+      warnIfMultiTenantWithoutScopes(this.auth);
+    }
     if (msg.syncQueries && msg.syncQueries.length > 0) {
       this.syncQuerySubsets = dedupeQuerySubsets(msg.syncQueries);
     } else {
@@ -9398,7 +9827,7 @@ var ClientSession = class _ClientSession {
     }
     this.resumeDeltaCursor = msg.deltaCursor ? decodeDeltaCursor(msg.deltaCursor) : null;
     this.clientDeliveryWatermark = msg.lastDeliverySequence ?? null;
-    if (this.clientDeliveryWatermark !== null && !sameScopeMap(msg.syncScope, this.authContext?.downlinkScopes)) {
+    if (this.clientDeliveryWatermark !== null && !sameScopeMap(msg.syncScope, this.authContext?.downlinkScopes, this.maxScopePredicateValues)) {
       const acceptedWatermark = msg.acceptedScopeWatermark;
       const resumable = typeof msg.acceptedScopeKey === "string" && typeof acceptedWatermark === "number" && Number.isSafeInteger(acceptedWatermark) && acceptedWatermark >= 0 && msg.acceptedScopeKey === scopeViewKey(this.authContext?.downlinkScopes);
       this.clientDeliveryWatermark = resumable ? acceptedWatermark : 0;
@@ -9522,6 +9951,7 @@ var ClientSession = class _ClientSession {
     }
     this.onReady?.(this.sessionId);
     if (heartbeat) this.startAppHeartbeat();
+    this.runDeferredScopeRefresh();
     if (this.takeOrphanedRelays && this.clientNodeId) {
       const buffered = this.takeOrphanedRelays(this.clientNodeId);
       if (buffered.length > 0) {
@@ -9628,8 +10058,8 @@ var ClientSession = class _ClientSession {
       };
     }
     try {
-      const downlink = rawDownlink ? normalizeScopeMap(rawDownlink) : directionalScopesConfigured ? {} : void 0;
-      const uplink = rawUplink ? normalizeScopeMap(rawUplink) : directionalScopesConfigured ? {} : void 0;
+      const downlink = rawDownlink ? normalizeScopeMap(rawDownlink, this.maxScopePredicateValues) : directionalScopesConfigured ? {} : void 0;
+      const uplink = rawUplink !== void 0 && rawUplink === rawDownlink ? downlink : rawUplink ? normalizeScopeMap(rawUplink, this.maxScopePredicateValues) : directionalScopesConfigured ? {} : void 0;
       return { ok: true, downlink, uplink, downlinkAuthScopes, authenticated };
     } catch (error) {
       return {
@@ -10190,7 +10620,7 @@ var ClientSession = class _ClientSession {
    * payloads have no envelope binding.
    */
   warnLegacyProtocol(nodeId) {
-    const message = `Client node "${nodeId}" speaks sync protocol ${String(this.clientProtocolVersion)}; this server speaks ${String(SYNC_PROTOCOL_VERSION)}. Protocol 1 clients (Kora <= beta.12) are accepted in beta.13 only and will be refused by the next release. Upgrade the client.`;
+    const message = `Client node "${nodeId}" speaks sync protocol ${String(this.clientProtocolVersion)}; this server speaks ${String(SYNC_PROTOCOL_VERSION)}. Protocol 1 clients (Kora <= beta.12) are deprecated and will be refused by a later release, announced in its release notes. Upgrade the client.`;
     this.logger?.log({
       timestamp: Date.now(),
       level: "warn",
@@ -10381,26 +10811,22 @@ var ClientSession = class _ClientSession {
         !(clientNodeId !== null && delivered.operation.nodeId === clientNodeId && delivered.deliverySequence > this.ownOperationsIncludedThrough)
       )
     );
-    this.recordLookupCache = await this.prefetchRecordsFor(candidates);
-    try {
-      for (const delivered of candidates) {
-        const snapshot = delivered.scopeSnapshot ?? null;
-        if (await this.operationVisibleToClient(delivered.operation, snapshot)) {
-          const entry = await this.scopeEntryFor(delivered.operation, snapshot);
-          if (entry) {
-            deliverable.push({
-              operation: entry,
-              deliverySequence: delivered.deliverySequence,
-              scopeEntry: true
-            });
-          }
-          deliverable.push(delivered);
-        } else if (await this.scopeRetractionFor(delivered.operation, snapshot)) {
-          deliverable.push({ ...delivered, retraction: true });
+    const rows = await this.prefetchRecordsFor(candidates);
+    for (const delivered of candidates) {
+      const snapshot = delivered.scopeSnapshot ?? null;
+      if (await this.operationVisibleToClient(delivered.operation, snapshot, rows)) {
+        const entry = await this.scopeEntryFor(delivered.operation, snapshot, rows);
+        if (entry) {
+          deliverable.push({
+            operation: entry,
+            deliverySequence: delivered.deliverySequence,
+            scopeEntry: true
+          });
         }
+        deliverable.push(delivered);
+      } else if (await this.scopeRetractionFor(delivered.operation, snapshot, rows)) {
+        deliverable.push({ ...delivered, retraction: true });
       }
-    } finally {
-      this.recordLookupCache = null;
     }
     return deliverable;
   }
@@ -10485,7 +10911,7 @@ var ClientSession = class _ClientSession {
    * row. Operations without a snapshot (legacy rows, custom stores) fall back to the
    * current row plus `op.data`.
    */
-  async operationVisibleToClient(stored, snapshot = null) {
+  async operationVisibleToClient(stored, snapshot = null, rows = null) {
     const judged = this.schemaView(stored);
     const op = judged.ok ? judged.op : stored;
     const scopes = this.authContext?.downlinkScopes ?? this.authContext?.scopes;
@@ -10494,18 +10920,18 @@ var ClientSession = class _ClientSession {
       let current;
       let post = snapshot.post;
       if (snapshotLacksScopeFields(op.collection, { pre: null, post }, scopes)) {
-        current = await this.lookupRecordFields(op.collection, op.recordId);
+        current = await this.lookupRecordFields(op.collection, op.recordId, rows);
         post = snapshotValuesWithFallback(op.collection, post, scopes, current);
       }
       if (!post || !recordMatchesScopes(op.collection, { ...post, id: op.recordId }, scopes)) {
         return false;
       }
       if (subsets.length === 0) return true;
-      current ??= await this.lookupRecordFields(op.collection, op.recordId);
+      current ??= await this.lookupRecordFields(op.collection, op.recordId, rows);
       return operationMatchesQuerySubsets(op, subsets, current);
     }
     const needsBackfill = missingScopeFields(op, scopes).length > 0 || subsets !== void 0 && subsets.length > 0;
-    const fullRecord = needsBackfill ? await this.lookupRecordFields(op.collection, op.recordId) : void 0;
+    const fullRecord = needsBackfill ? await this.lookupRecordFields(op.collection, op.recordId, rows) : void 0;
     if (!operationMatchesScopes(op, scopes, fullRecord)) {
       return false;
     }
@@ -10731,11 +11157,11 @@ var ClientSession = class _ClientSession {
    * operation without a snapshot never produces a retraction (fail quiet: the
    * client keeps what it already had, and no other tenant's record id leaks).
    */
-  async scopeRetractionFor(op, snapshot = null) {
+  async scopeRetractionFor(op, snapshot = null, rows = null) {
     if (this.scopeExitPolicy !== "retract") return false;
     const scopes = this.authContext?.downlinkScopes ?? this.authContext?.scopes;
     if (!scopes || !snapshot) return false;
-    const current = snapshotLacksScopeFields(op.collection, snapshot, scopes) ? await this.lookupRecordFields(op.collection, op.recordId) : void 0;
+    const current = snapshotLacksScopeFields(op.collection, snapshot, scopes) ? await this.lookupRecordFields(op.collection, op.recordId, rows) : void 0;
     return snapshotExitsScopes(op, snapshot, scopes, current);
   }
   /**
@@ -10746,14 +11172,14 @@ var ClientSession = class _ClientSession {
    * deleted, gets no entry: its later operations retract or delete it anyway).
    * Operations without a snapshot (legacy rows, custom stores) never produce one.
    */
-  async scopeEntryFor(op, snapshot) {
+  async scopeEntryFor(op, snapshot, rows = null) {
     const scopes = this.authContext?.downlinkScopes ?? this.authContext?.scopes;
     const schema = this.store.getSchema();
     if (!scopes || !snapshot || !schema || op.type !== "update") return null;
     if (!snapshotLacksScopeFields(op.collection, snapshot, scopes) && !snapshotEntersScopes(op, snapshot, scopes)) {
       return null;
     }
-    const current = await this.lookupRecordFields(op.collection, op.recordId);
+    const current = await this.lookupRecordFields(op.collection, op.recordId, rows);
     if (!current || current._deleted === 1 || current._deleted === true) return null;
     if (!snapshotEntersScopes(op, snapshot, scopes, current)) return null;
     if (!recordMatchesScopes(op.collection, { ...current, id: op.recordId }, scopes)) return null;
@@ -10787,23 +11213,65 @@ var ClientSession = class _ClientSession {
    * query-subset backfill. Includes soft-deleted rows so a relayed delete (whose op
    * carries no fields) is still judged against the record's actual scope. Returns
    * undefined when the record cannot be read (never materialized, or no schema).
+   * `rows` are the rows one delivery pass prefetched for its own decisions.
    */
-  async lookupRecordFields(collection, recordId) {
-    const cached = this.recordLookupCache?.get(recordCacheKey(collection, recordId));
+  async lookupRecordFields(collection, recordId, rows = null) {
+    const cached = rows?.get(recordCacheKey(collection, recordId));
     if (cached !== void 0) return cached ?? void 0;
     try {
-      const rows = await this.store.queryCollection(collection, {
+      const rows2 = await this.store.queryCollection(collection, {
         where: { id: recordId },
         includeDeleted: true,
         limit: 1
       });
-      return rows[0];
+      return rows2[0];
     } catch {
       return void 0;
     }
   }
-  handleAwarenessUpdate(msg) {
-    this.onAwarenessUpdate?.(this.sessionId, msg);
+  /**
+   * Hand an awareness update to the server's relay, with the record its cursor
+   * names, read from the store, so the relay can deliver it only to sessions whose
+   * download scope contains that record (the rule of the Yjs doc channel).
+   * Awareness is purely ephemeral: nothing is persisted.
+   */
+  async handleAwarenessUpdate(msg) {
+    if (!this.onAwarenessUpdate) return;
+    const state = msg.states[String(msg.clientId)];
+    const cursor = state ? state.cursor : void 0;
+    if (cursor === void 0 || cursor === null) {
+      this.onAwarenessUpdate(this.sessionId, msg);
+      return;
+    }
+    const collection = cursor.collection;
+    const recordId = cursor.recordId;
+    if (typeof cursor !== "object" || typeof collection !== "string" || typeof recordId !== "string" || !isStorableIdentifier(collection) || !isStorableIdentifier(recordId)) {
+      this.onAwarenessUpdate(this.sessionId, msg, { invalid: true });
+      return;
+    }
+    let read = this.presenceRecords.peek(collection, recordId);
+    if (read === void 0) {
+      if (!this.presenceLookupLimiter.allow(1)) {
+        this.onAwarenessUpdate(this.sessionId, msg, { invalid: true });
+        return;
+      }
+      try {
+        read = await this.presenceRecords.read(collection, recordId);
+        const key = presenceRecordKey(collection, recordId);
+        for (let attempt = 0; attempt < MAX_PRESENCE_REREADS && this.presenceRecords.touchedSince(key, read.asOf); attempt++) {
+          read = await this.presenceRecords.read(collection, recordId);
+        }
+      } catch {
+        this.onAwarenessUpdate(this.sessionId, msg, { invalid: true });
+        return;
+      }
+    }
+    this.onAwarenessUpdate(this.sessionId, msg, {
+      collection,
+      recordId,
+      stored: read.stored,
+      asOf: read.asOf
+    });
   }
   /**
    * A Yjs doc-channel update is a write to a richtext field: the sender must be
@@ -10897,10 +11365,13 @@ function operationIdentifiersStorable(op) {
 }
 
 // src/server/kora-sync-server.ts
-import { KoraError as KoraError6, SyncError as SyncError4, generateUUIDv7 as generateUUIDv76, isBlobRef as isBlobRef2 } from "@korajs/core";
+import { KoraError as KoraError7, SyncError as SyncError4, generateUUIDv7 as generateUUIDv76, isBlobRef as isBlobRef2 } from "@korajs/core";
 import { SimpleEventEmitter } from "@korajs/core/internal";
 import { HTTP_SYNC_SESSION_HEADER, JsonMessageSerializer as JsonMessageSerializer2 } from "@korajs/sync";
 
+// package.json
+var version = "1.0.0-beta.14";
+
 // src/awareness/awareness-relay.ts
 import { generateUUIDv7 as generateUUIDv74 } from "@korajs/core";
 var DEFAULT_PARTITION = "*";
@@ -10911,29 +11382,36 @@ var AwarenessRelay = class {
    * calls for an already-registered session are ignored, so a client cannot rebind
    * itself to another client's id.
    *
+   * The new client is sent every existing state it may see (catch-up): a state with
+   * an audience when the audience admits the new session, otherwise a state of the
+   * same partition.
+   *
    * @param sessionId - Unique session identifier
    * @param clientId - Client-assigned awareness ID
    * @param transport - Transport for sending messages to this client
-   * @param partition - Presence partition (clients only see their own partition)
+   * @param partition - Presence partition for states relayed without an audience
    */
   addClient(sessionId, clientId, transport, partition = DEFAULT_PARTITION) {
     if (this.clients.has(sessionId)) return;
-    this.clients.set(sessionId, {
+    const joining = {
       sessionId,
       clientId,
       transport,
       state: null,
-      partition
-    });
+      partition,
+      audience: null,
+      deliveredTo: /* @__PURE__ */ new Set()
+    };
+    this.clients.set(sessionId, joining);
     const existingStates = {};
     let hasStates = false;
     for (const [, client] of this.clients) {
       if (client.sessionId === sessionId) continue;
-      if (client.partition !== partition) continue;
-      if (client.state) {
-        existingStates[String(client.clientId)] = client.state;
-        hasStates = true;
-      }
+      if (!client.state) continue;
+      if (!this.mayReceive(client, joining)) continue;
+      existingStates[String(client.clientId)] = client.state;
+      client.deliveredTo.add(sessionId);
+      hasStates = true;
     }
     if (hasStates) {
       const catchUpMsg = {
@@ -10955,7 +11433,7 @@ var AwarenessRelay = class {
     return this.clients.has(sessionId);
   }
   /**
-   * Remove a client and broadcast its removal to the remaining clients in its partition.
+   * Remove a client and send its removal to every client that was shown its state.
    *
    * @param sessionId - Session ID of the disconnecting client
    */
@@ -10963,17 +11441,26 @@ var AwarenessRelay = class {
     const client = this.clients.get(sessionId);
     if (!client) return;
     this.clients.delete(sessionId);
-    if (client.state === null) return;
-    const removalStates = {
-      [String(client.clientId)]: null
-    };
-    const msg = {
-      type: "awareness-update",
-      messageId: generateUUIDv74(),
-      clientId: client.clientId,
-      states: removalStates
-    };
-    this.broadcastExcept(sessionId, client.partition, msg);
+    for (const [, other] of this.clients) other.deliveredTo.delete(sessionId);
+    if (client.deliveredTo.size === 0) return;
+    const msg = this.removalMessage(client);
+    for (const targetId of client.deliveredTo) {
+      const target = this.clients.get(targetId);
+      if (target?.transport.isConnected()) target.transport.send(msg);
+    }
+    client.deliveredTo.clear();
+  }
+  /**
+   * True when {@link handleUpdate} would take this update: the session is registered,
+   * the update is stamped with its bound `clientId` and carries that client's entry.
+   *
+   * @param sessionId - Session ID of the sending client
+   * @param message - The awareness update message
+   */
+  accepts(sessionId, message) {
+    const sender = this.clients.get(sessionId);
+    if (!sender || message.clientId !== sender.clientId) return false;
+    return String(sender.clientId) in message.states;
   }
   /**
    * Handle an incoming awareness update from a registered client.
@@ -10981,12 +11468,17 @@ var AwarenessRelay = class {
    * Only the sender's own entry is accepted: the message must be stamped with the
    * sender's bound `clientId`, and only `states[clientId]` is stored and relayed.
    * Entries for other clients are dropped, so a sender cannot overwrite or remove
-   * anyone else's presence. The sanitized update reaches only the sender's partition.
+   * anyone else's presence.
+   *
+   * The state is sent to every other client the audience admits (without an
+   * audience: every client of the sender's partition). A client that was shown an
+   * earlier state of the sender but is not admitted now receives a removal.
    *
    * @param sessionId - Session ID of the sending client
    * @param message - The awareness update message
+   * @param audience - Who may see this state; omitted means the sender's partition
    */
-  handleUpdate(sessionId, message) {
+  handleUpdate(sessionId, message, audience) {
     const sender = this.clients.get(sessionId);
     if (!sender) return;
     if (message.clientId !== sender.clientId) return;
@@ -10994,13 +11486,66 @@ var AwarenessRelay = class {
     if (!(key in message.states)) return;
     const senderState = message.states[key] ?? null;
     sender.state = senderState;
+    sender.audience = audience ?? null;
     const sanitized = {
       type: "awareness-update",
       messageId: message.messageId,
       clientId: sender.clientId,
       states: { [key]: senderState }
     };
-    this.broadcastExcept(sessionId, sender.partition, sanitized);
+    let removal = null;
+    for (const [, client] of this.clients) {
+      if (client.sessionId === sessionId) continue;
+      const visible = senderState !== null && this.mayReceive(sender, client);
+      if (visible) {
+        if (!client.transport.isConnected()) continue;
+        client.transport.send(sanitized);
+        sender.deliveredTo.add(client.sessionId);
+      } else if (sender.deliveredTo.delete(client.sessionId)) {
+        if (!client.transport.isConnected()) continue;
+        removal ??= senderState === null ? sanitized : this.removalMessage(sender);
+        client.transport.send(removal);
+      }
+    }
+  }
+  /**
+   * Re-decide who may see a client's current state after the record its cursor names
+   * changed (F16): it moved into or out of a session's grant. Sessions that may no
+   * longer see the state get a removal; sessions that may see it now and were not
+   * shown it get the state. Later catch-ups use the new audience.
+   *
+   * @param sessionId - The client whose audience changed
+   * @param audience - The new audience
+   */
+  updateAudience(sessionId, audience) {
+    const sender = this.clients.get(sessionId);
+    if (!sender) return;
+    sender.audience = audience;
+    if (sender.state === null) return;
+    const key = String(sender.clientId);
+    let current = null;
+    let removal = null;
+    for (const [, client] of this.clients) {
+      if (client.sessionId === sessionId) continue;
+      const visible = this.mayReceive(sender, client);
+      const shown = sender.deliveredTo.has(client.sessionId);
+      if (visible && !shown) {
+        if (!client.transport.isConnected()) continue;
+        current ??= {
+          type: "awareness-update",
+          messageId: generateUUIDv74(),
+          clientId: sender.clientId,
+          states: { [key]: sender.state }
+        };
+        client.transport.send(current);
+        sender.deliveredTo.add(client.sessionId);
+      } else if (!visible && shown) {
+        sender.deliveredTo.delete(client.sessionId);
+        if (!client.transport.isConnected()) continue;
+        removal ??= this.removalMessage(sender);
+        client.transport.send(removal);
+      }
+    }
   }
   /**
    * Get the number of registered awareness clients.
@@ -11015,14 +11560,23 @@ var AwarenessRelay = class {
     this.clients.clear();
   }
   // --- Private ---
-  broadcastExcept(excludeSessionId, partition, message) {
-    for (const [, client] of this.clients) {
-      if (client.sessionId === excludeSessionId) continue;
-      if (client.partition !== partition) continue;
-      if (!client.transport.isConnected()) continue;
-      client.transport.send(message);
+  /** True when `target` may see `source`'s current state. Fails closed. */
+  mayReceive(source, target) {
+    if (source.audience === null) return source.partition === target.partition;
+    try {
+      return source.audience(target.sessionId);
+    } catch {
+      return false;
     }
   }
+  removalMessage(client) {
+    return {
+      type: "awareness-update",
+      messageId: generateUUIDv74(),
+      clientId: client.clientId,
+      states: { [String(client.clientId)]: null }
+    };
+  }
 };
 
 // src/diagnostics/server-metrics-collector.ts
@@ -11136,8 +11690,8 @@ var ServerMetricsCollector = class {
     this.errorCount++;
   }
   /** Set the schema version. */
-  setSchemaVersion(version) {
-    this.schemaVersion = version;
+  setSchemaVersion(version2) {
+    this.schemaVersion = version2;
   }
   /** Return a full snapshot of current metrics. */
   getSnapshot(totalOperations) {
@@ -11951,6 +12505,18 @@ var KoraSyncServer = class _KoraSyncServer {
   logger;
   metrics;
   awarenessRelay = new AwarenessRelay();
+  /** Reads the records presence cursors name, for every session (F16). */
+  presenceRecords;
+  /** The record each session's current presence cursor names (F16). */
+  presenceTargets = /* @__PURE__ */ new Map();
+  /** The sessions whose presence cursor names each record, by record key. */
+  presenceTargetsByKey = /* @__PURE__ */ new Map();
+  /**
+   * Audience re-decisions running, one per record: a write while one runs marks it
+   * dirty, so it reads again and the last decision applied is always from a read that
+   * began after the last write (never an older read finishing late).
+   */
+  presenceRefreshes = /* @__PURE__ */ new Map();
   yjsDocRelay = new YjsDocRelay();
   blobChunkRelay;
   /** Wrapped encryption key records (ENC-1, D4b), persisted in the server store. */
@@ -11963,8 +12529,11 @@ var KoraSyncServer = class _KoraSyncServer {
   /** Per-principal ingest budget per minute; 0 when disabled. */
   maxOpsPerMinutePerUser;
   allowLegacyAnonymousClaims;
+  deviceNodeHandover;
+  unscopedSharing;
   anonymousClaimTtlMs;
   maxOpsPerBatch;
+  maxScopePredicateValues;
   maxMessageBytes;
   heartbeatIntervalMs;
   appHeartbeatIntervalMs;
@@ -11996,9 +12565,10 @@ var KoraSyncServer = class _KoraSyncServer {
   /** Internal ClientSession id -> HTTP session id, for cleanup on close. */
   httpSessionIdBySession = /* @__PURE__ */ new Map();
   httpSessionIdleTimeoutMs;
-  // Informational value reported by getStatus(). Keep in sync with the
-  // @korajs/server package version on release; it is not used for protocol negotiation.
-  serverVersion = "1.0.0-beta.0";
+  // The @korajs/server package version, reported by getStatus() and /health so
+  // operators can tell which release is deployed. Read from package.json (inlined by
+  // the build), never hand-maintained. Not used for protocol negotiation.
+  serverVersion = version;
   wsServer = null;
   running = false;
   /**
@@ -12031,6 +12601,7 @@ var KoraSyncServer = class _KoraSyncServer {
   static ORPHANED_RELAY_TTL_MS = 5 * 6e4;
   constructor(config) {
     this.store = config.store;
+    this.presenceRecords = new PresenceRecords(config.store);
     const storeSchemaVersion = this.store.getSchema()?.version;
     if (config.schemaVersion !== void 0 && storeSchemaVersion !== void 0 && config.schemaVersion !== storeSchemaVersion) {
       throw new SyncError4("Sync schema version does not match the configured store schema.", {
@@ -12124,6 +12695,8 @@ var KoraSyncServer = class _KoraSyncServer {
     }
     this.maxOpsPerMinutePerUser = config.maxOpsPerMinutePerUser ?? (config.maxOpsPerMinute ?? DEFAULT_MAX_OPS_PER_MINUTE) * DEFAULT_USER_BUDGET_MULTIPLIER;
     this.allowLegacyAnonymousClaims = config.allowLegacyAnonymousClaims;
+    this.deviceNodeHandover = config.deviceNodeHandover;
+    this.unscopedSharing = config.unscopedSharing;
     this.anonymousClaimTtlMs = config.anonymousClaimTtlMs;
     if (config.maxOpsPerBatch !== void 0 && (!Number.isInteger(config.maxOpsPerBatch) || config.maxOpsPerBatch < 1)) {
       throw new SyncError4("maxOpsPerBatch must be a positive integer", {
@@ -12131,6 +12704,12 @@ var KoraSyncServer = class _KoraSyncServer {
       });
     }
     this.maxOpsPerBatch = config.maxOpsPerBatch;
+    if (config.maxScopePredicateValues !== void 0 && (!Number.isInteger(config.maxScopePredicateValues) || config.maxScopePredicateValues < 1)) {
+      throw new SyncError4("maxScopePredicateValues must be a positive integer", {
+        maxScopePredicateValues: config.maxScopePredicateValues
+      });
+    }
+    this.maxScopePredicateValues = config.maxScopePredicateValues;
     this.validateOperation = config.validateOperation;
     this.koraContext = createRouteContext(this, this.store);
     if (!this.emitter) {
@@ -12175,7 +12754,7 @@ var KoraSyncServer = class _KoraSyncServer {
    */
   terminateSessions(filter) {
     if (filter.userId === void 0 && filter.deviceId === void 0) {
-      throw new KoraError6(
+      throw new KoraError7(
         "terminateSessions needs a userId or a deviceId; refusing to end every session.",
         "INVALID_TERMINATE_FILTER",
         { fix: "Pass { userId } to end a user, or { userId, deviceId } to end one device." }
@@ -12313,6 +12892,65 @@ var KoraSyncServer = class _KoraSyncServer {
     });
     return run;
   }
+  /**
+   * Re-resolve one user's grant on every live session of that user now, instead of
+   * waiting for the next revalidation pass (`sessionRevalidationIntervalMs`). Call it
+   * after a membership change the auth provider's grant depends on: an invitation
+   * accepted, a collaborator removed, a role changed.
+   *
+   * Each of the user's sessions re-authenticates its credential with the provider. A
+   * session whose resolved download or upload scope changed ends with a retriable
+   * `SCOPE_CHANGED`; its client reconnects at once and receives the new grant. A
+   * narrowed grant applies the client's `scopeExit` policy at that handshake
+   * (`'retract'` hides the rows that left the scope), and the device's unsynced writes
+   * outside the new upload scope are refused. A session still in its handshake
+   * re-checks as soon as it is established, so a grant read before the change never
+   * outlives this call. Sessions whose grant did not change are kept.
+   *
+   * Only this process's sessions are refreshed. Other instances apply the change at
+   * their next revalidation pass, or call this too (for example from a pub/sub
+   * message).
+   *
+   * @param userId - The user whose grant changed (the auth provider's `userId`)
+   * @returns The number of sessions this call ended
+   *
+   * @example
+   * ```typescript
+   * await removeCollaborator(documentId, bobId)
+   * await server.refreshScopes(bobId)
+   * ```
+   */
+  async refreshScopes(userId) {
+    if (typeof userId !== "string" || userId.length === 0) {
+      throw new KoraError7(
+        "refreshScopes needs the user id whose grant changed.",
+        "INVALID_REFRESH_SCOPES_USER",
+        { fix: "Pass the userId your auth provider returns for that user." }
+      );
+    }
+    let terminated = 0;
+    for (const session of [...this.sessions.values()]) {
+      const outcome = await session.refreshScopes(userId);
+      if (outcome === "terminated") terminated++;
+      if (outcome === "error") {
+        this.logger.log({
+          timestamp: Date.now(),
+          level: "warn",
+          event: "session.revalidation_failed",
+          sessionId: session.getSessionId(),
+          details: { reason: "refreshScopes", userId }
+        });
+      }
+    }
+    this.logger.log({
+      timestamp: Date.now(),
+      level: "info",
+      event: "sessions.scopes_refreshed",
+      count: terminated,
+      details: { userId }
+    });
+    return terminated;
+  }
   /** Run {@link revalidateSessions} from the delivery poll tick once the interval elapsed. */
   maybeRevalidateSessions(now = Date.now()) {
     if (this.sessionRevalidationIntervalMs <= 0) return;
@@ -12418,13 +13056,17 @@ var KoraSyncServer = class _KoraSyncServer {
     const MAX_SCANNED = 1e3;
     if (to - from > MAX_SCANNED) {
       this.blobAccess.invalidate();
+      this.refreshPresence(null);
       return;
     }
     try {
       const delivered = await this.store.getOperationsAfterDelivery(from, MAX_SCANNED);
-      this.blobAccess.invalidate(collectionsOf(delivered.map((d) => d.operation)));
+      const operations2 = delivered.map((d) => d.operation);
+      this.blobAccess.invalidate(collectionsOf(operations2));
+      this.refreshPresence(operations2);
     } catch {
       this.blobAccess.invalidate();
+      this.refreshPresence(null);
     }
   }
   /**
@@ -12640,6 +13282,10 @@ var KoraSyncServer = class _KoraSyncServer {
     this.revocationUnsubscribe?.();
     this.revocationUnsubscribe = null;
     this.awarenessRelay.clear();
+    this.presenceTargets.clear();
+    this.presenceTargetsByKey.clear();
+    this.presenceRefreshes.clear();
+    this.presenceRecords.clear();
     this.yjsDocRelay.clear();
     this.blobChunkRelay.clear();
     for (const session of this.sessions.values()) {
@@ -12904,9 +13550,10 @@ var KoraSyncServer = class _KoraSyncServer {
       onRelay: (sourceSessionId, operations2) => {
         this.handleRelay(sourceSessionId, operations2);
       },
-      onAwarenessUpdate: (sourceSessionId, message) => {
-        this.handleAwarenessRelay(sourceSessionId, message);
+      onAwarenessUpdate: (sourceSessionId, message, cursorTarget) => {
+        this.handleAwarenessRelay(sourceSessionId, message, cursorTarget);
       },
+      presenceRecords: this.presenceRecords,
       onYjsDocUpdate: (sourceSessionId, message, storedRecord) => {
         this.handleYjsDocRelay(sourceSessionId, message, storedRecord);
       },
@@ -12939,8 +13586,11 @@ var KoraSyncServer = class _KoraSyncServer {
       ...this.maxOpsPerMinute !== void 0 ? { maxOpsPerMinute: this.maxOpsPerMinute } : {},
       ...this.blobLimits.maxRequestsPerMinute !== void 0 ? { maxBlobRequestsPerMinute: this.blobLimits.maxRequestsPerMinute } : {},
       ...this.maxOpsPerBatch !== void 0 ? { maxOpsPerBatch: this.maxOpsPerBatch } : {},
+      ...this.maxScopePredicateValues !== void 0 ? { maxScopePredicateValues: this.maxScopePredicateValues } : {},
       ...this.validateOperation ? { validateOperation: this.validateOperation, koraContext: this.koraContext } : {},
       blobAccess: this.blobAccess,
+      ...this.deviceNodeHandover !== void 0 ? { deviceNodeHandover: this.deviceNodeHandover } : {},
+      ...this.unscopedSharing !== void 0 ? { unscopedSharing: this.unscopedSharing } : {},
       ...this.allowLegacyAnonymousClaims !== void 0 ? { allowLegacyAnonymousClaims: this.allowLegacyAnonymousClaims } : {},
       ...this.anonymousClaimTtlMs !== void 0 ? { anonymousClaimTtlMs: this.anonymousClaimTtlMs } : {},
       isNodeLive: (nodeId, exceptSessionId) => this.isNodeLive(nodeId, exceptSessionId),
@@ -13010,6 +13660,7 @@ var KoraSyncServer = class _KoraSyncServer {
     const result = await applyServerOperation(this.store, op, void 0, options);
     if (result.result === "applied" && result.appliedOperations.length > 0) {
       this.blobAccess.invalidate(collectionsOf(result.appliedOperations));
+      this.refreshPresence(result.appliedOperations);
       for (const session of this.sessions.values()) {
         session.relayOperations(result.appliedOperations);
       }
@@ -13029,6 +13680,7 @@ var KoraSyncServer = class _KoraSyncServer {
       return;
     }
     this.blobAccess.invalidate(collectionsOf(operations2));
+    this.refreshPresence(operations2);
     for (const session of this.sessions.values()) {
       session.relayOperations(operations2);
     }
@@ -13125,6 +13777,7 @@ var KoraSyncServer = class _KoraSyncServer {
   }
   handleRelay(sourceSessionId, operations2) {
     this.blobAccess.invalidate(collectionsOf(operations2));
+    this.refreshPresence(operations2);
     const targetCount = this.sessions.size - 1;
     const byteSize = estimateOperationByteSize(operations2);
     this.metrics.recordSent(
@@ -13149,6 +13802,7 @@ var KoraSyncServer = class _KoraSyncServer {
   handleSessionClose(sessionId) {
     this.metrics.recordDisconnection(sessionId);
     this.awarenessRelay.removeClient(sessionId);
+    this.setPresenceTarget(sessionId, null);
     this.yjsDocRelay.removeClient(sessionId);
     this.blobChunkRelay.removeClient(sessionId);
     this.sessions.delete(sessionId);
@@ -13160,7 +13814,7 @@ var KoraSyncServer = class _KoraSyncServer {
       }
     }
   }
-  handleAwarenessRelay(sourceSessionId, message) {
+  handleAwarenessRelay(sourceSessionId, message, cursorTarget) {
     const session = this.sessions.get(sourceSessionId);
     if (!session || !session.isStreaming()) return;
     if (!this.awarenessRelay.hasClient(sourceSessionId)) {
@@ -13168,10 +13822,143 @@ var KoraSyncServer = class _KoraSyncServer {
         sourceSessionId,
         message.clientId,
         session.getTransport(),
-        session.getScopePartitionKey()
+        session.getPresencePartitionKey()
       );
     }
-    this.awarenessRelay.handleUpdate(sourceSessionId, message);
+    if (!this.awarenessRelay.accepts(sourceSessionId, message)) return;
+    let audience = this.awarenessAudience(session, cursorTarget);
+    if (cursorTarget !== void 0 && cursorTarget.invalid !== true) {
+      const key = presenceRecordKey(cursorTarget.collection, cursorTarget.recordId);
+      this.setPresenceTarget(sourceSessionId, {
+        collection: cursorTarget.collection,
+        recordId: cursorTarget.recordId,
+        key
+      });
+      if (cursorTarget.asOf !== void 0 && this.presenceRecords.touchedSince(key, cursorTarget.asOf)) {
+        audience = () => false;
+        this.schedulePresenceRefresh(key);
+      }
+    } else {
+      this.setPresenceTarget(sourceSessionId, null);
+    }
+    this.awarenessRelay.handleUpdate(sourceSessionId, message, audience);
+  }
+  /** Point a session's presence at a record (or at none), keeping the index in step. */
+  setPresenceTarget(sessionId, target) {
+    const previous = this.presenceTargets.get(sessionId);
+    if (previous) {
+      const sessions2 = this.presenceTargetsByKey.get(previous.key);
+      sessions2?.delete(sessionId);
+      if (sessions2?.size === 0) this.presenceTargetsByKey.delete(previous.key);
+    }
+    if (target === null) {
+      this.presenceTargets.delete(sessionId);
+      return;
+    }
+    this.presenceTargets.set(sessionId, target);
+    let sessions = this.presenceTargetsByKey.get(target.key);
+    if (!sessions) {
+      sessions = /* @__PURE__ */ new Set();
+      this.presenceTargetsByKey.set(target.key, sessions);
+    }
+    sessions.add(sessionId);
+  }
+  /**
+   * Records changed (`operations`, or anything when null): re-decide the audience of
+   * every presence cursor on one of them (F16). A record that moved out of a session's
+   * grant takes the presence on it out of that session, and one that moved in brings
+   * it, without waiting for the sender's next update; catch-ups use the new audience.
+   * Every write is noted first, so a presence read that began before it is never
+   * taken as current.
+   */
+  refreshPresence(operations2) {
+    if (operations2 === null) {
+      this.presenceRecords.touch(null);
+      for (const key of this.presenceTargetsByKey.keys()) this.schedulePresenceRefresh(key);
+      return;
+    }
+    const keys = new Set(operations2.map((op) => presenceRecordKey(op.collection, op.recordId)));
+    this.presenceRecords.touch(keys);
+    for (const key of keys) {
+      if (this.presenceTargetsByKey.has(key)) this.schedulePresenceRefresh(key);
+    }
+  }
+  /** Re-decide the presence on one record, coalesced with a re-decision already running. */
+  schedulePresenceRefresh(key) {
+    const running = this.presenceRefreshes.get(key);
+    if (running) {
+      running.dirty = true;
+      return;
+    }
+    const state = { dirty: true };
+    this.presenceRefreshes.set(key, state);
+    void this.runPresenceRefresh(key, state);
+  }
+  async runPresenceRefresh(key, state) {
+    let staleReads = 0;
+    try {
+      while (state.dirty) {
+        state.dirty = false;
+        const sessions = this.presenceTargetsByKey.get(key);
+        const first = sessions?.values().next();
+        const target = first && !first.done ? this.presenceTargets.get(first.value) : void 0;
+        if (!target) return;
+        let stored;
+        try {
+          const read = await this.presenceRecords.read(target.collection, target.recordId);
+          if (this.presenceRecords.touchedSince(key, read.asOf)) {
+            state.dirty = true;
+            if (staleReads < 2) {
+              staleReads += 1;
+              continue;
+            }
+            stored = void 0;
+          } else {
+            stored = read.stored;
+          }
+        } catch {
+          stored = void 0;
+        }
+        staleReads = 0;
+        for (const sessionId of this.presenceTargetsByKey.get(key) ?? []) {
+          const session = this.sessions.get(sessionId);
+          if (!session) continue;
+          this.awarenessRelay.updateAudience(
+            sessionId,
+            stored === void 0 ? () => false : this.awarenessAudience(session, {
+              collection: target.collection,
+              recordId: target.recordId,
+              stored
+            })
+          );
+        }
+      }
+    } finally {
+      if (this.presenceRefreshes.get(key) === state) this.presenceRefreshes.delete(key);
+    }
+  }
+  /**
+   * Who may see a presence state (F16). A state whose cursor names a record reaches
+   * exactly the sessions whose download scope contains that record, the rule of the
+   * Yjs doc channel, and only when the sender may read the record too: collaborators
+   * with different grants see each other on the documents they share, and nobody
+   * sees presence on a record outside their grant. A malformed cursor reaches
+   * nobody. A state without a cursor names no record: it reaches only sessions of
+   * the same presence partition (identical download scope; anonymous sessions are
+   * each their own partition).
+   */
+  awarenessAudience(source, cursorTarget) {
+    if (cursorTarget === void 0) {
+      const partition = source.getPresencePartitionKey();
+      return (targetSessionId) => {
+        const target = this.sessions.get(targetSessionId);
+        return target?.isStreaming() === true && target.getPresencePartitionKey() === partition;
+      };
+    }
+    if (cursorTarget.invalid === true) return () => false;
+    const { collection, recordId, stored } = cursorTarget;
+    if (!source.canReceiveRecord(collection, recordId, stored)) return () => false;
+    return (targetSessionId) => this.sessions.get(targetSessionId)?.canReceiveRecord(collection, recordId, stored) ?? false;
   }
   handleYjsDocRelay(sourceSessionId, message, storedRecord) {
     if (!this.sessions.has(sourceSessionId)) {
@@ -13453,16 +14240,22 @@ function fileVersionKey(stats) {
   return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`;
 }
 var DIGEST_CACHE_MAX_ENTRIES = 4096;
-function createStaticFileHandler(staticDir) {
+function createStaticFileHandler(staticDir, options = {}) {
   const root = resolve(staticDir);
+  const spaFallback = options.spaFallback ?? "navigation";
+  const servesShell = (req, pathname) => {
+    if (pathname.startsWith(ASSET_PREFIX)) return false;
+    if (isNavigation(req)) return true;
+    return spaFallback === "extensionless" && extname(pathname) === "";
+  };
   const compressed = /* @__PURE__ */ new Map();
   let compressedBytes = 0;
   const digests = /* @__PURE__ */ new Map();
   const verifiedSiblings = /* @__PURE__ */ new Map();
   async function contentDigest(path, stats) {
-    const version = fileVersionKey(stats);
+    const version2 = fileVersionKey(stats);
     const cached = digests.get(path);
-    if (cached && cached.version === version) return cached.digest;
+    if (cached && cached.version === version2) return cached.digest;
     const hash = createHash("sha256");
     await new Promise((done, fail) => {
       const stream = createReadStream(path);
@@ -13476,7 +14269,7 @@ function createStaticFileHandler(staticDir) {
       const oldest = digests.keys().next().value;
       if (oldest !== void 0) digests.delete(oldest);
     }
-    digests.set(path, { version, digest });
+    digests.set(path, { version: version2, digest });
     return digest;
   }
   function remember(key, body) {
@@ -13542,7 +14335,7 @@ function createStaticFileHandler(staticDir) {
       return;
     }
     let found = await locate(pathname);
-    if (!found && isNavigation(req) && !pathname.startsWith(ASSET_PREFIX)) {
+    if (!found && servesShell(req, pathname)) {
       found = await locate("/index.html");
     }
     if (!found) {
@@ -13758,6 +14551,11 @@ function parseIpv6(address) {
 
 // src/server/production-server.ts
 var DEFAULT_MAX_REQUEST_BODY_BYTES = 1024 * 1024;
+var OPERATIONAL_PATHS = {
+  admin: "/__kora, /__kora/status, /__kora/events",
+  metrics: "/__kora/metrics",
+  backup: "/__kora/backup/*"
+};
 var DEFAULT_MAX_BACKUP_BYTES = 256 * 1024 * 1024;
 function createProductionServer(config) {
   const port = config.port ?? (Number(process.env.PORT) || 3001);
@@ -13793,10 +14591,27 @@ function createProductionServer(config) {
     }
     return null;
   }
-  function isOperationalRequestAllowed(req, kind) {
+  const production = process.env.NODE_ENV === "production";
+  const allowPublic = config.operationalAuth?.allowPublic === true;
+  const OPERATIONAL_GROUPS = ["admin", "metrics", "backup"];
+  const unprotectedGroups = OPERATIONAL_GROUPS.filter((kind) => !getOperationalToken(kind));
+  function isOperationalRequestAllowed(req, res, kind) {
     const expected = getOperationalToken(kind);
-    if (!expected) return true;
-    return extractRequestToken(req) === expected;
+    if (!expected) {
+      if (!production || allowPublic) return true;
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: `This operational endpoint is disabled: no ${kind === "admin" ? "adminToken" : `${kind}Token or adminToken`} is configured and NODE_ENV is production.`,
+          code: "OPERATIONAL_ENDPOINT_DISABLED",
+          fix: "Set operationalAuth tokens in createProductionServer, or operationalAuth.allowPublic: true to serve it without one."
+        })
+      );
+      return false;
+    }
+    if (extractRequestToken(req) === expected) return true;
+    rejectUnauthorized(res);
+    return false;
   }
   function rejectUnauthorized(res) {
     res.writeHead(401, {
@@ -13955,10 +14770,31 @@ function createProductionServer(config) {
     getLiveBlobRefs() {
       return syncServer.getLiveBlobRefs();
     },
+    refreshScopes(userId) {
+      return syncServer.refreshScopes(userId);
+    },
+    revalidateSessions() {
+      return syncServer.revalidateSessions();
+    },
     async start() {
+      if (unprotectedGroups.length > 0) {
+        const paths = unprotectedGroups.map((kind) => OPERATIONAL_PATHS[kind]).join(", ");
+        syncServer.getLogger().log({
+          timestamp: Date.now(),
+          level: "warn",
+          event: "server.operational_endpoints_unprotected",
+          details: {
+            groups: unprotectedGroups,
+            disabled: production && !allowPublic,
+            message: production && !allowPublic ? `Operational endpoints without a token are disabled (${paths}). Set operationalAuth.adminToken and backupToken to use them.` : `Operational endpoints without a token are PUBLIC (${paths}). Set operationalAuth.adminToken and backupToken before exposing this server.`
+          }
+        });
+      }
       const { createServer } = await import("http");
       const { WebSocketServer } = await import("ws");
-      const serveStatic = createStaticFileHandler(staticDir);
+      const serveStatic = createStaticFileHandler(staticDir, {
+        ...config.spaFallback ? { spaFallback: config.spaFallback } : {}
+      });
       httpServer = createServer(async (req, res) => {
         try {
           await handleRequest(req, res);
@@ -13992,29 +14828,20 @@ function createProductionServer(config) {
           return;
         }
         if (url.pathname === "/__kora/status") {
-          if (!isOperationalRequestAllowed(req, "admin")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "admin")) return;
           const status = await syncServer.getStatus();
           res.writeHead(200, { "Content-Type": "application/json" });
           res.end(JSON.stringify(status, null, 2));
           return;
         }
         if (url.pathname === "/__kora/metrics") {
-          if (!isOperationalRequestAllowed(req, "metrics")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "metrics")) return;
           res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4" });
           res.end(formatPrometheusMetrics());
           return;
         }
         if (url.pathname === "/__kora/events") {
-          if (!isOperationalRequestAllowed(req, "admin")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "admin")) return;
           res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
@@ -14042,20 +14869,14 @@ data: ${JSON.stringify(s)}
           return;
         }
         if (url.pathname === "/__kora" || url.pathname === "/__kora/") {
-          if (!isOperationalRequestAllowed(req, "admin")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "admin")) return;
           const status = await syncServer.getStatus();
           res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
           res.end(renderDashboardHtml(status));
           return;
         }
         if (url.pathname === "/__kora/backup/export" && req.method === "POST") {
-          if (!isOperationalRequestAllowed(req, "backup")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "backup")) return;
           try {
             const backup = await config.store.exportBackup();
             res.writeHead(200, {
@@ -14071,10 +14892,7 @@ data: ${JSON.stringify(s)}
           return;
         }
         if (url.pathname === "/__kora/backup/import" && req.method === "POST") {
-          if (!isOperationalRequestAllowed(req, "backup")) {
-            rejectUnauthorized(res);
-            return;
-          }
+          if (!isOperationalRequestAllowed(req, res, "backup")) return;
           try {
             const body = await readBodyBuffer(req, maxBackupBytes);
             if (body === null) {
@@ -14167,7 +14985,7 @@ data: ${JSON.stringify(s)}
   };
 }
 function renderDashboardHtml(status) {
-  const version = status.version;
+  const version2 = status.version;
   const uptime = formatUptime(status.uptime);
   return `<!DOCTYPE html>
 <html lang="en">
@@ -14198,7 +15016,7 @@ function renderDashboardHtml(status) {
 </head>
 <body>
 <h1>Kora Sync Server</h1>
-<p class="subtitle">v${version} &middot; <span class="status-dot running"></span>Running</p>
+<p class="subtitle">v${version2} &middot; <span class="status-dot running"></span>Running</p>
 <div class="grid">
   <div class="card"><div class="label">Uptime</div><div class="value">${uptime}</div></div>
   <div class="card"><div class="label">Connected Clients</div><div class="value" id="connectedClients">${status.connectedClients}</div></div>
@@ -14247,6 +15065,7 @@ export {
   ClientSession,
   DEFAULT_MAX_SCOPE_PREDICATE_VALUES,
   HttpServerTransport,
+  InvalidDiagnosticOptionsError,
   InvalidScopePredicateError,
   KoraAuthProvider,
   KoraSyncServer,
@@ -14275,6 +15094,7 @@ export {
   createProductionServer,
   createSilentLogger,
   createSqliteServerStore,
+  findJsonStringValues,
   isRetriableRejection,
   isServerNodeId,
   normalizeScopeMap,