@mosetta/server-action 0.0.0-stage → 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mosetta contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @mosetta/server-action
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server actions of the mosetta protocol: server code that ships with a tile and is called from its
+component side.
+
+A tile's server side declares actions. Every action says who may call it (`authorize`), what it
+takes (a zod schema) and what it does; the host vouches for the caller, the action decides:
+
+```ts
+// tiles/greeting/greeting.server.ts
+import { ServerActionToken } from '@mosetta/server-action/core';
+import { DiServerAction, defineServerSide, ServerAction } from '@mosetta/server-action/server';
+import type { ICreateSchema, IServerActionPayload } from '@mosetta/server-action/server';
+
+export const greetToken = new ServerActionToken<{ q: string }, { answer: string }>({ actionName: 'greet' });
+
+@DiServerAction(greetToken)
+class GreetAction extends ServerAction<{ q: string }, { answer: string }> {
+  authorize() {
+    return true; // anyone may ask
+  }
+
+  action({ input }: IServerActionPayload<{ q: string }>) {
+    return Promise.resolve({ answer: `hello ${input.q}` });
+  }
+
+  createSchema({ builder }: ICreateSchema) {
+    return builder.object({ q: builder.string() });
+  }
+}
+
+export default defineServerSide({ services: [GreetAction] });
+```
+
+The component side calls it with `useServerAction` from `@mosetta/react/server-action`; during
+server rendering the same call runs on the server, so the page arrives with the data in it.
+
+## Entry points
+
+| Entry | What it holds |
+|---|---|
+| `@mosetta/server-action/server` | `defineServerSide`, `ServerAction`, `DiServerAction`, `DiInject`; what an action may ask for: the caller, the request, the project's secrets by name (`SECRETS_TOKEN`), its stores (`PROVIDERS_TOKEN`), the site's tile hosts (`TILE_HOSTS_TOKEN`) |
+| `@mosetta/server-action/client` | the browser's call of an action |
+| `@mosetta/server-action/core` | `ServerActionToken` (shared by the server and the component side), serialization, the caller as the host vouches for it |
+
+An action runs in an isolated line of the factory: its privileges are handed in, never assumed —
+no store key and no secret value sits in its environment.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@mosetta/server-action",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.9",
+  "license": "MIT",
+  "description": "mosetta server actions (RPC): shared token/serializer contract, client hook, server-side action definition. Web-API native (workerd).",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    "./core": "./src/core/core.ts",
+    "./client": "./src/client/client.ts",
+    "./server": "./src/server/server.ts"
+  },
+  "dependencies": {
+    "react": "*",
+    "zod": "^3",
+    "@mosetta/di": "0.0.9",
+    "@mosetta/runtime": "0.0.9",
+    "@mosetta/stores": "0.0.9",
+    "@mosetta/router": "0.0.9"
+  },
+  "devDependencies": {
+    "@types/react": "^19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/client/client.ts

@@ -0,0 +1,61 @@
+// @mosetta/server-action / client — the client slice: the ServerData model, the
+// tag-invalidated query cache and the fetch transport. The react hook (useServerAction) lives in
+// the binding — @mosetta/react/server-action.
+import { DiContainer } from '@mosetta/di';
+import { SSR_RENDER_CHANNEL_TOKEN } from '@mosetta/runtime/client';
+import type { ISsrRenderChannel } from '@mosetta/runtime/client';
+import { CLIENT_SERIALIZER_TOKEN, EXECUTION_ENV_TOKEN, JsonClientSerializer, SERVER_ACTION_EXECUTOR_TOKEN } from '../core/core';
+import { FetchServerActionExecutor, OriginFetchServerActionExecutor } from './executor';
+import { ServerDataManager } from './manager';
+import { ACTION_CACHE_ELEMENT_ID, seedManagerFromDocument, SsrActionRecorder, SSR_ACTION_RECORDER_TOKEN } from './ssrRecorder';
+import { SERVER_DATA_MANAGER } from './manager';
+
+export * from './serverData';
+export * from './stableStringify';
+export { SERVER_DATA_MANAGER, ServerDataManager } from './manager';
+export type { IServerDataHandle } from './manager';
+export { FetchServerActionExecutor, OriginFetchServerActionExecutor } from './executor';
+export * from './ssrRecorder';
+// the pieces a consumer typically re-exports from core
+export { EServerActionStart, EXECUTION_ENV_TOKEN } from '../core/core';
+
+/**
+ * Wire the client slice into an app's container. The app calls this from its Component
+ * initializer with the `ssrChannel` prop: absent → the browser wiring; present →
+ * the SERVER wiring — same manager/cache, but the executor targets the runner origin absolutely,
+ * the environment flips to 'server' and the recorder drives the head channel's counter.
+ */
+export function registerServerActionClient(di: DiContainer, ssrChannel?: ISsrRenderChannel): void {
+  const serializer = new JsonClientSerializer();
+  di.registerValueOfToken(CLIENT_SERIALIZER_TOKEN, serializer);
+  di.registerServices(ServerDataManager);
+  if (ssrChannel) {
+    di.registerValueOfToken(EXECUTION_ENV_TOKEN, 'server');
+    di.registerValueOfToken(SERVER_ACTION_EXECUTOR_TOKEN,
+      new OriginFetchServerActionExecutor(serializer, ssrChannel.requestOrigin ?? ''));
+    di.registerValueOfToken(SSR_ACTION_RECORDER_TOKEN, new SsrActionRecorder(ssrChannel));
+  } else {
+    di.registerServices(FetchServerActionExecutor);
+    di.registerValueOfToken(EXECUTION_ENV_TOKEN, 'browser');
+    di.registerValueOfToken(SSR_ACTION_RECORDER_TOKEN, null);
+    // hydration seeds (stage 4): server-computed results from the head cache script — parked in
+    // the manager, consumed by each query's first ensureQuery (mirror parity, no refetch).
+    // Instantiated eagerly ONLY when the page actually carries a cache.
+    if (typeof document !== 'undefined' && document.getElementById(ACTION_CACHE_ELEMENT_ID)) {
+      seedManagerFromDocument(di.getByToken(SERVER_DATA_MANAGER));
+    }
+  }
+}
+
+/**
+ * Lazy, idempotent "carry your own" wiring: called by useServerAction on
+ * every render — the FIRST call registers the slice into the TOP scope of the inherited
+ * per-request container (the page-wide cache/tags must be shared), later calls see the manager
+ * and bail. The ssr channel arrives as DATA (SSR_RENDER_CHANNEL_TOKEN, stamped by
+ * createAppContainer) — the root module knows nothing about server actions anymore.
+ */
+export function ensureServerActionClient(di: DiContainer): void {
+  if (di.hasByToken(SERVER_DATA_MANAGER)) return;
+  const ssrChannel = di.hasByToken(SSR_RENDER_CHANNEL_TOKEN) ? di.getByToken(SSR_RENDER_CHANNEL_TOKEN) : null;
+  registerServerActionClient(di, ssrChannel ?? undefined);
+}

package/src/client/executor.ts

@@ -0,0 +1,101 @@
+// The browser transport: POST to the canonical origin-absolute route. Never rejects —
+// every failure (HTTP or network) is folded into IServerActionResult.error so the ServerData model is
+// the single error channel. The ONE exception is an abort of options.signal: that re-throws, because
+// it is not a server outcome — the manager initiated it and discards the whole try.
+import { DiInject, DiService } from '@mosetta/di';
+import {
+  CLIENT_SERIALIZER_TOKEN,
+  ClientSerializer,
+  IExecuteServerActionOptions,
+  IServerActionError,
+  IServerActionResult,
+  SERVER_ACTION_EXECUTOR_TOKEN,
+  serverActionRoute,
+  ServerActionExecutor,
+} from '../core/core';
+
+@DiService(SERVER_ACTION_EXECUTOR_TOKEN)
+export class FetchServerActionExecutor extends ServerActionExecutor {
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(
+    @DiInject(CLIENT_SERIALIZER_TOKEN)
+    private readonly defaultSerializer: ClientSerializer,
+  ) {
+    super();
+    // bind to globalThis — the global fetch must not be called as a method of `this`
+    this.fetchImpl = fetch.bind(globalThis);
+  }
+
+  // origin-relative in the browser (the page origin IS the runner); the ssr isolate overrides
+  protected route(fullId: string, actionName: string): string {
+    return serverActionRoute(fullId, actionName);
+  }
+
+  executeServerAction = async <TOutput>(
+    options: IExecuteServerActionOptions,
+  ): Promise<IServerActionResult<TOutput>> => {
+    const { request, requestHash } = options;
+    const serializer = options.customSerializer ?? this.defaultSerializer;
+
+    try {
+      const body = await serializer.serializeIntoRequestBody(request.input as object);
+      const response = await this.fetchImpl(this.route(request.fullId, request.actionName), {
+        method: 'POST',
+        body: body.content,
+        headers: body.contentType ? { 'content-type': body.contentType } : {},
+        signal: options.signal,
+      });
+
+      if (response.ok) {
+        const output = (await serializer.parseFromResponse(response)) as TOutput;
+        return { requestHash, output };
+      }
+
+      // non-2xx: the glue's wire format is { error: { code, ... } }; anything else → a synthetic code
+      // carrying a snippet of the RAW body — a proxy's HTML page or a plain-text crash is the actual
+      // clue, and statusText alone is useless (HTTP/2 dropped reason phrases entirely)
+      let error: IServerActionError | undefined;
+      let raw = '';
+      try {
+        raw = await response.text();
+        error = ((await serializer.parseFromString({
+          content: raw,
+          contentType: response.headers.get('content-type') ?? '',
+          serializerName: serializer.serializerName,
+        })) as { error?: IServerActionError }).error;
+      } catch (e) {
+        // aborted mid-body-read is not an outcome either — let the outer catch rethrow it;
+        // an unparseable body IS surfaced: via the raw snippet below
+        if (options.signal?.aborted) throw e;
+      }
+      return {
+        requestHash,
+        error: error ?? {
+          code: `SERVER_ACTION_HTTP_${response.status}`,
+          message: raw.trim().slice(0, 300) || response.statusText,
+        },
+      };
+    } catch (e) {
+      // aborted mid-fetch OR mid-body-read: not a network outcome — propagate to the initiator
+      if (options.signal?.aborted) throw e;
+      return {
+        requestHash,
+        error: { code: 'SERVER_ACTION_NETWORK', message: String((e as Error)?.message ?? e) },
+      };
+    }
+  };
+}
+
+// The ssr-isolate twin: SAME endpoint, but absolute — a worker has no page origin
+// to resolve a relative route against. `origin` is the runner origin of the original request
+// (rides the render channel). Constructed manually (not DI-scanned) by registerServerActionClient.
+export class OriginFetchServerActionExecutor extends FetchServerActionExecutor {
+  constructor(serializer: ClientSerializer, private readonly origin: string) {
+    super(serializer);
+  }
+
+  protected override route(fullId: string, actionName: string): string {
+    return new URL(serverActionRoute(fullId, actionName), this.origin).toString();
+  }
+}

package/src/client/manager.ts

@@ -0,0 +1,224 @@
+// ServerDataManager v2: the query cache + tag invalidation + manual (mutation) handles.
+// Subscriptions live on ENTRIES (persistent, with unsubscribe — the useSyncExternalStore contract),
+// snapshots are immutable ServerData instances replaced only on transitions. Invalidation of a tag
+// refetches ACTIVE entries immediately (stale-while-refetch: the previous Success stays visible until
+// the fresh result lands) and lazily marks inactive ones (refetch on next mount — entries are kept so
+// a subscribe can never race a deletion).
+//
+// Cancellation model: each run of a query owns a GENERATION + an AbortController.
+// The generation is the source of truth about whose landing counts — a superseded run's response is
+// discarded even if it slips past the abort (abort and landing can race within one tick). The abort
+// is network hygiene on top: superseded/abandoned requests actually disappear from the wire (devtools
+// shows them as cancelled, not as zombie in-flights). Mutations are NEVER aborted: by the time anyone
+// could cancel, the write is already on the server, and skipping the .then would lose `invalidate`.
+import { DiInject, DiService, SingleDiToken } from '@mosetta/di';
+import {
+  ClientSerializer,
+  IServerActionRequest,
+  SERVER_ACTION_EXECUTOR_TOKEN,
+  ServerActionExecutor,
+} from '../core/core';
+import {
+  IdleServerData,
+  IManualStart,
+  LoadingServerData,
+  ServerData,
+  serverDataOfResult,
+} from './serverData';
+
+export interface IEnsureQueryOptions {
+  readonly key: string;
+  readonly tags: readonly string[];
+  readonly request: IServerActionRequest;
+  readonly customSerializer?: ClientSerializer;
+}
+
+export interface ICreateManualOptions {
+  readonly fullId: string;
+  readonly actionName: string;
+  readonly invalidates: readonly string[];
+  readonly customSerializer?: ClientSerializer;
+}
+
+/** the hook-facing subscription surface — same shape for query entries and manual handles */
+export interface IServerDataHandle<TOut, TIn = unknown> {
+  subscribe(listener: () => void): () => void;
+  snapshot(): ServerData<TOut, TIn>;
+}
+
+interface IQueryEntry {
+  readonly tags: readonly string[];
+  readonly listeners: Set<() => void>;
+  current: ServerData<unknown>;
+  inflight: Promise<void> | null;
+  /** controller of the CURRENT generation's request; null once it lands */
+  controller: AbortController | null;
+  /** bumped by every run (and by last-unsubscribe abort) — an older run's landing is discarded */
+  generation: number;
+  invalidated: boolean;
+  run(): void;
+}
+
+export const SERVER_DATA_MANAGER = new SingleDiToken<ServerDataManager>('SERVER_DATA_MANAGER');
+
+@DiService(SERVER_DATA_MANAGER)
+export class ServerDataManager {
+  private readonly entries = new Map<string, IQueryEntry>();
+
+  // hydration seeds: server-computed results parked until the OWNING hook mounts —
+  // ensureQuery consumes a seed instead of fetching, so the entry keeps the hook's tags and the
+  // first client render shows the SAME data the server rendered (no Loading flash, no refetch)
+  private readonly seeds = new Map<string, ServerData<unknown>>();
+
+  constructor(
+    @DiInject(SERVER_ACTION_EXECUTOR_TOKEN)
+    private readonly executor: ServerActionExecutor,
+  ) {}
+
+  /** park a server-computed snapshot for the key; consumed by the first ensureQuery */
+  seedQuery(key: string, data: ServerData<unknown>): void {
+    if (!this.entries.has(key)) this.seeds.set(key, data);
+  }
+
+  /**
+   * Idempotent by key; called during render (the standard start-on-first-read pattern — safe because
+   * repeated calls are no-ops). A previously invalidated inactive entry refetches here, keeping its
+   * stale snapshot until the fresh result arrives.
+   */
+  ensureQuery({ key, tags, request, customSerializer }: IEnsureQueryOptions): void {
+    const existing = this.entries.get(key);
+    if (existing) {
+      if (existing.invalidated && !existing.inflight) existing.run();
+      return;
+    }
+
+    const entry: IQueryEntry = {
+      tags,
+      listeners: new Set(),
+      current: undefined as unknown as ServerData<unknown>,
+      inflight: null,
+      controller: null,
+      generation: 0,
+      invalidated: false,
+      run: () => {
+        // supersede the previous try: cancel it on the wire AND orphan its landing by the bump
+        // (the two are separate on purpose — a response can land in the same tick the abort fires)
+        entry.controller?.abort();
+        const gen = ++entry.generation;
+        const controller = new AbortController();
+        entry.controller = controller;
+        entry.invalidated = false;
+        const promise = this.executor
+          .executeServerAction({ request, requestHash: key, customSerializer, signal: controller.signal })
+          .then((result) => {
+            if (gen !== entry.generation) return; // orphaned: a newer generation owns this entry
+            entry.inflight = null;
+            entry.controller = null;
+            entry.current = serverDataOfResult(result);
+            // a tag invalidation landed mid-flight while nobody could refetch (entry was inactive) —
+            // this result is already suspect: show it as the stale and immediately go again
+            if (entry.invalidated && entry.listeners.size > 0) entry.run();
+            for (const listener of entry.listeners) listener();
+          })
+          .catch(() => {
+            // abort — always initiated by this manager (supersession or last-unsubscribe); swallowed
+            // so the waiter promise NEVER rejects (opt-in suspense throws it in both runtimes)
+          });
+        entry.inflight = promise;
+        // no data yet → (re)issue Loading with the CURRENT waiter, so a suspense retry after an
+        // aborted try suspends on a live promise instead of spinning on a settled one; a stale
+        // Success/Error stays visible instead (stale-while-refetch)
+        if (!entry.current || entry.current.isLoading()) {
+          entry.current = new LoadingServerData<unknown>(promise);
+        }
+      },
+    };
+    this.entries.set(key, entry);
+    const seed = this.seeds.get(key);
+    if (seed) {
+      // hydration parity (v1: seed without revalidation-on-mount) — a later tag invalidation
+      // refetches through the normal run() path
+      this.seeds.delete(key);
+      entry.current = seed;
+      return;
+    }
+    entry.run();
+  }
+
+  subscribe(key: string, listener: () => void): () => void {
+    const entry = this.entries.get(key);
+    if (!entry) return () => {};
+    entry.listeners.add(listener);
+    // revival: the entry was cancelled/invalidated while nobody watched (e.g. its fetch was aborted
+    // between this hook's render and its effect-phase subscription)
+    if (entry.invalidated && !entry.inflight) entry.run();
+    return () => {
+      entry.listeners.delete(listener);
+      // last watcher gone with a request still in flight → nobody wants the answer: cancel on the
+      // wire, orphan the landing, refetch on the next mount. Covers unmount AND a hook switching
+      // cache keys (debounced-search style). The entry itself is kept — subscribe never races a
+      // deletion — and revives via ensureQuery/subscribe.
+      if (entry.listeners.size === 0 && entry.inflight) {
+        entry.generation += 1;
+        entry.controller?.abort();
+        entry.controller = null;
+        entry.inflight = null;
+        entry.invalidated = true;
+      }
+    };
+  }
+
+  snapshot<TOut>(key: string): ServerData<TOut> {
+    const entry = this.entries.get(key);
+    if (!entry) throw new Error(`server-action query ${key} was not ensured before read`);
+    return entry.current as ServerData<TOut>;
+  }
+
+  /** tag invalidation: active entries refetch now, inactive refetch on next mount */
+  invalidate(tags: readonly string[]): void {
+    if (!tags.length) return;
+    const hit = new Set(tags);
+    for (const entry of this.entries.values()) {
+      if (!entry.tags.some((t) => hit.has(t))) continue;
+      if (entry.listeners.size > 0) {
+        // unconditionally: run() itself cancels+orphans an in-flight PRE-invalidation try — its
+        // response was computed before the write and must never be presented as fresh
+        entry.run();
+      } else {
+        entry.invalidated = true;
+      }
+    }
+  }
+
+  /** a per-hook mutation handle (START_MANUAL): never cached, never aborted (the write is already
+   *  on the server; killing the .then would silently lose `invalidate`), input arrives at start(input) */
+  createManual<TIn, TOut>({ fullId, actionName, invalidates, customSerializer }: ICreateManualOptions): IServerDataHandle<TOut, TIn> {
+    const listeners = new Set<() => void>();
+    const notify = () => {
+      for (const listener of listeners) listener(); 
+    };
+
+    let current: ServerData<TOut, TIn>;
+    const start: IManualStart<TIn> = (input) => {
+      const request: IServerActionRequest = { fullId, actionName, input };
+      const promise = this.executor
+        .executeServerAction<TOut>({ request, requestHash: `${fullId}/${actionName}#manual`, customSerializer })
+        .then((result) => {
+          current = serverDataOfResult<TOut, TIn>(result, start);
+          if (!result.error) this.invalidate(invalidates);
+          notify();
+        });
+      current = new LoadingServerData<TOut, TIn>(promise, start);
+      notify();
+    };
+    current = new IdleServerData<TOut, TIn>(start);
+
+    return {
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      snapshot: () => current,
+    };
+  }
+}

package/src/client/serverData.ts

@@ -0,0 +1,82 @@
+// ServerData v2: IMMUTABLE state snapshots of a server-action call. Sanitized against
+// the legacy model's traps: no subscribers on the snapshot (subscriptions live on the manager/handle
+// entry), no single-shot auto-clearing, void output IS a success, and no module-level shared instances.
+import { IServerActionError, IServerActionResult } from '../core/core';
+
+// Manual-mode (START_MANUAL) trigger: present on EVERY state of a mutation hook so the editor can
+// re-run it from any point (Idle → run, Success/Error → run again). Queries never carry it.
+export interface IManualStart<TIn> {
+  (input: TIn): void;
+}
+
+export abstract class ServerData<TOut, TIn = unknown> {
+  /** mutation trigger (manual mode only); undefined on query states */
+  readonly start?: IManualStart<TIn>;
+
+  protected constructor(start?: IManualStart<TIn>) {
+    this.start = start;
+  }
+
+  isIdle(): this is IdleServerData<TOut, TIn> {
+    // eslint-disable-next-line no-use-before-define
+    return this instanceof IdleServerData;
+  }
+
+  isLoading(): this is LoadingServerData<TOut, TIn> {
+    // eslint-disable-next-line no-use-before-define
+    return this instanceof LoadingServerData;
+  }
+
+  isSuccess(): this is SuccessServerData<TOut, TIn> {
+    // eslint-disable-next-line no-use-before-define
+    return this instanceof SuccessServerData;
+  }
+
+  isError(): this is ErrorServerData<TOut, TIn> {
+    // eslint-disable-next-line no-use-before-define
+    return this instanceof ErrorServerData;
+  }
+}
+
+export class IdleServerData<TOut, TIn = unknown> extends ServerData<TOut, TIn> {
+  constructor(start: IManualStart<TIn>) {
+    super(start);
+  }
+}
+
+export class LoadingServerData<TOut, TIn = unknown> extends ServerData<TOut, TIn> {
+  /** the in-flight promise — thrown by the hook when opt-in suspense is on */
+  readonly waiter: Promise<void>;
+
+  constructor(waiter: Promise<void>, start?: IManualStart<TIn>) {
+    super(start);
+    this.waiter = waiter;
+  }
+}
+
+export class SuccessServerData<TOut, TIn = unknown> extends ServerData<TOut, TIn> {
+  readonly serverData: TOut;
+
+  constructor(output: TOut, start?: IManualStart<TIn>) {
+    super(start);
+    this.serverData = output;
+  }
+}
+
+export class ErrorServerData<TOut, TIn = unknown> extends ServerData<TOut, TIn> {
+  readonly serverError: IServerActionError;
+
+  constructor(error: IServerActionError, start?: IManualStart<TIn>) {
+    super(start);
+    this.serverError = error;
+  }
+}
+
+/** result → snapshot; ABSENT error = success even for void/undefined output (legacy trap №3) */
+export function serverDataOfResult<TOut, TIn>(
+  result: IServerActionResult<TOut>,
+  start?: IManualStart<TIn>,
+): ServerData<TOut, TIn> {
+  if (result.error) return new ErrorServerData<TOut, TIn>(result.error, start);
+  return new SuccessServerData<TOut, TIn>(result.output as TOut, start);
+}

package/src/client/ssrRecorder.ts

@@ -0,0 +1,80 @@
+// SsrActionRecorder: the per-request bookkeeper of server-executed actions.
+// It drives the head channel's pending counter BY THE CHANNEL'S RULES — begin on the render that
+// starts a query, complete on the RETRY render that consumed the settled data (both idempotent
+// per KEY, so deduped hooks over one cache entry count once) — and accumulates the results into
+// ONE head entry: the action-cache script the client reads before hydration (stage 4).
+import { SingleDiToken } from '@mosetta/di';
+import { ACTION_CACHE_HEAD_KEY, ISsrRenderChannel } from '@mosetta/runtime/client';
+import { IServerActionError } from '../core/core';
+import type { ServerDataManager } from './manager';
+import { ErrorServerData, ServerData, SuccessServerData } from './serverData';
+
+// the collector key is the WELL-KNOWN reserved name from @mosetta/runtime/client — module writes
+// under it are ignored by useAddToHead, only this recorder ships the cache
+export { ACTION_CACHE_HEAD_KEY } from '@mosetta/runtime/client';
+/** DOM id of the cache script (one entry, rewritten as results accumulate) */
+export const ACTION_CACHE_ELEMENT_ID = 'mosettaActionCache';
+
+/** cache payload: query key → settled result (errors ride too — first-render parity, stage 4) */
+export type TActionCacheEntry = { output?: unknown; error?: IServerActionError };
+
+// null in the browser and in channel-less server renders (the v1 Loading-stub degenerate)
+export const SSR_ACTION_RECORDER_TOKEN = new SingleDiToken<SsrActionRecorder | null>('SSR_ACTION_RECORDER_TOKEN');
+
+// The browser half of the cache (stage 4): parse the script the server shipped and park every
+// result as a hydration seed — the first client render then shows the SAME data the server
+// rendered (mirror parity: no Loading flash, no refetch, no hydration mismatch). Errors seed
+// too — a server-rendered Error state must hydrate as itself.
+export function seedManagerFromDocument(manager: ServerDataManager): void {
+  if (typeof document === 'undefined') return;
+  const script = document.getElementById(ACTION_CACHE_ELEMENT_ID);
+  if (!script?.textContent) return;
+  let parsed: Record<string, TActionCacheEntry>;
+  try {
+    parsed = JSON.parse(script.textContent) as Record<string, TActionCacheEntry>;
+  } catch {
+    return; // a mangled cache is a missing cache — queries just fetch
+  }
+  for (const [key, entry] of Object.entries(parsed)) {
+    manager.seedQuery(key, entry.error
+      ? new ErrorServerData<unknown>(entry.error)
+      : new SuccessServerData<unknown>(entry.output));
+  }
+}
+
+export class SsrActionRecorder {
+  private readonly begun = new Set<string>();
+
+  private readonly settled = new Set<string>();
+
+  private readonly results: Record<string, TActionCacheEntry> = {};
+
+  constructor(private readonly channel: ISsrRenderChannel) {}
+
+  /** idempotent per key — called on the render that ensured the query */
+  onQueryStart(key: string): void {
+    if (this.begun.has(key)) return;
+    this.begun.add(key);
+    this.channel.beginAction();
+  }
+
+  /** idempotent per key — called on the RETRY render that sees Success/Error (never from .then) */
+  // TIn=never: the start-callback position is contravariant, never accepts every ServerData
+  onQuerySettled(key: string, data: ServerData<unknown, never>): void {
+    if (!this.begun.has(key) || this.settled.has(key)) return;
+    this.settled.add(key);
+    if (data.isSuccess()) this.results[key] = { output: data.serverData };
+    else if (data.isError()) this.results[key] = { error: data.serverError };
+    try {
+      // one keyed entry, last write wins — each settle re-ships the WHOLE accumulated map
+      const json = JSON.stringify(this.results).replace(/</g, '\\u003c');
+      this.channel.addToHead(ACTION_CACHE_HEAD_KEY, 'script',
+        { type: 'application/json', id: ACTION_CACHE_ELEMENT_ID }, json);
+    } catch {
+      // unserializable output (custom serializer territory) — drop it from the cache; the page
+      // still renders, the client just refetches this one
+      delete this.results[key];
+    }
+    this.channel.completeAction();
+  }
+}

package/src/client/stableStringify.ts

@@ -0,0 +1,11 @@
+// Deterministic serialization for cache keys: recursive key sort, so semantically equal
+// inputs always produce the same key. Replaces the legacy @mosetta/object-hash dependency.
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+  return `{${entries.join(',')}}`;
+}

package/src/core/core.ts

@@ -0,0 +1,234 @@
+import { SingleDiToken } from '@mosetta/di';
+
+// @mosetta/server-action / core — the shared contract, imported by BOTH the client hook and the server
+// module. Web-API native: serializers speak the platform `Request`/`Response`, never node
+// `http.IncomingMessage` / `stream.Readable`.
+
+// ---- execution environment ----
+// Registered by the runtime that owns the tree: the app module in the browser, the (future) SSR renderer
+// in the isolate. A container property, NOT React context — the hook branches on values, never on hooks.
+export type ExecutionEnv = 'browser' | 'server';
+export const EXECUTION_ENV_TOKEN = new SingleDiToken<ExecutionEnv>('EXECUTION_ENV_TOKEN');
+
+// ---- who is calling ------------------------------------------------------------------------
+//
+// Who calls is said by the HOST — the trust boundary in front of the runner (a platform's Worker
+// that verified a session, a dev server, a self-hosted gateway) — in one header it strips from every
+// incoming request before setting its own. What it says is ITS words: a platform that signs people
+// in with GitHub and keeps project roles says `{ via, login, roles }`, another host says what its
+// model has. The framework passes them through to the action and never reads them; an action that
+// cares injects CALLER_TOKEN, and every action's `authorize` gets them.
+export const IDENTITY_HEADER = 'x-mosetta-identity';
+
+// WHERE a platform's API is asked to publish: the target's name and its policy, set by the host
+// once it checked the caller may publish there (and stripped from every incoming request, like the
+// identity). The API's code reads the target from here, never from the body it was sent.
+export const PUBLISH_TARGET_HEADER = 'x-mosetta-publish-target';
+
+// The boundary's own CREDENTIAL: the session cookie the platform's Worker signs and reads. Code
+// inside learns WHO through the identity header, never holds the key itself: the runner drops
+// this cookie from every request it hands an isolate, and any Set-Cookie of it from an isolate's
+// answer. Every other cookie is the project's own and passes both ways.
+export const SESSION_COOKIE = 'mosetta-session';
+
+/** what the host vouches for about the caller — the host's own words, unread by the framework */
+export interface ICaller {
+  readonly [claim: string]: unknown;
+}
+
+/** the header's JSON object as the caller, or null: absent, malformed, or not an object */
+export function parseCaller(header: string | null | undefined): ICaller | null {
+  if (!header) return null;
+  try {
+    const raw: unknown = JSON.parse(header);
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as ICaller : null;
+  } catch {
+    return null;
+  }
+}
+
+export const CALLER_TOKEN = new SingleDiToken<ICaller | null>('CALLER_TOKEN');
+
+// ---- canonical naming ----
+// MUST agree with cli/runtime/naming.js (the build-side single source of truth for artifact ids) —
+// the CLI runtime is plain dependency-free JS bundled into bootstrap, so the encoder is duplicated
+// here for browser/isolate consumers and PINNED by a cross-check test (unify under the rebrand).
+export const normalizeVersion = (v: string) => String(v).trim().replace(/[^a-zA-Z0-9]/g, '_');
+
+/** canonical full-id of a SERVER module: _ns_<ns>_t_server_n_<name>_v_<normalized-version> */
+export function fullServerTileId({ namespace, name, version }: {
+  readonly namespace: string;
+  readonly name: string;
+  readonly version: string;
+}): string {
+  return `_ns_${namespace}_t_server_n_${name}_v_${normalizeVersion(version)}`;
+}
+
+// ---- request / result shapes ----
+export interface IServerActionRequest {
+  /** canonical full-id of the target server module (direct file addressing) */
+  readonly fullId: string;
+  readonly actionName: string;
+  readonly input: unknown;
+}
+
+// The error shape ON THE WIRE — exactly what the isolate glue returns ({ error: { code, ... } });
+// transport-level failures are mapped into the same shape by the client executor.
+export interface IServerActionError {
+  readonly code: string;
+  readonly message?: string;
+  readonly issues?: unknown[];
+}
+
+export interface IServerActionResult<TOutput = unknown> {
+  readonly requestHash: string;
+  readonly output?: TOutput;
+  readonly error?: IServerActionError;
+}
+
+export interface IContent<T> {
+  readonly contentType: string;
+  readonly serializerName: string;
+  readonly content: T;
+}
+
+// ---- when the action fires (SPA uses START_FROM_CLIENT; SSR pre-compute is deferred) ----
+export enum EServerActionStart {
+  START_FROM_SERVER = 'START_FROM_SERVER',
+  START_FROM_CLIENT = 'START_FROM_CLIENT',
+  START_MANUAL = 'START_MANUAL',
+}
+
+// ---- serializers (Web-API; no node:stream / IncomingMessage) ----
+export abstract class ClientSerializer {
+  protected constructor(readonly serializerName: string) {}
+
+  abstract serializeIntoRequestBody(objectContent: object): Promise<IContent<BodyInit>>;
+
+  abstract parseFromString(content: IContent<string>): Promise<object>;
+
+  abstract parseFromResponse(response: Response): Promise<object>;
+}
+
+export abstract class ServerSerializer {
+  protected constructor(readonly serializerName: string) {}
+
+  // Web-native: parse the platform Request (was node:http.IncomingMessage); serialize to a string (no stream).
+  abstract parse(request: Request): Promise<object>;
+
+  abstract serializeIntoString(body: object): Promise<IContent<string>>;
+}
+
+export class JsonClientSerializer extends ClientSerializer {
+  constructor() {
+    super('json');
+  }
+
+  serializeIntoRequestBody(objectContent: object): Promise<IContent<BodyInit>> {
+    return Promise.resolve({
+      content: JSON.stringify(objectContent),
+      contentType: 'application/json',
+      serializerName: this.serializerName,
+    });
+  }
+
+  parseFromString(content: IContent<string>): Promise<object> {
+    return Promise.resolve(JSON.parse(content.content) as object);
+  }
+
+  async parseFromResponse(response: Response): Promise<object> {
+    return (await response.json()) as object;
+  }
+}
+
+export class JsonServerSerializer extends ServerSerializer {
+  constructor() {
+    super('json');
+  }
+
+  async parse(request: Request): Promise<object> {
+    return (await request.json()) as object;
+  }
+
+  serializeIntoString(body: object): Promise<IContent<string>> {
+    return Promise.resolve({
+      content: JSON.stringify(body),
+      contentType: 'application/json',
+      serializerName: this.serializerName,
+    });
+  }
+}
+
+// ---- token: the client/server contract carrier (input/output types + action name + optional serializer) ----
+export class ServerActionToken<TIn extends {}, TOut> {
+  readonly inputType!: TIn;
+
+  readonly outputType!: TOut;
+
+  readonly actionName: string;
+
+  /**
+   * Name of the SERVER module implementing this action. The client hook combines it with
+   * the CALLING component's namespace+version (tokens live in the same distributive's Common file, so
+   * those always match). Omitted → the calling component's own name (facet pair convention).
+   */
+  readonly serverModuleName?: string;
+
+  /** cache tags this action's QUERY results are labeled with */
+  readonly tags?: readonly string[];
+
+  /** cache tags a successful MUTATION of this action invalidates */
+  readonly invalidates?: readonly string[];
+
+  readonly customSerializer?: ClientSerializer;
+
+  constructor({
+    actionName,
+    serverModuleName,
+    tags,
+    invalidates,
+    customSerializer,
+  }: {
+    readonly actionName: string;
+    readonly serverModuleName?: string;
+    readonly tags?: readonly string[];
+    readonly invalidates?: readonly string[];
+    readonly customSerializer?: ClientSerializer;
+  }) {
+    this.actionName = actionName;
+    this.serverModuleName = serverModuleName;
+    this.tags = tags;
+    this.invalidates = invalidates;
+    this.customSerializer = customSerializer;
+  }
+}
+
+// ---- client-side transport abstraction + DI tokens ----
+export interface IExecuteServerActionOptions {
+  readonly request: IServerActionRequest;
+  readonly requestHash: string;
+  readonly customSerializer?: ClientSerializer;
+  /** cancellation (queries only — a sent mutation must land: the server write already happened) */
+  readonly signal?: AbortSignal;
+}
+
+// Contract: NEVER rejects with transport/HTTP failures (those fold into result.error) — the ONLY
+// rejection is an abort of `signal`, and aborts are always initiated by the caller (ServerDataManager),
+// which swallows them.
+export abstract class ServerActionExecutor {
+  abstract executeServerAction<TOutput>(
+    options: IExecuteServerActionOptions,
+  ): Promise<IServerActionResult<TOutput>>;
+}
+
+export const CLIENT_SERIALIZER_TOKEN = new SingleDiToken<ClientSerializer>('CLIENT_SERIALIZER_TOKEN');
+
+export const SERVER_ACTION_EXECUTOR_TOKEN = new SingleDiToken<ServerActionExecutor>('SERVER_ACTION_EXECUTOR_TOKEN');
+
+// ---- route: /api/server-action/<server-module-full-id>/<actionName> ----
+// The full-id already encodes namespace/type/version, so no separate segments and direct file addressing
+// in the private provider (private/modules/<full-id>/). LEADING slash: the route must be origin-absolute
+// (a relative one breaks on any nested browser path — an actual legacy bug).
+export function serverActionRoute(fullId: string, actionName: string): string {
+  return `/${['api', 'server-action', fullId, actionName].join('/')}`;
+}

package/src/server/server.ts

@@ -0,0 +1,236 @@
+import { Constructable, DiContainer, DiService, SingleDiToken } from '@mosetta/di';
+import { parseStoreConnectors } from '@mosetta/stores';
+import type { IStoreConnector } from '@mosetta/stores';
+import { z, ZodType } from 'zod';
+import {
+  CALLER_TOKEN,
+  IDENTITY_HEADER,
+  JsonServerSerializer,
+  parseCaller,
+  ServerActionToken,
+  ServerSerializer,
+} from '../core/core';
+import type { ICaller } from '../core/core';
+
+// re-export the DI essentials a coder needs — so a server module imports everything from
+// `@mosetta/server-action/server` (not the legacy @mosetta/di directly).
+export { DiInject } from '@mosetta/di';
+
+// The isolate's provider origin — low-level, NON-secret context (an origin string, not a capability),
+// registered by the glue from the isolate env. The framework blesses NO write access with it: a writable
+// content transport is an opt-in service of a trusted module (`@mosetta/content`).
+export const PROVIDER_ORIGIN_TOKEN = new SingleDiToken<string>('PROVIDER_ORIGIN_TOKEN');
+
+// The isolate's providers: the host's registry as an isolate may see it — web entries (an
+// address, no secret) and CAPABILITIES (RPC stubs the host granted, `@mosetta/stores`
+// capability.ts): no key ever enters the isolate. An action isolate is granted read-write where
+// the store allows it; per-module grants are the next layer (ADR-0046).
+export const PROVIDERS_TOKEN = new SingleDiToken<readonly IStoreConnector[]>('PROVIDERS_TOKEN');
+
+/** a tile host of the site, as an action may know it: its key and where its public side lies */
+export interface ITileHostBase {
+  readonly key: string;
+  readonly publicBase: string;
+}
+
+// The site's TILE HOSTS, the primary first — where each one's public tiles and descriptor lie (no
+// secret: browsers load from there). What a module reads to see every tile the site may place (the
+// editor's block picker). Always registered: without the host's word, the primary alone, at the
+// provider origin.
+export const TILE_HOSTS_TOKEN = new SingleDiToken<readonly ITileHostBase[]>('TILE_HOSTS_TOKEN');
+
+/** the host's list of tile hosts, or the primary alone at `origin` — malformed entries are dropped */
+export function tileHostBasesOf(value: unknown, origin: string | undefined): ITileHostBase[] {
+  const listed = Array.isArray(value)
+    ? (value as Partial<ITileHostBase>[]).filter((h): h is ITileHostBase => typeof h?.key === 'string' && typeof h.publicBase === 'string' && Boolean(h.publicBase))
+    : [];
+  if (listed.length) return listed.map(({ key, publicBase }) => ({ key, publicBase }));
+  return origin ? [{ key: 'host', publicBase: origin }] : [];
+}
+
+// The project's SECRETS and plain settings, asked for by name — a database token, a mail key, a
+// sender address. The host grants the isolate a capability (an RPC stub, `SECRETS` in its env) that
+// answers with the value of the narrowest scope naming it for THIS module: `/` (the whole project),
+// `/<namespace>`, `/<namespace>/<module>`. No value sits in the env, and a module sees only what it
+// asked for. Where the host grants none, `get` throws — saying so, never a silent null.
+export interface ISecrets {
+  /** the value set for `name` (UPPER_SNAKE_CASE), or null when none is */
+  get(name: string): Promise<string | null>;
+}
+
+export const SECRETS_TOKEN = new SingleDiToken<ISecrets>('SECRETS_TOKEN');
+
+// The REQUEST an action answers: its address and headers — what the input does not carry, such as
+// the caller's address (`cf-connecting-ip` on Cloudflare) or the page it came from (`referer`). Its
+// body is the action's input, already read.
+export const REQUEST_TOKEN = new SingleDiToken<Request>('REQUEST_TOKEN');
+
+const NO_SECRETS: ISecrets = {
+  get: (name) => Promise.reject(new Error(`no secrets here: the host runs this module without them (asked for ${name})`)),
+};
+
+/** the env's secrets capability, or the refusal when the host granted none */
+function secretsOf(binding: unknown): ISecrets {
+  const get = (binding as { get?: unknown } | null | undefined)?.get;
+  if (typeof get !== 'function') return NO_SECRETS;
+  return { get: (name) => (binding as ISecrets).get(name) };
+}
+
+// @mosetta/server-action / server — how a coder authors a server-action module. Bundled into a
+// self-contained Web-API monolith and executed in a Worker Loader isolate. DI + decorators
+// are kept (the `@mosetta/di` container is Web-clean — explicit-token injection, no reflect-metadata).
+
+export interface ICreateSchema {
+  builder: typeof z;
+}
+
+export interface IServerActionPayload<TIn> {
+  input: TIn;
+}
+
+/** what an action's `authorize` decides by */
+export interface IServerActionAccess<TIn> {
+  /** the input, parsed and valid */
+  input: TIn;
+  /** what the host vouches for about the caller — its own words — or null: nobody is vouched for */
+  caller: ICaller | null;
+  /** the request the action answers (its body already read into `input`) */
+  request: Request;
+}
+
+export abstract class ServerAction<TIn, TOut> {
+  /**
+   * WHO MAY CALL IT — every action says so, explicitly: a server action is an address anybody can
+   * reach, and nothing in front of it decides for it. `true` lets the call on (open to anyone:
+   * `authorize() { return true; }` — said, not forgotten); `false` refuses it — 401 when nobody is
+   * vouched for, 403 when somebody is. The caller comes in the host's words, and the model of who
+   * may do what is the distribution's own: the framework knows no roles.
+   */
+  abstract authorize(access: IServerActionAccess<TIn>): boolean | Promise<boolean>;
+
+  abstract action({ input }: IServerActionPayload<TIn>): Promise<TOut>;
+
+  abstract createSchema(builder: ICreateSchema): ZodType<TIn>;
+
+  customSerializer(): ServerSerializer | undefined {
+    return undefined;
+  }
+}
+
+// Synthetic per-action DI token (derived from the action name) — how the isolate glue resolves the
+// concrete action out of the request-scoped container.
+export function __createSyntheticServerActionToken<TIn extends {}, TOut>(serverActionName: string) {
+  return new SingleDiToken<ServerAction<TIn, TOut>>(`${serverActionName}_server_action`);
+}
+
+export function DiServerAction<TIn extends {}, TOut>(serverActionToken: ServerActionToken<TIn, TOut>) {
+  return function DiServerActionDecorator(target: Constructable<ServerAction<TIn, TOut>>) {
+    const syntheticToken = __createSyntheticServerActionToken<TIn, TOut>(serverActionToken.actionName);
+    DiService(syntheticToken)(target);
+  };
+}
+
+export interface IServerSideDefinition {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  services: { new (...args: any[]): unknown }[];
+}
+
+// the server-action isolate's env (stamped at compose time)
+export interface IServerActionIsolateEnv {
+  readonly PROVIDER_ORIGIN?: string;
+  readonly PROVIDERS?: unknown;
+  /** the site's tile hosts, `{ key, publicBase }[]` — the primary first (see TILE_HOSTS_TOKEN) */
+  readonly TILE_HOSTS?: unknown;
+  /** the host's secrets capability for this module (see SECRETS_TOKEN) */
+  readonly SECRETS?: unknown;
+}
+
+// what the monolith exports and the transport glue calls (same shape as a router module:
+// every module kind carries its own aspect and exposes fetch)
+export interface IServerSide extends IServerSideDefinition {
+  fetch(request: Request, env?: IServerActionIsolateEnv): Promise<Response>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyAction = ServerAction<any, any>;
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  });
+}
+
+// The WHOLE execution aspect lives HERE and bundles INTO the monolith: fresh DI per
+// request → resolve the action by its synthetic token → parse input (serializer) → Zod-validate →
+// run → serialize. One copy of di per isolate; the coder updates the framework lib (and zod) on
+// their own release cycle — the glue is pure transport. Errors map to 4xx/5xx JSON.
+// Protocol: POST /api/server-action/<full-id>/<actionName>.
+export function defineServerSide({ services }: IServerSideDefinition): IServerSide {
+  return {
+    services,
+    async fetch(request: Request, env?: IServerActionIsolateEnv): Promise<Response> {
+      try {
+        const actionName = new URL(request.url).pathname.split('/').filter(Boolean).pop() ?? '';
+
+        const di = new DiContainer();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        di.registerServices(...(services as any[]));
+
+        // low-level isolate context (NON-secret provider origin). The framework does NOT register
+        // any writable content transport — only a TRUSTED module that includes one in its
+        // `services` has write access.
+        if (env?.PROVIDER_ORIGIN) {
+          di.registerValueOfToken(PROVIDER_ORIGIN_TOKEN, env.PROVIDER_ORIGIN);
+        }
+        // providers: ALWAYS registered (empty list by default) so the transport's injection
+        // never fails; the shape is validated — this is composition data
+        di.registerValueOfToken(PROVIDERS_TOKEN, parseStoreConnectors(env?.PROVIDERS, env as Record<string, unknown> | undefined));
+        di.registerValueOfToken(TILE_HOSTS_TOKEN, tileHostBasesOf(env?.TILE_HOSTS, env?.PROVIDER_ORIGIN));
+        // the caller: what the trust boundary vouches for, in its words (null — nobody)
+        const caller = parseCaller(request.headers.get(IDENTITY_HEADER));
+        di.registerValueOfToken(CALLER_TOKEN, caller);
+        di.registerValueOfToken(SECRETS_TOKEN, secretsOf(env?.SECRETS));
+        di.registerValueOfToken(REQUEST_TOKEN, request);
+
+        let action: AnyAction;
+        try {
+          action = di.getByToken(__createSyntheticServerActionToken(actionName)) as AnyAction;
+        } catch {
+          return json({ error: { code: 'SERVER_ACTION_NOT_FOUND', actionName } }, 404);
+        }
+
+        const serializer: ServerSerializer = action.customSerializer() ?? new JsonServerSerializer();
+        const input = await serializer.parse(request);
+
+        const validation = action.createSchema({ builder: z }).safeParse(input);
+        if (!validation.success) {
+          return json({ error: { code: 'SERVER_ACTION_VALIDATION', issues: validation.error.issues } }, 400);
+        }
+
+        // the action decides who may call it — before it runs, by the valid input and the caller
+        if (!(await action.authorize({ input: validation.data as unknown, caller, request }))) {
+          return caller
+            ? json({ error: { code: 'SERVER_ACTION_FORBIDDEN', actionName } }, 403)
+            : json({ error: { code: 'SERVER_ACTION_UNAUTHORIZED', actionName } }, 401);
+        }
+
+        // the action's TOut is erased at this generic call site — pin to unknown for the serializer
+        const output = (await action.action({ input: validation.data as unknown })) as unknown;
+        const serialized = await serializer.serializeIntoString(output as object);
+        return new Response(serialized.content, {
+          status: 200,
+          headers: { 'content-type': serialized.contentType },
+        });
+      } catch (e) {
+        return json(
+          { error: { code: 'SERVER_ACTION_FAILED', message: String((e as Error)?.message ?? e) } },
+          500,
+        );
+      }
+    },
+  };
+}
+
+export { CALLER_TOKEN, IDENTITY_HEADER, parseCaller } from '../core/core';
+export type { ICaller } from '../core/core';