@pattern-stack/codegen 0.7.4 → 0.7.6

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -722,6 +722,132 @@ function processSearchQueries(queriesBlock, processedFields, belongsTo, entityNa
   };
 }
 
+// ============================================================================
+// Sync write-surface derivation (#374)
+// ============================================================================
+
+/**
+ * Pre-compute the inbound-sync write surface for a `pattern: Synced` entity.
+ * Keeps the EJS thin + unit-testable: the template hand-emits the syncConfig
+ * literal (so `refTable` can carry a LIVE Drizzle table handle, which
+ * renderPatternConfigLiteral cannot express) using these locals.
+ *
+ * Returns null when the entity is not Synced.
+ *
+ * @param {string} patternName     resolved pattern name
+ * @param {object[]} processedFields  nonFkFields (camel + tsType + nullable)
+ * @param {object[]} belongsTo      clpBelongsTo entries
+ * @param {boolean} hasTimestamps
+ * @param {boolean} eavEnabled
+ * @param {boolean} hasSoftDelete
+ */
+export function buildSyncSurface(patternName, processedFields, belongsTo, hasTimestamps, eavEnabled, hasSoftDelete, fields) {
+  if (patternName !== 'Synced') return null;
+
+  // Copy-through columns: every non-FK declared field. external_id_tracking
+  // columns (external_id/provider/provider_metadata) are injected by the
+  // behavior, NOT present in processedFields, so they're already excluded.
+  const writeColumns = processedFields.map((f) => f.camelName);
+
+  // FK resolvers — one per belongs_to. writeKey = `${relationKey}ExternalId`
+  // (Decision 4). refTable is the string 'self' for self-FKs, else the parent
+  // table var name (emitted as a live identifier by the template).
+  const fkResolvers = belongsTo.map((rel) => ({
+    column: rel.camelField,
+    writeKey: `${rel.relationKey}ExternalId`,
+    refTable: rel.isSelfFk ? 'self' : rel.relatedTable,
+    isSelfFk: rel.isSelfFk,
+    nullable: rel.nullable,
+    // Strict resolution (throw on unresolved parent → failed item) when the FK
+    // COLUMN is required/non-null; opportunistic null otherwise. Sourced from
+    // the FK field's `required` — the relationship-level `nullable` is
+    // unreliable (defaults true when undeclared, e.g. a `belongs_to` with no
+    // explicit `nullable:`). Nullable FKs (e.g. self-FK hierarchies) stay
+    // opportunistic. (#374)
+    strict: fields?.[rel.field]?.required === true,
+    relatedTable: rel.relatedTable,
+    relatedEntity: rel.relatedEntity,
+    importPath: rel.importPath,
+  }));
+
+  // Projection columns: id + externalId + copy-through + local FK columns +
+  // timestamps. Omits provider/provider_metadata.
+  const projectionColumns = [
+    'id',
+    'externalId',
+    ...writeColumns,
+    ...belongsTo.map((rel) => rel.camelField),
+    ...(hasTimestamps ? ['createdAt', 'updatedAt'] : []),
+  ];
+
+  // The syncConfig object literal the template hand-emits. fkResolvers carry a
+  // sentinel so the template can swap `refTable` to either 'self' or the live
+  // table identifier.
+  const syncConfig = {
+    conflictTarget: ['provider', 'externalId'],
+    writeColumns,
+    projectionColumns,
+    eav: !!eavEnabled,
+    softDelete: !!hasSoftDelete,
+  };
+
+  // TSyncWrite fields: externalId:string, copy-through (typed, nullable-aware),
+  // one `<writeKey>?: string | null` per FK, fields?: Record<string, unknown>.
+  const writeFields = processedFields.map((f) => ({
+    camelName: f.camelName,
+    tsType: f.nullable ? `${f.tsType} | null` : f.tsType,
+  }));
+  const writeFkFields = fkResolvers.map((fk) => ({
+    name: fk.writeKey,
+    tsType: 'string | null',
+  }));
+
+  // TSyncProjection fields: id + externalId + copy-through (typed) + each local
+  // FK column (typed string, nullable per rel) + createdAt/updatedAt.
+  const projectionFields = [
+    { camelName: 'id', tsType: 'string' },
+    { camelName: 'externalId', tsType: 'string' },
+    ...processedFields.map((f) => ({
+      camelName: f.camelName,
+      tsType: f.nullable ? `${f.tsType} | null` : f.tsType,
+    })),
+    ...belongsTo.map((rel) => ({
+      camelName: rel.camelField,
+      tsType: rel.nullable ? 'string | null' : 'string',
+    })),
+    ...(hasTimestamps
+      ? [
+          { camelName: 'createdAt', tsType: 'Date' },
+          { camelName: 'updatedAt', tsType: 'Date' },
+        ]
+      : []),
+  ];
+
+  // Parent-table imports for non-self FKs, deduped (#368). Each entry imports
+  // the parent table var from its entity file. The entity's OWN table import is
+  // emitted separately by the template; we exclude self-FKs here.
+  const parentImportMap = new Map();
+  for (const fk of fkResolvers) {
+    if (fk.isSelfFk) continue;
+    if (!parentImportMap.has(fk.relatedTable)) {
+      parentImportMap.set(fk.relatedTable, {
+        table: fk.relatedTable,
+        importPath: fk.importPath,
+      });
+    }
+  }
+  const parentTableImports = Array.from(parentImportMap.values());
+
+  return {
+    syncConfig,
+    fkResolvers,
+    writeFields,
+    writeFkFields,
+    projectionFields,
+    parentTableImports,
+  };
+}
+
 // ============================================================================
 // Main export
 // ============================================================================
@@ -1028,6 +1154,17 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     zodChainOutput: zodChainForOutput(f),
   }));
 
+  // Sync write-surface derivation (#374) — null unless pattern: Synced.
+  const syncSurface = buildSyncSurface(
+    patternName,
+    nonFkFields,
+    belongsTo,
+    hasTimestamps,
+    eavEnabled,
+    hasSoftDelete,
+    fields,
+  );
+
   // EVT-7: emits locals flow through from baseLocals (prompt.js computed them
   // against the full events registry). When this helper is called in isolation
   // (e.g. from unit tests) baseLocals.hasEmits may be undefined — provide
@@ -1072,6 +1209,17 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     renderPatternConfigLiteral,
     ...patternConfigClasses,
 
+    // Sync write-surface (#374) — emitted only for pattern: Synced. The
+    // template hand-emits the syncConfig literal (live refTable handles) +
+    // TSyncWrite/TSyncProjection from these.
+    hasSyncSurface: syncSurface !== null,
+    clpSyncConfig: syncSurface?.syncConfig ?? null,
+    clpSyncFkResolvers: syncSurface?.fkResolvers ?? [],
+    clpSyncWriteFields: syncSurface?.writeFields ?? [],
+    clpSyncWriteFkFields: syncSurface?.writeFkFields ?? [],
+    clpSyncProjectionFields: syncSurface?.projectionFields ?? [],
+    clpSyncParentTableImports: syncSurface?.parentTableImports ?? [],
+
     // Behavior flags (also exposed at top level for template use)
     hasTimestamps,
     hasSoftDelete,

package/templates/entity/new/clean-lite-ps/repository.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.repository : nul
 skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject } from '@nestjs/common';
 <%_
 // CGP-358: FK methods with opts take priority over same-named declarative query impl.
@@ -21,15 +22,65 @@ import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc
 import { sql } from 'drizzle-orm';
 <% } -%>
 import { DRIZZLE } from '@shared/constants/tokens';
-import type { DrizzleClient<% if (eavValueTable) { %>, DrizzleTx<% } %> } from '@shared/types/drizzle';
+import type { DrizzleClient<% if (eavValueTable || (typeof hasSyncSurface !== 'undefined' && hasSyncSurface)) { %>, DrizzleTx<% } %> } from '@shared/types/drizzle';
 import { <%= repositoryBaseClass %> } from '<%= repositoryBaseImport %>';
+<% if (typeof hasSyncSurface !== 'undefined' && hasSyncSurface) { -%>
+import type { SyncUpsertConfig } from '@shared/base-classes/sync-upsert-config';
+<% } -%>
 <% if (hasTimestamps || hasSoftDelete || hasUserTracking) { -%>
 import type { BehaviorConfig } from '@shared/base-classes/base-repository';
 <% } -%>
+<% if (eavEnabled) { -%>
+import { FieldValueService } from '../field_values/field_value.service';
+<% } -%>
 import { <%= entityNamePlural %>, type <%= classNames.entity %> } from './<%= entityName %>.entity';
+<%_ if (typeof hasSyncSurface !== 'undefined' && hasSyncSurface) { _%>
+<%_ clpSyncParentTableImports.forEach((imp) => { _%>
+import { <%= imp.table %> } from '<%= imp.importPath %>';
+<%_ }); _%>
+<%_ } _%>
+<%_ if (typeof hasSyncSurface !== 'undefined' && hasSyncSurface) { _%>
+
+/**
+ * Canonical fields a synced <%= entityName %> write carries (#374). Copy-through
+ * columns are typed from the entity; each FK is named by its parent's external
+ * id and resolved <%= clpSyncFkResolvers.length > 0 ? 'in syncUpsertOne' : 'as configured' %>. Provider/providerMetadata are persistence
+ * seam, not carried here.
+ */
+export interface <%= classNames.entity %>SyncWrite {
+  readonly externalId: string;
+<%_ clpSyncWriteFields.forEach((f) => { _%>
+  readonly <%= f.camelName %>: <%- f.tsType %>;
+<%_ }); _%>
+<%_ clpSyncWriteFkFields.forEach((f) => { _%>
+  readonly <%= f.name %>?: <%- f.tsType %>;
+<%_ }); _%>
+  /** Flat custom-field bag (EAV). */
+  readonly fields?: Record<string, unknown>;
+}
+
+/**
+ * Canonical-projected view of a <%= entityName %> row, keyed for the sync differ
+ * (#374). external_id_tracking columns (provider/providerMetadata) are OMITTED;
+ * externalId is kept.
+ */
+export interface <%= classNames.entity %>SyncProjection {
+<%_ clpSyncProjectionFields.forEach((f) => { _%>
+  readonly <%= f.camelName %>: <%- f.tsType %>;
+<%_ }); _%>
+}
+<%_ } _%>
 
 @Injectable()
+<%_ if (typeof hasSyncSurface !== 'undefined' && hasSyncSurface) { _%>
+export class <%= classNames.repository %> extends <%= repositoryBaseClass %><
+  <%= classNames.entity %>,
+  <%= classNames.entity %>SyncWrite,
+  <%= classNames.entity %>SyncProjection
+> {
+<%_ } else { _%>
 export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%= classNames.entity %>> {
+<%_ } _%>
   readonly table = <%= entityNamePlural %>;
 <% if (hasTimestamps || hasSoftDelete || hasUserTracking) { -%>
 
@@ -48,10 +99,50 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
   // runtime (identical shape to `behaviors: BehaviorConfig`).
   protected override readonly patternConfig = <%- renderPatternConfigLiteral(patternConfig, '  ', '  ') %> as const;
 <% } -%>
+<%_ if (typeof hasSyncSurface !== 'undefined' && hasSyncSurface) { _%>
 
+  // Inbound-sync write surface (#374). Drives the generic syncUpsertOne /
+  // findByExternalIdProjected / softDeleteByExternalId on the base. FK
+  // resolvers carry LIVE Drizzle table handles ('self' → this.table).
+  protected readonly syncConfig: SyncUpsertConfig = {
+    conflictTarget: [<%- clpSyncConfig.conflictTarget.map((c) => `'${c}'`).join(', ') %>],
+    writeColumns: [<%- clpSyncConfig.writeColumns.map((c) => `'${c}'`).join(', ') %>],
+    fkResolvers: [
+<%_ clpSyncFkResolvers.forEach((fk) => { _%>
+      { column: '<%= fk.column %>', writeKey: '<%= fk.writeKey %>', refTable: <%- fk.isSelfFk ? "'self'" : fk.refTable %><%= fk.strict ? ', strict: true' : '' %> },
+<%_ }); _%>
+    ],
+    projectionColumns: [<%- clpSyncConfig.projectionColumns.map((c) => `'${c}'`).join(', ') %>],
+    eav: <%= clpSyncConfig.eav %>,
+    softDelete: <%= clpSyncConfig.softDelete %>,
+  };
+<%_ } _%>
+
+<%_ if (eavEnabled) { -%>
+  constructor(
+    @Inject(DRIZZLE) db: DrizzleClient,
+    private readonly fieldValues: FieldValueService,
+  ) {
+    super(db);
+  }
+
+  /**
+   * EAV dual-write override (#374 seam → #124 live path). Delegates to the
+   * shared FieldValueService so the inbound-sync write joins the same tx.
+   */
+  protected override async writeCustomFields(
+    db: DrizzleTx,
+    entityId: string,
+    userId: string,
+    fields: Record<string, unknown>,
+  ): Promise<void> {
+    await this.fieldValues.upsertFieldsTransactional('<%= entityName %>', entityId, userId, fields, db);
+  }
+<%_ } else { -%>
   constructor(@Inject(DRIZZLE) db: DrizzleClient) {
     super(db);
   }
+<%_ } -%>
 <% if (hasDeclarativeQueries) { -%>
 
   // ═══════════════════════════════════════════════════════════════════════

package/templates/entity/new/clean-lite-ps/search-controller.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.searchController
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.searchController %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasSearchQuery) { -%>
 import { BadRequestException, Controller, Get, Query } from '@nestjs/common';
 import { z } from 'zod';

package/templates/entity/new/clean-lite-ps/service.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.service : null %
 skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject, Optional } from '@nestjs/common';
 import { WithAnalytics } from '@shared/base-classes/with-analytics';
 import { EVENT_BUS } from '@shared/constants/tokens';

package/templates/entity/new/clean-lite-ps/use-cases/create.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.createUseCase :
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.createUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (eavEnabled) { -%>
 import { Injectable, Inject } from '@nestjs/common';
 import { DRIZZLE } from '<%= drizzleTokenImport %>';

package/templates/entity/new/clean-lite-ps/use-cases/declarative-queries.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= (typeof clpOutputPaths !== 'undefined' && hasDeclarativeQueries) ? clpOutputPaths.declarativeQueries : null %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasDeclarativeQueries) { -%>
 /**
  * Declarative Query Use Cases for <%= classNames.entity %>

package/templates/entity/new/clean-lite-ps/use-cases/delete.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.deleteUseCase :
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.deleteUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasEmits && deleteEventType) { -%>
 import { Injectable, Inject, NotFoundException } from '@nestjs/common';
 import { DRIZZLE } from '<%= drizzleTokenImport %>';

package/templates/entity/new/clean-lite-ps/use-cases/find-by-id-with-fields.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.findByIdWithFiel
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.findByIdWithFieldsUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
 import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';

package/templates/entity/new/clean-lite-ps/use-cases/find-by-id.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.findByIdUseCase : null %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
 import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';

package/templates/entity/new/clean-lite-ps/use-cases/list-with-fields.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.listWithFieldsUs
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.listWithFieldsUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
 import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';

package/templates/entity/new/clean-lite-ps/use-cases/list.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.listUseCase : null %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
 import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';

package/templates/entity/new/clean-lite-ps/use-cases/search.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.searchUseCase :
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.searchUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasSearchQuery) { -%>
 import { Injectable } from '@nestjs/common';
 import { and, asc, eq<% if (searchQuery.searchField) { %>, ilike<% } %>, type SQL } from 'drizzle-orm';

package/templates/entity/new/clean-lite-ps/use-cases/update.ejs.t

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.updateUseCase :
 skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.updateUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (eavEnabled) { -%>
 import { Injectable, Inject } from '@nestjs/common';
 import { DRIZZLE } from '<%= drizzleTokenImport %>';

package/templates/entity/new/frontend/entity/collection.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic') %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Collection
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/combined.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'monolithic' ? `${locations.frontendGenerated.pa
 skip_if: <%= !frontendEnabled || (generate.structure !== 'monolithic') %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> - Generated Entity Module
  *

package/templates/entity/new/frontend/entity/fields.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic' || !generate.fieldMetadata) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Field Metadata
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/hooks.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic') %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Hooks
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/index.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure !== 'entity-first') %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> - Entity Module
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/mutation-hooks.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic' || !generate.mutations || !(exposeTrpc || exposeRepository)) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Mutation Hooks
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/mutations.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic' || !generate.mutations || !(exposeTrpc || exposeRepository)) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Mutations
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/entity/types.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.
 skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic') %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Types
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/store/hooks.ejs.t

@@ -3,6 +3,7 @@ to: <%= locations.frontendStoreEntities.path %>/<%= name %>.ts
 skip_if: <%= !frontendEnabled || (!generate.hooks) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Entity Hooks
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/frontend/unified-entity.ejs.t

@@ -3,6 +3,7 @@ to: <%= locations.frontendEntities.path %>/<%= name %>.ts
 skip_if: <%= !frontendEnabled %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> - Unified Entity API
  *

package/templates/entity/new/prompt.js

@@ -24,6 +24,7 @@ import {
   getGenerateConfig,
 } from "../../../src/config/paths.mjs";
 import { getNamingConfig } from "../../../src/config/naming-config.mjs";
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
 
 // ============================================================================
 // Behavior Registry (inline to avoid import issues with Hygen)
@@ -1383,7 +1384,25 @@ export default {
     const drizzleTokenImport = '@shared/constants/tokens';
     const drizzleTypeImport = '@shared/types/drizzle';
 
+    // @generated banner — single line stamped at the top of every
+    // force-overwritten output. `yamlPath` is the consumer-relative source
+    // (e.g. `entities/opportunity.yaml`). Extension seam differs by
+    // architecture: clean-lite-ps customises via patterns, clean via the
+    // base-class behavior config / repository subclass.
+    const generatedBanner = renderGeneratedBanner({
+      // Relative to cwd so the banner is portable across machines (an absolute
+      // path would bake a developer's checkout root into every output).
+      source: path.relative(process.cwd(), fullPath),
+      generator: 'entity',
+      seam: isCleanLitePs
+        ? 'a pattern (src/patterns/*.pattern.ts) or the entity YAML'
+        : 'the entity YAML or a base-class behavior config',
+    });
+
     const locals = {
+      // @generated DO-NOT-EDIT banner (see renderGeneratedBanner)
+      generatedBanner,
+
       // Database configuration
       databaseDialect,
       schemaDir: BASE_PATHS.schemaDir,

package/templates/junction/new/entity.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.entity %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import {
 <%_ drizzleImports.filter(i => i !== 'relations').forEach(i => { _%>
   <%= i %>,
@@ -45,8 +46,10 @@ export const <%= tableVarName %> = pgTable(
     <%= rightColumnCamel %>: uuid('<%= rightColumn %>').notNull().references(() => <%= rightTable %>.id, { onDelete: '<%= onDeleteRight %>' }),
 <%_ if (hasRole) { _%>
 
-    // Role enum (per-pairing; declared in junction YAML's fields.role.choices)
-    role: <%= roleEnumName %>('role'),
+    // Role enum (per-pairing; declared in junction YAML's fields.role.choices).
+    // NOT NULL because role is part of the junction's identity (composite PK
+    // below): the same pair with two different roles is two distinct rows.
+    role: <%= roleEnumName %>('role').notNull(),
 <%_ } _%>
 
     // BaseJunctionFields — is_primary is always emitted
@@ -83,8 +86,17 @@ export const <%= tableVarName %> = pgTable(
     updatedAt: timestamp('updated_at').notNull().defaultNow(),
   },
   (table) => [
+<%_ if (hasRole) { _%>
+    // Composite primary key on the two FK columns PLUS role (Q4 resolution: no
+    // surrogate id). Role is part of the junction's identity — the same pair
+    // with two different roles is two distinct rows (e.g. a contact who is both
+    // `champion` and `decision_maker` on one opportunity). This is the
+    // ON CONFLICT target for syncUpsert on role-bearing junctions.
+    primaryKey({ columns: [table.<%= leftColumnCamel %>, table.<%= rightColumnCamel %>, table.role] }),
+<%_ } else { _%>
     // Composite primary key on the two FK columns (Q4 resolution: no surrogate id)
     primaryKey({ columns: [table.<%= leftColumnCamel %>, table.<%= rightColumnCamel %>] }),
+<%_ } _%>
   ],
 );
 

package/templates/junction/new/index.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.index %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= classNames.entity %> module barrel export
  * Generated by junction codegen — do not edit directly

package/templates/junction/new/module.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.module %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module, forwardRef } from '@nestjs/common';
 import { DatabaseModule } from '@shared/database/database.module';