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

package/dist/index.d.cts

@@ -402,6 +402,17 @@ interface ServerStore extends SyncStore {
      * for custom stores; the built-in stores persist the claim.
      */
     claimNode?(nodeId: string, userId: string): Promise<boolean>;
+    /**
+     * Atomically claim a node id that has no real owner for `userId` (F1): a node
+     * with operation history but no claim (written before node claims existed, by a
+     * beta.12 or older server) or one an admin released (owner `''`). A node another
+     * principal owns is never taken. One statement, so there is no gap between a
+     * release and a claim another claimant could slip into. Returns true when
+     * `userId` owns the node afterwards. The server calls it only for a node whose id
+     * equals the device id the auth provider verified for that user. Optional for
+     * custom stores; without it such nodes stay refused until an admin binds them.
+     */
+    claimUnownedNode?(nodeId: string, userId: string): Promise<boolean>;
     /**
      * Admin release of a node id (RT-5): the next principal to claim it takes it
      * over, even when the node has operation history. Returns true when the node had
@@ -1161,6 +1172,18 @@ declare class KoraSyncServer {
     private readonly logger;
     private readonly metrics;
     private readonly awarenessRelay;
+    /** Reads the records presence cursors name, for every session (F16). */
+    private readonly presenceRecords;
+    /** The record each session's current presence cursor names (F16). */
+    private readonly presenceTargets;
+    /** The sessions whose presence cursor names each record, by record key. */
+    private readonly presenceTargetsByKey;
+    /**
+     * 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).
+     */
+    private readonly presenceRefreshes;
     private readonly yjsDocRelay;
     private readonly blobChunkRelay;
     /** Wrapped encryption key records (ENC-1, D4b), persisted in the server store. */
@@ -1173,8 +1196,11 @@ declare class KoraSyncServer {
     /** Per-principal ingest budget per minute; 0 when disabled. */
     private readonly maxOpsPerMinutePerUser;
     private readonly allowLegacyAnonymousClaims;
+    private readonly deviceNodeHandover;
+    private readonly unscopedSharing;
     private readonly anonymousClaimTtlMs;
     private readonly maxOpsPerBatch;
+    private readonly maxScopePredicateValues;
     private readonly maxMessageBytes;
     private readonly heartbeatIntervalMs;
     private readonly appHeartbeatIntervalMs;
@@ -1309,6 +1335,35 @@ declare class KoraSyncServer {
      * ```
      */
     revalidateSessions(): Promise<number>;
+    /**
+     * 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)
+     * ```
+     */
+    refreshScopes(userId: string): Promise<number>;
     /** Run {@link revalidateSessions} from the delivery poll tick once the interval elapsed. */
     private maybeRevalidateSessions;
     /**
@@ -1504,6 +1559,31 @@ declare class KoraSyncServer {
     private handleRelay;
     private handleSessionClose;
     private handleAwarenessRelay;
+    /** Point a session's presence at a record (or at none), keeping the index in step. */
+    private setPresenceTarget;
+    /**
+     * 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.
+     */
+    private refreshPresence;
+    /** Re-decide the presence on one record, coalesced with a re-decision already running. */
+    private schedulePresenceRefresh;
+    private runPresenceRefresh;
+    /**
+     * 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).
+     */
+    private awarenessAudience;
     private handleYjsDocRelay;
     /** Open a new HTTP long-poll session bound to `principal`, under a fresh random id. */
     private openHttpSession;
@@ -1936,6 +2016,14 @@ interface KoraSyncServerConfig {
      * sends batches of 100 by default).
      */
     maxOpsPerBatch?: number;
+    /**
+     * Most values one `$in` scope predicate may hold, in either direction. A grant
+     * with more is refused at handshake with `SCOPE_PREDICATE_LIMIT`, so an auth
+     * provider bug cannot hand one session an unbounded predicate that every delivery
+     * and revalidation then evaluates. Defaults to 100. See the production server
+     * guide for the measured cost of larger values before raising it.
+     */
+    maxScopePredicateValues?: number;
     /**
      * Accept anonymous devices whose node claim predates confirmed claims (RT-21):
      * nodes whose operation history predates node claims (a database written by a
@@ -1953,6 +2041,29 @@ interface KoraSyncServerConfig {
      * devices syncing.
      */
     allowLegacyAnonymousClaims?: boolean;
+    /**
+     * Automatic device handover after an upgrade from beta.12 (F1). When a signed-in
+     * device presents a node id that has operation history but no owner (beta.12
+     * recorded no node claims) or that an administrator released, and the node id
+     * equals the device id the auth provider verified for that user
+     * (`AuthContext.metadata.deviceId`, set by the built-in `KoraAuthProvider` from the
+     * token), the node is claimed for that user in one atomic step instead of being
+     * refused `NODE_ID_CLAIMED`. A node another principal owns is never taken.
+     * Defaults to `true`. A custom auth provider must set `metadata.deviceId` only to
+     * a device id it verified as registered to the user; set this to `false` if yours
+     * cannot guarantee that.
+     */
+    deviceNodeHandover?: boolean;
+    /**
+     * What to do when a signed-in session's grant restricts no collection, so every user
+     * syncs every other user's data (F4). That happens when the auth provider returns
+     * a claims grant (the built-in provider's default) and the schema declares no sync
+     * rule binding it, or when a provider returns no scopes. `'warn'` (default) logs it
+     * once per provider; `'allow'` silences it for apps whose users all share one data
+     * set; `'refuse'` refuses such handshakes with `UNSCOPED_SHARING_REFUSED`.
+     * Anonymous sessions are not judged: their grant is the app's own choice.
+     */
+    unscopedSharing?: 'warn' | 'allow' | 'refuse';
     /**
      * How long an anonymous device's provisional node claim may stay unconfirmed and
      * still be re-issued to a device that presents no token (a handshake response lost
@@ -2129,6 +2240,78 @@ declare class HttpServerTransport implements ServerTransport {
     private makeEtag;
 }
 
+/** One read of a record for a presence decision. */
+interface PresenceRecordRead {
+    /** The stored row (soft-deleted rows included), or null when the server holds none */
+    stored: MaterializedRecord | null;
+    /**
+     * The reader's clock when the read began. A write that touched the record after
+     * it ({@link PresenceRecords.touchedSince}) means the row may predate that write.
+     */
+    asOf: number;
+}
+/**
+ * Reads the records presence cursors name, for every session of one sync server (F16).
+ *
+ * Presence decides who may see a cursor from the record it names, so the row must be
+ * the store's latest, never a copy another code path holds (a session's delivery
+ * pass caches rows for the whole chunk it filters). Every write the server commits
+ * {@link touch}es the records it wrote; a read is current when no touch of its record
+ * came after it began. Reads of one record are shared while current (many cursors on
+ * one busy document cost one read per write burst, not one per cursor per write), a
+ * read is never shared across a touch, and reads are bounded in number at once.
+ *
+ * Presence is ephemeral and nothing here is persisted.
+ */
+declare class PresenceRecords {
+    private readonly store;
+    private readonly now;
+    private clock;
+    /** The clock value of each tracked record's last touch, oldest first. */
+    private readonly lastTouch;
+    /** Touches forgotten to bound memory count as having happened at this clock. */
+    private forgottenTouchesAt;
+    private readonly inFlight;
+    private readonly cache;
+    private running;
+    private readonly waiting;
+    constructor(store: ServerStore, now?: () => number);
+    /**
+     * 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: Iterable<string> | null): void;
+    /**
+     * 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: string, asOf: number): boolean;
+    /**
+     * 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: string, recordId: string): PresenceRecordRead | undefined;
+    /**
+     * 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
+     */
+    read(collection: string, recordId: string): Promise<PresenceRecordRead>;
+    /** Forget every read and touch (the server stopped). */
+    clear(): void;
+    private readStore;
+    private forget;
+}
+
 /** Outcome of one key-service message. */
 interface KeyServiceOutcome {
     response: EncryptionKeyResponseMessage;
@@ -2207,7 +2390,23 @@ type RelayCallback = (sourceSessionId: string, operations: Operation[]) => void;
 /**
  * Callback invoked when a session receives an awareness update to relay to other sessions.
  */
-type AwarenessRelayCallback = (sourceSessionId: string, message: AwarenessUpdateMessage) => void;
+type AwarenessRelayCallback = (sourceSessionId: string, message: AwarenessUpdateMessage, cursorTarget?: AwarenessCursorTarget) => void;
+/**
+ * The record an awareness state's cursor names, as the sending session resolved it
+ * from the store. `stored` is null for a record the server does not hold. A cursor
+ * that is not a `{ collection, recordId }` pair of strings is `{ invalid: true }`;
+ * a state without a cursor has no target.
+ */
+type AwarenessCursorTarget = {
+    invalid?: false;
+    collection: string;
+    recordId: string;
+    stored: MaterializedRecord | null;
+    /** When the read of `stored` began, on the server's presence reader clock. */
+    asOf?: number;
+} | {
+    invalid: true;
+};
 /**
  * Callback invoked when a session receives a Yjs doc channel update to relay.
  */
@@ -2259,6 +2458,11 @@ interface ClientSessionOptions {
     onRelay?: RelayCallback;
     /** Called when this session receives an awareness update to broadcast */
     onAwarenessUpdate?: AwarenessRelayCallback;
+    /**
+     * The reader of the records presence cursors name, shared by the server's sessions
+     * (F16). Defaults to one of this session's own.
+     */
+    presenceRecords?: PresenceRecords;
     /** Called when this session receives a Yjs doc channel update to broadcast */
     onYjsDocUpdate?: YjsDocRelayCallback;
     /** Called when this session receives a blob chunk request to route */
@@ -2314,6 +2518,12 @@ interface ClientSessionOptions {
      * (`BATCH_TOO_LARGE`) before it is decoded or the store is read. Defaults to 1000.
      */
     maxOpsPerBatch?: number;
+    /**
+     * Most values one `$in` scope predicate may hold. A grant over the limit is
+     * refused at handshake (`SCOPE_PREDICATE_LIMIT`). Defaults to
+     * {@link DEFAULT_MAX_SCOPE_PREDICATE_VALUES} (100).
+     */
+    maxScopePredicateValues?: number;
     /**
      * Adjudicate untrusted client operations before materialization. When present,
      * each incoming operation is passed to this validator; a `reject` decision
@@ -2330,6 +2540,10 @@ interface ClientSessionOptions {
     blobAccess?: BlobAccessIndex;
     /** See `KoraSyncServerConfig.allowLegacyAnonymousClaims` (RT-21). Defaults to true. */
     allowLegacyAnonymousClaims?: boolean;
+    /** See `KoraSyncServerConfig.deviceNodeHandover` (F1). Defaults to true. */
+    deviceNodeHandover?: boolean;
+    /** See `KoraSyncServerConfig.unscopedSharing` (F4). Defaults to `'warn'`. */
+    unscopedSharing?: 'warn' | 'allow' | 'refuse';
     /** See `KoraSyncServerConfig.anonymousClaimTtlMs` (RT-21). Defaults to 24 hours. */
     anonymousClaimTtlMs?: number;
     /**
@@ -2419,6 +2633,8 @@ declare class ClientSession {
     /** A provisional anonymous claim awaiting the device's confirmation (RT-21). */
     private pendingNodeClaim;
     private readonly allowLegacyAnonymousClaims;
+    private readonly deviceNodeHandover;
+    private readonly unscopedSharing;
     private readonly anonymousClaimTtlMs;
     private readonly isNodeLive;
     /** The credential presented at handshake, kept to re-validate the session (RT-18). */
@@ -2491,7 +2707,6 @@ declare class ClientSession {
      * `collection\u0000id`; null marks a record known to be absent. Only set while a
      * chunk is filtered.
      */
-    private recordLookupCache;
     private readonly deliveryHighWaterBytes;
     private readonly handshakeTimeoutMs;
     private handshakeTimer;
@@ -2542,6 +2757,15 @@ declare class ClientSession {
     private readonly maxOperationBytes;
     private readonly maxOpsPerMinute;
     private readonly maxOpsPerBatch;
+    private readonly maxScopePredicateValues;
+    /** {@link getScopePartitionKey}, cached for the scope map it was computed from. */
+    private scopePartitionKeyCache;
+    /** Store reads for presence cursors (F16), per minute. */
+    private readonly presenceLookupLimiter;
+    /** Reads the records presence cursors name (shared by the server's sessions). */
+    private readonly presenceRecords;
+    /** A {@link refreshScopes} request arrived during the handshake: re-check once streaming. */
+    private scopeRefreshPending;
     private rateLimiter;
     /** Separate budget for blob chunk requests (RT-24). */
     private readonly blobRateLimiter;
@@ -2689,6 +2913,22 @@ declare class ClientSession {
      *   provider threw (nothing is ended; the caller retries later), else `'valid'`
      */
     revalidateCredential(): Promise<'valid' | 'terminated' | 'error'>;
+    /**
+     * 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
+     */
+    refreshScopes(userId: string): Promise<'valid' | 'terminated' | 'error' | 'deferred' | 'skipped'>;
+    /** Run a re-check deferred by {@link refreshScopes} once the session streams. */
+    private runDeferredScopeRefresh;
     /**
      * True when `context` (a fresh authentication of this session's principal)
      * resolves to download or upload scopes other than the ones this session holds.
@@ -2751,14 +2991,21 @@ declare class ClientSession {
      * not stored yet is judged by its id alone.
      */
     canReceiveRecord(collection: string, recordId: string, storedRecord: Record<string, unknown> | null): boolean;
-    /**
-     * 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(): ScopeMap | undefined;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
     /**
      * Get the transport for this session.
      * Used by the awareness relay to send messages to this client.
@@ -2801,6 +3048,32 @@ declare class ClientSession {
      * are re-issued only with `allowLegacyAnonymousClaims`, with a deprecation warning.
      */
     private claimAnonymousNode;
+    /**
+     * 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.
+     */
+    private handOverDeviceNode;
+    /**
+     * 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.
+     */
+    private grantWithoutHandshakeNarrowing;
+    /** Who holds a refused node id, as `NODE_ID_CLAIMED` reports it (F9). */
+    private nodeOwnershipOf;
     /** The deprecation warning for an anonymous device adopted under a legacy claim (RT-21, RT-91). */
     private warnLegacyAnonymousClaim;
     /**
@@ -3089,8 +3362,15 @@ declare 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.
      */
     private lookupRecordFields;
+    /**
+     * 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.
+     */
     private handleAwarenessUpdate;
     /**
      * A Yjs doc-channel update is a write to a richtext field: the sender must be
@@ -3112,6 +3392,54 @@ declare class ClientSession {
     private handleTransportClose;
 }
 
+/** {@link findJsonStringValues} was given a page or sample size it cannot use. */
+declare class InvalidDiagnosticOptionsError extends KoraError {
+    constructor(option: string, value: unknown);
+}
+/** Rows of one json/object field whose stored value is a string that itself holds JSON. */
+interface JsonStringValueReport {
+    collection: string;
+    field: string;
+    /** How many live rows hold such a string. */
+    count: number;
+    /** Ids of the first such rows, to inspect. */
+    sampleIds: string[];
+}
+/** Options for {@link findJsonStringValues}. */
+interface FindJsonStringValuesOptions {
+    /** Ids reported per field. Defaults to 10. */
+    sampleSize?: number;
+    /** Rows read per page. Defaults to 1,000. */
+    pageSize?: number;
+}
+/**
+ * Find `t.json()` / `t.object()` fields whose stored value is a JSON-encoded string
+ * (`'{"a":1}'` instead of `{ a: 1 }`), after an upgrade from a server older than
+ * 1.0.0-beta.13 (F14).
+ *
+ * Servers before beta.13 decoded one JSON-string layer of such values when they built
+ * rows; since beta.13 the rows hold exactly what the operations wrote. A client that
+ * wrote a json field as a string (or double-encoded it) therefore reads back a string
+ * where the old server returned an object. Kora does not rewrite these values: a string
+ * is also a legitimate json value, so no rule can tell a real string from an encoded
+ * object. Fix them with server-authored updates (`server.kora.apply`) once you know
+ * which shape your app expects.
+ *
+ * @param store - The server store, with its schema set
+ * @param options - Sample and page sizes
+ * @returns One report per field that holds at least one such value
+ * @throws {InvalidDiagnosticOptionsError} When `pageSize` is not a positive integer or
+ *   `sampleSize` not a non-negative one
+ *
+ * @example
+ * ```typescript
+ * for (const report of await findJsonStringValues(store)) {
+ *   console.warn(`${report.collection}.${report.field}: ${report.count} rows`, report.sampleIds)
+ * }
+ * ```
+ */
+declare function findJsonStringValues(store: ServerStore, options?: FindJsonStringValuesOptions): Promise<JsonStringValueReport[]>;
+
 /**
  * Configuration for the production server that serves both
  * static files and WebSocket sync on a single port.
@@ -3169,6 +3497,13 @@ interface ProductionServerConfig {
      * Largest backup accepted by `/__kora/backup/import`, in bytes. Defaults to 256 MiB.
      */
     maxBackupBytes?: number;
+    /**
+     * Which requests for a missing path get the app shell (`index.html`). `'navigation'`
+     * (default): browser navigations only, so a missing API path is a real 404.
+     * `'extensionless'`: also any path without a file extension, for a service worker
+     * that warms app routes with a plain `fetch(url)`. Never under `/assets/`.
+     */
+    spaFallback?: 'navigation' | 'extensionless';
 }
 interface ProductionOperationalAuth {
     /** Protects /__kora, /__kora/status, and /__kora/events. */
@@ -3177,6 +3512,14 @@ interface ProductionOperationalAuth {
     metricsToken?: string;
     /** Protects /__kora/backup/*. Falls back to adminToken when omitted. */
     backupToken?: string;
+    /**
+     * With `NODE_ENV=production`, an endpoint group whose token is unset is disabled
+     * (`403 OPERATIONAL_ENDPOINT_DISABLED`): backups export or replace every user's data,
+     * and the dashboard lists connected devices. Set this to `true` to serve such groups
+     * without a token anyway (for example behind a network you control). Outside
+     * production, groups without a token stay public, with a startup warning.
+     */
+    allowPublic?: boolean;
 }
 interface ProductionHttpRouteRequest {
     method: string;
@@ -3237,6 +3580,25 @@ interface ProductionServer {
      * @returns Every live blob reference the server can currently see.
      */
     getLiveBlobRefs(): Promise<BlobRef[]>;
+    /**
+     * Re-resolve one user's grant on their live sync sessions now. Call it after a
+     * membership change (an invitation accepted, a collaborator removed): a session
+     * whose scope changed ends with a retriable `SCOPE_CHANGED` and its client
+     * reconnects with the new grant, applying its `scopeExit` policy. See
+     * `KoraSyncServer.refreshScopes`.
+     *
+     * @param userId - The user whose grant changed
+     * @returns The number of sessions ended
+     */
+    refreshScopes(userId: string): Promise<number>;
+    /**
+     * Re-validate every live sync session's credential and grant now (the pass that
+     * otherwise runs every `sessionRevalidationIntervalMs`). See
+     * `KoraSyncServer.revalidateSessions`.
+     *
+     * @returns The number of sessions ended
+     */
+    revalidateSessions(): Promise<number>;
 }
 /**
  * Creates a production server that serves both static files and WebSocket sync
@@ -3627,6 +3989,7 @@ declare class MemoryServerStore implements ServerStore {
     listEncryptionKeyRecords(owner?: string): Promise<EncryptionKeyRecordRow[]>;
     getEncryptedKeyIds(nodeOwner: string | null, limit: number): Promise<string[]>;
     claimNode(nodeId: string, userId: string): Promise<boolean>;
+    claimUnownedNode(nodeId: string, userId: string): Promise<boolean>;
     getNodeClaimOwner(nodeId: string): Promise<string | null>;
     replaceNodeClaim(nodeId: string, expectedOwner: string, newOwner: string): Promise<boolean>;
     releaseNodeClaim(nodeId: string): Promise<boolean>;
@@ -3991,6 +4354,7 @@ declare class PostgresServerStore implements ServerStore {
     listEncryptionKeyRecords(owner?: string): Promise<EncryptionKeyRecordRow[]>;
     getEncryptedKeyIds(nodeOwner: string | null, limit: number): Promise<string[]>;
     claimNode(nodeId: string, userId: string): Promise<boolean>;
+    claimUnownedNode(nodeId: string, userId: string): Promise<boolean>;
     getNodeClaimOwner(nodeId: string): Promise<string | null>;
     replaceNodeClaim(nodeId: string, expectedOwner: string, newOwner: string): Promise<boolean>;
     releaseNodeClaim(nodeId: string): Promise<boolean>;
@@ -4248,6 +4612,7 @@ declare class SqliteServerStore implements ServerStore {
     listEncryptionKeyRecords(owner?: string): Promise<EncryptionKeyRecordRow[]>;
     getEncryptedKeyIds(nodeOwner: string | null, limit: number): Promise<string[]>;
     claimNode(nodeId: string, userId: string): Promise<boolean>;
+    claimUnownedNode(nodeId: string, userId: string): Promise<boolean>;
     getNodeClaimOwner(nodeId: string): Promise<string | null>;
     replaceNodeClaim(nodeId: string, expectedOwner: string, newOwner: string): Promise<boolean>;
     releaseNodeClaim(nodeId: string): Promise<boolean>;
@@ -4522,13 +4887,21 @@ declare function resolveSessionScopes(schema: SchemaDefinition | null, options:
  */
 declare function resolveSessionScopeGrant(schema: SchemaDefinition | null, options: ResolveSessionScopesOptions): ResolvedSessionScopeGrant;
 
+/**
+ * Decides whether one client's current awareness state may reach another session.
+ * Called with the receiving session's id; returning false keeps the state from it.
+ * The sync server builds one per update from the record named in the state's cursor.
+ */
+type AwarenessAudience = (targetSessionId: string) => boolean;
 /**
  * Server-side awareness relay. Broadcasts ephemeral awareness states
  * (cursor positions, user presence) between connected clients.
  *
  * Awareness data is never persisted. Each session's awareness `clientId` is bound on
  * registration: a session may only publish (or clear) its own state, never another
- * client's, and its updates reach only clients in the same partition.
+ * client's. A state reaches exactly the sessions its audience admits (the sync server
+ * admits sessions whose download scope contains the record named in the cursor), or,
+ * for an update without an audience, the clients of the same partition.
  */
 declare class AwarenessRelay {
     private readonly clients;
@@ -4537,10 +4910,14 @@ declare class AwarenessRelay {
      * 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: string, clientId: number, transport: ServerTransport, partition?: string): void;
     /**
@@ -4550,23 +4927,46 @@ declare class AwarenessRelay {
      */
     hasClient(sessionId: string): boolean;
     /**
-     * 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
      */
     removeClient(sessionId: string): void;
+    /**
+     * 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: string, message: AwarenessUpdateMessage): boolean;
     /**
      * Handle an incoming awareness update from a registered client.
      *
      * 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: string, message: AwarenessUpdateMessage, audience?: AwarenessAudience): void;
+    /**
+     * 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
      */
-    handleUpdate(sessionId: string, message: AwarenessUpdateMessage): void;
+    updateAudience(sessionId: string, audience: AwarenessAudience): void;
     /**
      * Get the number of registered awareness clients.
      */
@@ -4575,7 +4975,9 @@ declare class AwarenessRelay {
      * Remove all clients and clear all state.
      */
     clear(): void;
-    private broadcastExcept;
+    /** True when `target` may see `source`'s current state. Fails closed. */
+    private mayReceive;
+    private removalMessage;
 }
 
 /**
@@ -4595,4 +4997,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type ApplyRemoteOptions, type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, DEFAULT_MAX_SCOPE_PREDICATE_VALUES, type DeniedScopeCollection, type FoldMigrationReport, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, InvalidScopePredicateError, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, type MemoryServerStoreOptions, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type ResolveSessionScopesOptions, type ResolvedSessionScopeGrant, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, SERVER_NODE_PREFIX, ScopePredicateLimitError, ScopeRequiredError, ServerCloseHandler, ServerErrorHandler, ServerIdentityError, type ServerIdentityOptions, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerSchemaOptions, type ServerStatus, type ServerStore, ServerStoreUnavailableError, ServerTransport, type SessionRevocation, type SessionState, type SessionTerminationCode, SqliteServerStore, type StoredOperationKey, type TerminateSessionsFilter, TokenAuthProvider, type TokenAuthProviderOptions, type TrustProxySetting, type UplinkAuthorizationCode, UplinkAuthorizationError, type UplinkAuthorizationResult, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, authorizeUplinkWrite, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection, isServerNodeId, normalizeScopeMap, operationMatchesScopes, resolveSessionScopeGrant, resolveSessionScopes };
+export { type ApplyRemoteOptions, type AuthContext, type AuthProvider, type AwarenessAudience, type AwarenessCursorTarget, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, DEFAULT_MAX_SCOPE_PREDICATE_VALUES, type DeniedScopeCollection, type FindJsonStringValuesOptions, type FoldMigrationReport, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, InvalidDiagnosticOptionsError, InvalidScopePredicateError, type JsonStringValueReport, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, type MemoryServerStoreOptions, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type ResolveSessionScopesOptions, type ResolvedSessionScopeGrant, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, SERVER_NODE_PREFIX, ScopePredicateLimitError, ScopeRequiredError, ServerCloseHandler, ServerErrorHandler, ServerIdentityError, type ServerIdentityOptions, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerSchemaOptions, type ServerStatus, type ServerStore, ServerStoreUnavailableError, ServerTransport, type SessionRevocation, type SessionState, type SessionTerminationCode, SqliteServerStore, type StoredOperationKey, type TerminateSessionsFilter, TokenAuthProvider, type TokenAuthProviderOptions, type TrustProxySetting, type UplinkAuthorizationCode, UplinkAuthorizationError, type UplinkAuthorizationResult, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, authorizeUplinkWrite, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, findJsonStringValues, isRetriableRejection, isServerNodeId, normalizeScopeMap, operationMatchesScopes, resolveSessionScopeGrant, resolveSessionScopes };