@plitzi/sdk-server 0.33.2 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @plitzi/sdk-server
 
+## 0.34.0
+
+### Minor Changes
+
+- v0.34.0
+- 5aceda0: Draft previews you can iterate against, and a `DraftStore` contract that says so.
+
+  A preview token was one-shot: spent by the render that used it. That is right for a capture and wrong for a
+  person — reloading showed the saved space again, so "look at the change, adjust it, look again" meant minting a
+  new token for every look. `POST /__preview` now takes `mode: 'session'`, which mints a token that stays
+  resolvable until it expires (`preview.sessionTtlMs`, 15 minutes by default) or until `POST /__preview/end` ends
+  it. The token is remembered in an `HttpOnly` cookie on the first render, so the draft follows a navigation —
+  the page after a link carries no query parameter.
+
+  A draft render, either mode, is never cached, never metered and answers `Cache-Control: no-store` plus
+  `X-Robots-Tag: noindex`. Data refreshes (`/_rsc`) made from inside a session are excluded from metering and
+  caching too — without that, an open preview tab would be billed as live traffic.
+
+  **Breaking, for anyone who implements `DraftStore`** (a shared store for a multi-replica deployment). The
+  default in-memory store is unaffected; a custom one needs three changes:
+
+  ```ts
+  // before
+  put(token, data, ttlMs)
+  take(token): OfflineDataRaw | undefined
+
+  // after
+  put(token, data, { ttlMs, reusable })      // `reusable` is a session; absent is one-shot
+  take(token): { data, reusable } | undefined // consume unless reusable — and say which it was
+  drop(token)                                 // end a session before its TTL
+  ```
+
+  `take` reports which kind it resolved because the render that resolves a session is the one that has to remember
+  it for the rest of the visit, and only the store knows whether the token survived the read.
+
+### Patch Changes
+
+- Updated dependencies [5aceda0]
+- Updated dependencies
+- Updated dependencies [5aceda0]
+- Updated dependencies [9c3292c]
+  - @plitzi/sdk-shared@0.34.0
+  - @plitzi/plitzi-sdk@0.34.0
+
 ## 0.33.2
 
 ### Patch Changes

package/README.md

@@ -38,6 +38,120 @@ createServer({
 });
 ```
 
+## Your first space
+
+A page server needs a **space** to serve, and there are two ways to get one: export it from the Plitzi builder, or
+write it yourself. This is the second one, whole — one file, no account, no API key, no JSON:
+
+```bash
+yarn add @plitzi/sdk-authoring   # writing spaces is its own package, and it installs nothing else
+```
+
+```ts
+// server.ts
+import { authorSpace, container, heading, link, text } from '@plitzi/sdk-authoring';
+import { consoleLogger, createJsonAdapters, createServer } from '@plitzi/sdk-server';
+
+/** A space is a tree, some CSS and a palette. Ids, class names and the breakpoint maps are derived from it. */
+const space = authorSpace({
+  name: 'My space',
+  permanentUrl: 'my-space',
+
+  variables: { color: { ink: { light: '#17171c', dark: '#fafafa', default: '#17171c' } } },
+
+  // Rules written once and named. An element reaches one with `class`.
+  classes: {
+    page: {
+      desktop: {
+        display: 'flex',
+        'flex-direction': 'column',
+        'align-items': 'center',
+        gap: '16px',
+        padding: '96px 24px',
+        'font-family': 'system-ui, sans-serif',
+        color: 'var(--ink)'
+      }
+    },
+    card: { desktop: { 'border-radius': '12px', border: '1px solid #e4e4e7', padding: '24px' } }
+  },
+
+  pages: [
+    {
+      name: 'Home',
+      slug: '',
+      class: 'page',
+      body: [
+        heading('Hello from my own server', { subType: 'h1' }),
+        container({
+          class: 'card',
+          children: [text('This page is a document. Nothing here was compiled.'), link({ href: '/about' })]
+        })
+      ]
+    },
+    { name: 'About', slug: 'about', class: 'page', body: [heading('About', { subType: 'h1' })] }
+  ]
+});
+
+/** Where the server gets a space from. Hand it the documents and it fills in the reads a page server needs; a
+ *  real deployment swaps this for adapters that hit its own database, and the server never learns the difference. */
+const server = createServer({
+  port: 3001,
+  devMode: true,
+  adapters: createJsonAdapters({ offlineData: space }),
+  logger: consoleLogger
+});
+
+server.listen(3001, '127.0.0.1');
+```
+
+```bash
+yarn add @plitzi/sdk-server react react-dom
+yarn tsx server.ts     # http://127.0.0.1:3001/
+```
+
+Both pages render server-side, with the CSS the space declared. `authorSpace` refuses to hand back a space that
+would not render — a CSS property the style editor could not read back, a class nothing declares, a binding
+pointing at an element that is not there — so a mistake is an error at the line that made it rather than a blank
+section in production.
+
+**Shorthands are fine.** `padding: '96px 24px'` and `border: '1px solid #e4e4e7'` above are expanded into the
+atomic longhands Plitzi's style editor reads back, so a space written the way anyone writes CSS still opens in the
+builder.
+
+Everything else — data on the server, sessions, an agent editing the space, work the server runs — is the same
+space with more declared in it. The full surface (element factories, bindings, flows, validation) is in
+**[Authoring spaces](https://github.com/plitzi/plitzi-workspace/blob/main/docs/en/authoring-spaces.md)**, and
+there are runnable versions of each step in
+[`examples/`](https://github.com/plitzi/plitzi-workspace/tree/main/examples).
+
+### Working with an agent
+
+This package ships an [Agent Skill](https://agentskills.io/) for authoring, because an agent in your project sees
+only what npm installed — not this repository. It teaches the declaration, the flat prop model, the binding and
+flow builders, and the mistakes the validator refuses, so an agent writes a space instead of reconstructing schema
+JSON from memory. It is `@plitzi/sdk-authoring`'s file, shipped here as well so a server has it without installing
+anything else:
+
+```bash
+cp -R node_modules/@plitzi/sdk-server/skills/plitzi-authoring ~/.claude/skills/
+```
+
+It installs the same way into any agent that reads a `SKILL.md` (Claude Code, VS Code / Copilot, Codex, Gemini
+CLI, Cline, Goose). Everything it defers to is in the package too: every factory, spec field and step builder
+carries its documentation in the published `.d.ts`, so hovering a call or reading
+`node_modules/@plitzi/sdk-authoring/dist/index.d.ts` answers what an attribute takes without leaving the project.
+
+### Already have a space?
+
+An export from the builder is a `{ schema, style }` JSON and goes in the same door:
+
+```ts
+adapters: createJsonAdapters({ offlineData: './space.json' })
+```
+
+`validateSpace({ schema, style })` from `@plitzi/sdk-authoring` answers whether one is servable before you
+serve it — worth running over anything that arrives as a file.
+
 ## Configuration
 
 | Option | Type | Default | Description |
@@ -97,6 +211,57 @@ type SSRAdapters = {
 - **`endSession`** *(optional)* — called when `POST {logoutPath}` is received. Revoke the session at the source; the server clears the cookies. Clearing them alone would leave the credential itself working for anyone who had already copied it. A navigation receives a `303` redirect; a fetch receives `204 No Content`.
 - **`getRscData`** *(optional)* — called by the RSC endpoint (`/_rsc`), and once per page render, to fetch server-side data for schema elements with `runtime: 'server'`. Takes one `SSRRscContext`: the request, the space context, the resolved user so authenticated operations are safe, `ids` on a partial refresh (absent means every element), and `loadOfflineData`. That last one is the space itself, shared with the page render happening alongside — await it instead of fetching the schema again, and it is read once per request however many callers ask. Return `{}` when there is no server data for the current request (see [RSC](#react-server-components-rsc)).
 
+## Space adapters (a space per domain)
+
+`getSpaceDeployment` looks like glue and is not: the same handful of rules turn up in every deployment that serves
+more than one space, and getting any of them wrong is a real failure. `createSpaceAdapters` states them once and
+asks you only for the lookups.
+
+```ts
+import { authoringPreview, createSpaceAdapters, verifiedDomain, wildcardSubdomain } from '@plitzi/sdk-server';
+
+const spaces = createSpaceAdapters({
+  resolvers: [
+    authoringPreview({ hosts: platformHosts, resolveGrant: auth.identity.resolveGrant, find: findSpace }),
+    wildcardSubdomain({ suffix: 'example.app', find: findSpaceBySlug }),
+    verifiedDomain(findDeploymentByDomain)
+  ],
+  cache: redisCache,
+  frameAncestors: { find: findSpaceDomains, floor: platformHosts, cache: true },
+  decorate: resolution => Promise.resolve({ pluginNames: pluginsFor(resolution.spaceId) })
+});
+
+createServer({ adapters: { ...spaces.adapters, getOfflineData } });
+```
+
+**Resolvers are an ordered list**, and the order is the policy. Each returns a resolution, a refusal, or nothing —
+and the difference between the last two is the point: a refusal ENDS the chain, so a request that tried to act for
+a space and failed is never quietly served as an anonymous visitor of whatever else that host resolves to. Three
+are built in and a fourth is `(req) => …` of your own, which is how a deployment that identifies tenants by header,
+by path prefix or by a table nobody else has still gets everything below.
+
+| Built in | What it is |
+|---|---|
+| `authoringPreview` | An author looking at their own space through a builder, on a host you own. Marks the render `authoring` so metering skips it. Put it first. |
+| `wildcardSubdomain` | `<slug>.example.app`, with no per-space row to configure. Refuses to read a deeper sub-domain as a slug. |
+| `verifiedDomain` | A custom domain, through a row that says it was proven. |
+| `fixedSpace` | Always this one — a single-space deployment, or a catch-all last in the chain. |
+
+What it decides for you:
+
+- **A credentialed request is never served from, nor written to, the shared cache.** It is keyed by host, and a
+  credential resolves the same host to a different space — so a hit would serve one author's preview to the next.
+- **`frame-ancestors` is derived on every resolution**, from the domains the space declared plus your floor.
+  Deriving it per branch is how a deployment ends up with one branch that forgets, and that branch serves a space
+  framable by anyone.
+- **Refusals are not cached**, so fixing a row fixes the site rather than fixing it in five minutes.
+- **A resolver that throws is a 404 for that request**, reported through `onError`, not a dead server.
+
+`cache` is any `get`/`set`/`delete` of strings — Redis, Memcached, whatever you have — or `createMemoryCache()` for
+a single-process deployment. `invalidate.resolution(host)` and `invalidate.domains(spaceId)` drop what a change made
+untrue, which matters the moment an owner edits a domain list: until then the old framing policy stands, and a TTL
+is not a security boundary.
+
 ## JSON adapters (offline mode)
 
 `createJsonAdapters` provides a ready-made adapter set that reads a space from local JSON files, useful for offline mode, integration tests, and static deployments.
@@ -497,13 +662,13 @@ Enable RSC at the top level of your schema:
 | `'client'` | Skipped during SSR; rendered only in the browser after hydration. |
 | `'shared'` | Rendered on both server and client (default behaviour). |
 
-**`loadStrategy`** — controls when the browser requests the element's data (schema field; browser runtime behaviour is handled by the SDK):
+**`loadStrategy`** — controls when an element's items are mounted, relative to its `visibility` state. The element itself always renders (it is what registers the callbacks that show it again); only what is inside it is deferred. The builder canvas ignores it and keeps everything mounted.
 
 | Value | Behaviour |
 |---|---|
-| `'eager'` | Data fetched immediately on mount. |
-| `'lazy'` | Data fetched after the initial render completes. |
-| `'visible'` | Data fetched when the element enters the viewport. |
+| `'eager'` | Items always mounted, hidden or not (default behaviour). |
+| `'lazy'` | Items mounted the first time the element is shown, and kept from then on. `modalContainer` and `dialogContainer` declare it by default. |
+| `'visible'` | Items mounted only while the element is shown; their state is dropped on every hide. |
 
 ### `getRscData` adapter
 
@@ -650,18 +815,23 @@ cookies, and the store your accounts live in — and returns the whole cycle wir
 
 ```ts
 import { createServer } from '@plitzi/sdk-server';
-import { createAuth } from '@plitzi/sdk-server/kernel';
+import { createAuth } from '@plitzi/sdk-server/auth';
 
 const auth = createAuth({
   tokens: { secret: process.env.AUTH_SECRET, issuer: 'https://acme.com', audience: ['https://acme.com'] },
   cookie: { name: 'acme_session' },
-  adapters: accounts,
-  api: { verifyPassword }
+  adapters: accounts
 });
 
 createServer({ port: 443, adapters: { getOfflineData, getSpaceDeployment }, auth });
 ```
 
+There is no third argument for the security-relevant parts, on purpose: password hashing defaults to scrypt, sign-in
+is rate-limited in memory, mailed links expire, and CSRF is on. Each of those used to be an option with no default —
+which meant the ordinary deployment went without, because nobody configures what they have not read about. Supply
+`api.hashPassword`/`verifyPassword` to keep an existing algorithm (a store of bcrypt hashes needs bcrypt), and
+`api.rateLimit` to put one counter behind a fleet.
+
 `auth` on the server is the whole of the wiring: it mounts the `/auth` flows, answers the identity adapters a page
 server asks for, and carries the cookie naming with it — so there is no second place to keep in step. Everything is
 still exported separately (`createTokens`, `createIdentity`, `createAuthApi`, `authRoutes`, …) for a deployment that
@@ -730,6 +900,30 @@ Postgres, MySQL, Mongo or an identity service:
 rather than failing at runtime. Declining a flow is one act: do not implement it. `GET /auth/capabilities` publishes
 the result, so a sign-in page renders what the backend actually answers instead of a button that dead-ends.
 
+### …or don't: `@plitzi/sdk-server/mysql`
+
+If you are standing a user store up rather than adapting one you have, the table above is ceremony. Import the
+store instead — it is every adapter in it, already written, over tables it creates:
+
+```ts
+import { createMysqlStore } from '@plitzi/sdk-server/mysql';
+
+const store = await createMysqlStore({ url: process.env.DATABASE_URL });
+
+const auth = createAuth({
+  tokens: { secret, issuer },
+  adapters: store.authAdapters,   // spread your own on top: { ...store.authAdapters, sendMail }
+});
+```
+
+It connects to a MySQL server; it does not start one. `store.admin` seeds the roles, permissions and memberships
+that no request creates. `mysql2` is an optional peer dependency, since this is the only part of the package that
+touches a database.
+
+The tables, the contract they satisfy, and the four traps that fail somewhere other than where they were caused
+are in [`docs/auth/mysql-schema.md`](./docs/auth/mysql-schema.md) — worth reading even if you are mapping your own
+schema, because it is written as the set of questions your adapters have to answer.
+
 ### What you get
 
 `POST /auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/sessions/revoke`, `/auth/exchange`, `GET /auth/session`,
@@ -737,6 +931,18 @@ the result, so a sign-in page renders what the backend actually answers instead
 sign-out also answer a full-page form submission with a `303` so the view re-renders, which a `fetch` client does
 not need and a `<form>` does.
 
+**Changing an email is a confirmation, not a write.** Supply `setPendingEmail` / `findByPendingEmail` /
+`clearPendingEmail` (the MySQL store has them) and `POST /auth/profile` parks the new address instead of applying
+it: the account keeps signing in with the old one until `POST /auth/confirm-email` proves somebody reads the new
+one, which also marks it verified. A typo then costs a resend rather than the account. Leave them out and the
+address changes on the spot, as before.
+
+**Impersonation is off until you name its permission.** With `api.impersonationPermission` set,
+`POST /auth/admin/impersonate` answers a session as another account — one that carries `act` (RFC 8693) so every
+request made with it is distinguishable from the account holder's, lives fifteen minutes, cannot renew, and is
+returned in the body rather than written over the administrator's own cookie. `Actor.impersonatedBy` is that claim
+read back, and `GET /auth/session` reports it.
+
 Behaviour you do not have to get right yourself: the credential is renewed ahead of expiry and rotated when it is;
 signing out revokes at the source rather than only clearing the browser's copy; a readable hint cookie rides beside
 the session carrying nothing but expiry timestamps, so a page can tell that nobody is signed in without a request;
@@ -747,12 +953,81 @@ and every refusal names a machine-readable `reason`, so a client can tell "renew
 | Config | Effect |
 |---|---|
 | `cookie` | Name, domain, `SameSite`, `Secure`, the refresh path, the hint suffix. Defaults derive from the request host |
+| `api.password` | What a password has to be. `minLength` defaults to 8 (NIST SP 800-63B's floor); `validate` is where a breach-list lookup or a strength estimator goes. Applied wherever one is set — signing up, resetting, changing |
+| `api.rateLimit` | May this attempt proceed? **Defaults to an in-memory sliding window**, so no deployment is unthrottled by omission; supply one to put a single counter behind a whole fleet. Called before the password is checked, so a throttled attempt costs no hash |
+| `api.adminPermission` | The global capability the `/auth/admin/*` routes require. Default `userManage` |
+| `api.impersonationPermission` | The capability it takes to obtain a session **as** another account, and the switch that offers the flow at all — **absent, there is no impersonation**. Its own permission on purpose: suspending an account and becoming one are not the same grant |
+| `api.onEvent` | Every act worth recording — sign-ins, failures, password changes, admin actions — as a `SecurityEvent`. An audit trail, a webhook and an alert are the same feed. Never awaited and never able to fail a request |
+| `api.mfaIssuer` | What an authenticator app calls this deployment. Defaults to the token issuer |
+| `tokens.lifetimes.session` | The longest a session may live however often it renews. `0` (default) means no cap — the renewal window is already an idle timeout, since a session nobody refreshes dies with its refresh token |
+| `api.onMailError` | Where a failed delivery is reported. It is never thrown: every one of these sends after something has already been committed, so letting the provider decide whether the request succeeded reports a change that did happen as a 500 |
 | `basePath` | Where the flows are mounted. The guard's rules follow it |
 | `rules` / `fallback` | Extra authorization rules, applied before the derived ones, and what an unlisted path requires |
 | `identity` | Your own hosts and origins — the floor for domain binding and framing |
 | `tokens.lifetimes` | How long each credential lives |
 
-A working example is [`examples/02-with-users`](../../examples/02-with-users).
+Working examples are in [`examples/02-with-users`](../../examples/02-with-users): `01-sessions` over a store you
+write, `02-mysql` over one you do not.
+
+### Cross-site request forgery
+
+**On by default.** The session cookie defaults to `SameSite=None` off localhost — a space is embedded in an iframe
+on somebody else's domain — so the browser attaches it to requests another site caused. That is the attack, and
+`Lax` is what would otherwise prevent it.
+
+Two requests can never be forged into whatever they are reaching, and neither is ever asked for a token:
+
+| Never asked | Why |
+|---|---|
+| `GET`, `HEAD`, `OPTIONS` | They change nothing |
+| Anything with `Authorization: Bearer` | A cross-origin page cannot set that header without a preflight you would have to allow. **Every API client is unaffected** |
+
+After that it depends on what the flow does, because there are two different attacks:
+
+| Flow | Guarded by | Because |
+|---|---|---|
+| **An action taken as somebody** — profile, password, sessions, admin | A token, whenever a **session cookie** is present | The attack is the browser attaching the victim's credentials. No cookie, nothing to forge |
+| **A sign-in** — login, signup, the password-reset pair, the passwordless and MFA halves, `confirm-email` | A token, whenever the request came from **a site this deployment does not recognise** | There is no cookie to protect yet. The attack is login CSRF: another site signing a visitor into an account *it* controls. What separates that from a legitimate sign-in is not a cookie — it is where the request came from |
+| **`/auth/exchange`** | Its own grant | It acts for a space and is already refused unless the origin is one that space declared — narrower than any list here. A space is embedded on somebody else's domain by design |
+| **`/auth/refresh`, `/auth/logout`** | Nothing | Both authenticate with the refresh credential and must work when the access token has lapsed. Forging either gains an attacker nothing: renewing somebody's session hands the new credential to their own browser |
+
+**"A site this deployment recognises"** is decided by two headers a page cannot set: `Sec-Fetch-Site` — the
+browser's own account of where the request came from — and, where that is absent, `Origin`, matched exactly against
+this host or `identity.platformOrigins`, the hosts you already declared. **Neither header present means the caller
+is not a browser**, and a client that is not a browser has no victim's session in it to forge with — which is what
+lets every API client, mobile app and script sign in with nothing extra to send.
+
+#### What a browser client does
+
+```js
+// Once, or whenever a write is refused with 403 and reason "mismatch".
+const { token } = await (await fetch('/auth/csrf', { credentials: 'include' })).json();
+
+await fetch('/auth/profile', {
+  method: 'POST',
+  credentials: 'include',
+  headers: { 'content-type': 'application/json', 'x-csrf-token': token },
+  body: JSON.stringify({ email })
+});
+```
+
+The same token is also written to a **readable cookie** (`<session cookie>_csrf`), so a page that would rather read
+it out of `document.cookie` than call an endpoint can. A `<form>` without JavaScript posts it as `_csrf` instead.
+
+**Signing in re-issues it.** The token a signed-out page held is bound to nobody, and every write it attempted
+afterwards would be refused — so the grant that creates a session writes a fresh cookie bound to it. A client that
+re-reads the cookie after signing in never notices this exists.
+
+#### Why it is a signed token and not just a matching cookie
+
+Plain double-submit compares a cookie to a header, which fails against anyone who can *write* a cookie — a
+sub-domain they took over. Here the token is an HMAC over a nonce **and the session it belongs to**, so forging one
+needs the secret, and a token minted for one session is refused for another. A refusal always names a `reason`:
+`missing`, `malformed`, `expired` or `mismatch`.
+
+There is nothing to configure: the secret, the cookie scope and the origins all come from what you already told
+`createAuth`. Turn it off entirely with `csrf: false`. Outside this package, `createCsrfMiddleware` from
+`@plitzi/sdk-server/handlers` applies the same check to your own routes.
 
 ### `SSRUser`
 

package/dist/actions.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Server actions, for the deployment that supplies them.
+ *
+ * Its own entry, and not part of the barrel, for the same reason `mysql` is: what a deployment needs here is the
+ * task contract and the run types, and reaching for them through the package root would load the whole render
+ * path to get at a type. A page server that runs no actions never touches this file.
+ *
+ * The server builds the module itself from `action.lookups` — that is not a deployment's call — so what is
+ * exported is what a deployment writes AGAINST: its own tasks, and the shapes its lookups must answer.
+ */
+/**
+ * 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.
+ */
+export { createActionsModule } from './modules/actions';
+export { createScheduleRunner } from './modules/actions/runtime/schedule';
+/**
+ * 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';
+/**
+ * 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
+ * with no driver, a cron that will never fire. The document validator in `sdk-shared` catches the other half.
+ */
+export { checkAction } from './modules/actions/runtime/check';
+export type { ActionCheckDeps } from './modules/actions/runtime/check';
+export { ActionRunError } from './modules/actions/runtime/errors';
+export { DEFAULT_LIMITS } from './modules/actions/runtime/limits';
+export { createTaskRegistry, taskName } from './modules/actions/tasks/registry';
+export { describeCatalog, describeTask } from './modules/actions/taskCatalog';
+/**
+ * The `kv` seam: an ADAPTER a deployment fills, and the logic that sits on top of it.
+ *
+ * There is deliberately nothing here that talks to a store — no Redis, no database, no client of any kind. A
+ * deployment passes five string operations over whatever it already runs, and `createKvStore` supplies everything
+ * that decides how a counter behaves, so the rule a rate limit depends on is written once rather than once per
+ * deployment. The in-process Map is the same shape, which is why the default and a cluster's store behave
+ * identically instead of nearly so.
+ */
+export { createMemoryKv } from './modules/actions/runtime/memoryKv';
+export { createKvStore } from './modules/actions/runtime/kvStore';
+/**
+ * `onRun` and `onReject` for a deployment that wants to SEE its flows without building somewhere to keep them: a
+ * run — and a request that never became one — becomes one more event on the log stream the server already
+ * reports through.
+ *
+ * The two are separate hooks because they are separate questions. A deployment that keeps run history in a table
+ * and still wants refusals on the log stream wires one of each; that is the normal shape, not a workaround.
+ */
+export { createRunLogger, createRejectLogger } from './modules/actions/runtime/runLogger';
+export type { ActionCredential, ActionDbDriver, 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 { 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

@@ -0,0 +1,12 @@
+import { ActionRunError } from "./modules/actions/runtime/errors.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 };

package/dist/adapters/cloudAdapters.d.ts

@@ -0,0 +1,72 @@
+import { Environment, SSRPageAdapters, SSRSpaceDeployment } from '@plitzi/sdk-shared';
+/**
+ * Where a fetched space is kept between requests. Five operations over strings, with no rule to obey — Redis, a
+ * table, a directory, whatever this deployment already runs.
+ *
+ * Omitted leaves an in-process Map, which is per replica: five replicas mean five copies and five refreshes per
+ * window. Sharing one costs the cloud a single fetch per version no matter how many of them there are, and it
+ * survives a restart — which is what keeps a cold deploy from asking Plitzi once per replica.
+ */
+export type CloudSpaceCache = {
+    get: (key: string) => Promise<string | undefined>;
+    set: (key: string, value: string) => Promise<void>;
+};
+export type CloudAdaptersConfig = {
+    /** The GraphQL endpoint of the Plitzi server role. Defaults to production. */
+    serverUrl?: string;
+    /**
+     * The space's **host** key, which is what says WHICH space: the token is minted for one, so no space id travels
+     * here and none can be asked for by guessing a number.
+     *
+     * This is NOT the public render key that a published page embeds. It is issued separately, shown once, and must
+     * stay secret — see {@link assertHostKey} for why the public one is refused here rather than being allowed to
+     * work.
+     */
+    webKey: string;
+    /**
+     * Which environment to serve. `main` is the live document the builder is editing; anything else is published.
+     *
+     * This is the single switch between the two modes below, and it is worth being deliberate about: `main` is a
+     * development target and a published environment is a production one.
+     */
+    environment?: Environment;
+    /**
+     * Which published revision to serve. **Ignored when `environment` is `main`** — the live document has no
+     * revisions, it has whatever the builder last saved.
+     *
+     * Pinned to a number, this deployment serves that exact version until somebody changes the config: a revision
+     * cannot change, so it is fetched once and kept for the life of the process. That is what a deployment wants
+     * when it rolls forward on its own schedule, or when it has to be able to say precisely what it is serving.
+     *
+     * Left out, it serves the **latest** revision of that environment and notices when a new one is published: a
+     * cheap probe every `cacheSeconds` asks which revision is current, and the space is refetched only when the
+     * answer changes. Publishing from the builder is then all it takes to release.
+     */
+    revision?: number;
+    /**
+     * How often Plitzi is ASKED anything, in seconds. Default a minute. Ignored in both directions at the edges:
+     *
+     * - `main` **does not cache at all**. It is the document somebody is actively editing, and an edit that shows
+     *   up a minute later is worse than the round trip — every request reads it live. (Concurrent requests still
+     *   share one in-flight fetch: that is not caching, it is not asking the same question twice at once.)
+     * - A **pinned revision** never expires. Expiring an immutable document on a timer would be paying for a
+     *   question whose answer is already known.
+     *
+     * So this paces exactly one thing: the "which revision is current" probe, in latest mode. Even then it never
+     * sits in front of a visitor — the copy already held is served while the probe runs behind it.
+     */
+    cacheSeconds?: number;
+    /** Where fetched spaces are kept. Omitted, they are kept in this process only — see {@link CloudSpaceCache}. */
+    cache?: CloudSpaceCache;
+    /**
+     * What this server calls the space locally — the number every per-space thing here is keyed by (its actions, its
+     * cache entries, its logs). It is NOT Plitzi's id and does not have to match one: the key already says which
+     * space is being read, and a deployment serving one space has one number to choose.
+     */
+    spaceId?: number;
+    /** Who may frame this space, and whether a render counts as authoring. Passed through to the page server. */
+    deployment?: Omit<SSRSpaceDeployment, 'spaceId' | 'environment' | 'revision'>;
+    fetchImpl?: typeof fetch;
+};
+export declare const createCloudAdapters: (config: CloudAdaptersConfig) => SSRPageAdapters;
+export default createCloudAdapters;