@pattern-stack/codegen 0.6.8 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/src/patterns/library/base-junction-fields.ts

@@ -0,0 +1,32 @@
+/**
+ * BaseJunctionFields — shared column shape every junction table carries.
+ *
+ * Per-pairing role columns and pairing-specific fields are declared in the
+ * consumer YAML's `fields:` block and are NOT part of this shape.
+ *
+ * Exposed as a TS const so two consumers can import it:
+ *   - `junction.pattern.ts`              — registers it as the pattern's
+ *                                          column contribution so the
+ *                                          registry's `assertHasContribution()`
+ *                                          check passes structurally.
+ *   - `junction-definition.schema.ts`    — uses the name set for the
+ *                                          reserved-column collision check
+ *                                          on the consumer's `fields:` block.
+ *
+ * See ADR-031 and `.ai-docs/stacks/codegen-app-patterns/specs/58.md`.
+ */
+
+import type { PatternColumnContribution } from '../pattern-definition.js';
+
+export const BaseJunctionFields: readonly PatternColumnContribution[] = [
+	{ name: 'is_primary', type: 'boolean' },
+	{ name: 'started_at', type: 'timestamp' },
+	{ name: 'ended_at', type: 'timestamp' },
+	{ name: 'sourced_from', type: 'text' },
+	{ name: 'confidence', type: 'numeric(5,4)' },
+	{ name: 'matched_at', type: 'timestamp' },
+] as const;
+
+export const BASE_JUNCTION_FIELD_NAMES: ReadonlySet<string> = new Set(
+	BaseJunctionFields.map((c) => c.name),
+);

package/src/patterns/library/index.ts

@@ -11,6 +11,7 @@
 import { registerLibraryPattern } from '../registry.js';
 import { ActivityPattern } from './activity.pattern.js';
 import { BasePattern } from './base.pattern.js';
+import { JunctionPattern } from './junction.pattern.js';
 import { KnowledgePattern } from './knowledge.pattern.js';
 import { MetadataPattern } from './metadata.pattern.js';
 import { SyncedPattern } from './synced.pattern.js';
@@ -20,11 +21,17 @@ registerLibraryPattern(SyncedPattern);
 registerLibraryPattern(ActivityPattern);
 registerLibraryPattern(KnowledgePattern);
 registerLibraryPattern(MetadataPattern);
+registerLibraryPattern(JunctionPattern);
 
 export {
 	ActivityPattern,
 	BasePattern,
+	JunctionPattern,
 	KnowledgePattern,
 	MetadataPattern,
 	SyncedPattern,
 };
+export {
+	BaseJunctionFields,
+	BASE_JUNCTION_FIELD_NAMES,
+} from './base-junction-fields.js';

package/src/patterns/library/junction.pattern.ts

@@ -0,0 +1,41 @@
+/**
+ * JunctionPattern — top-level discriminator for explicit many-to-many
+ * junction YAML files.
+ *
+ * Unlike `Activity` / `Synced` / `Metadata` (which attach to an entity via
+ * `pattern:` / `patterns:`), `Junction` IS the top-level YAML shape — a
+ * junction file's discriminator is `pattern: Junction`, not `entity:`.
+ * It therefore does not declare `repositoryClass` / `serviceClass`: the
+ * downstream Hygen-template leaf emits a dedicated junction repo/service
+ * per pairing.
+ *
+ * `columns` is set to `BaseJunctionFields` for two reasons:
+ *   1. Registry-side declaration of the shared shape — discoverable through
+ *      `getPattern('Junction').columns` by the downstream template leaf.
+ *   2. Satisfies the registry's `assertHasContribution()` check, which
+ *      insists every pattern contribute at least one of columns / repo /
+ *      service class. (See spec §"Open Questions Q3"; recommendation (a).)
+ *
+ * See `.ai-docs/stacks/codegen-app-patterns/specs/58.md`.
+ */
+
+import { z } from 'zod';
+import { definePattern } from '../pattern-definition.js';
+import { BaseJunctionFields } from './base-junction-fields.js';
+
+/**
+ * The `pattern: Junction`-attached config block, validated at parse time.
+ *
+ * Surface is intentionally thin in this leaf — extensions land in later
+ * leaves (templates, association-codegen). `.strict()` rejects unknown
+ * keys so consumers who misspell a flag fail loudly.
+ */
+const JunctionPatternConfigSchema = z.object({}).strict();
+
+export const JunctionPattern = definePattern({
+	name: 'Junction',
+	description:
+		'Explicit many-to-many junction with role + temporal + sourcing metadata',
+	columns: [...BaseJunctionFields],
+	configSchema: JunctionPatternConfigSchema,
+});

package/templates/entity/new/backend/application/queries/get-by-id.ejs.t

@@ -16,7 +16,7 @@ force: true
 
 import { Inject, Injectable, NotFoundException } from '@nestjs/common';
 import { <%= repositoryToken %> } from '<%= imports.constants %>';
-import type { I<%= className %>Repository<%= hasRelationships ? `, ${className}With` : '' %> } from '<%= imports.domain %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>';
 import { <%= className %> } from '<%= imports.domain %>';
 
 @Injectable()
@@ -26,10 +26,10 @@ export class <%= getByIdQueryClass %> {
 		private readonly <%= camelName %>Repository: I<%= className %>Repository,
 	) {}
 
-	async execute(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>> {
+	async execute(id: string): Promise<<%= className %>> {
 		// TODO: Add authorization check if needed (row-level security)
 
-		const entity = await this.<%= camelName %>Repository.findById(id<%= hasRelationships ? ', include' : '' %>);
+		const entity = await this.<%= camelName %>Repository.findById(id);
 		if (!entity) {
 			throw new NotFoundException(`<%= className %> with id ${id} not found`);
 		}

package/templates/entity/new/backend/application/queries/grouped-index.ejs.t

@@ -14,7 +14,7 @@ force: true
 
 import { Inject, Injectable, NotFoundException } from '@nestjs/common';
 import { <%= repositoryToken %> } from '<%= imports.constants %>';
-import type { I<%= className %>Repository<%= hasRelationships ? `, ${className}With` : '' %> } from '<%= imports.domain %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>';
 import { <%= className %> } from '<%= imports.domain %>';
 
 // ============================================================================
@@ -37,10 +37,10 @@ export class <%= getByIdQueryClass %> {
 		private readonly <%= camelName %>Repository: I<%= className %>Repository,
 	) {}
 
-	async execute(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>> {
+	async execute(id: string): Promise<<%= className %>> {
 		// TODO: Add authorization check if needed (row-level security)
 
-		const entity = await this.<%= camelName %>Repository.findById(id<%= hasRelationships ? ', include' : '' %>);
+		const entity = await this.<%= camelName %>Repository.findById(id);
 		if (!entity) {
 			throw new NotFoundException(`<%= className %> with id ${id} not found`);
 		}
@@ -73,9 +73,9 @@ export class <%= listQueryClass %> {
 		private readonly <%= camelName %>Repository: I<%= className %>Repository,
 	) {}
 
-	async execute(<%= hasRelationships ? `include?: ${className}With` : '' %>): Promise<<%= className %>[]> {
+	async execute(): Promise<<%= className %>[]> {
 		// TODO: Add filtering, pagination, sorting as needed
-		return this.<%= camelName %>Repository.findAll(<%= hasRelationships ? 'include' : '' %>);
+		return this.<%= camelName %>Repository.findAll();
 	}
 }
 <% } -%>

package/templates/entity/new/backend/application/queries/index.ejs.t

@@ -11,4 +11,7 @@ force: true
 
 export * from './<%= fileNames.getByIdQuery.replace('.ts', '') %>';
 export * from './<%= fileNames.listQuery.replace('.ts', '') %>';
+<% if (hasRelationships && !isGrouped) { -%>
+export * from './relationships.queries';
+<% } -%>
 <% } -%>

package/templates/entity/new/backend/application/queries/list.ejs.t

@@ -18,7 +18,7 @@ force: true
 
 import { Inject, Injectable } from '@nestjs/common';
 import { <%= repositoryToken %> } from '<%= imports.constants %>';
-import type { I<%= className %>Repository<%= hasRelationships ? `, ${className}With` : '' %> } from '<%= imports.domain %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>';
 import { <%= className %> } from '<%= imports.domain %>';
 
 @Injectable()
@@ -28,9 +28,9 @@ export class <%= listQueryClass %> {
 		private readonly <%= camelName %>Repository: I<%= className %>Repository,
 	) {}
 
-	async execute(<%= hasRelationships ? `include?: ${className}With` : '' %>): Promise<<%= className %>[]> {
+	async execute(): Promise<<%= className %>[]> {
 		// TODO: Add filtering, pagination, sorting as needed
-		return this.<%= camelName %>Repository.findAll(<%= hasRelationships ? 'include' : '' %>);
+		return this.<%= camelName %>Repository.findAll();
 	}
 }
 <% } -%>

package/templates/entity/new/backend/application/queries/relationships.queries.ejs.t

@@ -0,0 +1,147 @@
+---
+to: "<%= (isCleanArchitecture && hasRelationships && !isGrouped) ? `${basePaths.backendSrc}/${paths.queries}/relationships.queries.ts` : '' %>"
+skip_if: <%= !(isCleanArchitecture && hasRelationships && !isGrouped) %>
+force: true
+---
+<% if (isCleanArchitecture && hasRelationships && !isGrouped) { -%>
+/**
+ * Relationship Composition Queries for <%= className %>
+ * Generated by entity codegen - do not edit directly
+ *
+ * These query classes implement service-layer composition via FK + single-table
+ * repo calls. No SQL JOINs. Two queries, no JOIN. (CGP-358 / CGP-62)
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>/<%= name %>';
+import type { <%= className %> } from '<%= imports.domain %>/<%= name %>';
+<%
+// Unique cross-entity targets (exclude self-refs which reuse same repo)
+const crossEntityTargets = [...new Map(
+  [...existingBelongsTo, ...existingHasMany, ...existingHasOne]
+    .filter(r => r.target !== name)
+    .map(r => [r.target, r])
+).values()];
+-%>
+<% crossEntityTargets.forEach((rel) => { -%>
+import type { I<%= rel.targetClass %>Repository } from '<%= imports.domain %>/<%= rel.target %>';
+import type { <%= rel.targetClass %> } from '<%= imports.domain %>/<%= rel.target %>';
+<% }) -%>
+<% existingBelongsTo.forEach((rel) => { -%>
+<%
+const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1);
+const targetCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+const isSelfRef = rel.target === name;
+-%>
+
+/**
+ * Resolves the <%= rel.name %> (<%= rel.targetClass %>) for a given <%= className %>.
+ * Two repo calls: fetch <%= className %> by id → fetch <%= rel.targetClass %> by FK.
+ */
+@Injectable()
+export class <%= className %><%= relNamePascal %>Query {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly repository: I<%= className %>Repository,
+<% if (!isSelfRef) { -%>
+		@Inject('<%= rel.target.toUpperCase() %>_REPOSITORY')
+		private readonly <%= targetCamel %>Repo: I<%= rel.targetClass %>Repository,
+<% } -%>
+	) {}
+
+	async execute(<%= camelName %>Id: string): Promise<<%= rel.targetClass %> | null> {
+		const entity = await this.repository.findById(<%= camelName %>Id);
+<% if (isSelfRef) { -%>
+		return entity ? this.repository.findById(entity.<%= rel.foreignKeyCamel %>) : null;
+<% } else { -%>
+		return entity ? this.<%= targetCamel %>Repo.findById(entity.<%= rel.foreignKeyCamel %>) : null;
+<% } -%>
+	}
+}
+<% }) -%>
+<% existingHasMany.forEach((rel) => { -%>
+<%
+const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1);
+const targetCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+const isSelfRef = rel.target === name;
+// Derive the findBy method name from the inverseForeignKey
+// inverseForeignKey = 'account_id' → foreignKeyPascal = 'AccountId'
+const fkPascal = rel.inverseForeignKeyCamel.charAt(0).toUpperCase() + rel.inverseForeignKeyCamel.slice(1);
+-%>
+
+/**
+ * Resolves the <%= rel.name %> (<%= rel.targetClass %>[]) for a given <%= className %>.
+ * Single repo call with FK filter + optional cursor/limit pagination.
+ */
+@Injectable()
+export class <%= className %><%= relNamePascal %>Query {
+	constructor(
+<% if (!isSelfRef) { -%>
+		@Inject('<%= rel.target.toUpperCase() %>_REPOSITORY')
+		private readonly <%= targetCamel %>Repo: I<%= rel.targetClass %>Repository,
+<% } else { -%>
+		@Inject(<%= repositoryToken %>)
+		private readonly repository: I<%= className %>Repository,
+<% } -%>
+	) {}
+
+	async execute(<%= camelName %>Id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= rel.targetClass %>[]> {
+<% if (!isSelfRef) { -%>
+		return this.<%= targetCamel %>Repo.findBy<%= fkPascal %>(<%= camelName %>Id, opts);
+<% } else { -%>
+		return this.repository.findBy<%= fkPascal %>(<%= camelName %>Id, opts);
+<% } -%>
+	}
+}
+<% }) -%>
+<% existingHasOne.forEach((rel) => { -%>
+<%
+const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1);
+const targetCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+const isSelfRef = rel.target === name;
+const fkPascal = rel.inverseForeignKeyCamel.charAt(0).toUpperCase() + rel.inverseForeignKeyCamel.slice(1);
+-%>
+
+/**
+ * Resolves the <%= rel.name %> (<%= rel.targetClass %>) for a given <%= className %> (has_one inverse).
+ * Single repo call returning at most one record.
+ */
+@Injectable()
+export class <%= className %><%= relNamePascal %>Query {
+	constructor(
+<% if (!isSelfRef) { -%>
+		@Inject('<%= rel.target.toUpperCase() %>_REPOSITORY')
+		private readonly <%= targetCamel %>Repo: I<%= rel.targetClass %>Repository,
+<% } else { -%>
+		@Inject(<%= repositoryToken %>)
+		private readonly repository: I<%= className %>Repository,
+<% } -%>
+	) {}
+
+	async execute(<%= camelName %>Id: string): Promise<<%= rel.targetClass %> | null> {
+<% if (!isSelfRef) { -%>
+		const results = await this.<%= targetCamel %>Repo.findBy<%= fkPascal %>(<%= camelName %>Id);
+<% } else { -%>
+		const results = await this.repository.findBy<%= fkPascal %>(<%= camelName %>Id);
+<% } -%>
+		return results[0] ?? null;
+	}
+}
+<% }) -%>
+
+export const relationshipQueryClasses = [
+<% existingBelongsTo.forEach((rel) => { -%>
+<% const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1); -%>
+	<%= className %><%= relNamePascal %>Query,
+<% }) -%>
+<% existingHasMany.forEach((rel) => { -%>
+<% const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1); -%>
+	<%= className %><%= relNamePascal %>Query,
+<% }) -%>
+<% existingHasOne.forEach((rel) => { -%>
+<% const relNamePascal = rel.name.charAt(0).toUpperCase() + rel.name.slice(1); -%>
+	<%= className %><%= relNamePascal %>Query,
+<% }) -%>
+];
+<% } -%>

package/templates/entity/new/backend/database/repository.ejs.t

@@ -19,20 +19,8 @@ import type {
 	Create<%= className %>Input,
 	I<%= className %>Repository,
 	Update<%= className %>Input,
-<% if (hasRelationships) { -%>
-	<%= className %>With,
-<% } -%>
 } from '../../../domain';
-<%
-// Collect unique entity imports - only include relationships with existing target entities
-const entityImports = new Set([className]);
-if (hasExistingRelationships) {
-  [...existingBelongsTo, ...existingHasMany, ...existingHasOne].forEach((rel) => {
-    entityImports.add(rel.targetClass);
-  });
-}
--%>
-import { <%- [...entityImports].join(', ') %> } from '../../../domain';
+import { <%= className %> } from '../../../domain';
 import { <%= plural %> } from '<%= locations.dbSchemaServer.import %>';
 
 @Injectable()
@@ -57,12 +45,20 @@ export class <%= className %>Repository
 	protected toEntity(record: typeof <%= plural %>.$inferSelect): <%= className %> {
 		return <%= className %>.fromRecord(record);
 	}
+<%_
+// CGP-358: FK methods with opts take priority over same-named declarative query impl.
+// Always emit FK methods with opts; skip the declarative query body when a FK method
+// covers the same method name (simple single-FK, non-unique, non-via, non-select).
+// The declarative use-case class still works because opts is optional.
+const _fkMethodNames = new Set(belongsToRelations.map(rel => `findBy${rel.foreignKeyPascal}`));
+_%>
 <% belongsToRelations.forEach((rel) => { -%>
 
-	async findBy<%= rel.foreignKeyPascal %>(id: string): Promise<<%= className %>[]> {
-		const records = await this.baseQuery()
+	async findBy<%= rel.foreignKeyPascal %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= className %>[]> {
+		let q = this.baseQuery()
 			.where(eq(this.table.<%= rel.foreignKeyCamel %>, id));
-		return records.map((r) => this.toEntity(r));
+		if (opts?.limit) q = (q as any).limit(opts.limit);
+		return (await q).map((r) => this.toEntity(r));
 	}
 <% }) -%>
 <% entityRefFields.forEach((ref) => { -%>
@@ -84,6 +80,12 @@ export class <%= className %>Repository
 	// Declarative queries (from queries: block in entity YAML)
 	// ═══════════════════════════════════════════════════════════════════════
 <% processedQueries.forEach((q) => { -%>
+<%_
+// Skip declarative impl when a FK method already covers this method name.
+// FK methods accept opts so they're a superset of a plain single-param non-unique query.
+const _skipDqImpl = _fkMethodNames.has(q.methodName) && !q.isUnique && !q.hasVia && !q.hasSelect;
+_%>
+<% if (!_skipDqImpl) { -%>
 
 	async <%= q.methodName %>(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>> {
 <% if (q.hasVia) { -%>
@@ -107,70 +109,8 @@ export class <%= className %>Repository
 		return records.map(r => this.toEntity(r));
 <% } -%>
 	}
-<% }) -%>
 <% } -%>
-<% if (hasRelationships) { -%>
-
-	// ═══════════════════════════════════════════════════════════════════════
-	// Relationship loading (extends base class)
-	// ═══════════════════════════════════════════════════════════════════════
-
-	async findByIdWithRelations(
-		id: string,
-		include?: <%= className %>With,
-	): Promise<<%= className %> | null> {
-		const record = await this.db.query.<%= plural %>.findFirst({
-			where: eq(<%= plural %>.id, id),
-			with: this.buildWithClause(include),
-		});
-		return record ? this.mapToEntityWithRelations(record) : null;
-	}
-
-	async findAllWithRelations(include?: <%= className %>With): Promise<<%= className %>[]> {
-		const records = await this.db.query.<%= plural %>.findMany({
-			with: this.buildWithClause(include),
-		});
-		return records.map((r) => this.mapToEntityWithRelations(r));
-	}
-
-	private buildWithClause(include?: <%= className %>With) {
-		if (!include) return undefined;
-		const result: Record<string, true> = {};
-<% relationships.forEach((rel) => { -%>
-		if (include.<%= rel.name %>) result.<%= rel.name %> = true;
 <% }) -%>
-		return Object.keys(result).length > 0 ? result : undefined;
-	}
-
-	// biome-ignore lint/suspicious/noExplicitAny: Drizzle relational query returns dynamic shape
-	private mapToEntityWithRelations(record: any): <%= className %> {
-<% if (hasExistingRelationships) { -%>
-		return <%= className %>.fromRecord(record, (name, data) => {
-			switch (name) {
-<% existingBelongsTo.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle record
-					return <%= rel.targetClass %>.fromRecord(data as any);
-<% }) -%>
-<% existingHasMany.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle records
-					return (data as any[]).map((r) => <%= rel.targetClass %>.fromRecord(r));
-<% }) -%>
-<% existingHasOne.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle record
-					return <%= rel.targetClass %>.fromRecord(data as any);
-<% }) -%>
-				default:
-					return data;
-			}
-		});
-<% } else { -%>
-		// Related entities not yet generated - return entity without relationship mapping
-		return <%= className %>.fromRecord(record);
-<% } -%>
-	}
 <% } -%>
 }
 <% } else { -%>
@@ -191,20 +131,8 @@ import type {
 	Create<%= className %>Input,
 	I<%= className %>Repository,
 	Update<%= className %>Input,
-<% if (hasRelationships) { -%>
-	<%= className %>With,
-<% } -%>
 } from '../../../domain';
-<%
-// Collect unique entity imports - only include relationships with existing target entities
-const entityImports = new Set([className]);
-if (hasExistingRelationships) {
-  [...existingBelongsTo, ...existingHasMany, ...existingHasOne].forEach((rel) => {
-    entityImports.add(rel.targetClass);
-  });
-}
--%>
-import { <%- [...entityImports].join(', ') %> } from '../../../domain';
+import { <%= className %> } from '../../../domain';
 import type { DrizzleDB } from '../database.module';
 import { <%= plural %> } from '<%= locations.dbSchemaServer.import %>';
 
@@ -238,35 +166,18 @@ export class <%= className %>Repository implements I<%= className %>Repository {
 		return <%= className %>.fromRecord(record);
 	}
 
-	async findById(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %> | null> {
-<% if (hasRelationships) { -%>
-		const record = await this.db.query.<%= plural %>.findFirst({
-			where: eq(<%= plural %>.id, id),
-			with: this.buildWithClause(include),
-		});
-
-		return record ? this.mapToEntity(record) : null;
-<% } else { -%>
+	async findById(id: string): Promise<<%= className %> | null> {
 		const result = await this.baseQuery()
 			.where(eq(<%= plural %>.id, id))
 			.limit(1);
 
 		const record = result[0];
 		return record ? <%= className %>.fromRecord(record) : null;
-<% } -%>
 	}
 
-	async findAll(<%= hasRelationships ? `include?: ${className}With` : '' %>): Promise<<%= className %>[]> {
-<% if (hasRelationships) { -%>
-		const records = await this.db.query.<%= plural %>.findMany({
-			with: this.buildWithClause(include),
-		});
-
-		return records.map((r) => this.mapToEntity(r));
-<% } else { -%>
+	async findAll(): Promise<<%= className %>[]> {
 		const records = await this.baseQuery();
 		return records.map(<%= className %>.fromRecord);
-<% } -%>
 	}
 
 	async update(id: string, input: Update<%= className %>Input<%= (hasEmits && updateEventType) ? ', tx?: DrizzleTransaction' : '' %>): Promise<<%= className %> | null> {
@@ -359,38 +270,24 @@ export class <%= className %>Repository implements I<%= className %>Repository {
 		return this.db.select().from(<%= plural %>);
 <% } -%>
 	}
+<%_
+// CGP-358: FK methods with opts take priority over same-named declarative query impl.
+// Always emit FK methods with opts; skip declarative body when FK covers it.
+const _fkMethodNamesInline = new Set(belongsToRelations.map(rel => `findBy${rel.foreignKeyPascal}`));
+_%>
 <% belongsToRelations.forEach((rel) => { -%>
 
-	async findBy<%= rel.foreignKeyPascal %>(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]> {
-<% if (hasRelationships) { -%>
-		const records = await this.db.query.<%= plural %>.findMany({
-			where: eq(<%= plural %>.<%= rel.foreignKeyCamel %>, id),
-			with: this.buildWithClause(include),
-		});
-
-		return records.map((r) => this.mapToEntity(r));
-<% } else { -%>
-		const records = await this.baseQuery()
+	async findBy<%= rel.foreignKeyPascal %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= className %>[]> {
+		let q = this.baseQuery()
 			.where(eq(<%= plural %>.<%= rel.foreignKeyCamel %>, id));
-
+		if (opts?.limit) q = (q as any).limit(opts.limit);
+		const records = await q;
 		return records.map(<%= className %>.fromRecord);
-<% } -%>
 	}
 <% }) -%>
 <% entityRefFields.forEach((ref) => { -%>
 
-	async findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>[]> {
-<% if (hasRelationships) { -%>
-		const records = await this.db.query.<%= plural %>.findMany({
-			where: and(
-				eq(<%= plural %>.<%= ref.camelName %>EntityType, entityType),
-				eq(<%= plural %>.<%= ref.camelName %>EntityId, entityId)
-			),
-			with: this.buildWithClause(include),
-		});
-
-		return records.map((r) => this.mapToEntity(r));
-<% } else { -%>
+	async findBy<%= ref.pascalName %>(entityType: EntityType, entityId: string): Promise<<%= className %>[]> {
 		const records = await this.baseQuery()
 			.where(
 				and(
@@ -400,7 +297,6 @@ export class <%= className %>Repository implements I<%= className %>Repository {
 			);
 
 		return records.map(<%= className %>.fromRecord);
-<% } -%>
 	}
 <% }) -%>
 <% if (hasDeclarativeQueries) { -%>
@@ -409,6 +305,11 @@ export class <%= className %>Repository implements I<%= className %>Repository {
 	// Declarative queries (from queries: block in entity YAML)
 	// ═══════════════════════════════════════════════════════════════════════
 <% processedQueries.forEach((q) => { -%>
+<%_
+// Skip declarative impl when a FK method already covers this method name.
+const _skipDqImplInline = _fkMethodNamesInline.has(q.methodName) && !q.isUnique && !q.hasVia && !q.hasSelect;
+_%>
+<% if (!_skipDqImplInline) { -%>
 
 	async <%= q.methodName %>(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>> {
 <% if (q.hasVia) { -%>
@@ -432,49 +333,8 @@ export class <%= className %>Repository implements I<%= className %>Repository {
 		return records.map(<%= className %>.fromRecord);
 <% } -%>
 	}
-<% }) -%>
 <% } -%>
-<% if (hasRelationships) { -%>
-
-	private buildWithClause(include?: <%= className %>With) {
-		if (!include) return undefined;
-		// Drizzle expects `true` or object, not `false`. Only include truthy values.
-		const result: Record<string, true> = {};
-<% relationships.forEach((rel) => { -%>
-		if (include.<%= rel.name %>) result.<%= rel.name %> = true;
-<% }) -%>
-		return Object.keys(result).length > 0 ? result : undefined;
-	}
-
-	// biome-ignore lint/suspicious/noExplicitAny: Drizzle relational query returns dynamic shape
-	private mapToEntity(record: any): <%= className %> {
-<% if (hasExistingRelationships) { -%>
-		return <%= className %>.fromRecord(record, (name, data) => {
-			switch (name) {
-<% existingBelongsTo.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle record
-					return <%= rel.targetClass %>.fromRecord(data as any);
 <% }) -%>
-<% existingHasMany.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle records
-					return (data as any[]).map((r) => <%= rel.targetClass %>.fromRecord(r));
-<% }) -%>
-<% existingHasOne.forEach((rel) => { -%>
-				case '<%= rel.name %>':
-					// biome-ignore lint/suspicious/noExplicitAny: Cast for Drizzle record
-					return <%= rel.targetClass %>.fromRecord(data as any);
-<% }) -%>
-				default:
-					return data;
-			}
-		});
-<% } else { -%>
-		// Related entities not yet generated - return entity without relationship mapping
-		return <%= className %>.fromRecord(record);
-<% } -%>
-	}
 <% } -%>
 }
 <% } -%>