@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/kernel.js

@@ -2,21 +2,8 @@ import { clientIp, parseRequest, readRawBody, requestOrigin } from "./core/reque
 import { createHttpServer } from "./core/server/baseServer.js";
 import { PREVIEW_TOKEN_PARAM } from "./core/previewToken.js";
 import { makeHandler } from "./core/http/dispatcher.js";
-import { clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
 import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { healthStage } from "./core/http/stages/health.js";
 import { configStaticStage, publicDirStage, wellKnownStage } from "./core/http/stages/static.js";
 import { consoleLogger, renderLogEvent } from "./helpers/serverLog.js";
-import { SCOPES, authFailureMessage, createTokens, userIdOf } from "./core/auth/tokens.js";
-import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
-import { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from "./core/auth/domains.js";
-import { createIdentity } from "./core/auth/identity.js";
-import { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from "./core/auth/authorize.js";
-import { createAuthApi } from "./core/auth/api.js";
-import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
-import { createAuth } from "./core/auth/createAuth.js";
-import { createSpaceTokenApi } from "./core/auth/spaceTokens.js";
-import { OAuthFailure } from "./core/auth/oauth/types.js";
-import { requestProfileJson } from "./core/auth/oauth/client.js";
-import { BUILT_IN_PROVIDERS, createSocialAuth } from "./core/auth/oauth/index.js";
-export { ANY_DOMAIN, BUILT_IN_PROVIDERS, OAuthFailure, PREVIEW_TOKEN_PARAM, SCOPES, applySessionOutcome, authFailureMessage, authPolicyRules, authRoutes, buildHealthPayload, checkPermission, checkSpaceAccess, clearFlowCookie, clearSessionCookies, clientIp, configStaticStage, consoleLogger, corsOrigins, createAuth, createAuthApi, createAuthorizer, createCarriers, createHttpServer, createIdentity, createSessionCookies, createSocialAuth, createSpaceTokenApi, createTokens, domainAllowed, frameAncestors, healthStage, hostnameOf, isLocalHost, makeHandler, normalizeDomain, parseRequest, presentedOrigin, publicDirStage, readFlowCookie, readRawBody, readRefreshToken, readSessionToken, registerHealthCheck, renderLogEvent, requestOrigin, requestProfileJson, requirementFor, sessionCookieParams, sessionHintValue, userIdOf, wellKnownStage, writeFlowCookie, writeSessionCookies };
+export { PREVIEW_TOKEN_PARAM, buildHealthPayload, clientIp, configStaticStage, consoleLogger, createHttpServer, healthStage, makeHandler, parseRequest, publicDirStage, readRawBody, registerHealthCheck, renderLogEvent, requestOrigin, wellKnownStage };

package/dist/modules/actions/{handler.js → connectorWrite.js}

@@ -1,5 +1,5 @@
 import { writeConnectorRecord } from "../connectors/engine.js";
-//#region src/modules/actions/handler.ts
+//#region src/modules/actions/connectorWrite.ts
 var parseBody = (body) => {
 	if (!body) return;
 	try {
@@ -44,7 +44,10 @@ var handleAction = async (req, res, config, lookups) => {
 		fail(res, 400, "Element has no connector");
 		return;
 	}
-	const manifest = await lookups.getConnector(spaceId, connectorId);
+	const manifest = await lookups.getConnector(spaceId, connectorId, {
+		environment,
+		revision
+	});
 	if (!manifest) {
 		fail(res, 404, "Unknown connector");
 		return;

package/dist/modules/actions/connectorWrite.test.d.ts

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

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

@@ -0,0 +1,40 @@
+import { RunGuards } from './runtime/guards';
+import { ActionRunner } from './runtime/runAction';
+import { ActionKvStore, ActionsConfig, ActionTaskRegistry, ResolvedActionLimits } from './types';
+import { ActionDocument } from '@plitzi/sdk-shared';
+export type ActionsModule = ActionRunner & {
+    registry: ActionTaskRegistry;
+    guards: RunGuards;
+    /** The key/value store, namespaced to one space — the same one the `kv` tasks write through, so a rate limit the
+     *  transport keeps and a counter a flow keeps cannot end up in different places. */
+    kv: (spaceId: number) => ActionKvStore;
+    /** What this server will allow one run of that document to spend — the deployment's ceilings, tightened by it. */
+    limitsFor: (document: ActionDocument) => ResolvedActionLimits;
+};
+/**
+ * The module's whole public surface: build it once from the deployment's config, then run actions through it.
+ *
+ * Constructed rather than imported piecemeal so the task registry is validated ONCE, at boot, and so the guards
+ * are a single set for the process — two instances would each think they were the only run in flight, which is
+ * the same as having no single-flight at all. Nothing outside this folder needs to know how a run is assembled.
+ */
+export declare const createActionsModule: (config: ActionsConfig) => ActionsModule;
+export { ActionRunError } from './runtime/errors';
+export { precheckRun } from './runtime/precheck';
+export { checkAction } from './runtime/check';
+export { DEFAULT_LIMITS, resolveLimits } from './runtime/limits';
+export { createRunGuards, deriveRunKey } from './runtime/guards';
+export { createScheduleRunner } from './runtime/schedule';
+export { createMemoryKv } from './runtime/memoryKv';
+export { createRunLogger, createRejectLogger } from './runtime/runLogger';
+export { createTaskRegistry, taskName } from './tasks/registry';
+export { describeCatalog, describeTask } from './taskCatalog';
+export { handleActionCall } from './transport/callHandler';
+export { handleActionCatalog } from './transport/catalogHandler';
+export { handleActionWebhook } from './transport/webhookHandler';
+export { verifySignature } from './transport/verifySignature';
+export { handleActionCancel } from './transport/cancelHandler';
+export type { ActiveRun, RunGuards } from './runtime/guards';
+export type { ScheduleResult, ScheduleRunner, ScheduleTick } from './runtime/schedule';
+export type { ActionTaskDescriptor } from './taskCatalog';
+export type { ActionCredential, ActionDbDriver, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './types';

package/dist/modules/actions/index.js

@@ -0,0 +1,46 @@
+import "./runtime/errors.js";
+import { createRunGuards } from "./runtime/guards.js";
+import { createKvStore } from "./runtime/kvStore.js";
+import { resolveLimits } from "./runtime/limits.js";
+import { createMemoryKv } from "./runtime/memoryKv.js";
+import { namespaceKv } from "./runtime/namespaceKv.js";
+import "./runtime/precheck.js";
+import { createActionRunner } from "./runtime/runAction.js";
+import { createTaskRegistry } from "./tasks/registry.js";
+import "./runtime/check.js";
+import "./runtime/schedule.js";
+import "./runtime/runLogger.js";
+import "./taskCatalog.js";
+import { handleActionCall } from "./transport/callHandler.js";
+import { handleActionCatalog } from "./transport/catalogHandler.js";
+import "./transport/verifySignature.js";
+import { handleActionWebhook } from "./transport/webhookHandler.js";
+import { handleActionCancel } from "./transport/cancelHandler.js";
+//#region src/modules/actions/index.ts
+/**
+* The module's whole public surface: build it once from the deployment's config, then run actions through it.
+*
+* Constructed rather than imported piecemeal so the task registry is validated ONCE, at boot, and so the guards
+* are a single set for the process — two instances would each think they were the only run in flight, which is
+* the same as having no single-flight at all. Nothing outside this folder needs to know how a run is assembled.
+*/
+var createActionsModule = (config) => {
+	const registry = createTaskRegistry(config.tasks, (config.dbDrivers?.length ?? 0) > 0);
+	const { runAction } = createActionRunner(config, registry, config.fetchImpl);
+	/**
+	* Single-flight over the store the deployment already gave the `kv` tasks — its own Redis, table or whatever it
+	* runs — because per process it is not a guarantee: the same double-click behind a load balancer lands on two
+	* replicas and both run. With none configured this is one process's Map, which is exactly right for one.
+	*/
+	const guards = createRunGuards(config.concurrency, config.kv, config.idempotency);
+	const kv = createKvStore(config.kv ?? createMemoryKv());
+	return {
+		runAction,
+		registry,
+		guards,
+		kv: (spaceId) => namespaceKv(kv, spaceId),
+		limitsFor: (document) => resolveLimits(config.limits, document.limits)
+	};
+};
+//#endregion
+export { createActionsModule, handleActionCall, handleActionCancel, handleActionCatalog, handleActionWebhook };

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

@@ -0,0 +1,3 @@
+import { ActionsModule } from './index';
+import { SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const actionsModuleFor: (config: SSRServerConfig) => ActionsModule | undefined;

package/dist/modules/actions/moduleFor.js

@@ -0,0 +1,35 @@
+import { createActionsModule } from "./index.js";
+//#region src/modules/actions/moduleFor.ts
+/**
+* The one actions module for a server, whoever asks first.
+*
+* Two places need it and they are built at different moments: the page pipeline mounts the endpoint, and the RSC
+* adapter is assembled before that to resolve `render` elements. Constructing one each would give a server two
+* guard sets — and two sets each believing they hold the only run in flight is the same as having no single-flight
+* at all.
+*
+* Memoized on the config OBJECT, which is exactly the lifetime wanted: one per `createServer` call, released with
+* it, and a fresh one per server in a test file that builds several.
+*/
+var modules = /* @__PURE__ */ new WeakMap();
+var actionsModuleFor = (config) => {
+	const lookups = config.action?.lookups;
+	if (!lookups) return;
+	const existing = modules.get(config);
+	if (existing) return existing;
+	const module = createActionsModule({
+		lookups,
+		tasks: config.action?.tasks,
+		limits: config.action?.limits,
+		concurrency: config.action?.concurrency,
+		kv: config.action?.kv,
+		rateLimit: config.action?.rateLimit,
+		idempotency: config.action?.idempotency,
+		dbDrivers: config.action?.dbDrivers,
+		onRun: config.action?.onRun
+	});
+	modules.set(config, module);
+	return module;
+};
+//#endregion
+export { actionsModuleFor };

package/dist/modules/actions/moduleFor.test.d.ts

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

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

@@ -0,0 +1,24 @@
+import { ActionDbDriver, ActionLookups, ActionTaskRegistry } from '../types';
+import { ActionCheckReport, ActionEntry } from '@plitzi/sdk-shared';
+export type ActionCheckDeps = {
+    spaceId: number;
+    registry: ActionTaskRegistry;
+    lookups: ActionLookups;
+    dbDrivers?: ActionDbDriver[];
+};
+/**
+ * What only THIS deployment can answer about an action.
+ *
+ * `validateActionDocument` reads the document and nothing else, so it catches a flow that contradicts itself — a
+ * step with no task, an output that names a step that does not exist. It cannot catch the other half, which is
+ * every way a correct document meets a server that cannot run it: a task this deployment never registered, a
+ * credential the space does not have, a key that is not in the credential it does have, a connector that was
+ * deleted, a database engine with no driver, a cron that will never fire.
+ *
+ * Those are the failures that surface at 3am on the first real delivery, and an author has no way to see them
+ * from the editor — which is why this runs on the server and answers in the same shape the validator does.
+ *
+ * It reads credentials to ask WHETHER they exist and whether they carry the key a step names. It never reports a
+ * value, and nothing here runs a step.
+ */
+export declare const checkAction: (entry: ActionEntry, deps: ActionCheckDeps) => Promise<ActionCheckReport>;

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

@@ -0,0 +1,111 @@
+import { triggerParams } from "./triggers.js";
+import { hasValidToken } from "@plitzi/sdk-shared/helpers/twigWrapper";
+import { parseCron, triggerHasStaleVerify, triggerVerify } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/runtime/check.ts
+/** A value the check can reason about: a literal the author typed, not a template resolved at run time. */
+var literal = (value) => {
+	const text = typeof value === "string" ? value.trim() : "";
+	return text && !hasValidToken(text) ? text : "";
+};
+/**
+* What only THIS deployment can answer about an action.
+*
+* `validateActionDocument` reads the document and nothing else, so it catches a flow that contradicts itself — a
+* step with no task, an output that names a step that does not exist. It cannot catch the other half, which is
+* every way a correct document meets a server that cannot run it: a task this deployment never registered, a
+* credential the space does not have, a key that is not in the credential it does have, a connector that was
+* deleted, a database engine with no driver, a cron that will never fire.
+*
+* Those are the failures that surface at 3am on the first real delivery, and an author has no way to see them
+* from the editor — which is why this runs on the server and answers in the same shape the validator does.
+*
+* It reads credentials to ask WHETHER they exist and whether they carry the key a step names. It never reports a
+* value, and nothing here runs a step.
+*/
+var checkAction = async (entry, deps) => {
+	const { spaceId, registry, lookups, dbDrivers = [] } = deps;
+	const issues = [];
+	const add = (level, path, message, hint) => issues.push({
+		level,
+		path,
+		message,
+		...hint === void 0 ? {} : { hint }
+	});
+	/** Answers once per identifier: a flow naming the same credential in four steps is one lookup, not four. */
+	const credentials = /* @__PURE__ */ new Map();
+	const credentialOf = async (identifier) => {
+		if (!credentials.has(identifier)) credentials.set(identifier, await lookups.getCredential?.(spaceId, identifier));
+		return credentials.get(identifier);
+	};
+	const checkCredential = async (node, identifier, field) => {
+		const path = `nodes.${node.id}.params.credential`;
+		const credential = await credentialOf(identifier);
+		if (!credential) {
+			add("error", path, `This space has no credential called "${identifier}"`, "Add it in Credentials, or name one that exists");
+			return;
+		}
+		if (field && !(field in credential)) add("error", path, `The credential "${identifier}" has no key called "${field}"`, `It holds: ${Object.keys(credential).join(", ") || "nothing"}`);
+		return credential;
+	};
+	const checkTrigger = async (node) => {
+		const params = triggerParams(node);
+		if (node.action === "webhook") {
+			if (triggerHasStaleVerify(params)) {
+				add("error", `nodes.${node.id}.params.signatureCredential`, "The signature check is in a format nothing reads any more, so this endpoint is refused outright", "Name the signing credential on the trigger step");
+				return;
+			}
+			const verify = triggerVerify(params);
+			if (!verify) {
+				add("warning", `nodes.${node.id}.params.signatureCredential`, "This webhook verifies nothing: anyone who learns the URL can start it", "Name the credential holding the sender’s signing secret");
+				return;
+			}
+			const credential = await credentialOf(verify.credential);
+			const field = verify.secretField ?? "secret";
+			if (!credential) {
+				add("error", `nodes.${node.id}.params.signatureCredential`, `This space has no credential called "${verify.credential}"`);
+				return;
+			}
+			if (!(field in credential)) {
+				add("error", `nodes.${node.id}.params.signatureSecretField`, `The credential "${verify.credential}" has no key called "${field}"`, `It holds: ${Object.keys(credential).join(", ") || "nothing"}`);
+				return;
+			}
+			if (!credential[field]) add("error", `nodes.${node.id}.params.signatureSecretField`, `The key "${field}" of "${verify.credential}" is empty`);
+		}
+		if (node.action === "schedule" && !parseCron(params.cron ?? "")) add("error", `nodes.${node.id}.params.cron`, `"${params.cron ?? ""}" is not an expression this server can fire`, "Five fields, UTC — minute hour day-of-month month day-of-week");
+	};
+	const checkTask = async (node) => {
+		if (!registry.get(node.action)) {
+			add("error", `nodes.${node.id}.action`, `This server registers no task called "${node.action}"`, `It offers: ${registry.list().map((entry) => entry.name).join(", ")}`);
+			return;
+		}
+		const { params } = node;
+		const connector = literal(params.connector);
+		if (connector && !await lookups.getConnector?.(spaceId, connector)) add("error", `nodes.${node.id}.params.connector`, `This space has no connector called "${connector}"`, "Add it in Connectors, or name one that exists");
+		const identifier = literal(params.credential);
+		if (!identifier) return;
+		if (node.action === "db.query") {
+			const credential = await checkCredential(node, identifier, "dsn");
+			const engine = credential?.engine ?? "";
+			if (credential && !engine) {
+				add("error", `nodes.${node.id}.params.credential`, `The credential "${identifier}" declares no engine`, "Add an `engine` key naming the database, e.g. mysql");
+				return;
+			}
+			if (engine && !dbDrivers.some((driver) => driver.engine === engine)) add("error", `nodes.${node.id}.params.credential`, `This server has no driver for "${engine}"`, dbDrivers.length > 0 ? `It drives: ${dbDrivers.map((driver) => driver.engine).join(", ")}` : "It registers no database drivers at all");
+			return;
+		}
+		await checkCredential(node, identifier);
+	};
+	for (const node of Object.values(entry.document.nodes)) {
+		if (node.type === "trigger") {
+			await checkTrigger(node);
+			continue;
+		}
+		if (node.type === "task" && node.action) await checkTask(node);
+	}
+	return {
+		valid: !issues.some((issue) => issue.level === "error"),
+		issues
+	};
+};
+//#endregion
+export { checkAction };

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

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

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

@@ -0,0 +1,11 @@
+import { ActionErrorReason } from '@plitzi/sdk-shared';
+/**
+ * A run that stopped for a reason the caller is entitled to know, as opposed to one whose step threw.
+ *
+ * Its own file so the precheck and the runner can both raise it without either importing the other — the
+ * precheck is called BY the runner and BEFORE it, and a shared error type is the only thing they have in common.
+ */
+export declare class ActionRunError extends Error {
+    reason: ActionErrorReason;
+    constructor(reason: ActionErrorReason, message: string);
+}

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

@@ -0,0 +1,17 @@
+//#region src/modules/actions/runtime/errors.ts
+/**
+* A run that stopped for a reason the caller is entitled to know, as opposed to one whose step threw.
+*
+* Its own file so the precheck and the runner can both raise it without either importing the other — the
+* precheck is called BY the runner and BEFORE it, and a shared error type is the only thing they have in common.
+*/
+var ActionRunError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "ActionRunError";
+		this.reason = reason;
+	}
+};
+//#endregion
+export { ActionRunError };

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

@@ -0,0 +1,126 @@
+import { ActionCallResult } from '@plitzi/sdk-shared';
+/**
+ * Which budget a run draws on.
+ *
+ * `call` is somebody ASKING for work — a click, a webhook, a schedule — and one space's callers hammering is a
+ * problem that belongs to that space. `render` is somebody LOOKING at a page, which is traffic: it scales with
+ * how popular the space is, and a ceiling per space would cap a successful page rather than an abusive one.
+ */
+export type RunKind = 'call' | 'render';
+/** A run currently holding a slot, and the handle that can stop it. */
+export type ActiveRun = {
+    runId: string;
+    runKey: string;
+    kind: RunKind;
+    spaceId: number;
+    actionId: string;
+    callerId: string;
+    controller: AbortController;
+    expiresAt: number;
+    /**
+     * Whether the caller NAMED this run's key rather than having it derived from what they sent.
+     *
+     * It is what decides whether the answer may be replayed: a sender that stamps a delivery id is telling us which
+     * request this is, so answering the retry with the first result is exactly right. A derived key is a hash of
+     * the input, and two identical calls a minute apart are usually two things somebody meant to happen twice.
+     */
+    explicitKey: boolean;
+};
+/**
+ * The half of a key/value store the guards need, and nothing more.
+ *
+ * The same methods `ActionKvAdapter` already declares, so a deployment that configured `action.kv` has already
+ * provided this: no second store to stand up, and no adapter change. `increment` is what takes a single-flight
+ * key; `get`/`set` are what carry a cancellation and a replayable answer between replicas.
+ */
+export type RunKeyStore = {
+    get: (key: string) => Promise<string | undefined>;
+    set: (key: string, value: string, ttlSeconds?: number) => Promise<void>;
+    increment: (key: string, amount: number) => Promise<number>;
+    expire: (key: string, ttlSeconds: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+};
+export type RunGuardsConfig = {
+    /** Concurrent CALLS one space may have in flight. Renders are not counted here — see {@link RunKind}. */
+    perSpace?: number;
+    /** Concurrent calls this process will carry, across every space. */
+    perProcess?: number;
+    /**
+     * Concurrent RENDERS this process will carry, across every space — the only ceiling renders have.
+     *
+     * What a render threatens is the box, never the space it belongs to: five hundred people reading one page at
+     * once is that page working. So this is sized for a machine, and it is the number a deployment tunes when it
+     * knows its own — the default is deliberately generous, and each slot is held for at most one run's timeout.
+     */
+    renderPerProcess?: number;
+};
+export type BeginRunParams = {
+    spaceId: number;
+    actionId: string;
+    callerId: string;
+    input: Record<string, unknown>;
+    idempotencyKey?: string;
+    /**
+     * The key names the WORK, not who asked.
+     *
+     * True only for a webhook, where the key is the SENDER's delivery id and the signature that let the request in
+     * is what authenticated it: the same delivery retried from another of a provider's addresses is the same
+     * delivery, and scoping it per caller would run it twice.
+     *
+     * Everywhere else the key is a string the caller made up, so it is scoped to them. Without that, a visitor who
+     * learns or guesses another's key collides with their single-flight and — where a deployment set a replay
+     * window — is handed the answer their run produced.
+     */
+    sharedKey?: boolean;
+    ttlMs: number;
+    /** Which budget this run draws on. Defaults to `call`: a trigger that says nothing is somebody asking. */
+    kind?: RunKind;
+};
+/** What a deployment may set about replaying a finished run. Off unless it says otherwise. */
+export type RunIdempotency = {
+    replayTtlMs?: number;
+};
+export type RunGuards = {
+    begin: (params: BeginRunParams) => Promise<ActiveRun>;
+    /** Releases the key, and — for a run the caller keyed itself — remembers the answer for {@link RunIdempotency}. */
+    end: (run: ActiveRun, outcome?: ActionCallResult) => Promise<void>;
+    get: (runId: string) => ActiveRun | undefined;
+    /** The answer a run with this key already produced, when it is still within the replay window. */
+    replay: (params: BeginRunParams) => Promise<ActionCallResult | undefined>;
+    /** Stops a run: here if this process holds it, and through the store if another one does. */
+    cancel: (runId: string, callerId: string) => Promise<boolean>;
+    active: () => number;
+};
+/**
+ * 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.
+ */
+export declare const runCancelKey: (runId: string) => string;
+export declare const deriveRunKey: ({ spaceId, actionId, callerId, input, idempotencyKey, sharedKey }: BeginRunParams) => string;
+/**
+ * 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.
+ */
+export declare const createRunGuards: (config?: RunGuardsConfig, store?: RunKeyStore, idempotency?: RunIdempotency) => RunGuards;