@plitzi/sdk-server 0.33.2 → 0.34.0

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

@@ -0,0 +1,246 @@
+import { ActionRunError } from "./errors.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/modules/actions/runtime/guards.ts
+var DEFAULTS = {
+	perSpace: 10,
+	perProcess: 100,
+	renderPerProcess: 1e3
+};
+/**
+* How long a cancellation waits to be read, when the replica that owns the run is not the one that took the
+* request.
+*
+* Longer than any run's own timeout would be pointless — the run it addresses is gone — and shorter risks a flag
+* expiring before a slow step finishes. A streaming run's ceiling is two minutes, so this covers it with room.
+*/
+var CANCEL_FLAG_TTL_SECONDS = 180;
+/** Kept away from the `kv` tasks' own prefix: a flow writing `run:…` must not be able to release a run. */
+var keyPrefix = "action:run:";
+/**
+* Where a cancellation is left for whichever replica is actually running the flow.
+*
+* Exported because the RUNNER is what reads it, at every step boundary, and the two must not each spell the key
+* their own way — a cancel written under one name and read under another is a stop button that does nothing.
+*/
+var runCancelKey = (runId) => `${keyPrefix}cancel:${runId}`;
+/** Who started a run, so a cancel arriving at another replica can still check ownership. */
+var runOwnerKey = (runId) => `${keyPrefix}owner:${runId}`;
+/** The answer a finished run left behind, for a caller that asks again with the same key. */
+var runResultKey = (runKey) => `${keyPrefix}done:${runKey}`;
+/** Stable regardless of key order, so the same call from the same caller derives the same key every time. */
+var canonical = (value) => {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+	if (value === void 0) return "null";
+	return JSON.stringify(value);
+};
+var deriveRunKey = ({ spaceId, actionId, callerId, input, idempotencyKey, sharedKey }) => {
+	if (idempotencyKey) return sharedKey ? `${spaceId}:${actionId}:${idempotencyKey}` : `${spaceId}:${actionId}:${callerId}:${idempotencyKey}`;
+	return `${spaceId}:${actionId}:${createHash("sha256").update(canonical({
+		callerId,
+		input
+	})).digest("hex").slice(0, 32)}`;
+};
+/**
+* Single-flight, concurrency caps and cancellation, in one place.
+*
+* The client engine already refuses re-entry — `InteractionsManager` drops a trigger that fires while its own flow
+* is still running — and this is the same rule keyed by what identifies a RUN rather than a DOM event. Without it
+* a client that retries, reconnects or simply double-clicks turns one intent into many runs, and a streaming
+* caller can turn it into an unbounded loop.
+*
+* **What is shared and what is not**, when a store is handed over:
+*
+* - **Single-flight is**, because per replica it is not a guarantee at all: the same double-click behind a load
+*   balancer lands on two of them and both run. The key is taken with `increment`, which is the one atomic
+*   test-and-set every adapter already has to provide — the holder is whoever's increment answered `1` — and it
+*   carries the run's own timeout as its lifetime, so a replica that dies holding one frees it by expiring.
+* - **The caps are not.** Counting them across replicas needs a decrementing counter, and a run that dies without
+*   decrementing throttles a healthy space until somebody notices. A ceiling that is per replica is a number a
+*   deployment can multiply and reason about; one that leaks is not. So `perSpace` is per replica, deliberately,
+*   and a cluster's real ceiling is that times the number of them.
+* - **Cancellation is**, in one direction. Only the process running a flow holds the `AbortController` that stops
+*   it, so a `DELETE` that lands anywhere else leaves a FLAG in the store and the run reads it at its next step
+*   boundary. Behind a load balancer that is the normal case rather than the exotic one: the tab that wants to
+*   stop a checkout almost never reaches the replica running it.
+* - **A finished answer is**, when the caller named the key and the deployment set a replay window.
+*/
+var createRunGuards = (config = {}, store, idempotency = {}) => {
+	const perSpace = config.perSpace ?? DEFAULTS.perSpace;
+	const perProcess = config.perProcess ?? DEFAULTS.perProcess;
+	const renderPerProcess = config.renderPerProcess ?? DEFAULTS.renderPerProcess;
+	const replayTtlMs = idempotency.replayTtlMs ?? 0;
+	const byKey = /* @__PURE__ */ new Map();
+	const byId = /* @__PURE__ */ new Map();
+	/** The no-store half of replay: one process remembering its own answers, which is what one process can honestly
+	*  offer. With a store it is never read — a cluster's replays have to be everybody's. */
+	const localResults = /* @__PURE__ */ new Map();
+	const sweep = () => {
+		const now = Date.now();
+		byKey.forEach((run) => {
+			if (run.expiresAt <= now) {
+				byKey.delete(run.runKey);
+				byId.delete(run.runId);
+			}
+		});
+		localResults.forEach((entry, key) => {
+			if (entry.expiresAt <= now) localResults.delete(key);
+		});
+	};
+	const count = (matches) => {
+		let total = 0;
+		byKey.forEach((run) => {
+			if (matches(run)) total += 1;
+		});
+		return total;
+	};
+	/**
+	* Takes the key, here and — when there is one — everywhere.
+	*
+	* `increment` is the primitive because it is the only atomic one the adapter contract has, and it says exactly
+	* what is needed: the caller whose increment answers `1` created the key and holds it. The lifetime is set by
+	* that same caller, which is the rule `createKvStore` already follows for a rate-limit window; the gap between
+	* the two calls is a key that outlives its holder if the process dies inside it, and it is the same gap that
+	* idiom has always had.
+	*/
+	const ttlSeconds = (ttlMs) => Math.max(1, Math.ceil(ttlMs / 1e3));
+	const takeShared = async (runKey, ttlMs) => {
+		if (!store) return true;
+		if (await store.increment(`${keyPrefix}${runKey}`, 1) !== 1) return false;
+		await store.expire(`${keyPrefix}${runKey}`, ttlSeconds(ttlMs));
+		return true;
+	};
+	const begin = async (params) => {
+		sweep();
+		const runKey = deriveRunKey(params);
+		const existing = byKey.get(runKey);
+		if (existing) throw new ActionRunError("duplicate", `This action is already running as ${existing.runId}`);
+		/**
+		* Two budgets, because they are two different risks.
+		*
+		* A call is counted against its space AND the process: one space's callers must not starve another's, and
+		* neither may take the box down. A render is counted against the PROCESS alone — it arrives because people
+		* are reading the page, so a per-space ceiling would refuse the visitor who made the space worth having.
+		*/
+		const kind = params.kind ?? "call";
+		if (kind === "render" ? count((run) => run.kind === "render") >= renderPerProcess : count((run) => run.kind === "call") >= perProcess || count((run) => run.kind === "call" && run.spaceId === params.spaceId) >= perSpace) throw new ActionRunError("over_capacity", "Too many actions are running right now");
+		const run = {
+			runId: randomUUID(),
+			runKey,
+			kind,
+			spaceId: params.spaceId,
+			actionId: params.actionId,
+			callerId: params.callerId,
+			controller: new AbortController(),
+			expiresAt: Date.now() + params.ttlMs,
+			explicitKey: Boolean(params.idempotencyKey)
+		};
+		/**
+		* The local slot is taken BEFORE anything is awaited, and that ordering is the guarantee.
+		*
+		* Everything above this line runs in one synchronous stretch, so two callers in the same process cannot both
+		* pass it — which is what made this work when `begin` was synchronous throughout. Reach for the store first
+		* and both of them would sail through the local check while the other was suspended on it.
+		*/
+		byKey.set(runKey, run);
+		byId.set(run.runId, run);
+		try {
+			if (!await takeShared(runKey, params.ttlMs)) throw new ActionRunError("duplicate", "This action is already running");
+		} catch (error) {
+			byKey.delete(runKey);
+			byId.delete(run.runId);
+			throw error;
+		}
+		await store?.set(runOwnerKey(run.runId), params.callerId, ttlSeconds(params.ttlMs)).catch(() => void 0);
+		return run;
+	};
+	/**
+	* Remembers what a run answered, for a caller that asks again by the same key.
+	*
+	* Only a COMPLETED run, and only a key the caller named. A failure is not replayed because a retry after one is
+	* the reasonable thing to do — pinning a transient outage for the whole window would turn a blip into an hour
+	* of it — and a derived key would make two deliberate identical calls into one.
+	*/
+	const remember = async (run, outcome) => {
+		if (replayTtlMs <= 0 || !run.explicitKey || outcome.status !== "completed") return;
+		const answer = {
+			runId: outcome.runId,
+			status: outcome.status,
+			output: outcome.output
+		};
+		if (!store) {
+			localResults.set(run.runKey, {
+				expiresAt: Date.now() + replayTtlMs,
+				result: answer
+			});
+			return;
+		}
+		await store.set(runResultKey(run.runKey), JSON.stringify(answer), ttlSeconds(replayTtlMs)).catch(() => void 0);
+	};
+	const end = async (run, outcome) => {
+		byKey.delete(run.runKey);
+		byId.delete(run.runId);
+		if (outcome) await remember(run, outcome);
+		await store?.delete(`${keyPrefix}${run.runKey}`).catch(() => void 0);
+		await store?.delete(runOwnerKey(run.runId)).catch(() => void 0);
+		await store?.delete(runCancelKey(run.runId)).catch(() => void 0);
+	};
+	/**
+	* The answer this key already produced, if it is still inside the window.
+	*
+	* Asked BEFORE a slot is taken, so a retry of something that already happened costs nothing and — this is the
+	* point — does not happen twice. Single-flight covers the retry that arrives while the first run is going; this
+	* covers the one that arrives a minute after it finished, which is the shape every webhook provider retries in.
+	*/
+	const replay = async (params) => {
+		if (replayTtlMs <= 0 || !params.idempotencyKey) return;
+		const runKey = deriveRunKey(params);
+		if (!store) {
+			sweep();
+			return localResults.get(runKey)?.result;
+		}
+		try {
+			const stored = await store.get(runResultKey(runKey));
+			return stored ? JSON.parse(stored) : void 0;
+		} catch {
+			return;
+		}
+	};
+	/**
+	* Only the caller that started a run may stop it.
+	*
+	* A run id is a bearer string that travels to the browser, and without this check anyone holding one could stop
+	* another visitor's checkout — a denial of service addressed at a single person.
+	*
+	* Local first, because a cancel that reaches the right replica should stop the flow at its next boundary rather
+	* than a store round trip later. When it does not — the usual case behind a load balancer — the request leaves
+	* the flag the running replica polls, and ownership is checked against what `begin` published.
+	*/
+	const cancel = async (runId, callerId) => {
+		const run = byId.get(runId);
+		if (run) {
+			if (run.callerId !== callerId) return false;
+			run.controller.abort();
+			await store?.set(runCancelKey(runId), "1", ttlSeconds(run.expiresAt - Date.now())).catch(() => void 0);
+			return true;
+		}
+		if (!store) return false;
+		try {
+			if (await store.get(runOwnerKey(runId)) !== callerId) return false;
+			await store.set(runCancelKey(runId), "1", CANCEL_FLAG_TTL_SECONDS);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	return {
+		begin,
+		end,
+		get: (runId) => byId.get(runId),
+		replay,
+		cancel,
+		active: () => byKey.size
+	};
+};
+//#endregion
+export { createRunGuards, deriveRunKey, runCancelKey };

package/dist/modules/actions/runtime/guards.test.d.ts

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

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

@@ -0,0 +1,27 @@
+import { ActionKvAdapter, ActionKvStore } from '../types';
+export type KvStoreConfig = {
+    /**
+     * Prefixed onto every key before it reaches the adapter. Defaults to `kv:`.
+     *
+     * The store a deployment hands over usually holds other things — a page cache, a session index — and a flow
+     * writing `visits:home` must not be able to land on one of them.
+     */
+    prefix?: string;
+};
+/**
+ * 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".
+ */
+export declare const createKvStore: (adapter: ActionKvAdapter, { prefix }?: KvStoreConfig) => ActionKvStore;

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

@@ -0,0 +1,41 @@
+//#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".
+*/
+var createKvStore = (adapter, { prefix = "kv:" } = {}) => {
+	const prefixed = (key) => `${prefix}${key}`;
+	return {
+		get: async (key) => {
+			const raw = await adapter.get(prefixed(key));
+			if (raw === void 0) return;
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return raw;
+			}
+		},
+		set: (key, value, ttlSeconds) => adapter.set(prefixed(key), JSON.stringify(value), ttlSeconds),
+		delete: (key) => adapter.delete(prefixed(key)),
+		increment: async (key, amount, ttlSeconds) => {
+			const full = prefixed(key);
+			const value = await adapter.increment(full, amount);
+			if (ttlSeconds !== void 0 && value === amount) await adapter.expire(full, ttlSeconds);
+			return value;
+		}
+	};
+};
+//#endregion
+export { createKvStore };

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

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

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

@@ -0,0 +1,11 @@
+import { ResolvedActionLimits } from '../types';
+import { ActionLimits } from '@plitzi/sdk-shared';
+export declare const DEFAULT_LIMITS: ResolvedActionLimits;
+/**
+ * Merges a document's limits over the deployment's.
+ *
+ * A per-action value may only ever TIGHTEN: the deployment is the party paying for the connection, the slot and
+ * the outbound traffic, and an authored document is customer input. Letting it widen would make every ceiling
+ * advisory — which is the same as not having one.
+ */
+export declare const resolveLimits: (deployment?: ActionLimits, document?: ActionLimits) => ResolvedActionLimits;

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

@@ -0,0 +1,35 @@
+//#region src/modules/actions/runtime/limits.ts
+var DEFAULT_LIMITS = {
+	timeoutMs: 1e4,
+	streamTimeoutMs: 12e4,
+	maxNodes: 50,
+	maxRequests: 20,
+	/** Generous for an API answer and nowhere near what it takes to hurt a process holding several runs at once. */
+	maxResponseBytes: 5e6
+};
+var tightest = (deployment, document) => document === void 0 || document <= 0 ? deployment : Math.min(deployment, document);
+/**
+* Merges a document's limits over the deployment's.
+*
+* A per-action value may only ever TIGHTEN: the deployment is the party paying for the connection, the slot and
+* the outbound traffic, and an authored document is customer input. Letting it widen would make every ceiling
+* advisory — which is the same as not having one.
+*/
+var resolveLimits = (deployment = {}, document = {}) => {
+	const base = {
+		timeoutMs: deployment.timeoutMs ?? DEFAULT_LIMITS.timeoutMs,
+		streamTimeoutMs: deployment.streamTimeoutMs ?? DEFAULT_LIMITS.streamTimeoutMs,
+		maxNodes: deployment.maxNodes ?? DEFAULT_LIMITS.maxNodes,
+		maxRequests: deployment.maxRequests ?? DEFAULT_LIMITS.maxRequests,
+		maxResponseBytes: deployment.maxResponseBytes ?? DEFAULT_LIMITS.maxResponseBytes
+	};
+	return {
+		timeoutMs: tightest(base.timeoutMs, document.timeoutMs),
+		streamTimeoutMs: tightest(base.streamTimeoutMs, document.streamTimeoutMs),
+		maxNodes: tightest(base.maxNodes, document.maxNodes),
+		maxRequests: tightest(base.maxRequests, document.maxRequests),
+		maxResponseBytes: tightest(base.maxResponseBytes, document.maxResponseBytes)
+	};
+};
+//#endregion
+export { DEFAULT_LIMITS, resolveLimits };

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

@@ -0,0 +1,2 @@
+import { ActionKvAdapter } from '../types';
+export declare const createMemoryKv: () => ActionKvAdapter;

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

@@ -0,0 +1,77 @@
+//#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;
+var createMemoryKv = () => {
+	const entries = /* @__PURE__ */ new Map();
+	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
+	* unbounded for everything else: a rate-limit window keyed by caller, an idempotency key per delivery, anything
+	* whose key is used once and never asked for again. Those entries expire and stay, and the map is the process's
+	* memory. Redis sweeps its own; this is the same courtesy, amortised over the writes that cause the growth.
+	*/
+	const sweep = () => {
+		writes += 1;
+		if (writes % SWEEP_EVERY !== 0) return;
+		const now = Date.now();
+		entries.forEach((entry, key) => {
+			if (entry.expiresAt !== void 0 && entry.expiresAt <= now) entries.delete(key);
+		});
+	};
+	const read = (key) => {
+		const entry = entries.get(key);
+		if (!entry) return;
+		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+			entries.delete(key);
+			return;
+		}
+		return entry;
+	};
+	const expiry = (ttlSeconds) => ttlSeconds === void 0 ? void 0 : Date.now() + ttlSeconds * 1e3;
+	return {
+		get: (key) => Promise.resolve(read(key)?.value),
+		set: (key, value, ttlSeconds) => {
+			entries.set(key, {
+				value,
+				expiresAt: expiry(ttlSeconds)
+			});
+			sweep();
+			return Promise.resolve();
+		},
+		delete: (key) => {
+			entries.delete(key);
+			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, {
+				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)
+			});
+			return Promise.resolve();
+		}
+	};
+};
+//#endregion
+export { createMemoryKv };

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

@@ -0,0 +1,9 @@
+import { ActionKvStore } from '../types';
+/**
+ * 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.
+ */
+export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;

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

@@ -0,0 +1,19 @@
+//#region src/modules/actions/runtime/namespaceKv.ts
+/**
+* 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.
+*/
+var namespaceKv = (store, spaceId) => {
+	const scoped = (key) => `action:${spaceId}:${key}`;
+	return {
+		get: (key) => store.get(scoped(key)),
+		set: (key, value, ttlSeconds) => store.set(scoped(key), value, ttlSeconds),
+		delete: (key) => store.delete(scoped(key)),
+		increment: (key, amount, ttlSeconds) => store.increment(scoped(key), amount, ttlSeconds)
+	};
+};
+//#endregion
+export { namespaceKv };

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

@@ -0,0 +1,27 @@
+import { ActionEntry, ActionTriggerType, ElementInteraction, SSRUser } from '@plitzi/sdk-shared';
+export type PrecheckParams = {
+    trigger: ActionTriggerType;
+    input: Record<string, unknown>;
+    user?: SSRUser;
+    /** Chain of run ids that caused this one. A run naming its own action is a loop. */
+    lineage?: string[];
+};
+/** The entry point that was cleared, and the input that survived its contract. */
+export type PrecheckResult = {
+    trigger: ElementInteraction;
+    values: Record<string, unknown>;
+};
+/**
+ * Everything that decides whether a run may happen at all, before it costs anything.
+ *
+ * One implementation, two callers, on purpose. The RUNNER calls it because a deployment mounting its own trigger
+ * goes straight there, and a check that lived only in the endpoint would be a check a custom trigger silently
+ * skips. The ENDPOINT calls it first because these are pure and cheap, and a refusal that has already taken a
+ * concurrency slot and a metering event teaches callers to retry harder for something that was never going to run.
+ *
+ * Everything it reads about the caller — may they, and with what — is on the TRIGGER STEP, so an action reachable
+ * both by a signed webhook and by a page call answers each on its own terms instead of on the loosest of the two.
+ *
+ * Returns the entry point and the coerced input, so neither caller has to find or validate either twice.
+ */
+export declare const precheckRun: (entry: ActionEntry, params: PrecheckParams) => PrecheckResult;

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

@@ -0,0 +1,45 @@
+import { ActionRunError } from "./errors.js";
+import { applyFields } from "./scope.js";
+import { findTriggerNode, triggerParams } from "./triggers.js";
+import { triggerAccess, triggerInput } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/runtime/precheck.ts
+var authorize = (access, kind, user) => {
+	if (kind === "schedule") return;
+	if (!access) throw new ActionRunError("forbidden", "This trigger declares no access rule");
+	if (access.mode === "public") return;
+	if (!user) throw new ActionRunError("unauthenticated", "This action requires a signed-in visitor");
+	if (access.mode === "role") {
+		const held = new Set(user.permissions);
+		if (access.permissions.some((permission) => !held.has(permission))) throw new ActionRunError("forbidden", "This action requires permissions the caller does not hold");
+	}
+};
+/**
+* Everything that decides whether a run may happen at all, before it costs anything.
+*
+* One implementation, two callers, on purpose. The RUNNER calls it because a deployment mounting its own trigger
+* goes straight there, and a check that lived only in the endpoint would be a check a custom trigger silently
+* skips. The ENDPOINT calls it first because these are pure and cheap, and a refusal that has already taken a
+* concurrency slot and a metering event teaches callers to retry harder for something that was never going to run.
+*
+* Everything it reads about the caller — may they, and with what — is on the TRIGGER STEP, so an action reachable
+* both by a signed webhook and by a page call answers each on its own terms instead of on the loosest of the two.
+*
+* Returns the entry point and the coerced input, so neither caller has to find or validate either twice.
+*/
+var precheckRun = (entry, params) => {
+	const { document } = entry;
+	const trigger = findTriggerNode(document.nodes, params.trigger);
+	if (!trigger) throw new ActionRunError("forbidden", `This action cannot be started by a "${params.trigger}" trigger`);
+	if (!trigger.enabled) throw new ActionRunError("disabled", `This action's "${params.trigger}" trigger is switched off`);
+	if (params.lineage?.includes(entry.id)) throw new ActionRunError("recursion", "This action already appears in the run lineage");
+	const stepParams = triggerParams(trigger);
+	authorize(triggerAccess(stepParams), params.trigger, params.user);
+	const { values, missing, invalid } = applyFields(triggerInput(stepParams), params.input);
+	if (missing.length > 0 || invalid.length > 0) throw new ActionRunError("invalid_input", `Invalid input: ${[...missing, ...invalid].join(", ")}`);
+	return {
+		trigger,
+		values
+	};
+};
+//#endregion
+export { precheckRun };

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

@@ -0,0 +1,15 @@
+import { RscElementResolver } from '../../rsc/resolveRscData';
+import { ActionsModule } from '../index';
+import { ActionLookups } from '../types';
+/**
+ * Resolves a `runtime: 'server'` element that names an ACTION rather than a connector.
+ *
+ * This is the read a manifest cannot express: two calls that have to be joined, a field computed from both, a
+ * shape that depends on who is looking. The element names an action exactly as it would name a connector, and the
+ * 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.
+ */
+export declare const createActionResolver: (lookups: ActionLookups, module: ActionsModule) => RscElementResolver;