lecodes-sdk 0.19.0

package/src/server/db/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Type layer: projects a `defineDb({ User: model({...}), … })` literal into marcidb's generic query
+ * types (./marci/query.ts — vendored from marcidb, see scripts/sync-marcidb.ts): each model becomes the
+ * `ModelTypes` bag marcidb's codegen would have emitted, and `db.<model>` is marcidb's own `Query<T>`.
+ * Everything here is type-only; the runtime lives in ./defineDb.ts.
+ *
+ * Naming: `S` = the schema record (model name → Model), `N` = a model name, `F` = a fields record.
+ */
+
+import type { Field, FieldMeta } from "./fields"
+import type {
+  CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue,
+  FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate,
+  RefListUpdateOrdered, RefUpdate, RefUpdateStruct, Rows, Sub, UpdateNumValue, VectorSearch, WhereValue,
+} from "./marci/query"
+
+// ───────────────────────────── schema shapes ─────────────────────────────
+
+export type Fields = Record<string, Field<any, any>>
+export type Model<F extends Fields = Fields> = { readonly fields: F, readonly __model: true }
+export type Schema = Record<string, Model<any>>
+
+export type FieldsOf<M> = M extends Model<infer F> ? F : never
+type TsOf<Fld> = Fld extends Field<infer T, any> ? T : never
+type StructFieldsOf<Fld> = TsOf<Fld> extends Fields ? TsOf<Fld> : never
+type MetaOf<Fld> = Fld extends Field<any, infer M> ? M : never
+type ModelName<S, Fld> = MetaOf<Fld>["model"] & keyof S & string
+
+type Nullable<M extends FieldMeta, T> = M["optional"] extends true ? T | null : T
+type Arr<M extends FieldMeta, T> = M["array"] extends true ? T[] : T
+type IsNum<M extends FieldMeta> = M["scalar"] extends "int" | "float" | "date" ? true : false
+
+// ───────────────────────────── key ─────────────────────────────
+
+/** Explicit `.id()` fields, or a field literally named `id`. */
+type IdKeys<F extends Fields> = { [K in keyof F]: MetaOf<F[K]>["isId"] extends true ? K : K extends "id" ? K : never }[keyof F]
+type IdValue<S, Fld> = MetaOf<Fld>["kind"] extends "one" ? Id<S, ModelName<S, Fld>> : TsOf<Fld>
+
+/** The id object of a model: `{ id: number }` implicitly, or the declared key fields. */
+export type Id<S, N extends keyof S> =
+  [IdKeys<FieldsOf<S[N]>>] extends [never] ? { id: number } : { [K in IdKeys<FieldsOf<S[N]>>]: IdValue<S, FieldsOf<S[N]>[K]> }
+/** What `update`/`delete` accept: the id object, or the bare value when the key is a single scalar. */
+export type IdArg<S, N extends keyof S> = Id<S, N> | (Id<S, N> extends { id: infer V } ? V : never)
+
+// ───────────────────────────── row ─────────────────────────────
+
+type FieldRow<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+  M["kind"] extends "one" ? Nullable<M, Row<S, ModelName<S, Fld>>>
+  : M["kind"] extends "many" | "list" ? Row<S, ModelName<S, Fld>>[]
+  : M["kind"] extends "struct" ? Nullable<M, StructRow<S, StructFieldsOf<Fld>>>
+  : Nullable<M, Arr<M, TsOf<Fld>>>
+
+/** Full row type of a model (relations included) — the `TModel` marcidb's `GetResult` selects from. */
+export type Row<S, N extends keyof S> = Id<S, N> & { [K in Exclude<keyof FieldsOf<S[N]>, IdKeys<FieldsOf<S[N]>>>]: FieldRow<S, FieldsOf<S[N]>[K]> }
+type StructRow<S, F extends Fields> = { [K in keyof F]: FieldRow<S, F[K]> }
+
+type ScalarKeys<F extends Fields> = { [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" ? K : never }[keyof F]
+type NumKeys<F extends Fields> = { [K in keyof F]: IsNum<MetaOf<F[K]>> extends true ? (MetaOf<F[K]>["array"] extends true ? never : K) : never }[keyof F]
+/** What an empty select returns: id + every scalar field. */
+export type Scalars<S, N extends keyof S> = Pick<Row<S, N>, (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>>
+/** The same, as the `{ field: true }` select shape a query starts with. */
+export type ScalarSelect<S, N extends keyof S> = { [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]: true }
+
+// ───────────────────────────── insert ─────────────────────────────
+
+type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+  M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>>
+  : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[]
+  : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>>
+  : Nullable<M, Arr<M, TsOf<Fld>>>
+
+type RequiredKeys<F extends Fields> = {
+  [K in keyof F]: K extends IdKeys<F> ? never
+    : MetaOf<F[K]>["optional"] extends true ? never
+    : MetaOf<F[K]>["hasDefault"] extends true ? never
+    : MetaOf<F[K]>["kind"] extends "many" | "list" ? never
+    : K
+}[keyof F]
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+type InsertOf<S, F extends Fields> = Simplify<
+  { [K in RequiredKeys<F>]: FieldInsert<S, F[K]> } &
+  { [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K]> }
+>
+export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>
+type StructInsert<S, F extends Fields> = InsertOf<S, F>
+
+// ───────────────────────────── update ─────────────────────────────
+
+type FieldUpdate<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+  M["kind"] extends "one" ? Nullable<M, RefUpdate<Id<S, ModelName<S, Fld>>>>     // `{ $connect: { id } }` / null — marcidb's update grammar (bare ids are for insert)
+  : M["kind"] extends "many" ? RefListUpdate<Id<S, ModelName<S, Fld>>>
+  : M["kind"] extends "list" ? RefListUpdateOrdered<Id<S, ModelName<S, Fld>>>
+  : M["kind"] extends "struct" ? RefUpdateStruct<StructInsert<S, StructFieldsOf<Fld>>, UpdateOf<S, StructFieldsOf<Fld>>> | null
+  : M["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>>
+  : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>
+
+type UpdateOf<S, F extends Fields> = { [K in Exclude<keyof F, IdKeys<F>>]?: FieldUpdate<S, F[K]> }
+export type Update<S, N extends keyof S> = UpdateOf<S, FieldsOf<S[N]>>
+
+// ───────────────────────────── select / where / order / query ─────────────────────────────
+
+// A relation also accepts a sub-query built from the related model's collection (`posts: db.post.limit(5)`,
+// `db.post.count()`), branded `Sub<"Post">` so a builder of the wrong model is a type error.
+type FieldSelect<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+  M["kind"] extends "one" ? Select<S, ModelName<S, Fld>> | boolean | Sub<ModelName<S, Fld>>
+  : M["kind"] extends "many" | "list" ? QueryObject<S, ModelName<S, Fld>> | AggregateQuery<S, ModelName<S, Fld>> | boolean | Sub<ModelName<S, Fld>>
+  : M["kind"] extends "struct" ? StructSelect<S, StructFieldsOf<Fld>> | boolean
+  : boolean
+
+export type Select<S, N extends keyof S> = { [K in keyof Row<S, N>]?: K extends keyof FieldsOf<S[N]> ? FieldSelect<S, FieldsOf<S[N]>[K]> : boolean }
+type StructSelect<S, F extends Fields> = { [K in keyof F]?: FieldSelect<S, F[K]> }
+
+type ScalarWhere<T, M extends FieldMeta> =
+  | Nullable<M, CompareValue<T>>
+  | (IsNum<M> extends true ? CompareNumValue<T> : M["scalar"] extends "string" ? CompareStrValue<T> : never)
+
+type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+  M["kind"] extends "one" ? CompareRefValue<Where<S, ModelName<S, Fld>> | null>
+  : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>>
+  : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null>
+  : M["kind"] extends "json" ? JsonPathWhere | JsonCondition
+  : M["array"] extends true ? CompareValue<TsOf<Fld>>
+  : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>
+
+type WhereFieldsOf<S, F extends Fields> = { [K in keyof F]?: FieldWhere<S, F[K]> }
+type IdWhere<S, N extends keyof S> = { [K in keyof Id<S, N> as K extends keyof FieldsOf<S[N]> ? never : K]?: CompareValue<Id<S, N>[K]> | CompareNumValue<number> }
+export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S[N]>> & IdWhere<S, N>>
+type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>
+
+export type Order<S, N extends keyof S> = { [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]?: "asc" | "desc" }
+
+/** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
+export type QueryObject<S, N extends keyof S> = Select<S, N> & {
+  $where?: Where<S, N>
+  $order?: Order<S, N>
+  $limit?: number
+  $skip?: number
+  $cursor?: Id<S, N>
+}
+
+export type AggregateQuery<S, N extends keyof S> = {
+  $where?: Where<S, N>
+  $count?: true
+  $sum?: NumKeys<FieldsOf<S[N]>> & string
+  $avg?: NumKeys<FieldsOf<S[N]>> & string
+  $min?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
+  $max?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
+}
+
+// ───────────────────────────── query / db ─────────────────────────────
+
+/** The per-model type bag marcidb's generic `Query<T>` is parametrised by (what its codegen emits as `UserTypes`). */
+export type Types<S, N extends keyof S> = {
+  name: N & string
+  model: Row<S, N>
+  id: Id<S, N>
+  scalars: ScalarSelect<S, N>
+  select: Select<S, N>
+  query: QueryObject<S, N>
+  where: Where<S, N>
+  order: Order<S, N>
+  insert: Insert<S, N>
+  update: Update<S, N>
+  aggregate: AggregateQuery<S, N>
+  reindex: false
+}
+
+/**
+ * `db.<model>` — marcidb's lazy, immutable query over one model: clauses (`where/order/limit/skip/after`)
+ * return a new query, `select(shape)` sets the projection, `await` runs it, `first/count/aggregate` terminate,
+ * `updateMany(data)`/`deleteMany()` write through the chain's `where`; a query placed in another query's
+ * select is a sub-query. `Sel` is the projection: id + scalars until `select(...)` sets a shape.
+ */
+export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>> = MarciQuery<Types<S, N>, Sel>
+/** The rows a query with projection `Q` resolves to (no field keys = id + scalars; sub-queries resolved). */
+export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>
+/** `db.<model>` — the root query of a model. */
+export type Collection<S, N extends keyof S> = Query<S, N>
+
+export type Db<S extends Schema> = {
+  [N in keyof S & string as Uncapitalize<N>]: Query<S, N>
+} & {
+  /** Atomic batch: all ops commit or none. `ref("0.id")` feeds a generated id into a later op. */
+  $transaction<P extends readonly Op<any>[]>(ops: [...P]): Promise<{ [K in keyof P]: P[K] extends Op<infer T> ? T : never }>
+  /** The `.marci` schema text this db syncs with. */
+  readonly $schema: string
+  /** @internal */ readonly $models: Record<string, Model>
+  /** @internal which models the auth runtime binds to (`Session` always exists; `User` when declared). */
+  readonly $auth: AuthBinding
+}
+/** @internal */
+export type AuthBinding = { user: string | null, session: string }
+
+// ───────────────────────────── relation-name validation ─────────────────────────────
+
+type RelKinds = "one" | "many" | "list"
+type CheckField<S, Fld> =
+  MetaOf<Fld>["kind"] extends RelKinds
+    ? MetaOf<Fld>["model"] extends keyof S ? Fld : `Unknown model "${MetaOf<Fld>["model"]}" — not a key of defineDb({...})`
+    : Fld
+/** Intersected with `S` in `defineDb`'s parameter: an unknown relation target fails to type-check on that field. */
+export type ValidateRefs<S extends Schema> = { [N in keyof S]: { readonly fields: { [K in keyof FieldsOf<S[N]>]: CheckField<S, FieldsOf<S[N]>[K]> } } }

package/src/server/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * `throw new ApiError(404, "Not found")` inside an endpoint → the client's promise rejects with the
+ * same status + message. Any other throw is a 500 (message hidden, logged to the server console).
+ */
+export class ApiError extends Error {
+  readonly status: number
+  constructor(status: number, message = "") {
+    super(message)
+    this.name = "ApiError"
+    this.status = status
+  }
+}

package/src/server/host.ts

@@ -0,0 +1,74 @@
+/**
+ * `sdk/server` — the HOST side of the app backend, imported normally by the runner
+ * (packages/lecodes-runner), the backend and tests. Nothing here is bundled into project code; the
+ * bundle carries its own SDK copy and meets this module only through the `globalThis.__lecodes*`
+ * seams (see ./runtime.ts).
+ */
+
+export {
+  loadServerModules, createInvoker, createJoinGuard, setChannelPublisher, setRequestProvider,
+} from "./runtime"
+export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
+export type { RequestContext } from "./context"
+export { setDbTransport } from "./db/defineDb"
+export { marciHttpTransport, marciRequest, encodeMarciId, MarciHttpError } from "./db/httpTransport"
+export type { MarciHttpOptions } from "./db/httpTransport"
+export type { MarciOp, MarciTransport } from "./db/marci/query"
+export type { ServerManifest, ServerExport } from "../compile/serverSplit"
+export { validateArgs, ValidationError } from "./validate"
+export type { ParamSchema, Schema as ParamSchemaNode } from "./validate"
+export { createAuthHost, signNonce, verifyNonce, sha256 } from "./auth/host"
+export type { AuthHost, AuthHostConfig, AuthMail } from "./auth/host"
+export type { AuthUser, AuthState, AuthOps, OAuthProfile, OAuthCredential } from "./auth/types"
+export type { AuthProvider, AppConfig } from "./auth/appConfig"
+
+import type { LoadedServer } from "./runtime"
+import type { Field, FieldDef } from "./db/fields"
+import type { Model } from "./db/types"
+
+/** JSON view of one field for the platform (Data tab, docs): `FieldDef` with nested struct fields flattened
+ *  to defs and functions/undefineds dropped. */
+export type FieldDescription = Omit<FieldDef, "fields" | "default"> & { fields?: Record<string, FieldDescription>, default?: unknown }
+
+/** What the runner reports to the platform after loading a bundle: schema text + models + the
+ *  endpoint/channel lists (with the manifest's param schemas). */
+export type ServerDescription = {
+  /** `.marci` schema text ("" when the project defines no db). */
+  marci: string
+  models: Record<string, { fields: Record<string, FieldDescription> }>
+  endpoints: { id: string, params: unknown[] | null }[]
+  channels: string[]
+  /** Which models the auth runtime binds to (`null` = the project has no db) and the app.json providers. */
+  auth: { user: string | null, session: string | null, providers: string[] }
+  /** `app.json` name (when the compile embedded one). */
+  appName?: string
+}
+
+const describeField = (f: Field<any, any>): FieldDescription => {
+  const def = f.def
+  const out: FieldDescription = { ...def, fields: undefined, default: undefined }
+  delete out.fields
+  delete out.default
+  if (def.hasDefault) out.default = def.default === undefined ? null : def.default
+  if (def.fields) out.fields = Object.fromEntries(Object.entries(def.fields).map(([k, v]) => [k, describeField(v)]))
+  return JSON.parse(JSON.stringify(out))
+}
+
+export const describeServer = (server: LoadedServer): ServerDescription => {
+  const db = server.dbs[0]
+  const models: ServerDescription["models"] = {}
+  if (db) {
+    for (const [name, m] of Object.entries(db.$models as Record<string, Model>)) {
+      models[name] = { fields: Object.fromEntries(Object.entries(m.fields as Record<string, Field<any, any>>).map(([k, f]) => [k, describeField(f)])) }
+    }
+  }
+  const params = (server.manifest.params ?? {}) as Record<string, unknown[]>
+  return {
+    marci: db?.$schema ?? "",
+    models,
+    endpoints: [...server.endpoints.keys()].map(id => ({ id, params: params[id] ?? null })),
+    channels: [...server.channels.keys()],
+    auth: { user: db?.$auth.user ?? null, session: db?.$auth.session ?? null, providers: server.manifest.app?.auth?.providers ?? [] },
+    appName: server.manifest.app?.name,
+  }
+}

package/src/server/inject.ts

@@ -0,0 +1,13 @@
+/*
+ * The SERVER inject module — the globals available in `*.server.ts` files (docs/backend-plan.md §4).
+ * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
+ * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
+ *
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, request, auth.
+ */
+
+export { t, model, defineDb, ref } from "./db"
+export { ApiError } from "./errors"
+export { channel } from "./channel"
+export { request } from "./context"
+export { auth } from "./auth/global"

package/src/server/runtime.ts

@@ -0,0 +1,133 @@
+/**
+ * Host side of a compiled server bundle — used by the runner (packages/lecodes-runner) and by tests.
+ * Imported normally (Node/Bun), NOT through chisel: the bundle carries its own SDK copy and talks
+ * to this module only through globals (`__lecodesServer`, `__lecodesRequest`, `__lecodesPublish`).
+ *
+ *   evaluate the bundle (it sets globalThis.__lecodesServer)
+ *   const server = loadServerModules()          // classify exports, name channels
+ *   const invoke = createInvoker(server)        // validate → run in request context → envelope
+ *   await invoke("notes.server.ts#listNotes", [20], { headers, ip })
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { ServerManifest } from "../compile/serverSplit"
+import type { AuthHost } from "./auth/host"
+import type { AuthState } from "./auth/types"
+import { setChannelPublisher, type Channel } from "./channel"
+import { setRequestProvider, type RequestContext } from "./context"
+import type { Db } from "./db/types"
+import { takeRegisteredDbs } from "./db/defineDb"
+import { validateArgs, ValidationError, type ParamSchema } from "./validate"
+
+export type ServerRegistration = { modules: Record<string, Record<string, unknown>>, manifest: ServerManifest }
+
+export type LoadedServer = {
+  endpoints: Map<string, (...args: any[]) => unknown>
+  channels: Map<string, Channel<any>>
+  /** Every `defineDb` handle — exported or not (the bundle registers them on globalThis; normally exactly one). */
+  dbs: Db<any>[]
+  manifest: ServerManifest
+}
+
+const isDb = (v: unknown): v is Db<any> => typeof v === "object" && v !== null && typeof (v as Db<any>).$schema === "string"
+const isChannel = (v: unknown): v is Channel<any> => typeof v === "object" && v !== null && (v as Channel<any>).__channel === true
+
+/** Read the registration a server bundle left on `globalThis.__lecodesServer` (or a given one). */
+export const loadServerModules = (
+  reg: ServerRegistration | undefined = (globalThis as any).__lecodesServer,
+): LoadedServer => {
+  if (!reg) throw new Error("loadServerModules: no server bundle registered (globalThis.__lecodesServer)")
+  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), dbs: [], manifest: reg.manifest }
+  for (const [mod, exports] of Object.entries(reg.modules)) {
+    for (const [name, value] of Object.entries(exports)) {
+      const id = `${mod}#${name}`
+      if (typeof value === "function") out.endpoints.set(id, value as (...args: any[]) => unknown)
+      else if (isChannel(value)) { value.__id = id; out.channels.set(id, value) }
+      else if (isDb(value)) out.dbs.push(value)
+    }
+  }
+  // Non-exported handles (`const db = defineDb(...)`): the bundle's SDK copy registered them on globalThis.
+  for (const db of takeRegisteredDbs()) if (!out.dbs.includes(db)) out.dbs.push(db)
+  return out
+}
+
+/** The wire envelope. `session` = a token the client must store from now on (new guest session / rotation). */
+export type InvokeResult =
+  | { ok: true, result: unknown, session?: string }
+  | { ok: false, status: number, message: string, session?: string }
+
+export type InvokerOptions = {
+  /** Validate args against the manifest's param schemas (default true; endpoints without a schema pass). */
+  validate?: boolean
+  /** Where unexpected (non-ApiError) failures are reported. Default: console.error. */
+  onError?: (id: string, error: unknown) => void
+  /** The auth host (./auth/host.ts): resolves the bearer token into `ctx.auth` before each call. Absent = no sessions. */
+  auth?: AuthHost | null
+}
+
+// The bundle's ApiError is a different class object than ours (its own SDK copy) — duck-type it.
+const apiStatus = (e: unknown): number | null =>
+  e && typeof e === "object" && (e as { name?: string }).name === "ApiError" && typeof (e as { status?: unknown }).status === "number"
+    ? (e as { status: number }).status : null
+
+/**
+ * Build the invoker: `invoke(id, args, ctx)` runs endpoint `id` inside an AsyncLocalStorage-scoped
+ * request context (what the `request`/`auth` globals read) and returns the wire envelope.
+ */
+// One request store for endpoints AND channel guards (a second store would steal the provider).
+const als = new AsyncLocalStorage<RequestContext>()
+const installProvider = () => setRequestProvider(() => als.getStore())
+
+// A token minted/rotated during the call rides on the envelope (the client transport stores it).
+const withSession = (r: InvokeResult, rc: RequestContext): InvokeResult => {
+  const issued = (rc.auth as AuthState | undefined)?.issuedToken
+  return issued ? { ...r, session: issued } : r
+}
+
+export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) => {
+  installProvider()
+  const validate = opts.validate ?? true
+  const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
+  const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
+  const auth = opts.auth ?? null
+
+  return async (id: string, args: unknown[], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+    const fn = server.endpoints.get(id)
+    if (!fn) return { ok: false, status: 404, message: `Unknown endpoint ${id}` }
+    if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
+    const rc: RequestContext = { ...ctx, id }
+    try {
+      if (validate && params?.[id]) validateArgs(params[id], args)
+      if (auth) await auth.resolve(rc)
+      const result = await als.run(rc, () => fn(...args))
+      return withSession({ ok: true, result: result === undefined ? null : result }, rc)
+    } catch (e) {
+      const status = apiStatus(e)
+      if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
+      if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
+      onError(id, e)
+      return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
+    }
+  }
+}
+
+/** Run a channel's `onJoin` guard for a subscription (same request scoping as endpoints). */
+export const createJoinGuard = (server: LoadedServer, opts: Pick<InvokerOptions, "auth"> = {}) => {
+  installProvider()
+  const auth = opts.auth ?? null
+  return async (channelId: string, topic: string, ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+    const ch = server.channels.get(channelId)
+    if (!ch) return { ok: false, status: 404, message: `Unknown channel ${channelId}` }
+    const rc: RequestContext = { ...ctx, id: channelId }
+    try {
+      if (auth) await auth.resolve(rc)
+      await als.run(rc, () => ch.options.onJoin?.(topic))
+      return withSession({ ok: true, result: null }, rc)
+    } catch (e) {
+      const status = apiStatus(e)
+      return withSession({ ok: false, status: status ?? 500, message: status !== null ? (e as Error).message : "Internal error" }, rc)
+    }
+  }
+}
+
+export { setChannelPublisher, setRequestProvider }

package/src/server/validate.ts

@@ -0,0 +1,87 @@
+/**
+ * Runtime validation of endpoint arguments against the compact schemas the compiler derives from the
+ * TypeScript parameter types (src/compile/serverTypes.ts). Dependency-free; the schema is JSON so it
+ * travels inside the server bundle's manifest.
+ */
+
+export type Schema =
+  | { t: "any" }
+  | { t: "string" } | { t: "number" } | { t: "boolean" } | { t: "null" } | { t: "undefined" }
+  | { t: "lit", v: string | number | boolean }
+  | { t: "array", of: Schema }
+  | { t: "tuple", items: Schema[], rest?: Schema }
+  | { t: "object", props: Record<string, Schema>, optional?: string[], index?: Schema }
+  | { t: "union", of: Schema[] }
+
+/** One endpoint parameter: its schema and whether it may be omitted (`?`, default value, rest). */
+export type ParamSchema = { name: string, schema: Schema, optional?: boolean, rest?: boolean }
+
+export class ValidationError extends Error {
+  readonly status = 400
+  constructor(message: string) { super(message); this.name = "ValidationError" }
+}
+
+const typeName = (v: unknown) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v
+
+/** Returns the first problem as a message, or null when `value` matches. */
+export const check = (schema: Schema, value: unknown, path: string): string | null => {
+  switch (schema.t) {
+    case "any": return null
+    case "string": case "number": case "boolean":
+      return typeof value === schema.t ? null : `${path}: expected ${schema.t}, got ${typeName(value)}`
+    case "null": return value === null ? null : `${path}: expected null, got ${typeName(value)}`
+    case "undefined": return value === undefined ? null : `${path}: expected undefined, got ${typeName(value)}`
+    case "lit": return value === schema.v ? null : `${path}: expected ${JSON.stringify(schema.v)}, got ${JSON.stringify(value)}`
+    case "array":
+      if (!Array.isArray(value)) return `${path}: expected array, got ${typeName(value)}`
+      for (let i = 0; i < value.length; i++) { const e = check(schema.of, value[i], `${path}[${i}]`); if (e) return e }
+      return null
+    case "tuple": {
+      if (!Array.isArray(value)) return `${path}: expected tuple, got ${typeName(value)}`
+      if (value.length < schema.items.length || (!schema.rest && value.length > schema.items.length))
+        return `${path}: expected ${schema.items.length} items, got ${value.length}`
+      for (let i = 0; i < value.length; i++) {
+        const s = i < schema.items.length ? schema.items[i] : schema.rest!
+        const e = check(s, value[i], `${path}[${i}]`); if (e) return e
+      }
+      return null
+    }
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) return `${path}: expected object, got ${typeName(value)}`
+      const obj = value as Record<string, unknown>
+      const optional = new Set(schema.optional ?? [])
+      for (const [k, s] of Object.entries(schema.props)) {
+        if (!(k in obj) || obj[k] === undefined) { if (optional.has(k)) continue; return `${path}.${k}: required` }
+        const e = check(s, obj[k], `${path}.${k}`); if (e) return e
+      }
+      for (const k of Object.keys(obj)) {
+        if (k in schema.props) continue
+        if (schema.index) { const e = check(schema.index, obj[k], `${path}.${k}`); if (e) return e }
+        // unknown keys without an index signature are ignored (structural typing)
+      }
+      return null
+    }
+    case "union": {
+      const errors: string[] = []
+      for (const s of schema.of) { const e = check(s, value, path); if (!e) return null; errors.push(e) }
+      return `${path}: no union member matched (${errors.join("; ")})`
+    }
+  }
+}
+
+/** Validate a positional argument list. Extra arguments are ignored (JS call semantics). */
+export const validateArgs = (params: ParamSchema[], args: unknown[]): void => {
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i]
+    if (p.rest) {
+      const rest = args.slice(i)
+      const e = check(p.schema, rest, p.name)
+      if (e) throw new ValidationError(e)
+      return
+    }
+    const v = args[i]
+    if (v === undefined) { if (p.optional) continue; throw new ValidationError(`${p.name}: required`) }
+    const e = check(p.schema, v, p.name)
+    if (e) throw new ValidationError(e)
+  }
+}