@g1cloud/entity-modeler-next 5.0.0-alpha.1

package/dist/core/svg.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 다이어그램 기하 스냅샷 → 벡터 SVG 문자열 (순수 함수, DOM 무의존).
+ *
+ * `core/text.ts`(모델→Markdown)와 같은 "산출물 합성" 계열이되, 입력이 논리 모델이 아니라
+ * 화면에서 측정한 기하 스냅샷(`DiagramGeometry`)이다. CSS 레이아웃 규칙을 일절 재현하지 않고
+ * 측정된 좌표·텍스트·색을 SVG primitive(<rect>/<text>/<line>/<path>)로 직렬화만 한다
+ * → CSS↔SVG 드리프트 0, DOM 무의존이라 단위 테스트 가능. 측정(DOM 의존)은 view 레이어 담당.
+ *
+ * 모든 좌표는 flow 좌표계(절대)다 — 측정 레이어가 그렇게 환산해 넘긴다.
+ */
+/** 텍스트 한 조각 — 측정된 위치에 같은 폰트로 그린다(위치가 실측이라 폰트 메트릭 재계산 불요). */
+export interface SvgTextFrag {
+    x: number;
+    /** 수직 중앙 y. dominant-baseline=central로 그려 baseline 추정을 피한다. */
+    y: number;
+    text: string;
+    fill: string;
+    fontSize: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    /** 'italic' 등. 미지정이면 normal. */
+    fontStyle?: string;
+    /** 가로 정렬 기준점. 기본 start(좌측). */
+    anchor?: 'start' | 'middle' | 'end';
+}
+/** 박스 내부 가로 구분선 (행/구획 경계). 좌표는 절대 flow 좌표. */
+export interface SvgHLine {
+    x1: number;
+    x2: number;
+    y: number;
+    stroke: string;
+    strokeWidth?: number;
+}
+/** 모서리별 둥글기 — 헤더(상단만)·그룹 라벨(비대칭) 같은 4코너 비대칭 radius 표현용. */
+export interface Corners {
+    tl: number;
+    tr: number;
+    br: number;
+    bl: number;
+}
+/** 박스형 노드(엔티티·그룹·노트) 기하. */
+export interface SvgBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill: string;
+    stroke: string;
+    strokeWidth?: number;
+    /** 점선 그룹 등. SVG stroke-dasharray 값(예: '6 4'). */
+    strokeDasharray?: string;
+    /** 단일 값(4코너 동일) 또는 코너별. 비대칭이면 rect가 아닌 rounded path로 그린다. */
+    radius?: number | Corners;
+    /** 반투명 그룹 배경 등. */
+    opacity?: number;
+    texts: SvgTextFrag[];
+    lines?: SvgHLine[];
+    /**
+     * 라인 아이콘(키 마커·임베드 글리프 등) — 측정 레이어가 좌표·색·viewBox를 박은 완결 <svg>
+     * 마크업 문자열. 신뢰된 내부 데이터(EmIcon)라 이스케이프 없이 그대로 삽입한다.
+     */
+    icons?: string[];
+}
+/** 엣지(연관선·노트연결선) 기하. d는 이미 렌더된 path를 그대로 차용. */
+export interface SvgEdge {
+    d: string;
+    stroke: string;
+    strokeWidth: number;
+    /** 점선 노트연결선 등. */
+    strokeDasharray?: string;
+    labels: SvgTextFrag[];
+    /**
+     * 끝점 표기 마커(까마귀발·선택성 원·컴포지션 마름모·네비 화살표) — 측정 레이어가 좌표·색을 박은
+     * 완결 <line>/<circle>/<path> 마크업 문자열. 신뢰된 내부 데이터(AssociationEdge)라 그대로 삽입.
+     */
+    markers?: string[];
+}
+/** 화면 측정으로 만든 다이어그램 전체 기하 스냅샷 (export 전용 뷰모델). */
+export interface DiagramGeometry {
+    viewBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** 캔버스 배경색(테마 반영). 미지정이면 배경 rect를 그리지 않음(투명). */
+    background?: string;
+    /** Z-order 하위부터: 그룹 → 엣지 → 엔티티/노트 순으로 합성한다. */
+    groups: SvgBox[];
+    edges: SvgEdge[];
+    entities: SvgBox[];
+    notes: SvgBox[];
+}
+/**
+ * 기하 스냅샷을 완결된 SVG 문서 문자열로 합성한다.
+ * Z-order(캔버스와 동일): 배경 → 그룹 → 엣지 → 엔티티 → 노트.
+ */
+export declare function renderDiagramSvg(geo: DiagramGeometry): string;

package/dist/core/text.d.ts

@@ -0,0 +1,8 @@
+import { DisplayMode, LogicalModel } from './types';
+/**
+ * 표시 모드별 라벨(평문) — Diagram Explorer 트리/캡션 공용.
+ * EntityNode의 labelSegs와 동일 의미 규칙: '논리'는 업무 논리명이며 없으면 '(논리명)'
+ * 플레이스홀더(코드명으로 폴백하지 않음), '물리'는 physicalName, CLASS만 코드명.
+ */
+export declare function displayLabel(mode: DisplayMode, code: string, logical: string | undefined, physical: string | undefined): string;
+export declare function entityModelToText(logical: LogicalModel): string;

package/dist/core/types.d.ts

@@ -0,0 +1,400 @@
+/**
+ * 논리 모델 ↔ 레이아웃 모델 분리의 타입 계약.
+ *
+ * 핵심 원칙: 레이아웃이 논리 모델을 `modelId`로 참조한다(단방향).
+ * 논리 모델에는 좌표/크기/waypoint/style 같은 렌더링 정보가 없다 →
+ * 코드생성·DDL·API 수정의 깨끗한 입력이 된다.
+ *
+ * 레거시 대응:
+ *  - EntityModel/AttributeModel/AssociationModel/GroupModel (geo·style 제거)
+ *  - Geo/Point/Size → 레이아웃 모델로 이동
+ */
+export type ModelId = string;
+/** 다국어 텍스트 (레거시 Map<String,String>, bluework4-tool MultiLangText 동형) */
+export type MultiLangText = Partial<Record<'ko' | 'en' | 'ja' | 'zh', string>>;
+/** MultiLangText가 지원하는 언어 코드. 입력 가능 언어셋·유저 언어 주입의 단위. */
+export type LangCode = keyof MultiLangText;
+export type ClassStereotype = 'UNDEFINED' | 'JPA_ENTITY' | 'JPA_EMBEDDABLE' | 'JPA_MULTI_LANGUAGE_ENTITY';
+export type Multiplicity = 'NO_INSTANCE_OR_ONE_INSTANCE' | 'EXACTLY_ONE_INSTANCE' | 'ZERO_OR_MORE_INSTANCES' | 'ONE_OR_MORE_INSTANCES';
+export type JpaCascadeType = 'ALL' | 'PERSIST' | 'MERGE' | 'REMOVE' | 'REFRESH' | 'DETACH';
+export type JpaFetchType = 'LAZY' | 'EAGER';
+export type AttributeType = 'NORMAL' | 'RELATION_OWN' | 'RELATION_REF' | 'EMBED_OWN' | 'EMBED_REF' | 'EMBED_PREDEF'
+/**
+ * 시각 구획 행 — 속성이 아니라 거대 엔티티에서 속성 묶음을 끊어 읽는 구분선. DB 컬럼·식별자·타입을
+ * 갖지 않으며(dbAttrs=[], type=''), `name`은 선택적 섹션 라벨(빈 문자열이면 민무늬 선). 검증·코드
+ * 생성·식별자 전파 등 논리 속성 순회에서는 제외 대상이다(과거엔 name이 대시인 NORMAL 가짜 속성으로
+ * 표현 → 속성명 중복/속성 과다 검증 false-positive 유발. adapter가 로드 시 DIVIDER로 승격).
+ */
+ | 'DIVIDER';
+/**
+ * Predefined 임베더블 카탈로그 — 신규 EMBED_PREDEF 삽입 시 dbAttr 골격을 시드하고, 빈 슬롯을 표시
+ * 폴백할 메타모델 정의. 레거시 `AttributeMeta.getPredefinedEmbeddableMetaModel`(Name/Address/Tel/
+ * UploadedFile) 대응. **호스트가 주입**하며(완전 통합 시 embeddableCatalog API) 코어는 소비만 한다
+ * — 코어에 4종을 박으면 곧 하드코딩이므로 정의를 외부(호스트/dev 프리셋)에 둔다.
+ */
+export interface EmbeddableCatalogField {
+    /** 논리 필드명(레거시 AttributeMeta name, 예: countryCode) — 현재 dbAttr엔 미저장, 폴백 인덱스 매칭·식별용. */
+    name: string;
+    physicalName: string;
+    logicalName?: MultiLangText;
+    dataType: string;
+    length?: number;
+    scale?: number;
+    /**
+     * 이 컬럼이 공유 통화 컬럼(SHARED_REF) 모드를 지원하는지 — true면 삽입/편집 UI가 OWN/SHARED_REF
+     * picker를 노출한다(예: Money의 currency 필드). per-usage로 같은 엔터티의 다른 컬럼을 참조하는
+     * 모델 표현은 인스턴스 `DbColumn.sharedColumnRef`가 담당하며, 이 플래그는 어떤 카탈로그 필드에
+     * 그 어포던스를 열어줄지 결정하는 **UI 힌트**일 뿐 모델에 모드를 저장하지 않는다.
+     */
+    shareable?: boolean;
+}
+export interface EmbeddableCatalogEntry {
+    /** Attribute.type에 들어가는 임베더블 타입명(예: EmbeddableAddress). 카탈로그 내 유일. */
+    type: string;
+    /** 삽입 시 기본 속성명(예: address). 사후 rename 허용. */
+    defaultName: string;
+    /** 메뉴 표시 라벨(미지정 시 type). */
+    label?: MultiLangText;
+    /** 펼쳐질 컬럼 메타모델(선언 순서 = dbAttr 인덱스). */
+    fields: EmbeddableCatalogField[];
+}
+export type EmbeddableCatalog = EmbeddableCatalogEntry[];
+/**
+ * Predefined customtype 카탈로그 — 등록된 **단일 컬럼** 커스텀 자바 타입(레거시 JavaType 중 StoredFile·
+ * MultiLangString 등 ③ 분류)의 타입 셀렉트 진입 정의. ②embeddable과 달리 단일 컬럼이라 컬럼 구조가
+ * ①스칼라와 동일 — 별도 진입이 아니라 ① 타입 셀렉트에 병합 노출하고(④ CustomType과 동질), 선택 시
+ * 단일 dbAttr의 dataType만 카탈로그 메타로 시드한다(attrType은 NORMAL 유지 — EMBED_PREDEF 아님).
+ * EmbeddableCatalog와 동형으로 **호스트가 주입**하며(MultiLangString·StoredFile은 프레임워크 공통분 +
+ * 프로젝트별 추가분) 코어는 소비만 한다 — lib에 정적 baseline을 두지 않는다. 빈 배열이면 셀렉트에
+ * 추가 옵션이 노출되지 않는다(inert — 기존 customtype-typed 속성은 폴백 합성으로 원형 표시).
+ */
+export interface PredefinedCustomTypeEntry {
+    /** Attribute.type에 들어가는 커스텀 타입명(예: StoredFile). 카탈로그 내 유일. */
+    type: string;
+    /** 셀렉트 표시 라벨(미지정 시 type). */
+    label?: MultiLangText;
+    /** 선택 시 단일 dbAttr에 시드할 물리 DB 타입. */
+    dataType: string;
+    length?: number;
+    scale?: number;
+}
+export type PredefinedCustomTypeCatalog = PredefinedCustomTypeEntry[];
+/**
+ * 공통 코드 그룹 카탈로그 — 속성의 `groupCode`(코드성 속성이 참조하는 공통 코드 그룹) 선택 UI에 쓰일
+ * 그룹·코드 정의. 레거시 `EMGroupCodeSelectionLayer` + `EMGroupCodeProvider`(호스트 콜백) 대응.
+ * EmbeddableCatalog와 동형으로 **호스트가 주입**하며(완전 통합 시 systemCode API) 코어는 소비만 한다
+ * — 코어에 코드 데이터를 박으면 곧 하드코딩이므로 정의를 외부(호스트/dev 프리셋)에 둔다.
+ * 빈 배열이면 groupCode 드롭다운은 비노출(inert).
+ */
+export interface GroupCodeValue {
+    /** 코드 값(예: "GOLD"). 속성 선택 시 그대로 defaultValue로 채워진다. */
+    code: string;
+    /** 메뉴 표시 라벨(미지정 시 code). */
+    label?: MultiLangText;
+    /** 코드 색상(레거시 codeList color, 선택). */
+    color?: string;
+}
+export interface GroupCodeCatalogEntry {
+    /** Attribute.groupCode에 들어가는 그룹 코드명(예: "CUSTOMER_GRADE"). 카탈로그 내 유일. */
+    groupCode: string;
+    /** 메뉴 표시 라벨(미지정 시 groupCode). */
+    label?: MultiLangText;
+    /** 그룹에 속한 코드 값 목록(선언 순서 = 드롭다운 표시 순서). */
+    codes: GroupCodeValue[];
+}
+export type GroupCodeCatalog = GroupCodeCatalogEntry[];
+export interface DbColumn {
+    modelId: ModelId;
+    physicalName: string;
+    logicalName?: MultiLangText;
+    dataType: string;
+    length?: number;
+    scale?: number;
+    unique?: boolean;
+    autoIncrement?: boolean;
+    updatable?: boolean;
+    /** JPA @Column(insertable=…). undefined=기본 따름. v1 레거시엔 없는 신규 옵션. */
+    insertable?: boolean;
+    /**
+     * 공유 통화 컬럼(SHARED_REF) — 이 컬럼이 자체 물리 컬럼을 갖지 않고 같은 엔터티의 다른 컬럼을
+     * **modelId로 참조**해 그 물리 컬럼에 read-only 투영됨을 뜻한다(예: Money embeddable의 currency
+     * 서브컬럼이 별도 스칼라 통화 속성의 컬럼을 공유). 존재 시 physicalName·insertable·updatable는
+     * 저장하지 않고 타깃 컬럼에서 파생(자동 insertable=false·updatable=false). 부재 시 OWN(전용 컬럼).
+     * FK 전파의 부모 PK 링크(persisted PDbAttr.targetModelId)와는 의미가 다른 별개 개념. v1 레거시엔
+     * 없는 신규 옵션. 근거=OrderItem 실측 67개 중 48개가 단일 통화 컬럼 공유(memory money-shared-currency-column-decision).
+     */
+    sharedColumnRef?: ModelId;
+    /** 다중값 컬럼 여부(레거시 AttributeDatabaseAttribute.multiValue). 라운드트립 보존 전용. */
+    multiValue?: boolean;
+    /** 다중값 직렬화 구분자(레거시 기본 "|"). multiValue=false여도 원형 보존 위해 verbatim 유지. */
+    multiValueSeparator?: string;
+    /** 시퀀스명(레거시 AttributeDatabaseAttribute.sequenceName). 라운드트립 보존 전용. */
+    sequenceName?: string;
+}
+export interface Attribute {
+    modelId: ModelId;
+    name: string;
+    type: string;
+    /** 빌트인 JavaType이 아닌 사용자 정의/커스텀 타입명(예: StoredFile). type이 커스텀 마커일 때 실제 타입. */
+    customType?: string;
+    attrType: AttributeType;
+    identifier: boolean;
+    notNull: boolean;
+    transient?: boolean;
+    description?: MultiLangText;
+    attributeGroup?: string;
+    groupCode?: string;
+    /**
+     * 속성 기본값(레거시 AttributeModel.defaultValue). 코드성 속성은 groupCode 선택 시 그 code 문자열을
+     * 채우고, 그 외엔 자유 입력("Y"/"N"/"999" 등). 항상 문자열 패스스루(타입 무관 verbatim 보존).
+     */
+    defaultValue?: string;
+    /**
+     * 개인정보 속성 유형(레거시 AttributeModel.personalInfoAttributeType, PersonalInfoAttributeType enum 이름).
+     * 라운드트립 보존 전용 — Operation.personalInfoAttributeType와 동형으로 문자열 패스스루.
+     */
+    personalInfoAttributeType?: string;
+    order: number;
+    /** 보통 1개, 임베더블 플래튼 시 다수 */
+    dbAttrs: DbColumn[];
+    /**
+     * 식별자 전파로 생성된 FK 속성의 출처. 수동 작성 속성은 undefined.
+     * 재전파/정리 시 컬럼 단위 매칭 키로 쓴다(associationRef + sourceAttributeRef).
+     */
+    derivedFrom?: {
+        /** 이 FK를 만든 관계 */
+        associationRef: ModelId;
+        /** 부모의 어느 식별자 속성을 미러하는가 */
+        sourceAttributeRef: ModelId;
+    };
+    /**
+     * 임베더블 인라인 EMBED hydration의 출처(load-only, 화면 표시 전용).
+     * 레거시는 임베더블 타입의 플래튼 컬럼 묶음을 소유자 association end에 인라인(EMBED_OWN)으로만
+     * 저장한다 → 로드 시 소유자 엔티티로 펼쳐 표시한다(컬럼은 source 물리정의 ⊕ owner 오버라이드 머지).
+     * 저장 시 이 속성은 entity.attributes에서 제외되고 association 인라인 원형(legacyEmbedRaw)으로 환원된다.
+     */
+    embedded?: {
+        /** 이 임베드를 만든 association */
+        associationRef: ModelId;
+        /** 임베더블 타입 엔티티(컬럼 정의 source) */
+        embeddableRef: ModelId;
+    };
+}
+export interface IndexColumn {
+    /** 참조 컬럼 modelId */
+    columnRef: ModelId;
+    descending: boolean;
+}
+export interface EntityIndex {
+    modelId: ModelId;
+    name: string;
+    unique: boolean;
+    description?: string;
+    parameters?: string;
+    columns: IndexColumn[];
+}
+export interface EntityJpaAttrs {
+    useVersion?: boolean;
+    useCacheable?: boolean;
+    useDynamicInsert?: boolean;
+    useDynamicUpdate?: boolean;
+    useDiscriminator?: boolean;
+    /**
+     * @DiscriminatorColumn 상세 — useDiscriminator=true일 때만 의미.
+     * 레거시 EntityJPAAttribute.discriminatorColumnName/discriminatorType/discriminatorLength.
+     * discriminatorType은 레거시 DiscriminatorType enum(STRING/CHAR/INTEGER)이나 persisted 계층 관례대로 문자열로 보존.
+     */
+    discriminatorColumnName?: string;
+    discriminatorType?: string;
+    discriminatorLength?: number;
+}
+export type OperationVisibility = 'PUBLIC' | 'PRIVATE' | 'PROTECTED' | 'PACKAGE';
+/**
+ * 엔티티 메서드 (레거시 OperationModel). 현재는 round-trip 보존 전용 — 렌더/편집은 PR2.
+ */
+export interface Operation {
+    modelId: ModelId;
+    name: string;
+    visibility?: OperationVisibility;
+    /** Java 메서드 본문 (멀티라인) */
+    sourceCode?: string;
+    /**
+     * ⚠️ 레거시 직렬화는 평문 string(Entity.description의 MultiLangText와 비대칭).
+     * 어댑터가 평문↔{ko} 변환해 모델 형태를 통일한다. PR2에서 ko 외 언어 편집 시 평문 역환원 비대칭 잔존.
+     */
+    description?: MultiLangText;
+    order: number;
+    personalInfoAttributeType?: string;
+    /**
+     * 라운드트립 전용 — 레거시 직렬화의 미매핑 키(parent back-ref·properties 등) 원형.
+     * 로드 시 어댑터가 보관, 저장 시 verbatim 환원한다. UI·전파는 무시한다.
+     * style은 뷰 관심사라 EntityLayout.operationStyles로 분리(여기 포함 안 함). [[embed-hydration-option-na]] 보존 패턴 동형.
+     */
+    legacyRaw?: Record<string, unknown>;
+}
+export interface Entity {
+    modelId: ModelId;
+    name: string;
+    stereotype: ClassStereotype;
+    packageName?: string;
+    superClass?: string;
+    schema?: string;
+    description?: MultiLangText;
+    abstractClass?: boolean;
+    hasPersonalInfo?: boolean;
+    declarationOfInterfaces?: string[];
+    attributes: Attribute[];
+    operations?: Operation[];
+    indexes?: EntityIndex[];
+    jpaAttrs?: EntityJpaAttrs;
+    table?: {
+        physicalName: string;
+        logicalName?: MultiLangText;
+    };
+}
+export interface AssociationEnd {
+    /** 이 끝이 가리키는 엔티티 */
+    entityRef: ModelId;
+    multiplicity: Multiplicity;
+    navigable: boolean;
+    composition: boolean;
+    /** FK/조인을 표현하는 속성 (RELATION_OWN/REF) */
+    attributeRef?: ModelId;
+    /**
+     * 라운드트립 전용 — 레거시 crossed 직렬화의 nav 참조 속성 원형(신규 모델에 표현 슬롯 없음).
+     * 로드 시 어댑터가 보관, 저장 시 그대로 환원한다. UI·전파는 무시한다.
+     */
+    legacyNavRaw?: Record<string, unknown>;
+    /**
+     * 라운드트립 전용 — 레거시 EMBED 직렬화의 인라인 속성 원형(EMBED_REF/EMBED_OWN).
+     * EMBED hydration은 load-only라 저장 시 소유자로 펼친 표시 속성을 버리고 이 원형을 verbatim 환원한다
+     * (의미 재구성 없이 무손실 보존). UI·전파는 무시한다. [[embed-hydration-option-na]]
+     */
+    legacyEmbedRaw?: Record<string, unknown>;
+    jpa?: {
+        fetchType?: JpaFetchType;
+        cascadeTypes?: JpaCascadeType[];
+        orphanRemoval?: boolean;
+        orderBy?: string;
+        /**
+         * 컬렉션 EMBED(`@ElementCollection`) 전용 — 이 end가 *_MORE multiplicity(N행)일 때만 의미.
+         * 단일 EMBED(EXACTLY_ONE)엔 무의미(검증 CHK로 차단·UI 비노출). 컬렉션 판정 권위는 multiplicity이며
+         * 아래 필드는 부속 메타다(결정 3: 별도 boolean 플래그 없음 — collection 여부는 multiplicity가 SoT).
+         */
+        collectionType?: 'LIST' | 'SET';
+        /** `@CollectionTable` 이름(미지정 시 코드젠 규약 폴백). */
+        collectionTable?: string;
+        /** List일 때 `@OrderColumn` 명(미지정 시 폴백 or 순서 비보존). */
+        orderColumn?: string;
+    };
+}
+export interface Association {
+    modelId: ModelId;
+    description?: string;
+    /**
+     * 식별 관계 여부. true면 부모 PK가 자식 PK의 일부로 전파(식별 관계),
+     * false/undefined면 일반 FK로만 전파(비식별 관계).
+     * self-association(end1.entityRef===end2.entityRef)은 식별 불가(INV-3).
+     */
+    identifying?: boolean;
+    /** 부모(PK 원천, "1" 측) */
+    end1: AssociationEnd;
+    /** 자식(FK 보유, "N" 측) */
+    end2: AssociationEnd;
+}
+export interface LogicalGroup {
+    modelId: ModelId;
+    name?: MultiLangText;
+    /** 그룹 설명(자유 텍스트) — 모듈/도메인 경계 의도 메모 */
+    description?: string;
+    packageName?: string;
+    excludeDDLGeneration: boolean;
+    /** 멤버십을 값 포함이 아닌 id 참조로 */
+    memberEntityRefs: ModelId[];
+}
+/** 논리 모델 전체 (한 비즈니스 모듈의 의미 정보) */
+export interface LogicalModel {
+    modelId: ModelId;
+    packageName?: string;
+    entities: Entity[];
+    associations: Association[];
+    groups: LogicalGroup[];
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Geo {
+    location: Point;
+    size: Size;
+}
+export type DisplayMode = 'LOGICAL' | 'PHYSICAL' | 'LOGICAL_PHYSICAL' | 'CLASS';
+export interface Style {
+    properties: Record<string, unknown>;
+}
+export interface EntityLayout {
+    entityRef: ModelId;
+    geo: Geo;
+    collapsed?: boolean;
+    displayMode?: DisplayMode;
+    /** 엔티티 헤더 바 색상 등 (style.properties.swatch = 토큰명) */
+    style?: Style;
+    /** 속성별 강조 색상 — attribute modelId 참조. 색은 뷰 관심사라 논리 Attribute가 아닌 레이아웃에 둔다. */
+    attributeStyles?: Record<ModelId, Style>;
+    /** 메서드별 강조 색상 — operation modelId 참조. attributeStyles와 동형(색은 뷰 관심사). */
+    operationStyles?: Record<ModelId, Style>;
+}
+export interface AssociationLayout {
+    associationRef: ModelId;
+    /** 직각 라우팅 제어점 (편집 가능 waypoint) */
+    waypoints: Point[];
+    /** 양 끝이 붙는 컬럼 앵커 (속성 행 단위 연결) */
+    sourceColumnRef?: ModelId;
+    targetColumnRef?: ModelId;
+    labelOffset?: Point;
+    style?: Style;
+}
+export interface GroupLayout {
+    groupRef: ModelId;
+    geo: Geo;
+    style?: Style;
+    /**
+     * 그룹 박스에 시각적으로 포함된 노트 멤버십(레거시 `groups[].notes`). 노트는 순수 레이아웃
+     * 객체(논리 의미 없음)라 멤버십도 레이아웃에 둔다 — 엔티티 멤버십(LogicalGroup.memberEntityRefs)과 비대칭.
+     */
+    memberNoteRefs?: ModelId[];
+}
+export interface NoteConnection {
+    /** 노트가 연결하는 대상 (엔티티/노트 등) */
+    targetRef: ModelId;
+    waypoints: Point[];
+}
+export interface Note {
+    modelId: ModelId;
+    memo: string;
+    geo: Geo;
+    style?: Style;
+    connections?: NoteConnection[];
+    /**
+     * 레거시 직렬화 중 next 모델로 매핑하지 않은 키(`ownedConnections`·`parent`·`properties`)의
+     * verbatim 보존(operation legacyRaw와 동형). 연결선 의미 재구성은 추후 UI에서.
+     */
+    legacyRaw?: Record<string, unknown>;
+}
+/** 한 다이어그램(뷰)의 레이아웃 — 1 논리모델 : N 다이어그램 가능 */
+export interface DiagramLayout {
+    diagramId: ModelId;
+    /** 어떤 논리 모델을 비추는가 */
+    logicalModelRef: ModelId;
+    name?: string;
+    canvasSize?: Size;
+    zoom?: number;
+    entityLayouts: EntityLayout[];
+    associationLayouts: AssociationLayout[];
+    groupLayouts: GroupLayout[];
+    notes: Note[];
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,53 @@
+import { EmbeddableCatalog, LogicalModel, ModelId } from './types';
+export declare const PHYSICAL_NAME_MAX_LENGTH = 63;
+/**
+ * 물리명이 이식성 권장 한도를 초과하면 경고 메시지, 아니면 null(비차단 — 호출부는 저장을 막지 않는다).
+ * 빈값/미설정은 경고 없음(레거시 isNotEmpty 게이트 동형).
+ */
+export declare function physicalNameWarning(name: string | null | undefined): string | null;
+export type IssueSeverity = 'error' | 'warning' | 'info';
+export type IssueTargetKind = 'entity' | 'attribute' | 'column' | 'association' | 'index' | 'group' | 'model';
+export interface ValidationIssue {
+    /** 규칙 식별자(예: 'CHK-NAME-1'). 엔진 불변식 INV-*와 다른 네임스페이스(위반 가능·수정 대상). */
+    ruleId: string;
+    severity: IssueSeverity;
+    targetKind: IssueTargetKind;
+    /** 문제 요소의 modelId(model 레벨이면 생략). 뷰가 클릭→포커스에 사용. */
+    targetRef?: ModelId;
+    /** 보조 ref(예: 컬럼/속성 이슈의 소속 엔티티) — 뷰 그룹핑/내비용. */
+    contextRef?: ModelId;
+    message: string;
+}
+/** 카탈로그 의존 규칙을 켜는 선택 주입 — 미주입 시 해당 규칙 skip(범위 밖 아님, 컨텍스트 부재). */
+export interface ValidationContext {
+    /** SQL 예약어 집합(대문자). 호스트 주입. 미주입 시 CHK-NAME-6 skip. */
+    reservedWords?: ReadonlySet<string>;
+    /**
+     * 타겟 DB가 허용하는 dataType 집합(다이얼렉트별). 호스트 주입. 미주입 시 CHK-TYPE-1 skip.
+     * reservedWords와 동형으로 ctx 게이트 — 코어 SELECTABLE_DATA_TYPES를 기본값으로 박지 않는 이유:
+     * 레거시 보존 타입(NCHAR 등 import verbatim)을 호스트가 다이얼렉트 셋을 줄 때까지 일괄 경고하지 않기 위함.
+     * 자연 주입값 = `new Set(SELECTABLE_DATA_TYPES)`(PG 타겟) — 호스트 통합 시 다이얼렉트로 대체.
+     */
+    selectableDataTypes?: ReadonlySet<string>;
+    /** 비대 엔티티(god-object) 판정 임계치 — 논리 속성 수가 이 값 초과면 CHK-DSN-4. 미주입 시 skip. */
+    largeEntityThreshold?: number;
+    /**
+     * CHK-DSN-3(모델링된 관계 없는 엔티티) 켜기 — **기본 off**(미주입/false 시 skip).
+     * 옵트인인 이유: 비형식 FK(연관 엣지 없이 raw id 컬럼만 둔 경우)는 코어가 탐지 불가라 잔존 오탐이
+     * 원리적으로 제거되지 않는다. "참여"는 연관·상속(superClass)·임베딩(embedded)까지 넓혀 오탐을 최소화하되,
+     * 의도적 연관 생략 모델에선 노이즈이므로 호스트/사용자가 명시적으로 켤 때만 평가한다.
+     */
+    flagEntitiesWithoutRelations?: boolean;
+    /**
+     * Predefined 임베더블 카탈로그 — CHK-TYPE-3(공유 통화 컬럼 SHARED_REF 타깃 타입 불일치)의 기대
+     * 타입 출처. 호스트/dev 주입(reservedWords와 동형 ctx 게이트). 미주입/빈 배열이면 CHK-TYPE-3 skip.
+     */
+    embeddableCatalog?: EmbeddableCatalog;
+}
+/**
+ * 설계 품질 검증 — 논리 모델(+선택 컨텍스트)을 받아 이슈 목록을 돌려준다.
+ * 순수 함수. 호출부가 심각도/차단정책/표시시점을 해석한다(예: 빈 이름 info는 저장 시점에만 표시).
+ *
+ * 범위: 명명·중복(CHK-NAME, P1) + JPA 정합성·물리타입·식별 사이클(CHK-JPA·CHK-TYPE, P2) + 설계 안티패턴(CHK-DSN, P3).
+ */
+export declare function validateModel(model: LogicalModel, ctx?: ValidationContext): ValidationIssue[];