@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/modules/actions/jobs/worker.js

@@ -0,0 +1,267 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { createFailureStreak } from "./failureStreak.js";
+import { ActionRunError } from "../runtime/errors.js";
+import { randomUUID } from "node:crypto";
+//#region src/modules/actions/jobs/worker.ts
+/**
+* Refusals that mean "not now" rather than "not ever".
+*
+* Both are the cluster protecting itself — another run holds the single-flight key, or this replica is already
+* carrying as much as it will — and neither says anything about the job. So the job goes back to the queue with
+* its attempt REFUNDED: burning one would let a busy afternoon retire a nightly digest as dead.
+*/
+var TRY_AGAIN = /* @__PURE__ */ new Set(["duplicate", "over_capacity"]);
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+* Why a run that ended badly did, in the words an operator can act on: the step that failed and what it said.
+*
+* Read from `steps` — the outline, whose errors are already redacted of every credential the run resolved — so
+* nothing lands on the job that the run history would not show. A run that failed without any step failing (a
+* timeout between steps, a budget spent) has no step to name, and says how it ended instead.
+*/
+var failureOf = (result) => {
+	const failed = result.steps.find((step) => step.phase === "flow" && step.status === "failed");
+	return failed ? `step "${failed.id}" failed: ${failed.error ?? "no reason given"}` : `the flow ended ${result.status}`;
+};
+/**
+* Refusals no number of attempts will change: the action was deleted, its schedule was switched off, or the
+* document refuses this trigger. Retrying is noise, and the job stops where an operator can see why.
+*/
+var GIVE_UP = /* @__PURE__ */ new Set([
+	"not_found",
+	"disabled",
+	"forbidden",
+	"recursion"
+]);
+var createJobWorker = ({ queue, lookups, module, workers = 4, pollMs = 1e3, leaseMs = 3e4, backoff = {}, workerId = `${process.pid}-${randomUUID().slice(0, 8)}`, onError: customOnError }) => {
+	const onError = customOnError ?? ((error) => serverLog.error("Actions", "job worker failed", error));
+	const claimFailures = createFailureStreak("Actions", "job claim");
+	const heartbeatFailures = createFailureStreak("Actions", "job heartbeat");
+	const { baseMs = 3e4, maxMs = 9e5 } = backoff;
+	const active = /* @__PURE__ */ new Map();
+	/** Every job this worker started, until it has settled — what `stop()` waits for. */
+	const inFlight = /* @__PURE__ */ new Set();
+	let timer;
+	let heart;
+	let stopping = false;
+	let pass;
+	const isStopping = () => stopping;
+	/** Doubles per attempt, with a jitter so a batch that failed together does not retry together. */
+	const retryDelay = (attempts) => {
+		const step = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempts - 1));
+		return step + Math.floor(Math.random() * Math.min(step, 3e4));
+	};
+	const settle = async (settlement) => {
+		try {
+			await queue.settle(settlement);
+		} catch (error) {
+			onError(error);
+		}
+	};
+	/** Back to the queue with nothing held against it — see {@link TRY_AGAIN}. */
+	const release = (job, delayMs, error) => settle({
+		jobId: job.id,
+		workerId,
+		status: "pending",
+		delayMs,
+		error
+	});
+	const fail = (job, runId, error) => {
+		const exhausted = job.attempts >= job.maxAttempts;
+		return settle({
+			jobId: job.id,
+			workerId,
+			status: exhausted ? "dead" : "pending",
+			...exhausted ? {} : { delayMs: retryDelay(job.attempts) },
+			...runId ? { runId } : {},
+			error,
+			attempt: {
+				status: "failed",
+				workerId,
+				...runId ? { runId } : {},
+				error
+			}
+		});
+	};
+	const execute = async (job) => {
+		const entry = await lookups.getAction(job.spaceId, job.actionId);
+		if (!entry) {
+			await settle({
+				jobId: job.id,
+				workerId,
+				status: "dead",
+				error: "the action this job belongs to no longer exists",
+				attempt: {
+					status: "failed",
+					workerId,
+					error: "action not found"
+				}
+			});
+			return;
+		}
+		let run;
+		try {
+			run = await module.guards.begin({
+				spaceId: job.spaceId,
+				actionId: job.actionId,
+				callerId: "schedule",
+				input: job.input,
+				idempotencyKey: job.id,
+				sharedKey: true,
+				ttlMs: module.limitsFor(entry.document).timeoutMs
+			});
+		} catch (error) {
+			const refusal = error instanceof ActionRunError ? error.reason : void 0;
+			/**
+			* Two different things, and telling them apart is what decides whether the job survives.
+			*
+			* A REFUSAL is the cluster answering: another run holds the key, this replica is full. A throw that is not a
+			* refusal means the guards could not be consulted at all — the shared store is unreachable — and that is
+			* infrastructure rather than anything about this job. Both go back with the attempt REFUNDED.
+			*
+			* Counting an outage as attempts is how a queue loses work: with three attempts and a widening backoff, a
+			* Redis blip of two minutes retires every scheduled job in the cluster as `dead`, permanently, and the digest
+			* nobody got is indistinguishable from one nobody asked for. The job comes back instead, carrying why, and an
+			* operator sees a queue that is waiting rather than a queue that has been emptied.
+			*/
+			if (!refusal || TRY_AGAIN.has(refusal)) {
+				await release(job, retryDelay(1), `not started: ${refusal ?? messageOf(error)}`);
+				return;
+			}
+			await fail(job, void 0, `could not start: ${refusal}`);
+			return;
+		}
+		active.set(job.id, run.controller);
+		try {
+			const result = await module.runAction({
+				entry,
+				input: job.input,
+				spaceId: job.spaceId,
+				environment: job.environment,
+				trigger: job.trigger,
+				callerId: "schedule",
+				runId: run.runId,
+				signal: run.controller.signal
+			});
+			if (result.status === "completed") {
+				await settle({
+					jobId: job.id,
+					workerId,
+					status: "succeeded",
+					runId: run.runId,
+					attempt: {
+						status: "succeeded",
+						workerId,
+						runId: run.runId
+					}
+				});
+				return;
+			}
+			if (result.status === "aborted" && run.controller.signal.aborted) {
+				await settle({
+					jobId: job.id,
+					workerId,
+					status: "cancelled",
+					runId: run.runId,
+					attempt: {
+						status: "cancelled",
+						workerId,
+						runId: run.runId
+					}
+				});
+				return;
+			}
+			await fail(job, run.runId, failureOf(result));
+		} catch (error) {
+			const reason = error instanceof ActionRunError ? error.reason : void 0;
+			if (reason && GIVE_UP.has(reason)) {
+				await settle({
+					jobId: job.id,
+					workerId,
+					status: "dead",
+					runId: run.runId,
+					error: reason,
+					attempt: {
+						status: "failed",
+						workerId,
+						runId: run.runId,
+						error: reason
+					}
+				});
+				return;
+			}
+			await fail(job, run.runId, messageOf(error));
+		} finally {
+			active.delete(job.id);
+			await module.guards.end(run);
+		}
+	};
+	const poll = async () => {
+		const free = workers - active.size;
+		if (stopping || free <= 0) return 0;
+		const claimed = await queue.claim({
+			workerId,
+			leaseMs,
+			limit: free
+		});
+		if (isStopping()) {
+			await Promise.all(claimed.map((job) => release(job, 0, "not started: the replica was shutting down")));
+			return 0;
+		}
+		for (const job of claimed) {
+			const running = execute(job).catch(onError);
+			inFlight.add(running);
+			running.finally(() => inFlight.delete(running));
+		}
+		return claimed.length;
+	};
+	/** Renews every claim this worker holds, and stops the ones an operator asked to cancel. */
+	const beat = async () => {
+		const held = [...active.keys()];
+		if (held.length === 0) return;
+		for (const jobId of await queue.heartbeat({
+			jobIds: held,
+			workerId,
+			leaseMs
+		})) active.get(jobId)?.abort();
+	};
+	/** One pass at a time, and the one under way is kept so `stop()` can wait for the claim it may be making. */
+	const guarded = async () => {
+		if (pass) return;
+		pass = poll().then(() => claimFailures.succeeded()).catch(customOnError ?? claimFailures.failed).finally(() => {
+			pass = void 0;
+		});
+		await pass;
+	};
+	return {
+		poll,
+		beat,
+		inFlight: () => active.size,
+		start: () => {
+			if (timer || workers <= 0) return;
+			timer = setInterval(() => void guarded(), pollMs);
+			timer.unref();
+			heart = setInterval(() => void beat().then(() => heartbeatFailures.succeeded()).catch(customOnError ?? heartbeatFailures.failed), Math.max(1e3, Math.floor(leaseMs / 3)));
+			heart.unref();
+		},
+		stop: async () => {
+			stopping = true;
+			clearInterval(timer);
+			timer = void 0;
+			await pass;
+			if (inFlight.size > 0) serverLog.info("Actions", `waiting for ${inFlight.size} running job(s) to finish before stopping`);
+			/**
+			* Drained rather than abandoned: a deploy finishes the jobs it started instead of leaving them to be retried.
+			*
+			* The heartbeat is stopped only AFTER, and that is the half that makes waiting safe. A job longer than its
+			* lease used to lose its claim the moment the drain began — another replica took it over and ran it again
+			* while this one was still finishing it, and the drain gave up at the lease regardless.
+			*/
+			await Promise.allSettled([...inFlight]);
+			clearInterval(heart);
+			heart = void 0;
+		}
+	};
+};
+//#endregion
+export { createJobWorker };

package/dist/modules/actions/jobs/worker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/moduleFor.js

@@ -1,4 +1,5 @@
 import { createActionsModule } from "./index.js";
+import { realtimeModuleFor } from "../realtime/index.js";
 //#region src/modules/actions/moduleFor.ts
 /**
 * The one actions module for a server, whoever asks first.
@@ -19,15 +20,18 @@ var actionsModuleFor = (config) => {
 	if (existing) return existing;
 	const module = createActionsModule({
 		lookups,
-		tasks: config.action?.tasks,
+		functions: config.functions,
 		limits: config.action?.limits,
 		concurrency: config.action?.concurrency,
 		kv: config.action?.kv,
+		jobs: config.action?.jobs,
 		rateLimit: config.action?.rateLimit,
 		idempotency: config.action?.idempotency,
+		signingSecret: config.action?.signingSecret,
 		dbDrivers: config.action?.dbDrivers,
 		email: config.action?.email,
-		onRun: config.action?.onRun
+		onRun: config.action?.onRun,
+		realtime: realtimeModuleFor(config)
 	});
 	modules.set(config, module);
 	return module;

package/dist/modules/actions/runtime/errors.d.ts

@@ -14,3 +14,15 @@ export declare class ActionRunError extends Error {
     steps?: ActionRunStep[];
     constructor(reason: ActionErrorReason, message: string);
 }
+/**
+ * A step refusing to go on, with a reason written for whoever called — a password too easy to guess, a board that is
+ * read-only, a quota reached.
+ *
+ * What any other step throws stays in the run's record and never reaches the caller: an error can carry a query, a
+ * URL, a credential's name, and a page is shown to anybody. This one says, by its type, that its message was written
+ * to be read. A run that ends on it answers `status: 'failed'` with the message as `error`, which a page's flow reads
+ * as `{{ step.error }}` — the same place a refusal before the run began puts its own.
+ */
+export declare class ActionRefusal extends Error {
+    constructor(message: string);
+}

package/dist/modules/actions/runtime/errors.js

@@ -18,5 +18,20 @@ var ActionRunError = class extends Error {
 		this.reason = reason;
 	}
 };
+/**
+* A step refusing to go on, with a reason written for whoever called — a password too easy to guess, a board that is
+* read-only, a quota reached.
+*
+* What any other step throws stays in the run's record and never reaches the caller: an error can carry a query, a
+* URL, a credential's name, and a page is shown to anybody. This one says, by its type, that its message was written
+* to be read. A run that ends on it answers `status: 'failed'` with the message as `error`, which a page's flow reads
+* as `{{ step.error }}` — the same place a refusal before the run began puts its own.
+*/
+var ActionRefusal = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ActionRefusal";
+	}
+};
 //#endregion
-export { ActionRunError };
+export { ActionRefusal, ActionRunError };

package/dist/modules/actions/runtime/kvChange.d.ts

@@ -0,0 +1,27 @@
+/** What a change needs of a store: read a key, and write it only if it still holds what was read. */
+export type KvChangeStore<V> = {
+    get: (key: string) => Promise<V | undefined>;
+    swap: (key: string, expected: V | undefined, next: V, ttlSeconds?: number) => Promise<boolean>;
+};
+/**
+ * The lifetime a change writes with: a number of seconds, one worked out from the value written, or none.
+ */
+export type KvChangeLifetime<T> = number | ((next: T) => number | undefined);
+export type KvChangeOptions<T> = {
+    lifetime?: KvChangeLifetime<T> | undefined;
+    /**
+     * The error a change that kept losing ends with — an `ActionRefusal` where there is one to make: being too busy is
+     * something to tell whoever asked, not a fault. Handed in because this function may import nothing.
+     */
+    refusal: (message: string) => Error;
+};
+/**
+ * Reads `key`, hands its value to `change`, and writes back what that answers — unless somebody wrote in between, and
+ * then it reads again and asks again. `change` answering `undefined` writes nothing. Answers what was written, or
+ * `undefined` when nothing was. Losing every time ends in `refusal`, whose message names no key: it is for a visitor.
+ *
+ * The one read-change-write there is: `ctx.kv.change`, a list's writes, and the sandbox's `ctx.kv.change` too — its
+ * guest is handed THIS function's source (`isolate.ts`), so it must stay self-contained: no import, nothing of this
+ * module's, only what the guest's globals also have (`setTimeout`, `Math`).
+ */
+export declare const changeKv: <V, T extends V>(store: KvChangeStore<V>, key: string, change: (current: V | undefined) => T | undefined | Promise<T | undefined>, { lifetime, refusal }: KvChangeOptions<T>) => Promise<T | undefined>;

package/dist/modules/actions/runtime/kvChange.js

@@ -0,0 +1,23 @@
+//#region src/modules/actions/runtime/kvChange.ts
+/**
+* Reads `key`, hands its value to `change`, and writes back what that answers — unless somebody wrote in between, and
+* then it reads again and asks again. `change` answering `undefined` writes nothing. Answers what was written, or
+* `undefined` when nothing was. Losing every time ends in `refusal`, whose message names no key: it is for a visitor.
+*
+* The one read-change-write there is: `ctx.kv.change`, a list's writes, and the sandbox's `ctx.kv.change` too — its
+* guest is handed THIS function's source (`isolate.ts`), so it must stay self-contained: no import, nothing of this
+* module's, only what the guest's globals also have (`setTimeout`, `Math`).
+*/
+var changeKv = async (store, key, change, { lifetime, refusal }) => {
+	const attempts = 25;
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		const current = await store.get(key);
+		const next = await change(current);
+		if (next === void 0) return;
+		if (await store.swap(key, current, next, typeof lifetime === "function" ? lifetime(next) : lifetime)) return next;
+		await new Promise((resolve) => setTimeout(resolve, Math.random() * Math.min(5 + attempt * 5, 50)));
+	}
+	throw refusal("Many people are changing this at once — try again in a moment");
+};
+//#endregion
+export { changeKv };

package/dist/modules/actions/runtime/kvList.d.ts

@@ -0,0 +1,51 @@
+/** One entry of a list: what it is called, where it sorts, and what it carries. */
+export type KvListEntry = {
+    id: string;
+    score: number;
+    value: unknown;
+};
+export type KvListRange = {
+    /** How many entries to skip first. 0 when absent. */
+    offset?: number;
+    /** How many to answer. All of them when absent. */
+    limit?: number;
+    /** `desc` — the highest score first — when absent. */
+    order?: 'asc' | 'desc';
+};
+/**
+ * The most a list holds. A list is one value of the store, read and written whole, so it is for what a page shows at
+ * once — the latest twenty, a leaderboard, a gallery — not for a table.
+ */
+export declare const MAX_LIST_ENTRIES = 500;
+/**
+ * Its largest size, as JSON. Every store holds far more; this is what a list is read and written whole for — a page's
+ * worth of entries, each an id and what the page shows — and past it, a list is being used as a table.
+ */
+export declare const MAX_LIST_BYTES = 128000;
+export declare const listIdProblem: (id: unknown) => string | undefined;
+/** The entries a stored list holds — none for a key that holds nothing, or something that is not a list. */
+export declare const parseList: (raw: string | undefined) => KvListEntry[];
+export type KvListPutOptions = {
+    /** How many to keep, the highest scores; what falls past it is dropped. {@link MAX_LIST_ENTRIES} at most. */
+    keep?: number;
+    /**
+     * Replace an entry already there only with a score at least as high — a player's best, or the latest of two writes
+     * that arrived out of order. Otherwise the one there stays and nothing is written.
+     */
+    higherOnly?: boolean;
+};
+/** What a put did: whether the entry went in, and what `keep` dropped to make room. */
+export type KvListPut = {
+    stored: boolean;
+    dropped: KvListEntry[];
+};
+/**
+ * The list with `entry` in it — replacing the one with its id — sorted and cut to the highest `keep`, and what the cut
+ * dropped; `undefined` when `higherOnly` keeps the one there. Refused, with what to do instead, when the result would
+ * be larger than a list may be.
+ */
+export declare const withEntry: (entries: KvListEntry[], entry: KvListEntry, { keep, higherOnly }?: KvListPutOptions) => {
+    kept: KvListEntry[];
+    dropped: KvListEntry[];
+} | undefined;
+export declare const rangeOf: (entries: KvListEntry[], { offset, limit, order }?: KvListRange) => KvListEntry[];

package/dist/modules/actions/runtime/kvList.js

@@ -0,0 +1,52 @@
+//#region src/modules/actions/runtime/kvList.ts
+/**
+* The most a list holds. A list is one value of the store, read and written whole, so it is for what a page shows at
+* once — the latest twenty, a leaderboard, a gallery — not for a table.
+*/
+var MAX_LIST_ENTRIES = 500;
+/**
+* Its largest size, as JSON. Every store holds far more; this is what a list is read and written whole for — a page's
+* worth of entries, each an id and what the page shows — and past it, a list is being used as a table.
+*/
+var MAX_LIST_BYTES = 128e3;
+var ID = /^[A-Za-z0-9:_.@-]{1,128}$/;
+var listIdProblem = (id) => typeof id === "string" && ID.test(id) ? void 0 : "A list entry’s id is 1-128 of A-Z a-z 0-9 : _ . @ -";
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isEntry = (value) => isRecord(value) && typeof value.id === "string" && typeof value.score === "number";
+/** The entries a stored list holds — none for a key that holds nothing, or something that is not a list. */
+var parseList = (raw) => {
+	if (raw === void 0) return [];
+	try {
+		const value = JSON.parse(raw);
+		return Array.isArray(value) ? value.filter(isEntry) : [];
+	} catch {
+		return [];
+	}
+};
+/** Highest score first; entries that tie keep a stable order, by id. */
+var byScore = (a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+* The list with `entry` in it — replacing the one with its id — sorted and cut to the highest `keep`, and what the cut
+* dropped; `undefined` when `higherOnly` keeps the one there. Refused, with what to do instead, when the result would
+* be larger than a list may be.
+*/
+var withEntry = (entries, entry, { keep = 500, higherOnly = false } = {}) => {
+	const there = entries.find((existing) => existing.id === entry.id);
+	if (higherOnly && there && there.score > entry.score) return;
+	const sorted = [...entries.filter((existing) => existing.id !== entry.id), entry].sort(byScore);
+	const cut = Math.min(Math.max(0, Math.floor(keep)), 500);
+	const kept = sorted.slice(0, cut);
+	const bytes = Buffer.byteLength(JSON.stringify(kept));
+	if (bytes > 128e3) throw new Error(`A list is at most ${MAX_LIST_BYTES} bytes and this one would be ${bytes}: keep fewer entries (\`keep\`), or store less in each one — an id and what a page shows, with the rest under its own key`);
+	return {
+		kept,
+		dropped: sorted.slice(cut)
+	};
+};
+var rangeOf = (entries, { offset = 0, limit, order = "desc" } = {}) => {
+	const ordered = order === "asc" ? entries.toReversed() : entries;
+	const start = Math.max(0, Math.floor(offset));
+	return ordered.slice(start, limit === void 0 ? void 0 : start + Math.max(0, Math.floor(limit)));
+};
+//#endregion
+export { MAX_LIST_BYTES, MAX_LIST_ENTRIES, listIdProblem, parseList, rangeOf, withEntry };

package/dist/modules/actions/runtime/kvStore.d.ts

@@ -23,5 +23,13 @@ export type KvStoreConfig = {
  *    table.
  * 3. **Nothing is caught.** This is not a cache: a miss means the rate limit did not count and the idempotency key
  *    was not seen, so an adapter that cannot answer fails the run rather than being read as "no value".
+ *
+ * A list is one value, changed only by `swap`: read, change, write back if nobody wrote in between, and read again if
+ * somebody did. Every adapter can do that much, so lists work on all of them without a command of their own. They
+ * live under `list:` rather than beside the values, so no key a flow writes can be one.
  */
+/** What every key is prefixed with unless the store was given another. */
+export declare const DEFAULT_KV_PREFIX = "kv:";
+/** Where a list lives, after the prefix: its own segment, so a list and a value of the same name never meet. */
+export declare const LIST_SEGMENT = "list:";
 export declare const createKvStore: (adapter: ActionKvAdapter, { prefix }?: KvStoreConfig) => ActionKvStore;

package/dist/modules/actions/runtime/kvStore.js

@@ -1,23 +1,20 @@
-//#region src/modules/actions/runtime/kvStore.ts
-/**
-* The `kv` tasks, over whatever a deployment gave them to write into.
-*
-* The adapter is transport: strings in, strings out. Everything a counter's BEHAVIOUR depends on is here, in one
-* place, for every deployment at once — which is the point of the split. Three rules:
-*
-* 1. **Values round-trip through JSON**, so a flow reads back what it wrote instead of its own `toString`. A value
-*    written by something else is answered as the string it is rather than failing.
-* 2. **A counter's TTL is set once, by whoever created it, and never extended.** A window refreshed on every hit
-*    never closes while traffic keeps arriving — which is a rate limit that stops limiting exactly when it is
-*    being leant on. The counter is the one that created it precisely when the increment returns its own amount,
-*    so this needs no conditional-expire support from the adapter and works the same on Redis, Memcached or a
-*    table.
-* 3. **Nothing is caught.** This is not a cache: a miss means the rate limit did not count and the idempotency key
-*    was not seen, so an adapter that cannot answer fails the run rather than being read as "no value".
-*/
+import { ActionRefusal } from "./errors.js";
+import { changeKv } from "./kvChange.js";
+import { listIdProblem, parseList, rangeOf, withEntry } from "./kvList.js";
+/** Where a list lives, after the prefix: its own segment, so a list and a value of the same name never meet. */
+var LIST_SEGMENT = "list:";
+var refusal = (message) => new ActionRefusal(message);
 var createKvStore = (adapter, { prefix = "kv:" } = {}) => {
 	const prefixed = (key) => `${prefix}${key}`;
-	return {
+	const listKey = (list) => `${prefix}${LIST_SEGMENT}${list}`;
+	/** Applies `change` to the list and writes it back unless somebody wrote first — then reads again. */
+	const changeList = async (list, change) => {
+		return await changeKv(adapter, listKey(list), (raw) => {
+			const next = change(parseList(raw));
+			return next ? JSON.stringify(next) : void 0;
+		}, { refusal }) !== void 0;
+	};
+	const store = {
 		get: async (key) => {
 			const raw = await adapter.get(prefixed(key));
 			if (raw === void 0) return;
@@ -34,8 +31,37 @@ var createKvStore = (adapter, { prefix = "kv:" } = {}) => {
 			const value = await adapter.increment(full, amount);
 			if (ttlSeconds !== void 0 && value === amount) await adapter.expire(full, ttlSeconds);
 			return value;
-		}
+		},
+		swap: (key, expected, next, ttlSeconds) => adapter.swap(prefixed(key), expected === void 0 ? void 0 : JSON.stringify(expected), JSON.stringify(next), ttlSeconds),
+		listPut: async (list, entry, options = {}) => {
+			const problem = listIdProblem(entry.id);
+			if (problem) throw new Error(problem);
+			if (!Number.isFinite(entry.score)) throw new Error("A list entry’s score is a number");
+			let put = {
+				stored: false,
+				dropped: []
+			};
+			await changeList(list, (entries) => {
+				const next = withEntry(entries, entry, options);
+				put = next ? {
+					stored: true,
+					dropped: next.dropped
+				} : {
+					stored: false,
+					dropped: []
+				};
+				return next?.kept;
+			});
+			return put;
+		},
+		listRange: async (list, range) => rangeOf(parseList(await adapter.get(listKey(list))), range),
+		listRemove: (list, id) => changeList(list, (entries) => entries.some((entry) => entry.id === id) ? entries.filter((entry) => entry.id !== id) : void 0),
+		change: (key, change, lifetime) => changeKv(store, key, change, {
+			lifetime,
+			refusal
+		})
 	};
+	return store;
 };
 //#endregion
-export { createKvStore };
+export { LIST_SEGMENT, createKvStore };

package/dist/modules/actions/runtime/memoryKv.d.ts

@@ -1,2 +1,5 @@
+import { StoreMethods } from '../../../core/server/fleet/channel';
 import { ActionKvAdapter } from '../types';
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+export declare const KV_METHODS: StoreMethods<ActionKvAdapter>;
 export declare const createMemoryKv: () => ActionKvAdapter;

package/dist/modules/actions/runtime/memoryKv.js

@@ -11,6 +11,15 @@
 */
 /** How many writes go by before the map is swept. Cheap enough to be unnoticeable, often enough to bound it. */
 var SWEEP_EVERY = 256;
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+var KV_METHODS = {
+	get: true,
+	set: true,
+	delete: true,
+	increment: true,
+	expire: true,
+	swap: true
+};
 var createMemoryKv = () => {
 	const entries = /* @__PURE__ */ new Map();
 	let writes = 0;
@@ -70,8 +79,17 @@ var createMemoryKv = () => {
 				expiresAt: expiry(ttlSeconds)
 			});
 			return Promise.resolve();
+		},
+		swap: (key, expected, next, ttlSeconds) => {
+			if (read(key)?.value !== expected) return Promise.resolve(false);
+			entries.set(key, {
+				value: next,
+				expiresAt: expiry(ttlSeconds)
+			});
+			sweep();
+			return Promise.resolve(true);
 		}
 	};
 };
 //#endregion
-export { createMemoryKv };
+export { KV_METHODS, createMemoryKv };

package/dist/modules/actions/runtime/namespaceKv.d.ts

@@ -1,9 +1,7 @@
 import { ActionKvStore } from '../types';
+export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;
 /**
- * Prefixes every key with the space that wrote it.
- *
- * A shared store with unprefixed keys is one space reading — or overwriting — another's counters, which is the
- * cross-tenant leak this whole design exists to avoid. Done at the runner rather than in each task so a
- * deployment's own tasks inherit it too.
+ * Every key a space's store holds, as patterns over the adapter's keys (`createKvStore`'s `prefix`, `kv:` unless it was
+ * given another) — for whoever has to let all of them go at once: a space that is deleted, or reset to how it started.
  */
-export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;
+export declare const spaceKvPatterns: (spaceId: number, prefix?: string) => string[];