@plitzi/sdk-server 0.37.1 → 0.37.3

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

@@ -1,9 +1,20 @@
 import { builtinTasks } from "./builtins.js";
 import { dbTasks } from "./db.js";
+import { nativeTasks } from "../../functions/native.js";
 //#region src/modules/actions/tasks/registry.ts
 var NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
 var taskName = (task) => `${task.namespace}.${task.action}`;
-var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
+/** The namespaces the platform's own tasks use: nobody else's task may take one. */
+var RESERVED_NAMESPACES = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
+/**
+* What is wrong with a task's name, or nothing — one rule for a deployment's tasks at boot and a space's own when its
+* functions are built. A malformed name is unreachable from any document; one in a namespace taken by another task
+* set silently changes what every action using that set does.
+*/
+var taskNameProblem = (task, reserved = RESERVED_NAMESPACES) => {
+	if (!NAME_PATTERN.test(task.namespace) || !NAME_PATTERN.test(task.action)) return `Invalid task name "${taskName(task)}": expected camelCase namespace and action`;
+	if (reserved.has(task.namespace)) return `Namespace "${task.namespace}" is reserved by another task set`;
+};
 /**
 * Builds the set of tasks this server can run.
 *
@@ -11,15 +22,15 @@ var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => tas
 * 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 = (custom = [], { db = false } = {}) => {
+var createTaskRegistry = (functions = [], { db = false } = {}) => {
 	const tasks = /* @__PURE__ */ new Map();
 	(db ? [...builtinTasks, ...dbTasks] : builtinTasks).forEach((task) => tasks.set(taskName(task), {
 		...task,
 		name: taskName(task)
 	}));
-	custom.forEach((task) => {
-		if (!NAME_PATTERN.test(task.namespace) || !NAME_PATTERN.test(task.action)) throw new Error(`[Actions] Invalid task name "${taskName(task)}": expected camelCase namespace and action`);
-		if (reservedNamespaces.has(task.namespace)) throw new Error(`[Actions] Namespace "${task.namespace}" is reserved by a built-in task set`);
+	nativeTasks(functions).forEach((task) => {
+		const problem = taskNameProblem(task);
+		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, {
@@ -33,4 +44,4 @@ var createTaskRegistry = (custom = [], { db = false } = {}) => {
 	};
 };
 //#endregion
-export { createTaskRegistry, taskName };
+export { RESERVED_NAMESPACES, createTaskRegistry, taskName, taskNameProblem };

package/dist/modules/actions/transport/callHandler.js

@@ -1,5 +1,6 @@
-import { ActionRunError } from "../runtime/errors.js";
+import { serverLog } from "../../../helpers/serverLog.js";
 import { triggerParams } from "../runtime/triggers.js";
+import { ActionRunError } from "../runtime/errors.js";
 import { precheckRun } from "../runtime/precheck.js";
 import onAbort from "../../../helpers/onAbort.js";
 import { openStream, wantsStream } from "./stream.js";
@@ -215,6 +216,7 @@ var handleActionCall = async (deps) => {
 					runId: result.runId,
 					status: result.status,
 					output: result.output,
+					...result.error === void 0 ? {} : { error: result.error },
 					...outline ? { steps: result.steps } : {}
 				}
 			});
@@ -224,7 +226,8 @@ var handleActionCall = async (deps) => {
 		const payload = {
 			runId: result.runId,
 			status: result.status,
-			output: result.output
+			output: result.output,
+			...result.error === void 0 ? {} : { error: result.error }
 		};
 		if (outline) payload.steps = result.steps;
 		if (fullTrace) payload.trace = result.trace;
@@ -232,7 +235,7 @@ var handleActionCall = async (deps) => {
 	} catch (error) {
 		const reason = error instanceof ActionRunError ? error.reason : "failed";
 		const message = error instanceof ActionRunError ? error.message : "Action failed";
-		if (!(error instanceof ActionRunError)) console.error("[Actions] run failed:", error);
+		if (!(error instanceof ActionRunError)) serverLog.error("Actions", "run failed", error);
 		const steps = error instanceof ActionRunError && error.steps && await showsOutline() ? error.steps : void 0;
 		if (stream) {
 			stream.send({

package/dist/modules/actions/transport/catalogHandler.d.ts

@@ -1,8 +1,11 @@
 import { ActionsModule } from '../index';
-import { SSRResponseHelpers } from '@plitzi/sdk-shared';
+import { SpaceRevision, SSRResponseHelpers } from '@plitzi/sdk-shared';
 export type ActionCatalogDeps = {
     res: SSRResponseHelpers;
     module: ActionsModule;
+    /** The space asking, as of the revision it is serving: its own functions are part of what it can run. */
+    spaceId?: number;
+    at?: SpaceRevision;
 };
 /**
  * Serves the tasks this server can run.
@@ -15,4 +18,4 @@ export type ActionCatalogDeps = {
  * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
  * to hand an anonymous visitor.
  */
-export declare const handleActionCatalog: ({ res, module }: ActionCatalogDeps) => void;
+export declare const handleActionCatalog: ({ res, module, spaceId, at }: ActionCatalogDeps) => Promise<void>;

package/dist/modules/actions/transport/catalogHandler.js

@@ -11,11 +11,12 @@ import { describeCatalog } from "../taskCatalog.js";
 * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
 * to hand an anonymous visitor.
 */
-var handleActionCatalog = ({ res, module }) => {
+var handleActionCatalog = async ({ res, module, spaceId, at }) => {
+	const registry = spaceId === void 0 ? module.registry : await module.registryFor(spaceId, at);
 	res.setStatus(200);
 	res.setHeader("Content-Type", "application/json; charset=utf-8");
 	res.setHeader("Cache-Control", "no-store");
-	res.send(JSON.stringify({ tasks: describeCatalog(module.registry) }));
+	res.send(JSON.stringify({ tasks: describeCatalog(registry) }));
 };
 //#endregion
 export { handleActionCatalog };

package/dist/modules/actions/transport/stream.d.ts

@@ -10,12 +10,11 @@ export type ActionStream = {
     isOpen: () => boolean;
 };
 /**
- * Opens a Server-Sent Events response.
+ * Opens a run's Server-Sent Events response.
  *
- * Written straight to the RAW response, never through the response helpers: those compress the body, set a
- * Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
- * thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
- * until its buffer fills and turns a live stream into one late burst.
+ * The run's id travels on the response head rather than in a frame: a streaming step returns as soon as the stream
+ * OPENS — that is what makes it a stream — so anything it learns from a frame arrives after the flow has already
+ * carried on. The head is the one place a caller can read the id in time to cancel the run it just started.
  */
 export declare const openStream: (raw: RawResponse, onAbort: () => void, runId: string) => ActionStream;
 /** Whether this caller asked for a stream. The negotiation is the client's, so a page that cannot read one never

package/dist/modules/actions/transport/stream.js

@@ -1,7 +1,5 @@
+import { openEventStream } from "../../../core/http/sse.js";
 //#region src/modules/actions/transport/stream.ts
-/** How often a comment frame goes out. Short enough that a dead peer is noticed in seconds, long enough that an
-*  idle stream costs nothing worth counting. */
-var HEARTBEAT_MS = 15e3;
 /**
 * How long a hand-rolled `EventSource` waits before reconnecting, if one ever gets here.
 *
@@ -11,84 +9,22 @@ var HEARTBEAT_MS = 15e3;
 */
 var RETRY_MS = 864e5;
 /**
-* How much unread body may pile up before the run is stopped.
+* Opens a run's Server-Sent Events response.
 *
-* A `write` that answers `false` has been buffered rather than sent, which is normal for a moment and a leak
-* forever: a peer that stopped reading — a phone that slept, a proxy that wedged — otherwise has the whole run's
-* output accumulated for it in memory. The socket says nothing, so the only signal is this one.
-*/
-var MAX_BUFFERED_BYTES = 1e6;
-var encode = (frame) => `event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`;
-/** What the host has written but not yet handed to the socket. Node's own response reports it; the minimum raw
-*  response this server accepts does not have to, and a host that cannot say simply never trips the cap. */
-var bufferedBytes = (raw) => {
-	const { writableLength } = raw;
-	return typeof writableLength === "number" ? writableLength : 0;
-};
-/**
-* Opens a Server-Sent Events response.
-*
-* Written straight to the RAW response, never through the response helpers: those compress the body, set a
-* Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
-* thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
-* until its buffer fills and turns a live stream into one late burst.
+* The run's id travels on the response head rather than in a frame: a streaming step returns as soon as the stream
+* OPENS — that is what makes it a stream — so anything it learns from a frame arrives after the flow has already
+* carried on. The head is the one place a caller can read the id in time to cancel the run it just started.
 */
 var openStream = (raw, onAbort, runId) => {
-	let open = true;
-	raw.writeHead(200, {
-		"Content-Type": "text/event-stream; charset=utf-8",
-		"Cache-Control": "no-cache, no-transform",
-		Connection: "keep-alive",
-		"X-Accel-Buffering": "no",
-		/**
-		* The run's id, on the response head rather than in a frame.
-		*
-		* A streaming step returns as soon as the stream OPENS — that is what makes it a stream — so anything it
-		* learns from a frame arrives after the flow has already carried on. The head is the one place a caller can
-		* read the id in time to cancel the run it just started.
-		*/
-		"X-Plitzi-Run-Id": runId
+	const stream = openEventStream(raw, {
+		onAbort,
+		headers: { "X-Plitzi-Run-Id": runId },
+		retryMs: RETRY_MS
 	});
-	raw.write(`retry: ${RETRY_MS}\n\n`);
-	const heartbeat = setInterval(() => {
-		if (!open) return;
-		try {
-			raw.write(": ping\n\n");
-		} catch {
-			open = false;
-			clearInterval(heartbeat);
-			onAbort();
-		}
-	}, HEARTBEAT_MS);
-	const close = () => {
-		if (!open) return;
-		open = false;
-		clearInterval(heartbeat);
-		try {
-			raw.end();
-		} catch {}
-	};
 	return {
-		send: (frame) => {
-			if (!open) return;
-			try {
-				raw.write(encode(frame));
-				if (bufferedBytes(raw) > MAX_BUFFERED_BYTES) {
-					open = false;
-					clearInterval(heartbeat);
-					onAbort();
-					try {
-						raw.end();
-					} catch {}
-				}
-			} catch {
-				open = false;
-				clearInterval(heartbeat);
-				onAbort();
-			}
-		},
-		close,
-		isOpen: () => open
+		send: (frame) => stream.send(frame.event, frame.data),
+		close: stream.close,
+		isOpen: stream.isOpen
 	};
 };
 /** Whether this caller asked for a stream. The negotiation is the client's, so a page that cannot read one never

package/dist/modules/actions/transport/webhookHandler.js

@@ -1,5 +1,6 @@
-import { ActionRunError } from "../runtime/errors.js";
+import { serverLog } from "../../../helpers/serverLog.js";
 import { findTriggerNode, triggerParams } from "../runtime/triggers.js";
+import { ActionRunError } from "../runtime/errors.js";
 import { precheckRun } from "../runtime/precheck.js";
 import onAbort from "../../../helpers/onAbort.js";
 import { reportReject } from "../runtime/report.js";
@@ -75,7 +76,7 @@ var handleActionWebhook = async (deps) => {
 	* one without a single line of it changing. Fail closed, and say which document to fix.
 	*/
 	if (triggerHasStaleVerify(stepParams)) {
-		console.error(`[Actions] webhook "${actionId}" in space ${spaceId} carries a signature check in a format nothing reads any more, so it is refused. Name the signing credential on the trigger step.`);
+		serverLog.error("Actions", `webhook "${actionId}" in space ${spaceId} carries a signature check in a format nothing reads any more, so it is refused. Name the signing credential on the trigger step.`);
 		await reject("unverifiable", "The signature check is in a format nothing reads any more; name the signing credential on the trigger step");
 		send(res, 503, { error: "Unavailable" });
 		return;
@@ -99,7 +100,7 @@ var handleActionWebhook = async (deps) => {
 		const secret = await resolveSecret(verify, spaceId, config.action?.lookups?.getCredential);
 		const check = verifySignature(verify, secret, req.headers, rawBody);
 		if (!check.ok) {
-			console.warn(`[Actions] webhook "${actionId}" rejected: ${check.reason}`);
+			serverLog.warn("Actions", `webhook "${actionId}" rejected: ${check.reason}`);
 			await reject("invalid_signature", check.reason);
 			send(res, 401, { error: "Invalid signature" });
 			return;
@@ -182,7 +183,7 @@ var handleActionWebhook = async (deps) => {
 			status: result.status
 		});
 	} catch (error) {
-		console.error("[Actions] webhook run failed:", error);
+		serverLog.error("Actions", "webhook run failed", error);
 		send(res, 500, { accepted: false });
 	} finally {
 		releaseAbort();

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

@@ -1,5 +1,10 @@
 import { ActionEmailSender } from './runtime/email';
-import { ActionEmailConfig, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionRunStep, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
+import { FunctionsConfig } from '../functions/config';
+import { SpaceFunctions } from '../functions/protocol';
+import { KvChangeLifetime } from './runtime/kvChange';
+import { KvListEntry, KvListPut, KvListPutOptions, KvListRange } from './runtime/kvList';
+import { SpaceSigning } from './runtime/signing';
+import { ActionEmailConfig, ActionJobQueue, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionRunStep, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
 /** Resolved secret material, as the connector engine already models it. */
 export type ActionCredential = Record<string, string>;
 /**
@@ -31,7 +36,7 @@ export type ActionDbDriver = {
 /**
  * Where a deployment keeps the `kv` tasks' data — Redis, Memcached, a table, whatever it already runs.
  *
- * Deliberately the DUMBEST possible surface: five operations over strings, with no rule to obey. Everything that
+ * Deliberately the DUMBEST possible surface: six operations over strings, with no rule to obey. Everything that
  * decides how a counter behaves — the key prefixing, the JSON round trip, and the one rule a rate limit lives or
  * dies by — is `createKvStore`'s, above this. An adapter that had to remember "extend the TTL only when the
  * counter did not exist" would be an adapter each deployment gets to write that rule wrongly in.
@@ -48,6 +53,12 @@ export type ActionKvAdapter = {
     increment: (key: string, amount: number) => Promise<number>;
     /** Sets a lifetime on a key that already exists. When to call it is decided above, never here. */
     expire: (key: string, ttlSeconds: number) => Promise<void>;
+    /**
+     * Writes `next` only if the key still holds `expected` — or, with `expected` undefined, only if it holds nothing (a
+     * key past its lifetime holds nothing). Answers whether it wrote. Must be atomic: it is what lets two writers
+     * read, change and write the same value without one of them silently undoing the other.
+     */
+    swap: (key: string, expected: string | undefined, next: string, ttlSeconds?: number) => Promise<boolean>;
 };
 /**
  * The `kv` tasks' own view: values rather than strings, and a TTL that means what a caller expects.
@@ -60,6 +71,27 @@ export type ActionKvStore = {
     set: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
     delete: (key: string) => Promise<void>;
     increment: (key: string, amount: number, ttlSeconds?: number) => Promise<number>;
+    /**
+     * Writes `next` only if the key still holds `expected` — the value `get` answered — or, with `expected` undefined,
+     * only if it holds nothing. Answers whether it wrote: read, change, and write back with this, and a writer that
+     * lost the race is told so instead of undoing the other.
+     */
+    swap: (key: string, expected: unknown, next: unknown, ttlSeconds?: number) => Promise<boolean>;
+    /**
+     * Puts `entry` in the list — replacing the one with its id — keeping the highest `keep` by score, and answers what
+     * that dropped, for whatever it named to be let go of too. A list has no lifetime: it lives until its entries are
+     * removed.
+     */
+    listPut: (list: string, entry: KvListEntry, options?: KvListPutOptions) => Promise<KvListPut>;
+    listRange: (list: string, range?: KvListRange) => Promise<KvListEntry[]>;
+    /** Takes the entry with `id` out of the list, and answers whether it was there. */
+    listRemove: (list: string, id: string) => Promise<boolean>;
+    /**
+     * Reads the key, hands its value to `change` and writes back what that answers — reading and asking again when
+     * somebody wrote in between, so no writer undoes another. `change` answering `undefined` writes nothing. Answers what
+     * was written. `lifetime` is seconds, or worked out from the value written.
+     */
+    change: <T>(key: string, change: (current: unknown) => T | undefined | Promise<T | undefined>, lifetime?: KvChangeLifetime<T>) => Promise<T | undefined>;
 };
 /** Re-exported so the module's files import one place. One type for actions and connectors: it is one concept. */
 export type { SpaceRevision } from '@plitzi/sdk-shared';
@@ -71,8 +103,23 @@ export type ActionLookups = {
     getAction: (spaceId: number, actionId: string, at?: SpaceRevision) => Promise<ActionEntry | undefined>;
     /** Only the builder's catalog, the MCP and the scheduler need the list; a page call never asks for it. */
     listActions?: (spaceId: number, at?: SpaceRevision) => Promise<ActionEntry[]>;
+    /**
+     * Which spaces have something scheduled, for the periodic reconcile.
+     *
+     * Optional, and a safety net rather than the mechanism: a deployment keeps the schedule rows current by calling
+     * `reconcile` whenever a space's actions change, and this is what catches the write that did not happen — a
+     * restore from backup, a row edited by hand, a deploy that missed a save. Absent, nothing reconciles on a timer
+     * and the rows are exactly as correct as the calls that wrote them.
+     */
+    listScheduledSpaces?: () => Promise<number[]>;
     getCredential?: (spaceId: number, identifier: string) => Promise<ActionCredential | undefined>;
     getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<ConnectorManifest | undefined>;
+    /**
+     * 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/`.
+     */
+    getFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<SpaceFunctions | undefined>;
 };
 /**
  * The only door a task has to the outside world.
@@ -114,6 +161,41 @@ export type ActionTaskContext = {
     email: ActionEmailSender;
     /** Pushes a `data` frame to a streaming caller. A no-op when nobody negotiated a stream. */
     emit: (chunk: unknown) => void;
+    /**
+     * A line for whoever reads the run: kept on the step that said it (`logs`), redacted like the rest of it, and shown
+     * wherever the run is — the builder's Try, the run history.
+     */
+    log: (line: string) => void;
+    /**
+     * Publishes on one of this space's realtime channels, as the server — `undefined` when the server has none. What
+     * the `realtime.publish` task sends through.
+     */
+    publish?: (topic: string, type: string, data: unknown) => Promise<void>;
+    /**
+     * A grant for one topic of a `grant: true` channel of this space — what `realtime.grant` hands the page, once the
+     * flow has decided the visitor may be there. `undefined` when the server has no realtime channels.
+     */
+    grant?: (topic: string, ttlSeconds?: number) => Promise<string>;
+    /** Revokes `grant` for `topic` — or every grant for it, naming none — and lets go whoever is on it with one. */
+    revoke?: (topic: string, grant?: string) => Promise<void>;
+    /** Signs with the space's own key (`ActionsConfig.signingSecret`) — `undefined` when the deployment gave none. */
+    sign?: SpaceSigning['sign'];
+    verify?: SpaceSigning['verify'];
+};
+/** How the actions module reaches the server's realtime channels. Set by `createServer`, never by a deployment. */
+export type ActionRealtime = {
+    publish: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, type: string, data: unknown) => Promise<void>;
+    grant: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, ttlSeconds?: number) => Promise<string>;
+    revoke: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, grant?: string) => Promise<void>;
 };
 /**
  * One step a server action can take.
@@ -147,8 +229,8 @@ export type ActionTaskRegistry = {
 /** What a deployment hands to `createServer` under `actions`. Absent → the module is never constructed. */
 export type ActionsConfig = {
     lookups: ActionLookups;
-    /** Deployment-owned tasks, validated at boot against the built-ins. */
-    tasks?: ActionTask<never>[];
+    /** Code of the server's own, and the sandbox for the spaces' — see `FunctionsConfig`. */
+    functions?: FunctionsConfig;
     /** Ceilings a per-action document may tighten but never exceed. */
     limits?: ActionLimits;
     /** How many runs may be in flight at once. Counted per space and for the process as a whole. */
@@ -159,6 +241,15 @@ export type ActionsConfig = {
     };
     /** Where the `kv` tasks keep things. Omitted → an in-process Map, which is per-replica by definition. */
     kv?: ActionKvAdapter;
+    /**
+     * Scheduled runs, and the durable queue they go through. See {@link ActionJobsConfig}.
+     *
+     * On by default wherever `lookups.listActions` is answerable, because a deployment that can list its actions can
+     * schedule them and the old behaviour — a `schedule` trigger that silently did nothing unless the deployment
+     * built a timer and a lock of its own — was a trigger the editor offered and the server did not honour. `false`
+     * turns it off for a replica that must only serve pages.
+     */
+    jobs?: ActionJobsConfig | false;
     /** Inbound webhooks are public, so they are counted per caller per minute. Default 60. */
     rateLimit?: {
         webhookPerMinute?: number;
@@ -199,6 +290,71 @@ export type ActionsConfig = {
         replayTtlMs?: number;
     };
     fetchImpl?: typeof fetch;
+    /** The server's realtime channels, for the `realtime.publish` task. Set by `createServer`. */
+    realtime?: ActionRealtime;
+    /**
+     * What each space's signatures are made from (`ctx.sign` / `ctx.verify` in its functions): at least 32 characters,
+     * the SAME on every replica — a key one signed is checked by whichever the next request reaches. Each space and
+     * environment signs with a key derived from it, so none can vouch for another. Absent, spaces sign nothing.
+     */
+    signingSecret?: string;
+};
+/**
+ * Scheduled runs: how they are produced, how many run at once, and where they are kept while they wait.
+ *
+ * Supplying nothing still schedules — over an in-process queue, which is correct for one replica and silently
+ * wrong for two, since each gets its own copy of every schedule. A deployment with more than one supplies a
+ * {@link ActionJobQueue} over a store they share.
+ */
+export type ActionJobsConfig = {
+    /**
+     * Where jobs and schedules live. Omitted → this process's memory: nothing survives a restart, and a second
+     * replica produces the same fires all over again.
+     */
+    queue?: ActionJobQueue;
+    /**
+     * How many jobs this replica runs at once. Default 4; `0` makes it a producer that never consumes.
+     *
+     * The number that decides whether a backlog drains in minutes or hours, and it belongs to the deployment because
+     * only it knows what its flows do — a queue of five hundred HTTP calls wants a far higher number than a queue of
+     * five hundred renders. It never widens the run guards: `concurrency.perSpace` still caps one space's runs per
+     * replica, and jobs over that ceiling go back to the queue rather than failing.
+     */
+    workers?: number;
+    /** Whether this replica sweeps schedules into the queue at all. Default true. */
+    produce?: boolean;
+    /**
+     * The spaces this server schedules for, when it serves a known few.
+     *
+     * The self-hosted shape: one space, named once. A multi-tenant deployment answers the same question with
+     * {@link ActionLookups.listScheduledSpaces} instead, which wins when both are given. With neither, nothing tells
+     * the scheduler where to look and it says so at boot rather than sitting silent — a schedule that never fires is
+     * indistinguishable from a cron expression that is wrong.
+     */
+    spaces?: number[];
+    /** How often a free worker looks for a job. Default 1s. */
+    pollMs?: number;
+    /** How often this replica looks for due schedules. Default 15s. */
+    schedulePollMs?: number;
+    /**
+     * How long a claim is held before another replica may take the job over — the failover window. Default 30s,
+     * renewed every third of it while a job runs.
+     */
+    leaseMs?: number;
+    /** Attempts a scheduled job gets before it is left for an operator as `dead`. Default 3. */
+    maxAttempts?: number;
+    /** First retry delay, doubling per attempt, up to `maxMs`. Defaults to 30s and 15 minutes. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Which environment scheduled runs execute in. Default `main`. */
+    environment?: Environment;
+    /** How often schedules are re-derived from documents, where `listScheduledSpaces` allows it. Default 15 min. */
+    reconcileMs?: number;
+    /** Names this replica in the job history. Defaults to the pid and a random suffix. */
+    workerId?: string;
+    onError?: (error: unknown) => void;
 };
 /** Re-exported so the module's own files import one place, and a deployment writing an `onRun` or an `onReject`
  *  sees the same shapes the module emits. */
@@ -241,4 +397,6 @@ export type ActionRunResult = {
      * anybody allowed to debug the page. The trace above is for authoring and development servers alone.
      */
     steps: ActionRunStep[];
+    /** Why the run failed, when a step said so for the caller (`ActionRefusal`). Absent for every other failure. */
+    error?: string;
 };

package/dist/modules/connectors/engine.js

@@ -1,4 +1,4 @@
-import { assertOutboundAllowed } from "../../helpers/outboundGuard.js";
+import { fetchOutbound } from "../../helpers/outboundGuard.js";
 import { getByPath } from "./getByPath.js";
 import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
@@ -150,7 +150,6 @@ var fetchConnectorRecords = async ({ manifest, endpoint = DEFAULT_READ_ENDPOINT,
 		...renderEntries(read.query ?? {}, variables),
 		...renderFilters(resolved, connection.operators, variables)
 	}).forEach(([key, value]) => url.searchParams.set(key, value));
-	await assertOutboundAllowed(url);
 	const method = read.method ?? "GET";
 	const headers = {
 		...applyAuth(connection, variables, url),
@@ -158,7 +157,7 @@ var fetchConnectorRecords = async ({ manifest, endpoint = DEFAULT_READ_ENDPOINT,
 	};
 	const sendsBody = !BODYLESS_METHODS.includes(method);
 	if (sendsBody) headers["Content-Type"] = "application/json";
-	const response = await fetchImpl(url.toString(), {
+	const response = await fetchOutbound(fetchImpl, url, {
 		method,
 		headers,
 		body: sendsBody ? JSON.stringify(renderEntries(read.body ?? {}, variables)) : void 0
@@ -202,13 +201,12 @@ var writeConnectorRecord = async ({ manifest, credential = {}, action, resource,
 	};
 	const url = new URL(render(operation.path, variables), connection.baseUrl);
 	Object.entries(renderEntries(operation.query ?? {}, variables)).forEach(([key, value]) => url.searchParams.set(key, value));
-	await assertOutboundAllowed(url);
 	const headers = {
 		...applyAuth(connection, variables, url),
 		...renderEntries(operation.headers ?? {}, variables)
 	};
 	headers["Content-Type"] = "application/json";
-	const response = await fetchImpl(url.toString(), {
+	const response = await fetchOutbound(fetchImpl, url, {
 		method: operation.method,
 		headers,
 		body: BODYLESS_METHODS.includes(operation.method) ? void 0 : JSON.stringify(wrapBody(values, operation.bodyPath))

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

@@ -0,0 +1,22 @@
+import { FunctionsProblem } from '@plitzi/sdk-shared';
+/** A space's functions source: its files under `functions/`, by path (`index.ts`, `lib/feed.ts`). */
+export type FunctionsSource = Record<string, string>;
+/** One bundle, built from a source: a single web-standard ES module whose default export is the definition. */
+export type FunctionsBuild = {
+    code: string;
+    bytes: number;
+};
+export declare class FunctionsBuildError extends Error {
+    readonly problems: FunctionsProblem[];
+    constructor(problems: FunctionsProblem[]);
+}
+/** The file a space's functions start from. */
+export declare const FUNCTIONS_ENTRY = "index.ts";
+/** The most a bundle may weigh: well under the smallest provider a runner may be (Workers take 3 MB compressed). */
+export declare const MAX_FUNCTIONS_BYTES = 1000000;
+/**
+ * Builds a space's functions into one bundle — the only way code reaches a runner, so what runs is always what the
+ * source says. Web-standard and self-contained: the space's own files, and the contract; a Node built-in or any other
+ * package is refused with where it was imported, because no runner could provide it.
+ */
+export declare const buildFunctions: (source: FunctionsSource) => Promise<FunctionsBuild>;