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

package/README.md

@@ -1,42 +1,47 @@
 # entity-modeler-next
 
-Vue 3 기반 비주얼 엔티티 모델링 / 클래스 다이어그램 에디터.
-레거시 GWT/Vaadin 7 모듈(`bluework-entitymodeler`)의 후속이며, `bluework4-tool`(Nuxt/Vue/Mongo)에 임베드된다.
+Vue 3 visual entity-modeling / class-diagram editor.
+Distributed as a library package (`@g1cloud/entity-modeler-next`) and embedded in `bluework4-tool` (Nuxt/Vue/Mongo).
 
-## 스택
+## Stack
 
-TypeScript · Vue 3 · **Vue Flow** · Pinia(비강제) · Vite(library mode) · Vitest · view는 `@g1cloud/open-bluesea-core`(BS) 컴포넌트 기반
+TypeScript · Vue 3 · **Vue Flow** · Pinia (opt-in) · Vite (library mode) · Vitest · views built on `@g1cloud/open-bluesea-core` (BS) components
 
-## 구조
+## Install
+
+```bash
+pnpm add @g1cloud/entity-modeler-next
+```
+
+Requires the peer dependencies `vue ^3.5.0` and `@g1cloud/open-bluesea-core` (installed by the host).
+
+## Usage
+
+```ts
+import { EntityModeler } from '@g1cloud/entity-modeler-next'
+import '@g1cloud/entity-modeler-next/style.css'  // required — components render unstyled without it
+```
+
+## Structure
 
 ```
 src/
-  core/      논리/레이아웃 타입(분리)·resolve(정합성)·routing·autolayout·propagation·validation·타입 카탈로그. 프레임워크 무관
-  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 라운드트립)
-  agent/     자연어→op 트랙 (symbolicOp·resolver·schema·buildAgentBatch)
-  dev/       데모 하니스 (라이브러리 빌드에서 제외)
+  core/      logical/layout types (separated) · resolve (consistency) · routing · autolayout · propagation · validation · type catalogs. Framework-agnostic
+  command/   Command (do/undo) · CommandStack · op/opSync (semantic op emit + CAS concurrency)
+  editor/    reactive controller (composable wrapping CommandStack, EDITOR inject key)
+  view/      Vue Flow components (DiagramCanvas · EntityNode · GroupNode · AssociationEdge · PropertyPanel · ValidationPanel, etc.)
+  adapter/   storage-schema mapping (persisted v1/v2 · fromPersisted/toPersisted/toPersistedV2 round-trip)
+  agent/     natural-language → op track (symbolicOp · resolver · schema · buildAgentBatch)
+  dev/       demo harness (excluded from the library build)
 ```
 
-핵심 설계: **레이아웃이 논리 모델을 `modelId`로 참조(단방향)**. 논리 모델엔 geo/waypoint/style이 없다.
-**현재 구조·상태·문서 인덱스의 정본은 루트 `CLAUDE.md`** (저장 스키마 영향은 `docs/M0-schema-impact.md`).
+Core design: **layout references the logical model by `modelId` (one-way)**. The logical model carries no geo/waypoint/style.
 
-## 스크립트
+## Scripts
 
 ```bash
-pnpm dev        # 스파이크/데모 dev 서버
-pnpm test       # Vitest (core 단위 테스트)
-pnpm typecheck  # vue-tsc
-pnpm build      # 라이브러리 빌드 (dist/)
+pnpm dev        # demo harness dev server (src/dev)
+pnpm test       # Vitest
+pnpm typecheck  # vue-tsc --noEmit
+pnpm build      # library 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/migrateLegacyMoney.d.ts

@@ -0,0 +1,8 @@
+import { LogicalModel } from './types';
+/**
+ * 논리 모델 내 전 레거시 Money 속성을 신규 Money embeddable로 승격한 **새 모델**을 반환(순수).
+ * 대상이 없으면 입력 참조를 그대로 반환(no-op). 레이아웃은 논리 modelId만 참조하고 dbAttr을 참조하지
+ * 않으므로 무변경 — 호출자(useMigrateEntityDiagram)는 `{ ...state, logical: migrateLegacyMoney(state.logical) }`.
+ * amount 슬롯이 레거시 컬럼 modelId를 보존하므로 인덱스(IndexColumn.columnRef) 참조도 안전.
+ */
+export declare function migrateLegacyMoney(logical: LogicalModel): LogicalModel;

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[];