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

package/README.md

@@ -1,7 +1,7 @@
 # entity-modeler-next
 
 Vue 3 기반 비주얼 엔티티 모델링 / 클래스 다이어그램 에디터.
-레거시 GWT/Vaadin 7 모듈(`bluework-entitymodeler`)의 후속이며, `bluework4-tool`(Nuxt/Vue/Mongo)에 임베드된다.
+라이브러리 패키지(`@g1cloud/entity-modeler-next`)로 배포되며, `bluework4-tool`(Nuxt/Vue/Mongo)에 임베드된다.
 
 ## 스택
 
@@ -15,7 +15,7 @@ src/
   command/   Command(do/undo)·CommandStack·op/opSync(시맨틱 op emit + CAS 동시성)
   editor/    reactive controller (CommandStack 래핑 컴포저블, EDITOR inject 키)
   view/      Vue Flow 컴포넌트 (DiagramCanvas·EntityNode·GroupNode·AssociationEdge·PropertyPanel·ValidationPanel 등)
-  adapter/   레거시 PDiagram 매핑 (persisted v1/v2·fromPersisted/toPersisted/toPersistedV2 라운드트립)
+  adapter/   저장 스키마 매핑 (persisted v1/v2·fromPersisted/toPersisted/toPersistedV2 라운드트립)
   agent/     자연어→op 트랙 (symbolicOp·resolver·schema·buildAgentBatch)
   dev/       데모 하니스 (라이브러리 빌드에서 제외)
 ```
@@ -26,17 +26,8 @@ src/
 ## 스크립트
 
 ```bash
-pnpm dev        # 스파이크/데모 dev 서버
-pnpm test       # Vitest (core 단위 테스트)
-pnpm typecheck  # vue-tsc
+pnpm dev        # 데모 하니스 dev 서버 (src/dev)
+pnpm test       # Vitest
+pnpm typecheck  # vue-tsc --noEmit
 pnpm build      # 라이브러리 빌드 (dist/)
 ```
-
-## M0 스파이크 검증 포인트 (브라우저)
-
-`pnpm dev` 후 다음을 확인:
-- 엔티티 노드가 속성 행·PK 마커와 함께 렌더되는가
-- 관계선이 **직각 라우팅**으로 그려지는가
-- 파란 **waypoint**를 드래그하면 경로가 갱신되는가
-- 세그먼트 중점(회색 원)을 **더블클릭**하면 waypoint가 추가되는가
-- 관계선 끝이 특정 **컬럼 행(앵커)**에 붙는가 (Order.id ↔ OrderLine.orderId)

package/dist/agent/resolver.d.ts

@@ -35,6 +35,75 @@ export type ResolveError = {
     code: 'self-identifying';
     opIndex: number;
     handle: AssocHandle;
+}
+/** `type:'GroupCodeEnum'` 인데 `groupCode` 미동반 — groupCode 바인딩 없는 깨진 파생 타입 방지(B3). */
+ | {
+    code: 'groupcode-required';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+}
+/** index.add 컬럼 핸들이 엔티티 내 dbAttr와 0개 매칭. */
+ | {
+    code: 'column-not-found';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+}
+/** index.add 컬럼 핸들이 복수 dbAttr와 매칭(예: 속성명 지정인데 다중 컬럼 임베드/Money). */
+ | {
+    code: 'column-ambiguous';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    matches: ModelId[];
+}
+/** index.update/remove 핸들이 엔티티 내 인덱스와 0개/복수 매칭. */
+ | {
+    code: 'index-not-found';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+} | {
+    code: 'index-ambiguous';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    matches: ModelId[];
+}
+/** operation.update/remove 핸들이 엔티티 내 operation과 0개/복수 매칭. */
+ | {
+    code: 'operation-not-found';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+} | {
+    code: 'operation-ambiguous';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+    matches: ModelId[];
+}
+/**
+ * index.update patch에 `columns` 키 — columnRef(dbAttr modelId)는 사람 핸들로 표현 불가라 패스스루 시
+ * 깨진 인덱스가 된다. 컬럼 변경은 index.remove + index.add(컬럼 핸들 해소 구현)로 유도(거부 권고안).
+ */
+ | {
+    code: 'index-columns-patch-unsupported';
+    opIndex: number;
+    entity: Handle;
+    handle: Handle;
+}
+/**
+ * 같은 배치에서 `entity.add`로 추가되는 엔티티를 자식/관계 op가 핸들로 참조(A 백스톱 가드).
+ * mongo arrayFilter는 update 선이미지에 평가되므로 갓 push된 엔티티에 닿는 child push가 silent no-op이 된다.
+ * 신규 엔티티의 자식은 `attribute.add`/`index.add`/`operation.add` 분리가 아니라 `entity.add` spec에 inline fold할 것
+ * (관계는 inline 불가 → 엔티티 배치 확정 후 별도 배치). entity-not-found 대신 의도를 드러내는 명시 에러.
+ */
+ | {
+    code: 'pending-entity-ref';
+    opIndex: number;
+    handle: Handle;
 };
 export type ResolveResult = {
     ok: true;

package/dist/agent/symbolicOp.d.ts

@@ -1,4 +1,4 @@
-import { ClassStereotype, Multiplicity } from '../core/types';
+import { ClassStereotype, MultiLangText, Multiplicity, OperationVisibility } from '../core/types';
 /**
  * 요소 지정 핸들 — modelId 대신 이름/물리명.
  * 엔티티: 물리명(`table.physicalName`) 우선, 논리명(`name`) 보조 — 논리명은 모델 내 중복 허용(CHK-NAME-3)이라 모호 가능.
@@ -19,18 +19,36 @@ export interface AssocHandle {
     from: Handle;
     to: Handle;
 }
-/** entity.add 페이로드 — resolver가 modelId 발급 + 빈 골격 조립. */
+/**
+ * entity.add 페이로드 — resolver가 modelId 발급 + 골격 조립.
+ *
+ * **inline fold**: 신규 엔티티의 자식(속성·인덱스·operation)은 별도 `attribute.add` 등으로 보내지 않고
+ * 여기에 inline 배열로 담는다. resolver가 완성형 엔티티를 한 `entity.add`로 조립해 단일 `$push`로 들어간다.
+ * (별도 child op는 mongo arrayFilter 선이미지 한계로 *같은 배치 신규 엔티티*에 닿지 못해 silent no-op이 된다 —
+ *  그래서 신규 엔티티 자식은 op 분리가 아니라 inline이 정공법. 분리 emit은 resolver가 `pending-entity-ref`로 거부.)
+ * `attribute.add`/`index.add`/`operation.add` op은 *기존* 엔티티에 자식을 추가하는 용도로 남는다.
+ */
 export interface EntitySpec {
     name: string;
     /** 기본 'JPA_ENTITY'. */
     stereotype?: ClassStereotype;
     /** 설정 시 `table.physicalName`. */
     physicalName?: string;
+    /** inline 속성 — 배열 순서가 곧 `order`. GroupCodeEnum+groupCode 규칙은 `attribute.add`와 동일하게 강제. */
+    attributes?: AttrSpec[];
+    /** inline 인덱스 — 컬럼 핸들은 *이 엔티티가 inline으로 만드는* dbAttr 내에서 해소된다(속성 inline 동반 전제). */
+    indexes?: IndexSpec[];
+    /** inline 도메인 메서드 — 배열 순서가 곧 `order`. */
+    operations?: OperationSpec[];
 }
 /** attribute.add 페이로드 — resolver가 modelId 발급 + dbAttr 골격 조립. */
 export interface AttrSpec {
     name: string;
-    /** Java 타입(예: 'Long', 'String'). */
+    /**
+     * Java 타입(예: 'Long', 'String'). 카탈로그 저장값.
+     * `'GroupCodeEnum'`은 파생 타입이라 **`groupCode` 동반 필수** — 없으면 resolver가 거부(groupCode 바인딩
+     * 없는 깨진 파생 타입 방지). groupCode 지정 시 코드성 속성으로 해소된다.
+     */
     type: string;
     identifier?: boolean;
     notNull?: boolean;
@@ -42,6 +60,26 @@ export interface AttrSpec {
     length?: number;
     /** dbAttr 소수 자릿수(DECIMAL/NUMERIC scale). length 동반이 일반적. 0/미설정은 미지정. */
     scale?: number;
+    /**
+     * 코드성 속성의 group code 바인딩(레거시 AttributeModel.groupCode). `type:'GroupCodeEnum'`이면 필수.
+     * 모델→모델 복사·코드 동기화에서 GroupCodeEnum 속성을 온전히 재현하는 핵심 필드(없으면 깨진 파생 타입).
+     */
+    groupCode?: string;
+    /** 속성 기본값(레거시 AttributeModel.defaultValue, 문자열 패스스루). */
+    defaultValue?: string;
+    /** 속성 분류 그룹(레거시 attributeGroup, 예: 'code'·'amt'). 표시·분류 전용 패스스루. */
+    attributeGroup?: string;
+    /** 속성 설명(다국어, 레거시 AttributeModel.description). */
+    description?: MultiLangText;
+    /**
+     * dbAttr 컬럼 논리명(다국어, 예: {ko:'체크아웃유형'}). 한글 업무명이 모델→모델 복사에서 보존되는 위치 —
+     * 속성 자체는 단일 식별자 `name`만 갖고, 다국어 업무명은 컬럼에 붙는다. 컬럼 생성 시에만 의미.
+     */
+    columnLogicalName?: MultiLangText;
+    /** dbAttr UNIQUE 제약. */
+    unique?: boolean;
+    /** dbAttr 갱신 가능 여부(JPA @Column(updatable=)). */
+    updatable?: boolean;
 }
 /** association.add 페이로드 — from/to 엔티티는 resolver가 해소, modelId 발급 + end 조립. */
 export interface AssocSpec {
@@ -58,6 +96,66 @@ export interface AssocSpec {
     /** end2 composition(부모가 자식 생명주기 소유). */
     composition?: boolean;
 }
+/**
+ * group.add 페이로드 — 엔티티 멤버를 묶는 논리 그룹(레거시 LogicalGroup). resolver가 modelId 발급 +
+ * 멤버 핸들을 entity modelId(`memberEntityRefs`)로 해소. 그룹 멤버십은 값 포함이 아닌 **id 참조**(엔티티는
+ * 그룹과 독립 존재). 멤버는 *기존* 엔티티여야 한다 — 같은 배치 신규 엔티티(entity.add)는 닿지 못하므로
+ * (top-level 그룹은 inline fold 불가) resolver가 `pending-entity-ref`로 거부, 엔티티 배치 확정 후 별도 배치로.
+ * 그룹 박스 좌표(groupLayout)는 호스트가 멤버 엔티티 레이아웃을 감싸 incidental로 첨부(C1 동형).
+ */
+export interface GroupSpec {
+    /** 그룹 논리명(다국어, 예: {ko:'주문'}). 패키지 기반 그룹이면 보통 패키지 leaf의 업무명. */
+    name?: MultiLangText;
+    /** 자바 패키지명 등 그룹의 물리 식별(레거시 LogicalGroup.packageName). */
+    packageName?: string;
+    /** 그룹 설명(자유 텍스트 — 모듈/도메인 경계 의도 메모). */
+    description?: string;
+    /** DDL 생성 제외 여부(기본 false). */
+    excludeDDLGeneration?: boolean;
+    /** 멤버 엔티티 핸들(물리명 우선/논리명 보조). resolver가 entity modelId로 해소. */
+    members: Handle[];
+}
+/**
+ * index.add 컬럼 지정 — 인덱스 컬럼은 dbAttr(컬럼) modelId(`IndexColumn.columnRef`)를 참조하나,
+ * 핸들은 사람이 지정 가능한 물리명/속성명이다. resolver가 소속 엔티티 내에서 dbAttr modelId로 해소한다.
+ */
+export interface IndexColumnSpec {
+    /**
+     * 컬럼 핸들 — 컬럼 물리명(`dbAttrs[].physicalName`) 우선, 속성명(`name`) 보조.
+     * 속성명으로 지정 시 그 속성이 단일 컬럼이어야 한다(다중 dbAttr=임베드/Money는 모호 → resolver 거부).
+     */
+    column: Handle;
+    /** 내림차순 정렬 컬럼(기본 false=오름차순). */
+    descending?: boolean;
+}
+/** index.add 페이로드 — resolver가 modelId 발급 + 컬럼 핸들을 dbAttr modelId로 해소. */
+export interface IndexSpec {
+    name: string;
+    /** UNIQUE 인덱스 여부(기본 false). */
+    unique?: boolean;
+    /** 인덱스 컬럼(순서 의미 있음). 비어 있으면 컬럼 없는 인덱스(허용 — 값 품질은 검증 엔진). */
+    columns: IndexColumnSpec[];
+    /** 인덱스 설명(레거시 IndexModel.description, 평문). */
+    description?: string;
+    /** 인덱스 파라미터(레거시 IndexModel.parameters, 패스스루). */
+    parameters?: string;
+}
+/**
+ * operation.add 페이로드 — 도메인 메서드(레거시 OperationModel). resolver가 modelId 발급 + order 누적.
+ * 파라미터·반환 타입은 별도 모델 필드가 아니라 `sourceCode`(Java 메서드 본문 텍스트)에 담긴다.
+ * legacyRaw(소스 엔티티 parent back-ref·properties)는 복사 시 stale이 되므로 op로 다루지 않는다.
+ */
+export interface OperationSpec {
+    name: string;
+    /** 가시성(기본 미설정 → 호스트/렌더 기본). */
+    visibility?: OperationVisibility;
+    /** Java 메서드 본문(멀티라인, 파라미터·반환 시그니처 포함). */
+    sourceCode?: string;
+    /** 메서드 설명(다국어). 레거시 직렬화는 평문이라 어댑터가 평문↔{ko} 변환(types.ts Operation 주석). */
+    description?: MultiLangText;
+    /** 개인정보 속성 유형(레거시 personalInfoAttributeType 패스스루). */
+    personalInfoAttributeType?: string;
+}
 /**
  * LLM이 산출하는 단일 심볼릭 op. `kind`는 op.ts 어휘와 1:1(로케이터만 심볼릭).
  * `patch`는 OpShape.patch와 동형(부분 patch, 그대로 전달 — 값 품질은 검증 엔진이 사후 경고).
@@ -100,10 +198,39 @@ export type SymbolicOp = {
     association: AssocHandle;
     end: 'from' | 'to';
     patch: Record<string, unknown>;
+} | {
+    kind: 'index.add';
+    entity: Handle;
+    spec: IndexSpec;
+} | {
+    kind: 'index.update';
+    entity: Handle;
+    index: Handle;
+    patch: Record<string, unknown>;
+} | {
+    kind: 'index.remove';
+    entity: Handle;
+    index: Handle;
+} | {
+    kind: 'operation.add';
+    entity: Handle;
+    spec: OperationSpec;
+} | {
+    kind: 'operation.update';
+    entity: Handle;
+    operation: Handle;
+    patch: Record<string, unknown>;
+} | {
+    kind: 'operation.remove';
+    entity: Handle;
+    operation: Handle;
+} | {
+    kind: 'group.add';
+    spec: GroupSpec;
 };
 /**
  * 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"];
+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 type SymbolicOpKind = (typeof SYMBOLIC_OP_KINDS)[number];

package/dist/command/commands.d.ts

@@ -40,6 +40,8 @@ export declare function resizeGroup(groupId: ModelId, size: {
     width: number;
     height: number;
 }): Command;
+/** 그룹 색상 변경 (레이아웃만 변경 — setEntitySwatch와 동형) */
+export declare function setGroupSwatch(groupId: ModelId, token: string | null): Command;
 export declare function addAttribute(entityId: ModelId, attribute: Attribute): Command;
 /** 속성 필드 부분 수정 (name·type·dataType·dbAttrs·identifier·notNull 등). 얕은 patch. */
 export declare function updateAttribute(entityId: ModelId, attributeId: ModelId, patch: Partial<Attribute>): Command;
@@ -89,6 +91,8 @@ export declare function resizeNote(noteId: ModelId, size: {
     height: number;
 }): Command;
 export declare function setNoteMemo(noteId: ModelId, memo: string): Command;
+/** 노트 색상 변경 (레이아웃만 변경 — setEntitySwatch와 동형) */
+export declare function setNoteSwatch(noteId: ModelId, token: string | null): Command;
 /**
  * 노트를 그룹 박스 멤버로 편입(레이아웃 GroupLayout.memberNoteRefs). 이미 멤버면 no-op.
  * addEntityToGroup과 거울이나 대상이 논리(memberEntityRefs)가 아닌 레이아웃이다 — 노트가 순수

package/dist/core/autolayout.d.ts

@@ -10,3 +10,48 @@ export declare function computeAutoLayout(logical: LogicalModel, layout: Diagram
     id: ModelId;
     location: Point;
 }[];
+/**
+ * 높이 인지(height-aware) 박스 패킹 — 신규 엔티티 다수를 겹침 없이 격자 배치 (순수 함수, 엔진 무관).
+ *
+ * `computeAutoLayout`(고정 셀 격자)는 모든 엔티티가 같은 높이라는 가정이라, 속성 수가 많은 박스가
+ * 아랫줄을 침범한다. 이 함수는 박스마다 **속성 수에 비례한 높이를 추정**하고, 열별로 누적 Y(`colBottom`)를
+ * 추적해 다음 박스를 그 아래에 둔다 → 어떤 박스 높이 분포에서도 겹침이 구조적으로 발생하지 않는다.
+ *
+ * 배치 순서(좌→우, 위→아래 라운드로빈)는 입력 순서를 보존한다. 높이 추정은 의도적으로 넉넉히
+ * (간격이 뜨는 건 무해하나 겹침은 깨져 보임) — EntityNode가 `min-height: min-content`로 콘텐츠 구동이라
+ * 픽셀 정확이 아닌 선형 추정으로 충분하다.
+ *
+ * 좌표는 절대좌표. 기존 레이아웃 하단 아래에서 시작하려면 `baseY`를 넘긴다(호출자가 계산).
+ */
+export interface EntityBoxSpec {
+    id: ModelId;
+    /** 엔티티의 속성(attribute) 개수 — 높이 추정 입력. */
+    attributeCount: number;
+}
+export interface PackedEntityBox {
+    id: ModelId;
+    location: Point;
+    size: {
+        width: number;
+        height: number;
+    };
+}
+export interface PackBoxesOptions {
+    cols: number;
+    boxWidth: number;
+    /** 박스 간(가로·세로) 여백. */
+    gap: number;
+    baseX: number;
+    baseY: number;
+    /** 헤더(스테레오타입+이름) 추정 높이. */
+    headerHeight: number;
+    /** 속성 1행 추정 높이. */
+    rowHeight: number;
+    /** 헤더·행 외 하단 여유(연산/인덱스 섹션 등) 추정 높이. */
+    footerHeight: number;
+    /** 박스 최소 높이(속성 0개여도 이 높이는 확보). */
+    minHeight: number;
+}
+/** 속성 수 → 박스 추정 높이 (넉넉히 over-reserve). */
+export declare function estimateEntityHeight(attributeCount: number, opts?: Partial<PackBoxesOptions>): number;
+export declare function packEntityBoxes(boxes: EntityBoxSpec[], options?: Partial<PackBoxesOptions>): PackedEntityBox[];

package/dist/core/projectActionLog.d.ts

@@ -0,0 +1,41 @@
+import { ModelId } from './types';
+import { FieldAuditRecord } from './projectFieldAudit';
+import { EntityAuditSubjectKind } from './projectEntityAudit';
+export type ActionSubjectKind = EntityAuditSubjectKind | 'association' | 'associationEnd' | 'group';
+/** 무엇이 바뀐 대상인가. entityRef는 자식(속성/연산/인덱스) subject의 부모(이름 조회·복원 스코프). */
+export interface ActionSubject {
+    kind: ActionSubjectKind;
+    ref: ModelId;
+    entityRef?: ModelId;
+    end?: 'end1' | 'end2';
+}
+/** 한 대상의 한 필드 변경(old→new / tombstone). */
+export interface ActionFieldChange {
+    field: string;
+    value: unknown;
+    oldValue?: unknown;
+    removed?: boolean;
+}
+/** 한 seq에서 한 대상에 일어난 액션 — verb + 변경 필드들(born=추가 요약, update=필드별). */
+export interface SubjectAction {
+    subject: ActionSubject;
+    verb: 'add' | 'update' | 'remove';
+    fields: ActionFieldChange[];
+}
+/** 한 seq(= 한 op 배치 = 한 사용자 액션) 그룹. */
+export interface ActionGroup {
+    seq: number;
+    ts?: string | number | Date;
+    origin?: string;
+    author?: string;
+    kind?: 'edit' | 'restore';
+    restoredFromSeq?: number;
+    actions: SubjectAction[];
+}
+/**
+ * op 이력 스트림을 seq(액션) 단위 그룹으로 투영한다(diagram-wide).
+ *
+ * @param records seq 정렬 이력 레코드.
+ * @returns seq **내림차순**(최신 먼저) 액션 그룹. 각 그룹은 subject별 액션(verb+필드)으로 구성.
+ */
+export declare function projectActionLog(records: readonly FieldAuditRecord[]): ActionGroup[];

package/dist/core/projectEntityAudit.d.ts

@@ -0,0 +1,22 @@
+import { ModelId } from './types';
+import { FieldAuditRecord, FieldAuditEntry } from './projectFieldAudit';
+/** 감사 대상 종류 — 엔티티 자신 또는 자식 컬렉션. */
+export type EntityAuditSubjectKind = 'entity' | 'attribute' | 'operation' | 'index';
+/** 무엇이 바뀐 대상인가 — 피드에서 필드 값과 함께 표시. */
+export interface EntityAuditSubject {
+    kind: EntityAuditSubjectKind;
+    /** 대상 ref. kind='entity'면 엔티티 자신(entityRef와 동일). */
+    ref: ModelId;
+}
+/** 엔티티 감사 피드 한 엔트리 — projectFieldAudit 엔트리 + 어느 대상인지(subject). */
+export interface EntityAuditEntry extends FieldAuditEntry {
+    subject: EntityAuditSubject;
+}
+/**
+ * 한 엔티티의 감사 피드(엔티티 자신 + 모든 자식 속성/연산/인덱스의 필드 변경)를 seq 순으로 반환한다.
+ *
+ * @param records seq 정렬 이력 레코드(projectFieldAudit와 동일 입력). 필요 시 방어적 재정렬은 하위가 수행.
+ * @param entityRef 대상 엔티티.
+ * @returns seq 오름차순 병합 피드(각 엔트리에 subject 태그). 동일 seq는 원 삽입 순서 유지(안정 정렬).
+ */
+export declare function projectEntityAudit(records: readonly FieldAuditRecord[], entityRef: ModelId): EntityAuditEntry[];

package/dist/core/projectFieldAudit.d.ts

@@ -0,0 +1,65 @@
+import { ModelId } from './types';
+import { OpShape } from '../command/op';
+/**
+ * 투영기 입력 — 이력 레코드의 lib-로컬 최소 형태(호스트 `OpHistoryRecord`의 부분집합).
+ * 호스트가 `{diagramId, seq}` 정렬로 조회해 넘긴다. lib는 호스트 타입에 의존하지 않으려 여기서 재선언한다.
+ */
+export interface FieldAuditRecord {
+    /** diagram 내 단조 증가 좌표 — 타임라인 정렬 키(갭 허용, 연속성 가정 금지 §5.4). */
+    seq: number;
+    /** 서버 시각(감사 표시용 패스스루). */
+    ts?: string | number | Date;
+    /** op 출처(gui/agent/rest). 감사 "누가"의 현 해상도(경로 수준, §4 결정 2). */
+    origin?: string;
+    /**
+     * 개별 사용자 식별자(감사 "누가"의 per-user 해상도, §4 결정 2-(나)).
+     * 슬라이스 1/3c 레코드에는 없음(forward-only) — 있으면 그대로 타임라인에 패스스루한다(author-aware).
+     */
+    author?: string;
+    /** 편집 vs 복원 축(감사 표시). */
+    kind?: 'edit' | 'restore';
+    /** kind='restore'일 때 복원 대상 seq(패스스루). */
+    restoredFromSeq?: number;
+    /** ★필드 변경의 원천. edit=배치 그대로 / restore=합성 diff. */
+    ops: OpShape[];
+}
+/**
+ * 감사 대상 로케이터. 설정된 ref로 대상 종류(엔티티/속성/연산/인덱스/연관/연관end/그룹)가 결정된다.
+ * `field`를 주면 그 필드 단일 타임라인, 생략하면 대상의 모든 변경 필드.
+ */
+export interface FieldAuditTarget {
+    entityRef?: ModelId;
+    attributeRef?: ModelId;
+    operationRef?: ModelId;
+    indexRef?: ModelId;
+    associationRef?: ModelId;
+    groupRef?: ModelId;
+    end?: 'end1' | 'end2';
+    /** 단일 필드로 좁힘(생략 시 전 필드). */
+    field?: string;
+}
+/** 타임라인 한 엔트리 — 한 필드가 한 seq에서 얻은 값(또는 tombstone). */
+export interface FieldAuditEntry {
+    seq: number;
+    ts?: string | number | Date;
+    origin?: string;
+    author?: string;
+    kind?: 'edit' | 'restore';
+    restoredFromSeq?: number;
+    /** 바뀐 필드명. 멤버십은 'memberEntityRefs'. */
+    field: string;
+    /** 신규 값. null=필드 비움(clear). removed=true면 undefined. */
+    value: unknown;
+    /** 직전 엔트리에서 파생한 이전 값(§3.3-(가)). 최초 born·재-add는 없음. */
+    oldValue?: unknown;
+    /** 대상/필드가 이 seq에 소멸(remove/entity.remove/group.removeMember). */
+    removed?: boolean;
+}
+/**
+ * op 이력 스트림을 특정 대상의 per-field 변경 타임라인으로 투영한다(순수).
+ *
+ * @param records seq 오름차순 이력 레코드(방어적으로 seq 재정렬). 각 `ops`가 필드 변경 원천.
+ * @param target 대상 로케이터(+ 선택적 field 필터).
+ * @returns seq 순 필드 감사 엔트리 배열(edit·restore 혼합, born·update·tombstone·멤버십).
+ */
+export declare function projectFieldAudit(records: readonly FieldAuditRecord[], target: FieldAuditTarget): FieldAuditEntry[];

package/dist/core/synthesizeRestoreOps.d.ts

@@ -0,0 +1,21 @@
+import { DiagramLayout, LogicalModel } from './types';
+import { OpShape } from '../command/op';
+/** 합성기 입력 — 정합한 완전 상태(logical + layout). 호스트는 v2 doc 서브트리를 그대로 넘긴다(rev/version은 무시). */
+export interface DiagramSnapshotState {
+    logical: LogicalModel;
+    layout: DiagramLayout;
+}
+/**
+ * null≡undefined≡absent 정규화 deep-equal. 스칼라/배열(인덱스별)/객체(키 합집합)를 재귀 비교한다.
+ * (mongo가 optional 필드 clear를 null로 저장하는 것과 target의 absent를 동치로 본다.)
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * current → target 복원 diff를 forward op으로 합성한다(순수, 감사 전용 — 실행 안 됨).
+ *
+ * 산출 순서(결정성): logical(entities → associations → groups; 각 remove → add → update/child) →
+ * layout(entityLayouts → associationLayouts → groupLayouts → notes). 각 컬렉션은 key 정렬.
+ *
+ * @returns OpShape[] — CAS 메타(rev 숫자·layout.version) 없는 어휘 형태(호스트 이력 레코드 `ops`에 그대로 기록).
+ */
+export declare function synthesizeRestoreOps(current: DiagramSnapshotState, target: DiagramSnapshotState): OpShape[];

package/dist/editor/controller.d.ts

@@ -3,6 +3,7 @@ import { EditorState } from '../command/types';
 import { DiagramMeta } from '../adapter/diagramAdapter';
 import { OpConflict } from '../command/op';
 import { OpSyncTransport } from '../command/opSync';
+import { FieldAuditRecord } from '../core/projectFieldAudit';
 import { ResolvedDiagram } from '../core/resolve';
 import { RoutingMode } from '../core/routing';
 import { ValidationIssue } from '../core/validation';
@@ -36,6 +37,22 @@ export type Selection = {
     ids: ModelId[];
     anchor: ModelId;
 } | null;
+/**
+ * (나) 필드 감사 조회 transport — 호스트가 주입하는 이력 조회 함수. diagram의 op 이력 스트림을
+ * seq 순 `FieldAuditRecord[]`로 반환한다. `sinceSeq`를 주면 그 이후만(증분 fetch, 기본 전량).
+ * op emit의 `OpSyncTransport`와 대칭 — 쓰기는 op 배치, 읽기는 감사 레코드.
+ */
+export type HistoryTransport = (sinceSeq?: number) => Promise<FieldAuditRecord[]>;
+/** 복원 결과 — 호스트 restore 라우트 응답의 lib-로컬 최소 형태(ok + 실패 사유). */
+export interface RestoreOutcome {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * 시점 복원 transport — 호스트가 주입하는 복원 함수(`restoreEntityDiagram` 라우트). toSeq 시점 상태로
+ * forward 보상 쓰기(diagram-wide). 성공 시 라이브 doc이 바뀌므로 controller가 reloadRequest로 재적재를 요청한다.
+ */
+export type RestoreTransport = (toSeq: number) => Promise<RestoreOutcome>;
 export interface EditorController {
     state: EditorState;
     resolved: ComputedRef<ResolvedDiagram>;
@@ -57,6 +74,8 @@ export interface EditorController {
     canUndo: Ref<boolean>;
     canRedo: Ref<boolean>;
     dirty: Ref<boolean>;
+    /** 모델 변경 신호 — 명령 적용마다 단조 증가. 외부 관찰자(감사 패널 등)가 재조회 트리거로 watch(디바운스 권장). */
+    revision: Ref<number>;
     /**
      * 편집 가능 여부 — false(조회 모드)면 모든 모델 변경(추가·삭제·이동·편집·재정렬·연결·붙여넣기·
      * undo/redo·저장)이 차단된다. 선택·팬/줌·hover 강조·복사·export 같은 읽기성 동작은 유지.
@@ -87,6 +106,28 @@ export interface EditorController {
      * `loadDiagram`으로 재적재하면 해소된다(B-5). op-mode가 아니면 항상 null.
      */
     opConflict: Ref<OpConflict | null>;
+    /**
+     * (나) 필드 감사 조회 transport — 호스트가 이력 조회 라우트(`entityDiagramHistory.get`) fetch 래퍼를
+     * 주입(opTransport 미러). 감사 패널이 호출해 이력 레코드를 얻고 `projectEntityAudit`로 투영한다.
+     * 미주입(dev/test·비-op doc) 시 undefined → 감사 패널 비활성.
+     */
+    historyTransport?: HistoryTransport;
+    /** 감사 패널 사용 가능 여부 — op-mode + historyTransport 주입 양쪽 충족. */
+    historyAvailable: ComputedRef<boolean>;
+    /** 시점 복원 transport(호스트 주입) — 감사 패널 '이 시점으로 복원'이 호출. */
+    restoreTransport?: RestoreTransport;
+    /** 복원 사용 가능 여부 — op-mode + editable + restoreTransport 주입(조회 모드·비-op은 불가). */
+    restoreAvailable: ComputedRef<boolean>;
+    /**
+     * 특정 seq 시점으로 복원 요청 — restoreTransport 위임. 성공(ok) 시 reloadRequest를 올려 호스트 재적재를 유도한다.
+     * transport 미주입/실패 시 { ok:false } 반환(패널이 사유 표시). editable=false면 no-op({ ok:false }).
+     */
+    restoreToSeq(toSeq: number): Promise<RestoreOutcome>;
+    /**
+     * 재적재 요청 신호(단조 증가) — 복원처럼 라이브 doc이 서버에서 바뀐 뒤, 호스트가 이 값을 watch해
+     * 최신 doc을 refetch → loadDiagram으로 갈아끼운다(focusRequest nonce와 같은 신호 패턴).
+     */
+    reloadRequest: Ref<number>;
     /**
      * 프리즈 후(또는 외부 변경 감지 시) 재적재 경로 — 호스트가 `fromPersisted`로 파싱한 state/meta를 주입한다
      * (생성자와 대칭 시그니처). state를 in-place 교체하고 스택을 리셋하며, 마커(schemaVersion/opWriteEnabled/
@@ -183,6 +224,8 @@ export interface EditorController {
     }): void;
     /** 그룹 필드 부분 수정 (name·description·packageName·excludeDDLGeneration) */
     updateGroup(groupId: ModelId, patch: Partial<LogicalGroup>): void;
+    /** 그룹 박스 색상 토큰 지정 (null이면 해제 → 기본 그룹 배경) */
+    setGroupSwatch(groupId: ModelId, token: string | null): void;
     /** 선택 엔티티들로 새 그룹 생성 (멤버 bbox에 박스 배치) */
     createGroup(entityIds: ModelId[], name?: string): ModelId | null;
     /** 빈 그룹 박스 생성 (이후 드래그로 엔티티 편입) */
@@ -326,6 +369,8 @@ export interface EditorController {
         height: number;
     }): void;
     setNoteMemo(noteId: ModelId, memo: string): void;
+    /** 노트 색상 토큰 지정 (null이면 해제 → 기본 노트 배경) */
+    setNoteSwatch(noteId: ModelId, token: string | null): void;
     /** 노트 → 대상(엔티티) 연결선 추가/삭제 + 꺾은점 편집 */
     addNoteConnection(noteId: ModelId, targetRef: ModelId): void;
     removeNoteConnection(noteId: ModelId, targetRef: ModelId): void;
@@ -358,6 +403,13 @@ export declare function createEditorController(initial?: EditorState, options?:
      * 어댑터가 활성(미주입 = dev/test → 어댑터 비활성, full-replace 저장 경로 유지).
      */
     opTransport?: OpSyncTransport;
+    /**
+     * (나) 필드 감사 조회 transport(`entityDiagramHistory.get` fetch 래퍼). 주입 + op-mode 시에만 감사
+     * 패널 활성(미주입 = dev/test·비-op doc → 패널 비활성). opTransport(쓰기)와 대칭인 읽기 채널.
+     */
+    historyTransport?: HistoryTransport;
+    /** 시점 복원 transport(`restoreEntityDiagram` 라우트). 주입 + op-mode + editable 시 감사 패널 '복원' 활성. */
+    restoreTransport?: RestoreTransport;
     /**
      * 검증 컨텍스트 — 카탈로그/정책 의존 규칙을 깨우는 호스트 주입(미주입 시 해당 규칙 skip).
      * selectableDataTypes(CHK-TYPE-1)는 코어 상수(SELECTABLE_DATA_TYPES)라 dev/호스트가 즉시 주입 가능.