@supalive/core 1.20.0 → 1.20.2

package/dist/sub-worker-dispatch-Ci_z8w10.js

@@ -0,0 +1,792 @@
+import { r as supaliveStringify } from "./helper-zdJT5FUc.js";
+import { a as mapWriteSetToRaw, i as mapReadSetToRaw, n as checkWriteSetAffectsReadSet, r as evaluateCacheFreshness } from "./overlap-checker-CCgq_Tpa.js";
+import { b as WriteEntrySchema, m as QueryCacheMetadataSchema, n as BigIntSchema, p as QueryCacheEntrySchema, r as CachedPgMetadataSchema, y as ReadEntrySchema } from "./types_db-OUou3o2Z.js";
+import { t as MySqlDatabase } from "./mysql-BX3cm94v.js";
+import { t as PgDatabase } from "./postgres-DwiUT_A6.js";
+import { i as logger$1, o as SupaliveDb, r as logLevelOf } from "./logger-DrXccWFZ.js";
+import z from "zod";
+import { ExponentialBackoff, handleAll, retry } from "cockatiel";
+import { createHash } from "node:crypto";
+import Redis from "ioredis";
+//#region src/server/retention-watermark.ts
+/** Redis pub/sub channel the sub-manager publishes the retention watermark on
+* after each prune (and at startup). App-server instances subscribe and update
+* their in-memory {@link RetentionWatermark}. Payload is the watermark `ts` as a
+* string. */
+const RETENTION_WATERMARK_CHANNEL = "supalive:retention_watermark";
+/**
+* In-memory holder for the commit-log retention watermark: the oldest commit-log
+* ts still retained after prune (see {@link Database.getMinSnapshotTimestamp}).
+* Read on the hot path by the query-cache freshness check — a plain variable, no
+* per-check Redis/DB round trip. Loaded once at startup from the `metadata`
+* table and kept fresh out-of-band: the sub-manager broadcasts the new watermark
+* (in-process to its workers, over Redis pub/sub to app servers) each time it
+* prunes.
+*
+* `set` is monotonic — the watermark only ever moves forward (pruning never
+* un-deletes rows), so an out-of-order or stale update can never lower it, which
+* keeps the freshness guard on the safe side (an over-estimate only costs an
+* extra recompute; an under-estimate could serve stale data).
+*
+* Initial value is the -1n genesis (not 0), matching `getMinSnapshotTimestamp`
+* and the empty-DB snapshot ts — so before anything is pruned the guard never
+* rejects a genesis-era entry (whose snapshot is -1).
+*/
+var RetentionWatermark = class {
+	ts = -1n;
+	get() {
+		return this.ts;
+	}
+	set(ts) {
+		if (ts > this.ts) this.ts = ts;
+	}
+	/** Seed from the persisted watermark (metadata table). Returns the current value. */
+	async loadFrom(db) {
+		this.set(await db.getMinSnapshotTimestamp());
+		return this.ts;
+	}
+};
+//#endregion
+//#region src/server/sub-manager-types.ts
+const RegisterSubscriptionParamsSchema = z.object({
+	/**
+	* Caller-computed FNV-1a routing key + identity for this subscription.
+	* The sub-manager trusts these values rather than re-deriving them from
+	* (queryName, args, queryIdentity); this avoids one stringify+SHA1 per
+	* register RPC. Trust is fine: the sub-manager RPC channel is fully
+	* internal.
+	*/
+	subId: z.string(),
+	cacheKey: z.string(),
+	queryName: z.string(),
+	args: z.unknown(),
+	/**
+	* Segmentation key used in the subId/cacheKey hash. Defaults to the
+	* authenticated user's id ("anonymous" when none), unless the
+	* procedure overrides it via `QueryConfig.queryIdentity`.
+	*/
+	queryIdentity: z.string(),
+	instanceName: z.string(),
+	lastSnapshotTs: BigIntSchema
+});
+const RegisterSubscriptionResultSchema = z.object({
+	cacheKey: z.string(),
+	recompute: z.boolean(),
+	readSet: z.array(ReadEntrySchema),
+	version: z.string().optional()
+});
+const RegisterSubscriptionBatchParamsSchema = z.array(RegisterSubscriptionParamsSchema);
+const RegisterSubscriptionBatchResultSchema = z.array(RegisterSubscriptionResultSchema);
+const UpdateSubscriptionReadSetParamsSchema = z.object({
+	cacheKey: z.string(),
+	subId: z.string(),
+	instanceName: z.string(),
+	lastSnapshotTs: BigIntSchema,
+	readSet: z.array(ReadEntrySchema)
+});
+/**
+* `tracked: false` means the sub-manager has no record of this subId (e.g.
+* a restart wiped state and the caller hasn't re-registered yet). The app
+* server should treat this as a signal to register the sub before retrying.
+*/
+const UpdateSubscriptionReadSetResultSchema = z.object({ tracked: z.boolean() });
+const UnregisterSubscriptionParamsSchema = z.object({
+	subId: z.string(),
+	instanceName: z.string()
+});
+const UnregisterSubscriptionsParamsSchema = z.array(UnregisterSubscriptionParamsSchema);
+const UnregisterSubscriptionResultSchema = z.object({ ok: z.boolean() });
+const UnregisterSubscriptionsResultSchema = z.array(z.object({ ok: z.boolean() }));
+const InvalidateWritesetParamsSchema = z.object({ writeSet: z.array(WriteEntrySchema) });
+const AffectedSubscriptionSchema = z.object({
+	subId: z.string(),
+	queryName: z.string(),
+	args: z.unknown(),
+	cacheKey: z.string(),
+	/**
+	* Every live instance that currently holds this subId. Routing rules:
+	*   • If the writer is in this list, it recomputes locally and publishes
+	*     an `update` to the rest (its own id is filtered by the publisher).
+	*   • Otherwise the writer broadcasts a `recompute-race` to every entry;
+	*     receivers race for a Redis lock and the winner recomputes.
+	*/
+	notifyInstances: z.array(z.string())
+});
+const InvalidateWritesetResultSchema = z.object({ affected: z.array(AffectedSubscriptionSchema) });
+const RegistrationRecordSchema = z.object({
+	queryName: z.string(),
+	args: z.unknown(),
+	queryIdentity: z.string(),
+	cacheKey: z.string()
+});
+//#endregion
+//#region src/db/cache.ts
+const logger = logger$1.child({ "name": "CACHE_LAYER" }, { level: logLevelOf("SERVER_LOG_LEVEL") });
+const redisRetryPolicy = retry(handleAll, {
+	maxAttempts: 3,
+	backoff: new ExponentialBackoff({
+		initialDelay: 5,
+		maxDelay: 2300,
+		exponent: 2
+	})
+});
+/** Atomic one-shot recompute write: set data + metadata iff incoming version
+*  (ARGV[3]) is not older than the stored one. KEYS: data, meta. */
+const WRITE_DATA_AND_META = `
+local cur = redis.call('GET', KEYS[2])
+if cur then
+  local ok, m = pcall(cjson.decode, cur)
+  if ok and type(m) == 'table' and m.version and tonumber(ARGV[3]) < tonumber(m.version) then
+    return 0
+  end
+end
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[4]))
+redis.call('SET', KEYS[2], ARGV[2], 'EX', tonumber(ARGV[4]))
+return 1`;
+/** Data-only write (subscribe path): set data iff incoming version (ARGV[2]) is
+*  not older than the stored metadata's version. KEYS: data, meta. */
+const WRITE_DATA_ONLY = `
+local cur = redis.call('GET', KEYS[2])
+if cur then
+  local ok, m = pcall(cjson.decode, cur)
+  if ok and type(m) == 'table' and m.version and tonumber(ARGV[2]) < tonumber(m.version) then
+    return 0
+  end
+end
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[3]))
+return 1`;
+/** Metadata-only replace (subscription recompute): set meta iff incoming version
+*  (ARGV[2]) is not older than the stored one. KEYS: meta. */
+const REPLACE_META = `
+local cur = redis.call('GET', KEYS[1])
+if cur then
+  local ok, m = pcall(cjson.decode, cur)
+  if ok and type(m) == 'table' and m.version and tonumber(ARGV[2]) < tonumber(m.version) then
+    return 0
+  end
+end
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[3]))
+return 1`;
+/** Metadata-only horizon advance (still-fresh subscription): bump lastSnapshotTs
+*  ONLY, without recomputing. Applies ARGV[1] iff the new horizon (ARGV[2]) is
+*  strictly ahead of the stored one AND no newer computation (stored.version >
+*  ARGV[3], the version the caller based its advance on) has landed meanwhile —
+*  so an advance never reverts a fresh recompute. KEYS: meta. */
+const ADVANCE_META = `
+local cur = redis.call('GET', KEYS[1])
+if not cur then return 0 end
+local ok, m = pcall(cjson.decode, cur)
+if not ok or type(m) ~= 'table' then return 0 end
+if tonumber(ARGV[2]) <= tonumber(m.lastSnapshotTs) then return 0 end
+if m.version and tonumber(m.version) > tonumber(ARGV[3]) then return 0 end
+redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[4]))
+return 1`;
+var CacheLayer = class {
+	redis;
+	ttlSeconds;
+	/** Cached EVALSHA digests keyed by Lua source (see evalScript). */
+	scriptShaCache = /* @__PURE__ */ new Map();
+	constructor(redis, ttlSeconds = 3600) {
+		this.redis = redis;
+		this.ttlSeconds = ttlSeconds;
+	}
+	/**
+	* Run a Lua script via EVALSHA using the script's SHA1 (computed locally — the
+	* same digest Redis keys scripts by, so no SCRIPT LOAD round-trip is needed on
+	* the hot path). On NOSCRIPT (the script isn't in Redis's cache yet, e.g. first
+	* use or after a Redis restart/failover) load it explicitly via SCRIPT LOAD and
+	* re-run via EVALSHA — so the script ends up cached server-side and subsequent
+	* EVALSHA calls hit. The runtime client is always ioredis (see initCacheLayer).
+	*/
+	async evalScript(src, keys, args) {
+		const redis = this.redis;
+		let sha = this.scriptShaCache.get(src);
+		if (!sha) {
+			sha = createHash("sha1").update(src).digest("hex");
+			this.scriptShaCache.set(src, sha);
+		}
+		return redisRetryPolicy.execute(async () => {
+			try {
+				return await redis.evalsha(sha, keys.length, ...keys, ...args);
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("NOSCRIPT")) {
+					const loadedSha = await redis.call("SCRIPT", "LOAD", src);
+					this.scriptShaCache.set(src, loadedSha);
+					return await redis.evalsha(loadedSha, keys.length, ...keys, ...args);
+				}
+				throw err;
+			}
+		});
+	}
+	/** One-shot recompute: atomically write data + metadata (CAS on version). */
+	async setQueryCacheAndMetadataFor(cacheKey, data, metaData, ttlSeconds) {
+		const ttl = ttlSeconds ?? this.ttlSeconds;
+		const dataJson = supaliveStringify({
+			data,
+			version: metaData.version,
+			lastSnapshotTs: metaData.lastSnapshotTs
+		});
+		const metaJson = supaliveStringify(metaData);
+		await this.evalScript(WRITE_DATA_AND_META, [this.getQueryCacheDataKey(cacheKey), this.getQeruyCacheMetaKey(cacheKey)], [
+			dataJson,
+			metaJson,
+			metaData.version,
+			String(ttl)
+		]);
+	}
+	/** Subscribe path: write the data blob only (CAS against the metadata's
+	*  version). The metadata is written separately by the sub-worker; the
+	*  `version` links the two so a divergent pair is detected on read. Takes the
+	*  snapshot ts directly (rather than a pre-stringified version) so the entry
+	*  can carry `lastSnapshotTs` as its own field; `version` is derived from it,
+	*  preserving the `version === String(ts)` convention the CAS relies on. */
+	async setQueryCacheFor(cacheKey, data, lastSnapshotTs, ttlSeconds) {
+		const ttl = ttlSeconds ?? this.ttlSeconds;
+		const version = String(lastSnapshotTs);
+		const dataJson = supaliveStringify({
+			data,
+			version,
+			lastSnapshotTs
+		});
+		await this.evalScript(WRITE_DATA_ONLY, [this.getQueryCacheDataKey(cacheKey), this.getQeruyCacheMetaKey(cacheKey)], [
+			dataJson,
+			version,
+			String(ttl)
+		]);
+	}
+	async getQueryCacheFor(cacheKey) {
+		const dataRaw = await redisRetryPolicy.execute(() => this.redis.get(this.getQueryCacheDataKey(cacheKey)));
+		if (!dataRaw) return null;
+		try {
+			const parsed = typeof dataRaw === "string" ? JSON.parse(dataRaw) : dataRaw;
+			return QueryCacheEntrySchema.parse(parsed);
+		} catch {
+			return null;
+		}
+	}
+	/** Subscription recompute: replace the whole metadata (CAS on version). */
+	async replaceQueryCacheMetadata(cacheKey, metaData, ttlSeconds) {
+		const ttl = ttlSeconds ?? this.ttlSeconds;
+		const metaJson = supaliveStringify(metaData);
+		await this.evalScript(REPLACE_META, [this.getQeruyCacheMetaKey(cacheKey)], [
+			metaJson,
+			metaData.version,
+			String(ttl)
+		]);
+	}
+	/** Still-fresh subscription: advance `lastSnapshotTs` only, preserving the
+	*  data's `version` + `readSet` (no recompute). Monotonic and non-clobbering
+	*  — see ADVANCE_META. `metaData` carries the new horizon plus the version +
+	*  readSet the caller read, which the script keeps unless a newer computation
+	*  has since landed. */
+	async advanceQueryCacheMetadata(cacheKey, metaData, ttlSeconds) {
+		const ttl = ttlSeconds ?? this.ttlSeconds;
+		const metaJson = supaliveStringify(metaData);
+		await this.evalScript(ADVANCE_META, [this.getQeruyCacheMetaKey(cacheKey)], [
+			metaJson,
+			String(metaData.lastSnapshotTs),
+			metaData.version,
+			String(ttl)
+		]);
+	}
+	async getQueryCacheMetaData(cacheKey) {
+		const dataRaw = await redisRetryPolicy.execute(() => this.redis.get(this.getQeruyCacheMetaKey(cacheKey)));
+		if (!dataRaw) return null;
+		try {
+			const parsed = typeof dataRaw === "string" ? JSON.parse(dataRaw) : dataRaw;
+			return QueryCacheMetadataSchema.parse(parsed);
+		} catch {
+			return null;
+		}
+	}
+	async persistRegistrationRecord(subId, record) {
+		const data = supaliveStringify(record);
+		await redisRetryPolicy.execute(() => this.redis.set(this.getRegistrationKey(subId), data));
+	}
+	async deleteRegistrationRecord(subId) {
+		await redisRetryPolicy.execute(() => this.redis.del(this.getRegistrationKey(subId)));
+	}
+	async deleteRegistrationsRecord(subIds) {
+		if (subIds.length === 0) return;
+		await redisRetryPolicy.execute(() => this.redis.del(...subIds.map((subId) => this.getRegistrationKey(subId))));
+	}
+	async fetchRegistrationRecordsBatch(subIds) {
+		const result = /* @__PURE__ */ new Map();
+		const CHUNK_SIZE = 100;
+		for (let i = 0; i < subIds.length; i += CHUNK_SIZE) {
+			const chunk = subIds.slice(i, i + CHUNK_SIZE);
+			const keys = chunk.map((id) => `sl:reg:${id}`);
+			try {
+				if (keys.length === 0) continue;
+				const rawValues = await redisRetryPolicy.execute(() => this.redis.mget(...keys));
+				for (let j = 0; j < chunk.length; j++) {
+					const subId = chunk[j];
+					const raw = rawValues[j];
+					const rawJson = typeof raw === "string" ? JSON.parse(raw) : raw;
+					if (!raw) result.set(subId, null);
+					else try {
+						const parsed = RegistrationRecordSchema.parse(rawJson);
+						result.set(subId, parsed);
+					} catch {
+						logger.error(`Failed to parse sl:reg:${subId} during batch recovery`);
+						result.set(subId, null);
+					}
+				}
+			} catch (err) {
+				logger.error(err, "Failed to fetch registration records batch");
+				for (const subId of chunk) result.set(subId, null);
+			}
+		}
+		return result;
+	}
+	async getCachedTableColumnTypes(key) {
+		const dataRaw = await redisRetryPolicy.execute(() => this.redis.get(key));
+		if (!dataRaw) return null;
+		try {
+			const parsed = typeof dataRaw === "string" ? JSON.parse(dataRaw) : dataRaw;
+			return CachedPgMetadataSchema.parse(parsed);
+		} catch {
+			return null;
+		}
+	}
+	async setCachedTableColumnsTypes(key, value) {
+		await redisRetryPolicy.execute(() => this.redis.set(key, supaliveStringify(value)));
+	}
+	/**
+	* Race participant: try to claim `lock:recompute:<subId>:<commitTs>`
+	* with `SET NX EX`. The single Redis round-trip both arbitrates and
+	* sets a TTL fallback in case the winner crashes mid-recompute.
+	*/
+	async tryAcquireRecomputeLock(instanceId, subId, commitTs, ttl) {
+		const key = `lock:recompute:${subId}:${commitTs}`;
+		return redisRetryPolicy.execute(async () => {
+			try {
+				return await this.redis.set(key, instanceId, "EX", ttl, "NX") === "OK";
+			} catch (err) {
+				logger.error(err, `Failed to acquire recompute lock ${key}`);
+				return false;
+			}
+		});
+	}
+	getRegistrationKey(subId) {
+		return `sl:reg:${subId}`;
+	}
+	getQueryCacheDataKey(cacheKey) {
+		return `sl:cache:${cacheKey}`;
+	}
+	getQeruyCacheMetaKey(cacheKey) {
+		return `sl:meta:${cacheKey}`;
+	}
+};
+//#endregion
+//#region src/db/init_db.ts
+/**
+* Current core runtime-bootstrap version. Bump this whenever core needs a new
+* runtime database operation — a data seed, a backfill, or a schema change that
+* must be applied directly at runtime rather than through the migration
+* pipeline. Each increment adds a case to `Database.coreMigrationStatements`.
+*
+* The core *schema* (the `commit_logs`/`metadata` tables and the
+* `global_commit_ts` sequence/counter) is NOT versioned here — it comes from
+* the generated schema (`coreTablesSql` / `generateSchemaSql`), which must be
+* applied to the database BEFORE `initCore` runs.
+*/
+const CORE_VERSION = 1n;
+/**
+* Bring the core runtime state up to {@link CORE_VERSION}. Idempotent and safe
+* to call from every process at startup: a lock-free version read short-circuits
+* the common "already current" case, and the actual migration runs under a
+* cross-process lock with a re-check so only one process applies it.
+*
+* Assumes the core schema already exists (apply the generated schema first);
+* the `metadata` table is where the version and seed rows live.
+*/
+async function initCore(db) {
+	if (await db.getCoreVersion() >= 1n) return;
+	await db.withCoreInitLock(async (ctx) => {
+		const from = await ctx.getVersion();
+		if (from >= 1n) return;
+		for (let v = from + 1n; v <= CORE_VERSION; v++) {
+			const statements = db.coreMigrationStatements(v);
+			logger$1.info(`Migrating core schema ${v - 1n} -> ${v} (${statements.length} statements)`);
+			for (const sql of statements) await ctx.exec(sql);
+		}
+		await ctx.setVersion(CORE_VERSION);
+		logger$1.info(`Core schema now at version ${CORE_VERSION}`);
+	});
+}
+/**
+* Default and env override for the per-statement DB timeout. PG enforces
+* this via `statement_timeout` (server cancels), MySQL via the per-query
+* `timeout` option (driver issues KILL QUERY). Set 0 to disable.
+*/
+const DB_QUERY_TIMEOUT_MS = Number(process.env.SUPALIVE_DB_QUERY_TIMEOUT_MS ?? 3e4);
+async function initDatabase(options) {
+	const impl = createDatabase(options.DbConfig, options.workerId);
+	const replicaImpl = options.ReplicaDbConfig ? createDatabase(options.ReplicaDbConfig, options.workerId) : void 0;
+	const supaliveDb = SupaliveDb.create({
+		db: impl,
+		replica: replicaImpl
+	});
+	await initCore(impl);
+	await bootstrapDbTypes(supaliveDb, options.CacheLayer, options.forceBootstrapReload ?? false);
+	return supaliveDb;
+}
+function createDatabase(config, workerId) {
+	const bindings = { "db": config.type };
+	if (workerId) bindings["worker"] = workerId;
+	if (config.type === "postgres") return new PgDatabase(logger$1.child(bindings), {
+		...config,
+		connectionString: config.connectionString,
+		min: config.minConnections ?? 0,
+		max: config.maxConnections ?? 20,
+		connectionTimeoutMillis: config.connectionTimeoutMillis ?? 15e3,
+		idleTimeoutMillis: config.idleTimeoutMillis ?? 3e4,
+		statement_timeout: DB_QUERY_TIMEOUT_MS > 0 ? DB_QUERY_TIMEOUT_MS : void 0
+	});
+	else return new MySqlDatabase(logger$1.child(bindings), {
+		uri: config.connectionString,
+		supportBigNumbers: true,
+		connectionLimit: config.maxConnections ?? 20,
+		connectTimeout: config.connectionTimeoutMillis ?? 15e3,
+		idleTimeout: config.idleTimeoutMillis ?? 3e4,
+		queueLimit: config.queueLimit ?? 0,
+		timezone: "Z",
+		queryTimeoutMs: DB_QUERY_TIMEOUT_MS
+	});
+}
+/**
+* Eagerly load column types into the apply-path cache at server start.
+* In production, the result is cached in Redis under
+* `supalive:schema:types:${app_migration}` (the applied-migration marker from
+* the `metadata` table, via {@link Database.getAppMigration}) so other
+* instances starting cold can skip the pg_attribute round-trip — and a schema
+* migration bumps that marker, so the key changes and stale types aren't
+* reused. In any
+* other env we go straight to PG every time so local schema iteration
+* is never blocked by stale Redis state. Migrations should publish a
+* `schema:reload` message (see {@link publishSchemaReload}) after
+* applying DDL — every instance picks that up and re-bootstraps.
+*/
+async function bootstrapDbTypes(db, cache, forceReload = false) {
+	if (db.impl.dbType === "mysql") return;
+	const inProd = process.env.NODE_ENV === "production";
+	const key = `supalive:schema:types:${await db.impl.getAppMigration()}`;
+	try {
+		await db.impl.bootstrapColumnTypes({
+			cacheKey: key,
+			redis: inProd && !forceReload ? cache : void 0
+		});
+		logger$1.info({ columnsTypes: db.impl.columnTypes }, `Bootstrapped db column types (redis=${inProd}, key=${key})`);
+	} catch (err) {
+		logger$1.error(err, "Failed to bootstrap db column types");
+		throw err;
+	}
+}
+function initCacheLayer(config) {
+	const redis = new Redis(config.upstash.redisUrl, {
+		connectTimeout: config.connectionTimeout ?? 15e3,
+		maxRetriesPerRequest: config.commandMaxRetries ?? 1,
+		keepAlive: 1e4
+	});
+	const redisSub = config.createSubClient ? new Redis(config.upstash.redisUrl, {
+		connectTimeout: config.connectionTimeout ?? 15e3,
+		maxRetriesPerRequest: config.commandSubMaxRetries ?? 5,
+		disableClientInfo: true,
+		retryStrategy: (times) => {
+			if (times > 5) return null;
+			return Math.min(times * 200, 2e3);
+		}
+	}) : void 0;
+	return {
+		cacheLayer: new CacheLayer(redis, config.cacheTtlSeconds ?? 3600),
+		redisSubClient: redisSub
+	};
+}
+//#endregion
+//#region src/server/sub-worker.ts
+var SubscriptionWorker = class {
+	id;
+	subscriptions = /* @__PURE__ */ new Map();
+	cache;
+	db;
+	retentionWatermark = new RetentionWatermark();
+	logger;
+	constructor(id, cache, db) {
+		this.id = id;
+		this.cache = cache;
+		this.db = db;
+		this.logger = logger$1.child({
+			name: "SUBS_WRK",
+			wid: id
+		}, { level: logLevelOf("SUBS_MANAGER_SERVER_LOG_LEVEL") });
+	}
+	size() {
+		return this.subscriptions.size;
+	}
+	has(subId) {
+		return this.subscriptions.has(subId);
+	}
+	/**
+	* Lowest `lastSnapshotTs` across this worker's subscriptions, or `null`
+	* when there are none. Used by the dispatcher to derive a safe prune watermark.
+	*/
+	minSubscriptionTs() {
+		let min = null;
+		for (const sub of this.subscriptions.values()) if (min === null || sub.lastSnapshotTs < min) min = sub.lastSnapshotTs;
+		return min;
+	}
+	/**
+	* Seed/repair the persisted retained watermark from the actual oldest retained
+	* commit log (`min(ts)`), then load it into memory and broadcast it. Called
+	* once at sub-manager startup — the `min(ts)` scan is off the hot path, and
+	* it corrects `metadata.min_retained_ts` even for a DB that was pruned before
+	* this feature existed. Returns the resulting watermark so the manager can
+	* broadcast it to the other workers.
+	*/
+	async refreshRetentionWatermark() {
+		const real = await this.db.getMinCommitLogTs() ?? 0n;
+		await this.db.updateMinSnapshotTimestamp(real);
+		const persisted = await this.db.getMinSnapshotTimestamp();
+		this.retentionWatermark.set(persisted);
+		await this.publishRetentionWatermark(persisted);
+		return this.retentionWatermark.get();
+	}
+	/** Adopt a watermark broadcast by the manager (in-process from the pruning
+	* worker). Monotonic, so an out-of-order message can't lower it. */
+	setRetentionWatermark(ts) {
+		this.retentionWatermark.set(ts);
+	}
+	/**
+	* Prune commit logs older than `minRetainedTs`. Advertises the new watermark FIRST —
+	* persist it, bump our in-memory copy, and broadcast it over Redis — and only
+	* then deletes, so no reader ever trusts a cache entry whose freshness scan
+	* would include rows we're about to remove. Returns rows deleted.
+	*/
+	async prune(minRetainedTs) {
+		await this.db.updateMinSnapshotTimestamp(minRetainedTs);
+		this.retentionWatermark.set(minRetainedTs);
+		await this.publishRetentionWatermark(minRetainedTs);
+		return await this.db.pruneCommitLogsBefore(minRetainedTs);
+	}
+	/** Broadcast the watermark to app-server instances over Redis pub/sub. Workers in
+	* this process get it in-process via {@link setRetentionWatermark}. */
+	async publishRetentionWatermark(ts) {
+		try {
+			await this.cache.redis.publish(RETENTION_WATERMARK_CHANNEL, ts.toString());
+		} catch (err) {
+			this.logger.error(err, "failed to publish commit-log watermark");
+		}
+	}
+	async register(params) {
+		const { subId, cacheKey, queryName, args, queryIdentity, instanceName, lastSnapshotTs } = params;
+		this.logger.info(`registering subscription: ${subId} from ${instanceName}`);
+		const existing = this.subscriptions.get(subId);
+		if (existing && !existing.timeout) {
+			existing.instances.add(instanceName);
+			return {
+				cacheKey,
+				recompute: false,
+				readSet: existing.readSet
+			};
+		}
+		if (existing?.timeout) {
+			this.logger.info(`reactivating subscription: ${subId} from: ${instanceName}`);
+			clearTimeout(existing.timeout);
+			existing.timeout = null;
+		}
+		const metadata = await this.cache.getQueryCacheMetaData(cacheKey);
+		const freshness = await evaluateCacheFreshness(this.db, metadata, lastSnapshotTs, this.retentionWatermark.get());
+		let needsRecompute = !freshness.fresh;
+		const readSet = freshness.readSet;
+		const rawReadSet = freshness.rawReadSet;
+		if (!needsRecompute && metadata && lastSnapshotTs > metadata.lastSnapshotTs) this.cache.advanceQueryCacheMetadata(cacheKey, {
+			lastSnapshotTs,
+			version: metadata.version,
+			readSet
+		}).catch((err) => this.logger.error(err, `Failed to advance cache metadata for ${cacheKey}`));
+		let newSubscription = {
+			subId,
+			queryName,
+			args,
+			cacheKey,
+			lastSnapshotTs,
+			readSet,
+			rawReadSet,
+			instances: /* @__PURE__ */ new Set([instanceName]),
+			timeout: null
+		};
+		const createdWhileChecking = this.subscriptions.get(subId);
+		if (createdWhileChecking) {
+			if (createdWhileChecking.timeout) {
+				clearTimeout(createdWhileChecking.timeout);
+				createdWhileChecking.timeout = null;
+			}
+			if (createdWhileChecking.lastSnapshotTs > lastSnapshotTs) {
+				newSubscription = {
+					...newSubscription,
+					...createdWhileChecking,
+					instances: /* @__PURE__ */ new Set([...createdWhileChecking.instances, instanceName])
+				};
+				needsRecompute = false;
+			}
+		}
+		this.subscriptions.set(subId, newSubscription);
+		this.persistRegistration(subId, {
+			queryName,
+			args,
+			queryIdentity,
+			cacheKey
+		});
+		return {
+			cacheKey,
+			recompute: needsRecompute,
+			readSet,
+			version: metadata?.version
+		};
+	}
+	async updateReadSet(params) {
+		const { cacheKey, subId, instanceName, lastSnapshotTs, readSet } = params;
+		this.logger.info(`updating subscription readSet: ${subId} from ${instanceName}`);
+		const existing = this.subscriptions.get(subId);
+		if (!existing) return { tracked: false };
+		if (lastSnapshotTs < existing.lastSnapshotTs) return { tracked: true };
+		const rawReadSet = mapReadSetToRaw(readSet);
+		this.subscriptions.set(subId, {
+			...existing,
+			readSet,
+			rawReadSet,
+			lastSnapshotTs
+		});
+		await this.cache.replaceQueryCacheMetadata(cacheKey, {
+			lastSnapshotTs,
+			version: String(lastSnapshotTs),
+			readSet
+		});
+		return { tracked: true };
+	}
+	async unregister(params, jitter = 0) {
+		const { subId, instanceName } = params;
+		this.logger.info(`unregistering subscription: ${subId} from: ${instanceName}`);
+		const sub = this.subscriptions.get(subId);
+		if (!sub) return { ok: true };
+		if (sub.timeout) clearTimeout(sub.timeout);
+		if (sub.instances.size > 1) {
+			sub.instances.delete(instanceName);
+			return { ok: true };
+		}
+		this.logger.debug(`scheduling unregister subscription: ${subId} from: ${instanceName} in 15s`);
+		sub.timeout = setTimeout(async () => {
+			sub.instances.delete(instanceName);
+			if (sub.instances.size === 0) {
+				this.logger.info(`unregistered subscription: ${subId} from: ${instanceName}`);
+				this.subscriptions.delete(subId);
+				await this.deleteRegistration(subId);
+			}
+		}, 15e3 + jitter);
+		return { ok: true };
+	}
+	async unregisters(params) {
+		this.logger.info({ subIds: params }, `scheduling unregistering subscriptions`);
+		for (const param of params) this.unregister(param, Math.floor(Math.random() * 100));
+		return params.map(() => ({ ok: true }));
+	}
+	/**
+	* Synchronous, CPU-bound. Scans this worker's slice of subscriptions and
+	* returns the ones affected by the writeSet.
+	*/
+	invalidate(rawWriteSet) {
+		const affected = [];
+		for (const [, sub] of this.subscriptions) {
+			if (sub.instances.size === 0) continue;
+			if (!checkWriteSetAffectsReadSet(rawWriteSet, sub.rawReadSet)) continue;
+			affected.push({
+				subId: sub.subId,
+				queryName: sub.queryName,
+				args: sub.args,
+				cacheKey: sub.cacheKey,
+				notifyInstances: Array.from(sub.instances)
+			});
+		}
+		return affected;
+	}
+	async persistRegistration(subId, record) {
+		try {
+			await this.cache.persistRegistrationRecord(subId, record);
+		} catch (err) {
+			this.logger.error(err, `[worker ${this.id}] Failed to persist registration for ${subId}`);
+		}
+	}
+	async deleteRegistration(subId) {
+		try {
+			await this.cache.deleteRegistrationRecord(subId);
+		} catch (err) {
+			this.logger.error(err, `[worker ${this.id}] Failed to delete registration for ${subId}`);
+		}
+	}
+};
+//#endregion
+//#region src/server/sub-worker-dispatch.ts
+/**
+* Dispatch a single worker operation against an already-constructed
+* {@link SubscriptionWorker} + {@link Database}. Shared by:
+*
+*   • the worker-thread entry (`subscription-manager-worker-entry.ts`), where
+*     the payload just crossed a `postMessage` boundary and is untrusted, so it
+*     is Zod-parsed against the matching schema; and
+*   • the in-process {@link InlineWorkerHandle}, where the payload is the
+*     manager's own already-typed object (no thread hop, no structured-clone) —
+*     `trusted: true` skips the redundant parse so the call goes straight
+*     through to the worker method.
+*
+* `MsgType.Init` is NOT handled here: it constructs the worker/db, which is
+* bootstrap logic owned by each caller (the thread entry builds its own pool;
+* the inline handle is handed live instances).
+*/
+async function dispatchWorkerMessage(worker, db, type, payload, opts) {
+	const trusted = opts?.trusted ?? false;
+	switch (type) {
+		case 2: {
+			const params = trusted ? payload : RegisterSubscriptionParamsSchema.parse(payload);
+			return worker.register(params);
+		}
+		case 3: {
+			const params = trusted ? payload : RegisterSubscriptionBatchParamsSchema.parse(payload);
+			return Promise.all(params.map((p) => worker.register(p)));
+		}
+		case 4: {
+			const params = trusted ? payload : UpdateSubscriptionReadSetParamsSchema.parse(payload);
+			return worker.updateReadSet(params);
+		}
+		case 5: {
+			const params = trusted ? payload : UnregisterSubscriptionParamsSchema.parse(payload);
+			return worker.unregister(params);
+		}
+		case 6: {
+			const params = trusted ? payload : UnregisterSubscriptionsParamsSchema.parse(payload);
+			return worker.unregisters(params);
+		}
+		case 7: {
+			const { writeSet } = trusted ? payload : InvalidateWritesetParamsSchema.parse(payload);
+			return worker.invalidate(mapWriteSetToRaw(writeSet));
+		}
+		case 8: return worker.minSubscriptionTs();
+		case 9: return db.getLatestSnapshotTimestamp();
+		case 10: return worker.prune(payload);
+		case 12: return worker.refreshRetentionWatermark();
+		case 13:
+			worker.setRetentionWatermark(payload);
+			return null;
+		case 11:
+			try {
+				await db.close();
+			} catch (_) {}
+			return null;
+		case 1: throw new Error("MsgType.Init must be handled by the caller (worker bootstrap)");
+		default: throw new Error(`Unknown MsgType: ${type}`);
+	}
+}
+//#endregion
+export { RetentionWatermark as S, UnregisterSubscriptionResultSchema as _, bootstrapDbTypes as a, UpdateSubscriptionReadSetResultSchema as b, initCore as c, InvalidateWritesetParamsSchema as d, InvalidateWritesetResultSchema as f, UnregisterSubscriptionParamsSchema as g, RegisterSubscriptionResultSchema as h, DB_QUERY_TIMEOUT_MS as i, initDatabase as l, RegisterSubscriptionParamsSchema as m, SubscriptionWorker as n, createDatabase as o, RegisterSubscriptionBatchResultSchema as p, CORE_VERSION as r, initCacheLayer as s, dispatchWorkerMessage as t, CacheLayer as u, UnregisterSubscriptionsResultSchema as v, RETENTION_WATERMARK_CHANNEL as x, UpdateSubscriptionReadSetParamsSchema as y };
+
+//# sourceMappingURL=sub-worker-dispatch-Ci_z8w10.js.map