@plitzi/sdk-server 0.38.4 → 0.38.6

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

@@ -1,14 +1,4 @@
 //#region src/modules/actions/runtime/memoryKv.ts
-/**
-* The `kv` tasks' fallback store: in this process, and nowhere else.
-*
-* Real enough for a single replica and for local work, and deliberately not pretending otherwise — a deployment
-* running several replicas passes an adapter over something shared, because a counter that only counts its own
-* replica is a rate limit that multiplies by the number of them.
-*
-* An adapter like any other: it stores strings and obeys no rules of its own. What a counter DOES lives in
-* `createKvStore`, so the in-process store and a deployment's own behave identically rather than nearly so.
-*/
 /** 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`). */
@@ -20,8 +10,16 @@ var KV_METHODS = {
 	expire: true,
 	swap: true
 };
-var createMemoryKv = () => {
-	const entries = /* @__PURE__ */ new Map();
+/**
+* The store's rules over a map somebody holds: what `createMemoryKv` is, and what a store that keeps the map
+* somewhere (`createFileKv`) is too — so the two answer identically and differ only in where the map lives.
+*
+* An adapter like any other: it stores strings and obeys no rules of its own. What a counter DOES lives in
+* `createKvStore`, so the in-process store and a deployment's own behave identically rather than nearly so.
+*
+* `changed` is told after every write that changed the map — an expired entry swept or read past included.
+*/
+var createMapKv = (entries, changed = () => void 0) => {
 	let writes = 0;
 	/**
 	* Expiry only ever happened on READ, which is fine for a counter that is read as often as it is written and
@@ -33,63 +31,80 @@ var createMemoryKv = () => {
 		writes += 1;
 		if (writes % SWEEP_EVERY !== 0) return;
 		const now = Date.now();
+		const before = entries.size;
 		entries.forEach((entry, key) => {
 			if (entry.expiresAt !== void 0 && entry.expiresAt <= now) entries.delete(key);
 		});
+		if (entries.size !== before) changed();
 	};
 	const read = (key) => {
 		const entry = entries.get(key);
 		if (!entry) return;
 		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
 			entries.delete(key);
+			changed();
 			return;
 		}
 		return entry;
 	};
 	const expiry = (ttlSeconds) => ttlSeconds === void 0 ? void 0 : Date.now() + ttlSeconds * 1e3;
+	const write = (key, entry) => {
+		entries.set(key, entry);
+		changed();
+		sweep();
+	};
 	return {
 		get: (key) => Promise.resolve(read(key)?.value),
 		set: (key, value, ttlSeconds) => {
-			entries.set(key, {
+			write(key, {
 				value,
 				expiresAt: expiry(ttlSeconds)
 			});
-			sweep();
 			return Promise.resolve();
 		},
 		delete: (key) => {
-			entries.delete(key);
+			if (entries.delete(key)) changed();
 			return Promise.resolve();
 		},
 		increment: (key, amount) => {
 			const current = read(key);
 			const base = Number(current?.value ?? 0);
 			const next = (Number.isFinite(base) ? base : 0) + amount;
-			entries.set(key, {
+			write(key, {
 				value: String(next),
 				expiresAt: current?.expiresAt
 			});
-			sweep();
 			return Promise.resolve(next);
 		},
 		expire: (key, ttlSeconds) => {
 			const current = read(key);
-			if (current) entries.set(key, {
-				...current,
-				expiresAt: expiry(ttlSeconds)
-			});
+			if (current) {
+				entries.set(key, {
+					...current,
+					expiresAt: expiry(ttlSeconds)
+				});
+				changed();
+			}
 			return Promise.resolve();
 		},
 		swap: (key, expected, next, ttlSeconds) => {
 			if (read(key)?.value !== expected) return Promise.resolve(false);
-			entries.set(key, {
+			write(key, {
 				value: next,
 				expiresAt: expiry(ttlSeconds)
 			});
-			sweep();
 			return Promise.resolve(true);
 		}
 	};
 };
+/**
+* The `kv` tasks' fallback store: in this process, and nowhere else — gone when it stops.
+*
+* Real enough for a single replica and for local work, and deliberately not pretending otherwise — a deployment
+* running several replicas passes an adapter over something shared, because a counter that only counts its own
+* replica is a rate limit that multiplies by the number of them. One that must survive a restart passes
+* `createFileKv` (one process) or `createSqliteKv` (`@plitzi/sdk-server/sqlite`).
+*/
+var createMemoryKv = () => createMapKv(/* @__PURE__ */ new Map());
 //#endregion
-export { KV_METHODS, createMemoryKv };
+export { KV_METHODS, createMapKv, createMemoryKv };

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

@@ -1,4 +1,6 @@
 import { ActionKvStore } from '../types';
+/** Every key `store` is asked for, under `prefix`: a space's own keys, or a plugin's inside the space's. */
+export declare const prefixKv: (store: ActionKvStore, prefix: string) => ActionKvStore;
 export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;
 /**
  * Every key a space's store holds, as patterns over the adapter's keys (`createKvStore`'s `prefix`, `kv:` unless it was

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

@@ -8,8 +8,9 @@ import { LIST_SEGMENT } from "./kvStore.js";
 * deployment's own tasks inherit it too.
 */
 var spaceScope = (spaceId) => `action:${spaceId}:`;
-var namespaceKv = (store, spaceId) => {
-	const scoped = (key) => `${spaceScope(spaceId)}${key}`;
+/** Every key `store` is asked for, under `prefix`: a space's own keys, or a plugin's inside the space's. */
+var prefixKv = (store, prefix) => {
+	const scoped = (key) => `${prefix}${key}`;
 	return {
 		get: (key) => store.get(scoped(key)),
 		set: (key, value, ttlSeconds) => store.set(scoped(key), value, ttlSeconds),
@@ -22,10 +23,11 @@ var namespaceKv = (store, spaceId) => {
 		change: (key, change, lifetime) => store.change(scoped(key), change, lifetime)
 	};
 };
+var namespaceKv = (store, spaceId) => prefixKv(store, spaceScope(spaceId));
 /**
 * 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.
 */
 var spaceKvPatterns = (spaceId, prefix = "kv:") => [`${prefix}${spaceScope(spaceId)}*`, `${prefix}${LIST_SEGMENT}${spaceScope(spaceId)}*`];
 //#endregion
-export { namespaceKv, spaceKvPatterns };
+export { namespaceKv, prefixKv, spaceKvPatterns };

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

@@ -9,7 +9,8 @@ import { ActionLookups } from '../types';
  * page still learns nothing about what happens on the other side.
  *
  * Its input is the page's own context — route params, then query params — plus whatever the element declares, so
- * an action feeding `/blog/:slug` reads `{{ input.slug }}` and needs nothing else. The action's own input contract
- * still drops everything it did not declare.
+ * an action feeding `/blog/:slug` reads `{{ input.slug }}` and needs nothing else; a refresh's own params (what
+ * `reloadApi` or a bound `input` asked for) come last and win. The action's own input contract still drops everything
+ * it did not declare.
  */
 export declare const createActionResolver: (lookups: ActionLookups, module: ActionsModule) => RscElementResolver;

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

@@ -35,8 +35,9 @@ var shareKey = (parts) => createHash("sha256").update(JSON.stringify(parts)).dig
 * page still learns nothing about what happens on the other side.
 *
 * Its input is the page's own context — route params, then query params — plus whatever the element declares, so
-* an action feeding `/blog/:slug` reads `{{ input.slug }}` and needs nothing else. The action's own input contract
-* still drops everything it did not declare.
+* an action feeding `/blog/:slug` reads `{{ input.slug }}` and needs nothing else; a refresh's own params (what
+* `reloadApi` or a bound `input` asked for) come last and win. The action's own input contract still drops everything
+* it did not declare.
 */
 var createActionResolver = (lookups, module) => {
 	const share = createRenderShare();
@@ -59,7 +60,8 @@ var createActionResolver = (lookups, module) => {
 		const values = {
 			...routeParams,
 			...queryParams,
-			...input
+			...input,
+			...req.ctx.rscParams
 		};
 		const trigger = findTriggerNode(entry.document.nodes, "render");
 		const ttlMs = trigger ? triggerCacheMs(triggerParams(trigger)) : 0;
@@ -73,7 +75,8 @@ var createActionResolver = (lookups, module) => {
 		]);
 		const callerId = user ? `user:${user.id}` : "render";
 		let ownRunId;
-		const startRun = async () => {
+		/** `stop` is the shared run's: aborted once nobody is waiting for it, this render included. */
+		const startRun = async (stop) => {
 			/**
 			* A key of its own per render, so two visitors are never each other's duplicate.
 			*
@@ -93,12 +96,13 @@ var createActionResolver = (lookups, module) => {
 			});
 			ownRunId = run.runId;
 			/**
-			* The render giving up ends the run, not just the wait for it.
+			* The renders giving up end the run, not just the wait for it — all of them: a render another visitor joined is
+			* that visitor's answer too.
 			*
-			* `resolveRscData` stops waiting when an element's budget is gone, and before this the run carried on to
-			* its own timeout — holding a slot and an outbound connection for a page that had already been answered.
+			* `resolveRscData` stops waiting when an element's budget is gone or the browser hung up, and before this the
+			* run carried on to its own timeout — holding a slot and an outbound connection for a page already answered.
 			*/
-			const releaseRenderStop = onAbort(signal, () => run.controller.abort());
+			const releaseRenderStop = onAbort(stop, () => run.controller.abort());
 			const startedAt = Date.now();
 			const summaryOf = (outcome) => ({
 				actionId: entry.id,
@@ -195,7 +199,7 @@ var createActionResolver = (lookups, module) => {
 		* reads all in the same instant.
 		*/
 		try {
-			const { output, summary } = await share.run(key, ttlMs, startRun);
+			const { output, summary } = await share.run(key, ttlMs, startRun, signal);
 			record(summary);
 			return output;
 		} catch (error) {

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

@@ -1,28 +1,11 @@
-/**
- * One answer for the visitors asking the same question at the same moment — and, when the author says so, for the
- * ones asking it a moment later.
- *
- * A `render` is a READ repeated once per visitor. A thousand people opening one page is a thousand runs of the
- * same flow and a thousand outbound requests to whatever it reads, all in flight together, all computing the same
- * thing. Refusing them is the wrong answer — that is what a per-space cap did, and it broke the page that was
- * doing well. Sharing is the right one.
- *
- * Two behaviours, and only one of them is a cache:
- *
- * - **In flight**: a render that arrives while an identical one is running joins it. Always on, and it cannot
- *   serve anything stale — the answer is being computed right now, for this request as much as for the first.
- * - **Reuse**: the answer is kept for as long as the trigger's `cacheSeconds` says. Off unless authored, because
- *   only the author knows whether their page may repeat itself.
- *
- * A failure is never kept. The joiners of a failed run fail with it — they would have failed too — but the next
- * request tries again rather than being told for a minute about a request that was already over.
- *
- * In-process, and that is honest here in a way it is not for a lock: two replicas each keeping their own copy is
- * two computations instead of one, while two replicas each keeping their own LOCK is no lock at all.
- */
 export type RenderShare = {
-    /** Runs `produce`, or joins whatever is already producing the same key. `ttlMs` of 0 keeps nothing afterwards. */
-    run: (key: string, ttlMs: number, produce: () => Promise<unknown>) => Promise<unknown>;
+    /**
+     * Runs `produce`, or joins whatever is already producing the same key. `ttlMs` of 0 keeps nothing afterwards.
+     *
+     * `signal` is this caller's: aborted, the caller stops waiting — and the run is stopped (`produce`'s own signal)
+     * only once every caller waiting on it has. One visitor who gave up must not cost the others their answer.
+     */
+    run: (key: string, ttlMs: number, produce: (signal: AbortSignal) => Promise<unknown>, signal?: AbortSignal) => Promise<unknown>;
     /** Entries currently held, for a deployment that wants to see it. */
     size: () => number;
 };

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

@@ -1,3 +1,4 @@
+import onAbort from "../../../helpers/onAbort.js";
 //#region src/modules/actions/runtime/renderShare.ts
 /** Keeps the map from growing without bound on a space with many keys: expired entries are dropped on write. */
 var sweep = (entries, now) => {
@@ -5,27 +6,60 @@ var sweep = (entries, now) => {
 		if (!entry.inFlight && (entry.expiresAt === void 0 || entry.expiresAt <= now)) entries.delete(key);
 	});
 };
+/** What a caller that stopped waiting is answered with: its own end, not the run's. */
+var stoppedWaiting = () => new DOMException("The render was aborted: its page stopped waiting for it", "AbortError");
+/** One caller waiting on a run in flight, until it answers or the caller gives up — whichever comes first. */
+var wait = (entry, inFlight, signal) => {
+	entry.waiting += 1;
+	let waiting = true;
+	const leave = () => {
+		if (!waiting) return;
+		waiting = false;
+		entry.waiting -= 1;
+		if (entry.waiting === 0) entry.controller?.abort();
+	};
+	return new Promise((resolve, reject) => {
+		const release = onAbort(signal, () => {
+			leave();
+			reject(stoppedWaiting());
+		});
+		inFlight.then((value) => {
+			waiting = false;
+			release();
+			resolve(value);
+		}, (error) => {
+			waiting = false;
+			release();
+			reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	});
+};
 var createRenderShare = (now = Date.now) => {
 	const entries = /* @__PURE__ */ new Map();
-	const run = async (key, ttlMs, produce) => {
+	const run = async (key, ttlMs, produce, signal) => {
 		const existing = entries.get(key);
-		if (existing?.inFlight) return existing.inFlight;
+		if (existing?.inFlight) return wait(existing, existing.inFlight, signal);
 		if (existing && existing.expiresAt !== void 0 && existing.expiresAt > now()) return existing.value;
-		const inFlight = produce();
-		entries.set(key, { inFlight });
-		try {
-			const value = await inFlight;
+		const controller = new AbortController();
+		const inFlight = produce(controller.signal);
+		const entry = {
+			inFlight,
+			controller,
+			waiting: 0
+		};
+		entries.set(key, entry);
+		inFlight.then((value) => {
 			sweep(entries, now());
 			if (ttlMs > 0) entries.set(key, {
 				value,
-				expiresAt: now() + ttlMs
+				expiresAt: now() + ttlMs,
+				waiting: 0
 			});
-			else entries.delete(key);
-			return value;
-		} catch (error) {
-			entries.delete(key);
-			throw error;
-		}
+			else if (entries.get(key) === entry) entries.delete(key);
+		}, () => {
+			if (entries.get(key) === entry) entries.delete(key);
+		});
+		return wait(entry, inFlight, signal);
 	};
 	return {
 		run,

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

@@ -224,7 +224,12 @@ var createActionRunner = (config, registryFor, baseFetch = fetch) => {
 			redactor,
 			signing
 		}, request, signal, runFetch);
-		const buildContext = contextFor(controller.signal, createRunFetch(baseFetch, controller.signal, limits, lineage));
+		/** The request budget ran out: said on the server's log at once, and in the step that hit it. */
+		let budgetSpent;
+		const buildContext = contextFor(controller.signal, createRunFetch(baseFetch, controller.signal, limits, lineage, (message) => {
+			budgetSpent = message;
+			serverLog.warn("Actions", `"${entry.id}" (run ${runId}): ${message}`);
+		}));
 		const trace = [];
 		const steps = [];
 		const startedAt = Date.now();
@@ -285,12 +290,20 @@ var createActionRunner = (config, registryFor, baseFetch = fetch) => {
 			const log = (line) => {
 				if (logs.length < MAX_LOG_LINES) logs.push(redact(line.length > MAX_LOG_LINE ? `${line.slice(0, MAX_LOG_LINE)}…` : line));
 			};
+			/** The step that spent the budget says so, whether or not it caught the refusal. */
+			const noteBudget = () => {
+				if (budgetSpent) {
+					log(budgetSpent);
+					budgetSpent = void 0;
+				}
+			};
 			try {
 				const outcome = await runNode(node, scope, registry, (stepScope) => ({
 					...build(stepScope),
 					log
 				}));
 				if (late()) return outcome;
+				noteBudget();
 				const endTime = Date.now();
 				trace.push({
 					node,
@@ -312,6 +325,7 @@ var createActionRunner = (config, registryFor, baseFetch = fetch) => {
 				return outcome;
 			} catch (error) {
 				if (late()) throw error;
+				noteBudget();
 				const endTime = Date.now();
 				const message = redact(error instanceof Error ? error.message : String(error));
 				trace.push({

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

@@ -18,6 +18,21 @@ var coerce = (type, value) => {
 		default: return typeof value === "object" && value !== null ? void 0 : String(value);
 	}
 };
+/** What a value is, in the words a refusal uses for it. */
+var kindOf = (value) => {
+	if (Array.isArray(value)) return "a list";
+	if (typeof value === "object" && value !== null) return "an object";
+	return typeof value === "string" ? "text that is not one" : `a ${typeof value}`;
+};
+/**
+* Why a value does not fit its field, said the way the fix is written.
+*
+* A list or an object sent to a `text` field is nearly always JSON the page meant as text — a step param that is only a
+* `|json_encode` is the value it encodes — so the refusal says which type takes it.
+*/
+var misfit = (key, type, value) => {
+	return `${key} (${type}, got ${kindOf(value)}${type === "text" && typeof value === "object" && value !== null ? "; declare the field `json` to take it" : ""})`;
+};
 /**
 * Coerces a value bag against declared fields.
 *
@@ -37,7 +52,7 @@ var applyFields = (fields, raw) => {
 		}
 		const coerced = coerce(field.type, provided);
 		if (coerced === void 0) {
-			invalid.push(key);
+			invalid.push(misfit(key, field.type, provided));
 			return;
 		}
 		values[key] = coerced;

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

@@ -1,4 +1,7 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/modules/actions/runtime/signing.ts
+/** A signing secret is what every link and key a space hands out stands on: as long as a 256-bit key written out. */
+var MIN_SIGNING_SECRET_LENGTH = 32;
 /**
 * Signing for every space, from the one secret the deployment holds (`signingSecret`).
 *
@@ -22,4 +25,4 @@ var createSigning = (secret) => {
 	};
 };
 //#endregion
-export { createSigning };
+export { MIN_SIGNING_SECRET_LENGTH, createSigning };

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

@@ -14,7 +14,13 @@ import { ActionKvStore, ActionRunRequest, ActionsConfig, ActionTaskContext, Reso
  * Every ceiling lives HERE rather than in each task, because this is the only door a task has to the outside
  * world — a task that had to remember to count its own bytes is a task that will forget.
  */
-export declare const createRunFetch: (base: typeof fetch, signal: AbortSignal, limits: ResolvedActionLimits, lineage: string[]) => typeof fetch;
+export declare const createRunFetch: (base: typeof fetch, signal: AbortSignal, limits: ResolvedActionLimits, lineage: string[], 
+/**
+ * Told once, the first time a request is refused for the budget. A task reading many sources usually catches a
+ * failed fetch and goes on with the rest, which made the budget invisible: twenty sources answered, the rest
+ * "failed" like a network error, and nothing anywhere named the limit.
+ */
+onBudgetSpent?: (message: string) => void) => typeof fetch;
 /** What a task's context is made of that outlives one run: the server's stores and the run's redactor. */
 export type TaskContextDeps = {
     kv: ActionKvStore;

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

@@ -42,11 +42,15 @@ var capped = (response, maxBytes) => {
 * Every ceiling lives HERE rather than in each task, because this is the only door a task has to the outside
 * world — a task that had to remember to count its own bytes is a task that will forget.
 */
-var createRunFetch = (base, signal, limits, lineage) => {
+var createRunFetch = (base, signal, limits, lineage, onBudgetSpent) => {
 	let issued = 0;
 	return async (input, init) => {
 		issued += 1;
-		if (issued > limits.maxRequests) throw new ActionRunError("over_capacity", `Action exceeded its ${limits.maxRequests} outbound request budget`);
+		if (issued > limits.maxRequests) {
+			const message = `Action exceeded its ${limits.maxRequests} outbound request budget — request ${issued} and every one after it were refused. A deployment that needs more raises it: \`createServer({ action: { limits: { maxRequests } } })\`.`;
+			if (issued === limits.maxRequests + 1) onBudgetSpent?.(message);
+			throw new ActionRunError("over_capacity", message);
+		}
 		const headers = new Headers(init?.headers);
 		headers.set("X-Plitzi-Action-Lineage", lineage.join(","));
 		return capped(await base(input, {

package/dist/modules/actions/tasks/registry.d.ts

@@ -13,6 +13,8 @@ export declare const taskNameProblem: (task: Pick<ActionTask, "namespace" | "act
 export type TaskRegistryOptions = {
     /** At least one database driver is registered, so `db.query` has an engine to run against. */
     db?: boolean;
+    /** The server halves of the plugins this server ships, by plugin type: their tasks are `<type>.<action>`. */
+    plugins?: Readonly<Record<string, FunctionsDefinition>>;
 };
 /**
  * Builds the set of tasks this server can run.
@@ -21,4 +23,4 @@ export type TaskRegistryOptions = {
  * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
  * in that deployment does. Both are invisible until a run misbehaves in production.
  */
-export declare const createTaskRegistry: (functions?: readonly FunctionsDefinition[], { db }?: TaskRegistryOptions) => ActionTaskRegistry;
+export declare const createTaskRegistry: (functions?: readonly FunctionsDefinition[], { db, plugins }?: TaskRegistryOptions) => ActionTaskRegistry;

package/dist/modules/actions/tasks/registry.js

@@ -1,5 +1,6 @@
 import { builtinTasks } from "./builtins.js";
 import { dbTasks } from "./db.js";
+import { pluginTaskProblem } from "../../functions/scope.js";
 import { nativeTasks } from "../../functions/native.js";
 //#region src/modules/actions/tasks/registry.ts
 var NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
@@ -22,7 +23,7 @@ var taskNameProblem = (task, reserved = RESERVED_NAMESPACES) => {
 * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
 * in that deployment does. Both are invisible until a run misbehaves in production.
 */
-var createTaskRegistry = (functions = [], { db = false } = {}) => {
+var createTaskRegistry = (functions = [], { db = false, plugins = {} } = {}) => {
 	const tasks = /* @__PURE__ */ new Map();
 	(db ? [...builtinTasks, ...dbTasks] : builtinTasks).forEach((task) => tasks.set(taskName(task), {
 		...task,
@@ -40,6 +41,19 @@ var createTaskRegistry = (functions = [], { db = false } = {}) => {
 			origin: "deployment"
 		});
 	});
+	Object.entries(plugins).forEach(([plugin, definition]) => {
+		nativeTasks([definition], { plugin }).forEach((task) => {
+			const problem = taskNameProblem(task) ?? (task.namespace === plugin ? void 0 : pluginTaskProblem(plugin, task.namespace, task.action));
+			if (problem) throw new Error(`[Actions] ${problem}`);
+			const name = taskName(task);
+			if (tasks.has(name)) throw new Error(`[Actions] Task "${name}" is registered twice`);
+			tasks.set(name, {
+				...task,
+				name,
+				origin: "plugin"
+			});
+		});
+	});
 	return {
 		get: (name) => tasks.get(name),
 		list: () => [...tasks.values()]

package/dist/modules/actions/types.d.ts

@@ -117,9 +117,21 @@ export type ActionLookups = {
     /**
      * The space's own functions as of that revision — the bundle and what it declared when saved, run by the deployment's
      * sandbox (`functions.runner`), or by the space's own runtime when it answers one with a `runner` of its own. Only
-     * asked when a run names a task the deployment does not have, or a request a path under `/api/`.
+     * asked when a run names a task the deployment does not have, or a request a path under `/fn/`.
      */
     getFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<SpaceFunctions | undefined>;
+    /**
+     * The server halves of the plugins the space uses, as of that revision, by plugin type — each built and checked as a
+     * plugin's (`prepareFunctions` with its `scope`) and run in the same sandbox as the space's own, with a plugin's
+     * narrower `ctx`. Asked like `getFunctions`: for a task the deployment does not have, or a path under
+     * `/fn/plugins/<type>/`.
+     */
+    getPluginFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<Record<string, SpaceFunctions> | undefined>;
+    /**
+     * The space's own data as of that revision: its files' text by path (`products.json`), for a provider resolved on the
+     * server whose `query` is `/data/<file>` — the platform's `dataDir`. Absent, such a provider reads nothing here.
+     */
+    getData?: (spaceId: number, at?: SpaceRevision) => Promise<Record<string, string> | undefined>;
     /**
      * The feature flags the space declares as of that revision, for a flow that reads `{{ flags.<name> }}`. Only asked
      * for a run whose document names `flags` at all. Absent, such a flow sees no flags — and the server says so.
@@ -228,7 +240,8 @@ export type ActionTask<T extends Record<string, unknown> = Record<string, unknow
  * Whose task it is: the deployment's — shipped with the server, or its own native functions — or the space's, from the
  * functions it saved. The run treats both alike; an editor lists them apart, as the platform's steps and the space's own.
  */
-export type ActionTaskOrigin = 'deployment' | 'space';
+/** Whose step it is: the deployment's, the space's own functions', or the server half of a plugin the space uses. */
+export type ActionTaskOrigin = 'deployment' | 'space' | 'plugin';
 export type RegisteredTask = ActionTask<Record<string, unknown>> & {
     name: string;
     origin: ActionTaskOrigin;

package/dist/modules/functions/config.d.ts

@@ -14,6 +14,12 @@ export type FunctionUsageRecord = {
  */
 export type FunctionsConfig = {
     native?: FunctionsDefinition[];
+    /**
+     * The server halves of the plugins this server ships, by plugin type — loaded natively like `native`, but each with a
+     * plugin's narrower `ctx` (its own `kv` and limits, signatures only it verifies, none of the space's credentials or
+     * channels). Their tasks are `<type>.<action>`, their routes answer under `/fn/plugins/<type>/`.
+     */
+    plugins?: Record<string, FunctionsDefinition>;
     /**
      * Where the spaces' own functions run: `createRemoteRunner` for the runner service, a provider's adapter, or
      * `createIsolateRunner` only where this process holds nothing a space must not reach. Absent, spaces have no

package/dist/modules/functions/context.d.ts

@@ -1,4 +1,5 @@
 import { FunctionContext } from './contract';
+import { FunctionScope } from './scope';
 import { ActionTaskContext } from '../actions/types';
 /**
  * Whether `hostname` is one the space declared: exactly, or under a `*.` wildcard (`*.example.com` is every subdomain of
@@ -12,6 +13,7 @@ export declare const hostAllowed: (hostname: string, hosts: readonly string[]) =
 export declare const lineOf: (values: readonly unknown[]) => string;
 /**
  * What a space's code is handed, built from the run's own context: the one place a {@link FunctionContext} is made.
- * A self-hosted server hands it to the code directly; the platform answers the sandbox's calls with it.
+ * A self-hosted server hands it to the code directly; the platform answers the sandbox's calls with it. With a `scope`,
+ * it is a plugin's code, and gets the plugin's corner of the space (`./scope`).
  */
-export declare const functionContextFor: (ctx: ActionTaskContext, hosts: readonly string[]) => FunctionContext;
+export declare const functionContextFor: (ctx: ActionTaskContext, hosts: readonly string[], scope?: FunctionScope) => FunctionContext;