@g1cloud/entity-modeler-next 5.0.0-alpha.9 → 5.0.0-beta.2

package/dist/agent/symbolicOp.d.ts

@@ -226,6 +226,7 @@ export type SymbolicOp = {
     entity: Handle;
     attribute: Handle;
     patch: Record<string, unknown>;
+    embeddableOverrides?: EmbeddableColumnOverride[];
 } | {
     kind: 'attribute.remove';
     entity: Handle;

package/dist/command/commands.d.ts

@@ -1,6 +1,12 @@
-import { Association, AssociationEnd, AssociationLayout, Attribute, Entity, EntityIndex, Geo, LogicalGroup, ModelId, Note, Operation, Point } from '../core/types';
+import { Association, AssociationEnd, AssociationLayout, Attribute, Entity, EntityIndex, EntityLayout, Geo, GroupLayout, LogicalGroup, ModelId, Note, Operation, Point } from '../core/types';
 import { Command } from './types';
-export declare function addEntity(entity: Entity, geo: Geo): Command;
+/**
+ * geo 외 EntityLayout 부가 필드(collapsed·displayMode·style·attributeStyles 등).
+ * import 등 레이아웃 스타일까지 복제하는 경로에서 전달. entityRef·geo는 별도 인자라 제외.
+ * locked는 뷰 어포던스라 호출자가 필요 시만 포함(import는 드롭).
+ */
+export type EntityLayoutExtras = Partial<Omit<EntityLayout, 'entityRef' | 'geo'>>;
+export declare function addEntity(entity: Entity, geo: Geo, extras?: EntityLayoutExtras): Command;
 /** 엔티티 삭제 — 참조 관계·레이아웃·그룹 멤버십까지 cascade. memento로 위치 보존 복원. */
 export declare function removeEntity(entityId: ModelId): Command;
 /** 엔티티 필드 부분 수정 (name·stereotype·package·table·jpaAttrs·description 등). 얕은 patch. */
@@ -30,7 +36,9 @@ export declare function setEntityLocked(entityId: ModelId, locked: boolean): Com
 export declare function setAllEntitiesCollapsed(collapsed: boolean): Command;
 /** 속성 강조 색상 변경 (레이아웃 attributeStyles[attrId]) */
 export declare function setAttributeSwatch(entityId: ModelId, attributeId: ModelId, token: string | null): Command;
-export declare function addGroup(group: LogicalGroup, geo: Geo): Command;
+/** geo 외 GroupLayout 부가 필드(style 등). entityLayout의 EntityLayoutExtras 거울. */
+export type GroupLayoutExtras = Partial<Omit<GroupLayout, 'groupRef' | 'geo' | 'memberNoteRefs'>>;
+export declare function addGroup(group: LogicalGroup, geo: Geo, extras?: GroupLayoutExtras): Command;
 /** 그룹 필드 부분 수정 (name·description·packageName·excludeDDLGeneration). 얕은 patch. */
 export declare function updateGroup(groupId: ModelId, patch: Partial<LogicalGroup>): Command;
 /** 그룹 해제(삭제) — 멤버 엔티티는 남고 그룹/박스만 제거 */

package/dist/core/associationNav.d.ts

@@ -0,0 +1,10 @@
+import { Multiplicity } from './types';
+/** end2 multiplicity가 컬렉션(0..* / 1..*)인가 — 코드젠의 @OneToMany vs @OneToOne 분기와 동일 기준. */
+export declare function isCollectionMultiplicity(m: Multiplicity): boolean;
+/**
+ * inverse nav 기본 이름: 자식 엔티티명(camel). 컬렉션이면 복수형.
+ * 예: Order→OrderItem 컬렉션 → `orderItems`, 단일 → `orderItem`.
+ */
+export declare function defaultInverseNavName(childEntityName: string, isCollection: boolean): string;
+/** 엔티티 내 속성명 유일화 — 충돌 시 숫자 suffix(addEmbedAssociation 필드명 패턴과 동형). */
+export declare function uniqueAttributeName(base: string, existing: ReadonlySet<string>): string;

package/dist/core/attributeOrder.d.ts

@@ -0,0 +1,17 @@
+import { Attribute, Entity } from './types';
+/** 물리 FK 컬럼을 가진 FK 여부 — derivedFrom(관계 파생) + dbAttrs(물리 컬럼) 보유. */
+export declare function isPhysicalFk(a: Attribute): boolean;
+/**
+ * 물리 FK 컬럼을 가진 FK를 순수 PK 바로 뒤로 당긴다. `순수 PK → 물리 FK → 나머지` 순으로 재배열하되,
+ * FK끼리·나머지끼리의 상대 순서는 원본 order를 보존한다(순서를 새로 추정하지 않음). 순수 PK가 없으면
+ * FK를 맨 앞으로. 물리 컬럼 없는 nav 참조(dbAttrs=0)는 추정이라 제외 — 실제로 그런 참조는 어느 엔티티
+ * attributes에도 물질화되지 않으므로(유령 앵커 참조) 대상이 되는 일도 없다.
+ *
+ * ★ order 필드뿐 아니라 **배열 물리 순서 자체**를 재정렬한다. 캔버스 노드(EntityNode)는 attributes를
+ * 배열 순서 그대로 렌더하고(order 정렬 미적용), 코드젠·탐색기는 order로 정렬하므로, 둘을 일치시켜야
+ * 모든 표시 경로에서 순서가 같다. [[attribute-display-order-array-vs-order-field]]
+ *
+ * 경계 강등(mergeDiagram)으로 derivedFrom이 제거된 FK는 `isPhysicalFk`가 false라 일반 컬럼으로 제자리에
+ * 남는다 — 강등 이후에 호출해야 한다.
+ */
+export declare function reorderForeignAttributes(entities: Entity[]): void;

package/dist/core/ddl.d.ts

@@ -0,0 +1,10 @@
+import { EmbeddableCatalog, LogicalModel } from './types';
+export type SqlDialect = 'postgres';
+export interface DdlContext {
+    /** EMBED_PREDEF 서브컬럼의 카탈로그 기본 물리명 해석용(validateModel과 동형 주입). */
+    embeddableCatalog?: EmbeddableCatalog;
+}
+/** 표시 모드 → 기본 DDL 방언. 현재는 PG 단일. */
+export declare function defaultSqlDialect(): SqlDialect;
+/** 논리 모델을 지정 방언의 SQL DDL로 직렬화. */
+export declare function entityModelToDdl(logical: LogicalModel, _dialect?: SqlDialect, ctx?: DdlContext): string;

package/dist/core/inheritedColumns.d.ts

@@ -0,0 +1,57 @@
+import { Entity, ModelId, MultiLangText, SuperClassCatalog } from './types';
+/**
+ * 상속 컬럼 참조 네임스페이스 접두사. 합성 modelId 형식 = `inherited:<BaseClass>:<field>`.
+ * 실제 modelId는 crypto.randomUUID()(하이픈 UUID, 콜론 없음)라 이 접두사 공간과 disjoint —
+ * IndexColumn.columnRef가 로컬 dbAttr modelId(UUID)와 상속 컬럼(합성)을 단일 ModelId 형태로
+ * 균일하게 담을 수 있다(D2 = 2a 합성 stable modelId, IndexColumn 유니온화 회피).
+ */
+export declare const INHERITED_REF_PREFIX = "inherited:";
+/** `inherited:<baseClass>:<field>` 합성 modelId 생성. */
+export declare function makeInheritedColumnRef(baseClass: string, field: string): ModelId;
+/** ref가 상속 컬럼 합성 modelId인지. UUID(로컬 dbAttr)면 false. */
+export declare function isInheritedColumnRef(ref: string): boolean;
+/**
+ * 합성 modelId를 `{baseClass, field}`로 분해. 상속 ref가 아니거나 형식이 깨졌으면 null.
+ * baseClass/field는 자바 식별자라 콜론을 포함하지 않으므로 접두사 뒤 **첫 콜론**으로 분할한다.
+ */
+export declare function parseInheritedColumnRef(ref: string): {
+    baseClass: string;
+    field: string;
+} | null;
+/**
+ * 파생(비저장) 상속 컬럼 — `Entity.superClass`가 카탈로그로 기여하는 컬럼을 인덱스 대상으로 참조
+ * 가능하게 하는 투영 결과. `entity.attributes`에 넣지 않는다(G4 보존). 뷰 picker·라벨, codegen,
+ * 검증이 온디맨드로 이 함수를 호출해 소비한다.
+ */
+export interface InheritedColumn {
+    /** 합성 modelId(`inherited:<baseClass>:<field>`) — IndexColumn.columnRef가 참조하는 값. */
+    modelId: ModelId;
+    /** 기여한 슈퍼클래스명(= 카탈로그 name = Entity.superClass). */
+    baseClass: string;
+    /** 논리 필드명(합성 id 키, D6). */
+    field: string;
+    /** 물리 컬럼명(@Index columnList 코드젠·라벨용). */
+    physicalName: string;
+    /** dbTypes 카탈로그 값. */
+    dataType: string;
+    logicalName?: MultiLangText;
+    length?: number;
+    scale?: number;
+}
+/**
+ * 엔티티의 `superClass`를 카탈로그로 해소해 상속 컬럼을 투영한다(파생·비저장).
+ *
+ * - `entity.superClass`가 **비어 있으면** 카탈로그의 **default base**(`SuperClassDef.default`)로 폴백한다.
+ *   레거시 관례상 superClass 미명시 = 코드젠 암묵 default(`extends BaseEntity`)라, 빈 값은 default 상속으로
+ *   해석해야 상속 컬럼이 점등된다. default가 지정 안 된 카탈로그면 빈 값은 여전히 빈 배열(opt-in 보존).
+ * - 명시적 `superClass='Object'`(자바 `extends Object` = default 상속 opt-out 트릭)는 non-empty라
+ *   default 폴백에 안 걸리고 카탈로그 미스 → 빈 배열. opt-out이 자연 보존된다.
+ * - D7 스킵: `stereotype === 'JPA_EMBEDDABLE'`(임베더블은 엔티티 상속 안 함), 엔티티 자신이
+ *   카탈로그 base(= 상속의 원천)면 스킵(자기 자신에게 투영하는 순환 방지).
+ * - 각 투영 컬럼에 합성 modelId(§4.3)를 부여한다.
+ * - 초기엔 1단 투영만(대부분 BaseEntity 단일 단계). base가 또 다른 base를 상속하는 다단 체인은
+ *   카탈로그가 상위 참조를 표현하도록 확장한 뒤 재귀 활성(범위 밖).
+ *
+ * 카탈로그가 비어 있거나 매칭 base가 없으면 빈 배열(inert 게이트 — groupCodeCatalog 동일 관례).
+ */
+export declare function projectInheritedColumns(entity: Entity, catalog: SuperClassCatalog): InheritedColumn[];

package/dist/core/jsonModel.d.ts

@@ -0,0 +1,23 @@
+import { DiagramLayout, LogicalModel } from './types';
+import { MergeDiagramSource } from './mergeDiagram';
+export declare const DIAGRAM_JSON_FORMAT = "entity-modeler-diagram";
+export declare const DIAGRAM_JSON_VERSION = 1;
+export interface DiagramJsonEnvelope {
+    format: typeof DIAGRAM_JSON_FORMAT;
+    version: number;
+    logical: LogicalModel;
+    layout: DiagramLayout;
+}
+/** 파싱 실패(잘못된 JSON·봉투·골격) — 호출부가 사용자에게 사유를 표시할 수 있도록 message에 이유를 담는다. */
+export declare class InvalidDiagramJsonError extends Error {
+    constructor(reason: string);
+}
+/** 현재 다이어그램(논리 + 레이아웃)을 이식 가능한 JSON 백업 문자열로 직렬화(pretty). */
+export declare function diagramToJson(logical: LogicalModel, layout: DiagramLayout): string;
+/**
+ * JSON 백업 문자열 → 임포트 소스(논리 + 레이아웃). 봉투·모델 골격을 검증하고, 실패 시
+ * `InvalidDiagramJsonError`를 던진다. 레이아웃 서브배열이 없으면 빈 배열로 관용 보정한다
+ * (논리 전용 JSON도 수용 — importEntities 폴백 geo가 배치). 참조 무결성(dangling)은 mergeDiagram이
+ * 관용 처리하므로 여기서 강제하지 않는다.
+ */
+export declare function parseDiagramJson(text: string): MergeDiagramSource;

package/dist/core/mergeDiagram.d.ts

@@ -0,0 +1,45 @@
+import { Association, AssociationLayout, DiagramLayout, Entity, EntityLayout, GroupLayout, LogicalGroup, LogicalModel, ModelId, Point, Style } from './types';
+export interface MergeDiagramSource {
+    logical: LogicalModel;
+    /** 소스 다이어그램 레이아웃 — 임포트 서브그래프의 좌표/스타일을 함께 옮긴다. */
+    layout: DiagramLayout;
+}
+export interface MergeDiagramOptions {
+    /** depth-1 관련 엔티티(경계 관계의 반대편)를 선택집합에 함께 끌어와 관계를 유지(D3 옵션 토글). */
+    includeRelated?: boolean;
+    /** 병합 대상(타깃) 논리 모델 — 이름/테이블 물리명 충돌 감지에 사용(D7). */
+    existing: LogicalModel;
+    /** 임포트 서브그래프 좌표에 더할 오프셋(D8 — 빈 영역 배치는 호출자가 계산해 전달). */
+    offset?: Point;
+    /**
+     * 이름/물리명 충돌 시 붙일 접미사(D7). 기본 `_imported`(타 모듈 import).
+     * 같은 문서 클립보드 붙여넣기는 `_copy`가 자연스럽다(단일 paste와 일관).
+     */
+    collisionSuffix?: string;
+    /** 결정적 테스트를 위한 id 생성기 주입(기본 newId). */
+    idFactory?: () => ModelId;
+}
+export interface MergeDiagramResult {
+    logical: {
+        entities: Entity[];
+        associations: Association[];
+        groups: LogicalGroup[];
+    };
+    layout: {
+        entityLayouts: EntityLayout[];
+        associationLayouts: AssociationLayout[];
+        groupLayouts: GroupLayout[];
+    };
+    /** 소스 modelId → 임포트 modelId 매핑(컨트롤러 진입점·후속 배선용). */
+    idMap: Map<ModelId, ModelId>;
+}
+/**
+ * 소스 다이어그램의 선택 서브그래프를 새 id 체계로 재매핑해 반환한다.
+ *
+ * @param source 소스 다이어그램(로드된 논리 + 레이아웃)
+ * @param selectedIds 임포트할 엔티티 modelId 목록(부분 선택 — 전량은 전 엔티티 id 전달)
+ * @param opts 경계/충돌/오프셋 정책
+ */
+export declare function mergeDiagram(source: MergeDiagramSource, selectedIds: ModelId[], opts: MergeDiagramOptions): MergeDiagramResult;
+/** 스타일 맵의 키(속성/연산 modelId) remap — 강등돼 사라진 키는 드롭. */
+export declare function remapStyleKeys(styles: Record<ModelId, Style>, get: (old: ModelId) => ModelId | undefined): Record<ModelId, Style>;

package/dist/core/mermaid.d.ts

@@ -0,0 +1,6 @@
+import { DisplayMode, LogicalModel } from './types';
+export type MermaidDialect = 'er' | 'class';
+/** 표시 모드 → 기본 Mermaid 방언. CLASS만 클래스 다이어그램, 나머지(논리·물리·논리·물리)는 ER. */
+export declare function defaultMermaidDialect(mode: DisplayMode): MermaidDialect;
+/** 논리 모델을 지정 방언의 Mermaid 소스로 직렬화. */
+export declare function entityModelToMermaid(logical: LogicalModel, dialect: MermaidDialect): string;

package/dist/core/parseMermaid.d.ts

@@ -0,0 +1,9 @@
+import { LogicalModel } from './types';
+import { MergeDiagramSource } from './mergeDiagram';
+/** Mermaid ER 소스를 논리 모델로 파싱(순수). 좌표/그룹/노트는 없음(리버스 임포트는 논리 전용). */
+export declare function parseMermaidEr(text: string): LogicalModel;
+/**
+ * Mermaid ER 텍스트 → 임포트 소스(논리 + auto-layout 레이아웃). `controller.importEntities`가 그대로 소비한다.
+ * 좌표가 없으므로 packEntityBoxes(높이 인지)로 겹침 없는 격자를 생성한다.
+ */
+export declare function mermaidErToImportSource(text: string): MergeDiagramSource;

package/dist/core/parseSqlDdl.d.ts

@@ -0,0 +1,11 @@
+import { LogicalModel } from './types';
+import { MergeDiagramSource } from './mergeDiagram';
+export interface ParseSqlDdlResult {
+    logical: LogicalModel;
+    /** best-effort 파싱에서 건너뛴 statement·해석 못한 부분(부분 성공 가시화). */
+    warnings: string[];
+}
+/** SQL DDL을 논리 모델로 파싱(순수·best-effort). warnings에 건너뛴 부분 보고. */
+export declare function parseSqlDdl(text: string): ParseSqlDdlResult;
+/** SQL DDL → 임포트 소스(논리 + auto-layout). controller.importEntities가 그대로 소비. */
+export declare function sqlDdlToImportSource(text: string): MergeDiagramSource;

package/dist/core/propagation.d.ts

@@ -47,3 +47,25 @@ export declare function reconcileForeignAttributes(logical: LogicalModel, childE
  * self-association은 비식별이라 자식 식별자를 바꾸지 않아 더 전파되지 않는다(자연 종료).
  */
 export declare function planPropagation(logical: LogicalModel, changedEntityId: ModelId, idFactory?: IdFactory): Map<ModelId, ReconcilePlan>;
+/**
+ * 주어진 속성이 "연관관계가 관리하는 FK 컬럼"이면 그 소유 연관관계를 돌려준다(아니면 undefined).
+ *
+ * 논리 모델러 계보(ERwin/ER-Studio/PowerDesigner)에서 FK 컬럼은 관계가 migrate한 파생 속성이라
+ * 관계가 소유한다 — 컬럼을 직접 지우는 게 아니라 관계를 삭제/변경해 제거해야 한다. 이 판별로
+ * FK 속성의 직접 삭제를 차단(어포던스+가드)하고 사용자를 관계 삭제 경로로 유도한다.
+ *
+ * FK 컬럼 불변식(RELATION* + 물리 컬럼 보유, EntityNode.keyMarks와 동형)으로 먼저 게이트해, 관계의
+ * 부모측 end가 가리키는 PK(비-RELATION) 오탐을 배제한다. 그다음 두 신호로 소유 관계를 찾는다:
+ *
+ *  1순위 `derivedFrom.associationRef` — 전파가 심은 권위 신호. v2 네이티브 doc에 보존되고 어댑터
+ *    hydration이 복원한다. GUI·sync 스킬·에이전트 어느 경로로 만들어졌든 FK 자신에 붙어 있어,
+ *    관계 end의 `attributeRef`가 stale해도(자기참조 재생성·sync가 링크를 다르게 심은 경우 등) 정확하다.
+ *  2순위 관계 end의 `attributeRef` 역참조 — `derivedFrom`이 없는 경우(레거시 v1 로드 FK 등)의 폴백.
+ *    방향 규약은 end2=자식이지만 드문 로드 형태가 end1에 실을 수 있어 양 end를 모두 검사한다.
+ *
+ * (초기엔 attributeRef만 신뢰했으나, sync 스킬로 만든 자기참조 FK가 `derivedFrom`은 정확한데
+ *  end2.attributeRef는 옛 FK id를 가리키는 실사례로 derivedFrom을 1순위로 승격.)
+ *
+ * `derivedFrom`이 이미 삭제된 관계를 가리키거나(고아) 둘 다 매칭 없으면 undefined → 직접 삭제(정리) 허용.
+ */
+export declare function findFkOwningAssociation(logical: LogicalModel, entityId: ModelId, attributeId: ModelId): Association | undefined;

package/dist/core/quickFix.d.ts

@@ -0,0 +1,12 @@
+import { JpaCascadeType, LogicalModel, ModelId } from './types';
+import { ValidationIssue } from './validation';
+export interface QuickFixPlan {
+    ruleId: string;
+    /** 현재는 association end의 cascade 재설정 한 종류(중복 제거). 확장 시 kind 분기 추가. */
+    kind: 'setEndCascades';
+    assocRef: ModelId;
+    which: 'end1' | 'end2';
+    cascades: JpaCascadeType[];
+}
+/** 이슈에 적용 가능한 결정적 quick-fix가 있으면 계획을, 없으면 null(순수·부수효과 없음). */
+export declare function resolveQuickFix(issue: ValidationIssue, model: LogicalModel): QuickFixPlan | null;

package/dist/core/scaffoldJava.d.ts

@@ -0,0 +1,62 @@
+import { LogicalModel, ModelId, SuperClassCatalog, EmbeddableCatalog } from './types';
+import { JavaTypeDef } from './javaTypes';
+export interface ScaffoldOptions {
+    /** 저장값→소스 타입 역해소 카탈로그. 미주입 시 lib 내장 `JAVA_TYPES` 폴백(호스트 javaTypeCatalog 미러). */
+    javaTypeCatalog?: readonly JavaTypeDef[];
+    /** 임베더블 타입 해소용(EMBED_PREDEF 필드 타입·클래스명). 미주입 시 모델 type 폴백 + fillIn. */
+    embeddableCatalog?: EmbeddableCatalog;
+    /**
+     * `extends <superClass>` + 상속 컬럼 인덱스 해소용. 핸드오프 O3 — `SuperClassDef.packageName`이
+     * "코드젠 forward 슬롯"으로 예약돼 있고 이 emitter가 그 첫 소비처다. 미주입 시 상속 컬럼/extends 미방출.
+     */
+    superClassCatalog?: SuperClassCatalog;
+    /**
+     * 패키지 조합 설정(레거시 codegen 이식 — 프로젝트/모듈 설정 + 그룹 조합). 모델 엔티티엔 packageName 이
+     * 없고(모델링 도구 특성), 코드젠이 `{basePackage}.{그룹 packageName}.{layerSuffix}` 로 조합한다.
+     * - `basePackage`: 모듈 base(호스트 `srcGenConfig.bizModuleConfigs[moduleId].basePackage`, 예 `net.g1project.ecp.sales.order`).
+     * - `layerSuffix`: DDD 레이어 접미(기본 `command.domain` — 실물 골든 관례). 그룹 packageName 이 base 마지막
+     *   세그먼트와 중복돼도 정상(대형 모듈은 base 안에 order/claim 서브패키지 존재). 그룹 미소속/무 packageName 이면
+     *   그룹 세그먼트 생략. 미주입 시 placeholder 폴백(reconcile 몫).
+     */
+    packageConfig?: {
+        basePackage: string;
+        layerSuffix?: string;
+    };
+    /**
+     * GroupCodeEnum 속성의 enum 클래스가 사는 패키지(레거시 codegen 컨벤션 = const 프로젝트 basePackage +
+     * `.code`, 예 `net.g1project.ecp.common.code`). 주입 시 `@Enumerated` 필드에 `{pkg}.{groupCode}` import 를
+     * 방출한다. 미주입 시 import 생략 + fillIn(패키지 확인). 호스트가 srcGenConfig.constProjectConfig 에서 도출.
+     */
+    groupCodeEnumPackage?: string;
+    /**
+     * Lombok 방출 모드(기본 `true` — 모델러 사용 프로젝트가 사실상 전부 Lombok). true면 **필드 단위**
+     * `@Getter`(스칼라·단일 임베드·owner 관계, 대형 엔티티 SalesOrch류 관례) + 클래스 `@NoArgsConstructor
+     * (access = AccessLevel.PROTECTED)`를 방출하고 수동 getter·protected 생성자를 생략한다. **컬렉션 관계**
+     * getter는 @Getter가 raw 컬렉션을 반환해 애그리거트 보호가 깨지므로 예외 — 수동 `Collections.unmodifiable…`
+     * 유지(@Getter 미부착). **@Version**은 JPA 관리 내부 필드라 getter 제외(실측 37/38 무 getter).
+     * `{Entity}PK`는 필드 @Getter만, equals/hashCode·생성자는 수동. `false` = 수동 전량(생성기/코퍼스 패리티,
+     * 바이트 골든 앵커 모드 — @Version getter 포함).
+     */
+    lombok?: boolean;
+}
+export interface ScaffoldedEntity {
+    modelId: ModelId;
+    /** `{ClassName}.java` */
+    fileName: string;
+    /** 조합·결정된 패키지(소비자 UI의 패키지 트리 그룹핑용). placeholder 폴백 시 `com.example`. */
+    packageName: string;
+    /** 컴파일 가능 최소 골격 자바 소스(`// TODO [손채움]` 포함). */
+    source: string;
+    /** 사람이 채울 지점 목록(라벨) — reconcile 보고용. */
+    fillIns: string[];
+    /** 신규 엔티티 경로에서만 write(기존엔 재추가 금지, §4.4) — reconcile 판단. */
+    repository?: {
+        fileName: string;
+        source: string;
+    };
+}
+/**
+ * 대상 엔티티들을 JPA 자바 소스로 렌더한다. `logical`은 참조 폐포(FK 대상 등) 해소를 위해 전체를 받고,
+ * `targetIds`가 실제 산출(파일 생성) 스코프다. 스코프 밖 엔티티는 읽기(폐포)에만 쓰이고 산출되지 않는다.
+ */
+export declare function scaffoldEntityJava(logical: LogicalModel, targetIds: readonly ModelId[], opts?: ScaffoldOptions): ScaffoldedEntity[];

package/dist/core/sharedColumn.d.ts

@@ -1,4 +1,4 @@
-import { DbColumn, ModelId } from './types';
+import { DbColumn, Entity, ModelId } from './types';
 /** SHARED_REF 컬럼의 파생 투영값. insertable/updatable는 정의상 항상 false. */
 export interface ResolvedSharedColumn {
     /** 타깃 컬럼의 물리명(이 컬럼이 read-only로 투영되는 실제 물리 컬럼). */
@@ -6,9 +6,24 @@ export interface ResolvedSharedColumn {
     insertable: false;
     updatable: false;
 }
+/**
+ * SHARED_REF 후보·해석의 **컬럼 스코프 엔터티** — "임베드 평탄화 후 같은 물리 테이블에 들어가는
+ * 컬럼을 가진 엔터티들". 일반 엔터티는 자기 자신뿐이지만, JPA_EMBEDDABLE 엔터티는 @Embedded로 owner
+ * 테이블에 평탄화되므로 owner 엔터티(자기를 EMBED_OWN 표시속성으로 임베드한 엔터티)의 컬럼도 같은
+ * 테이블 스코프다 → embeddable 안의 Money.currency가 owner의 통화 writer 컬럼을 SHARED_REF로 공유할 수
+ * 있다(BNKR_SALES 실측: OrderAmount·CancellationAmtDetail 등 수많은 embeddable이 owner의 단일 통화
+ * 컬럼을 공유하는 지배적 패턴). owner 판별 = `embedded.embeddableRef === 이 엔터티 modelId`인 EMBED_OWN
+ * 표시속성 보유(adapter가 owner에 push, diagramAdapter.ts:428). 다중 owner(재사용, 결정 B-1)면 합집합 —
+ * 실효 물리명이 같으면 각 usage의 @AttributeOverride가 정상 emit되고 어긋나면 dangling으로 표면화된다.
+ * 일반 엔터티엔 [self]만 반환 → 기존 동작 무회귀.
+ */
+export declare function sharedColumnScopeEntities(entity: Entity, entities: readonly Entity[]): Entity[];
+/** 스코프 엔터티들의 전 컬럼 평탄화 — 해석 인덱스(`indexColumnsByModelId`) 입력. */
+export declare function collectSharedColumns(entity: Entity, entities: readonly Entity[]): DbColumn[];
 /**
  * 같은 엔터티의 컬럼들을 modelId로 인덱싱 — picker 후보 해석·SHARED_REF 타깃 조회 공용 인덱스.
  * EMBED 펼친 dbAttrs를 포함한 전 컬럼을 평탄화하므로 SHARED_REF 타깃이 임베드 내부여도 조회된다.
+ * (embeddable→owner 크로스 스코프가 필요하면 `collectSharedColumns`로 입력을 넓혀 넘긴다.)
  */
 export declare function indexColumnsByModelId(columns: readonly DbColumn[]): Map<ModelId, DbColumn>;
 /**

package/dist/core/text.d.ts

@@ -3,6 +3,9 @@ import { DisplayMode, LogicalModel } from './types';
  * 표시 모드별 라벨(평문) — Diagram Explorer 트리/캡션 공용.
  * EntityNode의 labelSegs와 동일 의미 규칙: '논리'는 업무 논리명이며 없으면 '(논리명)'
  * 플레이스홀더(코드명으로 폴백하지 않음), '물리'는 physicalName, CLASS만 코드명.
+ *
+ * `logicalFallback`은 논리명 미입력 시 표시할 플레이스홀더(UI 크롬). 뷰는 로케일 문자열
+ * (`em.node.logicalMissing`)을 주입하고, 미주입 시 ko 기본값으로 폴백(codegen/테스트 무회귀).
  */
-export declare function displayLabel(mode: DisplayMode, code: string, logical: string | undefined, physical: string | undefined): string;
+export declare function displayLabel(mode: DisplayMode, code: string, logical: string | undefined, physical: string | undefined, logicalFallback?: string): string;
 export declare function entityModelToText(logical: LogicalModel): string;

package/dist/core/types.d.ts

@@ -103,6 +103,52 @@ export interface GroupCodeCatalogEntry {
     codes: GroupCodeValue[];
 }
 export type GroupCodeCatalog = GroupCodeCatalogEntry[];
+/**
+ * 슈퍼클래스 카탈로그 — `Entity.superClass`(예: BaseEntity)가 상속시키는 컬럼(감사필드 createdBy/
+ * createdAt/updatedBy/updatedAt 등)의 정의. 상속 컬럼은 모델에 물질화되지 않으므로(syncPlaybook §G4
+ * 상속필드 의도적 부재) 인덱스 대상으로 참조하려면 이 카탈로그로 파생 투영한다(`inheritedColumns.ts`).
+ * EmbeddableCatalog와 동형으로 **호스트가 주입**하며(shared/ 하드코딩 상수, 완전 통합 시 superClassCatalog
+ * 엔드포인트) 코어는 소비만 한다. 빈 배열이면 상속 컬럼 투영이 나오지 않는다(inert — 인덱스는 로컬
+ * dbAttr만 참조 가능).
+ */
+export interface SuperClassColumnDef {
+    /** 논리 필드명 = 합성 modelId(`inherited:<class>:<field>`) 키. 카탈로그 물리명이 바뀌어도 안정(D6). 예: 'createdAt'. */
+    field: string;
+    /** 물리 컬럼명(@Index columnList 코드젠용). 예: 'created_at'. */
+    physicalName: string;
+    /** dbTypes 카탈로그 값. 예: 'TIMESTAMP'. */
+    dataType: string;
+    /** 표시용 논리명(선택). */
+    logicalName?: MultiLangText;
+    length?: number;
+    scale?: number;
+}
+export interface SuperClassDef {
+    /** `Entity.superClass`와 매칭되는 클래스명(예: BaseEntity). 카탈로그 내 유일. */
+    name: string;
+    /**
+     * JPA 상속 종류. 초기엔 mapped-superclass만 — @Index(columnList=)가 상속 물리 컬럼을 유효하게
+     * 참조하는 전제(상속 컬럼이 자식 테이블에 병합됨). 다른 전략(JOINED 등)은 별도 트랙.
+     */
+    kind: 'MAPPED_SUPERCLASS';
+    /**
+     * base 클래스의 자바 패키지(FQN 구성용). 예: 'net.g1project.ecp.common.domain'.
+     * **현재 lib 소비처 없음** — 상속 컬럼 인덱스 모델링은 field/physicalName/dataType만 쓴다.
+     * 코드젠이 `import <packageName>.<name>;` + `extends <name>`를 낼 때를 위한 forward 슬롯(호스트 소유).
+     * 카탈로그를 base 클래스 단일 SoT로 키우려는 방향(embeddable/javaType 카탈로그 계열)의 provisioning.
+     */
+    packageName?: string;
+    /**
+     * 이 base가 프로젝트 **암묵 default**인지. `Entity.superClass`가 비어 있으면(레거시 관례상
+     * 명시 안 함 = 코드젠이 `extends <default>`를 냄) 이 base가 상속 컬럼을 기여한다.
+     * 카탈로그 내 최대 하나만 표시(여럿이면 첫 항목). 명시적 `superClass='Object'`는 non-empty라
+     * 이 폴백에 걸리지 않고 카탈로그 미스 → 상속 없음(자바 `extends Object` = default 상속 opt-out 트릭).
+     */
+    default?: boolean;
+    /** 이 슈퍼클래스가 기여하는 컬럼(선언 순서 보존). */
+    columns: SuperClassColumnDef[];
+}
+export type SuperClassCatalog = SuperClassDef[];
 export interface DbColumn {
     modelId: ModelId;
     physicalName: string;
@@ -269,13 +315,12 @@ export interface AssociationEnd {
     multiplicity: Multiplicity;
     navigable: boolean;
     composition: boolean;
-    /** FK/조인을 표현하는 속성 (RELATION_OWN/REF) */
-    attributeRef?: ModelId;
     /**
-     * 라운드트립 전용 — 레거시 crossed 직렬화의 nav 참조 속성 원형(신규 모델에 표현 슬롯 없음).
-     * 로드 시 어댑터가 보관, 저장 시 그대로 환원한다. UI·전파는 무시한다.
+     * FK/조인 또는 inverse nav를 표현하는 속성. owner end=RELATION_OWN(FK), 부모(navigable) end=
+     * RELATION_REF(inverse nav). 레거시 crossed nav는 로드 시 소유 엔티티에 RELATION_REF로 승격되고
+     * 이 ref가 그것을 가리킨다(diagramAdapter.assocFromHydrated). 레이아웃 앵커는 layout.sourceColumnRef로 분리.
      */
-    legacyNavRaw?: Record<string, unknown>;
+    attributeRef?: ModelId;
     /**
      * 라운드트립 전용 — 레거시 EMBED 직렬화의 인라인 속성 원형(EMBED_REF/EMBED_OWN).
      * EMBED hydration은 load-only라 저장 시 소유자로 펼친 표시 속성을 버리고 이 원형을 verbatim 환원한다

package/dist/core/validation.d.ts

@@ -1,14 +1,21 @@
-import { EmbeddableCatalog, LogicalModel, ModelId } from './types';
+import { Attribute, DbColumn, EmbeddableCatalog, LogicalModel, ModelId, SuperClassCatalog } from './types';
 export declare const PHYSICAL_NAME_MAX_LENGTH = 63;
 /**
- * 물리명이 이식성 권장 한도를 초과하면 경고 메시지, 아니면 null(비차단 — 호출부는 저장을 막지 않는다).
- * 빈값/미설정은 경고 없음(레거시 isNotEmpty 게이트 동형).
+ * 물리명이 이식성 권장 한도를 초과하면 **초과 길이(문자 수)**, 아니면 null(비차단 — 호출부는 저장을
+ * 막지 않는다). 빈값/미설정은 경고 없음(레거시 isNotEmpty 게이트 동형).
+ *
+ * 이전엔 완성된 경고 문자열을 반환했으나, i18n(P3)로 core가 표시 문자열을 만들지 않게 되어 길이만
+ * 돌려준다 — 컬럼·테이블·인덱스 3곳이 이 값을 `CHK-NAME-5` params `{max,len}`로 재사용(단일 출처).
  */
-export declare function physicalNameWarning(name: string | null | undefined): string | null;
+export declare function physicalNameLengthOverflow(name: string | null | undefined): number | null;
 export type IssueSeverity = 'error' | 'warning' | 'info';
 export type IssueTargetKind = 'entity' | 'attribute' | 'column' | 'association' | 'index' | 'group' | 'model';
 export interface ValidationIssue {
-    /** 규칙 식별자(예: 'CHK-NAME-1'). 엔진 불변식 INV-*와 다른 네임스페이스(위반 가능·수정 대상). */
+    /**
+     * 규칙 식별자(예: 'CHK-NAME-1'). 엔진 불변식 INV-*와 다른 네임스페이스(위반 가능·수정 대상).
+     * **메시지 code**를 겸한다 — 뷰가 `ruleId`(+targetKind/params 변형)로 i18n 키를 해석해 로컬라이즈
+     * (`view/validationDisplay.issueMessageKey`). core는 문자열을 만들지 않는다(D3, 논리↔표시 분리).
+     */
     ruleId: string;
     severity: IssueSeverity;
     targetKind: IssueTargetKind;
@@ -16,7 +23,12 @@ export interface ValidationIssue {
     targetRef?: ModelId;
     /** 보조 ref(예: 컬럼/속성 이슈의 소속 엔티티) — 뷰 그룹핑/내비용. */
     contextRef?: ModelId;
-    message: string;
+    /**
+     * 메시지 보간 파라미터 — 뷰가 `c.t(key, params)`로 치환. 값은 식별자/카운트/JPA 리터럴 등
+     * **번역 대상이 아닌 데이터**(name·dataType·which='end1'/'end2'·cascade='ALL'/'REMOVE' 등).
+     * 정적 메시지 규칙은 생략. i18n 카탈로그(`em.i18n`)에 의존하지 않도록 구조만 노출(순수성 유지).
+     */
+    params?: Record<string, string | number>;
 }
 /** 카탈로그 의존 규칙을 켜는 선택 주입 — 미주입 시 해당 규칙 skip(범위 밖 아님, 컨텍스트 부재). */
 export interface ValidationContext {
@@ -43,7 +55,26 @@ export interface ValidationContext {
      * 타입 출처. 호스트/dev 주입(reservedWords와 동형 ctx 게이트). 미주입/빈 배열이면 CHK-TYPE-3 skip.
      */
     embeddableCatalog?: EmbeddableCatalog;
+    /**
+     * 슈퍼클래스 카탈로그 — CHK-DSN-5(dangling 인덱스 대상)가 인덱스 columnRef의 상속 컬럼(`inherited:`
+     * 합성 ref)을 유효한 대상으로 인지하는 화이트리스트 출처. 호스트/dev 주입(embeddableCatalog 동형 ctx
+     * 게이트). 미주입/빈 배열이면 상속 컬럼을 인지하지 못하므로, superClass 상속 컬럼을 참조하는 인덱스가
+     * dangling으로 오탐될 수 있다 — 카탈로그가 주입돼야 정확 판정(로컬 컬럼만 참조하는 모델은 무영향).
+     */
+    superClassCatalog?: SuperClassCatalog;
 }
+/** 같은 키를 2회 이상 갖는 항목만 중복으로 — 중복 그룹의 모든 멤버를 반환(어느 쪽이든 보고 고치게). */
+/**
+ * 임베드 서브컬럼의 **실효 물리명** — 물리명 override(비어있지 않은 physicalName)가 있으면 그 값, 없으면
+ * 상속 기본값을 해석한다. EMBED_PREDEF·EMBED_OWN의 빈 슬롯은 "미매핑"이 아니라 카탈로그/임베더블 source의
+ * 기본 컬럼명을 상속하므로(JPA @Embedded는 @AttributeOverride 부재 시 임베더블 선언 컬럼명 사용), 컬럼 충돌
+ * 판정은 raw '' 가 아닌 이 실효 물리명으로 해야 한다. 특히 한 테이블에 같은 임베더블(예: Money)이 여러 번
+ * 쓰이고 서브컬럼을 비워두면 전부 같은 기본명으로 상속돼 실제 컬럼 충돌이 난다.
+ *  - EMBED_PREDEF: 카탈로그 fields[index].physicalName (ctx 미주입이면 해석 불가 → '' 로 graceful degrade).
+ *  - EMBED_OWN: 임베더블 엔터티 source 컬럼[index]의 physicalName(선언순 평탄화 = flattenEmbeddableColumns 동형).
+ *  - NORMAL 등 그 외: raw physicalName 그대로(빈 값은 '' → 충돌 판정 제외).
+ */
+export declare function resolveColumnPhysicalName(attr: Attribute, col: DbColumn, index: number, model: LogicalModel, ctx?: Pick<ValidationContext, 'embeddableCatalog'>): string;
 /**
  * 설계 품질 검증 — 논리 모델(+선택 컨텍스트)을 받아 이슈 목록을 돌려준다.
  * 순수 함수. 호출부가 심각도/차단정책/표시시점을 해석한다(예: 빈 이름 info는 저장 시점에만 표시).