@autobe/agent 0.18.0 → 0.20.0

package/lib/orchestrate/analyze/histories/transformAnalyzeReviewHistories.d.ts

@@ -0,0 +1,6 @@
+import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeAnalyzeScenarioEvent } from "@autobe/interface";
+import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
+import { ILlmSchema } from "@samchon/openapi";
+import { AutoBeContext } from "../../../context/AutoBeContext";
+export declare const transformAnalyzeReviewHistories: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, scenario: AutoBeAnalyzeScenarioEvent, allFiles: AutoBeAnalyzeFile[], myFile: AutoBeAnalyzeFile) => Array<IAgenticaHistoryJson.IUserMessage | IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage>;

package/lib/orchestrate/analyze/histories/transformAnalyzeWriteHistories.d.ts

@@ -1,4 +1,6 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
 import { AutoBeAnalyzeScenarioEvent } from "@autobe/interface";
 import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
-export declare const transformAnalyzeWriteHistories: (scenario: AutoBeAnalyzeScenarioEvent, file: AutoBeAnalyzeFile.Scenario) => Array<IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage>;
+import { ILlmSchema } from "@samchon/openapi";
+import { AutoBeContext } from "../../../context/AutoBeContext";
+export declare const transformAnalyzeWriteHistories: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, scenario: AutoBeAnalyzeScenarioEvent, file: AutoBeAnalyzeFile.Scenario) => Array<IAgenticaHistoryJson.IUserMessage | IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage>;

package/lib/orchestrate/analyze/orchestrateAnalyzeReview.d.ts

@@ -1,6 +1,11 @@
-import { AutoBeAnalyzeReviewEvent, AutoBeAnalyzeScenarioEvent } from "@autobe/interface";
+import { AutoBeAnalyzeReviewEvent, AutoBeAnalyzeScenarioEvent, AutoBeProgressEventBase } from "@autobe/interface";
 import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-import { IProgress } from "../internal/IProgress";
-export declare const orchestrateAnalyzeReview: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, scenario: AutoBeAnalyzeScenarioEvent, otherFiles: AutoBeAnalyzeFile[], myFile: AutoBeAnalyzeFile, progress: IProgress) => Promise<AutoBeAnalyzeReviewEvent>;
+export declare const orchestrateAnalyzeReview: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, props: {
+    scenario: AutoBeAnalyzeScenarioEvent;
+    allFiles: AutoBeAnalyzeFile[];
+    myFile: AutoBeAnalyzeFile;
+    progress: AutoBeProgressEventBase;
+    promptCacheKey: string;
+}) => Promise<AutoBeAnalyzeReviewEvent>;

package/lib/orchestrate/analyze/orchestrateAnalyzeWrite.d.ts

@@ -1,8 +1,10 @@
-import { AutoBeAnalyzeScenarioEvent, AutoBeAnalyzeWriteEvent } from "@autobe/interface";
+import { AutoBeAnalyzeScenarioEvent, AutoBeAnalyzeWriteEvent, AutoBeProgressEventBase } from "@autobe/interface";
 import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-export declare const orchestrateAnalyzeWrite: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, scenario: AutoBeAnalyzeScenarioEvent, file: AutoBeAnalyzeFile.Scenario, progress: {
-    total: number;
-    completed: number;
+export declare const orchestrateAnalyzeWrite: <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, props: {
+    scenario: AutoBeAnalyzeScenarioEvent;
+    file: AutoBeAnalyzeFile.Scenario;
+    progress: AutoBeProgressEventBase;
+    promptCacheKey: string;
 }) => Promise<AutoBeAnalyzeWriteEvent>;

package/lib/orchestrate/analyze/structures/IAutoBeAnalyzeReviewApplication.d.ts

@@ -12,9 +12,10 @@ export interface IAutoBeAnalyzeReviewApplication {
      * - Adding missing business processes and workflows
      * - Ensuring proper document structure and completeness
      *
-     * CRITICAL: The function outputs the actual document content that will be saved,
-     * not a review or analysis of the document. Any text output becomes part of
-     * the final document.
+     * DO: Output the actual document content that will be saved.
+     * DO NOT: Output review comments or analysis of the document.
+     *
+     * Note: Any text output becomes part of the final document.
      *
      * @param props - The properties containing the document to enhance along with
      *   plan and review criteria for guidance
@@ -40,14 +41,12 @@ export declare namespace IAutoBeAnalyzeReviewApplication {
          *
          * Critical review points:
          *
-         * - Mermaid diagrams MUST use double quotes for ALL labels
-         * - No spaces allowed between brackets and quotes in Mermaid
-         * - Requirements must be specific and measurable in natural language
-         * - Focus on business requirements and user scenarios
-         * - STRICTLY PROHIBITED: Reject if document contains database schemas or API
-         *   specifications
-         * - Business model and authentication requirements must be described in
-         *   natural language
+         * - DO: Use double quotes for ALL labels in Mermaid diagrams
+         * - DO NOT: Use spaces between brackets and quotes in Mermaid
+         * - DO: Make requirements specific and measurable in natural language
+         * - DO: Focus on business requirements and user scenarios
+         * - DO NOT: Accept documents containing database schemas or API specifications
+         * - DO: Describe business model and authentication requirements in natural language
          */
         review: string;
         /**
@@ -67,10 +66,11 @@ export declare namespace IAutoBeAnalyzeReviewApplication {
         /**
          * The actual markdown document content that incorporates review feedback.
          *
-         * ⚠️ CRITICAL: This field contains a COMPLETE MARKDOWN DOCUMENT that has
-         * already incorporated the review criteria and plan requirements. This is
-         * NOT raw input to be reviewed - it is the FINAL, PRODUCTION-READY DOCUMENT
-         * that reflects all review feedback and is immediately usable.
+         * This field contains a COMPLETE MARKDOWN DOCUMENT that has already
+         * incorporated the review criteria and plan requirements.
+         *
+         * DO: Treat this as the final, production-ready document.
+         * DO NOT: Treat this as raw input to be reviewed.
          *
          * This content represents:
          * - A fully-formed markdown document (.md file)
@@ -89,7 +89,7 @@ export declare namespace IAutoBeAnalyzeReviewApplication {
          * - Appropriate level of detail for backend implementation
          * - Proper document linking (descriptive text, not raw filenames)
          *
-         * IMPORTANT: The enhancer's output IS this document, not comments about it:
+         * The enhancer outputs the document itself:
          *
          * - If content is provided, it represents the actual document
          * - The enhancer outputs the enhanced version AS the document itself

package/lib/orchestrate/analyze/structures/IAutoBeAnalyzeScenarioApplication.d.ts

@@ -1,5 +1,6 @@
 import { AutoBeAnalyzeRole, CamelPattern } from "@autobe/interface";
 import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
+import { tags } from "typia";
 export interface IAutoBeAnalyzeScenarioApplication {
     /**
      * Compose project structure with roles and files.
@@ -25,7 +26,7 @@ export declare namespace IAutoBeAnalyzeScenarioApplication {
          * Prefix for file names and variable names. This will be used for
          * organizing documentation files.
          *
-         * MUST use camelCase naming convention.
+         * DO: Use camelCase naming convention.
          */
         prefix: string & CamelPattern;
         /** Roles to be assigned for the project */
@@ -57,9 +58,8 @@ export declare namespace IAutoBeAnalyzeScenarioApplication {
          * - Service overview and business model description
          * - User roles and permission requirements (described in natural language)
          * - Business logic and validation rules
-         * - STRICTLY PROHIBITED: Do NOT include database schemas, ERD, or API
-         *   specifications
-         * - All requirements must be written in natural language for clarity
+         * - DO NOT: Include database schemas, ERD, or API specifications
+         * - DO: Write all requirements in natural language for clarity
          *
          * Generate files based on actual requirements gathered from conversation.
          * Do not create unnecessary documentation - only generate what is needed to
@@ -73,6 +73,6 @@ export declare namespace IAutoBeAnalyzeScenarioApplication {
          * user does not specify a number, generate a sufficient number of documents
          * to adequately support the service.
          */
-        files: Array<AutoBeAnalyzeFile.Scenario>;
+        files: Array<AutoBeAnalyzeFile.Scenario> & tags.MinItems<1>;
     }
 }

package/lib/orchestrate/interface/orchestrateInterfaceAuthorizations.d.ts

@@ -1,4 +1,4 @@
-import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeInterfaceAuthorization } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-export declare function orchestrateInterfaceAuthorizations<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>): Promise<AutoBeOpenApi.IOperation[]>;
+export declare function orchestrateInterfaceAuthorizations<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>): Promise<AutoBeInterfaceAuthorization[]>;

package/lib/orchestrate/interface/orchestrateInterfaceGroups.d.ts

@@ -1,4 +1,4 @@
-import { AutoBeAssistantMessageHistory, AutoBeInterfaceGroupsEvent } from "@autobe/interface";
+import { AutoBeInterfaceGroupsEvent } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-export declare function orchestrateInterfaceGroups<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, message?: string): Promise<AutoBeAssistantMessageHistory | AutoBeInterfaceGroupsEvent>;
+export declare function orchestrateInterfaceGroups<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, message?: string): Promise<AutoBeInterfaceGroupsEvent>;

package/lib/orchestrate/interface/orchestrateInterfaceOperationsReview.d.ts

@@ -1,5 +1,4 @@
-import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeOpenApi, AutoBeProgressEventBase } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-import { IProgress } from "../internal/IProgress";
-export declare function orchestrateInterfaceOperationsReview<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, operations: AutoBeOpenApi.IOperation[], progress: IProgress): Promise<AutoBeOpenApi.IOperation[]>;
+export declare function orchestrateInterfaceOperationsReview<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, operations: AutoBeOpenApi.IOperation[], progress: AutoBeProgressEventBase): Promise<AutoBeOpenApi.IOperation[]>;

package/lib/orchestrate/interface/orchestrateInterfaceSchemasReview.d.ts

@@ -1,7 +1,4 @@
-import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeOpenApi, AutoBeProgressEventBase } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 import { AutoBeContext } from "../../context/AutoBeContext";
-export declare function orchestrateInterfaceSchemasReview<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, operations: AutoBeOpenApi.IOperation[], schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>>, progress: {
-    total: number;
-    completed: number;
-}): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>>;
+export declare function orchestrateInterfaceSchemasReview<Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>, operations: AutoBeOpenApi.IOperation[], schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>>, progress: AutoBeProgressEventBase): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>>;

package/lib/orchestrate/interface/structures/IAutoBeInterfaceComplementApplication.d.ts

@@ -17,6 +17,44 @@ export interface IAutoBeInterfaceComplementApplication {
 }
 export declare namespace IAutoBeInterfaceComplementApplication {
     interface IProps {
+        /**
+         * TypeScript draft code for complement schema definitions.
+         *
+         * This property contains TypeScript interface definitions for missing schema
+         * types that were referenced but not defined in the initial schema generation.
+         * Similar to the main schema draft, this serves as a preliminary TypeScript
+         * representation before converting to JSON Schema format.
+         *
+         * The draft helps ensure that complementary schemas maintain consistency with
+         * the existing type system and follow the same conventions as the primary schemas.
+         *
+         * This draft typically includes:
+         * - Missing entity interfaces referenced via $ref
+         * - Nested object types used within other schemas
+         * - Shared utility types or enumerations
+         * - Any transitively referenced types
+         *
+         * The final schemas in the `schemas` property should be validated against and
+         * derived from this TypeScript draft to ensure type safety and consistency
+         * across the entire API specification.
+         *
+         * Example complement draft:
+         * ```typescript
+         * interface IUserProfile {
+         *   id: string;
+         *   userId: string;
+         *   displayName: string;
+         *   avatarUrl?: string;
+         * }
+         *
+         * interface IAddress {
+         *   street: string;
+         *   city: string;
+         *   postalCode: string;
+         * }
+         * ```
+         */
+        draft: string;
         /**
          * A collection of missing schema definitions that need to be added to the
          * OpenAPI document's `components.schemas` section.

package/lib/orchestrate/interface/structures/IAutoBeInterfaceGroupApplication.d.ts

@@ -4,10 +4,10 @@ export interface IAutoBeInterfaceGroupApplication {
      * Generate logical groups for organizing API endpoint creation based on
      * Prisma schema structure.
      *
-     * Groups MUST be derived from Prisma schema organization (namespaces, file
-     * structure, table prefixes) rather than arbitrary business domains. Only
-     * create new groups when existing schema structure cannot adequately cover
-     * all requirements.
+     * DO: Derive groups from Prisma schema organization (namespaces, file
+     * structure, table prefixes) rather than arbitrary business domains.
+     * DO: Create new groups only when existing schema structure cannot adequately
+     * cover all requirements.
      *
      * @param props Properties containing the groups to be created for API
      *   organization
@@ -19,8 +19,8 @@ export declare namespace IAutoBeInterfaceGroupApplication {
         /**
          * Array of API endpoint groups for organizing development.
          *
-         * Groups MUST be organized around existing Prisma schema structure and
-         * provide complete coverage of all entities and requirements without
+         * DO: Organize groups around existing Prisma schema structure.
+         * DO: Provide complete coverage of all entities and requirements without
          * overlap.
          */
         groups: IGroup[] & tags.MinItems<1>;
@@ -31,10 +31,11 @@ export declare namespace IAutoBeInterfaceGroupApplication {
      *
      * **SCHEMA-BASED GROUP REQUIREMENTS:**
      *
-     * Groups MUST be derived from the Prisma schema structure rather than
-     * arbitrary business domain names. This ensures consistency with the
-     * underlying data model and prevents misalignment between API organization
-     * and database structure.
+     * DO: Derive groups from the Prisma schema structure rather than arbitrary
+     * business domain names.
+     *
+     * This ensures consistency with the underlying data model and prevents
+     * misalignment between API organization and database structure.
      *
      * **Primary Group Sources (in order of priority):**
      *
@@ -48,12 +49,11 @@ export declare namespace IAutoBeInterfaceGroupApplication {
      *
      * **Group Creation Guidelines:**
      *
-     * - Each group must cover specific Prisma schema entities without overlap
+     * - Each group covers specific Prisma schema entities without overlap
      * - Size groups appropriately for manageable endpoint generation cycles
      * - Maintain clear boundaries based on schema organization
      * - Ensure complete coverage of all database entities and requirements
-     * - Related database tables within the same schema area should be grouped
-     *   together
+     * - Related database tables within the same schema area are grouped together
      *
      * **When to Create Schema-Independent Groups:**
      *
@@ -68,14 +68,14 @@ export declare namespace IAutoBeInterfaceGroupApplication {
      * **Naming Standards:**
      *
      * - Use PascalCase format (e.g., "Shopping", "BBS", "UserManagement")
-     * - Names MUST directly reflect Prisma schema structure
+     * - Names directly reflect Prisma schema structure
      * - Keep names concise and schema-derived
      * - Avoid arbitrary business domain names
      * - Maintain consistency with schema organization
      *
      * **Quality Requirements:**
      *
-     * - Groups collectively must cover ALL entities and requirements
+     * - Groups collectively cover ALL entities and requirements
      * - Each database entity belongs to exactly one group
      * - Clear mapping to specific Prisma schema elements
      * - Balance group sizes within schema constraints
@@ -85,7 +85,7 @@ export declare namespace IAutoBeInterfaceGroupApplication {
         /**
          * Unique identifier name derived from Prisma schema structure.
          *
-         * Must correspond to schema namespaces, file names, table prefixes, or
+         * DO: Correspond to schema namespaces, file names, table prefixes, or
          * organizational annotations rather than arbitrary business domain names.
          */
         name: string & tags.MinLength<1>;

package/lib/orchestrate/interface/structures/IAutoBeInterfaceOperationApplication.d.ts

@@ -22,7 +22,7 @@ export declare namespace IAutoBeInterfaceOperationApplication {
         /**
          * Array of API operations to generate.
          *
-         * Each operation in this array must include:
+         * Each operation in this array includes:
          *
          * - Specification: Detailed API specification with clear purpose and
          *   functionality
@@ -37,7 +37,7 @@ export declare namespace IAutoBeInterfaceOperationApplication {
          *   components.schemas
          * - ResponseBody: With typeName referencing appropriate response type
          *
-         * All operations must follow strict quality standards:
+         * All operations follow strict quality standards:
          *
          * 1. Detailed descriptions referencing Prisma schema comments
          * 2. Accurate parameter definitions matching path parameters
@@ -64,11 +64,10 @@ export declare namespace IAutoBeInterfaceOperationApplication {
      * reason and description fields, making it clear why the API was designed and
      * how it should be used.
      *
-     * All request bodies and responses for this operation must be object types
-     * and must reference named types defined in the components section. The
-     * content-type is always `application/json`. For file upload/download
-     * operations, use `string & tags.Format<"uri">` in the appropriate schema
-     * instead of binary data formats.
+     * DO: Use object types for all request bodies and responses. DO: Reference
+     * named types defined in the components section. DO: Use `application/json`
+     * as the content-type. DO: Use `string & tags.Format<"uri">` in the schema
+     * for file upload/download operations instead of binary data formats.
      *
      * In OpenAPI, this might represent:
      *
@@ -85,7 +84,45 @@ export declare namespace IAutoBeInterfaceOperationApplication {
      * }
      * ```
      */
-    interface IOperation extends Omit<AutoBeOpenApi.IOperation, "authorizationRole"> {
+    interface IOperation extends Omit<AutoBeOpenApi.IOperation, "authorizationRole" | "authorizationType"> {
+        /**
+         * Prisma schema models relevant to this operation.
+         *
+         * Contains the complete Prisma schema definitions for all entities involved
+         * in this operation, including their fields, relations, and database
+         * constraints. This enables comprehensive validation and schema-aware
+         * operation design.
+         *
+         * The schema information serves multiple critical purposes:
+         *
+         * - **Field Verification**: Ensures all referenced fields actually exist in
+         *   the database schema and have the correct types
+         * - **Relationship Validation**: Confirms that entity relationships are
+         *   properly defined and can support the operation's data access patterns
+         * - **Soft-Delete Detection**: For DELETE operations, identifies whether
+         *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
+         *   determine if the operation should perform logical deletion instead of
+         *   physical removal
+         * - **Constraint Awareness**: Understands unique constraints, required
+         *   fields, and default values to generate accurate request/response
+         *   schemas
+         *
+         * Example content might include:
+         *
+         * ```prisma
+         * model User {
+         *   id         String    @id @default(uuid())
+         *   email      String    @unique
+         *   name       String
+         *   deleted_at DateTime? // Indicates soft-delete capability
+         *   posts      Post[]
+         * }
+         * ```
+         *
+         * This schema context ensures operations are fully aligned with the actual
+         * database structure and business logic requirements.
+         */
+        prisma_schemas: string;
         /**
          * Authorization roles required to access this API operation.
          *
@@ -93,16 +130,47 @@ export declare namespace IAutoBeInterfaceOperationApplication {
          * endpoint. Multiple roles can be specified to allow different types of
          * users to access the same endpoint.
          *
+         * ## ⚠️ CRITICAL: Role Multiplication Effect
+         *
+         * **EACH ROLE IN THIS ARRAY GENERATES A SEPARATE ENDPOINT**
+         *
+         * - If you specify `["admin", "moderator", "member"]`, this creates 3
+         *   separate endpoints
+         * - Total generated endpoints = operations × average roles.length
+         * - Example: 100 operations with 3 roles each = 300 actual endpoints
+         *
+         * ## 🔴 AVOID OVER-GENERATION
+         *
+         * **DO NOT create role-specific endpoints when a public endpoint would
+         * suffice:**
+         *
+         * - ❌ BAD: Separate GET endpoints for admin, member, moderator to view the
+         *   same public data
+         * - ✅ GOOD: Single public endpoint `[]` with role-based filtering in business
+         *   logic
+         *
+         * **DO NOT enumerate all possible roles when the Prisma schema uses a
+         * single User table:**
+         *
+         * - If Prisma has a User table with role/permission fields, you likely only
+         *   need `["user"]`
+         * - Avoid listing `["admin", "seller", "buyer", "moderator", ...]`
+         *   unnecessarily
+         * - The actual role checking happens in business logic, not at the endpoint
+         *   level
+         *
          * ## Naming Convention
          *
-         * All role names MUST use camelCase.
+         * DO: Use camelCase for all role names.
          *
          * ## Important Guidelines
          *
          * - Set to empty array `[]` for public endpoints that require no
          *   authentication
          * - Set to array with role strings for role-restricted endpoints
-         * - The role names MUST match exactly with the user type/role defined in the
+         * - **MINIMIZE the number of roles per endpoint to prevent explosion**
+         * - Consider if the endpoint can be public with role-based filtering instead
+         * - The role names match exactly with the user type/role defined in the
          *   database
          * - This will be used by the Realize Agent to generate appropriate decorator
          *   and authorization logic in the provider functions
@@ -111,11 +179,26 @@ export declare namespace IAutoBeInterfaceOperationApplication {
          *
          * ## Examples
          *
-         * - `[]` - Public endpoint, no authentication required
-         * - `["user"]` - Any authenticated user can access
-         * - `["admin"]` - Only admin users can access
+         * - `[]` - Public endpoint, no authentication required (PREFERRED for read
+         *   operations)
+         * - `["user"]` - Any authenticated user can access (PREFERRED for
+         *   user-specific operations)
+         * - `["admin"]` - Only admin users can access (USE SPARINGLY)
          * - `["admin", "moderator"]` - Both admin and moderator users can access
-         * - `["seller"]` - Only seller users can access
+         *   (AVOID if possible)
+         * - `["seller"]` - Only seller users can access (ONLY if Seller is a separate
+         *   table)
+         *
+         * ## Best Practices
+         *
+         * 1. **Start with public `[]` for all read operations** unless sensitive data
+         *    is involved
+         * 2. **Use single role `["user"]` for authenticated operations** and handle
+         *    permissions in business logic
+         * 3. **Only use multiple roles when absolutely necessary** for different
+         *    business logic paths
+         * 4. **Remember: Fewer roles = Fewer endpoints = Better performance and
+         *    maintainability**
          *
          * Note: The actual authentication/authorization implementation will be
          * handled by decorators at the controller level, and the provider function

package/lib/orchestrate/interface/structures/IAutoBeInterfaceOperationsReviewApplication.d.ts

@@ -91,6 +91,80 @@ export declare namespace IAutoBeInterfaceOperationsReviewApplication {
          * operations unchanged. These operations are validated and ready for schema
          * generation and subsequent implementation phases.
          */
-        content: AutoBeOpenApi.IOperation[];
+        content: IOperation[];
+    }
+    /**
+     * Operation of the Restful API.
+     *
+     * This interface defines a single API endpoint with its HTTP {@link method},
+     * {@link path}, {@link parameters path parameters},
+     * {@link requestBody request body}, and {@link responseBody} structure. It
+     * corresponds to an individual operation in the paths section of an OpenAPI
+     * document.
+     *
+     * Each operation requires a detailed explanation of its purpose through the
+     * reason and description fields, making it clear why the API was designed and
+     * how it should be used.
+     *
+     * All request bodies and responses for this operation must be object types
+     * and must reference named types defined in the components section. The
+     * content-type is always `application/json`. For file upload/download
+     * operations, use `string & tags.Format<"uri">` in the appropriate schema
+     * instead of binary data formats.
+     *
+     * In OpenAPI, this might represent:
+     *
+     * ```json
+     * {
+     *   "/shoppings/customers/orders": {
+     *     "post": {
+     *       "description": "Create a new order application from shopping cart...",
+     *       "parameters": [...],
+     *       "requestBody": {...},
+     *       "responses": {...}
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface IOperation extends Omit<AutoBeOpenApi.IOperation, "authorizationType"> {
+        /**
+         * Prisma schema models relevant to this operation.
+         *
+         * Contains the complete Prisma schema definitions for all entities involved
+         * in this operation, including their fields, relations, and database
+         * constraints. This enables comprehensive validation and schema-aware
+         * operation design.
+         *
+         * The schema information serves multiple critical purposes:
+         *
+         * - **Field Verification**: Ensures all referenced fields actually exist in
+         *   the database schema and have the correct types
+         * - **Relationship Validation**: Confirms that entity relationships are
+         *   properly defined and can support the operation's data access patterns
+         * - **Soft-Delete Detection**: For DELETE operations, identifies whether
+         *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
+         *   determine if the operation should perform logical deletion instead of
+         *   physical removal
+         * - **Constraint Awareness**: Understands unique constraints, required
+         *   fields, and default values to generate accurate request/response
+         *   schemas
+         *
+         * Example content might include:
+         *
+         * ```prisma
+         * model User {
+         *   id         String    @id @default(uuid())
+         *   email      String    @unique
+         *   name       String
+         *   deleted_at DateTime? // Indicates soft-delete capability
+         *   posts      Post[]
+         * }
+         * ```
+         *
+         * This schema context ensures operations are fully aligned with the actual
+         * database structure and business logic requirements.
+         */
+        prisma_schemas: string;
     }
 }

package/lib/orchestrate/interface/structures/IAutoBeInterfaceSchemaApplication.d.ts

@@ -13,10 +13,9 @@ export interface IAutoBeInterfaceSchemaApplication {
      * creation. This ensures that the final OpenAPI document has complete type
      * coverage for all operations.
      *
-     * CRITICAL: All schema definitions must follow the established naming
-     * conventions (IEntityName, IEntityName.ICreate, etc.) and must be thoroughly
-     * documented with descriptions that reference the original Prisma schema
-     * comments.
+     * DO: Follow established naming conventions (IEntityName,
+     * IEntityName.ICreate, etc.) DO: Document thoroughly with descriptions that
+     * reference the original Prisma schema comments.
      *
      * @param props Properties containing components to generate.
      */
@@ -24,6 +23,39 @@ export interface IAutoBeInterfaceSchemaApplication {
 }
 export declare namespace IAutoBeInterfaceSchemaApplication {
     interface IProps {
+        /**
+         * TypeScript draft code for schema definitions.
+         *
+         * This property contains TypeScript interface definitions that serve as a
+         * preliminary draft before generating the final JSON schema components.
+         * The draft allows for initial design and validation of the schema structure
+         * using TypeScript's type system before converting to OpenAPI/JSON Schema format.
+         *
+         * The draft typically includes:
+         * - Entity interfaces matching the Prisma models
+         * - Operation-specific variants (ICreate, IUpdate, etc.)
+         * - Utility types and enumerations
+         * - Type relationships and constraints
+         *
+         * This TypeScript draft serves as the foundation for the subsequent schema
+         * generation, ensuring type safety and consistency. The final schemas in the
+         * `schemas` property should be derived from and validated against this draft.
+         *
+         * Example draft structure:
+         * ```typescript
+         * interface IUser {
+         *   id: string;
+         *   email: string;
+         *   profile: IUserProfile;
+         * }
+         *
+         * namespace IUser {
+         *   interface ICreate extends Omit<IUser, "id"> {}
+         *   interface IUpdate extends Partial<ICreate> {}
+         * }
+         * ```
+         */
+        draft: string;
         /**
          * Complete set of schema components for the OpenAPI specification.
          *
@@ -31,23 +63,23 @@ export declare namespace IAutoBeInterfaceSchemaApplication {
          * the system. It is the central repository of all named schema types that
          * will be used throughout the API specification.
          *
-         * CRITICAL REQUIREMENT: All object types MUST be defined as named types in
-         * the components.schemas section. Inline anonymous object definitions are
-         * strictly prohibited.
+         * DO: Define all object types as named types in the components.schemas
+         * section. DO NOT: Use inline anonymous object definitions.
          *
-         * This components object should include:
+         * This components object includes:
          *
          * - Main entity types (IEntityName)
          * - Operation-specific variants (.ICreate, .IUpdate, .ISummary, etc.)
          * - Container types (IPage<T> for pagination)
          * - Enumeration types
          *
-         * All schema definitions must include detailed descriptions that reference
-         * the original Prisma schema comments and thoroughly document each
-         * property. Every property that references an object must use a $ref to a
-         * named type in the components.schemas section. This applies to all objects
-         * in request bodies, response bodies, and properties that are objects or
-         * arrays of objects.
+         * DO: Include detailed descriptions that reference the original Prisma
+         * schema comments and thoroughly document each property. DO: Use a $ref to
+         * a named type in the components.schemas section for every property that
+         * references an object.
+         *
+         * This applies to all objects in request bodies, response bodies, and
+         * properties that are objects or arrays of objects.
          *
          * Example structure:
          *