@plitzi/sdk-server 0.33.2 → 0.34.0

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

@@ -0,0 +1,130 @@
+import { ActionRunError } from "./errors.js";
+import { findTriggerNode, triggerParams } from "./triggers.js";
+import onAbort from "../../../helpers/onAbort.js";
+import { createRenderShare } from "./renderShare.js";
+import { createHash, randomUUID } from "node:crypto";
+import { triggerCacheMs } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/runtime/renderResolver.ts
+/**
+* What makes two renders the same question.
+*
+* Everything that can change the answer, and nothing else: the space and the version being served, the action,
+* the visitor, and the input the flow will actually see. The USER is in there because an action may read
+* `{{ user.* }}` — sharing across visitors would hand one person another's page — while anonymous visitors, who
+* are most of them, share the one key that matters.
+*/
+var shareKey = (parts) => createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
+/**
+* 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.
+*/
+var createActionResolver = (lookups, module) => {
+	const share = createRenderShare();
+	return async ({ element, routeParams, queryParams, spaceId, environment, user, req, signal }) => {
+		/**
+		* Which version of the space is being rendered — environment AND revision from the same record.
+		*
+		* Reading one from the deployment and the other from the resolve context would let them disagree, and the
+		* combination "this environment, that revision" names a snapshot nobody published.
+		*/
+		const deployment = req.ctx.spaceDeployment;
+		const at = {
+			environment: deployment?.environment ?? environment,
+			revision: deployment?.revision ?? 0
+		};
+		const { action: actionId, input = {} } = element.attributes;
+		if (!actionId) return;
+		const entry = await lookups.getAction(spaceId, actionId, at);
+		if (!entry) throw new Error(`Action "${actionId}" is not configured for space ${spaceId}`);
+		const values = {
+			...routeParams,
+			...queryParams,
+			...input
+		};
+		const trigger = findTriggerNode(entry.document.nodes, "render");
+		const ttlMs = trigger ? triggerCacheMs(triggerParams(trigger)) : 0;
+		const key = shareKey([
+			spaceId,
+			at.environment,
+			at.revision,
+			entry.id,
+			user?.id ?? null,
+			values
+		]);
+		const callerId = user ? `user:${user.id}` : "render";
+		const startRun = async () => {
+			/**
+			* A key of its own per render, so two visitors are never each other's duplicate.
+			*
+			* Single-flight exists for the caller who submits twice — a double-click, a retry — and keys on the caller
+			* and the input. A render has neither of those to go on: every anonymous visitor of one URL is `render`
+			* with the same input, so the derived key made concurrent page loads collide and one of them had its
+			* section refused as a duplicate. The busier the page, the more often.
+			*/
+			const run = await module.guards.begin({
+				spaceId,
+				actionId: entry.id,
+				callerId,
+				input,
+				idempotencyKey: `render:${randomUUID()}`,
+				kind: "render",
+				ttlMs: module.limitsFor(entry.document).timeoutMs
+			});
+			/**
+			* The render giving up ends the run, not just the wait for it.
+			*
+			* `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.
+			*/
+			const releaseRenderStop = onAbort(signal, () => run.controller.abort());
+			try {
+				const result = await module.runAction({
+					entry,
+					input: values,
+					spaceId,
+					environment,
+					trigger: "render",
+					user,
+					callerId,
+					runId: run.runId,
+					at,
+					signal: run.controller.signal
+				});
+				/**
+				* A run that did not COMPLETE resolved nothing, and must not look like one that resolved to nothing.
+				*
+				* A step that throws — an outbound call with no internet behind it, a `flow.fail` guard, a timeout — ends
+				* the run with `status: 'failed'` and an empty output, which published as a slice is indistinguishable
+				* from a provider that legitimately returned no records. The element then renders its empty state instead
+				* of its error one, and the bindings meant for exactly this (`hasError`, `errorMessage`) never fire: the
+				* page says "nothing here" when the truth is "this could not be fetched".
+				*/
+				if (result.status !== "completed") throw new Error(`Action "${actionId}" ended as ${result.status}`);
+				return result.output;
+			} catch (error) {
+				if (error instanceof ActionRunError) throw new Error(`Action "${actionId}" refused this render: ${error.reason}`, { cause: error });
+				throw error;
+			} finally {
+				releaseRenderStop();
+				await module.guards.end(run);
+			}
+		};
+		/**
+		* Everyone asking the same question at once gets one run, and its answer.
+		*
+		* Not an optimisation — it is what makes a page survive being read. Without it, a thousand visitors of one URL
+		* are a thousand identical flows and a thousand identical outbound requests, arriving at whatever the action
+		* reads all in the same instant.
+		*/
+		return share.run(key, ttlMs, startRun);
+	};
+};
+//#endregion
+export { createActionResolver };

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * 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>;
+    /** Entries currently held, for a deployment that wants to see it. */
+    size: () => number;
+};
+export declare const createRenderShare: (now?: () => number) => RenderShare;

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

@@ -0,0 +1,36 @@
+//#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) => {
+	entries.forEach((entry, key) => {
+		if (!entry.inFlight && (entry.expiresAt === void 0 || entry.expiresAt <= now)) entries.delete(key);
+	});
+};
+var createRenderShare = (now = Date.now) => {
+	const entries = /* @__PURE__ */ new Map();
+	const run = async (key, ttlMs, produce) => {
+		const existing = entries.get(key);
+		if (existing?.inFlight) return existing.inFlight;
+		if (existing && existing.expiresAt !== void 0 && existing.expiresAt > now()) return existing.value;
+		const inFlight = produce();
+		entries.set(key, { inFlight });
+		try {
+			const value = await inFlight;
+			sweep(entries, now());
+			if (ttlMs > 0) entries.set(key, {
+				value,
+				expiresAt: now() + ttlMs
+			});
+			else entries.delete(key);
+			return value;
+		} catch (error) {
+			entries.delete(key);
+			throw error;
+		}
+	};
+	return {
+		run,
+		size: () => entries.size
+	};
+};
+//#endregion
+export { createRenderShare };

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

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

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

@@ -0,0 +1,14 @@
+import { ActionRejectRecord, SSRPageServerConfig } from '@plitzi/sdk-shared';
+/**
+ * Reports a request that never became a run.
+ *
+ * Its own function rather than a call at each refusal so the two transports cannot end up reporting different
+ * things — and so the rule that a report may not fail the answer is written once. A deployment's sink throwing
+ * must not turn a clean 401 into a 500: the caller was refused either way, and the refusal is the part that has
+ * to reach them.
+ *
+ * Nothing is filtered here. A duplicate delivery is a well-behaved sender retrying and an invalid signature is a
+ * broken integration, but which of those is worth a row in somebody's activity feed is a policy, and policies
+ * belong to the deployment.
+ */
+export declare const reportReject: (config: SSRPageServerConfig, record: ActionRejectRecord) => Promise<void>;

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

@@ -0,0 +1,22 @@
+//#region src/modules/actions/runtime/report.ts
+/**
+* Reports a request that never became a run.
+*
+* Its own function rather than a call at each refusal so the two transports cannot end up reporting different
+* things — and so the rule that a report may not fail the answer is written once. A deployment's sink throwing
+* must not turn a clean 401 into a 500: the caller was refused either way, and the refusal is the part that has
+* to reach them.
+*
+* Nothing is filtered here. A duplicate delivery is a well-behaved sender retrying and an invalid signature is a
+* broken integration, but which of those is worth a row in somebody's activity feed is a policy, and policies
+* belong to the deployment.
+*/
+var reportReject = async (config, record) => {
+	try {
+		await config.action?.onReject?.(record);
+	} catch (error) {
+		console.error("[Actions] reject record failed:", error);
+	}
+};
+//#endregion
+export { reportReject };

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

@@ -0,0 +1,12 @@
+import { ActionRunRequest, ActionRunResult, ActionsConfig, ActionTaskRegistry } from '../types';
+export type ActionRunner = {
+    runAction: (request: ActionRunRequest) => Promise<ActionRunResult>;
+};
+/**
+ * Builds the runner every trigger goes through.
+ *
+ * Every check that decides whether a run may happen at all — the trigger and whether it is on, access, lineage,
+ * input contract — lives HERE rather than in a transport, because a deployment mounting its own trigger calls this
+ * directly. A check in the endpoint would be a check a custom trigger silently skips.
+ */
+export declare const createActionRunner: (config: ActionsConfig, registry: ActionTaskRegistry, baseFetch?: typeof fetch) => ActionRunner;

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

@@ -0,0 +1,405 @@
+import { ActionRunError } from "./errors.js";
+import { runCancelKey } from "./guards.js";
+import { createKvStore } from "./kvStore.js";
+import { resolveLimits } from "./limits.js";
+import { createMemoryKv } from "./memoryKv.js";
+import { namespaceKv } from "./namespaceKv.js";
+import { createRedactor, projectUser } from "./scope.js";
+import { precheckRun } from "./precheck.js";
+import onAbort from "../../../helpers/onAbort.js";
+import { evaluateRuleGroup } from "@plitzi/sdk-shared/helpers/ruleEvaluator";
+import { hasValidToken, processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+//#region src/modules/actions/runtime/runAction.ts
+var MAX_TWIG_RESOLUTION_PASSES = 5;
+/** How often a run asks the shared store whether it has been cancelled. Once a second is far finer than the
+*  boundaries a flow actually has, and it keeps a long run to sixty reads a minute. */
+var CANCEL_POLL_MS = 1e3;
+/**
+* The run's deadline, as a promise that loses patience.
+*
+* Aborting the controller is the polite half: a task that watches its signal stops, and the loop refuses to start
+* the next step. It is not enough on its own, because a step that ignores the signal — a driver that does not
+* take one, a provider client that swallows it, a `while (true)` inside a task — leaves the run awaiting something
+* that never returns. That is the stuck run this exists to end: nothing else in the process can tell the
+* difference between a flow that is working hard and one that will never finish.
+*
+* Racing the flow against this means the RUN always ends, even when a step does not. What the step does after
+* that is beyond anybody's reach in a single-threaded runtime — but it no longer holds a caller, a slot, or a
+* connection while it does it.
+*/
+var createDeadline = (timeoutMs, controller) => {
+	let timer;
+	return {
+		promise: new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				controller.abort();
+				reject(new ActionRunError("timeout", `Action exceeded its ${timeoutMs}ms budget`));
+			}, timeoutMs);
+		}),
+		clear: () => clearTimeout(timer)
+	};
+};
+/**
+* Whether somebody has asked this run to stop, from wherever the request landed.
+*
+* The socket closing aborts a run in the process that is running it, and a `DELETE` that happens to reach that
+* same process does too. Behind a load balancer it usually does not: a cancel arrives at a replica that has never
+* heard of the run, and the flow it was meant to stop carries on charging cards. So the cancel is a FLAG in the
+* store the deployment already shares, and this is the run reading it at every step boundary.
+*
+* Without a shared store it is a no-op rather than a lie — one process's local abort is the whole mechanism there,
+* and it already works.
+*/
+var createCancelWatch = (store, runId) => {
+	if (!store) return () => Promise.resolve(false);
+	let checkedAt = 0;
+	return async () => {
+		const now = Date.now();
+		if (now - checkedAt < CANCEL_POLL_MS) return false;
+		checkedAt = now;
+		try {
+			return await store.get(runCancelKey(runId)) !== void 0;
+		} catch {
+			return false;
+		}
+	};
+};
+/**
+* Resolves twig in a node's params against the flow scope.
+*
+* Multi-pass with a ceiling, exactly as the client engine does: a value can resolve to another template, and
+* without the ceiling a self-referencing pair spins forever. Unresolved tokens are left as-is and show up in the
+* trace, which is how an author sees that a step referenced something the flow never produced.
+*/
+var resolveParams = (params, scope, raw) => {
+	if (raw) return params;
+	return Object.entries(params).reduce((acum, [key, param]) => {
+		let value = param;
+		let passes = MAX_TWIG_RESOLUTION_PASSES;
+		while (typeof value === "string" && hasValidToken(value) && passes > 0) {
+			value = processTwig(value, scope, false, true);
+			passes--;
+		}
+		acum[key] = value;
+		return acum;
+	}, {});
+};
+/**
+* Holds an answer to what the run is allowed to carry.
+*
+* Two checks rather than one, because a body arrives in two ways. `Content-Length` is refused before a byte is
+* read, which is the cheap half; a chunked answer that declares nothing is counted AS it streams and errored the
+* moment it goes over — so the ceiling holds for a backend that lies about its size or never states one.
+*
+* The cap is on one response and not on the run: it exists so that a single answer cannot be unbounded, which is
+* a different failure from a flow that makes many small calls (that is `maxRequests`).
+*/
+var capped = (response, maxBytes) => {
+	const declared = Number(response.headers.get("content-length") ?? "");
+	if (Number.isFinite(declared) && declared > maxBytes) throw new ActionRunError("over_capacity", `Response is larger than the ${maxBytes} byte budget`);
+	if (!response.body) return response;
+	let seen = 0;
+	const counted = response.body.pipeThrough(new TransformStream({ transform: (chunk, controller) => {
+		seen += chunk.byteLength;
+		if (seen > maxBytes) {
+			controller.error(new ActionRunError("over_capacity", `Response exceeded the ${maxBytes} byte budget`));
+			return;
+		}
+		controller.enqueue(chunk);
+	} }));
+	return new Response(counted, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+};
+/**
+* Counts outbound calls, refuses past the budget, caps what one answer may carry back, and stamps the run's
+* lineage on every one of them.
+*
+* The budget stops a loop from turning one run into a hundred requests. The lineage header is what makes the
+* OTHER loop detectable: an action whose HTTP step reaches its own space's webhook arrives carrying the chain
+* that led there, and the run it would start refuses itself. It names the space's own actions to a backend that
+* space configured, which is the cost of catching a cycle nothing else can see.
+*
+* 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) => {
+	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`);
+		const headers = new Headers(init?.headers);
+		headers.set("X-Plitzi-Action-Lineage", lineage.join(","));
+		return capped(await base(input, {
+			...init,
+			headers,
+			signal: init?.signal ?? signal
+		}), limits.maxResponseBytes);
+	};
+};
+/**
+* Fills in what the node left out, from the task's own catalog entry.
+*
+* A task declares its params with a `defaultValue`, and a document written before a param existed simply has no
+* value for it. Without this the task receives `undefined` for something its signature says is a string, which is
+* how tasks end up full of defensive conversions that hide the real gap.
+*/
+/**
+* The pseudo-step a failure is recorded as.
+*
+* A run that died has no node to blame — a ceiling it hit, a throw from outside any step — and the trace is a list
+* of steps. Written out in full rather than cast into shape: a field added to a step becomes a compile error here
+* instead of an `undefined` whoever reads the trace has to work out.
+*/
+var errorNode = (action) => ({
+	id: "error",
+	title: "Error",
+	type: "task",
+	action,
+	params: {},
+	preview: {},
+	elementId: null,
+	beforeNode: "",
+	afterNode: "",
+	flowId: "",
+	enabled: true
+});
+var withDefaults = (task, params) => Object.entries(task.params).reduce((acum, [key, param]) => {
+	if (acum[key] === void 0 || acum[key] === "") acum[key] = param.defaultValue ?? "";
+	return acum;
+}, { ...params });
+var runNode = async (node, scope, registry, buildContext) => {
+	if (!node.action || !node.enabled) return {
+		status: "disabled",
+		result: {}
+	};
+	if (node.when && !evaluateRuleGroup(node.when, {
+		...scope,
+		[node.id]: node.params
+	})) return {
+		status: "skipped",
+		result: {}
+	};
+	if (node.type !== "task") throw new ActionRunError("failed", `Step "${node.action}" is a ${node.type}, which cannot run on the server`);
+	const task = registry.get(node.action);
+	if (!task) throw new ActionRunError("failed", `No server task is registered as "${node.action}"`);
+	const params = withDefaults(task, resolveParams(node.params, scope, task.rawParams === true));
+	return {
+		status: "success",
+		result: await task.run(params, buildContext(scope))
+	};
+};
+/**
+* Builds the runner every trigger goes through.
+*
+* Every check that decides whether a run may happen at all — the trigger and whether it is on, access, lineage,
+* input contract — lives HERE rather than in a transport, because a deployment mounting its own trigger calls this
+* directly. A check in the endpoint would be a check a custom trigger silently skips.
+*/
+var createActionRunner = (config, registry, baseFetch = fetch) => {
+	const kv = createKvStore(config.kv ?? createMemoryKv());
+	/** Never allowed to fail a run: a logging outage must not take an action down, the same rule metering follows. */
+	const record = async (entry) => {
+		try {
+			await config.onRun?.(entry);
+		} catch (error) {
+			console.error("[Actions] run record failed:", error);
+		}
+	};
+	const runAction = async (request) => {
+		const { entry, runId } = request;
+		const { document } = entry;
+		const { trigger: triggerNode, values } = precheckRun(entry, {
+			trigger: request.trigger,
+			input: request.input,
+			user: request.user,
+			lineage: request.lineage
+		});
+		const limits = resolveLimits(config.limits, document.limits);
+		const redactor = createRedactor();
+		const redact = redactor.redact;
+		const controller = new AbortController();
+		const deadline = createDeadline(request.emit ? limits.streamTimeoutMs : limits.timeoutMs, controller);
+		const releaseOuter = onAbort(request.signal, () => controller.abort());
+		const scopedKv = namespaceKv(kv, request.spaceId);
+		const runFetch = createRunFetch(baseFetch, controller.signal, limits, [...request.lineage ?? [], entry.id]);
+		const buildContext = (scope) => ({
+			runId,
+			spaceId: request.spaceId,
+			environment: request.environment,
+			trigger: request.trigger,
+			user: request.user,
+			callerId: request.callerId,
+			signal: controller.signal,
+			scope,
+			/**
+			* The secret a STEP asked for, resolved inside that step and never in the flow scope.
+			*
+			* There is no allow-list to check it against, deliberately: an action is authored by someone who may edit
+			* every action in the space, so a list they can edit is not a boundary — it only ever told the redactor what
+			* to look for, and the redactor now learns from what was actually resolved. What IS a boundary is that a
+			* credential reaches only the params of the step that named it, which is `renderTaskParams`' whole job.
+			*/
+			credential: async (identifier) => {
+				const credential = await config.lookups.getCredential?.(request.spaceId, identifier);
+				if (credential) redactor.add(credential);
+				return credential;
+			},
+			connector: async (connectorId) => {
+				const manifest = await config.lookups.getConnector?.(request.spaceId, connectorId, request.at);
+				if (!manifest) return;
+				const credential = manifest.credential ? await config.lookups.getCredential?.(request.spaceId, manifest.credential) : void 0;
+				if (credential) redactor.add(credential);
+				return {
+					manifest,
+					credential
+				};
+			},
+			fetch: runFetch,
+			kv: scopedKv,
+			dbDrivers: config.dbDrivers ?? [],
+			emit: (chunk) => request.emit?.(redact(chunk))
+		});
+		const trace = [];
+		const startedAt = Date.now();
+		let failure;
+		/**
+		* What every step can see.
+		*
+		* The run itself carries only the basics — which space, which environment, who asked, what came in — and
+		* everything else a flow can reach is whatever a TASK chose to return into it. Credentials are deliberately
+		* NOT here: an ambient `{{credential.*}}` would be interpolable by any node, including `flow.output`, which
+		* is a secret handed to the browser through a step nobody would think to audit. A task that needs one asks
+		* for it by identifier and resolves it inside its own execution.
+		*/
+		const scope = {
+			input: values,
+			user: projectUser(request.user),
+			spaceId: request.spaceId,
+			environment: request.environment,
+			trigger: request.trigger,
+			runId
+		};
+		let status = "completed";
+		let returned;
+		const isCancelled = createCancelWatch(config.kv, runId);
+		/**
+		* The flow itself, as something that can be raced.
+		*
+		* Separated from the `try` around it for one reason: what awaits it must be able to stop awaiting. A run that
+		* hits its deadline answers, releases its slot and closes its connection while whatever step ignored the abort
+		* carries on in the background — which is the difference between a stuck STEP and a stuck server.
+		*/
+		const runFlow = async () => {
+			let current = triggerNode;
+			let executed = 0;
+			let next = document.nodes[current.afterNode];
+			while (next) {
+				if (controller.signal.aborted) {
+					status = "aborted";
+					break;
+				}
+				if (await isCancelled()) {
+					controller.abort();
+					status = "aborted";
+					break;
+				}
+				executed += 1;
+				if (executed > limits.maxNodes) throw new ActionRunError("over_capacity", `Action exceeded its ${limits.maxNodes} step budget`);
+				const startTime = Date.now();
+				const outcome = await runNode(next, scope, registry, buildContext);
+				trace.push({
+					node: next,
+					status: outcome.status,
+					result: redact(outcome.result),
+					postCallbacks: [],
+					startTime,
+					endTime: Date.now()
+				});
+				request.onNode?.(next.id, outcome.status);
+				scope[next.id] = outcome.result;
+				if (next.action === "flow.output" && outcome.status === "success") returned = outcome.result;
+				current = next;
+				next = document.nodes[current.afterNode];
+			}
+		};
+		/** Set when the run ends in a way the CALLER has to hear as a status code rather than as a result. */
+		let fatal;
+		try {
+			await Promise.race([runFlow(), deadline.promise]);
+		} catch (error) {
+			status = controller.signal.aborted ? "aborted" : "failed";
+			if (error instanceof ActionRunError) {
+				/**
+				* Recorded before it is rethrown.
+				*
+				* A run refused before it began is not a run and leaves nothing; a run that STARTED and then hit a
+				* ceiling — its deadline, its step budget, its request budget — is exactly the one somebody needs to find
+				* afterwards. Rethrowing straight from here used to skip the record, so the runs hardest to explain were
+				* the ones that left no trace at all.
+				*/
+				fatal = error;
+				failure = error.message;
+				trace.push({
+					node: errorNode(error.reason),
+					status: "failed",
+					result: redact({
+						error: error.message,
+						reason: error.reason
+					}),
+					postCallbacks: [],
+					startTime: Date.now(),
+					endTime: Date.now()
+				});
+			} else {
+				failure = error instanceof Error ? error.message : String(error);
+				trace.push({
+					node: errorNode("error"),
+					status: "failed",
+					result: redact({ error: error instanceof Error ? error.message : String(error) }),
+					postCallbacks: [],
+					startTime: Date.now(),
+					endTime: Date.now()
+				});
+			}
+		} finally {
+			deadline.clear();
+			releaseOuter();
+		}
+		const output = returned ?? {};
+		await record({
+			runId,
+			actionId: entry.id,
+			spaceId: request.spaceId,
+			environment: request.environment,
+			trigger: request.trigger,
+			status,
+			durationMs: Date.now() - startedAt,
+			...request.user ? { userId: request.user.id } : {},
+			nodes: trace.map((step) => ({
+				id: step.node.id,
+				action: step.node.action,
+				status: step.status
+			})),
+			...failure === void 0 ? {} : { error: redact(failure) }
+		});
+		if (fatal) throw fatal;
+		/**
+		* The trace is COPIED out.
+		*
+		* A run that hit its deadline is no longer awaited, and whatever step ignored the abort may still push into
+		* this array while the answer is being serialized. The caller gets what was true when it asked.
+		*/
+		return {
+			runId,
+			status,
+			output: redact(output),
+			trace: [...trace]
+		};
+	};
+	return { runAction };
+};
+//#endregion
+export { createActionRunner };

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

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