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

package/dist/agent/resolver.d.ts

@@ -84,6 +84,28 @@ export type ResolveError = {
     handle: Handle;
     matches: ModelId[];
 }
+/** reorder order 목록의 핸들이 엔티티 내 속성/메서드와 0개 매칭(D7 — 부분 재배치 안 함, 전체 거부). */
+ | {
+    code: 'reorder-handle-not-found';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+}
+/** reorder order 목록의 핸들이 복수 매칭(모호). */
+ | {
+    code: 'reorder-handle-ambiguous';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    matches: ModelId[];
+}
+/** reorder order 목록에 같은 요소가 두 번(중복 핸들) — 배열 재배치 모호. */
+ | {
+    code: 'reorder-handle-duplicate';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+}
 /**
  * index.update patch에 `columns` 키 — columnRef(dbAttr modelId)는 사람 핸들로 표현 불가라 패스스루 시
  * 깨진 인덱스가 된다. 컬럼 변경은 index.remove + index.add(컬럼 핸들 해소 구현)로 유도(거부 권고안).
@@ -129,6 +151,30 @@ export type ResolveError = {
     entity: Handle;
     handle: Handle;
     matches: ModelId[];
+}
+/**
+ * attribute.update patch의 평탄 dbAttr 키를 스칼라 단일 컬럼으로 매핑할 수 없음. 스칼라(NORMAL·단일 dbAttr)면
+ * `dbAttrs[0]`로 자동 매핑되지만, 모호/불가한 대상은 거부한다: EMBED_PREDEF/다중 dbAttr(어느 컬럼인지 모호 →
+ * `embeddableOverrides`), dbAttrs 0개/transient(머지할 컬럼 없음), `sharedColumnRef` 평탄(opaque modelId),
+ * flat + dotted-dbAttrs 혼용($set 충돌). 통과 시 논리 노드 blind-write로 orphan 오염이라 거부.
+ */
+ | {
+    code: 'attribute-patch-dbattr-flat-key';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    keys: string[];
+}
+/**
+ * attribute.update patch에 Attribute 논리 노드에 실재하지 않는 미지 키 — 통과 시 orphan blind-write.
+ * 오탈자/스키마 밖 키를 조용히 흡수하지 않고 명시 거부(자기증식 오염 원천 차단).
+ */
+ | {
+    code: 'attribute-patch-unknown-key';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    keys: string[];
 };
 export type ResolveResult = {
     ok: true;

package/dist/agent/symbolicOp.d.ts

@@ -226,10 +226,15 @@ export type SymbolicOp = {
     entity: Handle;
     attribute: Handle;
     patch: Record<string, unknown>;
+    embeddableOverrides?: EmbeddableColumnOverride[];
 } | {
     kind: 'attribute.remove';
     entity: Handle;
     attribute: Handle;
+} | {
+    kind: 'attribute.reorder';
+    entity: Handle;
+    order: Handle[];
 } | {
     kind: 'association.add';
     spec: AssocSpec;
@@ -271,6 +276,10 @@ export type SymbolicOp = {
     kind: 'operation.remove';
     entity: Handle;
     operation: Handle;
+} | {
+    kind: 'operation.reorder';
+    entity: Handle;
+    operations: Handle[];
 } | {
     kind: 'group.add';
     spec: GroupSpec;
@@ -279,5 +288,5 @@ export type SymbolicOp = {
  * v1이 다루는 심볼릭 op 종류의 닫힌 집합(단일 출처). resolver·JSON Schema(`schema.ts`)가 공유한다.
  * 아래 컴파일타임 단언이 이 튜플과 `SymbolicOp['kind']`의 일치를 강제 — 한쪽만 늘리면 타입 에러.
  */
-export declare const SYMBOLIC_OP_KINDS: readonly ["entity.add", "entity.update", "entity.remove", "attribute.add", "attribute.update", "attribute.remove", "association.add", "association.remove", "association.update", "associationEnd.update", "index.add", "index.update", "index.remove", "operation.add", "operation.update", "operation.remove", "group.add"];
+export declare const SYMBOLIC_OP_KINDS: readonly ["entity.add", "entity.update", "entity.remove", "attribute.add", "attribute.update", "attribute.remove", "association.add", "association.remove", "association.update", "associationEnd.update", "index.add", "index.update", "index.remove", "operation.add", "operation.update", "operation.remove", "attribute.reorder", "operation.reorder", "group.add"];
 export type SymbolicOpKind = (typeof SYMBOLIC_OP_KINDS)[number];

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;
 /** 그룹 해제(삭제) — 멤버 엔티티는 남고 그룹/박스만 제거 */
@@ -52,10 +60,11 @@ export declare function updateAttribute(entityId: ModelId, attributeId: ModelId,
 export declare function removeAttribute(entityId: ModelId, attributeId: ModelId): Command;
 /**
  * 속성 재정렬 — 대상(attrIds)을 현재 표시 순서를 유지한 채 toIndex로 이동.
- * 표시 순서 = attributes 배열 순서가 SoT이므로 배열을 splice 이동하고, 저장·range선택이
- * 의존하는 order 필드를 0..n-1로 전체 재인덱싱한다(중간 삭제로 생긴 기존 갭도 함께 치유).
- * toIndex = 대상을 모두 제거한 뒤의 배열(rest) 기준 삽입 위치.
+ * 표시 순서 SoT는 `order` 필드다(S1 이후 전 뷰가 order sort). 배열도 splice로 함께 맞춰 두 표현을
+ * 일관 유지하고(캔버스 노드가 배열도 참조하는 전환기 안전), order 필드를 0..n-1로 전체 재인덱싱한다
+ * (중간 삭제로 생긴 기존 갭도 함께 치유). toIndex = 대상을 모두 제거한 뒤의 배열(rest) 기준 삽입 위치.
  * invert는 변경 전 배열 스냅샷(order 포함 얕은 복사)으로 통째 복원 → 재인덱싱 손실 없이 원자 원복.
+ * emit은 order 패치(S3, orderPatchEmission) — 배열 $set 아님.
  */
 export declare function reorderAttributes(entityId: ModelId, attrIds: ModelId[], toIndex: number): Command;
 export declare function addOperation(entityId: ModelId, operation: Operation): Command;

package/dist/core/associationNav.d.ts

@@ -0,0 +1,16 @@
+import { Multiplicity } from './types';
+/** end2 multiplicity가 컬렉션(0..* / 1..*)인가 — 코드젠의 @OneToMany vs @OneToOne 분기와 동일 기준. */
+export declare function isCollectionMultiplicity(m: Multiplicity): boolean;
+/**
+ * 다중성 표시 기호(0..1 / 1 / 0..* / 1..*) — 영속용 enum(`*_INSTANCE(S)`)의 단일 표시 SoT.
+ * 기호는 언어 무관 UML 표기라 i18n 대상이 아니다. 캔버스 관계선 라벨·인스펙터 select·mermaid
+ * 라벨이 모두 이 함수로 위임한다(과거 multSymbol/multHuman으로 중복 정의되던 것 통합).
+ */
+export declare function multiplicityLabel(m: Multiplicity): string;
+/**
+ * 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,26 @@
+import { Attribute, Entity } from './types';
+/**
+ * 다음 표시 순서 값 = 현재 최대 `order` + 1(비어 있으면 0). 표시 순서가 `order` 필드 단일 SoT이므로
+ * add-side는 반드시 이 값을 써야 order가 항상 distinct하다. 배열 `.length`를 쓰면
+ * `removeAttribute`/`removeOperation`가 재인덱싱하지 않아(splice만) 남은 order와 length가 충돌할 수
+ * 있다(order [0,2] + length 2 → 신규 order 2 = 중복). [[attribute-display-order-array-vs-order-field]]
+ */
+export declare function nextOrder(items: readonly {
+    order: number;
+}[]): number;
+/** 물리 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/fkDerived.d.ts

@@ -0,0 +1,17 @@
+import { Association, Attribute, DbColumn, Entity } from './types';
+/**
+ * FK 유래 컬럼 = 물리 컬럼을 보유한 관계 속성(RELATION* + dbAttrs). 형상(dataType/length/scale/
+ * physicalName/notNull 등)은 부모 식별자(PK) + 관계 identifying에서 파생된다.
+ * derivedFrom이 아니라 이 불변식을 쓰는 이유: derivedFrom은 세션 중 live propagation으로 만든 FK에만
+ * 붙고 어댑터가 로드 시 복원하지 않아(영속 데이터엔 0건) 로드된 다이어그램에선 FK 판정에서 통째로 누락된다.
+ * RELATION_REF(inverse nav, dbAttrs=0)는 물리 컬럼이 없어 제외.
+ */
+export declare function isFkDerivedColumn(attr: Attribute): boolean;
+/**
+ * FK 유래 컬럼 i의 원본(부모 식별자) 컬럼 — 물리명·타입·길이·스케일이 여기서 파생된다. FK 컬럼 자신의
+ * dbAttrs가 비어 있을 때(v1→v2 로드/레거시 데이터, 어댑터가 재전파를 하지 않음) placeholder·캔버스
+ * 표시에 쓴다(레거시 getForeignDatabaseAttributePlaceholder 동형). 1순위 derivedFrom.sourceAttributeRef
+ * (전파가 심은 권위), 2순위 관계 역참조로 부모 식별자 컬럼(derivedFrom 부재하는 레거시 v1 로드 FK 폴백).
+ * 못 찾으면 undefined.
+ */
+export declare function resolveFkOriginColumn(attr: Attribute, childEntity: Entity | null | undefined, entities: readonly Entity[], associations: readonly Association[], i?: number): DbColumn | undefined;

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/projectSeqDiff.d.ts

@@ -0,0 +1,41 @@
+import { ModelId } from './types';
+import { FieldAuditRecord } from './projectFieldAudit';
+import { ActionFieldChange, ActionSubject } from './projectActionLog';
+/** 한 대상의 구간 net 결과 — verb + net 필드 변경(최초 old→최종 new). */
+export interface SeqDiffEntry {
+    subject: ActionSubject;
+    /** added=구간 내 생성되어 B에 존재 / removed=A에 존재했고 구간 내 삭제 / modified=양쪽 존재+내용 변경. */
+    verb: 'added' | 'modified' | 'removed';
+    /** net 필드 변경. added=최종값(요약), removed=빈 배열(tombstone), modified=old→new(수렴分 제외). */
+    fields: ActionFieldChange[];
+}
+export interface SeqDiff {
+    fromSeq: number;
+    /** 실효 상한 — 옵션 미지정 시 스트림 최신 seq(레코드 없으면 fromSeq). */
+    toSeq: number;
+    /** subject 최초 등장 순(결정적). */
+    entries: SeqDiffEntry[];
+}
+/**
+ * op 이력 스트림을 구간 `(fromSeq, toSeq]`의 subject별 net diff로 투영한다.
+ *
+ * @param records seq 정렬 이력 레코드(전체 스트림 — old 파생 정확성을 위해 구간 밖 레코드도 포함해 전달).
+ * @param range fromSeq(비포함)·toSeq(포함, 생략=최신). D1: 투영기는 일반형, UI는 "과거↔현재"부터.
+ */
+export declare function projectSeqDiff(records: readonly FieldAuditRecord[], range: {
+    fromSeq: number;
+    toSeq?: number;
+}): SeqDiff;
+/** 캔버스 오버레이 마크 — 엔티티 노드 단위(removed 대상은 캔버스에 없어 패널 전용, D3). */
+export interface DiffMark {
+    verb: 'added' | 'modified';
+    /** 구간 내 추가/변경된 속성 행(하이라이트 대상). 삭제 속성은 행이 없어 제외. */
+    changedAttributeIds: Set<ModelId>;
+    /** 구간 내 추가/변경된 연산 행. */
+    changedOperationIds: Set<ModelId>;
+}
+/**
+ * SeqDiff → 캔버스 마크 맵. 엔티티 subject는 자기 verb로, 자식(속성/연산/인덱스) 변경은 부모 엔티티를
+ * modified로 승격(이미 added면 유지)한다. 연관/그룹은 S3 스코프 밖(엔티티 오버레이 전용).
+ */
+export declare function buildDiffMarks(diff: SeqDiff): Map<ModelId, DiffMark>;

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/stereotype.d.ts

@@ -0,0 +1,2 @@
+import { ClassStereotype } from './types';
+export declare function stereotypeLabel(s: ClassStereotype): string;

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;