@autobe/agent 0.22.0 → 0.23.0

package/src/orchestrate/interface/orchestrateInterfaceComplement.ts

@@ -17,8 +17,8 @@ import { transformInterfaceComplementHistories } from "./histories/transformInte
 import { IAutoBeInterfaceComplementApplication } from "./structures/IAutoBeInterfaceComplementApplication";
 import { JsonSchemaFactory } from "./utils/JsonSchemaFactory";
 import { JsonSchemaNamingConvention } from "./utils/JsonSchemaNamingConvention";
+import { JsonSchemaValidator } from "./utils/JsonSchemaValidator";
 import { fulfillJsonSchemaErrorMessages } from "./utils/fulfillJsonSchemaErrorMessages";
-import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export function orchestrateInterfaceComplement<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
@@ -33,7 +33,7 @@ async function step<Model extends ILlmSchema.Model>(
   life: number,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const missed: string[] = getMissed(document);
-  if (missed.length === 0 || life <= 0) {
+  if (missed.length === 0 || life < 0) {
     return document.components.schemas;
   }
 
@@ -143,7 +143,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
     }
 
     const errors: IValidation.IError[] = [];
-    validateAuthorizationSchema({
+    JsonSchemaValidator.validateSchemas({
       errors,
       schemas: result.data.schemas,
       path: "$input.schemas",

package/src/orchestrate/interface/orchestrateInterfaceOperations.ts

@@ -4,30 +4,30 @@ import {
   AutoBeOpenApi,
   AutoBeProgressEventBase,
 } from "@autobe/interface";
-import { AutoBeEndpointComparator, StringUtil } from "@autobe/utils";
+import { StringUtil } from "@autobe/utils";
 import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
 import { HashMap, HashSet, IPointer } from "tstl";
 import typia from "typia";
-import { Escaper } from "typia/lib/utils/Escaper";
 import { NamingConvention } from "typia/lib/utils/NamingConvention";
 import { v7 } from "uuid";
 
+import { AutoBeConfigConstant } from "../../constants/AutoBeConfigConstant";
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { divideArray } from "../../utils/divideArray";
-import { emplaceMap } from "../../utils/emplaceMap";
 import { executeCachedBatch } from "../../utils/executeCachedBatch";
 import { transformInterfaceOperationHistories } from "./histories/transformInterfaceOperationHistories";
 import { orchestrateInterfaceOperationsReview } from "./orchestrateInterfaceOperationsReview";
 import { IAutoBeInterfaceOperationApplication } from "./structures/IAutoBeInterfaceOperationApplication";
 import { OpenApiEndpointComparator } from "./utils/OpenApiEndpointComparator";
+import { OperationValidator } from "./utils/OperationValidator";
 
 export async function orchestrateInterfaceOperations<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
   endpoints: AutoBeOpenApi.IEndpoint[],
-  capacity: number = 8,
+  capacity: number = AutoBeConfigConstant.INTERFACE_CAPACITY,
 ): Promise<AutoBeOpenApi.IOperation[]> {
   const matrix: AutoBeOpenApi.IEndpoint[][] = divideArray({
     array: endpoints,
@@ -192,31 +192,13 @@ function createController<Model extends ILlmSchema.Model>(props: {
     const operations: IAutoBeInterfaceOperationApplication.IOperation[] =
       result.data.operations;
     const errors: IValidation.IError[] = [];
-    operations.forEach((op, i) => {
-      // get method has request body
-      if (op.method === "get" && op.requestBody !== null)
-        errors.push({
-          path: `$input.operations[${i}].requestBody`,
-          expected:
-            "GET method should not have request body. Change method, or re-design the operation.",
-          value: op.requestBody,
-        });
-      // operation name
-      if (Escaper.variable(op.name) === false)
-        errors.push({
-          path: `$input.operations[${i}].name`,
-          expected: "<valid_variable_name>",
-          value: op.name,
-          description: StringUtil.trim`
-            The operation name will be converted to the API controller method
-            (function) name, so the operation.name must be a valid JavaScript 
-            variable/function name.
+    OperationValidator.validate({
+      path: "$input.operations",
+      errors,
+      operations,
+    });
 
-            However, what you've configured value ${JSON.stringify(op.name)}
-            is not a valid JavaScript variable/function name. Please change
-            it to a valid variable/function name.
-          `,
-        });
+    operations.forEach((op, i) => {
       // validate roles
       if (props.roles.length === 0) op.authorizationRoles = [];
       else if (op.authorizationRoles.length !== 0 && props.roles.length !== 0)
@@ -236,72 +218,6 @@ function createController<Model extends ILlmSchema.Model>(props: {
           });
         });
     });
-
-    // validate duplicated endpoints
-    const endpoints: HashMap<AutoBeOpenApi.IEndpoint, number[]> = new HashMap(
-      AutoBeEndpointComparator.hashCode,
-      AutoBeEndpointComparator.equals,
-    );
-    operations.forEach((op, i) => {
-      const key: AutoBeOpenApi.IEndpoint = {
-        path: op.path,
-        method: op.method,
-      };
-      const it = endpoints.find(key);
-      if (it.equals(endpoints.end()) === false) {
-        const indexes: number[] = it.second;
-        errors.push({
-          path: `$input.operations[${i}].{"path"|"method"}`,
-          expected: "Unique endpoint (path and method)",
-          value: key,
-          description: StringUtil.trim`
-            Duplicated endpoint detected (method: ${op.method}, path: ${op.path}).
-
-            The duplicated endpoints of others are located in below accessors.
-            Check them, and consider which operation endpoint would be proper to modify.
-            
-            ${indexes
-              .map((idx) => `- $input.operations.[${idx}].{"path"|"method"}`)
-              .join("\n")}
-          `,
-        });
-        indexes.push(i);
-      } else endpoints.emplace(key, [i]);
-    });
-
-    // validate duplicated method names
-    const accessors: Map<string, number[]> = new Map();
-    operations.forEach((op, i) => {
-      const key: string =
-        op.path
-          .split("/")
-          .filter((e) => e[0] !== "{" && e.at(-1) !== "}")
-          .filter((e) => e.length !== 0)
-          .join(".") + `.${op.name}`;
-      const indexes: number[] = emplaceMap(accessors, key, () => []);
-      if (indexes.length !== 0) {
-        errors.push({
-          path: `$input.operations[${i}].name`,
-          expected: "Unique name in the same accessor scope.",
-          value: op.name,
-          description: StringUtil.trim`
-            Duplicated operation accessor detected (name: ${op.name}, accessor: ${key}).
-
-            The operation name must be unique within the parent accessor.
-            In other worlds, the operation accessor determined by the name
-            must be unique in the OpenAPI document.
-
-            Here is the list of elements of duplicated operation names.
-            Check them, and consider which operation name would be proper to modify.
-
-            ${indexes
-              .map((idx) => `- ${operations[idx].name} (accessor: ${key})`)
-              .join("\n")}
-          `,
-        });
-      }
-      indexes.push(i);
-    });
     if (errors.length !== 0)
       return {
         success: false,

package/src/orchestrate/interface/orchestrateInterfaceOperationsReview.ts

@@ -5,7 +5,7 @@ import {
   AutoBePrisma,
   AutoBeProgressEventBase,
 } from "@autobe/interface";
-import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
 import { IPointer } from "tstl";
 import typia from "typia";
 import { v7 } from "uuid";
@@ -13,6 +13,7 @@ import { v7 } from "uuid";
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { transformInterfaceOperationsReviewHistories } from "./histories/transformInterfaceOperationsReviewHistories";
 import { IAutoBeInterfaceOperationsReviewApplication } from "./structures/IAutoBeInterfaceOperationsReviewApplication";
+import { OperationValidator } from "./utils/OperationValidator";
 
 export async function orchestrateInterfaceOperationsReview<
   Model extends ILlmSchema.Model,
@@ -41,7 +42,6 @@ export async function orchestrateInterfaceOperationsReview<
       message: "Review the operations",
     });
     if (pointer.value === null) {
-      console.error("Failed to review operations.");
       ++progress.completed;
       return [];
     }
@@ -67,8 +67,7 @@ export async function orchestrateInterfaceOperationsReview<
       completed: ++progress.completed,
     } satisfies AutoBeInterfaceOperationsReviewEvent);
     return content;
-  } catch (error) {
-    console.error("Error occurred during interface operations review:", error);
+  } catch {
     ++progress.completed;
     return [];
   }
@@ -79,9 +78,32 @@ function createReviewController<Model extends ILlmSchema.Model>(props: {
   prismaSchemas: AutoBePrisma.IFile[];
   build: (reviews: IAutoBeInterfaceOperationsReviewApplication.IProps) => void;
 }): IAgenticaController.IClass<Model> {
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfaceOperationsReviewApplication.IProps> => {
+    const result: IValidation<IAutoBeInterfaceOperationsReviewApplication.IProps> =
+      typia.validate<IAutoBeInterfaceOperationsReviewApplication.IProps>(next);
+    if (result.success === false) return result;
+
+    const errors: IValidation.IError[] = [];
+    OperationValidator.validate({
+      path: "$input.content",
+      operations: result.data.content,
+      errors,
+    });
+    if (errors.length !== 0)
+      return {
+        success: false,
+        errors,
+        data: next,
+      };
+    return result;
+  };
   const application: ILlmApplication<Model> = collection[
     props.model === "chatgpt" ? "chatgpt" : "claude"
-  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
 
   return {
     protocol: "class",
@@ -96,12 +118,26 @@ function createReviewController<Model extends ILlmSchema.Model>(props: {
 }
 
 const collection = {
-  chatgpt: typia.llm.application<
-    IAutoBeInterfaceOperationsReviewApplication,
-    "chatgpt"
-  >(),
-  claude: typia.llm.application<
-    IAutoBeInterfaceOperationsReviewApplication,
-    "claude"
-  >(),
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<
+      IAutoBeInterfaceOperationsReviewApplication,
+      "chatgpt"
+    >({
+      validate: {
+        reviewOperations: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<
+      IAutoBeInterfaceOperationsReviewApplication,
+      "claude"
+    >({
+      validate: {
+        reviewOperations: validate,
+      },
+    }),
 };
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfaceOperationsReviewApplication.IProps>;

package/src/orchestrate/interface/orchestrateInterfaceSchemas.ts

@@ -11,6 +11,7 @@ import { IPointer } from "tstl";
 import typia from "typia";
 import { v7 } from "uuid";
 
+import { AutoBeConfigConstant } from "../../constants/AutoBeConfigConstant";
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { divideArray } from "../../utils/divideArray";
@@ -19,15 +20,15 @@ import { transformInterfaceSchemaHistories } from "./histories/transformInterfac
 import { IAutoBeInterfaceSchemaApplication } from "./structures/IAutoBeInterfaceSchemaApplication";
 import { JsonSchemaFactory } from "./utils/JsonSchemaFactory";
 import { JsonSchemaNamingConvention } from "./utils/JsonSchemaNamingConvention";
+import { JsonSchemaValidator } from "./utils/JsonSchemaValidator";
 import { fulfillJsonSchemaErrorMessages } from "./utils/fulfillJsonSchemaErrorMessages";
-import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemas<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
-  capacity: number = 5,
+  capacity: number = AutoBeConfigConstant.INTERFACE_CAPACITY,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   // fix operation type names
   JsonSchemaNamingConvention.operations(operations);
@@ -196,7 +197,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
 
     // Check all IAuthorized types
     const errors: IValidation.IError[] = [];
-    validateAuthorizationSchema({
+    JsonSchemaValidator.validateSchemas({
       errors,
       schemas: result.data.schemas,
       path: "$input.schemas",

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -10,6 +10,7 @@ import { IPointer } from "tstl";
 import typia from "typia";
 import { v7 } from "uuid";
 
+import { AutoBeConfigConstant } from "../../constants/AutoBeConfigConstant";
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { divideArray } from "../../utils/divideArray";
@@ -18,8 +19,8 @@ import { transformInterfaceSchemasReviewHistories } from "./histories/transformI
 import { IAutoBeInterfaceSchemasReviewApplication } from "./structures/IAutobeInterfaceSchemasReviewApplication";
 import { JsonSchemaFactory } from "./utils/JsonSchemaFactory";
 import { JsonSchemaNamingConvention } from "./utils/JsonSchemaNamingConvention";
+import { JsonSchemaValidator } from "./utils/JsonSchemaValidator";
 import { fulfillJsonSchemaErrorMessages } from "./utils/fulfillJsonSchemaErrorMessages";
-import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemasReview<
   Model extends ILlmSchema.Model,
@@ -27,6 +28,7 @@ export async function orchestrateInterfaceSchemasReview<
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
   schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  capacity: number = AutoBeConfigConstant.INTERFACE_CAPACITY,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const a = Object.entries(schemas).map(([key, schema]) => {
     return { [key]: schema };
@@ -35,7 +37,7 @@ export async function orchestrateInterfaceSchemasReview<
   const matrix: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>[][] =
     divideArray({
       array: a,
-      capacity: 8,
+      capacity,
     });
   const progress: IProgress = {
     total: matrix.length,
@@ -97,7 +99,6 @@ export async function step<Model extends ILlmSchema.Model>(
       message: "Review type schemas.",
     });
     if (pointer.value === null) {
-      console.error("Failed to extract review information.");
       ++progress.completed;
       return {};
     }
@@ -122,8 +123,7 @@ export async function step<Model extends ILlmSchema.Model>(
       created_at: new Date().toISOString(),
     } satisfies AutoBeInterfaceSchemasReviewEvent);
     return content;
-  } catch (error) {
-    console.error("Error occurred during interface schemas review:", error);
+  } catch {
     ++progress.completed;
     return {};
   }
@@ -150,7 +150,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
     }
 
     const errors: IValidation.IError[] = [];
-    validateAuthorizationSchema({
+    JsonSchemaValidator.validateSchemas({
       errors,
       schemas: result.data.content,
       path: "$input.content",

package/src/orchestrate/interface/structures/IAutoBeInterfaceOperationApplication.ts

@@ -87,10 +87,260 @@ export namespace IAutoBeInterfaceOperationApplication {
    * ```
    */
   export interface IOperation
-    extends Omit<
-      AutoBeOpenApi.IOperation,
-      "authorizationRole" | "authorizationType"
-    > {
+    extends AutoBeOpenApi.IEndpoint {
+    /**
+     * Specification of the API operation.
+     *
+     * Before defining the API operation interface, please describe what you're
+     * planning to write in this `specification` field.
+     *
+     * The specification must be fully detailed and clear, so that anyone can
+     * understand the purpose and functionality of the API operation and its
+     * related components (e.g., {@link path}, {@link parameters},
+     * {@link requestBody}).
+     *
+     * IMPORTANT: The specification MUST identify which Prisma DB table this
+     * operation is associated with, helping ensure complete coverage of all
+     * database entities.
+     */
+    specification: string;
+
+    /**
+     * Detailed description about the API operation.
+     *
+     * IMPORTANT: This field MUST be extensively detailed and MUST reference the
+     * description comments from the related Prisma DB schema tables and
+     * columns. The description should be organized into MULTIPLE PARAGRAPHS
+     * separated by line breaks to improve readability and comprehension.
+     *
+     * For example, include separate paragraphs for:
+     *
+     * - The purpose and overview of the API operation
+     * - Security considerations and user permissions
+     * - Relationship to underlying database entities
+     * - Validation rules and business logic
+     * - Related API operations that might be used together with this one
+     * - Expected behavior and error handling
+     *
+     * When writing the description, be sure to incorporate the corresponding DB
+     * schema's description comments, matching the level of detail and style of
+     * those comments. This ensures consistency between the API documentation
+     * and database structure.
+     *
+     * If there's a dependency to other APIs, please describe the dependency API
+     * operation in this field with detailed reason. For example, if this API
+     * operation needs a pre-execution of other API operation, it must be
+     * explicitly described.
+     *
+     * - `GET /shoppings/customers/sales` must be pre-executed to get entire list
+     *   of summarized sales. Detailed sale information would be obtained by
+     *   specifying the sale ID in the path parameter.
+     *
+     * **CRITICAL WARNING about soft delete keywords**: DO NOT use terms like
+     * "soft delete", "soft-delete", or similar variations in this description
+     * UNLESS the operation actually implements soft deletion. These keywords
+     * trigger validation logic that expects a corresponding soft_delete_column
+     * to be specified. Only use these terms when you intend to implement soft
+     * deletion (marking records as deleted without removing them from the
+     * database).
+     *
+     * Example of problematic description: ❌ "This would normally be a
+     * soft-delete, but we intentionally perform permanent deletion here" - This
+     * triggers soft delete validation despite being a hard delete operation.
+     *
+     * > MUST be written in English. Never use other languages.
+     */
+    description: string;
+
+    /**
+     * Short summary of the API operation.
+     *
+     * This should be a concise description of the API operation, typically one
+     * sentence long. It should provide a quick overview of what the API does
+     * without going into too much detail.
+     *
+     * This summary will be used in the OpenAPI documentation to give users a
+     * quick understanding of the API operation's purpose.
+     *
+     * IMPORTANT: The summary should clearly indicate which Prisma DB table this
+     * operation relates to, helping to ensure all tables have API coverage.
+     *
+     * **CRITICAL WARNING about soft delete keywords**: DO NOT use terms like
+     * "soft delete", "soft-delete", or similar variations in this summary
+     * UNLESS the operation actually implements soft deletion. These keywords
+     * trigger validation logic that expects a corresponding soft_delete_column
+     * to be specified. Only use these terms when you intend to implement soft
+     * deletion (marking records as deleted without removing them from the
+     * database).
+     *
+     * > MUST be written in English. Never use other languages
+     */
+    summary: string;
+
+    /**
+     * List of path parameters.
+     *
+     * Note that, the {@link AutoBeOpenApi.IParameter.name identifier name} of
+     * path parameter must be corresponded to the
+     * {@link path API operation path}.
+     *
+     * For example, if there's an API operation which has {@link path} of
+     * `/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}`,
+     * its list of {@link AutoBeOpenApi.IParameter.name path parameters} must be
+     * like:
+     *
+     * - `saleId`
+     * - `questionId`
+     * - `commentId`
+     */
+    parameters: AutoBeOpenApi.IParameter[];
+
+    /**
+     * Request body of the API operation.
+     *
+     * Defines the payload structure for the request. Contains a description and
+     * schema reference to define the expected input data.
+     *
+     * Should be `null` for operations that don't require a request body, such
+     * as most "get" operations.
+     */
+    requestBody: AutoBeOpenApi.IRequestBody | null;
+
+    /**
+     * Response body of the API operation.
+     *
+     * Defines the structure of the successful response data. Contains a
+     * description and schema reference for the returned data.
+     *
+     * Should be null for operations that don't return any data.
+     */
+    responseBody: AutoBeOpenApi.IResponseBody | null;
+
+    /**
+     * Functional name of the API endpoint.
+     *
+     * This is a semantic identifier that represents the primary function or
+     * purpose of the API endpoint. It serves as a canonical name that can be
+     * used for code generation, SDK method names, and internal references.
+     *
+     * ## Reserved Word Restrictions
+     *
+     * CRITICAL: The name MUST NOT be a TypeScript/JavaScript reserved word, as
+     * it will be used as a class method name in generated code. Avoid names
+     * like:
+     *
+     * - `delete`, `for`, `if`, `else`, `while`, `do`, `switch`, `case`, `break`
+     * - `continue`, `function`, `return`, `with`, `in`, `of`, `instanceof`
+     * - `typeof`, `void`, `var`, `let`, `const`, `class`, `extends`, `import`
+     * - `export`, `default`, `try`, `catch`, `finally`, `throw`, `new`
+     * - `super`, `this`, `null`, `true`, `false`, `async`, `await`
+     * - `yield`, `static`, `private`, `protected`, `public`, `implements`
+     * - `interface`, `package`, `enum`, `debugger`
+     *
+     * Instead, use alternative names for these operations:
+     *
+     * - Use `erase` instead of `delete`
+     * - Use `iterate` instead of `for`
+     * - Use `when` instead of `if`
+     * - Use `cls` instead of `class`
+     *
+     * ## Standard Endpoint Names
+     *
+     * Use these conventional names based on the endpoint's primary function:
+     *
+     * - **`index`**: List/search operations that return multiple entities
+     *
+     *   - Typically used with PATCH method for complex queries
+     *   - Example: `PATCH /users` → `name: "index"`
+     * - **`at`**: Retrieve a specific entity by identifier
+     *
+     *   - Typically used with GET method on single resource
+     *   - Example: `GET /users/{userId}` → `name: "at"`
+     * - **`create`**: Create a new entity
+     *
+     *   - Typically used with POST method
+     *   - Example: `POST /users` → `name: "create"`
+     * - **`update`**: Update an existing entity
+     *
+     *   - Typically used with PUT method
+     *   - Example: `PUT /users/{userId}` → `name: "update"`
+     * - **`erase`**: Delete/remove an entity (NOT `delete` - reserved word!)
+     *
+     *   - Typically used with DELETE method
+     *   - Example: `DELETE /users/{userId}` → `name: "erase"`
+     *
+     * ## Custom Endpoint Names
+     *
+     * For specialized operations beyond basic CRUD, use descriptive verbs:
+     *
+     * - **`activate`**: Enable or turn on a feature/entity
+     * - **`deactivate`**: Disable or turn off a feature/entity
+     * - **`approve`**: Approve a request or entity
+     * - **`reject`**: Reject a request or entity
+     * - **`publish`**: Make content publicly available
+     * - **`archive`**: Move to archived state
+     * - **`restore`**: Restore from archived/deleted state
+     * - **`duplicate`**: Create a copy of an entity
+     * - **`transfer`**: Move ownership or change assignment
+     * - **`validate`**: Validate data or state
+     * - **`process`**: Execute a business process or workflow
+     * - **`export`**: Generate downloadable data
+     * - **`import`**: Process uploaded data
+     *
+     * ## Naming Guidelines
+     *
+     * - MUST use camelCase naming convention
+     * - Use singular verb forms
+     * - Be concise but descriptive
+     * - Avoid abbreviations unless widely understood
+     * - Ensure the name clearly represents the endpoint's primary action
+     * - For nested resources, focus on the action rather than hierarchy
+     * - NEVER use JavaScript/TypeScript reserved words
+     *
+     * Valid Examples:
+     *
+     * - `index`, `create`, `update`, `erase` (single word)
+     * - `updatePassword`, `cancelOrder`, `publishArticle` (camelCase)
+     * - `validateEmail`, `generateReport`, `exportData` (camelCase)
+     *
+     * Invalid Examples:
+     *
+     * - `update_password` (snake_case not allowed)
+     * - `UpdatePassword` (PascalCase not allowed)
+     * - `update-password` (kebab-case not allowed)
+     *
+     * Path to Name Examples:
+     *
+     * - `GET /shopping/orders/{orderId}/items` → `name: "index"` (lists items)
+     * - `POST /shopping/orders/{orderId}/cancel` → `name: "cancel"`
+     * - `PUT /users/{userId}/password` → `name: "updatePassword"`
+     *
+     * ## Uniqueness Rule
+     *
+     * The `name` must be unique within the API's accessor namespace. The
+     * accessor is formed by combining the path segments (excluding parameters)
+     * with the operation name.
+     *
+     * Accessor formation:
+     *
+     * 1. Extract non-parameter segments from the path (remove `{...}` parts)
+     * 2. Join segments with dots
+     * 3. Append the operation name
+     *
+     * Examples:
+     *
+     * - Path: `/shopping/sale/{saleId}/review/{reviewId}`, Name: `at` → Accessor:
+     *   `shopping.sale.review.at`
+     * - Path: `/users/{userId}/posts`, Name: `index` → Accessor:
+     *   `users.posts.index`
+     * - Path: `/auth/login`, Name: `signIn` → Accessor: `auth.login.signIn`
+     *
+     * Each accessor must be globally unique across the entire API. This ensures
+     * operations can be uniquely identified in generated SDKs and prevents
+     * naming conflicts.
+     */
+    name: string & CamelPattern;
+
     /**
      * Authorization roles required to access this API operation.
      *