@plitzi/sdk-server 0.37.1 → 0.37.2

package/CHANGELOG.md

@@ -1,5 +1,151 @@
 # @plitzi/sdk-server
 
+## 0.37.2
+
+### Patch Changes
+
+- ## Authoring and agents
+  - **A step's params are templates in full.** Only a bare name (`{{ post.slug }}`) used to be recognised, so a
+    condition or a loop in a `setState` or a webhook body was handed on as its own text — a flag set to
+    `{% if … %}1{% endif %}` stored the template, a non-empty string every later check read as true. Any `{{ }}` or
+    `{% %}` in a param is now evaluated; what it resolves to is data and is not evaluated again.
+  - **Twig tests work.** `x is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd` (and `is not …`) used
+    to be read as comparisons with a variable of that name — `x is defined` answered true exactly when `x` was not
+    defined. Anything else on the right of `is` still compares.
+  - **A group takes an access chain.** `(rows|find('id', 3)).title` read the whole row; the key after the parenthesis
+    was never parsed.
+  - **An expression that chose to be empty renders empty** under `keepEmptyTokens`. A kept token is for a name still
+    waiting for a value; `{{ on ? 'active' : '' }}` said "nothing" on purpose, and handing back its text made the
+    empty branch a non-empty string.
+  - **Checkbox params written as text are booleans.** `dateConverter({ isUnix: 'false' })` read `'false'` as yes and
+    gave an ISO date back raw. Every utility's checkbox params are normalised before its callback runs.
+  - **`condition-starts-visible`** warns about a visibility computed from data on an element that starts on screen: it
+    is drawn until its provider answers and then hidden — an empty state or a "get started" card flashing past on
+    every load. `visible: false` makes it wait hidden. The export reads a visibility binding back in its place, so a
+    space whose condition is not its last binding round-trips unchanged.
+  - **A source named by its short id inside a binding's template is refused** with the full name, as it already was in
+    a flow: `{{ stats.total }}` resolved to nothing and the element showed its empty branch.
+  - **`activeOn(class, pageIds)`** marks a menu's current entry from `navigation.currentPageId` — one binding for a menu
+    kept in a layout. `variantFrom` now says `append: 'true'`, which is what it did.
+  - **Two elements with one id** name where the first one was written. **`template-never-resolved`** warns about a
+    condition left in an attribute, which only resolves `{{ name|filter }}` tokens.
+  - **The authoring skill is a folder**: `SKILL.md` plus references for layouts, data and visibility, templates,
+    flows, structure, testing and a review checklist. `plitzi create` copies all of it, and writes an `AGENTS.md`
+    (imported by `CLAUDE.md`) pointing any agent at it.
+
+  - **A new space starts on a page worth keeping.** The space `POST /spaces` and `plitzi create` both begin from is
+    redesigned: a top bar with the theme switch, a hero with two calls to action, and six guides — each a card linking to
+    its page of the docs (`https://plitzi.com/docs/…`). Every link used to be `#`, and one promised a course that does
+    not exist. The palette is a set of light/dark tokens in Geist, the guides are one list mapped to one card, and the
+    bands of the page share a `shell` class — the page is written the way the authoring skill asks a space to be.
+  - **The copy `plitzi create` writes passes its own project's lint.** An import of the package that would not fit
+    120 columns is wrapped one name per line, as the project's formatter would wrap it.
+
+  ## Server actions and scheduled jobs
+
+  **Scheduled jobs across replicas, out of the box, on the database a deployment already runs.** The scheduler and the
+  workers were already the package's; where the jobs wait was left to each deployment to write — and a queue is the part
+  that is easiest to get subtly wrong. Two helpers now build the adapters over a store the deployment owns, without the
+  package opening a connection or keeping data of its own:
+
+  - `@plitzi/sdk-server/mongo` — `createMongoJobQueue({ db })` and `createMongoKv({ db })`, over a `Db` (or a getter for a
+    client that reconnects). Creates the indexes its queries need; `mongodb` is an optional peer, used for its types.
+  - `@plitzi/sdk-server/mysql` — `createMysqlJobQueue({ pool })` and `createMysqlKv({ pool })`, over a `mysql2` pool.
+    Each job is claimed by a single-row compare-and-set, so replicas claiming at once never deadlock. Creates its three
+    tables on first use, or hands them to your own migrations through `mysqlJobSchemaStatements()`.
+
+  Every instant is the database server's, never a replica's. The in-process queue and both helpers pass one contract test
+  suite: exactly-once enqueue, atomic claims, leases that lapse and are reaped, heartbeats, settlements ignored from a
+  worker that lost its claim, refunded hand-backs, schedules advanced by compare-and-set, operator retry and cancel.
+
+  **`closeOnSignals(server, { afterClose })`** closes the server on SIGTERM/SIGINT and exits only once it has — so a
+  deploy finishes the jobs a replica is running and leaves the waiting ones for the next. A second signal exits at once.
+  Opt-in: a host with its own signal handling calls `server.close()` itself. Projects from `plitzi create` use it.
+
+  **A replica that is told to stop finishes the jobs it is running — and only those.** `server.close()` (and the job
+  worker's `stop()`) now waits for every running job to end however long past its lease that is, and keeps renewing
+  their claims while it waits. It used to stop renewing the moment the drain began and give up at the lease: a job longer
+  than its lease was taken over by another replica and run a second time while the first was still finishing it, and the
+  process exited in the middle of it. What is still waiting is not touched — it stays in the shared queue for the replica
+  that is staying or the one the deploy starts — and a job claimed in the instant the stop arrived is handed back with its
+  attempt refunded, never started. A run is bounded by its own timeout, which is the number an orchestrator's grace period
+  has to cover.
+
+  - **An every-minute schedule fired every other minute.** After producing a fire, the scheduler asked for the next
+    one from `lateness + 1 minute`, and `cronNextFire` rounds up to a whole minute — so a sweep that ran even a second
+    late (with the default 15-second sweep, nearly all of them) skipped the minute it should have produced. It now asks
+    from the minute after the one the sweep ran in. Only expressions with consecutive-minute fires were affected;
+    hourly and daily schedules were not.
+  - **A job that gives up says which step failed and why.** Its `error` and the failed attempt in its history used to
+    read "the flow ended failed" for every failure there is; they now read `step "<id>" failed: <message>`, taken from
+    the run's outline — already redacted of every credential the run resolved, so nothing reaches the job that the
+    run history would not show.
+  - **`apiContainer` takes `refreshSeconds`**: it asks again on its own every N seconds, for a page showing something
+    still moving — a queue, a feed, a status board. It is the same refresh `performQuery` runs, so it works for both
+    runtimes (a browser request is sent again; a server provider asks for its own RSC slice again). It pauses while
+    the tab is hidden and never starts a refresh while the last one is in flight. `0`, the default, never does. Before
+    this a live server provider needed a plugin element of its own to call `useRscRefresh` on a timer: `onApiSuccess`
+    never fires for a server provider, so there was no way to author the loop. The builder shows it as "Refresh every
+    (s)" for either runtime.
+  - **`onApiSuccess` / `onApiError` fire for a server provider.** The declaration offered them for every
+    `apiContainer`, but they were decided from the browser request alone — which a `runtime: 'server'` provider never
+    makes — so a flow wired to them never ran. They now fire when the provider's slice arrives (or the payload arrives
+    without it), and again on each refresh, the same as a browser refetch. A payload resolved for another page fires
+    neither. **A space that wired a flow to one of them will now see it run.**
+  - **The theme toggle shows one icon by default.** It renders both — which one is right depends on stored state, and
+    markup that depended on it would differ between the server and the browser — and until now every space had to copy
+    ten lines of `customCss` to hide the other; one that did not showed a sun and a moon side by side. The SDK's base
+    layer now shows the icon of the scheme in use, and a space's own rule still wins.
+  - **`variantFrom(cls, source)`** in `@plitzi/sdk-authoring` binds which of a CLASS's variants an element wears to a
+    value in the data — a status pill that is amber while a job waits and green once it is done. Written by hand the
+    variant key is the trap: it names the selector the variants belong to, and the element's type (`text.base`) is a
+    different selector from its class (`statusPill.base`), so the element rendered with no variant and nothing
+    reported it. The helper takes the key from the class declaration.
+  - **`authorSpace` refuses a flow template that reads a source by its short name.** A binding completes the prefix
+    (`jobRows.item.id` → `list_jobRows.item.id`), so the short form is the one an author learns first; a step's params
+    are read as written, and there it resolved to nothing — a row's button posted an empty id and every layer below
+    reported success. The error names the full source. A root that is a step of the same flow is left alone.
+  - New example, [`05-with-server-actions/05-schedules`](../examples/05-with-server-actions/05-schedules): scheduled and
+    delayed jobs on a self-hosted server, with the `ActionJobQueue` and `kv` seams written out in full over one SQLite
+    file, two replicas sharing it, failover when one is killed, and a board that watches it happen.
+
+  ## Rendering, data and styles
+  - **A server element inside a layout is resolved.** `collectServerElements` walked the page alone, so a
+    `runtime: 'server'` provider in a layout — a dashboard's sidebar, a section's header — was never resolved: the RSC
+    payload came back empty and the element rendered with nothing. It now walks the page and every shell in its layout
+    chain.
+  - **The twig `date` filter reads an epoch.** `new Date("1790143200000")` is Invalid Date, so an epoch in milliseconds
+    handed over as text — how an attribute passes one — formatted as nothing. A number, or a string of digits, is now
+    read as milliseconds.
+  - **An action is called by its name, not by its trigger kind.** `actionName` took the first trigger's title, and a
+    trigger nobody named is titled with its kind — so every rendered action in a workspace read "render" and every clock
+    "schedule". A title that only repeats the kind is no longer a name, and `defineAction` titles each trigger with the
+    action's name.
+  - **`variant` on an element that wears a class is that class's variant** when the class declares it and the type does
+    not. Keyed by the type, `text({ class: avatar, variant: 'violet' })` named `text--violet`, a selector nothing wears,
+    and rendered with no variant at all. Exporting a document back to authoring reads the same key back into `variant`.
+  - **`variantFrom` takes `{ slot, template }`**, where `template` turns a value into a variant name for data that does
+    not already speak in them — `"{{ source == 'code' ? 'on' : '' }}"`. The third argument was the slot name alone.
+  - **Entry declarations no longer alternate with `export {}`.** In `@plitzi/sdk-server` and `@plitzi/sdk-mcp` a repeated
+    `build:dev` left some `dist/<entry>.d.ts` as a ten-byte `export {}`, and consumers saw "has no exported member". The
+    cause was `insertTypesEntry` writing a types entry over the real declaration of the same path; it is gone.
+  - **Signing in keeps what a guest was doing.** `runtimeStatePersist` reset `runtime.state` whenever its owner changed,
+    and a guest becoming a user is a change — so a sign-in screen that remembered where to send somebody (`?redirect=`)
+    forgot it the moment the session arrived, and the sign-in ended on the fallback page instead. Only a change FROM an
+    account resets now: one account's state still never reaches the next, and a guest has no account to protect.
+
+  **A value with functions inside functions is written as it was given, and fast.** A CSS value was split into layers
+  at commas by a pattern that could only see one level of parentheses, so `var(--bg, light-dark(#fff, #111))` was cut at
+  its inner comma and half a function went on into the stylesheet. The half was then tokenised by an expression that
+  nested one quantifier inside another and backtracked exponentially on it — nearly two seconds for thirty characters,
+  on every generation of that selector's cache. Both are now one linear scan that splits only outside parentheses and
+  quotes. Generated caches keep the spacing the value was written with inside functions (`repeat(3, minmax(0, 1fr))`,
+  `color-mix(in oklab, oklch(…) 50%, transparent)`), where they used to drop it after the first comma.
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.37.2
+  - @plitzi/sdk-shared@0.37.2
+
 ## 0.37.1
 
 ### Patch Changes

package/README.md

@@ -1134,6 +1134,32 @@ A stage receives the `SSRContext` — the request, the config, and the render si
 **is** the decision to mount them: there is no config flag mirroring it, and a server that never passes them
 never loads them.
 
+## Scheduled jobs across replicas
+
+Server actions with a `schedule` trigger, and jobs queued for later, run with no configuration — over an in-process
+queue, which is right for one replica and wrong for two: each keeps its own schedules, and the jobs a replica holds
+leave with it. More than one replica needs a queue and a key/value store they share. They are adapters, so the jobs
+live in your database; for Mongo and MySQL they are already written, over the connection you already have:
+
+```ts
+import { closeOnSignals, createServer } from '@plitzi/sdk-server';
+import { createMongoJobQueue, createMongoKv } from '@plitzi/sdk-server/mongo';
+
+const db = mongoClient.db('app');
+const server = createServer({
+  adapters,
+  action: { lookups, kv: createMongoKv({ db }), jobs: { queue: createMongoJobQueue({ db }) } }
+});
+
+server.listen(3000);
+// On SIGTERM: finish the jobs this replica is running, leave the waiting ones for the next, then exit.
+closeOnSignals(server, { afterClose: () => mongoClient.close() });
+```
+
+`@plitzi/sdk-server/mysql` has the same pair over a `mysql2` pool (`createMysqlJobQueue`, `createMysqlKv`). Anything
+else is the `ActionJobQueue` contract written against your store — see
+[server actions § self-hosted](https://github.com/plitzi/plitzi-workspace/blob/main/docs/en/server-actions.md#13-for-a-self-hosted-deployment).
+
 ## Running it locally
 
 The package ships a small harness in [`dev/`](./dev) — file-backed adapters over a sample space, three demo

package/dist/actions.d.ts

@@ -12,18 +12,26 @@
  * Builds a runner outside a page server.
  *
  * The page server builds its own from `action.lookups`; this is for the deployment that needs to run an action
- * from somewhere else — a scheduler, a queue consumer, or the API role answering a builder's test run. Same
- * runner, same checks: a trigger that skipped them would be a weaker path to the same work.
+ * from somewhere else — a queue consumer, or the API role answering a builder's test run. Same runner, same
+ * checks: a trigger that skipped them would be a weaker path to the same work.
  */
 export { createActionsModule } from './modules/actions';
-export { createScheduleRunner } from './modules/actions/runtime/schedule';
+/**
+ * Scheduled runs: a durable queue, a leaderless producer and the workers that drain it.
+ *
+ * `createActionsModule` already assembles these from `jobs` — a deployment reaches for them directly only to run a
+ * sweep from its own cron, to build a worker in a process that serves no pages, or to hold the queue itself for an
+ * operator's panel. The in-memory queue is the default and is correct for exactly one replica.
+ */
+export { createActionJobs, createJobWorker, createMemoryJobQueue, createScheduler } from './modules/actions/jobs';
+export { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor } from './modules/actions/jobs';
 /**
  * Cron, straight from `sdk-shared`, where the parser lives because the validator needs it too.
  *
  * Re-exported HERE and nowhere in between: a deployment mounting its own scheduler reaches for one package, and
  * the file that used to sit in `runtime/` existed only so a neighbouring import could look local.
  */
-export { cronMatches, parseCron } from '@plitzi/sdk-shared/actions';
+export { cronFiresBetween, cronMatches, cronNextFire, parseCron } from '@plitzi/sdk-shared/actions';
 /**
  * What only this deployment can answer about an action, before anybody runs it: a task it does not register, a
  * credential the space has not got, a key missing from the one it has, a connector that was deleted, an engine
@@ -56,8 +64,8 @@ export { createKvStore } from './modules/actions/runtime/kvStore';
  */
 export { createRunLogger, createRejectLogger } from './modules/actions/runtime/runLogger';
 export type { TaskRegistryOptions } from './modules/actions/tasks/registry';
-export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionKvAdapter, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './modules/actions/types';
+export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionJobsConfig, ActionKvAdapter, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './modules/actions/types';
 export type { ActionsModule } from './modules/actions';
+export type { ActionJobs, JobWorker, JobWorkerOptions, MemoryJobQueueOptions, Scheduler, SchedulerOptions, SweepResult } from './modules/actions/jobs';
 export type { ActiveRun, RunGuards } from './modules/actions/runtime/guards';
-export type { ScheduleResult, ScheduleRunner, ScheduleTick } from './modules/actions/runtime/schedule';
 export type { ActionTaskDescriptor } from './modules/actions/taskCatalog';

package/dist/actions.js

@@ -1,12 +1,16 @@
+import { createMemoryJobQueue } from "./modules/actions/jobs/memoryQueue.js";
+import { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor } from "./modules/actions/jobs/schedules.js";
+import { createScheduler } from "./modules/actions/jobs/scheduler.js";
 import { ActionRunError } from "./modules/actions/runtime/errors.js";
+import { createJobWorker } from "./modules/actions/jobs/worker.js";
+import { createActionJobs } from "./modules/actions/jobs/index.js";
 import { createKvStore } from "./modules/actions/runtime/kvStore.js";
 import { DEFAULT_LIMITS } from "./modules/actions/runtime/limits.js";
 import { createMemoryKv } from "./modules/actions/runtime/memoryKv.js";
 import { createTaskRegistry, taskName } from "./modules/actions/tasks/registry.js";
 import { checkAction } from "./modules/actions/runtime/check.js";
-import { createScheduleRunner } from "./modules/actions/runtime/schedule.js";
 import { createRejectLogger, createRunLogger } from "./modules/actions/runtime/runLogger.js";
 import { describeCatalog, describeTask } from "./modules/actions/taskCatalog.js";
 import { createActionsModule } from "./modules/actions/index.js";
-import { cronMatches, parseCron } from "@plitzi/sdk-shared/actions";
-export { ActionRunError, DEFAULT_LIMITS, checkAction, createActionsModule, createKvStore, createMemoryKv, createRejectLogger, createRunLogger, createScheduleRunner, createTaskRegistry, cronMatches, describeCatalog, describeTask, parseCron, taskName };
+import { cronFiresBetween, cronMatches, cronNextFire, parseCron } from "@plitzi/sdk-shared/actions";
+export { ActionRunError, DEFAULT_LIMITS, DEFAULT_MAX_ATTEMPTS, checkAction, createActionJobs, createActionsModule, createJobWorker, createKvStore, createMemoryJobQueue, createMemoryKv, createRejectLogger, createRunLogger, createScheduler, createTaskRegistry, cronFiresBetween, cronMatches, cronNextFire, describeCatalog, describeTask, parseCron, scheduleFor, scheduleJobId, schedulesFor, taskName };

package/dist/core/server/baseServer.d.ts

@@ -4,6 +4,9 @@ export interface HttpServerParts {
     label: string;
     cache: CacheManager | null;
     plugins: PluginRegistry;
-    onDestroy?: () => void;
+    /** Started once the transport is bound: background work that should not run in a server nobody listened on. */
+    onListen?: () => void;
+    /** Awaited, so a server that holds work in flight — jobs, drains — can finish it before the sockets close. */
+    onDestroy?: () => void | Promise<void>;
 }
 export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/core/server/baseServer.js

@@ -41,10 +41,11 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 			});
 			primary.listen(port, host, () => {
 				console.log(`[${label}] ${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
+				parts.onListen?.();
 			});
 		},
 		async close() {
-			parts.onDestroy?.();
+			await parts.onDestroy?.();
 			const open = [primary, h3].filter((srv) => srv !== void 0);
 			primary = void 0;
 			h3 = void 0;

package/dist/core/server/closeOnSignals.d.ts

@@ -0,0 +1,28 @@
+/** Anything that closes the way a server from `createServer` does. */
+export type Closable = {
+    close: () => Promise<void>;
+};
+export type CloseOnSignalsOptions = {
+    /** Default `SIGTERM` (what an orchestrator sends before it replaces a replica) and `SIGINT` (^C). */
+    signals?: NodeJS.Signals[];
+    /** Runs once the server has closed: what the deployment opened itself — a pool, a client, a file — goes here. */
+    afterClose?: () => void | Promise<void>;
+};
+/**
+ * Closes the server when the process is told to stop, and only then lets the process exit.
+ *
+ * `close()` already does the waiting — the page server stops claiming jobs, finishes the ones it is running and lets
+ * go of its sockets — but nothing calls it when a deploy sends SIGTERM, and a process that simply exits leaves every
+ * running job to be retried by somebody else. This is that call, for a deployment that has no signal handling of its
+ * own. Opt in: a host that already manages its process's signals keeps doing so, and calls `close()` from there.
+ *
+ * ```ts
+ * const server = createServer(config);
+ * server.listen(3000);
+ * closeOnSignals(server, { afterClose: () => pool.end() });
+ * ```
+ *
+ * A second signal while it is closing exits at once — the ^C a person presses when waiting is not what they want.
+ * Answers a function that removes the handlers again.
+ */
+export declare const closeOnSignals: (server: Closable, { signals, afterClose }?: CloseOnSignalsOptions) => (() => void);

package/dist/core/server/closeOnSignals.js

@@ -0,0 +1,46 @@
+//#region src/core/server/closeOnSignals.ts
+/**
+* Closes the server when the process is told to stop, and only then lets the process exit.
+*
+* `close()` already does the waiting — the page server stops claiming jobs, finishes the ones it is running and lets
+* go of its sockets — but nothing calls it when a deploy sends SIGTERM, and a process that simply exits leaves every
+* running job to be retried by somebody else. This is that call, for a deployment that has no signal handling of its
+* own. Opt in: a host that already manages its process's signals keeps doing so, and calls `close()` from there.
+*
+* ```ts
+* const server = createServer(config);
+* server.listen(3000);
+* closeOnSignals(server, { afterClose: () => pool.end() });
+* ```
+*
+* A second signal while it is closing exits at once — the ^C a person presses when waiting is not what they want.
+* Answers a function that removes the handlers again.
+*/
+var closeOnSignals = (server, { signals = ["SIGTERM", "SIGINT"], afterClose } = {}) => {
+	let closing = false;
+	const onSignal = (signal) => {
+		if (closing) {
+			console.warn(`[server] ${signal} again: exiting without waiting`);
+			process.exit(1);
+			return;
+		}
+		closing = true;
+		console.info(`[server] ${signal}: finishing what is running, then exiting`);
+		(async () => {
+			try {
+				await server.close();
+				await afterClose?.();
+				process.exit(0);
+			} catch (error) {
+				console.error("[server] could not close cleanly:", error);
+				process.exit(1);
+			}
+		})();
+	};
+	for (const signal of signals) process.on(signal, onSignal);
+	return () => {
+		for (const signal of signals) process.off(signal, onSignal);
+	};
+};
+//#endregion
+export { closeOnSignals };

package/dist/core/server/pageServer.js

@@ -52,7 +52,9 @@ var createPageServer = (config, services, extensions) => {
 		label: "SSR",
 		cache,
 		plugins,
-		onDestroy: () => {
+		onListen: () => actions?.jobs?.start(),
+		onDestroy: async () => {
+			await actions?.jobs?.stop();
 			destroyServerCaches(caches);
 			pluginManager.destroy();
 		}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createServer, resolveServices } from './core/createServer';
+export { closeOnSignals } from './core/server/closeOnSignals';
 export { registerHealthCheck, buildHealthPayload } from './core/health';
 export { consoleLogger, renderLogEvent } from './helpers/serverLog';
 export type { HealthCheckApp, HealthIdentity } from './core/health';
@@ -19,4 +20,5 @@ export type { RscElementResolver, RscResolveContext, ResolveRscDataOptions } fro
 export type { ConnectorAuth, ConnectorCredential, ConnectorEndpoints, ConnectorFilter, ConnectorLookups, ConnectorManifest, ConnectorManifestDraft, ConnectorPageInfo, ConnectorPagination, ConnectorQuery, ConnectorReadEndpoint, ConnectorRecord, ConnectorResponseMapping, ConnectorResult, ProviderPagination } from './modules/connectors';
 export type { FontStore, StoredFont } from './core/fontStore';
 export type { ResolvedServices } from './core/createServer';
+export type { Closable, CloseOnSignalsOptions } from './core/server/closeOnSignals';
 export type { BaseContext, PipelineExtensions, SSRContext, Stage } from './core/http/types';

package/dist/index.js

@@ -6,6 +6,7 @@ import { createMemoryDraftStore, takeDraftOverride } from "./modules/ssr/preview
 import { resolveServices } from "./core/services/resolve.js";
 import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { createServer } from "./core/createServer.js";
+import { closeOnSignals } from "./core/server/closeOnSignals.js";
 import { consoleLogger, renderLogEvent } from "./helpers/serverLog.js";
 import { createCloudAdapters } from "./adapters/cloudAdapters.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
@@ -14,4 +15,4 @@ import { createMemoryCache, refuse } from "./adapters/space/types.js";
 import { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildcardSubdomain } from "./adapters/space/resolvers.js";
 import { createSpaceAdapters } from "./adapters/space/index.js";
 import { createLocalFontStore, hostedPathsOf } from "./core/fontStore.js";
-export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, hostedPathsOf, presentsCredential, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };
+export { PREVIEW_TOKEN_PARAM, authoringPreview, buildHealthPayload, closeOnSignals, consoleLogger, createAuthAdapters, createCloudAdapters, createConnectorResolver, createJsonAdapters, createLocalFontStore, createMemoryCache, createMemoryDraftStore, createServer, createSpaceAdapters, fetchConnectorRecords, fixedSpace, hostedPathsOf, presentsCredential, rebaseMedia, refuse, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, takeDraftOverride, verifiedDomain, wildcardSubdomain, writeConnectorRecord };

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

@@ -1,3 +1,4 @@
+import { ActionJobs } from './jobs';
 import { RunGuards } from './runtime/guards';
 import { ActionRunner } from './runtime/runAction';
 import { ActionKvStore, ActionsConfig, ActionTaskRegistry, ResolvedActionLimits } from './types';
@@ -10,6 +11,14 @@ export type ActionsModule = ActionRunner & {
     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;
+    /**
+     * Scheduled runs: the queue, the sweep that fills it and the workers that drain it.
+     *
+     * Built but NOT started — whoever owns the process decides when background work begins, and a server nobody
+     * listened on must not be quietly claiming jobs. Absent when the deployment cannot list a space's actions, since
+     * there is then no way to know what is scheduled.
+     */
+    jobs?: ActionJobs;
 };
 /**
  * The module's whole public surface: build it once from the deployment's config, then run actions through it.
@@ -24,7 +33,7 @@ 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 { createActionJobs, createJobWorker, createMemoryJobQueue, createScheduler } from './jobs';
 export { createMemoryKv } from './runtime/memoryKv';
 export { createRunLogger, createRejectLogger } from './runtime/runLogger';
 export { createTaskRegistry, taskName } from './tasks/registry';
@@ -34,8 +43,8 @@ export { handleActionCatalog } from './transport/catalogHandler';
 export { handleActionWebhook } from './transport/webhookHandler';
 export { verifySignature } from './transport/verifySignature';
 export { handleActionCancel } from './transport/cancelHandler';
+export type { ActionJobs, JobWorker, JobWorkerOptions, Scheduler, SchedulerOptions, SweepResult } from './jobs';
 export type { ActiveRun, RunGuards } from './runtime/guards';
-export type { ScheduleResult, ScheduleRunner, ScheduleTick } from './runtime/schedule';
 export type { ActionTaskDescriptor } from './taskCatalog';
 export type { TaskRegistryOptions } from './tasks/registry';
-export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './types';
+export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionJobsConfig, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './types';

package/dist/modules/actions/index.js

@@ -1,4 +1,8 @@
+import "./jobs/memoryQueue.js";
+import "./jobs/scheduler.js";
 import "./runtime/errors.js";
+import "./jobs/worker.js";
+import { createActionJobs } from "./jobs/index.js";
 import { createRunGuards } from "./runtime/guards.js";
 import { createKvStore } from "./runtime/kvStore.js";
 import { resolveLimits } from "./runtime/limits.js";
@@ -8,7 +12,6 @@ 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";
@@ -34,13 +37,16 @@ var createActionsModule = (config) => {
 	*/
 	const guards = createRunGuards(config.concurrency, config.kv, config.idempotency);
 	const kv = createKvStore(config.kv ?? createMemoryKv());
-	return {
+	const limitsFor = (document) => resolveLimits(config.limits, document.limits);
+	const module = {
 		runAction,
 		registry,
 		guards,
 		kv: (spaceId) => namespaceKv(kv, spaceId),
-		limitsFor: (document) => resolveLimits(config.limits, document.limits)
+		limitsFor
 	};
+	if (config.jobs !== false && config.lookups.listActions) module.jobs = createActionJobs(config.jobs ?? {}, module, config.lookups);
+	return module;
 };
 //#endregion
 export { createActionsModule, handleActionCall, handleActionCancel, handleActionCatalog, handleActionWebhook };

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

@@ -0,0 +1,32 @@
+import { Scheduler } from './scheduler';
+import { JobWorker } from './worker';
+import { ActionsModule } from '../index';
+import { ActionJobsConfig, ActionLookups } from '../types';
+import { ActionJobQueue } from '@plitzi/sdk-shared';
+export type ActionJobs = {
+    queue: ActionJobQueue;
+    scheduler: Scheduler;
+    worker: JobWorker;
+    start: () => void;
+    stop: () => Promise<void>;
+};
+/**
+ * The scheduling half of actions: a producer, a consumer and the store they meet in.
+ *
+ * Both halves run in EVERY replica by default, and neither needs to know about the others. The producer is safe to
+ * duplicate because a fire's job id is the fire's own instant; the consumer is safe to duplicate because a claim is
+ * atomic. What a deployment tunes is how many jobs each replica carries (`workers`) and whether it produces at all
+ * — a pod dedicated to running jobs sets `produce: false`, a pod serving pages sets `workers: 0`.
+ *
+ * With no `queue` supplied this is one process's memory, which is right for a single replica and wrong the moment
+ * there are two. That is a sentence rather than a silent behaviour because the failure is invisible: everything
+ * works, and the nightly email goes out once per replica.
+ */
+export declare const createActionJobs: (config: ActionJobsConfig, module: ActionsModule, lookups: ActionLookups) => ActionJobs;
+export { createMemoryJobQueue } from './memoryQueue';
+export { createScheduler } from './scheduler';
+export { createJobWorker } from './worker';
+export { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor } from './schedules';
+export type { MemoryJobQueueOptions } from './memoryQueue';
+export type { Scheduler, SchedulerOptions, SweepResult } from './scheduler';
+export type { JobWorker, JobWorkerOptions } from './worker';

package/dist/modules/actions/jobs/index.js

@@ -0,0 +1,57 @@
+import { createMemoryJobQueue } from "./memoryQueue.js";
+import { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor } from "./schedules.js";
+import { createScheduler } from "./scheduler.js";
+import { createJobWorker } from "./worker.js";
+//#region src/modules/actions/jobs/index.ts
+/**
+* The scheduling half of actions: a producer, a consumer and the store they meet in.
+*
+* Both halves run in EVERY replica by default, and neither needs to know about the others. The producer is safe to
+* duplicate because a fire's job id is the fire's own instant; the consumer is safe to duplicate because a claim is
+* atomic. What a deployment tunes is how many jobs each replica carries (`workers`) and whether it produces at all
+* — a pod dedicated to running jobs sets `produce: false`, a pod serving pages sets `workers: 0`.
+*
+* With no `queue` supplied this is one process's memory, which is right for a single replica and wrong the moment
+* there are two. That is a sentence rather than a silent behaviour because the failure is invisible: everything
+* works, and the nightly email goes out once per replica.
+*/
+var createActionJobs = (config, module, lookups) => {
+	const queue = config.queue ?? createMemoryJobQueue();
+	const { produce = true, workers = 4 } = config;
+	const scheduler = createScheduler({
+		queue,
+		lookups,
+		...config.environment ? { environment: config.environment } : {},
+		...config.schedulePollMs ? { pollMs: config.schedulePollMs } : {},
+		...config.maxAttempts ? { maxAttempts: config.maxAttempts } : {},
+		...config.reconcileMs ? { reconcileMs: config.reconcileMs } : {},
+		...config.spaces ? { spaces: config.spaces } : {},
+		...config.onError ? { onError: config.onError } : {}
+	});
+	const worker = createJobWorker({
+		queue,
+		lookups,
+		module,
+		workers,
+		...config.pollMs ? { pollMs: config.pollMs } : {},
+		...config.leaseMs ? { leaseMs: config.leaseMs } : {},
+		...config.backoff ? { backoff: config.backoff } : {},
+		...config.workerId ? { workerId: config.workerId } : {},
+		...config.onError ? { onError: config.onError } : {}
+	});
+	return {
+		queue,
+		scheduler,
+		worker,
+		start: () => {
+			if (produce) scheduler.start();
+			worker.start();
+		},
+		stop: async () => {
+			scheduler.stop();
+			await worker.stop();
+		}
+	};
+};
+//#endregion
+export { DEFAULT_MAX_ATTEMPTS, createActionJobs, createJobWorker, createMemoryJobQueue, createScheduler, scheduleFor, scheduleJobId, schedulesFor };

package/dist/modules/actions/jobs/memoryQueue.d.ts

@@ -0,0 +1,30 @@
+import { ActionJobQueue } from '@plitzi/sdk-shared';
+export type MemoryJobQueueOptions = {
+    /**
+     * How many finished jobs to keep before the oldest are dropped.
+     *
+     * A bound rather than a retention period, because this store has no eviction of its own and an unbounded history
+     * in a long-lived process is a leak with a nice name. A deployment that wants jobs it can still read next week
+     * supplies a queue backed by something that survives a restart.
+     */
+    retainFinished?: number;
+    /**
+     * What this queue calls now, in epoch ms.
+     *
+     * The seam that makes a lease, a backoff and an overdue schedule testable without waiting for one — and the
+     * shape of the rule a shared store keeps too: everything here reads ONE clock, and it is the store's.
+     */
+    clock?: () => number;
+};
+/**
+ * The default queue: one process's Maps.
+ *
+ * Correct for a deployment that runs ONE replica, which is most self-hosted ones, and honest about the rest — a
+ * second replica running on this gets its own schedules and its own jobs, so a nightly digest goes out twice. The
+ * cure is any store the replicas share, behind the same {@link ActionJobQueue} seam.
+ *
+ * It keeps the contract exactly, rather than approximately: enqueue is idempotent by id, a claim reaps lapsed
+ * leases, and every instant is read here rather than accepted from a caller. A test that passes against this one
+ * is testing the rules a shared store has to keep too.
+ */
+export declare const createMemoryJobQueue: ({ retainFinished, clock }?: MemoryJobQueueOptions) => ActionJobQueue;