@fougere/adapter-graphql 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/auto-register.ts

@@ -1,25 +1,13 @@
 import { upperFirst, FieldSet, Role } from '@fougere/schema';
-/**
- * Auto-register GraphQL types and operations from a fougere App.
- *
- * Reads scanned entities + handler facades and registers
- * types, inputs, queries and mutations automatically.
- * Respects handler method-based contracts and surfaces config.
- *
- * Relations (ref/many) are auto-wired between registered types.
- */
+/** Auto-register GraphQL types and operations from a fougere App. */
 import type SchemaBuilder from '@pothos/core';
-import type { Fields, SchemaView, SchemaOrCard } from '@fougere/schema';
-import { Anatomy, fieldsOf, } from '@fougere/schema';
+import type { Fields, SchemaView } from '@fougere/schema';
+import { Shapes } from '@fougere/schema';
 import { registerType, registerOperations, type OperationMeta } from './pothos.js';
 
 type HandlerFacade = Record<string, Function>;
 
-/**
- * The relation a foreign key points at — `authorId → author`, `user_id → user`.
- * Returns undefined when the field carries no id suffix at all: there is nothing to
- * derive, and taking the scalar's own name would collide with it.
- */
+/** The relation a foreign key points at — `authorId → author`, `user_id → user`. */
 function relationNameFor(fieldName: string): string | undefined {
   const stripped = fieldName.replace(/(_id|Id|ID)$/, '');
   return stripped && stripped !== fieldName ? stripped : undefined;
@@ -41,15 +29,7 @@ interface Batch {
 /** The batch of ONE direction — the two sides of a relation must not share a read. */
 const directionKey = (entity: string, field: string) => `${entity}#${field}`;
 
-/**
- * How many keys go into one `list` call.
- *
- * A page has no ceiling, and `list` is the one read the ORM refuses to split (a limit
- * and an order do not recompose across statements). So the slicing happens HERE, where
- * the answer is a map being assembled and slices merge for free. Below SQL Server's
- * 2100 bindings, the lowest of the four engines — this side does not know the dialect,
- * so it takes the floor rather than guessing.
- */
+/** How many keys go into one `list` call. */
 const KEYS_PER_READ = 1000;
 
 /** Read a key set in slices, merging what each answers. */
@@ -74,24 +54,12 @@ const keepEach = <R>(into: Map<string, R>, from: Map<string, R>) => {
 /** A key answers a group: slices of the SAME key concatenate. */
 const concatEach = (into: Map<string, any[]>, from: Map<string, any[]>) => {
   for (const [key, rows] of from) {
-    const held = into.get(key);
-    if (held) held.push(...rows); else into.set(key, rows);
+    const bucket = into.get(key);
+    if (bucket) bucket.push(...rows); else into.set(key, rows);
   }
 };
 
-/**
- * The keys asked for during one tick, answered by one read.
- *
- * graphql-js calls a field resolver once per parent, so a page of 50 rows asked for
- * its relation 50 times — measured, with 5 distinct keys behind those 50 calls. The
- * keys of a tick are collected and answered together, which is the shape the framework
- * already imposes one level up: a presenter receives the PAGE (`egress.ts`).
- *
- * Scoped by the request's context object, which graphql-js hands identically to every
- * resolver of one request and never shares with another — two callers must never be
- * answered out of one read. When there is no context (a resolver called directly, as
- * the tests do), the scope is a shared object and the tick alone bounds the batch.
- */
+/** The keys asked for during one tick, answered by one read. */
 const batches = new WeakMap<object, Map<string, Batch>>();
 const NO_CONTEXT: object = {};
 
@@ -127,12 +95,15 @@ function loadByKey<R>(
 interface EntityEntry {
   name: string;
   /** A live class in-process, a card from a frond whose class never crossed. */
-  entityClass: SchemaOrCard;
+  entityClass: SchemaView;
   exposed?: boolean;
 }
 
 interface HandlerEntry {
-  /** The name the door answers to — `PostHandler` → `post`. NOT an entity name: a handler may carry none. */
+  /**
+   * The name the door answers to — `PostHandler` → `post`. NOT an entity name: a handler may carry
+   * none.
+   */
   address: string;
   operations: Map<string, OperationMeta>;
   surface?: string;
@@ -174,32 +145,22 @@ interface AppLike {
   facadeFor(entity: string, surface?: string): Record<string, Function> | undefined;
   /** Canonical operation table produced by core. */
   operationsFor(entity: string, surface?: string): Map<string, OperationMeta> | undefined;
-  /**
-   * The presenter of an entity — `undefined` when none. Asked for rather than
-   * resolved by a key spelled here: this adapter used to build `${Name}Presenter`
-   * itself, and a convention respelled in two places drifts silently on the day it
-   * changes, exactly as `facadeFor` exists to prevent for doors.
-   */
+  /** The presenter of an entity — `undefined` when none. */
   presenterFor(entity: string): unknown | undefined;
 }
 
 // ─── Helpers ────────────────────────────────────
 
 /**
- * The key an entity is filed under — case-folded, because the same entity is spelled
- * differently depending on where its name came from: the scan yields the registration name
- * (`authorUser`), while a card's relation target is fully lowercased by `describe`
- * (`authoruser`). Folding both is what lets one registry serve both sources.
+ * The key an entity is filed under — case-folded, because the same entity is spelled differently
+ * depending on where its name came from: the scan yields the registration name (`authorUser`),
+ * while a card's relation target is fully lowercased by `describe` (`authoruser`).
  */
 function registryKey(entityName: string): string {
   return entityName.toLowerCase();
 }
 
-/**
- * The key a relation points at. A live entity class answers with its class name; a target
- * rebuilt from a lone card is a `{ name }` stand-in and answers with the name `describe`
- * wrote. Both are names, which is the whole reason this resolves by name.
- */
+/** The key a relation points at. */
 function targetKey(target: unknown): string {
   return registryKey(String((target as { name?: string } | undefined)?.name ?? ''));
 }
@@ -213,20 +174,8 @@ export interface RegisterAllOptions {
   surface?: string;
 }
 
-/**
- * Auto-register GraphQL types and operations for all entities
- * in the app that have a matching handler facade.
- *
- * Operations are driven by parsed handler signatures (from the scanner).
- * Relations (ref/many) are auto-wired between registered entity types.
- */
-/**
- * The GraphQL type of a declared presenter view, built once per view class.
- *
- * Named after the field that emits it (`OrderItems`, `OrderUser`) rather than after the view
- * class, so two fields sharing one view still land on the same type and a view used twice is
- * registered once — Pothos refuses a duplicate type name and would take the schema down.
- */
+/** Auto-register GraphQL types and operations from a fougere App. */
+/** The GraphQL type of a declared presenter view, built once per view class. */
 const viewTypes = new WeakMap<object, any>();
 function viewTypeOf(
   builder: InstanceType<typeof SchemaBuilder>,
@@ -248,7 +197,7 @@ export function registerAll(
   // Collect registered types across all fronds for relation wiring, keyed by entity NAME.
   //
   // The name is the identity everywhere else in the system — `facadeFor(entity)`,
-  // `ormFor(entity)`, `schemaFor(entity)` all take one, and the table, the GraphQL type
+  // `storageFor(entity)`, `schemaFor(entity)` all take one, and the table, the GraphQL type
   // and the DI match are all derived from it. This registry keyed by class OBJECT was the
   // lone dissent, and it cost a silent failure: a relation target that is not the very
   // object registered (an entity rebuilt from a card, whose `to()` leaves a `{ name }`
@@ -313,7 +262,7 @@ export function registerAll(
       typeRegistry.set(registryKey(entity.name), {
         name: typeName, type, facade,
         presenterFields: new Set(presenterMeta?.fields ?? []),
-        fields: fieldsOf(entity.entityClass),
+        fields: entity.entityClass.getFields(),
       });
 
       const opOverrides = frond.operationsOverrides;
@@ -364,7 +313,7 @@ export function registerAll(
         // a presenter's computed field: the author named it, the author wins. Deriving
         // over it would either crash the build or shadow what they wrote.
         if (!relationName || relationName in fields || presenterFields.has(relationName)) continue;
-        const nullable = Anatomy.isNullable(field.shape);
+        const nullable = Shapes.isNullable(field.shape);
 
         const targetKeyName = primaryNameOf(targetEntry.fields);
         const targetList = targetEntry.facade.list;
@@ -431,8 +380,8 @@ export function registerAll(
                 const grouped = new Map<string, any[]>();
                 for (const row of rows) {
                   const key = String(row?.[reverseFkName]);
-                  const held = grouped.get(key);
-                  if (held) held.push(row); else grouped.set(key, [row]);
+                  const bucket = grouped.get(key);
+                  if (bucket) bucket.push(row); else grouped.set(key, [row]);
                 }
                 return grouped;
               }, concatEach),

package/src/index.ts

@@ -1,12 +1,4 @@
-/**
- * The GraphQL surface, in two calls: derive the schema, then mount it.
- *
- * The Pothos primitives `registerAll` stands on live one import away, under
- * `@fougere/adapter-graphql/pothos`. They are a complement — a field the projection cannot
- * derive — never a second way to build what it already gives. Offering them at the same
- * rank made that hierarchy invisible: an agent looking for "how do I declare a type" found
- * three doors and rebuilt two hundred lines by hand (measured 2026-08-02).
- */
+/** The GraphQL surface, in two calls. */
 export { registerAll } from './auto-register.js';
 export type { RegisterAllOptions } from './auto-register.js';
 export { registerGraphQL } from './serve.js';

package/src/pothos-entry.ts

@@ -1,9 +1,3 @@
-/**
- * The Pothos primitives — for what `registerAll` cannot derive, never to replace it.
- *
- * Reach for these to add a field the projection has no way to know about. Rebuilding
- * types, inputs and operations with them reimplements `registerAll` by hand and drops
- * what it wires for free: relations, and a presenter's computed fields.
- */
+/** The Pothos primitives — for what `registerAll` cannot derive, never to replace it. */
 export { registerType, registerInput, registerOperations, registerObjectType } from './pothos.js';
 export type { TypeConfig, InputConfig, OperationsConfig, ObjectFieldDef } from './pothos.js';

package/src/pothos.ts

@@ -3,9 +3,9 @@ import { upperFirst, Role } from '@fougere/schema';
  * @fougere/adapter-graphql — Pothos types derived from Fougere entities
  */
 import type SchemaBuilder from '@pothos/core';
-import { Anatomy, Schema, type Shape } from '@fougere/schema';
-import type { Field, Fields, SchemaView, SchemaOrCard } from '@fougere/schema';
-import { Boundary, Card, Lifecycle, schemaOf, Visibility } from '@fougere/schema';
+import { Shapes, Schema, type Shape } from '@fougere/schema';
+import type { Field, Fields, SchemaView } from '@fougere/schema';
+import { Boundary, Card, Lifecycle, Visibility } from '@fougere/schema';
 
 // ─── Types ─────────────────────────────────────────
 
@@ -19,7 +19,7 @@ export interface TypeConfig {
   name: string;
   /** Entity source */
   /** The schema whose fields become the type — a live class, or a card that travelled. */
-  entity: SchemaOrCard;
+  entity: SchemaView;
   /** Champs à exclure du type GraphQL */
   exclude?: string[];
   /** Relations à résoudre */
@@ -31,9 +31,8 @@ export interface TypeConfig {
   /** Per-field type metadata from source parsing. */
   presenterFieldMeta?: { name: string; returnType?: string; list?: boolean; nullable?: boolean }[];
   /**
-   * The view a computed field emits, when the presenter declared one — the object type
-   * to build for it. Without a declaration the scan reads a scalar or nothing, and an
-   * object-valued field can only be serialized.
+   * The view a computed field emits, when the presenter declared one — the object type to build
+   * for it.
    */
   presenterViews?: Record<string, EntityClass | [EntityClass]>;
   /** Builds (or reuses) the GraphQL object type for a declared view. */
@@ -69,7 +68,7 @@ export interface OperationBinding {
   source:
     | { kind: 'collector' | 'context' | 'fact' }
     | { kind: 'param'; name: string }
-    | { kind: 'body' | 'query' };
+    | { kind: 'input' | 'query' };
 }
 
 /** The projection-facing subset of core's EffectiveOperation. */
@@ -104,11 +103,7 @@ export interface OperationsConfig {
    * one root field. Absent when a caller builds a type by hand.
    */
   origin?: string;
-  /**
-   * The GraphQL type for a schema an operation declares as its return. The caller owns
-   * this because it alone knows whether the schema IS the entity's (then: the type
-   * already registered) or something else (then: a new named type).
-   */
+  /** The GraphQL type for a schema an operation declares as its return. */
   viewType?: (view: SchemaView, opName: string) => any;
 }
 
@@ -135,13 +130,7 @@ const PRIMITIVES: Record<string, (t: any, required: boolean) => any> = {
   boolean: (t, r) => t.arg.boolean({ required: r }),
 };
 
-/**
- * Parameter types no GraphQL argument stands for. `ListOptions` is NOT one of
- * them: it has its own branch below that turns it into the six pagination
- * arguments. Listing it here classified it first — the skip branch runs before
- * the pagination one — so `kind: 'pagination'` was never assigned and every
- * `list(options?: ListOptions)` op reached GraphQL with no arguments at all.
- */
+/** Parameter types no GraphQL argument stands for. */
 const SKIP_TYPES = new Set(['InvocationContext']);
 
 // ─── Helpers ───────────────────────────────────────
@@ -154,7 +143,7 @@ function fieldToGraphQL(
 ): any {
   // Dispatch on the BASE type via anatomy — `shape.type` may be the nullable
   // `[T,'null']` union, a direct comparison would fail silently on it.
-  const { base: shape, nullable } = Anatomy.of(field.shape);
+  const { base: shape, nullable } = Shapes.of(field.shape);
 
   // Before the type switch: a bounded set is its own GraphQL type whatever its base type
   // carries. `oneOf` fed the form's `select` and the DDL's `CHECK` from the day it was
@@ -199,7 +188,7 @@ function fieldToGraphQL(
     case 'array': {
       // A value list (`list(text())`) becomes a GraphQL list of the item scalar; a list
       // of objects becomes a list of JSON strings — the same rule 'object' follows.
-      const items = Anatomy.of(shape.items).base;
+      const items = Shapes.of(shape.items).base;
       const resolve = (parent: any) => parent[fieldName] ?? (nullable ? null : []);
       switch (items?.type) {
         case 'integer': return t.intList({ nullable, resolve });
@@ -240,14 +229,7 @@ function fieldToGraphQL(
   }
 }
 
-/**
- * A JSON-Schema object shape, turned into a GraphQL input type.
- *
- * `list(json(OrderLine))` inlines the line's shape as nested `properties` — good enough for
- * the judge, invisible to GraphQL until now: the `array` case fell through to `stringList`,
- * so `items` reached the schema as `[String!]!` and a client had to hand-encode every line
- * as JSON. The mutation was unusable (measured 2026-08-02).
- */
+/** A JSON-Schema object shape, turned into a GraphQL input type. */
 function nestedInputType(
   builder: InstanceType<typeof SchemaBuilder>,
   shape: Shape,
@@ -266,7 +248,7 @@ function nestedInputType(
       const out: Record<string, any> = {};
       for (const [key, prop] of Object.entries(properties)) {
         const isRequired = required.has(key);
-        switch (Anatomy.of(prop).base?.type) {
+        switch (Shapes.of(prop).base?.type) {
           case 'integer': out[key] = t.int({ required: isRequired }); break;
           case 'number': out[key] = t.float({ required: isRequired }); break;
           case 'boolean': out[key] = t.boolean({ required: isRequired }); break;
@@ -281,9 +263,9 @@ function nestedInputType(
 }
 
 /**
- * One input type per name, PER BUILDER — Pothos refuses a duplicate name, and a ref built on
- * one builder is unknown to the next: a global cache handed a stale ref to the second schema
- * ("InputObjectRef has not been implemented"). The builder owns its types, so it owns the map.
+ * One input type per name, PER BUILDER — Pothos refuses a duplicate name, and a ref built on one
+ * builder is unknown to the next: a global cache handed a stale ref to the second schema
+ * ("InputObjectRef has not been implemented").
  */
 const nestedInputs = new WeakMap<object, Map<string, any>>();
 
@@ -291,9 +273,8 @@ const nestedInputs = new WeakMap<object, Map<string, any>>();
 const enumTypes = new WeakMap<object, Map<string, { ref: any; values: string[] }>>();
 
 /**
- * A GraphQL enum value is an IDENTIFIER, not a string: `in-progress` or `à valider` cannot
- * be spelled in a query. `oneOf` is a JSON Schema keyword and accepts any string, so a set
- * that will not fit stays a `String` — the judge still refuses what is not in it.
+ * A GraphQL enum value is an IDENTIFIER, not a string: `in-progress` or `à valider` cannot be
+ * spelled in a query.
  */
 const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
 
@@ -307,10 +288,6 @@ function enumValuesOf(shape: Shape | undefined): string[] | undefined {
 /**
  * The enum type for one field's value set — one per NAME per builder, so `Post.status` and
  * `CreatePostInput.status` are the same `PostStatus` and a value read can be written back.
- *
- * A second field claiming the name with a different set falls back to `String` rather than
- * being served the first one: two different sets under one name would let a client send a
- * value this field never declared, which is the opposite of what the enum is for.
  */
 function enumTypeFor(
   builder: InstanceType<typeof SchemaBuilder>,
@@ -346,7 +323,7 @@ function fieldToInput(
   // Required = the presence axis, projected onto GraphQL's single knob: the
   // caller must supply it (no `lifecycle.create` rule answers absence), null is
   // not legal, and the view is not in patch mode (a patch omits freely).
-  const { base: shape, nullable } = Anatomy.of(field.shape);
+  const { base: shape, nullable } = Shapes.of(field.shape);
   const required = !patch && !nullable && Lifecycle.of(field).requiredAtCreate;
 
   // The dual of the output side, and it must be the SAME type: an input left as `String`
@@ -369,7 +346,7 @@ function fieldToInput(
       return t.boolean({ required });
 
     case 'array': {
-      const items = Anatomy.of(shape.items).base;
+      const items = Shapes.of(shape.items).base;
       switch (items?.type) {
         case 'integer': return t.intList({ required });
         case 'number': return t.floatList({ required });
@@ -416,21 +393,7 @@ export interface ObjectFieldDef {
   resolve?: (parent: any) => any;
 }
 
-/**
- * Register a GraphQL object type from a declarative field map.
- *
- * Each field auto-resolves from `parent[key]` unless a custom `resolve` is provided.
- * Works for wrapper types, result types, or any structural type.
- *
- * ```ts
- * const PostList = registerObjectType(builder, 'PostList', {
- *   items:     { type: [PostType] },
- *   total:     { type: 'int', nullable: true, resolve: async (p) => lazyCount(p) },
- *   hasMore:   { type: 'boolean', nullable: true },
- *   endCursor: { type: 'string', nullable: true },
- * });
- * ```
- */
+/** Register a GraphQL object type from a declarative field map. */
 export function registerObjectType(
   builder: InstanceType<typeof SchemaBuilder>,
   name: string,
@@ -476,26 +439,10 @@ export function registerObjectType(
 
 // ─── Public API ────────────────────────────────────
 
-/**
- * Enregistre un type GraphQL (lecture) depuis une entité fougere.
- *
- * ```ts
- * const ProductType = registerType(builder, {
- *   name: 'Product',
- *   entity: Product,
- *   exclude: ['categoryId'],
- *   relations: {
- *     category: {
- *       type: CategoryType,
- *       resolve: (parent) => db.select()...
- *     },
- *   },
- * });
- * ```
- */
+/** Enregistre un type GraphQL (lecture) depuis une entité fougere. */
 export function registerType(builder: InstanceType<typeof SchemaBuilder>, config: TypeConfig): any {
   // A live class or a card — an adapter needs the fields, never the constructor.
-  const schema = schemaOf(config.entity);
+  const schema = config.entity;
   const fields = schema.getFields();
   const exclude = new Set(config.exclude ?? []);
   // Who owns the enum names: the schema a view came from, so `PostCard.status` and
@@ -621,26 +568,7 @@ export function registerType(builder: InstanceType<typeof SchemaBuilder>, config
   });
 }
 
-/**
- * The GraphQL input for EXACTLY this view — or none, when the view asks for nothing.
- *
- * The caller derives the view and this projects it; it holds no policy of its own. What
- * a client may supply at CREATION is `Visibility.input`, which the op path applies for
- * create/update alone — `publish(input: Post)` must still name the post.
- *
- * Two things are dropped here because GraphQL cannot carry them, not because of any
- * rule: a collection has no column to send, and `boundary in: 'closed'` is refused from
- * every client. A view left with nothing after that gets `undefined` rather than an
- * input object with zero fields, which is invalid GraphQL and takes the WHOLE schema
- * down — every other type included.
- *
- * ```ts
- * const CreateProductInput = registerInput(builder, {
- *   name: 'CreateProductInput',
- *   schema: CreateProduct,
- * });
- * ```
- */
+/** The GraphQL input for EXACTLY this view — or none, when the view asks for nothing. */
 export function registerInput(builder: InstanceType<typeof SchemaBuilder>, config: InputConfig): any {
   const fields = Object.fromEntries(
     Object.entries(config.schema.getFields())
@@ -676,25 +604,13 @@ export function registerInput(builder: InstanceType<typeof SchemaBuilder>, confi
 
 // ─── GraphQL field naming ────────────────────────
 
-/**
- * Who holds each root field — a GraphQL root is FLAT, and two ops can want one name.
- *
- * Refused here rather than left to Pothos: it answers `Duplicate field ofBook on
- * Mutation` with no file, no handler and no remedy, and it takes the whole schema down
- * — every other type included. The five CRUD names weave the entity in (`createBook`),
- * so they never meet this; a custom op keeps its method name, which is the author's and
- * says nothing about its subject. Four handlers named `ofBook` in one measured app.
- *
- * Nothing is renamed automatically: `chapterOfBook` would be this package's choice of
- * the app's public vocabulary, and adding an entity in some other frond would silently
- * rename a field already published.
- */
+/** Who holds each root field — a GraphQL root is FLAT, and two ops can want one name. */
 const claimed = new WeakMap<object, Map<string, string>>();
 function claimRootField(builder: object, fieldName: string, origin: string): void {
-  let held = claimed.get(builder);
-  if (!held) { held = new Map(); claimed.set(builder, held); }
+  let perField = claimed.get(builder);
+  if (!perField) { perField = new Map(); claimed.set(builder, perField); }
 
-  const first = held.get(fieldName);
+  const first = perField.get(fieldName);
   if (first !== undefined && first !== origin) {
     const opName = origin.split('.').pop();
     // `operations:` is keyed by op name PER FROND, so it cannot tell two handlers of the
@@ -710,7 +626,7 @@ function claimRootField(builder: object, fieldName: string, origin: string): voi
       + `A root field is global, so one of them has to give. ${remedy}`,
     );
   }
-  held.set(fieldName, origin);
+  perField.set(fieldName, origin);
 }
 
 function graphqlFieldName(opName: string, entityName: string): string {
@@ -733,7 +649,7 @@ function graphqlFieldName(opName: string, entityName: string): string {
 
 interface ArgsResult {
   argsDef: (t: any) => Record<string, any>;
-  buildInvocation: (args: any, gqlCtx: any) => { params: Record<string, any>; query: Record<string, any>; body: unknown; state: Record<string, any> };
+  buildInvocation: (args: any, gqlCtx: any) => { params: Record<string, any>; query: Record<string, any>; input: unknown; state: Record<string, any> };
 }
 
 function buildArgsFromSignature(
@@ -748,7 +664,7 @@ function buildArgsFromSignature(
   // invocation context, and publishing it would let callers impersonate that value.
   const paramPlan: {
     name: string;
-    kind: 'primitive' | 'body' | 'skip' | 'pagination';
+    kind: 'primitive' | 'input' | 'skip' | 'pagination';
     typeName: string;
     optional: boolean;
     nullable: boolean;
@@ -772,8 +688,8 @@ function buildArgsFromSignature(
         case 'param':
           paramPlan.push({ name: param.name, kind: 'primitive', typeName, optional: binding.optional, nullable: param.type.nullable === true });
           continue;
-        case 'body':
-          paramPlan.push({ name: param.name, kind: 'body', typeName, optional: binding.optional, nullable: param.type.nullable === true });
+        case 'input':
+          paramPlan.push({ name: param.name, kind: 'input', typeName, optional: binding.optional, nullable: param.type.nullable === true });
           continue;
       }
     }
@@ -794,14 +710,14 @@ function buildArgsFromSignature(
       continue;
     }
 
-    // Object/entity param → body
-    paramPlan.push({ name: param.name, kind: 'body', typeName, optional: param.optional ?? false, nullable: param.type.nullable === true });
+    // Object/entity param → input
+    paramPlan.push({ name: param.name, kind: 'input', typeName, optional: param.optional ?? false, nullable: param.type.nullable === true });
   }
 
   // Register input type if needed
   let inputRef: any;
-  const bodyParam = paramPlan.find((p) => p.kind === 'body');
-  if (bodyParam && meta.input) {
+  const inputParam = paramPlan.find((p) => p.kind === 'input');
+  if (inputParam && meta.input) {
     // Only strip non-client fields for create/update — other ops may legitimately use them (e.g. publish(id))
     const isMutation = opName === 'create' || opName === 'update';
     const opInputFields = isMutation ? Visibility.of(meta.input.getFields()).input : meta.input.getFields();
@@ -831,8 +747,8 @@ function buildArgsFromSignature(
       }
     }
 
-    if (bodyParam && inputRef) {
-      args.input = t.arg({ type: inputRef, required: !bodyParam.optional && !bodyParam.nullable });
+    if (inputParam && inputRef) {
+      args.input = t.arg({ type: inputRef, required: !inputParam.optional && !inputParam.nullable });
     }
 
     if (hasPagination) {
@@ -849,7 +765,7 @@ function buildArgsFromSignature(
 
   const buildInvocation = (args: any, gqlCtx: any) => {
     const params: Record<string, any> = {};
-    let body: unknown = undefined;
+    let input: unknown = undefined;
 
     for (const p of paramPlan) {
       if (p.kind === 'primitive') {
@@ -857,19 +773,19 @@ function buildArgsFromSignature(
         // null. Test undefined alone: `!= null` erased the second case and made
         // `foo?: T | null` indistinguishable from `foo?: T`.
         if (args[p.name] !== undefined) params[p.name] = args[p.name];
-      } else if (p.kind === 'body') {
-        body = args.input;
+      } else if (p.kind === 'input') {
+        input = args.input;
       } else if (p.kind === 'pagination') {
-        // Collect pagination args into body (ListOptions)
+        // Collect pagination args into input (ListOptions)
         const options: Record<string, any> = {};
         for (const key of ['limit', 'offset', 'page', 'after', 'orderBy', 'order']) {
           if (args[key] !== undefined) options[key] = args[key];
         }
-        body = options;
+        input = options;
       }
     }
 
-    return { params, query: {}, body, state: gqlCtx?.state ?? {} };
+    return { params, query: {}, input, state: gqlCtx?.state ?? {} };
   };
 
   return { argsDef, buildInvocation };
@@ -895,17 +811,7 @@ function resolveOutputType(
     return { type: 'list-wrapper', isList: true, nullable: false };
   }
 
-  /**
-   * The type the operation SAYS it returns.
-   *
-   * `async stats(): Promise<StatsOutput[]>` is a declaration, and the scan already
-   * resolved it into a live schema class. Until now this threw it away and announced the
-   * entity's type instead, so a schema built from a handler with such an op was simply
-   * wrong: its own fields were not queryable, and the entity's came back null.
-   *
-   * Falls back to the entity when nothing is declared, or when what is declared IS the
-   * entity — `publish(): Promise<Post>` must not mint a second Post type.
-   */
+  /** The type the operation SAYS it returns. */
   const declared = meta?.output && opName && config.viewType
     ? config.viewType(meta.output, opName)
     : undefined;
@@ -919,19 +825,7 @@ function resolveOutputType(
 
 // ─── registerOperations ──────────────────────────
 
-/**
- * Register all GraphQL operations for an entity from parsed handler signatures.
- *
- * Each operation in the map is registered as a Query or Mutation field
- * based on naming convention (list*, find*, get*, search* → Query, else → Mutation).
- *
- * Args are generated from the parsed method signature:
- * - Primitives (string, number) → scalar args
- * - Entity/object params → input types (derived from meta.input)
- * - Partial<T> wrapper → all input fields nullable
- * - ListOptions → standard pagination args
- * - InvocationContext → skipped (injected by resolver)
- */
+/** Register all GraphQL operations for an entity from parsed handler signatures. */
 export function registerOperations(builder: InstanceType<typeof SchemaBuilder>, config: OperationsConfig): void {
   // Pre-register list wrapper type if list op exists
   let listWrapperType: any;
@@ -992,7 +886,7 @@ export function registerOperations(builder: InstanceType<typeof SchemaBuilder>,
               hasMore: result?.hasMore,
               _count: () => config.facade[opName]({
                 ...invocation,
-                body: { ...(invocation.body as any ?? {}), count: true, limit: 1 },
+                input: { ...(invocation.input as any ?? {}), count: true, limit: 1 },
               }),
             };
           }