@pattern-stack/codegen 0.10.1 → 0.12.0

package/templates/entity/new/backend/modules/core/{sync-source.ejs.t → integration-source.ejs.t}

@@ -1,17 +1,17 @@
 ---
-to: "<%= hasDetection ? (isCleanLitePs ? clpOutputPaths.syncSourceModule : `${basePaths.backendSrc}/${paths.modules}/${name}-sync-source.module.ts`) : null %>"
+to: "<%= hasDetection ? (isCleanLitePs ? clpOutputPaths.integrationSourceModule : `${basePaths.backendSrc}/${paths.modules}/${name}-integration-source.module.ts`) : null %>"
 skip_if: <%= !hasDetection %>
 force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module } from '@nestjs/common';
-import { buildChangeSource } from '@shared/subsystems/sync';
+import { buildChangeSource } from '@shared/subsystems/integration';
 import type {
   DetectionConfig,
   IChangeSource,
   PollFetchCallback,
-} from '@shared/subsystems/sync';
-import type { <%= className %> } from '<%= isCleanLitePs ? clpImports.syncSourceToEntity : imports.moduleToDomain %>';
+} from '@shared/subsystems/integration';
+import type { <%= className %> } from '<%= isCleanLitePs ? clpImports.integrationSourceToEntity : imports.moduleToDomain %>';
 
 const <%= name.toUpperCase() %>_DETECTION_CONFIGS: Record<string, DetectionConfig> = <%- detectionConfigsLiteral %>;
 
@@ -31,7 +31,7 @@ export const <%= name.toUpperCase() %>_CHANGE_SOURCES = Symbol('<%= name.toUpper
             const fetch = fetches[provider];
             if (!fetch) {
               throw new Error(
-                `<%= className %>SyncSourceModule: missing fetch callback for provider '${provider}' in <%= name.toUpperCase() %>_POLL_FETCH_REGISTRY`,
+                `<%= className %>IntegrationSourceModule: missing fetch callback for provider '${provider}' in <%= name.toUpperCase() %>_POLL_FETCH_REGISTRY`,
               );
             }
             return [provider, buildChangeSource(cfg, fetch)];
@@ -41,4 +41,4 @@ export const <%= name.toUpperCase() %>_CHANGE_SOURCES = Symbol('<%= name.toUpper
   ],
   exports: [<%= name.toUpperCase() %>_CHANGE_SOURCES],
 })
-export class <%= className %>SyncSourceModule {}
+export class <%= className %>IntegrationSourceModule {}

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

@@ -22,6 +22,10 @@ import { type InferSelectModel } from 'drizzle-orm';
 import { <%= rel.relatedTable %> } from '<%= rel.importPath %>';
 <%_ } _%>
 <%_ }) _%>
+<%_ /* #354: field-level foreign_key target table imports */ _%>
+<%_ if (typeof clpFieldFkImports !== 'undefined') { clpFieldFkImports.forEach(imp => { _%>
+import { <%= imp.relatedTable %> } from '<%= imp.importPath %>';
+<%_ }) } _%>
 <%_ /* CGP-358b: import has_many target tables for many() relation const */ _%>
 <%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
 <%_ clpExistingHasMany.filter(rel => !rel.isSelfRef).forEach(rel => { _%>
@@ -65,10 +69,15 @@ export const <%= entityNamePlural %> = pgTable(
     deletedAt: timestamp('deleted_at'),
 <%_ } _%>
   },
-<%_ if (hasExternalIdTracking) { _%>
+<%_ /* #355/#356: pgTable extra-config — indexes + composite unique indexes + external_id unique index */ _%>
+<%_ if (typeof clpTableConstraints !== 'undefined' && clpTableConstraints.length > 0) { _%>
   (t) => [
-    // external_id_tracking behavior — ON CONFLICT target for syncUpsert
-    uniqueIndex('uq_<%= entityNamePlural %>_provider_external_id').on(t.provider, t.externalId),
+<%_ clpTableConstraints.forEach(c => { _%>
+<%_ if (c.comment) { _%>
+    // <%= c.comment %>
+<%_ } _%>
+    <%- c.expr %>,
+<%_ }) _%>
   ],
 <%_ } _%>
 );

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

@@ -116,7 +116,7 @@ import { <%= classNames.searchController %> } from './<%= entityName %>-search.c
   // exported so sibling modules that compose this entity cross-module (junction
   // `.list()`, EAV value→definition resolution) inject the home-module instance
   // — the only place the repo's own deps are wired (e.g. an EAV entity's repo
-  // injects FieldValueService for the #374 sync dual-write tx). Local-providing
+  // injects FieldValueService for the #374 integration dual-write tx). Local-providing
   // such a repo elsewhere can't satisfy those deps. Use-case internals stay unexported.
   exports: [<%= classNames.service %>, <%= classNames.repository %>],
 })

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

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import pluralizePkg from 'pluralize';
 // The patterns barrel has the side effect of pre-registering the five
-// library-shipped patterns (Base / Synced / Activity / Knowledge /
+// library-shipped patterns (Base / Integrated / Activity / Knowledge /
 // Metadata). App-defined patterns are loaded separately in the parent
 // prompt.js via loadAppPatterns() against `codegen.config.yaml patterns:`
 // globs before this helper runs — we only read the registry here.
@@ -108,7 +108,7 @@ export function resolvePatternBaseClasses(entity) {
 /**
  * Resolve the behaviors implied by an entity's declared pattern(s).
  *
- * A pattern (e.g. `Synced`) may declare `impliedBehaviors` — behaviors the
+ * A pattern (e.g. `Integrated`) may declare `impliedBehaviors` — behaviors the
  * entity gets for free without re-declaring them in its `behaviors:` array.
  * Walks every declared pattern (both the `pattern: X` and `patterns: [...]`
  * shapes), unions their `impliedBehaviors`, and returns a deduped list.
@@ -145,6 +145,7 @@ const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 const camelCase = (s) => s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 const pascalCase = (s) => capitalize(camelCase(s));
 const pluralize = (s) => pluralizePkg.plural(s);
+const singularize = (s) => pluralizePkg.singular(s);
 
 // ============================================================================
 // Drizzle type mapping
@@ -260,15 +261,45 @@ function buildDrizzleChain(fieldName, field, drizzleType, enumName) {
     chain += '.notNull()';
   }
 
-  // Boolean defaults
-  if (drizzleType === 'boolean' && hasDefault) {
-    chain += `.default(${field.default})`;
+  // Column defaults (#345). The value is validated upstream (schema `default:`).
+  // Covers every scalar type, enum literals, and the `now` sentinel on
+  // timestamp/date columns — not just booleans.
+  if (hasDefault) {
+    chain += renderColumnDefault(field.default, drizzleType);
   }
 
-  // Timestamp defaults for datetime fields in behavior context handled separately
   return chain;
 }
 
+/**
+ * Render a Drizzle `.default(...)` (or `.defaultNow()`) suffix for a column.
+ *
+ * - timestamp/date + a `now`/`now()`/`current_timestamp` sentinel → `.defaultNow()`
+ * - numeric (Drizzle returns it as a string) → quoted, even for numeric YAML values
+ * - string / enum literal → single-quoted, escaped
+ * - number / boolean → bare literal
+ * - anything else (jsonb object/array default) → JSON literal
+ */
+function renderColumnDefault(value, drizzleType) {
+  if (
+    (drizzleType === 'timestamp' || drizzleType === 'date') &&
+    typeof value === 'string' &&
+    /^(now|now\(\)|current_timestamp)$/i.test(value)
+  ) {
+    return '.defaultNow()';
+  }
+  if (drizzleType === 'numeric') {
+    return `.default('${String(value)}')`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return `.default(${value})`;
+  }
+  if (typeof value === 'string') {
+    return `.default('${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}')`;
+  }
+  return `.default(${JSON.stringify(value)})`;
+}
+
 /**
  * Process entity fields into ProcessedField[]
  */
@@ -446,10 +477,95 @@ function processBelongsTo(relationships, parentEntityNamePlural) {
   return result;
 }
 
+/**
+ * Field-level `foreign_key:` + `index:` emission (#354, #355).
+ *
+ * Distinct from `relationships:`-driven belongs_to FKs (processBelongsTo),
+ * which own their own column + import. This handles features declared
+ * directly on a column field:
+ *
+ *   - `foreign_key: <table>.<column>` → append `.references(() => <table>.<column>)`
+ *     to the column's Drizzle chain (self-FKs get the `: AnyPgColumn` annotation)
+ *     and record the cross-module import. The table segment is the Drizzle table
+ *     export name (plural, e.g. `conversations`); the import path singularizes it
+ *     to the entity file (`../conversations/conversation.entity`).
+ *   - `index: true` → emit a named single-column index in the pgTable
+ *     extra-config callback (`<table>_<column>_idx`).
+ *
+ * Mutates each processed field's `drizzleChain` in place (the same objects are
+ * later rendered via clpProcessedFields). Returns the imports + index
+ * expressions the template needs.
+ *
+ * @param {object[]} renderedFields  the fields actually emitted as columns
+ *                                   (nonFkFields — belongs_to FK columns excluded)
+ * @param {object}   fields          raw field map keyed by snake_case name
+ * @param {string}   entityNamePlural Drizzle table export name for self-FK detection
+ */
+function processFieldFeatures(renderedFields, fields, entityNamePlural) {
+  const fkImports = [];
+  const indexExpressions = [];
+  const seenImports = new Set();
+  let hasSelfFieldFk = false;
+
+  for (const pf of renderedFields) {
+    const field = fields[pf.name];
+    if (!field) continue;
+
+    // --- foreign_key (#354) ---
+    if (typeof field.foreign_key === 'string' && field.foreign_key.includes('.')) {
+      const [relatedTable, fkColumn] = field.foreign_key.split('.');
+      const isSelfFk = relatedTable === entityNamePlural;
+      pf.drizzleChain += isSelfFk
+        ? `.references((): AnyPgColumn => ${relatedTable}.${fkColumn})`
+        : `.references(() => ${relatedTable}.${fkColumn})`;
+
+      if (isSelfFk) {
+        hasSelfFieldFk = true;
+      } else if (!seenImports.has(relatedTable)) {
+        seenImports.add(relatedTable);
+        fkImports.push({
+          relatedTable,
+          importPath: `../${relatedTable}/${singularize(relatedTable)}.entity`,
+        });
+      }
+    }
+
+    // --- index: true (#355) ---
+    if (field.index === true) {
+      indexExpressions.push({
+        comment: null,
+        expr: `index('${entityNamePlural}_${pf.name}_idx').on(t.${pf.camelName})`,
+      });
+    }
+  }
+
+  return { fkImports, indexExpressions, hasSelfFieldFk };
+}
+
+/**
+ * Composite unique index emission (#356).
+ *
+ * Top-level `unique_indexes: [{ fields: [...], name? }]` → a `uniqueIndex(...)`
+ * entry in the pgTable extra-config callback. Column names are camelCased to
+ * match the emitted Drizzle column identifiers; they may reference FK columns
+ * (belongs_to) or ordinary fields. Index name defaults to
+ * `<table>_<col1>_<col2>_..._uniq`.
+ */
+function processUniqueIndexes(uniqueIndexes, entityNamePlural) {
+  if (!Array.isArray(uniqueIndexes)) return [];
+
+  return uniqueIndexes.map((ui) => {
+    const cols = ui.fields;
+    const name = ui.name || `${entityNamePlural}_${cols.join('_')}_uniq`;
+    const onCols = cols.map((c) => `t.${camelCase(c)}`).join(', ');
+    return { comment: null, expr: `uniqueIndex('${name}').on(${onCols})` };
+  });
+}
+
 /**
  * Collect drizzle imports needed for entity fields
  */
-function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany = []) {
+function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany = [], extraImports = []) {
   const imports = new Set(['pgTable', 'uuid']);
 
   for (const field of processedFields) {
@@ -475,7 +591,7 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
 
   // external_id_tracking behavior injects varchar + jsonb columns plus a
   // unique index over (provider, external_id) — the ON CONFLICT target the
-  // sync sink's syncUpsert relies on.
+  // integration sink's integrationUpsert relies on.
   if (hasExternalIdTracking) {
     imports.add('varchar');
     imports.add('jsonb');
@@ -486,6 +602,13 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
     imports.add('relations');
   }
 
+  // Caller-supplied extras: `index` (field-level index: true) and
+  // `uniqueIndex` (composite unique_indexes) — see processFieldFeatures /
+  // processUniqueIndexes.
+  for (const extra of extraImports) {
+    imports.add(extra);
+  }
+
   return Array.from(imports).sort();
 }
 
@@ -725,16 +848,16 @@ function processSearchQueries(queriesBlock, processedFields, belongsTo, entityNa
 }
 
 // ============================================================================
-// Sync write-surface derivation (#374)
+// Integration 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
+ * Pre-compute the inbound-integration write surface for a `pattern: Integrated` entity.
+ * Keeps the EJS thin + unit-testable: the template hand-emits the integrationConfig
  * 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.
+ * Returns null when the entity is not Integrated.
  *
  * @param {string} patternName     resolved pattern name
  * @param {object[]} processedFields  nonFkFields (camel + tsType + nullable)
@@ -743,8 +866,8 @@ function processSearchQueries(queriesBlock, processedFields, belongsTo, entityNa
  * @param {boolean} eavEnabled
  * @param {boolean} hasSoftDelete
  */
-export function buildSyncSurface(patternName, processedFields, belongsTo, hasTimestamps, eavEnabled, hasSoftDelete, fields) {
-  if (patternName !== 'Synced') return null;
+export function buildIntegrationSurface(patternName, processedFields, belongsTo, hasTimestamps, eavEnabled, hasSoftDelete, fields) {
+  if (patternName !== 'Integrated') return null;
 
   // Copy-through columns: every non-FK declared field. external_id_tracking
   // columns (external_id/provider/provider_metadata) are injected by the
@@ -782,10 +905,10 @@ export function buildSyncSurface(patternName, processedFields, belongsTo, hasTim
     ...(hasTimestamps ? ['createdAt', 'updatedAt'] : []),
   ];
 
-  // The syncConfig object literal the template hand-emits. fkResolvers carry a
+  // The integrationConfig 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 = {
+  const integrationConfig = {
     conflictTarget: ['provider', 'externalId'],
     writeColumns,
     projectionColumns,
@@ -793,7 +916,7 @@ export function buildSyncSurface(patternName, processedFields, belongsTo, hasTim
     softDelete: !!hasSoftDelete,
   };
 
-  // TSyncWrite fields: externalId:string, copy-through (typed, nullable-aware),
+  // TIntegrationWrite 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,
@@ -804,7 +927,7 @@ export function buildSyncSurface(patternName, processedFields, belongsTo, hasTim
     tsType: 'string | null',
   }));
 
-  // TSyncProjection fields: id + externalId + copy-through (typed) + each local
+  // TIntegrationProjection fields: id + externalId + copy-through (typed) + each local
   // FK column (typed string, nullable per rel) + createdAt/updatedAt.
   const projectionFields = [
     { camelName: 'id', tsType: 'string' },
@@ -841,7 +964,7 @@ export function buildSyncSurface(patternName, processedFields, belongsTo, hasTim
   const parentTableImports = Array.from(parentImportMap.values());
 
   return {
-    syncConfig,
+    integrationConfig,
     fkResolvers,
     writeFields,
     writeFkFields,
@@ -885,6 +1008,18 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const entityNamePlural = entity.plural || pluralize(entityName);
   const entityNamePluralPascal = pascalCase(entityNamePlural);
 
+  // #403: bounded-context folder grouping. A top-level `context:` nests this
+  // entity's module folder under that segment so same-context entities group
+  // together (`<modules>/<context>/<plural>/`); no context → flat
+  // (`<modules>/<plural>/`, byte-identical to pre-#403). Emit-folder-only —
+  // every intra-module import is folder-relative and therefore unaffected, and
+  // the generated barrel recomputes its import paths from the full file paths
+  // below. The module-folder base used by every clpOutputPaths entry:
+  const entityContext = definition.context || null;
+  const moduleGroupDir = entityContext
+    ? `${srcRoot}/modules/${entityContext}`
+    : `${srcRoot}/modules`;
+
   // Generation toggles — `generate.writes` defaults to true so consumers who
   // regenerate pick up create/update/delete use cases without YAML changes.
   // Set `generate.writes: false` in YAML to suppress write-side emission
@@ -953,7 +1088,7 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   // Behavior flags (re-read from behaviors array for clean-lite-ps use).
   //
   // Fold in the resolved pattern's `impliedBehaviors` (ADR-031): an entity
-  // declaring e.g. `pattern: Synced` need not re-declare the
+  // declaring e.g. `pattern: Integrated` need not re-declare the
   // `external_id_tracking` behavior — the pattern contributes it. Deduped
   // with any explicit `behaviors:` entries, explicit-first so order is
   // stable for pre-existing fixtures. Mirrors the dedup in
@@ -1033,6 +1168,33 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const fkFieldNames = new Set(belongsTo.map((r) => r.field));
   const nonFkFields = processedFields.filter((f) => !fkFieldNames.has(f.name));
 
+  // Field-level foreign_key + index emission (#354, #355). Mutates the
+  // drizzleChain of the rendered (non-belongs_to) columns in place. Skip FK
+  // imports for tables belongs_to already imports to avoid duplicate import
+  // lines.
+  const fieldFeatures = processFieldFeatures(nonFkFields, fields, entityNamePlural);
+  const belongsToTables = new Set(belongsTo.map((r) => r.relatedTable));
+  const clpFieldFkImports = fieldFeatures.fkImports.filter(
+    (imp) => !belongsToTables.has(imp.relatedTable),
+  );
+
+  // Composite unique indexes (#356).
+  const uniqueIndexExpressions = processUniqueIndexes(definition.unique_indexes, entityNamePlural);
+
+  // pgTable extra-config callback entries, in emission order: single-column
+  // indexes, composite unique indexes, then the external_id_tracking unique
+  // index (the ON CONFLICT target integrationUpsert relies on).
+  const clpTableConstraints = [
+    ...fieldFeatures.indexExpressions,
+    ...uniqueIndexExpressions,
+  ];
+  if (hasExternalIdTracking) {
+    clpTableConstraints.push({
+      comment: 'external_id_tracking behavior — ON CONFLICT target for integrationUpsert',
+      expr: `uniqueIndex('uq_${entityNamePlural}_provider_external_id').on(t.provider, t.externalId)`,
+    });
+  }
+
   // Enum field declarations — surface a separate collection so the entity
   // template can emit `export const xEnum = pgEnum('x', [...])` ahead of
   // the `pgTable(...)` block. Both FK-filtered and unfiltered processing
@@ -1045,59 +1207,70 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
       choices: f.choices,
     }));
 
-  // Drizzle imports needed
-  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany);
+  // Drizzle imports needed. `index` / `uniqueIndex` are pulled in only when a
+  // field declares `index: true` or the entity declares `unique_indexes:`
+  // (external_id_tracking adds `uniqueIndex` on its own flag below).
+  const extraDrizzleImports = [];
+  if (fieldFeatures.indexExpressions.length > 0) extraDrizzleImports.push('index');
+  if (uniqueIndexExpressions.length > 0) extraDrizzleImports.push('uniqueIndex');
+  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany, extraDrizzleImports);
   // Whether relations() import is needed (CGP-358b: also trigger on has_many)
   const hasRelationsBlock = belongsTo.length > 0 || hasMany.length > 0;
 
   // Output paths
   const outputPaths = {
-    entity: `${srcRoot}/modules/${entityNamePlural}/${entityName}.entity.ts`,
-    repository: `${srcRoot}/modules/${entityNamePlural}/${entityName}.repository.ts`,
-    service: `${srcRoot}/modules/${entityNamePlural}/${entityName}.service.ts`,
-    controller: `${srcRoot}/modules/${entityNamePlural}/${entityName}.controller.ts`,
-    module: `${srcRoot}/modules/${entityNamePlural}/${entityNamePlural}.module.ts`,
-    index: `${srcRoot}/modules/${entityNamePlural}/index.ts`,
-    findByIdUseCase: `${srcRoot}/modules/${entityNamePlural}/use-cases/find-${entityName}-by-id.use-case.ts`,
-    listUseCase: `${srcRoot}/modules/${entityNamePlural}/use-cases/list-${entityNamePlural}.use-case.ts`,
+    entity: `${moduleGroupDir}/${entityNamePlural}/${entityName}.entity.ts`,
+    repository: `${moduleGroupDir}/${entityNamePlural}/${entityName}.repository.ts`,
+    service: `${moduleGroupDir}/${entityNamePlural}/${entityName}.service.ts`,
+    controller: `${moduleGroupDir}/${entityNamePlural}/${entityName}.controller.ts`,
+    module: `${moduleGroupDir}/${entityNamePlural}/${entityNamePlural}.module.ts`,
+    index: `${moduleGroupDir}/${entityNamePlural}/index.ts`,
+    findByIdUseCase: `${moduleGroupDir}/${entityNamePlural}/use-cases/find-${entityName}-by-id.use-case.ts`,
+    listUseCase: `${moduleGroupDir}/${entityNamePlural}/use-cases/list-${entityNamePlural}.use-case.ts`,
     findByIdWithFieldsUseCase: eavEnabled
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/find-${entityName}-by-id-with-fields.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/find-${entityName}-by-id-with-fields.use-case.ts`
       : null,
     listWithFieldsUseCase: eavEnabled
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/list-${entityNamePlural}-with-fields.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/list-${entityNamePlural}-with-fields.use-case.ts`
       : null,
     createUseCase: generateWrites
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/create-${entityName}.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/create-${entityName}.use-case.ts`
       : null,
     updateUseCase: generateWrites
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/update-${entityName}.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/update-${entityName}.use-case.ts`
       : null,
     deleteUseCase: generateWrites
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/delete-${entityName}.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/delete-${entityName}.use-case.ts`
       : null,
-    createDto: `${srcRoot}/modules/${entityNamePlural}/dto/create-${entityName}.dto.ts`,
-    updateDto: `${srcRoot}/modules/${entityNamePlural}/dto/update-${entityName}.dto.ts`,
-    outputDto: `${srcRoot}/modules/${entityNamePlural}/dto/${entityName}-output.dto.ts`,
+    createDto: `${moduleGroupDir}/${entityNamePlural}/dto/create-${entityName}.dto.ts`,
+    updateDto: `${moduleGroupDir}/${entityNamePlural}/dto/update-${entityName}.dto.ts`,
+    outputDto: `${moduleGroupDir}/${entityNamePlural}/dto/${entityName}-output.dto.ts`,
     searchUseCase: searchQueryResolved
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/search-${entityNamePlural}.use-case.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/search-${entityNamePlural}.use-case.ts`
       : null,
     searchController: searchQueryResolved
-      ? `${srcRoot}/modules/${entityNamePlural}/${entityName}-search.controller.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/${entityName}-search.controller.ts`
       : null,
     declarativeQueries: hasDeclarativeQueries
-      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/declarative-queries.ts`
+      ? `${moduleGroupDir}/${entityNamePlural}/use-cases/declarative-queries.ts`
       : null,
-    // ADR-033.1 §8 — sync-source module emission for clean-lite-ps. Co-located
+    // ADR-033.1 §8 — integration-source module emission for clean-lite-ps. Co-located
     // with the entity feature module under src/modules/<plural>/. Closes #267.
-    syncSourceModule: `${srcRoot}/modules/${entityNamePlural}/${entityName}-sync-source.module.ts`,
-    syncSourceProviders: `${srcRoot}/modules/${entityNamePlural}/${entityName}-sync-source.providers.ts`,
+    // #403: routed through moduleGroupDir so a `context:`-tagged entity nests the
+    // integration-source module under its context segment (untagged → flat, the
+    // same `${srcRoot}/modules/<plural>/…` path as before).
+    integrationSourceModule: `${moduleGroupDir}/${entityNamePlural}/${entityName}-integration-source.module.ts`,
+    // ADR-033.2's per-entity provider tuples (`<entity>-integration-source.providers.ts`)
+    // are removed by RFC-0001 §8 (D4). The surface-scoped typed view
+    // (`src/integrations/<surface>/types.generated.ts`) is the single source of
+    // provider truth now — see src/cli/shared/adapter-emission-generator.ts.
   };
 
-  // Architecture-specific imports for clean-lite-ps. The sync-source module
+  // Architecture-specific imports for clean-lite-ps. The integration-source module
   // imports the entity type sibling-style (`./<entity>.entity`) since the
   // module file lives next to the entity file in the same feature folder.
   const clpImports = {
-    syncSourceToEntity: `./${entityName}.entity`,
+    integrationSourceToEntity: `./${entityName}.entity`,
   };
 
   // Class names
@@ -1156,8 +1329,8 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     zodChainOutput: zodChainForOutput(f),
   }));
 
-  // Sync write-surface derivation (#374) — null unless pattern: Synced.
-  const syncSurface = buildSyncSurface(
+  // Integration write-surface derivation (#374) — null unless pattern: Integrated.
+  const integrationSurface = buildIntegrationSurface(
     patternName,
     nonFkFields,
     belongsTo,
@@ -1211,16 +1384,16 @@ 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 ?? [],
+    // Integration write-surface (#374) — emitted only for pattern: Integrated. The
+    // template hand-emits the integrationConfig literal (live refTable handles) +
+    // TIntegrationWrite/TIntegrationProjection from these.
+    hasIntegrationSurface: integrationSurface !== null,
+    clpIntegrationConfig: integrationSurface?.integrationConfig ?? null,
+    clpIntegrationFkResolvers: integrationSurface?.fkResolvers ?? [],
+    clpIntegrationWriteFields: integrationSurface?.writeFields ?? [],
+    clpIntegrationWriteFkFields: integrationSurface?.writeFkFields ?? [],
+    clpIntegrationProjectionFields: integrationSurface?.projectionFields ?? [],
+    clpIntegrationParentTableImports: integrationSurface?.parentTableImports ?? [],
 
     // Behavior flags (also exposed at top level for template use)
     hasTimestamps,
@@ -1245,10 +1418,14 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     hasSearchQuery: !!searchQueryResolved,
 
 
+    // #403: bounded-context segment (null when untagged). Drives the
+    // module-folder nesting reflected in clpOutputPaths above.
+    clpContext: entityContext,
+
     // Output paths
     clpOutputPaths: outputPaths,
 
-    // Architecture-specific imports (ADR-033.1 §8 — sync-source closes #267)
+    // Architecture-specific imports (ADR-033.1 §8 — integration-source closes #267)
     clpImports,
 
     // Class names
@@ -1269,9 +1446,15 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     // strict mode flags the table const with TS7022/TS7024 (circular initializer).
     // Surfaced by the cgp-62 relationship-scenario smoke when generating a CRM
     // account with a `parent_account_id` self-FK.
-    clpHasSelfFk: belongsTo.some((rel) => rel.isSelfFk),
+    clpHasSelfFk: belongsTo.some((rel) => rel.isSelfFk) || fieldFeatures.hasSelfFieldFk,
     clpEnumFields,
 
+    // Field-level foreign_key imports (#354) and pgTable extra-config
+    // entries: single-column indexes (#355) + composite unique indexes (#356)
+    // + the external_id_tracking unique index.
+    clpFieldFkImports,
+    clpTableConstraints,
+
     // Declarative queries
     processedQueries,
     hasDeclarativeQueries,