@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/functions/sandbox/isolate.js

@@ -0,0 +1,347 @@
+import { changeKv } from "../../actions/runtime/kvChange.js";
+import { FunctionFailure } from "../protocol.js";
+import { installGuest } from "./guest.js";
+import { guestPrelude } from "./prelude.js";
+import { createFunctionsDriver, describeFunctions } from "../driver.js";
+import { createHash, createHmac, pbkdf2, randomBytes } from "node:crypto";
+import { promisify } from "node:util";
+//#region src/modules/functions/sandbox/isolate.ts
+/** What reading a bundle's declaration may spend: its top level runs, and nothing else. */
+var DESCRIBE_LIMITS = {
+	cpuMs: 1e3,
+	wallMs: 5e3,
+	memoryMb: 64,
+	outputBytes: 1e6,
+	calls: 100
+};
+/**
+* What a bundle's top level can call while it is read: only the console, since `ctx` exists only in an invocation — and
+* a line logged while loading is nobody's to read.
+*/
+var describeAnswer = (call) => typeof call === "object" && call !== null && "op" in call && call.op === "log" ? Promise.resolve(void 0) : Promise.reject(/* @__PURE__ */ new Error("Nothing is reachable while a bundle is read"));
+var WATCHDOG_MS = 5;
+/** What isolated-vm throws when a `timeout` it was given runs out. */
+var ISOLATE_TIMEOUT = "Script execution timed out.";
+/** How long code that listens to `ctx.signal` gets to stop by itself before the isolate is disposed under it. */
+var ABORT_GRACE_MS = 50;
+var NO_NODE_SNAPSHOT = "--no-node-snapshot";
+/**
+* Since Node 20 the process starts from Node's own V8 snapshot, and isolated-vm's isolates crash beside it — not always,
+* which is why this refuses up front rather than letting a process run until the one invocation that brings it down.
+*/
+var nodeSnapshotOff = () => Number(process.versions.node.split(".")[0]) < 20 || process.execArgv.includes(NO_NODE_SNAPSHOT) || (process.env.NODE_OPTIONS ?? "").split(/\s+/).includes(NO_NODE_SNAPSHOT);
+var loadIvm = async () => {
+	if (!nodeSnapshotOff()) throw new Error(`Running space functions in isolates needs Node started with ${NO_NODE_SNAPSHOT} (e.g. NODE_OPTIONS=${NO_NODE_SNAPSHOT}): isolated-vm crashes beside Node's startup snapshot`);
+	try {
+		return (await import("isolated-vm")).default;
+	} catch {
+		throw new Error("Running space functions in isolates needs isolated-vm installed beside @plitzi/sdk-server");
+	}
+};
+/**
+* The code cache a compile produced. isolated-vm sets it on the compiled script or module, and its declarations leave
+* it out — so it is looked for rather than assumed.
+*/
+var cachedDataOf = (ivm, compiled) => "cachedData" in compiled && compiled.cachedData instanceof ivm.ExternalCopy ? compiled.cachedData : void 0;
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+var stopMessage = (reason, limits) => {
+	switch (reason) {
+		case "cpu": return `Stopped after ${String(limits.cpuMs)} ms of CPU`;
+		case "wall": return `Did not finish within ${String(limits.wallMs)} ms`;
+		case "memory": return `Went over its ${String(limits.memoryMb)} MB of memory`;
+		case "output": return `Answered more than the ${String(limits.outputBytes)} bytes it may`;
+		case "calls": return `Made more than the ${String(limits.calls)} calls to the platform it may`;
+		case "aborted": return "The run was aborted";
+	}
+};
+/**
+* The most a PBKDF2 derivation may ask for. The runner does the work, outside the isolate's clock, so each is bounded
+* here and its time is charged to the run's CPU: a million rounds is past any password guidance, and 1024 bits past
+* any key.
+*/
+var PBKDF2_MAX_ITERATIONS = 1e6;
+var PBKDF2_MAX_BITS = 1024;
+var derive = promisify(pbkdf2);
+var cryptoField = (request, name) => {
+	const value = request[name];
+	if (typeof value !== "string") throw new Error(`The operation has no ${name}`);
+	return value;
+};
+var boundedInteger = (text, what, max) => {
+	const value = Number(text);
+	if (!Number.isInteger(value) || value < 1 || value > max) throw new Error(`${what} is a whole number from 1 to ${String(max)}`);
+	return value;
+};
+/**
+* The `crypto.subtle` a guest cannot do by itself, done with the runner's own: digests, HMAC and PBKDF2. A derivation
+* is the one that costs, and `charge` is handed what it took.
+*/
+var cryptoAnswer = async (message, charge) => {
+	try {
+		const request = JSON.parse(message);
+		if (typeof request !== "object" || request === null || Array.isArray(request)) throw new Error("Not a crypto operation");
+		const fields = { ...request };
+		const hash = cryptoField(fields, "hash").replace("-", "").toLowerCase();
+		const bytes = (name) => Buffer.from(cryptoField(fields, name), "base64");
+		const op = cryptoField(fields, "op");
+		if (op === "pbkdf2") {
+			const iterations = boundedInteger(cryptoField(fields, "iterations"), "PBKDF2 iterations", PBKDF2_MAX_ITERATIONS);
+			const bits = boundedInteger(cryptoField(fields, "bits"), "A PBKDF2 length in bits", PBKDF2_MAX_BITS);
+			if (bits % 8 !== 0) throw new Error("A PBKDF2 length is a multiple of 8 bits");
+			const started = performance.now();
+			const derived = await derive(bytes("key"), bytes("salt"), iterations, bits / 8, hash);
+			charge(performance.now() - started);
+			return JSON.stringify({
+				ok: true,
+				value: derived.toString("base64")
+			});
+		}
+		if (op !== "hmac" && op !== "digest") throw new Error(`${op} is not a crypto operation`);
+		const digest = op === "hmac" ? createHmac(hash, bytes("key")).update(bytes("data")).digest() : createHash(hash).update(bytes("data")).digest();
+		return JSON.stringify({
+			ok: true,
+			value: digest.toString("base64")
+		});
+	} catch (error) {
+		return JSON.stringify({
+			ok: false,
+			error: messageOf(error)
+		});
+	}
+};
+/**
+* Sets the guest up in a fresh context: the runner's four calls, taken off the global the moment they are captured,
+* and the guest printed from its own source — with the platform's functions it runs as they are (`GuestShared`),
+* printed from theirs. Answers the driver.
+*/
+var BOOTSTRAP = `(() => {
+  const refs = { call: __plitziCall, sleep: __plitziSleep, random: __plitziRandom, crypto: __plitziCrypto };
+  delete globalThis.__plitziCall;
+  delete globalThis.__plitziSleep;
+  delete globalThis.__plitziRandom;
+  delete globalThis.__plitziCrypto;
+  const transfer = { arguments: { copy: true }, result: { promise: true, copy: true } };
+  return (${installGuest.toString()})(globalThis, {
+    call: message => refs.call.apply(undefined, [message], transfer),
+    sleep: ms => refs.sleep.apply(undefined, [ms], transfer),
+    random: length => refs.random(length),
+    crypto: message => refs.crypto.apply(undefined, [message], transfer)
+  }, { changeKv: ${changeKv.toString()}, describeFunctions: ${describeFunctions.toString()}, createFunctionsDriver: ${createFunctionsDriver.toString()} });
+})()`;
+/**
+* The runner as V8 isolates in this process — what the runner service serves, and what a deployment may use directly
+* when the process holds nothing a space's code must not reach (tests, a sandbox of its own).
+*
+* ONE ISOLATE PER INVOCATION: each limit is then exactly that invocation's — its CPU, its memory — and stopping it
+* disposes nothing anybody else was using. No state survives an invocation, by construction. The cost is ~2 ms: the
+* prelude comes from a V8 snapshot, the guest and the bundle from V8's code cache after their first compile.
+*/
+var createIsolateRunner = ({ concurrency = 8, cacheBytes = 67108864 } = {}) => {
+	const cache = /* @__PURE__ */ new Map();
+	let cachedBytes = 0;
+	/** Every isolate starts from a heap with the prelude already run in it: running it each time was most of the cost. */
+	let snapshot;
+	let guestCache;
+	let running = 0;
+	const waiting = [];
+	const acquire = async () => {
+		if (running >= concurrency) await new Promise((resolve) => waiting.push(resolve));
+		running++;
+	};
+	const release = () => {
+		running--;
+		waiting.shift()?.();
+	};
+	/** The bundle's entry, most recently used now: its code fetched only when this runner has never kept it. */
+	const cached = async (bundle) => {
+		const kept = cache.get(bundle.id);
+		if (kept) {
+			cache.delete(bundle.id);
+			cache.set(bundle.id, kept);
+			return kept;
+		}
+		const code = await bundle.load();
+		const entry = {
+			code,
+			bytes: Buffer.byteLength(code)
+		};
+		cache.set(bundle.id, entry);
+		cachedBytes += entry.bytes;
+		for (const [id, oldest] of cache) {
+			if (cachedBytes <= cacheBytes || id === bundle.id) break;
+			cache.delete(id);
+			cachedBytes -= oldest.bytes;
+		}
+		return entry;
+	};
+	/** What every isolate is made from, once per process: the module, the prelude, the heap it starts as. */
+	const ready = async () => {
+		const ivm = await loadIvm();
+		snapshot ??= ivm.Isolate.createSnapshot([{
+			code: await guestPrelude(),
+			filename: "plitzi:prelude"
+		}]);
+		return ivm;
+	};
+	const session = async ({ bundle, limits, answer, signal, onUsage, drive }) => {
+		const ivm = await ready();
+		const entry = await cached(bundle);
+		await acquire();
+		const isolate = new ivm.Isolate({
+			memoryLimit: limits.memoryMb,
+			snapshot
+		});
+		const timers = /* @__PURE__ */ new Set();
+		let stopped;
+		let calls = 0;
+		const startedAt = Date.now();
+		/** The CPU the isolate used, kept as it is read: a disposed isolate has none left to ask. */
+		let isolateCpuMs = 0;
+		/** What the runner spent on the run's behalf — a PBKDF2 derivation — which the isolate's clock never sees. */
+		let hostCpuMs = 0;
+		const readCpu = () => {
+			if (!isolate.isDisposed) isolateCpuMs = Number(isolate.cpuTime) / 1e6;
+			return isolateCpuMs + hostCpuMs;
+		};
+		const stop = (reason) => {
+			stopped ??= reason;
+			readCpu();
+			if (!isolate.isDisposed) isolate.dispose();
+		};
+		const later = (ms, run) => {
+			const timer = setTimeout(() => {
+				timers.delete(timer);
+				run();
+			}, ms);
+			timers.add(timer);
+		};
+		const watchdog = setInterval(() => {
+			if (!isolate.isDisposed && readCpu() > limits.cpuMs) stop("cpu");
+		}, WATCHDOG_MS);
+		later(limits.wallMs, () => stop("wall"));
+		let driver;
+		const onAbort = () => {
+			driver?.get("abort", { reference: true }).then((abort) => abort.apply(void 0, ["The run was aborted"])).catch(() => void 0);
+			later(ABORT_GRACE_MS, () => stop("aborted"));
+		};
+		try {
+			const context = isolate.createContextSync();
+			const global = context.global;
+			global.setSync("globalThis", global.derefInto());
+			global.setSync("__plitziCall", new ivm.Reference(async (message) => {
+				calls++;
+				if (calls > limits.calls) {
+					stop("calls");
+					return JSON.stringify({
+						ok: false,
+						error: stopMessage("calls", limits)
+					});
+				}
+				try {
+					const value = await answer(JSON.parse(message));
+					return JSON.stringify({
+						ok: true,
+						value: value ?? null
+					});
+				} catch (error) {
+					return JSON.stringify({
+						ok: false,
+						error: messageOf(error)
+					});
+				}
+			}));
+			global.setSync("__plitziSleep", new ivm.Reference((ms) => new Promise((resolve) => later(Math.min(Math.max(0, ms), limits.wallMs), resolve))));
+			global.setSync("__plitziRandom", new ivm.Callback((length) => [...randomBytes(Math.min(Math.max(0, length), 65536))]));
+			global.setSync("__plitziCrypto", new ivm.Reference((message) => cryptoAnswer(message, (ms) => {
+				hostCpuMs += ms;
+				if (readCpu() > limits.cpuMs) stop("cpu");
+			})));
+			const guestScript = isolate.compileScriptSync(BOOTSTRAP, {
+				filename: "plitzi:guest",
+				...guestCache ? { cachedData: guestCache } : { produceCachedData: true }
+			});
+			guestCache ??= cachedDataOf(ivm, guestScript);
+			driver = guestScript.runSync(context, { reference: true });
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
+			const module = isolate.compileModuleSync(entry.code, {
+				filename: "functions.js",
+				...entry.cachedData ? { cachedData: entry.cachedData } : { produceCachedData: true }
+			});
+			entry.cachedData ??= cachedDataOf(ivm, module);
+			module.instantiateSync(context, (specifier) => {
+				throw new Error(`"${specifier}" cannot be imported: a bundle is one module`);
+			});
+			await module.evaluate({ timeout: limits.cpuMs });
+			const definition = module.namespace.getSync("default", { reference: true });
+			if (definition.typeof !== "object") throw new FunctionFailure("error", "functions/index.ts exports its definition by default: export default defineFunctions({ … })");
+			const text = await drive(driver, definition);
+			if (Buffer.byteLength(text) > limits.outputBytes) stop("output");
+			if (stopped) throw new FunctionFailure(stopped, stopMessage(stopped, limits));
+			const outcome = JSON.parse(text);
+			if (typeof outcome !== "object" || outcome === null || !("ok" in outcome)) throw new FunctionFailure("error", "The runtime answered something that is not an outcome");
+			if (outcome.ok !== true) throw new FunctionFailure("refused" in outcome && outcome.refused === true ? "refused" : "error", "error" in outcome ? String(outcome.error) : "The function failed");
+			return "value" in outcome ? outcome.value : null;
+		} catch (error) {
+			if (error instanceof FunctionFailure && !stopped) throw error;
+			const timedOut = error instanceof Error && error.message === ISOLATE_TIMEOUT;
+			const reason = stopped ?? (timedOut ? "cpu" : isolate.isDisposed ? "memory" : void 0);
+			throw reason ? new FunctionFailure(reason, stopMessage(reason, limits)) : new FunctionFailure("error", messageOf(error));
+		} finally {
+			onUsage?.({
+				cpuMs: Math.round(readCpu()),
+				wallMs: Date.now() - startedAt,
+				calls
+			});
+			clearInterval(watchdog);
+			timers.forEach((timer) => clearTimeout(timer));
+			signal?.removeEventListener("abort", onAbort);
+			if (!isolate.isDisposed) isolate.dispose();
+			release();
+		}
+	};
+	const describe = (bundle) => session({
+		bundle: {
+			id: bundle.id,
+			load: () => Promise.resolve(bundle.code)
+		},
+		limits: DESCRIBE_LIMITS,
+		answer: describeAnswer,
+		drive: async (driver, definition) => {
+			return driver.getSync("describe", { reference: true }).apply(driver.derefInto(), [definition.derefInto()], {
+				result: { copy: true },
+				timeout: DESCRIBE_LIMITS.cpuMs
+			});
+		}
+	});
+	return {
+		describe,
+		invoke: ({ bundle, invocation, limits, answer, signal, onUsage }) => session({
+			bundle,
+			limits,
+			answer,
+			signal,
+			onUsage,
+			drive: async (driver, definition) => {
+				const invoke = driver.getSync("invoke", { reference: true });
+				const message = JSON.stringify(invocation);
+				return invoke.apply(driver.derefInto(), [definition.derefInto(), message], {
+					result: {
+						promise: true,
+						copy: true
+					},
+					timeout: limits.cpuMs
+				});
+			}
+		}),
+		warm: async () => {
+			await ready();
+			await describe({
+				id: "plitzi:warm-up",
+				code: "export default {};"
+			});
+		}
+	};
+};
+//#endregion
+export { PBKDF2_MAX_BITS, PBKDF2_MAX_ITERATIONS, createIsolateRunner };

package/dist/modules/functions/sandbox/isolate.test.d.ts

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

package/dist/modules/functions/sandbox/prelude.d.ts

@@ -0,0 +1,2 @@
+/** The prelude's source, built on first use and the same for every isolate this process makes. */
+export declare const guestPrelude: () => Promise<string>;

package/dist/modules/functions/sandbox/prelude.js

@@ -0,0 +1,49 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import esbuild from "esbuild";
+import { fileURLToPath } from "node:url";
+//#region src/modules/functions/sandbox/prelude.ts
+/**
+* The web APIs a bare V8 lacks that are the spec's to get right rather than ours: `URL`, `URLSearchParams`, `atob`,
+* `btoa`, `structuredClone`, `DOMException` — core-js's, bundled once per runner process. What is left (`Headers`,
+* `Request`, `Response`, timers, `crypto`, `ctx`) is the guest's, because each of those is a call to the runner.
+*/
+var POLYFILLS = [
+	"core-js/actual/dom-exception",
+	"core-js/actual/url",
+	"core-js/actual/url-search-params",
+	"core-js/actual/structured-clone",
+	"core-js/actual/atob",
+	"core-js/actual/btoa"
+];
+var build = async () => {
+	const require = createRequire(import.meta.url);
+	let entries;
+	try {
+		entries = POLYFILLS.map((entry) => require.resolve(entry));
+	} catch {
+		throw new Error("Running space functions in isolates needs core-js@3 installed beside @plitzi/sdk-server");
+	}
+	return (await esbuild.build({
+		stdin: {
+			contents: entries.map((entry) => `import ${JSON.stringify(entry)};`).join("\n"),
+			loader: "js",
+			resolveDir: path.dirname(fileURLToPath(import.meta.url))
+		},
+		bundle: true,
+		write: false,
+		format: "iife",
+		platform: "browser",
+		target: "es2022",
+		minify: true,
+		logLevel: "silent"
+	})).outputFiles[0]?.text ?? "";
+};
+var prelude;
+/** The prelude's source, built on first use and the same for every isolate this process makes. */
+var guestPrelude = () => {
+	prelude ??= build();
+	return prelude;
+};
+//#endregion
+export { guestPrelude };

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

@@ -0,0 +1,40 @@
+import { FunctionsSource } from './build';
+import { FunctionsConfig } from './config';
+import { FunctionsBundle, FunctionLimits, FunctionRunner, SpaceFunctions } from './protocol';
+import { ActionTask, ActionTaskRegistry } from '../actions/types';
+import { FunctionsManifest, FunctionsProblem } from '@plitzi/sdk-shared';
+/**
+ * A space's tasks as the registry holds them — each run by the runner, answering the code's calls with the run's own
+ * {@link FunctionContext}: the same one native functions get, built by the same function.
+ */
+export declare const spaceTasks: (functions: SpaceFunctions, runner: FunctionRunner, limits: FunctionLimits, { admit, onUsage }?: Pick<FunctionsConfig, "admit" | "onUsage">) => ActionTask<Record<string, unknown>>[];
+export type SpaceRegistries = {
+    /** The tasks one run of that space can use: the deployment's, and its own functions' when it has any. */
+    registryFor: (functions: SpaceFunctions | undefined) => ActionTaskRegistry;
+};
+/**
+ * Registries per space bundle, built once per bundle and limits — a space's functions change when they are saved, and
+ * a saved bundle is a new id.
+ */
+export declare const createSpaceRegistries: (base: ActionTaskRegistry, config?: FunctionsConfig) => SpaceRegistries;
+/** Functions whose code is already in hand — prepared a moment ago, or a deployment's own — as a run reaches them. */
+export declare const functionsInHand: ({ bundle, manifest }: {
+    bundle: FunctionsBundle;
+    manifest: FunctionsManifest;
+}) => SpaceFunctions;
+/** A source made ready to store: the bundle whole — storing is the one place its code travels — and what it declared. */
+export type PreparedFunctions = {
+    ok: true;
+    functions: {
+        bundle: FunctionsBundle;
+        manifest: FunctionsManifest;
+    };
+} | {
+    ok: false;
+    problems: FunctionsProblem[];
+};
+/**
+ * A space's source made ready to save: built, read by the runner, and checked — the only way a space's functions are
+ * stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use.
+ */
+export declare const prepareFunctions: (source: FunctionsSource, runner: FunctionRunner, reserved: ReadonlySet<string>) => Promise<PreparedFunctions>;

package/dist/modules/functions/space.js

@@ -0,0 +1,162 @@
+import { ActionRefusal } from "../actions/runtime/errors.js";
+import { functionContextFor } from "./context.js";
+import { taskName } from "../actions/tasks/registry.js";
+import { readManifest } from "./manifest.js";
+import { answerCall, readCall } from "./capabilities.js";
+import { functionLimitsFor } from "./config.js";
+import { FunctionFailure } from "./protocol.js";
+import { FunctionsBuildError, buildFunctions } from "./build.js";
+import { createHash } from "node:crypto";
+//#region src/modules/functions/space.ts
+var invocationContextOf = ({ spaceId, environment, runId, trigger, callerId, user }) => ({
+	spaceId,
+	environment,
+	runId,
+	trigger,
+	callerId,
+	...user ? { user } : {}
+});
+/**
+* A space's tasks as the registry holds them — each run by the runner, answering the code's calls with the run's own
+* {@link FunctionContext}: the same one native functions get, built by the same function.
+*/
+var spaceTasks = (functions, runner, limits, { admit, onUsage } = {}) => functions.manifest.tasks.map((task) => {
+	const name = taskName(task);
+	return {
+		namespace: task.namespace,
+		action: task.action,
+		title: task.title,
+		...task.description ? { description: task.description } : {},
+		params: task.params,
+		run: async (params, ctx) => {
+			const refusal = await admit?.(ctx.spaceId);
+			if (refusal) throw new Error(refusal);
+			const fnCtx = functionContextFor(ctx, functions.manifest.hosts);
+			let ok = false;
+			let spent;
+			try {
+				const value = await runner.invoke({
+					bundle: functions.bundle,
+					invocation: {
+						kind: "task",
+						name,
+						params,
+						context: invocationContextOf(fnCtx)
+					},
+					limits,
+					answer: (call) => answerCall(fnCtx, readCall(call)),
+					signal: ctx.signal,
+					onUsage: (usage) => {
+						spent = usage;
+					}
+				});
+				ok = true;
+				return value;
+			} catch (error) {
+				if (error instanceof FunctionFailure && error.reason === "refused") throw new ActionRefusal(error.message);
+				throw error;
+			} finally {
+				if (spent) onUsage?.({
+					spaceId: ctx.spaceId,
+					task: name,
+					ok,
+					usage: spent
+				});
+			}
+		}
+	};
+});
+/** The deployment's tasks and a space's, one registry: a space's never answers a name the deployment's already does. */
+var composeRegistry = (base, tasks) => {
+	const own = /* @__PURE__ */ new Map();
+	tasks.forEach((task) => {
+		const name = taskName(task);
+		if (!base.get(name)) own.set(name, {
+			...task,
+			name
+		});
+	});
+	return {
+		get: (name) => base.get(name) ?? own.get(name),
+		list: () => [...base.list(), ...own.values()]
+	};
+};
+var REGISTRY_CACHE = 500;
+/**
+* Registries per space bundle, built once per bundle and limits — a space's functions change when they are saved, and
+* a saved bundle is a new id.
+*/
+var createSpaceRegistries = (base, config = {}) => {
+	const cache = /* @__PURE__ */ new Map();
+	return { registryFor: (functions) => {
+		const runner = functions?.runner ?? config.runner;
+		if (!functions || !runner) return base;
+		const limits = functionLimitsFor(config.limits, functions.limits);
+		const key = `${functions.bundle.id}:${JSON.stringify(limits)}`;
+		const found = cache.get(key);
+		if (found) return found;
+		const registry = composeRegistry(base, spaceTasks(functions, runner, limits, config));
+		cache.set(key, registry);
+		if (cache.size > REGISTRY_CACHE) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== void 0) cache.delete(oldest);
+		}
+		return registry;
+	} };
+};
+/** Functions whose code is already in hand — prepared a moment ago, or a deployment's own — as a run reaches them. */
+var functionsInHand = ({ bundle, manifest }) => ({
+	bundle: {
+		id: bundle.id,
+		load: () => Promise.resolve(bundle.code)
+	},
+	manifest
+});
+/**
+* A space's source made ready to save: built, read by the runner, and checked — the only way a space's functions are
+* stored, so what is stored always passed every rule. `reserved` is every namespace the deployment's own tasks use.
+*/
+var prepareFunctions = async (source, runner, reserved) => {
+	let code;
+	try {
+		({code} = await buildFunctions(source));
+	} catch (error) {
+		if (error instanceof FunctionsBuildError) return {
+			ok: false,
+			problems: error.problems
+		};
+		throw error;
+	}
+	const bundle = {
+		id: createHash("sha256").update(code).digest("hex"),
+		code
+	};
+	let declared;
+	try {
+		declared = await runner.describe(bundle);
+	} catch (error) {
+		return {
+			ok: false,
+			problems: [{
+				file: "index.ts",
+				message: error instanceof Error ? error.message : String(error)
+			}]
+		};
+	}
+	const { manifest, problems } = readManifest(declared, reserved);
+	return problems.length ? {
+		ok: false,
+		problems: problems.map((message) => ({
+			file: "index.ts",
+			message
+		}))
+	} : {
+		ok: true,
+		functions: {
+			bundle,
+			manifest
+		}
+	};
+};
+//#endregion
+export { createSpaceRegistries, functionsInHand, prepareFunctions, spaceTasks };

package/dist/modules/functions/testing/tasksOf.d.ts

@@ -0,0 +1,4 @@
+import { FunctionsConfig } from '../config';
+import { FunctionTask } from '../contract';
+/** A server's native functions made of just these tasks — what a test registers the tasks it runs with. */
+export declare const tasksOf: (...tasks: FunctionTask<never>[]) => FunctionsConfig;

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

@@ -0,0 +1,9 @@
+import { ActionEntry } from '@plitzi/sdk-shared';
+/** The id of the step that runs the task in a {@link functionTryEntry}: where its value, logs and error are found. */
+export declare const TRY_STEP = "task";
+/**
+ * One task as the smallest flow that runs it: a session call, the task, and its answer — so trying a function is an
+ * ordinary run, with every check, limit and record a run has, and nothing of its own to keep in step. The builder's
+ * Try, an agent's and `plitzi functions dev` are all this.
+ */
+export declare const functionTryEntry: (task: string, params: Record<string, unknown>) => ActionEntry;

package/dist/modules/functions/tryEntry.js

@@ -0,0 +1,49 @@
+//#region src/modules/functions/tryEntry.ts
+var step = (id, fields) => ({
+	id,
+	title: id,
+	type: "task",
+	action: "",
+	params: {},
+	preview: {},
+	elementId: null,
+	beforeNode: "",
+	afterNode: "",
+	flowId: "try",
+	enabled: true,
+	...fields
+});
+/** The id of the step that runs the task in a {@link functionTryEntry}: where its value, logs and error are found. */
+var TRY_STEP = "task";
+/**
+* One task as the smallest flow that runs it: a session call, the task, and its answer — so trying a function is an
+* ordinary run, with every check, limit and record a run has, and nothing of its own to keep in step. The builder's
+* Try, an agent's and `plitzi functions dev` are all this.
+*/
+var functionTryEntry = (task, params) => ({
+	id: `try:${task}`,
+	document: {
+		name: `Try ${task}`,
+		output: { value: { type: "json" } },
+		nodes: {
+			start: step("start", {
+				type: "trigger",
+				action: "call",
+				params: { access: "session" },
+				afterNode: TRY_STEP
+			}),
+			[TRY_STEP]: step(TRY_STEP, {
+				title: task,
+				action: task,
+				params,
+				afterNode: "answer"
+			}),
+			answer: step("answer", {
+				action: "flow.output",
+				params: { values: `{"value": {{ ${TRY_STEP}|json_encode }}}` }
+			})
+		}
+	}
+});
+//#endregion
+export { TRY_STEP, functionTryEntry };