matrix-nodejs-homeserver 0.3.2 → 0.3.4

package/dist/core/admin.js

@@ -301,6 +301,7 @@ var AdminService = class {
 			content: { tags: { [M.SERVER_NOTICE]: { order: .5 } } },
 			stream
 		}));
+		this.hs.notifier.notify([userId]);
 		return room_id;
 	}
 };

package/dist/core/changes.d.ts

@@ -0,0 +1,79 @@
+import { DatabaseAdapter } from "../storage/types.js";
+//#region src/core/changes.d.ts
+/**
+ * Where keys last changed, for a homeserver that is the only instance on its database.
+ *
+ * https://github.com/k18k/matrix-nodejs-homeserver/issues/51: most of a `/sync` build asked the
+ * database whether something had changed since the token (to-device messages, presence, account
+ * data, the user's rooms) and almost always found nothing. Every write passes through the adapter
+ * returned by `ChangeTracker.wrap`, which notes, per key, the stream position (or, for cached
+ * values, the write) at which it last changed, so `/sync` knows without asking.
+ *
+ * It is only used without a cluster adapter: another instance's writes would not pass through it.
+ * Memory is bounded: each log keeps its most recently changed keys, and forgetting a key raises
+ * the log's floor, at or below which every key counts as changed (and the database is asked).
+ */
+export declare class ChangeLog {
+  private latest;
+  private floor;
+  private max;
+  constructor(max: number, floor?: number);
+  /** `key` changed at `pos`. */
+  record(key: string, pos: number): void;
+  /** Every key may have changed at or below `pos` (for writes whose keys are not known). */
+  raiseFloor(pos: number): void;
+  /** Set the floor (also lower it: from "nothing is known" to a starting position). */
+  setFloor(pos: number): void;
+  /** Whether `key` may have changed after `pos`; false only when it is known not to have. */
+  changedAfter(key: string, pos: number): boolean;
+  /** The keys among `keys` that may have changed after `pos`. */
+  filterChanged(keys: Iterable<string>, pos: number): string[];
+}
+/**
+ * Values read from the database, kept until a write changes their key. A value is only kept if
+ * no write to its key started while it was being read; in a transaction, the keys are marked
+ * again once it commits, so a value read before the commit is not kept either.
+ */
+export declare class ValueCache<V> {
+  private values;
+  private writes;
+  private clock;
+  private max;
+  constructor(max: number, clock: () => number);
+  /** A write to `key` (or, without a key, to any) has started or finished at `tick`. */
+  written(key: string | null, tick: number): void;
+  /** The kept value of `key`, if there is one and no write has changed it since it was read. */
+  peek(key: string): V | undefined;
+  /**
+   * Keep `value`, read by a read that began at `readAt` (the clock then): unless a write to `key`
+   * began since, which may or may not be in `value`.
+   */
+  store(key: string, value: V, readAt: number): void;
+  get(key: string, load: () => Promise<V>): Promise<V>;
+}
+/** Stream logs: keys that changed at a stream position. */
+export type StreamLogName = "toDevice" | "presence" | "deviceLists" | "accountData" | "roomEvents" | "roomReceipts" | "roomMembers" | "roomPartialState";
+/** Value caches: values kept until their key is written. */
+export type ValueName = "userMemberships" | "ignoredUsers" | "oneTimeKeys" | "fallbackKeys" | "presenceRow" | "readReceipts" | "unreadCounts";
+export declare class ChangeTracker {
+  readonly logs: Record<StreamLogName, ChangeLog>;
+  readonly values: Record<ValueName, ValueCache<any>>;
+  private tick;
+  constructor();
+  /**
+   * Begin answering for changes after `position`. Until then, every key counts as changed. Every
+   * write after the adapter was wrapped is noted, so the logs know all changes after `position`
+   * if it was read after wrapping.
+   */
+  start(position: number): void;
+  /** The clock to pass to `ValueCache.store` for a read that begins now. */
+  now(): number;
+  /** Note a write to `model`: `rows` written, or rows matching `where` changed or deleted. */
+  private note;
+  /** Mark cached values written again (after a transaction committed). */
+  private rewritten;
+  /** An adapter that notes every write before passing it on to `db`. */
+  wrap(db: DatabaseAdapter): DatabaseAdapter;
+  private wrapWith;
+}
+//#endregion

package/dist/core/changes.js

@@ -0,0 +1,332 @@
+import { readBatch } from "../storage/batch.js";
+//#region src/core/changes.ts
+/** Rows kept in a cache are shared between requests: freeze them, so a change fails loudly. */
+function freeze(value) {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const v of Object.values(value)) freeze(v);
+	}
+	return value;
+}
+/**
+* Run `reads` like `readBatch`, but answer from the change tracker what it can (#51); the others
+* still go to the database together. Without a tracker (in a cluster), all go to the database.
+*/
+async function trackedReads(db, tracker, reads) {
+	if (!tracker) return readBatch(db, reads.map((r) => r.query));
+	const out = [];
+	const pending = [];
+	reads.forEach((read, i) => {
+		const skip = read.unlessChanged;
+		if (skip && !tracker.logs[skip.log].changedAfter(skip.key, skip.after)) out[i] = [];
+		else if (read.cached && (out[i] = tracker.values[read.cached.name].peek(read.cached.key)) !== void 0) return;
+		else pending.push(i);
+	});
+	if (!pending.length) return out;
+	const readAt = tracker.now();
+	const rows = await readBatch(db, pending.map((i) => reads[i].query));
+	pending.forEach((i, j) => {
+		out[i] = rows[j];
+		const cached = reads[i].cached;
+		if (cached) tracker.values[cached.name].store(cached.key, freeze(rows[j]), readAt);
+	});
+	return out;
+}
+/**
+* Where keys last changed, for a homeserver that is the only instance on its database.
+*
+* https://github.com/k18k/matrix-nodejs-homeserver/issues/51: most of a `/sync` build asked the
+* database whether something had changed since the token (to-device messages, presence, account
+* data, the user's rooms) and almost always found nothing. Every write passes through the adapter
+* returned by `ChangeTracker.wrap`, which notes, per key, the stream position (or, for cached
+* values, the write) at which it last changed, so `/sync` knows without asking.
+*
+* It is only used without a cluster adapter: another instance's writes would not pass through it.
+* Memory is bounded: each log keeps its most recently changed keys, and forgetting a key raises
+* the log's floor, at or below which every key counts as changed (and the database is asked).
+*/
+var ChangeLog = class {
+	latest = /* @__PURE__ */ new Map();
+	floor;
+	max;
+	constructor(max, floor = 0) {
+		this.max = max;
+		this.floor = floor;
+	}
+	/** `key` changed at `pos`. */
+	record(key, pos) {
+		const previous = this.latest.get(key);
+		this.latest.delete(key);
+		this.latest.set(key, previous === void 0 ? pos : Math.max(previous, pos));
+		if (this.latest.size > this.max) {
+			const [oldest, at] = this.latest.entries().next().value;
+			this.latest.delete(oldest);
+			if (at > this.floor) this.floor = at;
+		}
+	}
+	/** Every key may have changed at or below `pos` (for writes whose keys are not known). */
+	raiseFloor(pos) {
+		if (pos > this.floor) this.floor = pos;
+	}
+	/** Set the floor (also lower it: from "nothing is known" to a starting position). */
+	setFloor(pos) {
+		this.floor = pos;
+	}
+	/** Whether `key` may have changed after `pos`; false only when it is known not to have. */
+	changedAfter(key, pos) {
+		return pos < this.floor || (this.latest.get(key) ?? Number.NEGATIVE_INFINITY) > pos;
+	}
+	/** The keys among `keys` that may have changed after `pos`. */
+	filterChanged(keys, pos) {
+		const out = [];
+		for (const k of keys) if (this.changedAfter(k, pos)) out.push(k);
+		return out;
+	}
+};
+/**
+* Values read from the database, kept until a write changes their key. A value is only kept if
+* no write to its key started while it was being read; in a transaction, the keys are marked
+* again once it commits, so a value read before the commit is not kept either.
+*/
+var ValueCache = class {
+	values = /* @__PURE__ */ new Map();
+	writes;
+	clock;
+	max;
+	constructor(max, clock) {
+		this.max = max;
+		this.clock = clock;
+		this.writes = new ChangeLog(max * 2);
+	}
+	/** A write to `key` (or, without a key, to any) has started or finished at `tick`. */
+	written(key, tick) {
+		if (key === null) {
+			this.writes.raiseFloor(tick);
+			this.values.clear();
+		} else {
+			this.writes.record(key, tick);
+			this.values.delete(key);
+		}
+	}
+	/** The kept value of `key`, if there is one and no write has changed it since it was read. */
+	peek(key) {
+		const hit = this.values.get(key);
+		if (!hit) return void 0;
+		if (this.writes.changedAfter(key, hit.readAt)) {
+			this.values.delete(key);
+			return;
+		}
+		this.values.delete(key);
+		this.values.set(key, hit);
+		return hit.value;
+	}
+	/**
+	* Keep `value`, read by a read that began at `readAt` (the clock then): unless a write to `key`
+	* began since, which may or may not be in `value`.
+	*/
+	store(key, value, readAt) {
+		if (this.writes.changedAfter(key, readAt)) return;
+		this.values.delete(key);
+		this.values.set(key, {
+			value,
+			readAt
+		});
+		if (this.values.size > this.max) this.values.delete(this.values.keys().next().value);
+	}
+	async get(key, load) {
+		const hit = this.peek(key);
+		if (hit !== void 0) return hit;
+		const readAt = this.clock();
+		const value = await load();
+		this.store(key, value, readAt);
+		return value;
+	}
+};
+const LOG_SIZE = 1e5;
+const CACHE_SIZE = 5e4;
+const join = (...parts) => parts.every((p) => typeof p === "string") ? parts.join("|") : null;
+const GLOBAL = () => "*";
+const RULES = {
+	to_device: [{
+		stream: "toDevice",
+		key: (f) => join(f.user_id, f.device_id)
+	}],
+	presence: [{
+		stream: "presence",
+		key: GLOBAL
+	}, {
+		value: "presenceRow",
+		key: (f) => join(f.user_id)
+	}],
+	device_list_changes: [{
+		stream: "deviceLists",
+		key: GLOBAL
+	}],
+	account_data: [{
+		stream: "accountData",
+		key: (f) => join(f.user_id)
+	}, {
+		value: "ignoredUsers",
+		key: (f) => join(f.user_id)
+	}],
+	events: [{
+		stream: "roomEvents",
+		key: (f) => join(f.room_id)
+	}],
+	receipts: [
+		{
+			stream: "roomReceipts",
+			key: (f) => join(f.room_id)
+		},
+		{
+			value: "readReceipts",
+			key: (f) => join(f.room_id, f.user_id)
+		},
+		{
+			value: "unreadCounts",
+			key: (f) => join(f.user_id, f.room_id)
+		}
+	],
+	memberships: [{
+		stream: "roomMembers",
+		key: (f) => join(f.room_id)
+	}, {
+		value: "userMemberships",
+		key: (f) => join(f.user_id)
+	}],
+	partial_state_rooms: [{
+		stream: "roomPartialState",
+		key: (f) => join(f.room_id),
+		pos: "completed_stream"
+	}],
+	notifications: [{
+		value: "unreadCounts",
+		key: (f) => join(f.user_id, f.room_id)
+	}],
+	one_time_keys: [{
+		value: "oneTimeKeys",
+		key: (f) => join(f.user_id, f.device_id)
+	}],
+	fallback_keys: [{
+		value: "fallbackKeys",
+		key: (f) => join(f.user_id, f.device_id)
+	}]
+};
+/** The fields a where clause pins to one value. */
+function pinned(where) {
+	const out = {};
+	for (const w of where) if ((w.operator ?? "eq") === "eq") out[w.field] = w.value;
+	return out;
+}
+var ChangeTracker = class {
+	logs;
+	values;
+	tick = 0;
+	constructor() {
+		const log = () => new ChangeLog(LOG_SIZE, Number.POSITIVE_INFINITY);
+		this.logs = {
+			toDevice: log(),
+			presence: log(),
+			deviceLists: log(),
+			accountData: log(),
+			roomEvents: log(),
+			roomReceipts: log(),
+			roomMembers: log(),
+			roomPartialState: log()
+		};
+		const clock = () => this.tick;
+		const cache = () => new ValueCache(CACHE_SIZE, clock);
+		this.values = {
+			userMemberships: cache(),
+			ignoredUsers: cache(),
+			oneTimeKeys: cache(),
+			fallbackKeys: cache(),
+			presenceRow: cache(),
+			readReceipts: cache(),
+			unreadCounts: cache()
+		};
+	}
+	/**
+	* Begin answering for changes after `position`. Until then, every key counts as changed. Every
+	* write after the adapter was wrapped is noted, so the logs know all changes after `position`
+	* if it was read after wrapping.
+	*/
+	start(position) {
+		for (const log of Object.values(this.logs)) log.setFloor(position);
+	}
+	/** The clock to pass to `ValueCache.store` for a read that begins now. */
+	now() {
+		return this.tick;
+	}
+	/** Note a write to `model`: `rows` written, or rows matching `where` changed or deleted. */
+	note(model, rows, where, data) {
+		const rules = RULES[model];
+		if (!rules) return [];
+		const tick = ++this.tick;
+		const touched = [];
+		const sources = rows ?? [{
+			...pinned(where ?? []),
+			...data
+		}];
+		for (const fields of sources) for (const rule of rules) {
+			const key = rule.key(fields);
+			if (rule.value) {
+				this.values[rule.value].written(key, tick);
+				if (key !== null) touched.push(`${rule.value}\0${key}`);
+			}
+			if (rule.stream) {
+				const pos = fields[rule.pos ?? "stream"];
+				if (typeof pos !== "number") continue;
+				if (key === null) this.logs[rule.stream].raiseFloor(pos);
+				else this.logs[rule.stream].record(key, pos);
+			}
+		}
+		return touched;
+	}
+	/** Mark cached values written again (after a transaction committed). */
+	rewritten(touched) {
+		const tick = ++this.tick;
+		for (const t of touched) {
+			const [name, key] = t.split("\0");
+			this.values[name].written(key, tick);
+		}
+	}
+	/** An adapter that notes every write before passing it on to `db`. */
+	wrap(db) {
+		return this.wrapWith(db, null);
+	}
+	wrapWith(db, inTx) {
+		const around = async (touched, run) => {
+			try {
+				return await run();
+			} finally {
+				if (inTx) inTx.push(...touched);
+				else this.rewritten(touched);
+			}
+		};
+		const adapter = {
+			findMany: (model, opts) => db.findMany(model, opts),
+			findOne: (model, where) => db.findOne(model, where),
+			...db.findManyBatch ? { findManyBatch: (queries, options) => db.findManyBatch(queries, options) } : {},
+			create: (model, data) => around(this.note(model, [data], null), () => db.create(model, data)),
+			upsert: (model, data) => around(this.note(model, [data], null), () => db.upsert(model, data)),
+			...db.upsertMany ? { upsertMany: (model, rows) => around(this.note(model, rows, null), () => db.upsertMany(model, rows)) } : {},
+			update: (model, where, data) => around(this.note(model, null, where, data), () => db.update(model, where, data)),
+			delete: (model, where) => around(this.note(model, null, where), () => db.delete(model, where)),
+			max: (model, field) => db.max(model, field),
+			...db.migrate ? { migrate: (schema) => db.migrate(schema) } : {}
+		};
+		if (db.transaction) adapter.transaction = async (fn) => {
+			if (inTx) return db.transaction((tx) => fn(this.wrapWith(tx, inTx)));
+			const touched = [];
+			try {
+				return await db.transaction((tx) => fn(this.wrapWith(tx, touched)));
+			} finally {
+				this.rewritten(touched);
+			}
+		};
+		return adapter;
+	}
+};
+//#endregion
+export { ChangeLog, ChangeTracker, ValueCache, freeze, trackedReads };

package/dist/core/cluster.d.ts

@@ -52,9 +52,13 @@ export declare class StreamManager {
   private lastPos;
   private heartbeat;
   private positionCache;
+  private highestAllocated;
+  /** Called after a write of this instance completed, when the position may have moved (#50). */
+  onAdvance: () => void;
   private publishing;
   private nextPublish;
-  constructor(cluster: ClusterAdapter, instanceId: string);
+  private warn;
+  constructor(cluster: ClusterAdapter, instanceId: string, warn?: (...args: unknown[]) => void);
   private key;
   /** Publish this writer's state as it is when the publish starts; concurrent callers share it. */
   private flush;
@@ -64,8 +68,20 @@ export declare class StreamManager {
   write<T>(fn: (id: number) => Promise<T>): Promise<T>;
   /** A fresh decreasing position for backfilled (historical) events. */
   backfillId(): Promise<number>;
-  /** The highest position below which everything is persisted, cluster-wide. */
-  position(): Promise<number>;
+  /** The highest position this instance has allocated: an upper bound of its changes so far. */
+  get lastAllocated(): number;
+  /**
+   * The highest position below which everything is persisted, cluster-wide. `fresh` skips the
+   * 20 ms cache, for a caller that knows a change has completed elsewhere.
+   */
+  position(fresh?: boolean): Promise<number>;
+  /**
+   * Resolve once the position has reached `pos` (true), or false after `timeoutMs` or on abort.
+   * For a request woken by a change that another write in flight still keeps out of sight
+   * (https://github.com/k18k/matrix-nodejs-homeserver/issues/50). It checks again at growing
+   * intervals: writes finish in milliseconds, and the position may be held by another instance.
+   */
+  waitFor(pos: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
   advanceTo(value: number): Promise<void>;
   lowerBackfillTo(value: number): Promise<void>;
   stop(): Promise<void>;

package/dist/core/cluster.js

@@ -80,6 +80,11 @@ function localCluster() {
 }
 const WRITER_TTL_MS = 3e4;
 /**
+* A stream position held longer than this holds back /sync for everyone: it is logged with where
+* it was allocated (https://github.com/k18k/matrix-nodejs-homeserver/issues/48).
+*/
+const SLOW_LEASE_MS = 5e3;
+/**
 * Stream positions with multiple writers. Positions are allocated from a global
 * sequence; readers only see positions up to which every writer has finished, so
 * an event committed late with a lower position can never be skipped by /sync.
@@ -99,11 +104,16 @@ var StreamManager = class {
 	lastPos = 0;
 	heartbeat;
 	positionCache = null;
+	highestAllocated = 0;
+	/** Called after a write of this instance completed, when the position may have moved (#50). */
+	onAdvance = () => {};
 	publishing = Promise.resolve();
 	nextPublish = null;
-	constructor(cluster, instanceId) {
+	warn;
+	constructor(cluster, instanceId, warn = () => {}) {
 		this.cluster = cluster;
 		this.instanceId = instanceId;
+		this.warn = warn;
 		this.heartbeat = setInterval(() => void this.flush().catch(() => {}), WRITER_TTL_MS / 3);
 		this.heartbeat.unref?.();
 	}
@@ -146,10 +156,14 @@ var StreamManager = class {
 			await this.flush();
 			id = await this.cluster.nextId("stream");
 			this.inflight.add(id);
+			if (id > this.highestAllocated) this.highestAllocated = id;
 		} finally {
 			this.allocating--;
 		}
 		let finished = false;
+		const site = /* @__PURE__ */ new Error("stream position allocated here");
+		const slow = setTimeout(() => this.warn(`Stream position ${id} held for over ${SLOW_LEASE_MS} ms; /sync waits for it`, site), SLOW_LEASE_MS);
+		slow.unref?.();
 		const timer = setTimeout(() => void lease.done(), 6e4);
 		timer.unref?.();
 		const lease = {
@@ -158,9 +172,11 @@ var StreamManager = class {
 				if (finished) return;
 				finished = true;
 				clearTimeout(timer);
+				clearTimeout(slow);
 				this.inflight.delete(id);
 				await this.flush();
 				this.positionCache = null;
+				this.onAdvance();
 			}
 		};
 		return lease;
@@ -178,9 +194,16 @@ var StreamManager = class {
 	async backfillId() {
 		return -await this.cluster.nextId("backfill");
 	}
-	/** The highest position below which everything is persisted, cluster-wide. */
-	async position() {
-		if (this.positionCache && Date.now() - this.positionCache.at < 20) return this.positionCache.value;
+	/** The highest position this instance has allocated: an upper bound of its changes so far. */
+	get lastAllocated() {
+		return this.highestAllocated;
+	}
+	/**
+	* The highest position below which everything is persisted, cluster-wide. `fresh` skips the
+	* 20 ms cache, for a caller that knows a change has completed elsewhere.
+	*/
+	async position(fresh = false) {
+		if (!fresh && this.positionCache && Date.now() - this.positionCache.at < 20) return this.positionCache.value;
 		let pos = await this.cluster.currentId("stream");
 		for (const [, w] of await this.cluster.entries("writer:")) if (w?.busy) pos = Math.min(pos, w.pos);
 		if (this.inflight.size) pos = Math.min(pos, Math.min(...this.inflight) - 1);
@@ -190,6 +213,23 @@ var StreamManager = class {
 		};
 		return pos;
 	}
+	/**
+	* Resolve once the position has reached `pos` (true), or false after `timeoutMs` or on abort.
+	* For a request woken by a change that another write in flight still keeps out of sight
+	* (https://github.com/k18k/matrix-nodejs-homeserver/issues/50). It checks again at growing
+	* intervals: writes finish in milliseconds, and the position may be held by another instance.
+	*/
+	async waitFor(pos, timeoutMs, signal) {
+		const deadline = Date.now() + timeoutMs;
+		let delay = 5;
+		for (;;) {
+			if (await this.position(true) >= pos) return true;
+			const left = deadline - Date.now();
+			if (left <= 0 || signal?.aborted) return false;
+			await new Promise((resolve) => setTimeout(resolve, Math.min(delay, left)));
+			delay = Math.min(delay * 2, 200);
+		}
+	}
 	async advanceTo(value) {
 		await this.cluster.advance("stream", value);
 	}

package/dist/core/keys.js

@@ -438,8 +438,10 @@ var KeyService = class {
 				if (m.membership === "join") {
 					for (const u of members) if (u !== userId) changed.add(u);
 				} else for (const u of members) if (!sharing.has(u)) left.add(u);
-			} else if (m.membership === "join") changed.add(m.user_id);
-			else if (!sharing.has(m.user_id)) left.add(m.user_id);
+			} else if (m.membership === "join") {
+				const ev = await this.hs.rooms.getEvent(m.event_id);
+				if (ev && ev.stream > since) changed.add(m.user_id);
+			} else if (!sharing.has(m.user_id)) left.add(m.user_id);
 		}
 		for (const u of left) changed.delete(u);
 		return {

package/dist/core/notifier.d.ts

@@ -1,17 +1,63 @@
 import { ClusterAdapter } from "./cluster.js";
 //#region src/core/notifier.d.ts
+/** A registration for wake-ups from the moment it was made (see `Notifier.listen`). */
+export interface Listener {
+  /**
+   * The stream position of this user's latest wake-up before the listener was registered (0 if
+   * none is remembered): the change may not have been visible to the build that preceded it.
+   */
+  readonly recent: number;
+  /**
+   * Resolve with the position of the first wake-up since registration (at once if there was one
+   * already), or null after `timeoutMs` or on abort.
+   */
+  wait(timeoutMs: number, signal?: AbortSignal): Promise<number | null>;
+  /** Stop listening; a pending `wait` resolves with null. */
+  cancel(): void;
+}
 /**
  * Wakes long-polling `/sync` requests when something relevant happens. Notifications
  * are broadcast through the cluster adapter so waiters on other instances wake too.
+ *
+ * https://github.com/k18k/matrix-nodejs-homeserver/issues/50: every wake-up carries the stream
+ * position of its change, or an upper bound of it. Writes can complete out of order, so a change
+ * may be committed while an earlier write still holds the position below it. As in Synapse
+ * (`Notifier._notify_pending_new_room_events`), such a wake-up is held here until the position
+ * reaches it: a request is only woken for changes it can see.
  */
 export declare class Notifier {
-  private waiters;
+  private listeners;
+  /** Each user's latest wake-up position, oldest first (re-inserted on update). */
+  private recent;
   private cluster;
   private instanceId;
-  constructor(cluster: ClusterAdapter, instanceId: string);
-  notify(userIds: Iterable<string>): void;
+  private lastAllocated;
+  private position;
+  /** Wake-ups whose change is beyond the position known to be visible. */
+  private held;
+  /** The highest position known to be visible. */
+  private visible;
+  private release;
+  /**
+   * `lastAllocated`: the highest stream position this instance has allocated (an upper bound of
+   * its changes); `position`: the position below which everything is visible.
+   */
+  constructor(cluster: ClusterAdapter, instanceId: string, lastAllocated?: () => number, position?: (fresh: boolean) => Promise<number>);
+  /**
+   * Wake `userIds`. `pos` is the stream position of the change; without it, the highest position
+   * this instance has allocated stands in, which is never below it.
+   */
+  notify(userIds: Iterable<string>, pos?: number): void;
+  /** The position may have moved (a write of this instance completed): release what it covers. */
+  advanced(): void;
+  /** Wake now if the change is visible, otherwise once the position reaches it. */
+  private hold;
+  private scheduleRelease;
+  private releaseHeld;
   private wakeLocal;
   notifyAll(): void;
+  listen(userId: string): Listener;
+  /** Wait for a wake-up of `userId` (for callers that do not track positions). */
   wait(userId: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
 }
 //#endregion