@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/generator/domain/config.js

@@ -1,17 +1,17 @@
+import { toSnakeCase } from '../utils/string-utils.js';
 export const FRONT_APPS_CONTAINER = '@apps';
 export const FRONT_TYPES_PATH = '@src/app/aurora.types';
 export const APP_CONTAINER = '@app';
 export const API_CONTAINER = '@api';
-export const DASHBOARD_CONTAINER = 'app/domains/admin/bounded-contexts';
+export const DASHBOARD_CONTAINER = 'app/domains/admin/apps';
 export const ADMIN_CONTAINER = 'app/domains/admin';
 export const DASHBOARD_TRANSLATIONS = 'public/i18n';
-export const AURORA_CORE_COMMON = '@aurorajs.dev/core-common';
 export const AURORA_CORE_BACK = '@aurorajs.dev/core-back';
 export const AURORA_CORE_FRONT = '@aurorajs.dev/core-front';
 export const AURORA_LOCAL_PACKAGE = '@aurora';
 export const SCHEMA_DEFINITION_EXTENSION = '.aurora.yaml';
 export const CONFIG_YAML_VERSION = '0.0.1';
-export const LOCK_JSON_VERSION = '0.1.0';
+export const LOCK_JSON_VERSION = '0.2.0';
 export const TIMESTAMP_FIELDS = ['createdAt', 'updatedAt', 'deletedAt'];
 export const DELETED_AT_FIELD = ['deletedAt'];
 /** SHA1 hashes of sentinel lines used to mark generator-ignored files. */
@@ -35,6 +35,7 @@ export const ALLOWED_RENDER_EXTENSIONS = [
 ];
 export const AVOID_OVERWRITING_FILES = [
     'backend/@app/index.ts',
+    'backend/@app/__bounded_context_name__.seed.ts',
     'backend/@api/__bounded_context_name__.module.ts',
     'frontend/module/__bounded_context_name__.navigation.ts',
     'frontend/module/__bounded_context_name__.module.ts',
@@ -54,8 +55,8 @@ export const JAVASCRIPT_TYPES = {
     boolean: 'boolean',
     char: 'string',
     date: 'string',
+    dateTime: 'string',
     decimal: 'number',
-    encrypted: 'string',
     enum: 'string',
     float: 'number',
     id: 'string',
@@ -64,9 +65,10 @@ export const JAVASCRIPT_TYPES = {
     jsonb: 'any',
     manyToMany: 'string[]',
     password: 'string',
+    secret: 'string',
     smallint: 'number',
     text: 'string',
-    timestamp: 'string',
+    timestamp: 'number',
     varchar: 'string',
 };
 /** Maps PropertyType → JavaScript model type (Buffer for blobs) */
@@ -80,8 +82,8 @@ export const JAVASCRIPT_MODEL_TYPES = {
     boolean: 'boolean',
     char: 'string',
     date: 'string',
+    dateTime: 'string',
     decimal: 'number',
-    encrypted: 'string',
     enum: 'string',
     float: 'number',
     id: 'string',
@@ -90,9 +92,10 @@ export const JAVASCRIPT_MODEL_TYPES = {
     jsonb: 'any',
     manyToMany: 'string[]',
     password: 'string',
+    secret: 'string',
     smallint: 'number',
     text: 'string',
-    timestamp: 'string',
+    timestamp: 'number',
     varchar: 'string',
 };
 /** Maps PropertyType → Swagger decorator type */
@@ -106,8 +109,8 @@ export const SWAGGER_TYPES = {
     boolean: 'Boolean',
     char: 'String',
     date: 'String',
+    dateTime: 'String',
     decimal: 'Number',
-    encrypted: 'String',
     enum: 'String',
     float: 'Number',
     id: 'String',
@@ -116,9 +119,10 @@ export const SWAGGER_TYPES = {
     jsonb: 'Object',
     manyToMany: '[String]',
     password: 'String',
+    secret: 'String',
     smallint: 'Number',
     text: 'String',
-    timestamp: 'String',
+    timestamp: 'Number',
     varchar: 'String',
 };
 /** Maps PropertyType → GraphQL type string */
@@ -131,8 +135,8 @@ export const GRAPHQL_TYPES = {
     boolean: 'GraphQLBoolean',
     char: 'GraphQLString',
     date: 'GraphQLISODateTime',
+    dateTime: 'GraphQLISODateTime',
     decimal: 'GraphQLFloat',
-    encrypted: 'GraphQLString',
     enum: 'GraphQLString',
     float: 'GraphQLFloat',
     id: 'ID',
@@ -141,6 +145,7 @@ export const GRAPHQL_TYPES = {
     jsonb: 'JSON',
     manyToMany: '[ID]',
     password: 'GraphQLString',
+    secret: 'GraphQLString',
     smallint: 'GraphQLInt',
     text: 'GraphQLString',
     timestamp: 'GraphQLTimestamp',
@@ -157,8 +162,8 @@ export const DASHBOARD_COLUMN_TYPES = {
     boolean: 'BOOLEAN',
     char: 'STRING',
     date: 'DATE',
+    dateTime: 'DATE',
     decimal: 'NUMBER',
-    encrypted: 'STRING',
     enum: 'ENUM',
     float: 'NUMBER',
     id: 'STRING',
@@ -167,6 +172,7 @@ export const DASHBOARD_COLUMN_TYPES = {
     jsonb: 'JSONB',
     manyToMany: '',
     password: 'STRING',
+    secret: 'STRING',
     smallint: 'NUMBER',
     text: 'STRING',
     timestamp: 'TIMESTAMP',
@@ -183,8 +189,8 @@ export const UNACCENT_MAP = {
     boolean: false,
     char: true,
     date: false,
+    dateTime: false,
     decimal: false,
-    encrypted: false,
     enum: false,
     float: false,
     id: false,
@@ -193,6 +199,9 @@ export const UNACCENT_MAP = {
     jsonb: true,
     manyToMany: false,
     password: false,
+    // secret is omitted from the read/search surface entirely (design.md D3) —
+    // unaccent search would be dead code for a field the frontend never queries.
+    secret: false,
     smallint: false,
     text: true,
     timestamp: false,
@@ -208,8 +217,8 @@ export const QUOTATION_TYPES = {
     boolean: false,
     char: true,
     date: true,
+    dateTime: true,
     decimal: false,
-    encrypted: true,
     enum: false,
     float: false,
     id: true,
@@ -217,9 +226,10 @@ export const QUOTATION_TYPES = {
     json: false,
     jsonb: false,
     password: true,
+    secret: true,
     smallint: false,
     text: true,
-    timestamp: true,
+    timestamp: false,
     varchar: true,
 };
 /** Default lengths per PropertyType */
@@ -229,43 +239,119 @@ export const DEFAULT_TYPE_LENGTH = {
     id: 36,
     int: 10,
     password: 255,
+    secret: 255,
     smallint: 6,
     varchar: 255,
 };
-function getPropertyStringEnumOptions(property) {
-    const options = property.enumOptions ?? property.arrayOptions?.enumOptions;
-    return options?.map((o) => `'${o.trim().toUpperCase()}'`).join(',') ?? '';
-}
-export const SEQUELIZE_TYPES = {
-    array(param) {
-        const opts = param;
-        return `DataTypes.ARRAY(${SEQUELIZE_TYPES[opts.type](opts)})`;
+/**
+ * Maps `PropertyType` → Drizzle `pgTable` column builder expression, keyed by
+ * type (successor of `SEQUELIZE_TYPES`). Each builder receives the FULL
+ * property (not a narrowed param) because a Drizzle column bundles the DB
+ * field name and its type-specific options in one call — unlike a Sequelize
+ * `DataTypes.*` descriptor, which never carried the column name.
+ *
+ * `enum` is emitted as a plain `varchar` column (no `pgEnum`/CHECK
+ * constraint): the allowed values are enforced at the DTO/GraphQL layer, same
+ * as the Sequelize incumbent's app-level validation — a native
+ * Postgres/Drizzle enum type would need a separate top-level declaration
+ * shared across every module referencing it, which is out of scope for a
+ * per-module column builder (see design.md D4).
+ */
+export const DRIZZLE_COLUMNS = {
+    array(property) {
+        const opts = property.arrayOptions;
+        const innerProperty = {
+            ...property,
+            arrayOptions: undefined,
+            enumOptions: opts.enumOptions ?? property.enumOptions,
+            length: opts.length,
+            maxLength: opts.maxLength,
+            type: opts.type,
+        };
+        return `${DRIZZLE_COLUMNS[opts.type](innerProperty)}.array()`;
+    },
+    bigint: (property) => `bigint('${toSnakeCase(property.name)}', { mode: 'number' })`,
+    blob: (property) => `bytea('${toSnakeCase(property.name)}')`,
+    'blob.long': (property) => `bytea('${toSnakeCase(property.name)}')`,
+    'blob.medium': (property) => `bytea('${toSnakeCase(property.name)}')`,
+    'blob.tiny': (property) => `bytea('${toSnakeCase(property.name)}')`,
+    boolean: (property) => `boolean('${toSnakeCase(property.name)}')`,
+    char(property) {
+        const field = toSnakeCase(property.name);
+        // A bare char() is Postgres CHAR(1) — silently truncates any value
+        // longer than 1 char. Fall back to DEFAULT_TYPE_LENGTH.char instead of
+        // emitting an unbounded-looking call that is actually CHAR(1).
+        const length = property.length ?? DEFAULT_TYPE_LENGTH.char;
+        return `char('${field}', { length: ${length} })`;
+    },
+    // A `date` is a calendar day: no time-of-day, no timezone. `dateTime` is the
+    // instant-bearing type below — the two never emit the same column type.
+    date: (property) => `date('${toSnakeCase(property.name)}', { mode: 'string' })`,
+    dateTime(property) {
+        const field = toSnakeCase(property.name);
+        const withTimezone = property.applyTimezone !== false;
+        return withTimezone
+            ? `timestamp('${field}', { mode: 'string', withTimezone: true })`
+            : `timestamp('${field}', { mode: 'string' })`;
+    },
+    decimal(property) {
+        const field = toSnakeCase(property.name);
+        // `decimals` is only usable as a [precision, scale] pair — a malformed
+        // single-element array must not fall through to a destructured
+        // `scale: undefined`, which would emit invalid-looking generated code.
+        if (!property.decimals || property.decimals.length !== 2)
+            return `numeric('${field}')`;
+        const [precision, scale] = property.decimals;
+        return `numeric('${field}', { precision: ${precision}, scale: ${scale} })`;
+    },
+    enum: (property) => `varchar('${toSnakeCase(property.name)}')`,
+    float: (property) => `real('${toSnakeCase(property.name)}')`,
+    id: (property) => `uuid('${toSnakeCase(property.name)}')`,
+    int: (property) => `integer('${toSnakeCase(property.name)}')`,
+    json: (property) => `json('${toSnakeCase(property.name)}')`,
+    jsonb: (property) => `jsonb('${toSnakeCase(property.name)}')`,
+    password(property) {
+        const field = toSnakeCase(property.name);
+        // Consistency with varchar's DEFAULT_TYPE_LENGTH fallback — no reason a
+        // password column should default to unbounded while varchar defaults to 255.
+        const length = property.length ?? DEFAULT_TYPE_LENGTH.password;
+        return `varchar('${field}', { length: ${length} })`;
     },
-    bigint: () => 'DataTypes.BIGINT',
-    blob: () => 'DataTypes.BLOB',
-    'blob.long': () => "DataTypes.BLOB('long')",
-    'blob.medium': () => "DataTypes.BLOB('medium')",
-    'blob.tiny': () => "DataTypes.BLOB('tiny')",
-    boolean: () => 'DataTypes.BOOLEAN',
-    char: (length) => `DataTypes.CHAR(${String(length)})`,
-    date: () => 'DataTypes.DATE',
-    decimal: (decimals) => `DataTypes.DECIMAL(${decimals.join(',')})`,
-    encrypted: () => 'DataTypes.TEXT',
-    enum: (prop) => `DataTypes.ENUM(${getPropertyStringEnumOptions(prop)})`,
-    float: () => 'DataTypes.FLOAT',
-    id: () => 'DataTypes.UUID',
-    int: () => 'DataTypes.INTEGER',
-    json: () => 'DataTypes.JSON',
-    jsonb: () => 'DataTypes.JSONB',
-    password: (length) => `DataTypes.STRING(${String(length)})`,
-    smallint: () => 'DataTypes.SMALLINT',
-    text: () => 'DataTypes.TEXT',
-    timestamp: () => 'DataTypes.DATE',
-    varchar(prop) {
-        const p = prop;
-        return `DataTypes.STRING(${p.maxLength ? String(p.maxLength) : ''})`;
+    // secret is a varchar clone with a masked read (design.md D1/D2) — reuses
+    // the varchar builder verbatim, never password's (byte-identical Drizzle
+    // column to a varchar of the same maxLength; no DB migration, D8).
+    secret: (property) => DRIZZLE_COLUMNS.varchar(property),
+    smallint: (property) => `smallint('${toSnakeCase(property.name)}')`,
+    text: (property) => `text('${toSnakeCase(property.name)}')`,
+    timestamp: (property) => `bigint('${toSnakeCase(property.name)}', { mode: 'number' })`,
+    varchar(property) {
+        const field = toSnakeCase(property.name);
+        // Sequelize STRING() without an explicit length is VARCHAR(255) — fall
+        // back to the same default instead of emitting an unbounded varchar.
+        const length = property.maxLength ?? DEFAULT_TYPE_LENGTH.varchar;
+        return `varchar('${field}', { length: ${length} })`;
     },
 };
+/**
+ * Canonical runtime vocabulary of `PropertyType`. Derived from
+ * `DRIZZLE_COLUMNS` (which carries exactly the scalar/array types — no
+ * `relation`-owning, vestigial `manyToMany`-style keys some OTHER type-keyed
+ * maps still carry for historical reasons) plus `'relationship'`, the one
+ * `PropertyType` member that never gets a Drizzle column (it IS the relation).
+ * `PropertyType` itself is a compile-time-only union — it has no runtime
+ * representation — so this Set is the load-bearing single source of truth any
+ * externally authored `type` string is checked against.
+ *
+ * EVERY gate that accepts a `type` from outside the generator MUST consume this
+ * Set — `schema-loader.ts` when loading a YAML, `sheets/validators` when
+ * pushing to or pulling from Google Sheets. A hand-written copy of the list
+ * silently drifts: the sheets one went 5 types stale (`dateTime`, `secret`,
+ * `blob.*`) and rejected every module carrying an audit field.
+ */
+export const VALID_PROPERTY_TYPES = new Set([
+    'relationship',
+    ...Object.keys(DRIZZLE_COLUMNS),
+]);
 export const DTO_TYPES = {
     array: (property) => `${DTO_TYPES[property.arrayOptions.type]()}[]`,
     bigint: () => 'number',
@@ -276,8 +362,8 @@ export const DTO_TYPES = {
     boolean: () => 'boolean',
     char: () => 'string',
     date: () => 'string',
+    dateTime: () => 'string',
     decimal: () => 'number',
-    encrypted: () => 'string',
     enum: () => 'string',
     float: () => 'number',
     id: () => 'string',
@@ -286,9 +372,10 @@ export const DTO_TYPES = {
     jsonb: () => 'any',
     manyToMany: () => 'string[]',
     password: () => 'string',
+    secret: () => 'string',
     smallint: () => 'number',
     text: () => 'string',
-    timestamp: () => 'string',
+    timestamp: () => 'number',
     varchar: () => 'string',
 };
 export const BACK_PACKAGES = [
@@ -301,6 +388,10 @@ export const BACK_PACKAGES = [
         name: 'Identity (IAM + OAuth)',
         packageFolder: 'identity',
     },
+    {
+        name: 'Queue Manager',
+        packageFolder: 'queue-manager',
+    },
 ];
 export const FRONT_PACKAGES = [
     {
@@ -308,6 +399,10 @@ export const FRONT_PACKAGES = [
         name: 'Identity (IAM + OAuth)',
         packageFolder: 'identity',
     },
+    {
+        name: 'Queue Manager',
+        packageFolder: 'queue-manager',
+    },
 ];
 export const PROPERTY_TYPE = {
     ARRAY: 'array',
@@ -316,8 +411,8 @@ export const PROPERTY_TYPE = {
     BOOLEAN: 'boolean',
     CHAR: 'char',
     DATE: 'date',
+    DATE_TIME: 'dateTime',
     DECIMAL: 'decimal',
-    ENCRYPTED: 'encrypted',
     ENUM: 'enum',
     FLOAT: 'float',
     ID: 'id',
@@ -326,6 +421,7 @@ export const PROPERTY_TYPE = {
     JSONB: 'jsonb',
     PASSWORD: 'password',
     RELATIONSHIP: 'relationship',
+    SECRET: 'secret',
     SMALLINT: 'smallint',
     TEXT: 'text',
     TIMESTAMP: 'timestamp',
@@ -346,3 +442,11 @@ export const DETAIL_MODE = {
     DIALOG: 'dialog',
     VIEW: 'view',
 };
+/** Named-token → emitted Tailwind width class for the create/edit dialog. See {@link DialogWidth}. */
+export const DIALOG_WIDTH = {
+    FULL: 'w-[min(95vw,90rem)]',
+    LG: 'w-[min(92vw,56rem)]',
+    MD: 'w-[min(92vw,42rem)]',
+    SM: 'w-[min(92vw,28rem)]',
+    XL: 'w-[min(92vw,72rem)]',
+};

package/dist/generator/domain/cross-bc-relations-discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Project-wide scan for every DECLARED cross-BC relation
+ * (`generate-cross-bc-drizzle-relations`, design.md D3, tasks.md group 5) —
+ * what the bidirectional trigger needs to answer "which candidates are
+ * relevant to the module I am generating right now", whichever endpoint
+ * that module is (source or target).
+ *
+ * Walks every `cliter/<bc>/<module>.aurora.yaml`, INCLUDING every
+ * many-to-many property's own pivot module (`buildPivotSchema(pivot)`) as a
+ * separate candidate source — a pivot's own FK columns are independently
+ * cross-BC-eligible (e.g. `hubAppAccount.account` -> `iam/account`), exactly
+ * mirroring how `addPivotReferences` (`back.handler.ts`) registers the
+ * pivot's own per-BC relations entry separately from its parent's.
+ *
+ * Discovery never decides resolution — that is `isModuleGenerated`'s job,
+ * applied by the caller (`CodeWriter.resolveAndUpsertCrossBcRelations`).
+ */
+import type { CrossBcRelationCandidate } from './relations-builder.js';
+import { type ModuleDefinitionSchema } from './model.js';
+/**
+ * Scans EVERY `cliter/<bc>/<module>.aurora.yaml` under `cwd` and returns
+ * every declared cross-BC relation candidate in the project.
+ */
+export declare function discoverDeclaredCrossBcRelations(cwd: string): CrossBcRelationCandidate[];
+/**
+ * Selects every cross-BC candidate relevant to the module CURRENTLY BEING
+ * GENERATED (design.md D3, tasks.md group 5's bidirectional trigger) — its
+ * OWN declared relations (computed fresh from `schema`, no disk dependency:
+ * `generateBackModule`'s `saveSchema` step runs AFTER this point, so this
+ * module's own YAML may not exist on disk yet) UNION every OTHER
+ * already-declared relation elsewhere in the project whose TARGET is this
+ * module. That reverse half is what completes a pair "generate A, then
+ * generate B" without anyone returning to A: by the time B's own generation
+ * reaches this call, A's relation to B is already on disk and B's own
+ * module now exists too, so `resolveAndUpsertCrossBcRelations` (the caller)
+ * finds it resolvable.
+ */
+export declare function selectRelevantCrossBcCandidates(schema: ModuleDefinitionSchema, cwd: string): CrossBcRelationCandidate[];

package/dist/generator/domain/cross-bc-relations-discovery.js

@@ -0,0 +1,89 @@
+/**
+ * Project-wide scan for every DECLARED cross-BC relation
+ * (`generate-cross-bc-drizzle-relations`, design.md D3, tasks.md group 5) —
+ * what the bidirectional trigger needs to answer "which candidates are
+ * relevant to the module I am generating right now", whichever endpoint
+ * that module is (source or target).
+ *
+ * Walks every `cliter/<bc>/<module>.aurora.yaml`, INCLUDING every
+ * many-to-many property's own pivot module (`buildPivotSchema(pivot)`) as a
+ * separate candidate source — a pivot's own FK columns are independently
+ * cross-BC-eligible (e.g. `hubAppAccount.account` -> `iam/account`), exactly
+ * mirroring how `addPivotReferences` (`back.handler.ts`) registers the
+ * pivot's own per-BC relations entry separately from its parent's.
+ *
+ * Discovery never decides resolution — that is `isModuleGenerated`'s job,
+ * applied by the caller (`CodeWriter.resolveAndUpsertCrossBcRelations`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { toKebabCase } from '../utils/string-utils.js';
+import { SCHEMA_DEFINITION_EXTENSION } from './config.js';
+import { buildPivotSchema } from './model.js';
+import { getManyToManyRelationshipProperties } from './property-filters.js';
+import { buildCrossBcRelationCandidates } from './relations-builder.js';
+import { loadSchema } from './schema-loader.js';
+/**
+ * Candidates for one schema — empty for a module that opted out of the
+ * Drizzle relations file entirely (`excludedFiles: ['src/@app/**']`), same
+ * exclusion `addReferences`/`addPivotReferences` already check before
+ * calling `declareBackSchemaInBcRelations`.
+ */
+function schemaCandidates(schema) {
+    if (schema.excludedFiles?.includes('src/@app/**'))
+        return [];
+    return buildCrossBcRelationCandidates(schema);
+}
+/**
+ * Scans EVERY `cliter/<bc>/<module>.aurora.yaml` under `cwd` and returns
+ * every declared cross-BC relation candidate in the project.
+ */
+export function discoverDeclaredCrossBcRelations(cwd) {
+    const cliterDir = path.join(cwd, 'cliter');
+    if (!fs.existsSync(cliterDir))
+        return [];
+    const discovered = [];
+    for (const boundedContextName of fs.readdirSync(cliterDir)) {
+        const bcDir = path.join(cliterDir, boundedContextName);
+        if (!fs.statSync(bcDir).isDirectory())
+            continue;
+        for (const fileName of fs.readdirSync(bcDir)) {
+            if (!fileName.endsWith(SCHEMA_DEFINITION_EXTENSION))
+                continue;
+            const moduleName = fileName.slice(0, -SCHEMA_DEFINITION_EXTENSION.length);
+            const schema = loadSchema(boundedContextName, moduleName, cwd);
+            discovered.push(...schemaCandidates(schema));
+            for (const property of getManyToManyRelationshipProperties(schema.aggregateProperties ?? [])) {
+                if (!property.relationship?.pivot)
+                    continue;
+                discovered.push(...schemaCandidates(buildPivotSchema(property.relationship.pivot)));
+            }
+        }
+    }
+    return discovered;
+}
+/**
+ * Selects every cross-BC candidate relevant to the module CURRENTLY BEING
+ * GENERATED (design.md D3, tasks.md group 5's bidirectional trigger) — its
+ * OWN declared relations (computed fresh from `schema`, no disk dependency:
+ * `generateBackModule`'s `saveSchema` step runs AFTER this point, so this
+ * module's own YAML may not exist on disk yet) UNION every OTHER
+ * already-declared relation elsewhere in the project whose TARGET is this
+ * module. That reverse half is what completes a pair "generate A, then
+ * generate B" without anyone returning to A: by the time B's own generation
+ * reaches this call, A's relation to B is already on disk and B's own
+ * module now exists too, so `resolveAndUpsertCrossBcRelations` (the caller)
+ * finds it resolvable.
+ */
+export function selectRelevantCrossBcCandidates(schema, cwd) {
+    if (schema.excludedFiles?.includes('src/@app/**'))
+        return [];
+    const boundedContextKebab = toKebabCase(schema.boundedContextName);
+    const moduleKebab = toKebabCase(schema.moduleName);
+    const ownCandidates = buildCrossBcRelationCandidates(schema);
+    const reverseCandidates = discoverDeclaredCrossBcRelations(cwd).filter((candidate) => candidate.targetBoundedContextKebab === boundedContextKebab &&
+        candidate.targetModuleKebab === moduleKebab &&
+        !(candidate.ownerBoundedContextKebab === boundedContextKebab &&
+            candidate.ownerModuleKebab === moduleKebab));
+    return [...ownCandidates, ...reverseCandidates];
+}

package/dist/generator/domain/cross-schema-resolver.d.ts

@@ -38,12 +38,65 @@ export declare function findFkProperty(childSchema: ModuleDefinitionSchema, pare
  *   - **Default (unset)** → returns `'name'`.
  *
  * Used by the columns template's FK auto-include to emit the correct
- * `accessorKey: '<rel>.<targetDisplayField>'`.
+ * null-safe `accessorFn: (row) => row.<rel>?.<targetDisplayField> ?? ''`.
+ *
+ * Delegates to {@link getTargetDisplayFieldInfo} for the actual schema load +
+ * identifier resolution — this function is now a thin `.name` projection over
+ * it, so the "resolve target displayField" logic exists in exactly ONE place.
  *
  * @param targetModulePath path of the target aggregate, format `<bc>/<mod>`.
  * @param cwd              working directory (defaults to `process.cwd()`).
  */
 export declare function getTargetDisplayField(targetModulePath: string, cwd?: string): string;
+/** Result of resolving a target aggregate's display-field, including whether it is embedded-i18n. */
+export interface TargetDisplayFieldInfo {
+    /** `'<base>I18n'` — present only when `isEmbeddedI18n`. */
+    i18nName?: string;
+    /** `true` iff `name` is an `isI18n` property AND the target is NOT table-strategy. */
+    isEmbeddedI18n: boolean;
+    /**
+     * Defect F (harden-generator-emission-contract, design.md D12): `true` when
+     * the resolved display-field is text-shaped (`varchar`/`text`/`char`, the
+     * masked-on-read text clones, or embedded-i18n — always a derived text
+     * column). A relation column over a `false` target must NOT be emitted
+     * `searchable`/`filterable`: the search box and filter UI build `iLike`,
+     * which Postgres rejects against a non-text column (`42883`).
+     */
+    isTextDisplayField: boolean;
+    /** First identifier of the target's `front.displayField` (same rules as `getTargetDisplayField`). */
+    name: string;
+    /**
+     * Human-readable SQL type noun for the "NOT searchable/filterable" comment
+     * the columns template emits — present only when `isTextDisplayField` is
+     * `false`.
+     */
+    nonTextSqlTypeNoun?: string;
+    /** `'<base>I18nSearchText'` — present only when `isEmbeddedI18n`. */
+    searchTextName?: string;
+}
+/**
+ * Sister helper to `getTargetDisplayField`: resolves, in a SINGLE load of the
+ * target schema, everything the columns template's three relation branches
+ * (FK many-to-one, HasOne, many-to-many) need to emit a display column whose
+ * target `displayField` may be an embedded-i18n field — the map/search-text
+ * column names, so the caller never has to reload the schema or re-derive
+ * `isEmbeddedI18n` itself.
+ *
+ * `name` is computed exactly as `getTargetDisplayField` does today. When the
+ * property named `name` on the target aggregate is `isI18n: true` under a
+ * non-`'table'` `i18nStrategy`, `isEmbeddedI18n` is `true` and `i18nName`/
+ * `searchTextName` are derived via `buildI18nEmbeddedColumns(name)`.
+ * Otherwise (table-strategy i18n, or a plain scalar `name`) `isEmbeddedI18n`
+ * is `false` and the two derived names are omitted.
+ *
+ * `getTargetDisplayField` is left unchanged and keeps powering the
+ * search-select pipe args and delete-toast property access, which only need
+ * the scalar identifier.
+ *
+ * @param targetModulePath path of the target aggregate, format `<bc>/<mod>`.
+ * @param cwd              working directory (defaults to `process.cwd()`).
+ */
+export declare function getTargetDisplayFieldInfo(targetModulePath: string, cwd?: string): TargetDisplayFieldInfo;
 /**
  * Resolves a target aggregate's `displayField` as a placeholder template
  * suitable for the `ToOptionsPipe` runtime pipe in the Aurora frontend lib.

package/dist/generator/domain/cross-schema-resolver.js

@@ -4,6 +4,8 @@
  * it loads the child schema on-demand. These helpers encapsulate the loading + lookup.
  */
 import { getDisplayFieldFirstIdentifier, getDisplayFieldTemplate, } from './display-field.js';
+import { buildI18nEmbeddedColumns, isEmbeddedI18n } from './i18n-embedded.js';
+import { isTextShapedPropertyType, toNonTextSqlTypeNoun } from './relation-search-eligibility.js';
 import { loadSchema } from './schema-loader.js';
 /**
  * Resolves the FK property name on the child pointing back to the parent.
@@ -54,18 +56,65 @@ export function findFkProperty(childSchema, parentModulePath) {
  *   - **Default (unset)** → returns `'name'`.
  *
  * Used by the columns template's FK auto-include to emit the correct
- * `accessorKey: '<rel>.<targetDisplayField>'`.
+ * null-safe `accessorFn: (row) => row.<rel>?.<targetDisplayField> ?? ''`.
+ *
+ * Delegates to {@link getTargetDisplayFieldInfo} for the actual schema load +
+ * identifier resolution — this function is now a thin `.name` projection over
+ * it, so the "resolve target displayField" logic exists in exactly ONE place.
  *
  * @param targetModulePath path of the target aggregate, format `<bc>/<mod>`.
  * @param cwd              working directory (defaults to `process.cwd()`).
  */
 export function getTargetDisplayField(targetModulePath, cwd = process.cwd()) {
+    return getTargetDisplayFieldInfo(targetModulePath, cwd).name;
+}
+/**
+ * Sister helper to `getTargetDisplayField`: resolves, in a SINGLE load of the
+ * target schema, everything the columns template's three relation branches
+ * (FK many-to-one, HasOne, many-to-many) need to emit a display column whose
+ * target `displayField` may be an embedded-i18n field — the map/search-text
+ * column names, so the caller never has to reload the schema or re-derive
+ * `isEmbeddedI18n` itself.
+ *
+ * `name` is computed exactly as `getTargetDisplayField` does today. When the
+ * property named `name` on the target aggregate is `isI18n: true` under a
+ * non-`'table'` `i18nStrategy`, `isEmbeddedI18n` is `true` and `i18nName`/
+ * `searchTextName` are derived via `buildI18nEmbeddedColumns(name)`.
+ * Otherwise (table-strategy i18n, or a plain scalar `name`) `isEmbeddedI18n`
+ * is `false` and the two derived names are omitted.
+ *
+ * `getTargetDisplayField` is left unchanged and keeps powering the
+ * search-select pipe args and delete-toast property access, which only need
+ * the scalar identifier.
+ *
+ * @param targetModulePath path of the target aggregate, format `<bc>/<mod>`.
+ * @param cwd              working directory (defaults to `process.cwd()`).
+ */
+export function getTargetDisplayFieldInfo(targetModulePath, cwd = process.cwd()) {
     const [targetBc, targetMod] = targetModulePath.split('/');
     if (!targetBc || !targetMod) {
-        throw new Error(`getTargetDisplayField: invalid targetModulePath '${targetModulePath}'. Expected format '<bc>/<mod>'.`);
+        throw new Error(`getTargetDisplayFieldInfo: invalid targetModulePath '${targetModulePath}'. Expected format '<bc>/<mod>'.`);
     }
     const targetSchema = loadSchema(targetBc, targetMod, cwd);
-    return getDisplayFieldFirstIdentifier(targetSchema);
+    const name = getDisplayFieldFirstIdentifier(targetSchema);
+    const property = targetSchema.aggregateProperties.find((p) => p.name === name);
+    const embedded = isEmbeddedI18n(Boolean(property?.isI18n), targetSchema.i18nStrategy);
+    if (!embedded) {
+        // An embedded-i18n target is always text (its search column is the
+        // derived `<prop>SearchText`, text by construction) — only a non-embedded
+        // target's raw declared type decides here (Defect F, design.md D12).
+        const isTextDisplayField = isTextShapedPropertyType(property?.type);
+        if (isTextDisplayField)
+            return { isEmbeddedI18n: false, isTextDisplayField, name };
+        return {
+            isEmbeddedI18n: false,
+            isTextDisplayField,
+            name,
+            nonTextSqlTypeNoun: toNonTextSqlTypeNoun(property?.type),
+        };
+    }
+    const { i18nName, searchTextName } = buildI18nEmbeddedColumns(name);
+    return { i18nName, isEmbeddedI18n: true, isTextDisplayField: true, name, searchTextName };
 }
 /**
  * Resolves a target aggregate's `displayField` as a placeholder template