@fougere/app 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/client.ts

@@ -1,17 +1,6 @@
 /**
- * The couple, minus the reactivity — everything `useQuery`/`useCommand` decide
- * before a framework's state primitives get involved.
- *
- * Designation is class + verb: the imported entity class carries the metadata,
- * its name carries the registration key. That is true in Vue and in React, and so
- * is the link — a successful command on an entity revalidates every mounted query
- * on that entity, because the entity is designated on both sides and nothing has
- * to be declared. What differs between hosts is only HOW a value becomes reactive
- * and how a revalidation is triggered, which is ~50 lines each and belongs to them.
- *
- * Browser-safe by construction: this module reaches `@fougere/core/contract` and
- * the transport's client subpath, never the boot. `@fougere/app/client` is the
- * subpath that keeps it that way.
+ * The couple, minus the reactivity — everything `useQuery`/`useCommand` decide before a
+ * framework's state primitives get involved.
  */
 import {
   FougereError,
@@ -26,7 +15,7 @@ import { frameCall, unframeResponse, type RpcResponse } from '@fougere/transport
 export type EntityClass = { name: string };
 
 /** What a page provides of an invocation — the rest is stamped server-side. */
-export type CallInput = Partial<Pick<InvocationContext, 'params' | 'query' | 'body'>>;
+export type CallInput = Partial<Pick<InvocationContext, 'params' | 'query' | 'input'>>;
 
 /** The one door the browser knows. A named surface adds `/{surface}` to it. */
 export const CALL_ENDPOINT = '/_fougere/call';
@@ -45,14 +34,10 @@ export function callOf(entity: EntityClass, op: string): FrondCall {
 }
 
 export function invocationOf(input?: CallInput): InvocationContext {
-  return { params: {}, query: {}, body: undefined, state: {}, ...input };
+  return { params: {}, query: {}, input: undefined, state: {}, ...input };
 }
 
-/**
- * The cache key of a read. Same designation and same input means the same key —
- * which is what lets two components asking the same thing share one request, and
- * what the command side matches against to revalidate.
- */
+/** The cache key of a read. */
 export function queryKeyOf(entityKey: string, op: string, input?: CallInput): string {
   return `fougere:${entityKey}.${op}:${JSON.stringify(input ?? {})}`;
 }
@@ -88,14 +73,7 @@ export function mountedKeys(entityKey: string): string[] {
   return [...(mounted.get(entityKey) ?? [])];
 }
 
-/**
- * `mountedKeys` says WHICH reads a command invalidates; these say how to make one
- * happen. Both halves turned out to be host-independent — Nuxt is the exception,
- * because `refreshNuxtData` already is this registry.
- *
- * They lived in `@fougere/react` until a second non-Nuxt client needed them, which
- * is when it became visible that nothing in them is React.
- */
+/** `mountedKeys` says WHICH reads a command invalidates; these say how to make one happen. */
 const refetchers = new Map<string, Set<() => void>>();
 
 /** Register a mounted read's refetch. Returns the unregistration. */
@@ -135,11 +113,7 @@ export function pageOf(data: unknown): { total?: number; hasMore?: boolean; endC
   return (data ?? {}) as { total?: number; hasMore?: boolean; endCursor?: string };
 }
 
-/**
- * Whatever failed, as the error the primitives promise. A transport failure is not
- * a domain refusal, so it arrives under SERVICE_UNAVAILABLE rather than borrowing a
- * code the server never sent.
- */
+/** Whatever failed, as the error the primitives promise. */
 export function asFougereError(err: unknown, entityKey: string, op: string): FougereError {
   return err instanceof FougereError
     ? err

package/src/express.ts

@@ -1,35 +1,4 @@
-/**
- * The doors as Express middlewares — the form an Express app expects.
- *
- * ```ts
- * const app = express();
- * app.use(express.json());
- * app.use(fougere());          // ← one line, like cors() or express.json()
- * ```
- *
- * This replaces an earlier `mountDoors(createExpressRouter(app))`, which was wrong in
- * two ways at once. It handed the app INTO a function instead of adding something to
- * the app, and it made the caller name Express 5's wildcard syntax (`/api/*splat`) —
- * a detail that belongs to the framework, not to its user. Worse, it mounted all
- * three doors together with no way to take two of them.
- *
- * A middleware fixes both by construction, because Express already says WHERE:
- *
- * ```ts
- * app.use(fougere());                 // the three doors, at the paths the client knows
- * app.use('/admin', fougereRest());   // REST only, wherever you want it
- * ```
- *
- * And `next()` is the passthrough these doors were already imitating: `serveRest`
- * answers `{ kind: 'pass' }` for a path it does not serve, which is exactly what
- * Express means by calling the next handler. The middleware stops inventing it.
- *
- * The names mirror `@fougere/app/web` on purpose — same doors, host-shaped. `/web`
- * gives you `Request` → `Response` handlers; this gives you middlewares.
- *
- * Nothing here imports express: the shapes are structural, so the package keeps its
- * dependency list and a test can hand it a plain object.
- */
+/** The doors as Express middlewares — the form an Express app expects. */
 import { readExpressBody } from '@fougere/http';
 import { serveRest, serveRpc, rpcParseError } from './serve.js';
 import { serveGraphQL } from './graphql.js';
@@ -59,14 +28,7 @@ interface ExpressResponse {
 type Next = (err?: unknown) => void;
 export type ExpressMiddleware = (req: any, res: any, next: Next) => void;
 
-/**
- * Who the caller is, from what ran before.
- *
- * Express has no ambient request, so an app that resolves its own session says so by
- * putting it on the request — `req.fougereState`, or a bare `req.user`, which is what
- * passport and most middlewares already set. Nothing is taken from the payload: the
- * browser sits outside the topology.
- */
+/** Who the caller is, from what ran before. */
 function stateOf(req: ExpressRequest): Record<string, unknown> {
   if (req.fougereState) return req.fougereState;
   return req.user ? { user: req.user } : {};
@@ -95,12 +57,7 @@ function fail(res: ExpressResponse, next: Next, err: unknown): void {
   next(err);
 }
 
-/**
- * The call envelope, at `/_fougere/call` — the door the browser primitives use.
- *
- * Mounted with `app.use()`, Express strips nothing, so the path still carries the
- * audience segment (`/_fougere/call/public`) that `surfaceOf` reads.
- */
+/** The call envelope, at `/_fougere/call` — the door the browser primitives use. */
 export function fougereCall(mountPath = '/_fougere/call'): ExpressMiddleware {
   return (req, res, next) => {
     const path = pathOf(req);
@@ -132,12 +89,7 @@ export function fougereSession(mountPath = '/_fougere/session'): ExpressMiddlewa
   };
 }
 
-/**
- * The REST projection, under `/api` by default.
- *
- * A path this app does not serve calls `next()` — so an app's own `/api/health` keeps
- * answering whether it was registered before or after this middleware.
- */
+/** The REST projection, under `/api` by default. */
 export function fougereRest(mountPath = '/api'): ExpressMiddleware {
   return (req, res, next) => {
     const path = pathOf(req);

package/src/form.ts

@@ -1,30 +1,15 @@
 import { Lifecycle } from '@fougere/schema';
 /**
- * Form contract, pure part — derives what a create/edit form is made of
- * from the entity's field axes. No Vue, no Nuxt: testable headless,
- * usable by any renderer (the page owns the widgets).
+ * Form contract, pure part — derives what a create/edit form is made of from the entity's field
+ * axes.
  */
-import { Anatomy, lowerFirst, Role, Visibility } from '@fougere/schema';
+import { Shapes, lowerFirst, Role, Visibility } from '@fougere/schema';
 import type { Field, SchemaView, ValidationError, ValidationResult } from '@fougere/schema';
 
-/**
- * What an entity class exposes to a form — the schema statics it already has.
- *
- * `SchemaView` and the real `Field`, not a local re-description of the axes: this file
- * used to declare its own `FieldLike` with `shape?` optional, so it kept judging by a
- * looser contract than the schema's own and would never have seen `shape` become
- * required.
- */
+/** What an entity class exposes to a form — the schema statics it already has. */
 export type FormEntity = SchemaView;
 
-/**
- * The literal a field is born with, when it declares one.
- *
- * `text({ default: 'x' })` and `oneOf('a', 'b', { default: 'a' })` both compile to
- * `lifecycle.create = { value }` — the create rule that answers the field's absence.
- * The other create rules ('now', { generate }, 'optional') name no literal: their value
- * is decided at write time, so a form has nothing to show for them.
- */
+/** The literal a field is born with, when it declares one. */
 function defaultOf(field: Field): unknown {
   return Lifecycle.of(field).literal?.value;
 }
@@ -41,28 +26,8 @@ export interface FormField {
   /** Enum values, when control is 'select'. */
   options?: string[];
   /**
-   * What the browser enforces, under the names it already knows — spread this on the
-   * input and the page states no rule of its own.
-   *
-   * The shape holds `minLength`/`maximum`/`pattern`; a browser holds `minlength`/
-   * `max`/`pattern` and enforces them with no JavaScript at all. Carrying them here
-   * is a projection, not a second rule: the judge reads the same shape, and a form
-   * that ignores these still gets the same verdict — it just gets it later, and a
-   * screen reader never gets it at all.
-   *
-   * `type` is part of the contract, not decoration: `email` and `url` are formats the
-   * shape states and the browser checks live, per field, as one types. A page writing
-   * `type="email"` by hand is spelling a second time what the card already said.
-   *
-   * Three deliberate absences, each one a place where the attribute would mean
-   * something the shape does not say:
-   * - a `date` field gets no `type` — neither `date` nor `datetime-local` produces the
-   *   RFC 3339 string a `date-time` shape judges, so the browser would accept what the
-   *   judge refuses;
-   * - `select` and `boolean` are not inputs — the page picks the widget, `control` says
-   *   which;
-   * - a required `boolean` gets no `required` — on a checkbox that attribute means
-   *   "must be CHECKED", where the shape only says the value must be supplied.
+   * What the browser enforces, under the names it already knows — spread this on the input and the
+   * page states no rule of its own.
    */
   attrs?: {
     type?: 'text' | 'email' | 'url' | 'number';
@@ -73,11 +38,7 @@ export interface FormField {
     max?: number;
     pattern?: string;
   };
-  /**
-   * The value the field is born with — the literal its `lifecycle.create` rule names.
-   * Present so the form can SHOW what is about to be written; the storage realizes it
-   * either way, so a form that ignores this still produces the same row.
-   */
+  /** The value the field is born with — the literal its `lifecycle.create` rule names. */
   default?: unknown;
 }
 
@@ -87,7 +48,7 @@ function baseType(type: unknown): string {
   return (type as string) ?? 'string';
 }
 
-/** The formats a browser has an input type for — the rest stay `text`, judged later. */
+/** The formats a browser has an input type for — the rest stay `text`, validated later. */
 const CONTROL_BY_FORMAT: Record<string, FormField['control']> = {
   'date-time': 'date',
   email: 'email',
@@ -98,7 +59,7 @@ function controlOf(field: Field): FormField['control'] {
   // Through `anatomy`, never `shape.type` directly: the nullable form is the `[T,'null']`
   // union, which a direct comparison misses in silence. It is also what narrows the shape
   // union, so `enum` and `format` are only reachable on the branches that carry them.
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   if (base?.type === 'string' && base.enum?.length) return 'select';
   if (base?.type === 'number' || base?.type === 'integer') return 'number';
   if (base?.type === 'boolean') return 'boolean';
@@ -108,7 +69,7 @@ function controlOf(field: Field): FormField['control'] {
 
 /** A closed set's members, when the shape declares one — `oneOf('draft','live')`. */
 function enumOf(field: Field): readonly (string | null)[] | undefined {
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   return base?.type === 'string' ? base.enum : undefined;
 }
 
@@ -117,7 +78,7 @@ const INPUT_TYPES = new Set(['text', 'email', 'url', 'number']);
 
 /** The shape's bounds, under the names a browser already enforces. */
 function attrsOf(field: Field, control: FormField['control'], required: boolean): NonNullable<FormField['attrs']> {
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   const text = base?.type === 'string' ? base : undefined;
   const numeric = base?.type === 'number' || base?.type === 'integer' ? base : undefined;
   const attrs = {
@@ -140,11 +101,7 @@ function labelOf(name: string, entityKey: string): Pick<FormField, 'labelKey' |
   return { labelKey: `${entityKey}.${name}`, label: name.charAt(0).toUpperCase() + name.slice(1) };
 }
 
-/**
- * The fields a create form is made of: membership from the io projection
- * (`Visibility.input` — what a client may supply), requiredness from the
- * lifecycle axis (any create rule makes absence legal).
- */
+/** The fields a create form is made of. */
 export function formFieldsOf(entity: FormEntity, entityKey: string): FormField[] {
   return Object.entries(Visibility.of(entity.getFields()).input).map(([name, field]) => {
     const f = field;
@@ -175,18 +132,14 @@ export interface TableColumn {
   /** The same key a form uses for the same field — one convention, two projections. */
   labelKey: string;
   label: string;
-  /**
-   * The entity a `link` points at, under the key its door is named by. Always present on a
-   * reference: the card carries the target's name, and a card rebuilt with no sibling to
-   * resolve to keeps it as a stand-in rather than losing it.
-   */
+  /** The entity a `link` points at, under the key its door is named by. */
   to?: string;
 }
 
 /** Asked of the relation before the shape: a reference's own shape is a bare string. */
 function renderOf(field: Field): TableColumn['render'] {
   if (Role.of(field).isReference) return 'link';
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   if (base?.type === 'number' || base?.type === 'integer') return 'number';
   if (base?.type === 'boolean') return 'boolean';
   if (base?.type === 'object' || base?.type === 'array') return 'json';
@@ -194,13 +147,7 @@ function renderOf(field: Field): TableColumn['render'] {
   return 'text';
 }
 
-/**
- * The columns a list is made of: membership from the io projection (`Visibility.output` — what
- * may leave), minus collections, because a cell holds one value and a `many()` is a page.
- *
- * Which column identifies the row is NOT answered here — `FieldSet.primary` answers it for a
- * shape, and its own doc records what five private copies of that loop cost.
- */
+/** The columns a list is made of. */
 export function tableColumnsOf(entity: FormEntity, entityKey: string): TableColumn[] {
   return Object.entries(Visibility.of(entity.getFields()).output)
     .filter(([, field]) => !Role.of(field).isCollection)
@@ -216,9 +163,9 @@ export function tableColumnsOf(entity: FormEntity, entityKey: string): TableColu
 }
 
 /**
- * The wire body of the form's values — an empty control is an absent value
- * at the create boundary (absence is judged by the lifecycle axis, an empty
- * string would be judged as a present bad value).
+ * The wire body of the form's values — an empty control is an absent value at the create boundary
+ * (absence is validated by the lifecycle axis, an empty string would be validated as a present bad
+ * value).
  */
 export function payloadOf(values: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(
@@ -226,7 +173,7 @@ export function payloadOf(values: Record<string, unknown>): Record<string, unkno
   );
 }
 
-/** Index judge errors by field — local judge and remote judge share this shape. */
+/** Index validator errors by field — local validator and remote validator share this shape. */
 export function errorsByField(errors: ValidationError[]): Record<string, string> {
   const byField: Record<string, string> = {};
   for (const err of errors) {

package/src/graphql.ts

@@ -1,25 +1,4 @@
-/**
- * The GraphQL door — declared like the others, mounted like the others.
- *
- * Until now GraphQL was the odd one out: `adapters: { graphql: true }` was
- * declarable and nothing read it, while an app that wanted a schema wrote fifteen
- * lines of its own (a Pothos builder, a query type, a mutation type, `registerAll`,
- * then `registerGraphQL` on a router). Every one of those lines is convention —
- * there is no decision in them — so the app declaring the adapter is enough.
- *
- * The package is imported LAZILY, the same shape `db: 'sqlite'` uses (`resolveStorage`
- * pulls `@fougere/adapter-sql` only when a database is declared). A schema builder is
- * heavy and most apps serve none, so a host must not carry one to find out. Declaring
- * the adapter without installing it is refused by name, the way an unresolvable dialect is.
- *
- * This file used to BUILD the schema — a Pothos builder, `registerAll`, then `graphql()`
- * — which made it the only schema constructor in the repo, in the package least entitled
- * to be one. Two costs, one cause: the derivation sat away from the adapter whose job it
- * is, and `graphql` guards its types with `instanceOf`, so a schema built on one side of
- * the package boundary was refused on the other as coming *"from another module or
- * realm"*. Both are gone: `@fougere/adapter-graphql` derives and executes, this door
- * translates the result into an `Outcome`.
- */
+/** The GraphQL door — declared like the others, mounted like the others. */
 import type { App } from '@fougere/core';
 import type { Outcome } from './serve.js';
 
@@ -56,12 +35,7 @@ async function executor(): Promise<ExecuteOn> {
   }
 }
 
-/**
- * Execute a GraphQL request against the app's own operations.
- *
- * `pass` when the app declares no GraphQL adapter — the same answer `serveRest` gives,
- * so a host that mounted the door takes nothing away from an app that did not ask for it.
- */
+/** Execute a GraphQL request against the app's own operations. */
 export async function serveGraphQL(app: App, request: GraphQLRequest): Promise<Outcome> {
   if (!app.adapters?.graphql) return { kind: 'pass' };
 

package/src/index.ts

@@ -1,14 +1,4 @@
-/**
- * `@fougere/app` — what an app host needs and what no host owns.
- *
- * Two adapters read this package: `@fougere/nuxt` and `@fougere/next`. Between
- * them they share the boot, the three doors' decisions, the REST table, the form
- * contract and the session view; what they do NOT share is how a request arrives,
- * how routes are mounted, and how a value becomes reactive.
- *
- * The root entry pulls in the boot, which reads the filesystem — client code wants
- * `@fougere/app/client`.
- */
+/** `@fougere/app` — what an app host needs and what no host owns. */
 export {
   configureFougere,
   extendFougere,

package/src/rest.ts

@@ -1,12 +1,4 @@
-/**
- * The REST table this app serves, and the rule that matches a request against it.
- *
- * Separated from the h3 handler on purpose: this file holds the whole of what the door
- * DECIDES — which operation a verb and a path name — while `api/crud.ts` only translates
- * that decision into h3. The rule was previously inline, untested, and had drifted into a
- * second REST projection that answered differently from `schema-rest` on all three counts
- * (verb, path, exposure).
- */
+/** The REST table this app serves, and the rule that matches a request against it. */
 import { generateRoutes } from '@fougere/adapter-rest';
 import type { App } from '@fougere/core';
 
@@ -31,14 +23,7 @@ export type RouteMatch =
 // it changes exactly when the app does.
 const tables = new WeakMap<App, Matchable[]>();
 
-/**
- * The table, per frond.
- *
- * `generateRoutes` prefixes every path the same way, while this door addresses a frond by
- * name (`/api/{frond}/{plural}`) — so it runs once per frond, each with its own prefix and
- * a filter naming it. That frond loop is the only thing this file knows that `schema-rest`
- * does not; the verbs, the paths and the membership rule all come from there.
- */
+/** The table, per frond. */
 export function tableOf(app: App): Matchable[] {
   const cached = tables.get(app);
   if (cached) return cached;
@@ -78,25 +63,10 @@ function openness(route: Matchable): number {
   return route.segments.filter((s) => s.startsWith(':')).length;
 }
 
-/**
- * Verbs this door accepts in place of the one the table names.
- *
- * `deriveMethod` gives `update` a single verb, PUT, while this door has always served
- * PATCH on it too — and says so (`docs/infra/surfaces`, "PUT · PATCH"). An alias keeps
- * that promise without giving the table a second row: both are mutations on a row, so
- * nothing is widened, and the one thing the table decides — WHICH operation a path names —
- * is still decided there alone.
- */
+/** Verbs this door accepts in place of the one the table names. */
 const ALIASES: Record<string, string> = { PATCH: 'PUT' };
 
-/**
- * Path first, method second — a router's order, and what makes a 405 possible at all.
- *
- * The order matters where the two overlap: `/posts/publish` and `/posts/:id` both accept
- * `GET /posts/publish`. Taking the most specific path first means the answer is "that verb
- * is refused here", not `findById('publish')` — and never `publish()`, which is what this
- * door used to do with the caller's session cookie attached.
- */
+/** Path first, method second — a router's order, and what makes a 405 possible at all. */
 export function matchRoute(table: Matchable[], method: string, segments: string[]): RouteMatch {
   const matches = table
     .map((route) => ({ route, params: paramsOf(route, segments) }))

package/src/serve.ts

@@ -1,16 +1,4 @@
-/**
- * The three doors, decided — and nothing about how a request arrives.
- *
- * A host (Nuxt, Next) owns exactly two translations: read the request into the
- * plain values below, and write the outcome back out. Everything between — which
- * operation a verb and a path name, which audience a segment selects, what a
- * refusal becomes — is decided here, once, for every host.
- *
- * The split matters because the alternative was measured in this repo: two copies
- * of a REST rule drifted until the Nuxt door answered differently from
- * `schema-rest` on the verb, the path AND the exposure. A second host would have
- * been a third copy.
- */
+/** The three doors, decided — and nothing about how a request arrives. */
 import {
   createAppRunner,
   callValueOf,
@@ -29,11 +17,7 @@ export interface DoorRequest {
   path: string;
   query: Record<string, string>;
   body?: unknown;
-  /**
-   * The server-resolved session. Stamped by the host from what IT resolved —
-   * never taken from the wire, which is the whole trust boundary of the browser
-   * door (`transport/http/src/server.ts` carries the same warning for the split).
-   */
+  /** The server-resolved session. */
   state: Record<string, unknown>;
 }
 
@@ -46,31 +30,16 @@ export type Outcome =
 
 // ── The call envelope ────────────────────────────
 
-/**
- * The audience this door serves — the path segment after `/_fougere/call`.
- *
- * The envelope is a surface like REST and GraphQL, so it selects its audience like
- * they do; the difference is only that it takes it from the path instead of an
- * option, because a door is mounted, not called. The same word names the directory
- * (`handlers/public/`), the config key (`surfaces: { public: [...] }`) and this
- * segment — derived, never configured.
- *
- * No escalation to guard: a named surface serves the entities it names and nothing
- * else (closed by naming), so every one of them is a subset of what the bare path
- * already serves.
- */
+/** The audience this door serves — the path segment after `/_fougere/call`. */
 export function surfaceOf(path: string): string | undefined {
   const named = /^\/_fougere\/call\/([A-Za-z0-9_-]+)/.exec(path.replace(/\?.*$/, ''));
   return named?.[1];
 }
 
 /**
- * Receiving end for the browser — same wire as process-to-process (JSON-RPC),
- * different trust boundary: the browser sits outside the topology, so `state` is
- * whatever the host resolved server-side, never what the payload claims.
- *
- * The runner follows the app's topology: local façades and remote doublures alike
- * — the browser never knows where a Frond lives.
+ * Receiving end for the browser — same wire as process-to-process (JSON-RPC), different trust
+ * boundary: the browser sits outside the topology, so `state` is whatever the host resolved
+ * server-side, never what the payload claims.
  */
 export async function serveRpc(app: App, request: Pick<DoorRequest, 'path' | 'body' | 'state'>): Promise<unknown> {
   const runner = createAppRunner(app, surfaceOf(request.path));
@@ -85,12 +54,7 @@ export function rpcParseError() {
 // ── REST ─────────────────────────────────────────
 
 /**
- * Match the URL against the canonical table, invoke the call it names, shape the
- * result for HTTP. The decision lives in `rest.ts`; dispatch belongs to the runner.
- *
- * `path` is what follows the REST mount point, so `/api/blog/posts/1` arrives as
- * `blog/posts/1`. A path this door does not serve returns `pass`, and that is what
- * lets an app keep its own `/api/*` handlers.
+ * Match the URL against the canonical table, invoke the call it names, shape the result for HTTP.
  */
 export async function serveRest(app: App, request: DoorRequest): Promise<Outcome> {
   // The app decides, not the host. A route file may exist and a middleware may be
@@ -123,7 +87,7 @@ export async function serveRest(app: App, request: DoorRequest): Promise<Outcome
     result = await invokeOn(
       app,
       { entity: route.entityName, op: route.operationName },
-      { params, query: request.query, body: request.body },
+      { params, query: request.query, input: request.body },
       undefined,
       request.state,
     );
@@ -135,13 +99,7 @@ export async function serveRest(app: App, request: DoorRequest): Promise<Outcome
   return shapeRest(route.operationName, result);
 }
 
-/**
- * What an operation's return becomes on the wire.
- *
- * Separate from `serveRest` because it is a DECISION and dispatch is not: it can be
- * pinned without a runner, and both hosts get it whether the call ran in memory or
- * came back over JSON-RPC.
- */
+/** What an operation's return becomes on the wire. */
 export function shapeRest(operationName: string, result: unknown): Outcome {
   if (result === null) return { kind: 'error', status: 404, body: { message: 'Not found' } };
 
@@ -168,13 +126,8 @@ type EntityClass = { name: string };
 type CallInput = Partial<InvocationContext>;
 
 /**
- * Name a call server-side and let the runner place it — local façade → direct
- * in-memory execution, a frond in `remotes` → JSON-RPC on the wire. The caller
- * never knows which.
- *
- * `state` is explicit here. Each host wraps this with its own way of finding the
- * current request (Nitro's async context, Next's `headers()` scope), because that
- * is the one part a host actually owns.
+ * Name a call server-side and let the runner place it — local façade → direct in-memory execution,
+ * a frond in `remotes` → JSON-RPC on the wire.
  */
 export async function invokeOn<T = unknown>(
   app: App,
@@ -186,6 +139,6 @@ export async function invokeOn<T = unknown>(
   const { call, invocation } = callValueOf(target, opOrInput, input);
   // An explicit `state` on the input wins over the request's — the caller who spells
   // it is answering for it, which is what makes a call outside any request possible.
-  const given = typeof opOrInput === 'string' ? input : opOrInput;
-  return (await createAppRunner(app)(call, { ...invocation, state: given?.state ?? state })) as T;
+  const explicit = typeof opOrInput === 'string' ? input : opOrInput;
+  return (await createAppRunner(app)(call, { ...invocation, state: explicit?.state ?? state })) as T;
 }

package/src/session.ts

@@ -1,11 +1,6 @@
 /**
- * The session view — the one place that turns the server-resolved
- * request context (filled by the auth middleware) into what the client
- * is allowed to see. One resolution, three readers: the page by
- * hydration, the refresh route over the wire, handlers by invocation.
- *
- * The app-declared context (viewer enrichment) will attach here when
- * a real case lands — this function is the seam.
+ * The session view — the one place that turns the server-resolved request context (filled by the
+ * auth middleware) into what the client is allowed to see.
  */
 
 export interface SessionView {

package/src/state.ts

@@ -1,14 +1,4 @@
-/**
- * Who the caller is, resolved server-side from the request's own headers.
- *
- * Nuxt answers this with a Nitro middleware that stamps `event.context`; a
- * Web-standard host has no such seam on a route handler, so it resolves here
- * instead. Same source (the auth runtime mounted on `app.auth`), same result shape
- * (`{ user, session }`), so `serveRpc` and `serveRest` cannot tell hosts apart.
- *
- * What must stay true in both: this is what the SERVER resolved. A browser sits
- * outside the topology, so nothing here may come from the payload.
- */
+/** Who the caller is, resolved server-side from the request's own headers. */
 import { useFougereApp } from './boot.js';
 
 type SessionApi = {