@supalive/core 1.0.0 → 1.2.0

package/dist/src/exports/server.js

@@ -1,15 +1,17 @@
-import { n as getContextRegistry } from "../../router-DlTYWpop.js";
+import { n as getContextRegistry } from "../../router-CiWYeWUR.js";
 import { n as stableStringify, r as supaliveStringify, t as groupByToMap } from "../../helper-wGbzz6zo.js";
+import { r as evaluateCacheFreshness } from "../../overlap-checker-ClJC0nxW.js";
 import { i as AuthenticationError, o as ClientMessageSchema } from "../../types_client_rpc-CIsjQQGG.js";
 import { n as RemoteSubscriptionMessageSchema } from "../../types_server-Dk6o_B7N.js";
-import { n as sleep } from "../../realtime_db-DOCgqbwi.js";
-import { C as UpdateSubscriptionReadSetParamsSchema, S as UnregisterSubscriptionsResultSchema, _ as RegisterSubscriptionParamsSchema, a as initCacheLayer, b as UnregisterSubscriptionResultSchema, c as appInstanceId, d as logger, f as serializeMapValue, g as RegisterSubscriptionBatchResultSchema, i as createDatabase, l as isProduction, m as InvalidateWritesetResultSchema, n as DB_QUERY_TIMEOUT_MS, o as initDatabase, p as InvalidateWritesetParamsSchema, r as bootstrapDbTypes, s as CacheLayer, u as logLevelOf, v as RegisterSubscriptionResultSchema, w as UpdateSubscriptionReadSetResultSchema, y as UnregisterSubscriptionParamsSchema } from "../../subscription-worker-CqoWp6zB.js";
+import { n as sleep } from "../../realtime_db-BtwBABDY.js";
+import { C as RetentionWatermark, D as logger, E as logLevelOf, O as serializeMapValue, S as RETENTION_WATERMARK_CHANNEL, T as isProduction, _ as UnregisterSubscriptionResultSchema, a as createDatabase, b as UpdateSubscriptionReadSetParamsSchema, c as initDatabase, d as InvalidateWritesetResultSchema, g as UnregisterSubscriptionParamsSchema, h as RegisterSubscriptionResultSchema, i as bootstrapDbTypes, l as CacheLayer, m as RegisterSubscriptionParamsSchema, n as CORE_VERSION, o as initCacheLayer, p as RegisterSubscriptionBatchResultSchema, r as DB_QUERY_TIMEOUT_MS, s as initCore, u as InvalidateWritesetParamsSchema, w as appInstanceId, x as UpdateSubscriptionReadSetResultSchema, y as UnregisterSubscriptionsResultSchema } from "../../subscription-worker-CAf6MUta.js";
 import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
 import { v4 } from "uuid";
 import { ExponentialBackoff, handleAll, retry } from "cockatiel";
 import { sha1 } from "hash-wasm";
 import { Client, Server } from "rpc-websockets";
+import { Client as Client$1, Receiver } from "@upstash/qstash";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 //#region src/server/sub_hash.ts
@@ -23,6 +25,33 @@ async function getHashOf(input) {
 */
 const ANONYMOUS_IDENTITY = "anonymous";
 /**
+* Resolve the segmentation key that participates in the subId/cacheKey hash for
+* a query. Shared by every query transport (WS subscribe, WS one-shot call, and
+* HTTP RPC) so identity — and therefore cache segmentation — is computed
+* identically regardless of how the query is invoked. Priority:
+*
+*   1. Procedure-level `queryIdentity` override:
+*        - `false`    → `ANONYMOUS_IDENTITY` (cache shared across users)
+*        - `string`   → that literal
+*        - `function` → serverCtx + input → string | null | undefined
+*   2. `getUserId(serverCtx)` → falls back to `ANONYMOUS_IDENTITY` when it
+*      returns null/undefined or isn't configured.
+*/
+function resolveQueryIdentity(procedure, serverCtx, input, getUserId) {
+	const override = procedure.queryIdentity;
+	if (override !== void 0) {
+		if (override === false) return ANONYMOUS_IDENTITY;
+		if (typeof override === "string") return override;
+		if (typeof override === "function") {
+			const value = override(serverCtx, input);
+			if (value === null || value === void 0) return ANONYMOUS_IDENTITY;
+			return value;
+		}
+	}
+	if (!getUserId) return ANONYMOUS_IDENTITY;
+	return getUserId(serverCtx) ?? "anonymous";
+}
+/**
 * Compute a subscription id from hash of procedure + input + queryIdentity.
 *
 * `queryIdentity` is the segmentation key for cache/subscriptions. By default
@@ -42,8 +71,55 @@ async function generateCacheKey(queryName, input, queryIdentity) {
 	return `ck_${await getHashOf(`${queryName}_${typeof input === "string" ? input : stableStringify(input)}_${queryIdentity}`)}`;
 }
 //#endregion
+//#region src/server/one-shot-query.ts
+/**
+* Execute a one-shot query (WS `call` or HTTP RPC) with the same caching model
+* as a live subscription — but without registering a tracked subscription.
+*
+* Flow (mirrors `handleSubscribe` / worker `register`):
+*   1. Resolve `queryIdentity` → `cacheKey` (identical segmentation to subs).
+*   2. Freshness check via {@link evaluateCacheFreshness}: cached metadata +
+*      the retention watermark + a between-ts commit-log scan.
+*   3. Fresh  → return the cached data.
+*      Stale/miss → recompute via `queryInternal` and write BOTH the data and
+*      the metadata (readSet + snapshotTs) back, so a later one-shot or a fresh
+*      subscription can reuse it.
+*
+* The retention guard is what makes an untracked one-shot safe: nothing holds
+* the prune watermark down for it, so an entry whose snapshot has fallen below
+* the oldest retained commit log is treated as a miss (its freshness scan would
+* be incomplete).
+*
+* `lastSnapshotTs` is the freshness upper bound — the latest snapshot ts as of
+* this call. The caller loads it (via `db.getLatestSnapshotTimestamp()`) and
+* passes it in, exactly like the subscribe path loads it before `register`, so
+* the snapshot read lives at the caller seam rather than being hidden here.
+*/
+async function runCachedQuery(deps, procedure, procedureName, input, serverCtx, lastSnapshotTs) {
+	const queryIdentity = resolveQueryIdentity(procedure, serverCtx, input, deps.getUserId);
+	const cacheKey = await generateCacheKey(procedureName, stableStringify(input), queryIdentity);
+	const metadata = await deps.cache.getQueryCacheMetaData(cacheKey);
+	if ((await evaluateCacheFreshness(deps.db.impl, metadata, lastSnapshotTs, deps.getMinRetainedTs())).fresh) {
+		const cached = await deps.cache.getQueryCacheFor(cacheKey);
+		if (cached && metadata && cached.version === metadata.version) return cached.data;
+	}
+	const result = await deps.db.queryInternal(async (ctx) => {
+		const fn = procedure.fn;
+		return fn({
+			db: ctx,
+			serverCtx
+		}, input);
+	});
+	await deps.cache.setQueryCacheAndMetadataFor(cacheKey, result.data, {
+		lastSnapshotTs: result.ts,
+		version: String(result.ts),
+		readSet: result.readSet
+	}).catch((err) => logger.error(err, "one-shot query cache write failed"));
+	return result.data;
+}
+//#endregion
 //#region src/server/subscription-manager-client.ts
-const logger$3 = logger.child({ name: "SUBS_MGR_CLIENT" }, { level: logLevelOf("SUB_MANAGER_CLIENT_LOG_LEVEL") });
+const logger$5 = logger.child({ name: "SUBS_MGR_CLIENT" }, { level: logLevelOf("SUB_MANAGER_CLIENT_LOG_LEVEL") });
 const subscriptionManagerDataPack = {
 	encode: (data) => supaliveStringify(data),
 	decode: (data) => JSON.parse(data)
@@ -100,7 +176,7 @@ var SubManagerClient = class {
 		this.client.dataPack = subscriptionManagerDataPack;
 		this.client.on("open", this.handleOpen.bind(this));
 		this.client.on("close", this.handleClose.bind(this));
-		this.client.on("error", (err) => logger$3.warn(err, "sub-manager client socket error"));
+		this.client.on("error", (err) => logger$5.warn(err, "sub-manager client socket error"));
 	}
 	/**
 	* Wire up the app-server-driven recovery. Must be called before any
@@ -161,7 +237,7 @@ var SubManagerClient = class {
 	appendToBuffer(writeSet) {
 		if (this.bufferedWriteSets.length + writeSet.length > this.bufferLimit) {
 			if (!this.bufferDroppedDuringOutage) {
-				logger$3.warn(`Invalidate buffer would exceed ${this.bufferLimit}; dropping buffered entries. Subscriptions will be caught up via commit-log replay on re-register.`);
+				logger$5.warn(`Invalidate buffer would exceed ${this.bufferLimit}; dropping buffered entries. Subscriptions will be caught up via commit-log replay on re-register.`);
 				this.bufferDroppedDuringOutage = true;
 			}
 			this.bufferedWriteSets = [];
@@ -178,7 +254,7 @@ var SubManagerClient = class {
 			const result = await this.call("invalidateWriteset", { writeSet }, InvalidateWritesetResultSchema);
 			if (this.affectedHandler && result.affected.length > 0) await this.affectedHandler(result.affected);
 		} catch (err) {
-			logger$3.error(err, "Failed to flush invalidate buffer after recovery");
+			logger$5.error(err, "Failed to flush invalidate buffer after recovery");
 		}
 	}
 	markBusy() {
@@ -194,28 +270,28 @@ var SubManagerClient = class {
 		this.resolveReady();
 	}
 	handleClose() {
-		logger$3.info("sub-manager client: socket closed");
+		logger$5.info("sub-manager client: socket closed");
 		this.markBusy();
 	}
 	handleOpen() {
 		if (!this.hasConnectedOnce) {
 			this.hasConnectedOnce = true;
-			logger$3.info("sub-manager client: initial connect");
+			logger$5.info("sub-manager client: initial connect");
 			this.markReady();
 			return;
 		}
-		logger$3.info("sub-manager client: reconnected — starting recovery");
+		logger$5.info("sub-manager client: reconnected — starting recovery");
 		this.runRecovery();
 	}
 	async runRecovery() {
 		try {
 			if (this.recoveryDriver) await this.recoveryDriver();
-			else logger$3.warn("sub-manager client: no recoveryDriver configured — skipping recovery step");
+			else logger$5.warn("sub-manager client: no recoveryDriver configured — skipping recovery step");
 			await this.flushBuffer();
 		} catch (err) {
-			logger$3.error(err, "Recovery failed; state will be marked ready anyway");
+			logger$5.error(err, "Recovery failed; state will be marked ready anyway");
 		} finally {
-			logger$3.info("sub-manager client: recovery complete");
+			logger$5.info("sub-manager client: recovery complete");
 			this.markReady();
 		}
 	}
@@ -232,6 +308,423 @@ var SubManagerClient = class {
 	}
 };
 //#endregion
+//#region src/jobs/scheduler.ts
+const logger$4 = logger.child({ name: "SCHEDULER" }, { level: logLevelOf("SCHEDULER_LOG_LEVEL") });
+function delayMsFrom(opts) {
+	if (opts?.runAt) return Math.max(0, opts.runAt.getTime() - Date.now());
+	if (opts?.delaySeconds && opts.delaySeconds > 0) return opts.delaySeconds * 1e3;
+	return 0;
+}
+/**
+* In-process scheduler for local development and tests. Recurring jobs fire on
+* a fixed interval; one-shots fire on an exact `setTimeout` (so precise timing
+* is faithfully testable). Every fire POSTs to the real HTTP job endpoint, and
+* `verify` accepts everything — there is no signing in dev.
+*/
+var DevScheduler = class {
+	intervalMs;
+	fetchImpl;
+	intervals = /* @__PURE__ */ new Map();
+	timeouts = /* @__PURE__ */ new Map();
+	constructor(opts = {}) {
+		this.intervalMs = opts.recurringIntervalMs ?? 6e4;
+		this.fetchImpl = opts.fetchImpl ?? fetch;
+	}
+	async verify(_req) {
+		return true;
+	}
+	async syncSchedules(jobs, endpointFor) {
+		for (const timer of this.intervals.values()) clearInterval(timer);
+		this.intervals.clear();
+		for (const job of jobs) {
+			const endpoint = endpointFor(job.name);
+			const timer = setInterval(() => {
+				this.post(endpoint, {}).catch((err) => logger$4.error(err, `dev recurring job "${job.name}" failed`));
+			}, this.intervalMs);
+			timer.unref?.();
+			this.intervals.set(job.name, timer);
+			logger$4.info(`dev schedule "${job.name}" (cron "${job.cron}") → firing every ${this.intervalMs}ms`);
+		}
+	}
+	async enqueue(name, body, endpoint, opts) {
+		const id = crypto.randomUUID();
+		const timer = setTimeout(() => {
+			this.timeouts.delete(id);
+			this.post(endpoint, body).catch((err) => logger$4.error(err, `dev one-shot job "${name}" failed`));
+		}, delayMsFrom(opts));
+		timer.unref?.();
+		this.timeouts.set(id, timer);
+		return { id };
+	}
+	async cancel(handleId) {
+		const timer = this.timeouts.get(handleId);
+		if (timer) {
+			clearTimeout(timer);
+			this.timeouts.delete(handleId);
+		}
+	}
+	/** Stop every dev timer (call on server shutdown / in test teardown). */
+	stop() {
+		for (const t of this.intervals.values()) clearInterval(t);
+		for (const t of this.timeouts.values()) clearTimeout(t);
+		this.intervals.clear();
+		this.timeouts.clear();
+	}
+	async post(endpoint, body) {
+		const res = await this.fetchImpl(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body ?? {})
+		});
+		if (!res.ok) throw new Error(`job endpoint ${endpoint} returned ${res.status}`);
+	}
+};
+/**
+* Production scheduler backed by Upstash QStash. Externalizes the timer so a
+* horizontally-scaled deployment fires each cron tick exactly once (QStash
+* calls one HTTP endpoint), with at-least-once retries and signed webhooks.
+*/
+var QStashScheduler = class {
+	client;
+	receiver;
+	constructor(opts) {
+		this.client = new Client$1({ token: opts.token });
+		this.receiver = new Receiver({
+			currentSigningKey: opts.currentSigningKey,
+			nextSigningKey: opts.nextSigningKey
+		});
+	}
+	async verify(req) {
+		const signature = req.headers["upstash-signature"];
+		if (!signature) return false;
+		try {
+			return await this.receiver.verify({
+				signature,
+				body: req.rawBody,
+				url: req.url
+			});
+		} catch (err) {
+			logger$4.warn(err, `signature verification failed for job "${req.name}"`);
+			return false;
+		}
+	}
+	async syncSchedules(jobs, endpointFor) {
+		const desired = new Map(jobs.map((j) => [scheduleIdFor(j.name), j]));
+		let existing = [];
+		try {
+			existing = await this.client.schedules.list();
+		} catch (err) {
+			logger$4.error(err, "failed to list QStash schedules; skipping reconcile of stale schedules");
+		}
+		for (const schedule of existing) {
+			const id = schedule.scheduleId;
+			if (id?.startsWith(SCHEDULE_ID_PREFIX) && !desired.has(id)) try {
+				await this.client.schedules.delete(id);
+				logger$4.info(`removed stale QStash schedule ${id}`);
+			} catch (err) {
+				logger$4.error(err, `failed to remove stale schedule ${id}`);
+			}
+		}
+		for (const [scheduleId, job] of desired) try {
+			await this.client.schedules.create({
+				scheduleId,
+				destination: endpointFor(job.name),
+				cron: job.cron
+			});
+			logger$4.info(`synced QStash schedule "${job.name}" (${job.cron})`);
+		} catch (err) {
+			logger$4.error(err, `failed to sync schedule for job "${job.name}"`);
+			throw err;
+		}
+	}
+	async enqueue(name, body, endpoint, opts) {
+		const messageId = (await this.client.publishJSON({
+			url: endpoint,
+			body,
+			...opts?.runAt ? { notBefore: Math.floor(opts.runAt.getTime() / 1e3) } : opts?.delaySeconds ? { delay: opts.delaySeconds } : {},
+			...opts?.dedupeId ? { deduplicationId: opts.dedupeId } : {}
+		})).messageId;
+		if (!messageId) throw new Error(`QStash publish for job "${name}" returned no messageId`);
+		return { id: messageId };
+	}
+	async cancel(handleId) {
+		await this.client.messages.cancel(handleId);
+	}
+};
+const SCHEDULE_ID_PREFIX = "supalive-job-";
+function scheduleIdFor(jobName) {
+	return `${SCHEDULE_ID_PREFIX}${jobName}`;
+}
+/**
+* Thin app-facing handle for scheduling precise one-shots from inside
+* procedures. The server builds one (via `getJobClient()`) that already knows
+* how to turn a job name into its endpoint, so callers just say
+* `jobs.enqueue("expireSpendAuth", { id }, { runAt })`.
+*/
+var JobClient = class {
+	scheduler;
+	endpointFor;
+	constructor(scheduler, endpointFor) {
+		this.scheduler = scheduler;
+		this.endpointFor = endpointFor;
+	}
+	enqueue(name, body, opts) {
+		return this.scheduler.enqueue(name, body, this.endpointFor(name), opts);
+	}
+	cancel(handleId) {
+		return this.scheduler.cancel(handleId);
+	}
+};
+//#endregion
+//#region src/server/rate-limit.ts
+var FixedWindowRateLimiter = class {
+	windowMs;
+	max;
+	buckets = /* @__PURE__ */ new Map();
+	sweepTimer;
+	constructor(windowMs, max) {
+		this.windowMs = windowMs;
+		this.max = max;
+		this.sweepTimer = setInterval(() => this.sweep(), Math.max(windowMs, 1e3));
+		this.sweepTimer.unref?.();
+	}
+	check(key, now = Date.now()) {
+		let bucket = this.buckets.get(key);
+		if (!bucket || bucket.resetAt <= now) {
+			bucket = {
+				count: 0,
+				resetAt: now + this.windowMs
+			};
+			this.buckets.set(key, bucket);
+		}
+		bucket.count++;
+		if (bucket.count > this.max) return {
+			allowed: false,
+			retryAfterMs: bucket.resetAt - now,
+			remaining: 0
+		};
+		return {
+			allowed: true,
+			retryAfterMs: 0,
+			remaining: this.max - bucket.count
+		};
+	}
+	sweep(now = Date.now()) {
+		for (const [key, bucket] of this.buckets) if (bucket.resetAt <= now) this.buckets.delete(key);
+	}
+	/** Stop the background sweep (call on server shutdown / test teardown). */
+	stop() {
+		if (this.sweepTimer) clearInterval(this.sweepTimer);
+		this.sweepTimer = void 0;
+	}
+};
+//#endregion
+//#region src/server/http-rpc.ts
+const logger$3 = logger.child({ name: "HTTP_RPC" }, { level: logLevelOf("SERVER_LOG_LEVEL") });
+/**
+* Handles the one-shot HTTP RPC transport: `POST {path}/<procedureName>` for
+* `query`/`mutation`/`action`. Subscriptions are not offered here (WS only).
+* Kept independent of the WebSocket server so it can be unit-tested against a
+* plain `http.Server` with a stub db/registry.
+*
+* Request flow: CORS → (OPTIONS preflight) → rate limit (pre-auth) → procedure
+* lookup (internal/job rejected) → auth → validate input → run → respond.
+*/
+var HttpRpcHandler = class {
+	deps;
+	path;
+	rpc;
+	rateLimiter;
+	constructor(deps) {
+		this.deps = deps;
+		this.rpc = deps.rpc;
+		this.path = normalizeRpcPath(deps.rpc.path ?? "/_rpc");
+		if (deps.rpc.rateLimit !== false) {
+			const rl = deps.rpc.rateLimit ?? {};
+			this.rateLimiter = new FixedWindowRateLimiter(rl.windowMs ?? 6e4, rl.max ?? 120);
+		}
+	}
+	/** True when this handler owns the given request path. */
+	handlesPath(path) {
+		return path === this.path || path.startsWith(`${this.path}/`);
+	}
+	stop() {
+		this.rateLimiter?.stop();
+	}
+	async handle(req, res, path) {
+		this.applyCors(req, res);
+		if (req.method === "OPTIONS") {
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+		if (req.method !== "POST") return this.send(res, 405, {
+			success: false,
+			error: "method not allowed",
+			code: "METHOD_NOT_ALLOWED"
+		});
+		const prefix = `${this.path}/`;
+		const name = path.startsWith(prefix) ? decodeURIComponent(path.slice(prefix.length)) : "";
+		if (!name || name.includes("/")) return this.send(res, 404, {
+			success: false,
+			error: "unknown procedure",
+			code: "NOT_FOUND"
+		});
+		if (this.rateLimiter) {
+			const keyBy = this.rpc.rateLimit ? this.rpc.rateLimit.keyBy : void 0;
+			const key = keyBy ? keyBy(req) : clientIp(req);
+			const rl = this.rateLimiter.check(key);
+			if (!rl.allowed) {
+				res.setHeader("retry-after", String(Math.ceil(rl.retryAfterMs / 1e3)));
+				return this.send(res, 429, {
+					success: false,
+					error: "rate limit exceeded",
+					code: "RATE_LIMITED"
+				});
+			}
+		}
+		const procedure = this.deps.getRegistry()?.getProcedure(name);
+		if (!procedure || procedure.internal || procedure.type === "job") return this.send(res, 404, {
+			success: false,
+			error: `Procedure "${name}" not found`,
+			code: "NOT_FOUND"
+		});
+		const auth = await this.resolveAuth(req);
+		if (!auth.ok) return this.send(res, 401, {
+			success: false,
+			error: auth.message,
+			code: "UNAUTHENTICATED"
+		});
+		const rawBody = await readBody(req);
+		let input;
+		try {
+			const parsed = rawBody.trim().length > 0 ? JSON.parse(rawBody) : {};
+			input = procedure.inputSchema.parse(parsed);
+		} catch (err) {
+			logger$3.warn(err, `RPC "${name}" received invalid input`);
+			return this.send(res, 400, {
+				success: false,
+				error: "invalid input",
+				code: "BAD_REQUEST"
+			});
+		}
+		try {
+			const data = await this.runProcedure(procedure, input, auth.ctx);
+			return this.send(res, 200, {
+				success: true,
+				data
+			});
+		} catch (err) {
+			logger$3.error(err, `RPC "${name}" failed`);
+			return this.send(res, 500, {
+				success: false,
+				error: err instanceof Error ? err.message : "execution failed",
+				code: "EXECUTION_ERROR"
+			});
+		}
+	}
+	async runProcedure(procedure, input, serverCtx) {
+		if (procedure.type === "query") {
+			const lastSnapshotTs = await this.deps.db.impl.getLatestSnapshotTimestamp();
+			return runCachedQuery(this.deps.oneShotDeps, procedure, procedure.name, input, serverCtx, lastSnapshotTs);
+		}
+		if (procedure.type === "mutation") return (await this.deps.db.mutation(async (ctx) => {
+			const fn = procedure.fn;
+			return fn({
+				db: ctx,
+				serverCtx
+			}, input);
+		})).result;
+		const fn = procedure.fn;
+		return fn({
+			db: this.deps.db,
+			serverCtx
+		}, input);
+	}
+	async resolveAuth(req) {
+		const data = (this.rpc.auth ?? defaultHttpAuth)(req);
+		if (!this.deps.verifyAuth || !data) return {
+			ok: true,
+			ctx: void 0
+		};
+		try {
+			const ctx = await this.deps.verifyAuth(data, `http-${crypto.randomUUID()}`);
+			if (!ctx) return {
+				ok: false,
+				message: "Invalid authentication"
+			};
+			return {
+				ok: true,
+				ctx
+			};
+		} catch (err) {
+			if (err instanceof AuthenticationError) return {
+				ok: false,
+				message: `Invalid authentication: ${err.message}`
+			};
+			return {
+				ok: false,
+				message: "Invalid authentication"
+			};
+		}
+	}
+	applyCors(req, res) {
+		const cors = this.rpc.cors;
+		if (!cors) return;
+		const originHeader = req.headers["origin"];
+		const origin = Array.isArray(originHeader) ? originHeader[0] : originHeader;
+		if (cors.origins === "*") res.setHeader("access-control-allow-origin", "*");
+		else if (origin && cors.origins.includes(origin)) {
+			res.setHeader("access-control-allow-origin", origin);
+			res.setHeader("vary", "Origin");
+		} else return;
+		res.setHeader("access-control-allow-methods", "POST, OPTIONS");
+		res.setHeader("access-control-allow-headers", "authorization, content-type");
+		res.setHeader("access-control-max-age", "86400");
+	}
+	send(res, status, body) {
+		res.writeHead(status, { "content-type": "application/json" });
+		res.end(supaliveStringify(body));
+	}
+};
+function normalizeRpcPath(p) {
+	let s = p.startsWith("/") ? p : `/${p}`;
+	if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+	return s;
+}
+function defaultHttpAuth(req) {
+	const header = req.headers["authorization"];
+	const value = Array.isArray(header) ? header[0] : header;
+	if (!value) return void 0;
+	const match = /^Bearer\s+(.+)$/i.exec(value);
+	return match ? { token: match[1] } : void 0;
+}
+function clientIp(req) {
+	const xff = req.headers["x-forwarded-for"];
+	if (xff) {
+		const first = (Array.isArray(xff) ? xff[0] : xff).split(",")[0]?.trim();
+		if (first) return first;
+	}
+	return req.socket?.remoteAddress ?? "unknown";
+}
+function readBody(req, maxBytes = 1024 * 1024) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > maxBytes) {
+				reject(/* @__PURE__ */ new Error("request body too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", reject);
+	});
+}
+//#endregion
 //#region src/server/supalive-server.ts
 const redisRetryPolicy = retry(handleAll, {
 	maxAttempts: 3,
@@ -291,6 +784,12 @@ var SupaliveWebSocketServer = class {
 	db;
 	contextRegistry;
 	router;
+	retentionWatermark = new RetentionWatermark();
+	oneShotDeps;
+	scheduler;
+	jobPath;
+	jobClient;
+	rpcHandler;
 	sessions = /* @__PURE__ */ new Map();
 	serverSubscriptions = /* @__PURE__ */ new Map();
 	subManagerClient;
@@ -313,9 +812,39 @@ var SupaliveWebSocketServer = class {
 		this.cache = config.cacheLayer;
 		this.redisSub = config.redisSubClient;
 		this.db = config.database;
+		this.db.setOnAfterCommit((writeSet, commitTs) => {
+			this.handleMutationCommit(writeSet, commitTs).catch((err) => logger$2.error(err, "post-commit invalidation failed"));
+		});
+		this.scheduler = config.scheduler;
+		this.jobPath = normalizeJobPath(config.jobPath ?? "/_jobs");
+		if (this.scheduler) {
+			if (!this.config.publicUrl) throw new Error("publicUrl config is required when a scheduler is configured (used to build job endpoints)");
+			this.jobClient = new JobClient(this.scheduler, (name) => this.endpointFor(name));
+		}
+		this.oneShotDeps = {
+			db: this.db,
+			cache: this.cache,
+			getUserId: config.getUserId,
+			getMinRetainedTs: () => this.retentionWatermark.get()
+		};
+		if (config.rpc) this.rpcHandler = new HttpRpcHandler({
+			getRegistry: () => this.contextRegistry,
+			db: this.db,
+			oneShotDeps: this.oneShotDeps,
+			verifyAuth: config.verifyAuth,
+			rpc: config.rpc
+		});
 		this.subManagerClient.setRecoveryDriver(this.runSubManagerRecovery.bind(this));
 		this.subManagerClient.setAffectedHandler(this.runAffectedHandler.bind(this));
-		this.httpServer = createServer();
+		this.httpServer = createServer((req, res) => {
+			this.handleHttpRequest(req, res).catch((err) => {
+				logger$2.error(err, "HTTP request handler error");
+				if (!res.headersSent) {
+					res.writeHead(500, { "content-type": "application/json" });
+					res.end(JSON.stringify({ error: "internal error" }));
+				}
+			});
+		});
 		this.wss = new WebSocketServer({
 			server: this.httpServer,
 			autoPong: true,
@@ -362,16 +891,68 @@ var SupaliveWebSocketServer = class {
 		this.contextRegistry = getContextRegistry(router.contextName);
 	}
 	async start() {
-		return new Promise((resolve) => {
+		try {
+			await this.retentionWatermark.loadFrom(this.db.impl);
+		} catch (err) {
+			logger$2.error(err, "failed to load initial retention watermark");
+		}
+		await new Promise((resolve) => {
 			this.httpServer.listen(this.config.port, this.config.host, () => {
 				logger$2.info(`Server: ${this.instanceId} listening on ${this.config.host}:${this.config.port}`);
 				resolve();
 			});
 		});
+		await this.syncJobSchedules();
+	}
+	/**
+	* Reconcile every registered recurring (cron) job with the scheduler. Safe
+	* to call more than once. No-op when no scheduler is configured or the router
+	* declares no cron jobs. Runs after the HTTP listener is up so the endpoints
+	* the scheduler registers are already reachable.
+	*/
+	async syncJobSchedules() {
+		if (!this.scheduler || !this.contextRegistry) return;
+		const jobs = this.contextRegistry.getJobProcedures().filter((p) => !!p.cron).map((p) => ({
+			name: p.name,
+			cron: p.cron
+		}));
+		if (jobs.length === 0) return;
+		try {
+			await this.scheduler.syncSchedules(jobs, (name) => this.endpointFor(name));
+			logger$2.info(`Synced ${jobs.length} recurring job schedule(s)`);
+		} catch (err) {
+			logger$2.error(err, "Failed to sync job schedules");
+		}
+	}
+	/** Absolute URL the scheduler POSTs to for a given job name. */
+	endpointFor(name) {
+		return `${this.config.publicUrl}${this.jobPath}/${name}`;
+	}
+	/**
+	* Enqueue a precise, one-shot run of a job (e.g. "expire this record at
+	* exactly `expiresAt`"). Returns a handle whose `id` can be passed to
+	* {@link cancelJob}. Requires a configured scheduler.
+	*/
+	async scheduleJob(name, body, opts) {
+		if (!this.jobClient) throw new Error("No scheduler configured; cannot schedule jobs");
+		return this.jobClient.enqueue(name, body, opts);
+	}
+	/** Cancel a one-shot previously created by {@link scheduleJob}. */
+	async cancelJob(handleId) {
+		if (!this.jobClient) throw new Error("No scheduler configured; cannot cancel jobs");
+		return this.jobClient.cancel(handleId);
+	}
+	/**
+	* The app-facing {@link JobClient} — hand it to your service layer so
+	* procedures can schedule/cancel one-shots without reaching for the server.
+	*/
+	getJobClient() {
+		return this.jobClient;
 	}
 	async stop() {
 		this.wss.close();
 		for (const [ws] of this.sessions) ws.close(1001, "Server shutting down");
+		this.rpcHandler?.stop();
 		this.httpServer.close();
 		logger$2.info("Server stopped");
 	}
@@ -386,6 +967,64 @@ var SupaliveWebSocketServer = class {
 	getInstanceId() {
 		return this.instanceId;
 	}
+	/**
+	* Plain-HTTP entrypoint (non-WS). Serves a liveness probe and the job
+	* webhook: `POST {jobPath}/<jobName>`. Every job POST is authenticated by the
+	* configured scheduler before the (server-only) job handler runs.
+	*/
+	async handleHttpRequest(req, res) {
+		const path = (req.url ?? "/").split("?")[0];
+		if (req.method === "GET" && (path === "/_health" || path === `${this.jobPath}/_health`)) return sendJson(res, 200, {
+			status: "ok",
+			instanceId: this.instanceId
+		});
+		if (this.rpcHandler && this.rpcHandler.handlesPath(path)) return this.rpcHandler.handle(req, res, path);
+		const jobPrefix = `${this.jobPath}/`;
+		if (!path.startsWith(jobPrefix)) return sendJson(res, 404, { error: "not found" });
+		if (req.method !== "POST") return sendJson(res, 405, { error: "method not allowed" });
+		const name = decodeURIComponent(path.slice(jobPrefix.length));
+		if (!name || name.includes("/")) return sendJson(res, 404, { error: "unknown job" });
+		if (!this.scheduler) return sendJson(res, 503, { error: "jobs not enabled" });
+		const rawBody = await readRequestBody(req);
+		let verified = false;
+		try {
+			verified = await this.scheduler.verify({
+				name,
+				rawBody,
+				headers: lowercaseHeaders(req.headers),
+				url: this.endpointFor(name)
+			});
+		} catch (err) {
+			logger$2.warn(err, `job "${name}" verification threw`);
+		}
+		if (!verified) return sendJson(res, 401, { error: "invalid signature" });
+		const procedure = this.contextRegistry?.getProcedure(name);
+		if (!procedure || procedure.type !== "job") return sendJson(res, 404, { error: "unknown job" });
+		let input;
+		try {
+			const parsed = rawBody.trim().length > 0 ? JSON.parse(rawBody) : {};
+			input = procedure.inputSchema.parse(parsed);
+		} catch (err) {
+			logger$2.warn(err, `job "${name}" received an invalid payload`);
+			return sendJson(res, 400, { error: "invalid payload" });
+		}
+		try {
+			const serverCtx = this.config.jobContext ? await this.config.jobContext() : void 0;
+			const fn = procedure.fn;
+			const result = await fn({
+				db: this.db,
+				serverCtx
+			}, input);
+			logger$2.info(`job "${name}" completed`);
+			return sendJson(res, 200, {
+				ok: true,
+				result
+			});
+		} catch (err) {
+			logger$2.error(err, `job "${name}" failed`);
+			return sendJson(res, 500, { error: "job failed" });
+		}
+	}
 	setupWebSocketHandlers() {
 		this.wss.on("connection", (ws, req) => {
 			this.handleConnection(ws, req).catch((err) => {
@@ -555,20 +1194,15 @@ var SupaliveWebSocketServer = class {
 			return;
 		}
 		const procedure = this.contextRegistry.getProcedure(procedureName);
-		if (!procedure) {
+		if (!procedure || procedure.type === "job") {
 			this.sendError(session, id, `Procedure "${procedureName}" not found`, "NOT_FOUND");
 			return;
 		}
 		try {
 			const validatedInput = procedure.inputSchema.parse(input);
 			if (procedure.type === "query") {
-				const result = await this.db.query(async (ctx) => {
-					const fn = procedure.fn;
-					return fn({
-						db: ctx,
-						serverCtx: session.serverCtx
-					}, validatedInput);
-				});
+				const lastSnapshotTs = await this.db.impl.getLatestSnapshotTimestamp();
+				const result = await runCachedQuery(this.oneShotDeps, procedure, procedureName, validatedInput, session.serverCtx, lastSnapshotTs);
 				this.sendMessage(session, {
 					type: "response",
 					id,
@@ -584,9 +1218,9 @@ var SupaliveWebSocketServer = class {
 				this.sendMessage(session, {
 					type: "response",
 					id,
-					success: true
+					success: true,
+					data: mutationResult.result
 				});
-				await this.handleMutationCommit(mutationResult.writeSet, mutationResult.commitTs);
 			} else if (procedure.type === "action") {
 				if (session.actionInFlight >= MAX_ACTION_CONCURRENCY) {
 					this.sendError(session, id, `Too many concurrent actions on this connection (max ${MAX_ACTION_CONCURRENCY})`, "TOO_MANY_CONCURRENT_ACTIONS");
@@ -627,7 +1261,7 @@ var SupaliveWebSocketServer = class {
 		}
 		try {
 			const validatedInput = procedure.inputSchema.parse(input);
-			const queryIdentity = this.resolveQueryIdentity(procedure, session, validatedInput);
+			const queryIdentity = resolveQueryIdentity(procedure, session.serverCtx, validatedInput, this.config.getUserId);
 			const inputJsonStable = stableStringify(validatedInput);
 			const subId = await generateSubscriptionId(procedureName, inputJsonStable, queryIdentity);
 			const cacheKey = await generateCacheKey(procedureName, inputJsonStable, queryIdentity);
@@ -656,7 +1290,7 @@ var SupaliveWebSocketServer = class {
 					lastSnapshotTs
 				});
 				const cached = await this.cache.getQueryCacheFor(subManagerResult.cacheKey);
-				if (cached && !subManagerResult.recompute) data = cached.data;
+				if (cached && !subManagerResult.recompute && cached.version === subManagerResult.version) data = cached.data;
 				else {
 					liveResult = await this.executeLiveQuery(procedureName, validatedInput, session.serverCtx);
 					data = liveResult.data;
@@ -675,7 +1309,7 @@ var SupaliveWebSocketServer = class {
 					lastSnapshotTs: liveResult.ts,
 					readSet: liveResult.readSet,
 					instanceName: this.instanceId
-				}), this.cache.setQueryCacheFor(cacheKey, data)]);
+				}), this.cache.setQueryCacheFor(cacheKey, data, String(liveResult.ts))]);
 				if (!updateResult.tracked) logger$2.warn(`updateSubscriptionReadSet returned tracked:false immediately after register for ${subId} — possible sub-manager restart mid-subscribe`);
 			}
 			dataHash = await getHashOf(data);
@@ -922,7 +1556,7 @@ var SupaliveWebSocketServer = class {
 				lastSnapshotTs: liveResult.ts,
 				readSet: liveResult.readSet,
 				instanceName: this.instanceId
-			}), this.cache.setQueryCacheFor(affected.cacheKey, liveResult.data)]);
+			}), this.cache.setQueryCacheFor(affected.cacheKey, liveResult.data, String(liveResult.ts))]);
 			if (!updateResult.tracked) {
 				this.dropSubscriptionLocally(affected.subId, "no longer tracked by sub-manager");
 				return;
@@ -950,31 +1584,6 @@ var SupaliveWebSocketServer = class {
 			}, input);
 		});
 	}
-	/**
-	* Resolve the segmentation key used in the subId/cacheKey hash for a
-	* query subscription. Priority:
-	*
-	*   1. Procedure-level `queryIdentity` override:
-	*        - `false`       → identity = `ANONYMOUS_IDENTITY` (cache shared across users)
-	*        - `string`      → that literal
-	*        - `function`    → ctx + input → string | null | undefined
-	*   2. `config.getUserId(serverCtx)` → falls back to ANONYMOUS_IDENTITY if it
-	*      returns null/undefined or isn't configured.
-	*/
-	resolveQueryIdentity(procedure, session, input) {
-		const override = procedure.queryIdentity;
-		if (override !== void 0) {
-			if (override === false) return ANONYMOUS_IDENTITY;
-			if (typeof override === "string") return override;
-			if (typeof override === "function") {
-				const value = override(session.serverCtx, input);
-				if (value === null || value === void 0) return ANONYMOUS_IDENTITY;
-				return value;
-			}
-		}
-		if (!this.config.getUserId) return ANONYMOUS_IDENTITY;
-		return this.config.getUserId(session.serverCtx) ?? "anonymous";
-	}
 	sendMessage(session, message) {
 		if (session.ws.readyState !== WebSocket.OPEN) return;
 		session.ws.send(supaliveStringify(message));
@@ -995,9 +1604,10 @@ var SupaliveWebSocketServer = class {
 	async subscribeToInstanceChannel() {
 		const instanceChannel = `sub:instance:${this.instanceId}`;
 		const schemaChannel = SCHEMA_RELOAD_CHANNEL;
-		await this.redisSub.subscribe(instanceChannel, schemaChannel);
+		const watermarkChannel = RETENTION_WATERMARK_CHANNEL;
+		await this.redisSub.subscribe(instanceChannel, schemaChannel, watermarkChannel);
 		this.redisSub.on("connect", () => {
-			logger$2.info(`Subscribed to Redis channels: ${instanceChannel}, ${schemaChannel}`);
+			logger$2.info(`Subscribed to Redis channels: ${instanceChannel}, ${schemaChannel}, ${watermarkChannel}`);
 		});
 		this.redisSub.on("message", (channel, message) => {
 			if (channel === instanceChannel) this.handleRemoteInstanceMessage(message).catch((err) => {
@@ -1006,6 +1616,11 @@ var SupaliveWebSocketServer = class {
 			else if (channel === schemaChannel) this.handleSchemaReload().catch((err) => {
 				logger$2.error(err, "Error handling schema reload");
 			});
+			else if (channel === watermarkChannel) try {
+				this.retentionWatermark.set(BigInt(message));
+			} catch (err) {
+				logger$2.error(err, `Bad retention watermark message: ${message}`);
+			}
 		});
 		this.redisSub.on("error", (err) => {
 			logger$2.error(err, `Subscriber error for channels: ${instanceChannel}, ${schemaChannel}`);
@@ -1100,6 +1715,40 @@ var SupaliveWebSocketServer = class {
 		await Promise.all(publishPromises);
 	}
 };
+/** Normalize a job path to a leading-slash, no-trailing-slash prefix. */
+function normalizeJobPath(p) {
+	let s = p.startsWith("/") ? p : `/${p}`;
+	if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+	return s;
+}
+function sendJson(res, status, body) {
+	const payload = supaliveStringify(body);
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(payload);
+}
+function lowercaseHeaders(headers) {
+	const out = {};
+	for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = Array.isArray(v) ? v.join(",") : v;
+	return out;
+}
+/** Buffer an incoming request body to a string, capped to guard against abuse. */
+function readRequestBody(req, maxBytes = 1024 * 1024) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > maxBytes) {
+				reject(/* @__PURE__ */ new Error("request body too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", reject);
+	});
+}
 //#endregion
 //#region src/server/hash.ts
 /**
@@ -1201,7 +1850,7 @@ var SubscriptionManager = class SubscriptionManager {
 	port;
 	workers;
 	pruneInterval = null;
-	static PRUNE_INTERVAL_MS = 1800 * 1e3;
+	static PRUNE_INTERVAL_MS = 10080 * 60 * 1e3;
 	constructor(config) {
 		this.port = config.port;
 		this.wss = new Server({ port: this.port }, subscriptionManagerDataPack);
@@ -1221,6 +1870,12 @@ var SubscriptionManager = class SubscriptionManager {
 	async start() {
 		await Promise.all(this.workers.map((w) => w.ready()));
 		logger$1.info(`Listening on port ${this.port}`);
+		try {
+			const minRetainedTs = await this.workers[0].send(12, null);
+			await this.broadcastRetentionWatermark(minRetainedTs);
+		} catch (err) {
+			logger$1.error(err, "initial retention watermark seed failed");
+		}
 		this.pruneInterval = setInterval(() => {
 			this.pruneCommitLogs().catch((err) => logger$1.error(err, "commit_logs prune failed"));
 		}, SubscriptionManager.PRUNE_INTERVAL_MS);
@@ -1237,18 +1892,25 @@ var SubscriptionManager = class SubscriptionManager {
 	}
 	async pruneCommitLogs() {
 		const minPerWorker = await Promise.all(this.workers.map((w) => w.send(8, null)));
-		let floor = null;
+		let minRetainedTs = null;
 		for (const m of minPerWorker) {
 			if (m === null) continue;
-			if (floor === null || m < floor) floor = m;
+			if (minRetainedTs === null || m < minRetainedTs) minRetainedTs = m;
 		}
-		if (floor === null) {
+		if (minRetainedTs === null) {
 			const latest = await this.workers[0].send(9, null);
 			if (latest <= 0n) return;
-			floor = latest;
+			minRetainedTs = latest;
 		}
-		const deleted = await this.workers[0].send(10, floor);
-		if (deleted > 0n) logger$1.info(`pruned ${deleted} commit_logs older than ts=${floor}`);
+		const deleted = await this.workers[0].send(10, minRetainedTs);
+		await this.broadcastRetentionWatermark(minRetainedTs);
+		if (deleted > 0n) logger$1.info(`pruned ${deleted} commit_logs older than ts=${minRetainedTs}`);
+	}
+	/** Fan a watermark value out to every worker's in-memory copy. Worker 0 (the
+	* pruner/seeder) already has it, but re-sending is harmless — {@link
+	* SubscriptionWorker.setRetentionWatermark} is monotonic. */
+	async broadcastRetentionWatermark(ts) {
+		await Promise.all(this.workers.map((w) => w.send(13, ts).catch((err) => logger$1.error(err, "retention watermark broadcast to worker failed"))));
 	}
 	workerCount() {
 		return this.workers.length;
@@ -1337,6 +1999,6 @@ function resolveMaxConnectionsPerWorker(config, workers) {
 	return Math.max(1, Math.floor(total / workers));
 }
 //#endregion
-export { ANONYMOUS_IDENTITY, CacheLayer, DB_QUERY_TIMEOUT_MS, InvalidateWritesetParamsSchema, RegisterSubscriptionParamsSchema, SubManagerClient, SubscriptionManager, SupaliveWebSocketServer, UnregisterSubscriptionParamsSchema, UpdateSubscriptionReadSetParamsSchema, appInstanceId, bootstrapDbTypes, createDatabase, generateCacheKey, generateSubscriptionId, getHashOf, initCacheLayer, initDatabase, isProduction, logLevelOf, logger, serializeMapValue };
+export { ANONYMOUS_IDENTITY, CORE_VERSION, CacheLayer, DB_QUERY_TIMEOUT_MS, DevScheduler, InvalidateWritesetParamsSchema, JobClient, QStashScheduler, RegisterSubscriptionParamsSchema, SubManagerClient, SubscriptionManager, SupaliveWebSocketServer, UnregisterSubscriptionParamsSchema, UpdateSubscriptionReadSetParamsSchema, appInstanceId, bootstrapDbTypes, createDatabase, generateCacheKey, generateSubscriptionId, getHashOf, initCacheLayer, initCore, initDatabase, isProduction, logLevelOf, logger, serializeMapValue };
 
 //# sourceMappingURL=server.js.map