feat(agen): detailed guideline about realize phase. (#1283)

* feat(agen): detailed guideline about realize phase.

* add test cases

* fix format

* fix orchestrateRealizeCorrectWithRetry

Author: samchon

packages/agent/prompts/REALIZE_OPERATION_CORRECT.md

@@ -46,7 +46,7 @@ export namespace IAutoBeRealizeOperationCorrectApplication {
 
 ## 4. Common Error Patterns
 
-> **Reuse first**: When errors concentrate in `data:` or `select`/transform blocks, call `getRealizeCollectors`/`getRealizeTransformers` first. If a Transformer exists for the model you're querying, use `Transformer.select()` + `Transformer.transform()` — this is the **MOST COMMON fix** for "missing properties" errors. Similarly, `Collector.collect(...)` eliminates write-side errors.
+> **Reuse first — THE #1 FIX**: Call `getRealizeCollectors`/`getRealizeTransformers` BEFORE patching any error manually. If a matching Transformer or Collector exists, use it — see **4.11** and **4.12**.
 
 > **Nullable relation access**: If you see `'X.Y' is possibly 'null'`, add a null guard (`if (!X.Y) throw new HttpException(...)`) or use optional chaining (`X.Y?.prop ?? null`) before accessing properties of nullable Prisma relations.
 
@@ -290,6 +290,49 @@ data: { parent_category_id: null }
 data: { metadata: Prisma.DbNull }  // only valid for Json? type
 ```
 
+### 4.11. Transformer Available but Not Used
+
+If TS2322 errors concentrate in the return object and the code has no `Transformer.select()`/`.transform()` calls — **compare with the template code** provided above. The template already shows which Transformers to use. Rewrite the read side to follow the template's Transformer pattern instead of patching manual mapping line by line.
+
+```typescript
+// ❌ WRONG — manual mapping ignoring template's Transformer guidance
+return {
+  task: timer.task ? { project: timer.task.project ? {...} : null } : null,
+} satisfies IHrmPlatformTimer.ISummary;  // TS2322: nullable vs non-nullable
+
+// ✅ FIX — Follow the template: use Transformer.select() + .transform()
+const timer = await MyGlobal.prisma.hrm_platform_timers.findUniqueOrThrow({
+  where: { id: timerId },
+  ...HrmPlatformTimerAtSummaryTransformer.select(),
+});
+return await HrmPlatformTimerAtSummaryTransformer.transform(timer);
+```
+
+For **composite responses** (e.g., dashboard), the template maps each property to its neighbor Transformer — follow that mapping.
+
+### 4.12. Transformer select/transform Pairing Violation
+
+`Transformer.select()` and `Transformer.transform()` **MUST** always be paired. `select()` shapes the Prisma payload for `transform()` — using one without the other causes type mismatches.
+
+```typescript
+// ❌ select() without transform() — manual mapping of transformer-shaped data
+return { id: record.id, name: record.name };
+
+// ❌ transform() without select() — wrong data shape
+const record = await MyGlobal.prisma.users.findUniqueOrThrow({
+  where: { id },
+  select: { id: true, name: true },  // Manual select
+});
+return await UserAtSummaryTransformer.transform(record);  // Type mismatch
+
+// ✅ Always pair both
+const record = await MyGlobal.prisma.users.findUniqueOrThrow({
+  where: { id },
+  ...UserAtSummaryTransformer.select(),
+});
+return await UserAtSummaryTransformer.transform(record);
+```
+
 ## 5. Unrecoverable Errors
 
 When schema-API mismatch is fundamental:
@@ -309,6 +352,9 @@ export async function method__path(props: {...}): Promise<IResponse> {
 
 | Error | First Try | Alternative |
 |-------|-----------|-------------|
+| 2322 (deep type mismatch in return) + no Transformer calls | **Follow the template's Transformer pattern** | - |
+| select() without transform() | Add matching `.transform()` call | - |
+| transform() without select() | Add matching `.select()` call | - |
 | 2353 (field doesn't exist) | DELETE the field | Use correct field name |
 | 2322 (null → string) | Add `?? ""` | Check if optional |
 | 2322 (Date → string) | `.toISOString()` | - |
@@ -329,7 +375,9 @@ export async function method__path(props: {...}): Promise<IResponse> {
 ## 7. Final Checklist
 
 ### Reuse Check
-- [ ] Errors in `data:` or `select`/transform: checked for matching Collector/Transformer before patching
+- [ ] Compared current code with the template — if template uses Transformers/Collectors, code follows the same pattern
+- [ ] Every `Transformer.select()` has a matching `.transform()` call (and vice versa)
+- [ ] Composite responses: each nested DTO uses its neighbor Transformer per the template
 
 ### Compiler Authority
 - [ ] NO compiler errors remain

packages/agent/src/orchestrate/realize/correct/orchestrateRealizeCorrectWithRetry.ts

@@ -1,5 +1,6 @@
 import { AutoBeRealizeFunction } from "@autobe/interface";
 
+import { AutoBeConfigConstant } from "../../../constants/AutoBeConfigConstant";
 import { IAutoBeRealizeFunctionResult } from "../structures/IAutoBeRealizeFunctionResult";
 
 export async function orchestrateRealizeCorrectWithRetry<
@@ -22,28 +23,38 @@ export async function orchestrateRealizeCorrectWithRetry<
     return await props.correctOverall(casted);
   };
 
-  //----
-  // FIRST ATTEMPT
-  //----
-  // write functions
-  const results: IAutoBeRealizeFunctionResult<Func>[] = await process(
-    await props.write(),
+  const partition = (
+    results: IAutoBeRealizeFunctionResult<Func>[],
+  ): IPartition<Func> => ({
+    success: results.filter((r) => r.success).map((r) => r.function),
+    failures: results.filter((r) => !r.success).map((r) => r.function),
+  });
+
+  // first attempt
+  const initial: IPartition<Func> = partition(
+    await process(await props.write()),
   );
+  const success: Func[] = initial.success;
+  let failures: Func[] = initial.failures;
 
-  // filter success and failures
-  const filter = (v: boolean) =>
-    results.filter((r) => r.success === v).map((r) => r.function);
-  const success: Func[] = filter(true);
-  const failures: Func[] = filter(false);
+  // retry loop
+  const limit: number = Math.max(
+    Math.floor(AutoBeConfigConstant.COMPILER_RETRY / 2),
+    1,
+  );
+  for (let i: number = 0; failures.length !== 0 && i < limit; i++) {
+    const retry: IPartition<Func> = partition(
+      await process(await props.rewrite(failures)),
+    );
+    success.push(...retry.success);
+    failures = retry.failures;
+  }
 
-  // no failures, return success
-  if (failures.length === 0) return success;
+  // remaining failures are included as-is
+  return [...success, ...failures];
+}
 
-  //----
-  // RETRY
-  //----
-  const retryResults: IAutoBeRealizeFunctionResult<Func>[] = await process(
-    await props.rewrite(failures),
-  );
-  return [...success, ...retryResults.map((r) => r.function)];
+interface IPartition<Func extends AutoBeRealizeFunction> {
+  success: Func[];
+  failures: Func[];
 }

packages/agent/src/orchestrate/realize/orchestrateRealizeOperationCorrectOverall.ts

@@ -101,11 +101,12 @@ export const orchestrateRealizeOperationCorrectOverall = async (
               (c) =>
                 c.plan.dtoTypeName === scenario.operation.requestBody?.typeName,
             ),
-            realizeTransformers: props.transformers.filter(
-              (t) =>
-                t.plan.dtoTypeName ===
-                scenario.operation.responseBody?.typeName.replace(/^IPage/, ""),
-            ),
+            realizeTransformers:
+              AutoBeRealizeOperationProgrammer.getLocalTransformers({
+                operation: scenario.operation,
+                schemas: document.components.schemas,
+                transformers: props.transformers,
+              }),
           },
         });
       },
@@ -143,13 +144,21 @@ export const orchestrateRealizeOperationCorrectOverall = async (
               thinking: result.data.thinking,
               request: result.data.request,
             });
-          const errors: IValidation.IError[] = validateEmptyCode({
-            name: next.function.name,
-            draft: result.data.request.draft,
-            revise: result.data.request.revise,
-            path: "$input.request",
-            asynchronous: true,
-          });
+          const errors: IValidation.IError[] = [
+            ...validateEmptyCode({
+              name: next.function.name,
+              draft: result.data.request.draft,
+              revise: result.data.request.revise,
+              path: "$input.request",
+              asynchronous: true,
+            }),
+            ...AutoBeRealizeOperationProgrammer.validateSelectTransformContract(
+              {
+                draft: result.data.request.draft,
+                revise: result.data.request.revise,
+              },
+            ),
+          ];
           return errors.length
             ? {
                 success: false,

packages/agent/src/orchestrate/realize/orchestrateRealizeOperationWrite.ts

@@ -145,11 +145,12 @@ async function process(
         (c) =>
           c.plan.dtoTypeName === props.scenario.operation.requestBody?.typeName,
       ),
-      realizeTransformers: props.transformers.filter(
-        (t) =>
-          t.plan.dtoTypeName ===
-          props.scenario.operation.responseBody?.typeName.replace(/^IPage/, ""),
-      ),
+      realizeTransformers:
+        AutoBeRealizeOperationProgrammer.getLocalTransformers({
+          operation: props.scenario.operation,
+          schemas: props.document.components.schemas,
+          transformers: props.transformers,
+        }),
       analysisSections: ragSections,
     },
   });
@@ -254,13 +255,19 @@ function createController(props: {
         request: result.data.request,
       });
 
-    const errors: IValidation.IError[] = validateEmptyCode({
-      name: props.functionName,
-      draft: result.data.request.draft,
-      revise: result.data.request.revise,
-      path: "$input.request",
-      asynchronous: true,
-    });
+    const errors: IValidation.IError[] = [
+      ...validateEmptyCode({
+        name: props.functionName,
+        draft: result.data.request.draft,
+        revise: result.data.request.revise,
+        path: "$input.request",
+        asynchronous: true,
+      }),
+      ...AutoBeRealizeOperationProgrammer.validateSelectTransformContract({
+        draft: result.data.request.draft,
+        revise: result.data.request.revise,
+      }),
+    ];
     return errors.length
       ? {
           success: false,

packages/agent/src/orchestrate/realize/programmers/AutoBeRealizeOperationProgrammer.ts

@@ -5,14 +5,15 @@ import {
   AutoBeRealizeTransformerFunction,
   IAutoBeCompiler,
 } from "@autobe/interface";
-import { StringUtil } from "@autobe/utils";
+import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
 import { OpenApiTypeChecker } from "@typia/utils";
 import { IValidation } from "typia";
 
 import { AutoBeContext } from "../../../context/AutoBeContext";
 import { IAutoBeRealizeScenarioResult } from "../structures/IAutoBeRealizeScenarioResult";
 import { AutoBeRealizeCollectorProgrammer } from "./AutoBeRealizeCollectorProgrammer";
 import { AutoBeRealizeTransformerProgrammer } from "./AutoBeRealizeTransformerProgrammer";
+import { resolvePropertyTransformer } from "./internal/resolvePropertyTransformer";
 import { writeRealizeOperationTemplate } from "./internal/writeRealizeOperationTemplate";
 
 export namespace AutoBeRealizeOperationProgrammer {
@@ -177,6 +178,43 @@ export namespace AutoBeRealizeOperationProgrammer {
     );
   }
 
+  /**
+   * Resolves transformers relevant to an operation, including neighbor
+   * transformers for composite response types (e.g., dashboard endpoints).
+   * Falls back to direct top-level match for simple response types.
+   */
+  export function getLocalTransformers(props: {
+    operation: AutoBeOpenApi.IOperation;
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+    transformers: AutoBeRealizeTransformerFunction[];
+  }): AutoBeRealizeTransformerFunction[] {
+    const responseTypeName = props.operation.responseBody?.typeName;
+    if (!responseTypeName) return [];
+
+    const innerTypeName = responseTypeName.replace(/^IPage/, "");
+
+    // Direct match (covers simple and paginated types)
+    const direct = props.transformers.filter(
+      (t) => t.plan.dtoTypeName === innerTypeName,
+    );
+    if (direct.length > 0) return direct;
+
+    // Composite: resolve each property's transformer
+    const schema = props.schemas[innerTypeName];
+    if (!schema || !AutoBeOpenApiTypeChecker.isObject(schema)) return [];
+
+    const results: AutoBeRealizeTransformerFunction[] = [];
+    for (const value of Object.values(schema.properties ?? {})) {
+      const resolved = resolvePropertyTransformer({
+        schema: value as AutoBeOpenApi.IJsonSchemaProperty,
+        transformers: props.transformers,
+      });
+      if (resolved && !results.includes(resolved.transformer))
+        results.push(resolved.transformer);
+    }
+    return results;
+  }
+
   export function validateEmptyCode(props: {
     functionName: string;
     draft: string;
@@ -204,6 +242,81 @@ export namespace AutoBeRealizeOperationProgrammer {
       });
     return errors;
   }
+
+  /**
+   * Validates that Transformer.select() and Transformer.transform() are always
+   * used as a pair in operation code. Using one without the other causes type
+   * mismatches: select() shapes the Prisma payload for transform(), so they
+   * must appear together.
+   */
+  export function validateSelectTransformContract(props: {
+    draft: string;
+    revise: {
+      final: string | null;
+    };
+  }): IValidation.IError[] {
+    const errors: IValidation.IError[] = [];
+    validateSelectTransformContractForCode({
+      content: props.draft,
+      path: "$input.request.draft",
+      errors,
+    });
+    if (props.revise.final !== null) {
+      validateSelectTransformContractForCode({
+        content: props.revise.final,
+        path: "$input.request.revise.final",
+        errors,
+      });
+    }
+    return errors;
+  }
+}
+
+function validateSelectTransformContractForCode(props: {
+  content: string;
+  path: string;
+  errors: IValidation.IError[];
+}): void {
+  const selectUsers: Set<string> = new Set();
+  const transformUsers: Set<string> = new Set();
+  const selectRegex: RegExp = /(\w+Transformer)\.select/g;
+  const transformRegex: RegExp = /(\w+Transformer)\.transform/g;
+  let match: RegExpExecArray | null;
+  while ((match = selectRegex.exec(props.content)) !== null)
+    selectUsers.add(match[1]!);
+  while ((match = transformRegex.exec(props.content)) !== null)
+    transformUsers.add(match[1]!);
+  for (const name of transformUsers) {
+    if (selectUsers.has(name) === false)
+      props.errors.push({
+        path: props.path,
+        expected: `${name}.select() must appear in the query when ${name}.transform() is used.`,
+        value: props.content,
+        description: StringUtil.trim`
+          You call ${name}.transform() but never include ${name}.select()
+          in your Prisma query. The Payload type of ${name}.transform()
+          is derived from ${name}.select() — without it, the data shape
+          will not match and you will get type mismatch compile errors.
+          Add \`...${name}.select()\` to your Prisma query's select/spread.
+        `,
+      });
+  }
+  for (const name of selectUsers) {
+    if (transformUsers.has(name) === false)
+      props.errors.push({
+        path: props.path,
+        expected: `${name}.transform() must be called when ${name}.select() is used.`,
+        value: props.content,
+        description: StringUtil.trim`
+          You include ${name}.select() in your query but never call
+          ${name}.transform() to convert the result. The data fetched
+          via ${name}.select() is a raw Prisma payload shaped for
+          ${name}.transform() — assigning it directly to a DTO field
+          or transforming it inline will cause type mismatches. Call
+          ${name}.transform() on the fetched data.
+        `,
+      });
+  }
 }
 
 function writeImportStatements(props: {