@pattern-stack/codegen 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,10 @@
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
+    "./subsystems": {
+      "types": "./dist/runtime/subsystems/index.d.ts",
+      "default": "./dist/runtime/subsystems/index.js"
+    },
     "./runtime/*": {
       "types": "./dist/runtime/*.d.ts",
       "default": "./dist/runtime/*.js"
@@ -127,6 +131,10 @@
   ],
   "devDependencies": {
     "@anatine/zod-openapi": "^2.2.8",
+    "@pattern-stack/codegen-calendar": "workspace:*",
+    "@pattern-stack/codegen-crm": "workspace:*",
+    "@pattern-stack/codegen-mail": "workspace:*",
+    "@pattern-stack/codegen-transcript": "workspace:*",
     "@cubejs-client/core": "^1.0.0",
     "@nestjs/common": "10",
     "@nestjs/core": "10",

package/runtime/subsystems/index.ts

@@ -50,6 +50,21 @@ export type {
   CursorSnapshot,
 } from './observability';
 
+// Integration — entity change-source registry (C7) + change-source port.
+// Exposed here so L2 surface packages (e.g. @pattern-stack/codegen-crm) can
+// import them across the package boundary via @pattern-stack/codegen/subsystems
+// (Track C C6). Selective re-export (not `export *`) to avoid the
+// IntegrationRunSummary name clash with the observability barrel above.
+export {
+  ENTITY_CHANGE_SOURCE_REGISTRY,
+  MemoryEntityChangeSourceRegistry,
+  UnknownEntityError,
+} from './integration';
+export type {
+  IEntityChangeSourceRegistry,
+  IChangeSource,
+} from './integration';
+
 // Auth
 export {
   ENCRYPTION_KEY,

package/runtime/subsystems/integration/entity-change-source-registry.memory.ts

@@ -0,0 +1,40 @@
+/**
+ * Integration subsystem — in-memory entity-change-source registry
+ *
+ * Default `IEntityChangeSourceRegistry` backed by a `Map<entityName, source>`.
+ * Track D's codegen-emitted aggregator folds per-provider adapter
+ * contributions into one of these and binds it under
+ * `ENTITY_CHANGE_SOURCE_REGISTRY` (RFC-0001 §3); tests and simple consumers
+ * construct it directly.
+ *
+ * See {@link ./entity-change-source-registry.protocol} for the contract and
+ * #336 for scope.
+ */
+
+import type { IChangeSource } from './integration-change-source.protocol';
+import {
+  type IEntityChangeSourceRegistry,
+  UnknownEntityError,
+} from './entity-change-source-registry.protocol';
+
+export class MemoryEntityChangeSourceRegistry
+  implements IEntityChangeSourceRegistry
+{
+  constructor(private readonly sources: Map<string, IChangeSource<unknown>>) {}
+
+  get<T = unknown>(name: string): IChangeSource<T> {
+    const source = this.sources.get(name);
+    if (!source) {
+      throw new UnknownEntityError(name, [...this.sources.keys()]);
+    }
+    return source as IChangeSource<T>;
+  }
+
+  has(name: string): boolean {
+    return this.sources.has(name);
+  }
+
+  entities(): readonly string[] {
+    return [...this.sources.keys()];
+  }
+}

package/runtime/subsystems/integration/entity-change-source-registry.protocol.ts

@@ -0,0 +1,59 @@
+/**
+ * Integration subsystem — entity-keyed change-source registry (port)
+ *
+ * `IEntityChangeSourceRegistry` resolves an `IChangeSource<T>` by entity name.
+ * It generalizes today's per-entity DI tokens (`ACCOUNT_POLL_FETCH_REGISTRY`,
+ * `CONTACT_POLL_FETCH_REGISTRY`, …) into one entity-keyed registry, so the L3
+ * composing port (`<Surface>Port`, Track C C6) can be entity-agnostic at the
+ * type level instead of enumerating entities (epic #328 locked decision #5).
+ *
+ * This lives in L1 (the integration subsystem) rather than in a per-surface
+ * package because the same shape applies across surfaces — CRM (`account`,
+ * `contact`, `deal`), Mail (`email`, `thread`, `label`), Transcript
+ * (`transcript`, `speaker`, `utterance`), Meeting (`meeting`, `attendee`).
+ * Cross-surface plumbing belongs at L1 (epic #328 locked decision #6).
+ *
+ * Scope (Track C · C7): this is purely the L1 type + memory impl. Codegen does
+ * NOT yet emit this registry, and the existing per-entity tokens keep emitting
+ * unchanged — the retarget (and the per-entity-token deprecation) is Track D
+ * D3/D4 (RFC-0001 §3/§8).
+ *
+ * See #336 (this issue), #328 (parent epic), RFC-0001 §3 (the registry
+ * contract Track D emits the wiring for).
+ */
+
+import type { IChangeSource } from './integration-change-source.protocol';
+
+/**
+ * Entity-keyed resolver for change sources. The orchestrator (and the L3
+ * surface port) consume this, agnostic to whether a source came from a
+ * hand-written adapter or a configured `PollChangeSource<T>`.
+ */
+export interface IEntityChangeSourceRegistry {
+  /**
+   * Resolve a change source for a given entity name.
+   * Throws {@link UnknownEntityError} if the entity isn't registered.
+   */
+  get<T = unknown>(entityName: string): IChangeSource<T>;
+
+  /** True if the entity is registered. */
+  has(entityName: string): boolean;
+
+  /** List all entity names this registry serves. */
+  entities(): readonly string[];
+}
+
+/**
+ * Thrown by {@link IEntityChangeSourceRegistry.get} when no source is
+ * registered for the requested entity. The message enumerates the available
+ * entities so a misconfiguration (typo'd entity name, missing adapter
+ * contribution) is diagnosable from the error alone.
+ */
+export class UnknownEntityError extends Error {
+  constructor(entity: string, available: readonly string[]) {
+    super(
+      `No change source registered for entity '${entity}'. Available: ${available.join(', ')}`,
+    );
+    this.name = 'UnknownEntityError';
+  }
+}

package/runtime/subsystems/integration/index.ts

@@ -44,6 +44,14 @@ export type {
 } from './integration-run-recorder.protocol';
 export type { ILoopbackFingerprintStore } from './integration-loopback.protocol';
 
+// Entity-keyed change-source registry (C7, #336) — L1 protocol + memory impl.
+// Generalizes per-entity `<ENTITY>_POLL_FETCH_REGISTRY` tokens into one
+// entity-keyed registry so the L3 surface port (C6) is entity-agnostic. Codegen
+// retarget to emit it is Track D D3/D4 (RFC-0001 §3).
+export type { IEntityChangeSourceRegistry } from './entity-change-source-registry.protocol';
+export { UnknownEntityError } from './entity-change-source-registry.protocol';
+export { MemoryEntityChangeSourceRegistry } from './entity-change-source-registry.memory';
+
 // DetectionConfig (#226-1) — Zod schema + inferred types; canonical source
 // of filter/mapping shape consumed by primitives + codegen YAML validator
 export {
@@ -100,6 +108,7 @@ export { buildChangeSource } from './build-change-source';
 
 // Tokens
 export {
+  ENTITY_CHANGE_SOURCE_REGISTRY,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,

package/runtime/subsystems/integration/integration.tokens.ts

@@ -47,3 +47,17 @@ export const INTEGRATION_MODULE_OPTIONS = 'INTEGRATION_MODULE_OPTIONS' as const;
  * Consumed by `ExecuteIntegrationUseCase` to enforce the tenantId-is-required rule.
  */
 export const INTEGRATION_MULTI_TENANT = 'INTEGRATION_MULTI_TENANT' as const;
+
+/**
+ * Injection token for the entity-keyed `IEntityChangeSourceRegistry` (C7,
+ * #336). Bound to the codegen-emitted aggregator that folds per-provider
+ * adapter contributions into one registry (RFC-0001 §3, emitted by Track D
+ * D3/D4).
+ *
+ * A string constant, not `Symbol.for(...)`, to match this subsystem's token
+ * convention (see file header). The originating issue's code block proposed a
+ * `Symbol.for('@pattern-stack/codegen.entity-change-source-registry')` key,
+ * predating the sync→integration consolidation onto string tokens; kept as a
+ * string here for internal consistency with the other INTEGRATION_* tokens.
+ */
+export const ENTITY_CHANGE_SOURCE_REGISTRY = 'ENTITY_CHANGE_SOURCE_REGISTRY' as const;

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 integrationUpsert
-    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/prompt-extension.js

@@ -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) {
@@ -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();
 }
 
@@ -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
@@ -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,52 +1207,63 @@ 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 — integration-source module emission for clean-lite-ps. Co-located
     // with the entity feature module under src/modules/<plural>/. Closes #267.
-    integrationSourceModule: `${srcRoot}/modules/${entityNamePlural}/${entityName}-integration-source.module.ts`,
-    integrationSourceProviders: `${srcRoot}/modules/${entityNamePlural}/${entityName}-integration-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 integration-source module
@@ -1245,6 +1418,10 @@ 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,
 
@@ -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,

package/templates/entity/new/backend/modules/core/integration-source.providers.ejs.t

@@ -1,18 +0,0 @@
----
-to: "<%= hasDetection ? (isCleanLitePs ? clpOutputPaths.integrationSourceProviders : `${basePaths.backendSrc}/${paths.modules}/${name}-integration-source.providers.ts`) : null %>"
-skip_if: <%= !hasDetection %>
-force: true
----
-<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
-/**
- * <%= className %> integration-source providers
- * Generated by entity codegen — do not edit directly.
- *
- * ADR-033.2: typed provider artifacts. Consumers type their registry as
- * Record<<%= className %>Provider, …> to get compile-time provider-key checks.
- * Order matches YAML detection: insertion order.
- */
-
-export const <%= name.toUpperCase() %>_PROVIDERS = [<%- detectionProviders.map((p) => `'${p}'`).join(', ') %>] as const;
-
-export type <%= className %>Provider = (typeof <%= name.toUpperCase() %>_PROVIDERS)[number];