@g1cloud/entity-modeler-next 5.0.0-beta.35 → 5.0.0-beta.37

package/dist/command/op.d.ts

@@ -31,6 +31,25 @@ export interface OpShape {
      */
     incidental?: boolean;
 }
+/**
+ * update patch의 **clear 표기 정규화** — 값이 `undefined`인 키(= 그 필드를 부재로 되돌린다)를 `null`로 바꾼다.
+ *
+ * ★왜 필요한가: op은 JSON으로 호스트에 전송되는데 `JSON.stringify`가 **값이 undefined인 키를 통째로 드롭**한다.
+ * 그러면 그 키가 호스트 `$set`에 도달하지 못해 **로컬은 지웠는데 서버는 그대로**인 괴리가 남는다. 발동 경로는
+ * 둘 다 일상 편집이다 —
+ *   ① **undo**: 원래 비어 있던 필드를 채운 뒤 되돌리면 invert patch가 `{field: undefined}`가 된다
+ *      (`updateEntity` 등이 `old[k] = e[k]`로 캡처하므로 부재 필드는 undefined로 잡힌다).
+ *   ② **명시적 clear**: 컨트롤러가 `{legacyEmbedRaw: undefined}`·`{attributeRef: undefined}`·
+ *      임베드 단일 전환의 `{collectionType/collectionTable/orderColumn: undefined}`처럼 "비움"을 patch로 낸다.
+ *
+ * `null`은 wire를 통과하고 호스트가 `$set field: null`로 집행한다. 이 리포는 **null ≡ 부재** 규약을 이미
+ * 쓰고 있어(`synthesizeRestoreOps`의 `fieldPatch`가 같은 이유로 clear를 null로 표기 + `deepEqual`이 둘을 동치로
+ * 비교, FK 전파 `diffSyncedFields`도 저장 null을 undefined로 정규화해 비교) 저장값 null은 부재와 같게 읽힌다.
+ *
+ * ★**얕은 정규화만** 한다 — 중첩 객체(`jpaAttrs`·`jpa`·`dbAttrs`)는 호스트가 **통째로 `$set`**하므로 내부의
+ * undefined 키는 드롭돼도 결과가 "그 키 부재"라 의미가 그대로 보존된다. 최상위 키만 `$set` 경로로 1:1 매핑된다.
+ */
+export declare function toWirePatch(patch: object): Record<string, unknown>;
 /**
  * apply 이후 호출 계약(계약 1)의 산출 — memento가 채워진 상태에서 do/undo 양방향 op.
  * invert는 *역방향 forward op*(계약 2) — 같은 op의 역값이 아니라 역연산 op.
@@ -62,7 +81,22 @@ export interface PersistedOpBatch {
     /** 멱등 키 — 재시도 중복 적용 차단(호스트가 직전 결과 반환). */
     clientOpId: string;
 }
-/** 충돌 종류 — rev 불일치 / layout.version 불일치 / 대상 소실. */
+/**
+ * 하드 프리즈 사유 — **방출 주체가 kind마다 다르다**(선언과 실제를 맞춘 기록, 2026-08-15 실측).
+ *
+ * - `rev` — **호스트가 내는 유일한 kind**. CAS filter 불일치(`matchedCount:0`)를 전부 이걸로 접는다.
+ *   호스트는 rev 불일치와 layout.version 불일치를 구분하지 않으므로(단일 updateOne filter) 두 원인이
+ *   모두 여기로 들어온다. = "다른 곳에서 이미 변경됨".
+ * - `layout` — **현재 어떤 writer도 방출하지 않는다**(예약). 위 사유로 호스트가 `rev`로 접고, 클라도
+ *   합성하지 않는다. 소비처(배너·호스트 watch)는 `rev`와 같은 경로로 처리한다.
+ * - `missing` — **클라이언트 합성 전용 = op 전송 실패**(4xx/5xx/네트워크로 transport가 throw).
+ *   동시편집이 아니라 혼자 편집 중에도 발생하므로 "다른 사용자가 변경"으로 안내하면 오진이다
+ *   (`opConflictNotice`·호스트 watch가 이 kind로 분기해 손실 고지 후 재적재를 확인받는다).
+ *   ★이름이 "대상 소실"처럼 읽히지만 그 의미로 쓰인 적이 없다 — 호스트 op 어휘엔 대상 소실 응답이 없다.
+ *
+ * ⚠️ 새 kind를 늘리기 전에 **소비처 분기**(`opConflictNotice` + 호스트 `opConflict` watch)를 함께 넓힐 것.
+ * 넓히지 않으면 새 kind가 else 분기로 떨어져 조용히 다른 복구 경로를 탄다(CC-9의 무신호 실패 모드).
+ */
 export interface OpConflict {
     kind: 'rev' | 'layout' | 'missing';
     ref?: ModelId;

package/dist/command/opSync.d.ts

@@ -40,14 +40,24 @@ export interface OpSyncOptions {
     newClientOpId?: () => string;
     /** 충돌(또는 전송 실패)로 하드 프리즈 진입 시 — controller가 editable=false + reload UX 연동. */
     onFreeze?: (conflict: OpConflict) => void;
-    /** 전송 거부(네트워크 등) 통지 — 진단용(프리즈는 별도 onFreeze로). */
+    /**
+     * 전송 거부(네트워크 등) 통지 — 진단용(프리즈는 별도 onFreeze로).
+     * 재시도하는 경우 **시도마다** 발화한다(회복돼도 원인을 추적할 수 있어야 하므로).
+     */
     onError?: (err: unknown) => void;
+    /**
+     * 전송 실패 재시도 지연(ms) — 배열 길이가 곧 재시도 횟수. 기본 `[400, 1200]`(총 3회 시도).
+     * `[]`이면 재시도 없이 즉시 프리즈. 같은 배치를 **같은 `clientOpId`로** 재전송하므로 호스트
+     * 멱등 ring이 중복 적용을 흡수한다(응답만 유실된 경우 직전 결과를 그대로 돌려받는다).
+     */
+    retryDelaysMs?: number[];
 }
 export declare class OpSyncAdapter {
     private readonly opts;
     private readonly cache;
     private readonly newClientOpId;
     private readonly debounceMs;
+    private readonly retryDelaysMs;
     private readonly emissions;
     private open;
     private debounceHandle;

package/dist/core/fkDerived.d.ts

@@ -9,6 +9,22 @@ import { Association, Attribute, DbColumn, Entity } from './types';
  *  v1은 어댑터 `assocFromHydrated`(diagramAdapter.ts:350)가 하이드레이션 시 합성한다. 두 판정은 이
  *  데이터에서 100% 일치하므로 동작 차이는 없다.)
  * RELATION_REF(inverse nav, dbAttrs=0)는 물리 컬럼이 없어 제외.
+ *
+ * ── FK 판정 술어 인벤토리(리포 전역) ─────────────────────────────────────────
+ * 이 술어 말고도 "FK인가"를 묻는 자리가 몇 곳 더 있고, **의도적으로 다르다**. 새 판정을 추가하기 전에
+ * 아래 중 하나로 답할 수 있는지 먼저 확인할 것(중복이면 여기로 위임).
+ *
+ *  | 자리 | 술어 | 왜 다른가 |
+ *  |---|---|---|
+ *  | `isFkDerivedColumn`(여기) | RELATION* && dbAttrs>0 | 뷰 잠금·형상 해소. `findFkOwningAssociation`이 위임 |
+ *  | `attributeOrder.isPhysicalFk` | derivedFrom && dbAttrs>0 | 표시 순서 정렬. **강등 이후** 호출 전제라 `derivedFrom`이 기준(경계 강등된 컬럼은 제자리에 남아야 한다) |
+ *  | `mermaid.isForeignKey` | RELATION_OWN‖RELATION_REF‖derivedFrom | ER **FK 마커**는 nav(dbAttrs=0)까지 표시 대상이라 컬럼 보유를 안 본다 |
+ *  | `ddl.ts` FK 제약 방출 | derivedFrom 단독 | 부모 컬럼을 알아야 REFERENCES를 쓸 수 있어 링크가 필수 |
+ *  | `propagation` `currentFk` | derivedFrom 단독 | 판정이 아니라 reconcile diff의 **매칭 키** |
+ *
+ * 실 데이터에서 두 축(RELATION* / derivedFrom)은 100% 일치하므로(위 문단) 이 차이는 대체로 관측되지
+ * 않는다. 발산했던 유일한 경로는 mermaid 임포트가 관계 없는 RELATION_OWN을 만들던 것이고
+ * (`parseMermaid.wireForeignKeyColumns` 주석), 그건 발생원에서 닫았다.
  */
 export declare function isFkDerivedColumn(attr: Attribute): boolean;
 /**

package/dist/core/javaTypes.d.ts

@@ -17,6 +17,11 @@ export declare const DEFAULT_JAVA_TYPE = "String";
 export declare const JAVA_TYPES: readonly JavaTypeDef[];
 /** 저장값 → 표시 라벨. 미등록 값(임베더블 타입명·커스텀명·미지 값)은 그대로 반환(폴백). */
 export declare function javaTypeLabel(value: string): string;
+/**
+ * 물리 DB 타입 → 자바 타입 저장값. 매핑 없는 타입(미지 타입·구조 타입·JDBC 추상 타입)은 undefined —
+ * 호출자가 타입을 비워 "모른다"를 보존한다. 위 `JAVA_TYPE_BY_DATA_TYPE` 주석의 결정 근거 참조.
+ */
+export declare function javaTypeFromDataType(dataType: string | undefined): string | undefined;
 /**
  * ① 스칼라 자바 타입 셀렉트 후보(단일 출처). JAVA_TYPES에서 비후보(⑤·레거시 표시용)를 빼고
  * ④ CustomType은 "사용자정의" 안내 라벨로 노출. ②embeddable·③customtype은 애초에 JAVA_TYPES에 없음.

package/dist/core/propagation.d.ts

@@ -71,7 +71,7 @@ export declare function planChildReconcileWithCascade(futureLogical: LogicalMode
  * 관계가 소유한다 — 컬럼을 직접 지우는 게 아니라 관계를 삭제/변경해 제거해야 한다. 이 판별로
  * FK 속성의 직접 삭제를 차단(어포던스+가드)하고 사용자를 관계 삭제 경로로 유도한다.
  *
- * FK 컬럼 불변식(RELATION* + 물리 컬럼 보유, EntityNode.keyMarks와 동형)으로 먼저 게이트해, 관계의
+ * FK 컬럼 불변식(`isFkDerivedColumn` = RELATION* + 물리 컬럼 보유)으로 먼저 게이트해, 관계의
  * 부모측 end가 가리키는 PK(비-RELATION) 오탐을 배제한다. 그다음 두 신호로 소유 관계를 찾는다:
  *
  *  1순위 `derivedFrom.associationRef` — 전파가 심은 권위 신호. v2 네이티브 doc에 보존되고 어댑터

package/dist/editor/controller.d.ts

@@ -496,9 +496,11 @@ export declare function createEditorController(initial?: EditorState, options?:
     /** 시점 복원 transport(`restoreEntityDiagram` 라우트). 주입 + op-mode + editable 시 감사 패널 '복원' 활성. */
     restoreTransport?: RestoreTransport;
     /**
-     * op 전송 실패(4xx/5xx/네트워크로 transport가 throw) 통지 — 진단용(opt-in). 하드 프리즈는 별도로
-     * 발생하며(opConflict.kind='missing'), 이 콜백은 소실될 원 에러를 호스트가 로깅/리포팅하도록 넘긴다.
-     * 미주입이어도 어댑터가 콘솔에 남긴다(정상 rev/layout 충돌은 이 경로가 아님 — throw만).
+     * op 전송 실패(4xx/5xx/네트워크로 transport가 throw) 통지 — 진단용(opt-in). 이 콜백은 소실될 원
+     * 에러를 호스트가 로깅/리포팅하도록 넘긴다. 미주입이어도 어댑터가 콘솔에 남긴다(정상 rev 충돌은
+     * 이 경로가 아님 — throw만).
+     * ⚠️ **발화 ≠ 프리즈**: 어댑터가 제한 재시도하므로 회복되는 시도도 통지된다(시도마다 1회).
+     * 하드 프리즈는 재시도 소진 후에만 발생하며 `opConflict.kind='missing'`으로 별도 노출된다.
      */
     onOpError?: (err: unknown) => void;
     /**